# Getting Started URL: https://docs.nium.com/docs/getting-started This guide details how to get started with the Nium One platform, portal, and APIs. ## Step 1: Create a Nium Portal account ### Sign up for a Nium Portal account Sign up for a Nium Portal account at: If you already have a Nium account: ### Create your account Fill in the requested details and click **Sign up**. Nium Portal sign-up screen ### Verify your email Open the verification email from Nium with the subject line **Welcome to Nium Portal!** and click **Confirm my account**. Verify Email Nium sends the verification email to the address you provided during sign up. If you don't see it, check your spam folder. ### Sign in to Nium Portal After verification, you’re redirected to the [Nium Portal sign in page](https://app.nium.com). Enter your Nium email. Then verify you are human by selecting the checkbox and completing the CAPTCHA, if prompted. Nium Portal sign-in screen Multi-factor authentication For security purposes, when you log in for the first time, Nium Portal prompts you to add another level of authentication to your account. Multi-factor authentication setup screen Nium supports two methods of multi-factor authentication: - Push notification via [Auth0's Guardian](https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian) app. - Push notification via Google Authenticator, Microsoft Authenticator, Okta, or any other third-party authentication service. Choose a method and follow the onscreen steps to set up the additional level of authentication. ## Step 2: Retrieve your API credentials When you verify your account, the Nium creates a `clientHashId` and **API Key**. Use these credentials to build and test your integration with Nium. To successfully submit requests to Nium's API, you must include a `clientHashId` and your API key. These credentials specifically represent: - `clientHashId`: The universally unique identifier (UUID) that represents your account. The Client ID is used in API calls to manage your corporate and individual customers. - `x-api-key`: A randomly generated encoded key. You must include, with the associated `clientHashId` to authenticate and submit requests to Nium. If you lose it, you can regenerate a key in the Nium Portal under **API keys**. Retrieve your active API credentials from Nium Portal. Log in to [Nium Portal](https://app.nium.com) and click **Configuration** > **API keys**. - `clientHashId` is available under **Client ID** - `x-api-key` is available under **API Key** Nium Portal - API Credentials Sandbox and production environments have separate API keys and `clientHashIds`. See our [Authentication](/docs/developers/nium-api/authentication) guide for more details. ## Step 3: Try out the Nium API Use your `clientHashId` and `x-api-key` to try the Nium API. To help you explore, use the Nium Postman collection to try out different requests. For more details, see [Postman Collection](/docs/getting-started/postman-collection). To get started, use the [**Get Client Details** request](/api#tag/client-settings/GET/api/v1/client/{clientHashId}) to test out your credentials. #### Request Example ```shell curl --location 'https://gateway.nium.com/api/v1/client/a1b2c3d4-e5f6-7890-1234-567890abcdef' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' ``` #### Response example ```shell { "name": "Acme Co.", "email": "no-reply@example.com", "contactNo": null, "markup": 0.0, "clientHashId": "a6908180-0016-44d1-865f-4e57d1d5aec5", "prefundName": "Developer Portal Management US", ... } ``` A successful request returns details about how your `client` is configured. Note that for some requests, you may need to include an additional UUID with the `x-request-id` header to help you track API calls. When required, enter any string that helps you keep track of requests. For example, you can include the date and time as the UUID when you submit a request where `x-request-id` is required. With API keys and access to Nium Portal, you have everything you need to build a test integration and explore Nium. The next step in building a test integration is to add customers and entities you can use to run example requests while exploring Nium's offerings. ## Step 4: Prefund your Nium wallet Before you add any customers, you need to add funds to your wallet to help you manage your customer's balances. In this example, and for sandbox transactions, we'll use the [Simulate Receiving a Transaction](/api#tag/payin/POST/api/v1/inward/payment/manual) request to fund a client's wallet. ```shell curl --request POST \ --url https://gateway.nium.com/api/v1/inward/payment/manual \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' \ --data '{ "amount": 1000000, "currency": "USD", "bankReferenceNumber": "1111", "bankSource": "CB_GB", "country":"SG" }' ``` #### Response example ```shell { "success": true, "message": "ICC request has been processed and published successfully" } ``` With funds added, your sandbox transactions to move customer funds will be approved. For production requests, use the [Client Prefund Request](/api#tag/client-prefund-account/POST/api/v1/client/{clientHashId}/prefund) to fund a client's wallet. Once you've submitted the prefund request, contact your Nium account manager to get the request approved. ## Step 5: Add a customer In Nium's API, `customers` represent the corporations and individuals you hold funds for and submit money transfers (also called ***remittances***) on behalf of. Any `customers` you hold or transfer funds for will need to go through an `onboarding` process that involves submitting registration information about the entity and identifying information about the owners and beneficiaries for verification and compliance purposes. See the following guides for more information about onboarding: | Guide | Description | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Individual Customer Onboarding - Overview](/docs/onboarding/individual-customers) | An overview of how to onboard individual customers using the `customer` endpoint. Individual customers include entities you'll be holding or transferring funds on behalf of and any retail end-customers. | | [Corporate Customer Onboarding - Overview](/docs/onboarding/corporate-customers/corporate-constants) | An overview of how to onboard corporate customers using the `customer` endpoint. Corporate customers include the entities you create wallets for, transfer funds on behalf of, and any previous enterprise customers. | | [Nium API Reference - `Customer`](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) | API documentation detailing the `customer` endpoint and available requests. | As you build your integration, use the test values included throughout our documentation to test `customers` and the different `onboarding` scenarios your business will run into. Contact your Nium account manager if you have any questions about onboarding a `customer` and which endpoint to use. For clients who identify as ***Financial Institutions*** (FIs for short) or plan to process transactions on their own behalf, please contact your Nium account manager for specifics about Onboarding requirements. The following articles provide examples of `onboarding` requests you can use to develop your integration (based on where the entity is incorporated and registered). Request Examples | Country | Individual customer | Corporate customer | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Australia - AU | We're actively working on expanding Nium's efforts in Australia. If you have any questions, please contact your Nium Account Manager. | [Corporate Customer Onboarding - AU Request Examples](/docs/onboarding/corporate-customers/au-onboarding/example-requests) | | Canada - CA | We're actively working on expanding Nium's efforts in Canada. If you have any questions, please contact your Nium Account Manager. | [Corporate Customer Onboarding - CA Request Examples](/docs/onboarding/corporate-customers/ca-onboarding/example-requests) | | Europe - EU | [Individual Customer Onboarding - EU Request Examples](/docs/onboarding/individual-customers/onboarding-eu/required-documents) | [Corporate Customer Onboarding - EU Request Examples](/docs/onboarding/corporate-customers/eu-onboarding/example-requests) | | Hong Kong - HK | We're actively working on expanding Nium's efforts in Hong Kong. If you have any questions, please contact your Nium Account Manager. | [Corporate Customer Onboarding - HK Request Examples](/docs/onboarding/corporate-customers/hk-onboarding/example-requests) | | Singapore - SG | [Individual Customer Onboarding - SG Request Examples](/docs/onboarding/individual-customers/onboarding-sg/required-parameters) | [Corporate Customer Onboarding - SG Request Examples](/docs/onboarding/corporate-customers/sg-onboarding/example-requests) | | United Kingdom - UK | [Individual Customer Onboarding - UK Request Examples](/docs/onboarding/individual-customers/onboarding-uk/required-parameters) | [Corporate Customer Onboarding - UK Request Examples](/docs/onboarding/corporate-customers/uk-onboarding/example-requests) | | United States - US | [Individual Customer Onboarding - US Request Examples](/docs/onboarding/individual-customers/onboarding-us/required-documents) | [Corporate Customer Onboarding - US Request Examples](/docs/onboarding/corporate-customers/us-onboarding/example-requests) | Use the requests as needed to build out your onboarding experience. Available examples include: - **Auto-Approvals**: These requests automatically create a `customer` using the submitted information. Use `Auto-Approval` requests to understand how to handle approvals and what approved customers should experience. - **Action required**: A member of Nium's compliance team needs to review the customer's onboarding application manually. **Action required** can be returned for any reason, including missing details to an unsupported country. - **In Progress with documents required**: Required `customer` verification documents are missing. See the `remarks` field for more details on what documents are missing; resubmit the request when you have the documents prepared. - **In Progress with redirection link**: The `customer` still needs to submit identifying information. Also known as Know Your Customer (KYC) details, direct the customer to the URL in `redirectUrl` to submit the missing information. For more details about the different statuses returned when using these examples, see [SG request examples](/docs/onboarding/corporate-customers/sg-onboarding/example-requests). The following examples use the Auto-example request for a corporate SG customer. You can also use this request to follow along and simulate a customer approval. Auto-approval - SG Corporate Customer Onboarding - Request Example ```shell curl --request POST \ --url https://gateway.nium.com/api/v1/client/a1b2c3d4-e5f6-7890-1234-567890abcdef/corporate \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' \ --data '{ "region": "EU", "businessDetails": { "businessName": "KOLBE ELECTRIC COMPANY 1", "businessRegistrationNumber": "320000M01283", "businessType": "PRIVATE_COMPANY", "tradeName": "Kolbe Electric", "website": "www.kolbe.com", "legalDetails": { "registeredCountry": "DE", "registeredDate": "2018-11-12" }, "addresses": { "registeredAddress": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" } }, "taxDetails": [ { "country": "DE", "taxNumber": "12223423" } ], "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD", "fileType": "application/pdf", "document": "" } ] }, { "documentType": "REGISTER_OF_DIRECTORS", "document": [ { "fileName": "RegisterOfDirectors", "fileType": "application/pdf", "document": "" } ] }, { "documentType": "REGISTER_OF_SHAREHOLDERS", "document": [ { "fileName": "RegisterOfShareholders", "fileType": "application/pdf", "document": "" } ] } ], "stakeholders": [ { "referenceId": "29aeb27f-4168-4125-a3b0-fa786f425a7c", "businessPartner": { "businessName": "NEWVILE INC.", "businessRegistrationNumber": "900843822", "businessEntityType": "SHAREHOLDER", "addresses": { "registeredAddress": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" } }, "legalDetails": { "registeredCountry": "DE" }, "sharePercentage": "05.00" } }, { "stakeholderDetails": { "firstName": "KATIE", "middleName": "ATIKINSON", "lastName": "RONTAK", "nationality": "GB", "dateOfBirth": "1981-06-15", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "city": "Eastleigh", "state": "London", "country": "GB", "postcode": "SO53 2FW" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "taxDetails": [ { "country": "DE", "taxNumber": "12223423" } ], "additionalInfo": { "isPep": "No" }, "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "Z3367529", "documentIssuanceCountry": "GB", "documentExpiryDate": "2026-01-04" } ] } } ], "applicantDetails": { "firstName": "SHELDON", "middleName": "PATTERSON", "lastName": "COOPER", "nationality": "DE", "dateOfBirth": "1981-06-15", "address": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" }, "contactDetails": { "contactNo": "8897681220", "email": "sheldon@garage.com", "countryCode": "DE" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "kycMode": "E_DOC_VERIFY", "birthCountry": "DE", "additionalInfo": { "isPep": "No" }, "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "Z3367659", "documentIssuanceCountry": "EU", "documentExpiryDate": "2026-01-04" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes", "searchId":"6b25cdde-6ced-11ee-b962-0242ac120002" } }, "riskAssessmentInfo": { "totalEmployees": "EM005", "annualTurnover": "EU001", "industrySector": "IS053", "intendedUseOfAccount": "IU004", "countryOfOperation": [ "DE" ], "transactionCountries": [ "US", "AU", "DE" ] } }{ "region": "US", "businessDetails": { "businessName": "Acme and Co.", "businessRegistrationNumber": "529402356", "businessType": "LIMITED_LIABILITY_COMPANY", "description": "Limited liability company in US for IT services", "legalDetails": { "registeredCountry": "US", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "223, Grand St.", "addressLine2": "", "city": "New York", "state": "NY", "country": "US", "postcode": "10013" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "MARTHA", "lastName": "ENGLISH REBORN", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "Park Street", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US" } ] } }, { "businessPartner": { "businessName": "CUZEK PRIVATE VENTURES", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "MARTHA", "lastName": "ENGLISH REBORN", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "US", "contactNo": "9974922222", "email": "tony@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "West Hartford", "state": "Connecticut", "postcode": "06110", "country": "US" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US" } ], "additionalInfo": { "applicantDeclaration": "Yes" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "US011", "industrySector": "IS141", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "US", "SG", "HK", "AU" ], "transactionCountries": [ "SG", "AU", "EU" ] } }' ``` The Nium API returns a `customerHashId` that you use to manage the customers' `wallets`, `cards`, and other resources. Response Example ```json { "clientId": "NIM1712038090GBC", "caseId": "34d2c12c-0a70-4c89-ba09-d2c59b3ad640", "status": "IN_PROGRESS", "remarks": "", "customerHashId": "1087d697-49f6-4d5c-a171-8cd49395731b", "walletHashId": "1e2d2de7-7c95-4c04-b7a7-7e14784ddd52", "redirectUrl": "", "expiry": null, "errors": [] } ``` ## Step 6: Fetch wallet details When you create a `customer`, additional resources are also automatically created to help facilitate their finances and experience in Nium. This includes a `wallet` that provides your customer with an account where they can hold their funds and submit transfers. Fetch the details of the `customer` to retrieve their `walletHashId`: ```shell curl --url https://gateway.nium.com/api/v1/client/a1b2c3d4-e5f6-7890-1234-567890abcdef/customer/1087d697-49f6-4d5c-a171-8cd49395731b \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' ``` See `walletHashId` for the UUID you use to fund customers' `wallets`. Response Example ```json { "referenceId": "63792940-7983-466b-b96c-f7528e1c3f80", "customerId": 532574, "walletHashId": "1e2d2de7-7c95-4c04-b7a7-7e14784ddd52", "customerHashId": "1087d697-49f6-4d5c-a171-8cd49395731b", "email": "tony@xyz.com", "countryCode": "US", "mobile": "9974922222", "phoneCode": "1", "firstName": "MARTHA", "middleName": null, "lastName": "ENGLISH REBORN", "preferredName": "MARTHA", "dateOfBirth": "1961-08-11", "gender": null, "nationality": "US", "employeeId": null, "designation": null, "customerType": "CORPORATE", "deliveryAddress1": "Apt X 99, Green Avenue", "deliveryAddress2": null, "deliveryCity": "West Hartford", "deliveryLandmark": null, "deliveryCountry": "US", "deliveryState": "Connecticut", "deliveryZipCode": "06110", "billingAddress1": "Apt X 99, Green Avenue", "billingAddress2": null, "billingCity": "West Hartford", "billingLandmark": null, "billingCountry": "US", "billingState": "Connecticut", "billingZipCode": "06110", "complianceStatus": "IN_PROGRESS", "termsAndConditionAcceptanceFlag": false, "termsAndConditionName": null, "termsAndConditionVersionId": null, "remarks": "Updated compliance details for the Existing Initiate-KYB Customer", "complianceRemarks": "The compliance is updated for existing KYB Customer", "rfiDetails": null, "paymentIds": [ { "currencyCode": "USD", "uniquePaymentId": "85081121750", "uniquePayerId": null, "bankName": "CFSB_US" } ], "status": "Pending", "kycMode": "KYB", "complianceLevel": "SCREENING_KYB", "identificationTypes": [ "NATIONAL_ID" ], "segment": null, "nativeLanguageName": null, "identificationData": [ { "type": "NATIONAL_ID", "value": "xxxxxxxxx" } ], "blockReason": null, "blockComment": null, "blockUpdatedBy": null, "taxDetails": [], "professionalDetails": [ { "position": "SIGNATORY", "sharePercentage": "0.0", "positionStartDate": null, "positionEndDate": null } ], "pep": false, "tags": {}, "businessDetails": { "referenceId": "54dd8104-0c05-4a28-9fd0-87bf3e2ba471", "businessName": "TESSERACT LLC WFWEF", "complianceRegion": "US", "tradeName": null, "businessType": "LIMITED_LIABILITY_COMPANY", "registeredCountry": "US", "businessRegistrationType": null, "businessRegistrationNumber": "529402356", "registeredAddress": { "address1": "223, Grand St.", "address2": "", "city": "New York", "state": "NY", "country": "US", "zipCode": "10013" }, "businessAddress": { "address1": null, "address2": null, "city": null, "state": null, "country": null, "zipCode": null }, "website": null, "registeredDate": "2021-08-10", "listedExchange": null, "caseId": "34d2c12c-0a70-4c89-ba09-d2c59b3ad640", "clientId": "NIM1712038090GBC", "documentDetails": [], "description": "Limited liability company in SG for IT services", "trusteeName": null, "settlorName": null, "formerName": null, "legislationName": null, "legislationType": null, "regulatoryDetails": null, "businessExtractCoveredStakeholder": null, "partnershipDetails": null, "associationDetail": null, "taxDetails": [], "stockSymbol": null }, "stakeholderDetails": [ { "referenceId": "f6060166-56a3-43fa-a7da-e44b16563f94", "firstName": "MARTHA", "middleName": null, "lastName": "ENGLISH REBORN", "gender": null, "dateOfBirth": "1961-08-11", "nationality": "US", "email": null, "mobile": null, "designation": null, "address": { "address1": "Park Street", "address2": null, "city": "Newark", "state": "New Jersey", "country": "US", "zipCode": "07071" }, "professionalDetails": [ { "position": "CONTROL_PRONG", "sharePercentage": null, "positionStartDate": null, "positionEndDate": null } ], "birthCountry": null, "taxDetails": [], "documentDetails": [ { "identificationType": "NATIONAL_ID", "identificationValue": "xxxxxxxxx", "documentIssuanceCountry": "US" } ], "resident": false } ], "businessPartner": [ { "referenceId": "9740ddac-d5fa-433b-89f6-effa26a33909", "businessName": "CUZEK PRIVATE VENTURES", "registrationNumber": "987609384", "businessType": null, "businessEntityType": "UBO", "sharePercentage": "15", "registeredDate": null, "registeredCountry": "US", "addressLine1": null, "addressLine2": null, "city": null, "state": null, "country": null, "postcode": null } ], "riskAssessmentInfo": { "annualTurnover": "US011", "industrySector": "IS141", "totalEmployees": "EM009", "intendedUseOfAccount": "IU003", "transactionCountries": [ "SG", "AU", "EU" ] }, "verificationConsent": false, "countryOfBirth": null, "intendedUseOfAccount": null, "createdAt": "2024-04-02 06:07:49", "updatedAt": "2024-04-02 06:08:16", "estimatedMonthlyFunding": null, "estimatedMonthlyFundingCurrency": null, "internationalPaymentsSupported": false, "expectedCountriesToSendReceiveFrom": null, "regulatoryRegion": "US" } ``` For more details on `wallets`, see: - [Wallets - Overview](/docs/wallets) - [Nium API Reference - `Wallet`](/api#tag/customer-wallet-balance/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}) You can also fetch the details of the `walletHashId` from the `wallet` endpoint to review the details of the account, including the virtual account number (also called VAN). ## Step 7: Issue a Virtual Account Number Next, assign a virtual account number (VAN for short) to the `wallet`. This enables the `wallet` to be cited as a `Funding Instrument` for transactions and funding ```shell curl --url https://gateway.nium.com/api/v1/client/a1b2c3d4-e5f6-7890-1234-567890abcdef/customer/e692e075-57bb-4ccf-ab5e-0cbec8182d21/wallet/2e2375a8-6752-496f-ae50-dccf9f6d7c5f/paymentId \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' \ --data '{ "amount": 1000, "destinationCurrencyCode": "SGD", "fundingChannel": "PREFUND", "sourceCurrencyCode": "SGD" }' ``` #### Request Example ```json { "bankName": "COMMUNITY FEDERAL SAVINGS BANK", "currencyCode": "SGD", "uniquePayerId": null, "uniquePaymentId": "85175412368" } ``` For more details, see [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId). ## Step 8: Fund the customer's wallet With the above information and VAN details, you're ready to move funds. We'll first need to prefund the *customer's wallet* so funds are available to transfer or remit. This funding represents customers depositing funds into their Nium wallet to remit around the world. For this sandbox example, we'll use the [Simulate Receiving a Transaction](/api#tag/payin/POST/api/v1/inward/payment/manual) request. You'll see the balance in your `client` wallet lower in the equivalent amount to cover the transaction while funds are being moved. We'll continue using the same SG customer and wallet as used above: ```shell curl --request POST \ --url https://gateway.nium.com/api/v1/inward/payment/manual \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' \ --data '{ "amount": 10, "bankReferenceNumber": "712347512376", "bankSource": "DBS_SG", "currency": "SGD", "country": "SG" }' ``` #### Response example ```json { "message": "ICC request has been processed and published successfully", "success": true } ``` For details about production requests, see [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments). ## Step 9: Add a beneficiary Next, add a `beneficiary` - the person or organization receiving the remittance. In other words, a `beneficiary` represents the side of the transaction that funds are being transferred to. ```shell curl --request POST \ --url https://gateway.nium.com/api/v2/client/a1b2c3d4-e5f6-7890-1234-567890abcdef/customer/1087d697-49f6-4d5c-a171-8cd49395731b/beneficiaries \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' \ --data '{ "beneficiaryName": "Jane Doe", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "SG", "destinationCountry": "SG", "destinationCurrency": "SGD", "payoutMethod": "LOCAL", "beneficiaryAccountNumber": "235689856", "routingCodeType1": "SWIFT", "routingCodeValue1": "DBSSSGSG" }' ``` #### Response Example ```json { "beneficiaryHashId": "660ba867f9fcab54bcde40e3", "beneficiaryName": "Jane Doe", "beneficiaryContactCountryCode": null, "beneficiaryContactNumber": null, "beneficiaryAccountType": "Individual", "beneficiaryEmail": null, "autosweepPayoutAccount": false, "defaultAutosweepPayoutAccount": false, "remitterBeneficiaryRelationship": null, "beneficiaryAddress": null, "beneficiaryCountryCode": "SG", "beneficiaryState": null, "beneficiaryCity": null, "beneficiaryPostcode": null, "beneficiaryCreatedAt": "2024-04-02 06:40:39", "beneficiaryUpdatedAt": "2024-04-02 06:40:39", "payoutHashId": "660ba867f9fcab54bcde40e5", "destinationCountry": "SG", "destinationCurrency": "SGD", "beneficiaryBankName": "DBS Bank Ltd", "beneficiaryBankAccountType": null, "beneficiaryAccountNumber": "235689856", "beneficiaryBankCode": null, "routingCodeType1": "SWIFT", "routingCodeValue1": "DBSSSGSG", "routingCodeType2": null, "routingCodeValue2": null, "payoutMethod": "LOCAL", "beneficiaryIdentificationType": null, "beneficiaryIdentificationValue": null, "payoutCreatedAt": "2024-04-02 06:40:39", "payoutUpdatedAt": "2024-04-02 06:40:39", "beneficiaryCardType": null, "beneficiaryCardToken": null, "beneficiaryCardNumberMask": null, "beneficiaryCardIssuerName": null, "beneficiaryCardExpiryDate": null, "beneficiaryCardMetaData": null, "proxyType": null, "proxyValue": null, "beneficiaryContactName": null, "beneficiaryEntityType": null, "beneficiaryDob": null, "beneficiaryEstablishmentDate": null } ``` For more details, see [Add Beneficiary](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries). With the `wallet` funded and a `beneficiary` created, your `customer` can now transfer funds. ## Step 10: Create a payout In Nium's API, the `remittance` object (also called payouts) represents transfers that move funds out of wallets. Create a `remittance` to debit funds from a `customers` wallet and transfer them to a `beneficiary`. ```shell curl --request POST \ --url "https://gateway.nium.com/api/v2/client/a1b2c3d4-e5f6-7890-1234-567890abcdef/customer/1087d697-49f6-4d5c-a171-8cd49395731b/wallet/1e2d2de7-7c95-4c04-b7a7-7e14784ddd52/remittance" \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' \ --data '{ "beneficiary": { "id": "660ee40ff9fcab54bcdec4fa" }, "payout": { "source_amount": "500", "source_currency": "GBP" }, "purposeCode": "IR001", "sourceOfFunds": "Personal Savings", "exemptionCode": "01" }' ``` #### Response Example ```json { "message": "Transfer Initiated", "payment_id": null, "system_reference_number": "RT0710486913" } ``` The above response means you successfully charged the wallet. Once approved, the funds will be moved to the beneficiary. For more information about payouts, see [Transfer Money](/docs/payouts). ## Next Steps After taking these steps, you have everything you need to test Nium's API and fully build out your integration. If you have any questions, both technical and operations-related, please don't hesitate to contact your Nium account manager or email the [Nium Support team](mailto:support@nium.com). Other parts of the Nium One platform to explore include: - [Wallets](/docs/wallets) - [Payouts](/docs/payouts) - [Cards](/docs/cards) --- # Key Concepts URL: https://docs.nium.com/docs/getting-started/key-concepts Nium is a flexible, comprehensive, and easy-to-embed fintech infrastructure platform. Companies use Nium to launch and manage their payment platforms and take advantage of several features, including: - Domestic or cross-border transfers - Holding balances in multicurrency wallets - Card issuing - Receiving multiple currencies into a single wallet locally, for example, receiving GBP in the UK using the Faster Payments Service (FPS) or the Clearing House Automated Payment System (CHAPS) This guide provides a high-level overview of the platform features. Sign up ## Clients It all starts with the setup of a platform client. Nium configures the solution that meets your needs. The client configuration captures the multicurrency configuration, virtual account number-related configuration, card-issuing details, customer onboarding requirements, risk parameters, fee details, and so on. As the diagram above illustrates, the platform client is at the top of the hierarchy. As part of the platform client onboarding—that is as part of your onboarding before you can integrate and access the APIs—Nium does the needful API configuration of IP allow listing and keys provisioning. It helps you with the details you need to connect to the platform API endpoints. You use the APIs to onboard new customers, issue them cards, check balances, see transaction listings, and manage payouts, among other tasks. Depending on the nature of the product or program you're planning to build you might want to make use of the `prefund` accounts capability. If you're operating as a corporate travel and expense (T\&E) business, for example, funding to the underlying customer-level wallet only comes from you. You can then fund first into your `prefund` account and then allocate funds to the respective customer-level wallets using your pre-funded account as the funding source. You can fund into the `prefund` accounts using local and Society for Worldwide Interbank Financial Telecommunication (SWIFT) bank rails. Refer to the [Parent-child hierarchy](/docs/getting-started/parent-child-hierarchy) overview to set up the parent corporate customer and the child individual customer. This configuration is useful in Spend and Payroll Management use cases. ## Customers Next in the hierarchy is the customer. There are two types of customers, the individual customer and the corporate or business customer. The individual customer is an end user who holds the balance. In a corporate customer T\&E use case, this would be a staff member who receives a T\&E card. In a consumer-funded use case, this would be the retail end customer who has the account. Depending on the nature of the product or program, the Know Your Business (KYB), the Know Your Customer (KYC), and the onboarding flow differ. For more information, refer to the [Individual customer onboarding overview](/docs/onboarding/individual-customers) and the [Corporate customer onboarding overview](/docs/onboarding/corporate-customers/corporate-constants) guides. Work with your Nium program representative to help you navigate your onboarding. As an example, where the KYC process is mandatory, Nium's e-KYC options—MyInfo in Singapore, greenID in Australia, and Onfido in multiple markets—need to be used to automate the KYC and the onboarding process. ## Multicurrency wallets Every customer or account holder gets a multicurrency wallet or a multicurrency account. Since a wallet is considered an account, the terms wallet and account are used interchangeably. The wallet is set up for the platform client. It has placeholders or stores to carry one or as many currencies as configured for the platform client. For more information, refer to the [Wallet overview](/docs/wallets) guide. ## Virtual account numbers Based on the product configuration, the platform automatically assigns virtual account numbers (VANs) at the wallet-currency level by using the configured VAN sources. You can also use the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) API to assign VANs at the currency level. If the product configuration, for example, is such that a VAN for SGD, from Nium's SG bank partner, needs to be assigned, then when the wallet is created, the platform automatically allocates an SGD VAN from the SG bank partner and maps it to the SGD currency of the wallet. This facilitates the account holder to fund SGD in the wallet by using the SG local bank rails, for instance, the Fast And Secure Transfers (FAST) service in Singapore. Nium can assign a VAN from the following countries: - SGD (local) in SG - GBP (local) in the UK - AUD (local) in AU - EUR (SEPA) in EU - USD (local) in the US Contact your Nium representative to learn about additional VAN sources. The multicurrency balances held within the wallet—if the product requires multicurrency support—can be exchanged between each other. Nium provides competitive foreign exchange (FX) rates and helps you with liquidity. The platform also lets you move funds from one customer's wallet to another customer’s wallet—provided the transaction is performed in the same currency and the two customers are under the same platform client. ## Payins The Payin service lets you receive, hold, and offer payment methods through bank transfers, cards, digital wallets, and a Nium-assigned virtual account number (VAN). The Payin product capabilities include monetary collections and funding. The Payin collections capability helps you collect money from a third party—a payer or a buyer—and put it into your Nium wallet. An example would be a business-to-business collections process where a United States (US)-registered software company collects money from its business customers to charge for its software service subscription. The Payin funding capability helps you fund your Nium wallet through a bank transfer from your own bank account into your Nium-assigned VAN or funding wallet account. An example would be a corporate customer that wants to fund into their Nium wallet to use the money to compensate their payroll employees for their work on a regular basis. ## Transactions Nium offers a comprehensive payment network built through global partnerships with clearing systems, banks, and service providers. Clients use this network to process various types of transactions (also called transfers), including: - **Payouts** (also known as remittances) - **Wallet to wallet transfers** Whether you need to process transactions for your business, personal use, or create a seamless experience for your customers, Nium provides the necessary tools. ### Payouts A payout is a transaction that transfers funds (credit or debit) between a client and a third party. Funds available in a wallet can be used for both domestic and cross-border payouts. The platform automatically deducts the required balance from the appropriate wallet and processes the transaction through Nium’s global payment network. Nium’s foreign exchange (FX) conversion services let you send funds from any available wallet currency to a supported recipient currency. For example, you can transfer funds from a USD wallet balance to a PHP wallet or a bank account in the Philippines. Our FX service automatically applies conversion charges, making cross-border transfers seamless. For more information, see [Payouts](/docs/payouts). ### Wallet to wallet transfers Using Nium’s FX conversion services, you can transfer funds between wallets in different currencies. For example, you can transfer funds from your USD wallet balance to your GBP wallet or a bank account in the United Kingdom. Our FX service automatically applies conversion charges, streamlining cross-border transfers. For more information, see the [Wallets](/docs/wallets) guide. ## Cards As part of the client setup, you could work with Nium to configure one or many card programs. By using the Cards API endpoints, you could issue one or many cards—physical or virtual—referring to the configured card programs linked to a given wallet. The balance always stays at the wallet level and cards are payment instruments to act on the balance. Read about the [Delegated Model](/docs/cards/dynamic-authorization/delegated-model) for an alternative approach to keep the wallet-level balances at your end. Every time a Nium-issued card is used at the merchant point of sale or at an ATM terminal, Nium processes the card transactions—authorization, clearing, and settlement—and you don't need to worry about the transaction processing, reconciliation, and settlement. You can use the APIs to manage the cards—set limits, block or unblock cards—check balances at the wallet level, and check transaction listing. You can subscribe to webhooks to receive real-time events from the platform and you could use that to manage communication with the end users, such as push notifications, email messages, and Short Message Service (SMS). For more information, refer to the [Card overview](/docs/cards) guide. To learn more about the technical words this guide uses, refer to the [Glossary of Nium terms](/docs/getting-started/glossary). --- # Postman Collection URL: https://docs.nium.com/docs/getting-started/postman-collection Postman is an API platform for using APIs. With Postman you can easily make API calls without the need to setup a programming environment. Nium has made a Postman Collection for all of [Nium's APIs.](/api) You can use this collection to sample, test, or debug an API request. You will see a number of instances with buttons on our guides. You may click on them and it will take you to the public collection where you can fork or copy the request into your own workspace. Pull changes may override changes that you have made to your collection. If you want to preserve your own changes and incorporate updates, you can use **Merge Changes** instead. ## Setting up Nium Collection How to Fork the Collection and Setup the environment variables. 1. Navigate to the [Postman Collection](https://www.postman.com/nium-api/workspace/nium) and select **Create Fork** Sign up 2. **Fork the Collection** - When you select Fork, Postman will ask you what destination to Fork this Collection to.\ From your workspace selector, you can select a destination. It can be a team or private workspace.\ You can also add a label to distinguish this instance that you are copying.\ You can select **watch original collection** to get notifications if the source collection gets updated. See [Updating Nium Postman Collection](#updating-nium-postman-collection). Sign up 3. **Fork the Environments** - You will also need to Fork the environments on the Environments Tab. Sign up 4. Copy your API key & Client id into the applicable environment, and **save**.\ The data must be saved in both the **Initial** & **Current** value spaces.\ **Initial values:** Are a default set of values that can be used for your requests.\ **Current values:** Can change as you make requests, and can be set by the collection (such as card\_id, wallet\_id, etc.)\ For more information on how these work see: [Adding environment variables in Postman](https://learning.postman.com/docs/sending-requests/environments/managing-environments/#add-environment-variables) Sign up 5. Send your API request ## Updating Nium Postman Collection From time to time, Nium will be updating our collection. This might include adding more APIs, adding examples, adding workflows. Your Forked collection will not update automatically.\ For this you will need to **Pull Changes** from the source collection to pick up new updates. If you selected **watch original collection** when you Forked the collection you will get notifications when Nium has made updates. ### Pulling New Changes 1. Select the collection you wish to update 2. From the collections menu select **Pull Changes** Sign up 3. You will see a list of changes before you accept. 4. Hit accept and the changes will be incorporated into your Collection. --- # Parent-Child Hierarchy URL: https://docs.nium.com/docs/getting-started/parent-child-hierarchy A parent-child structure means one data item is the parent of another data item, the child. In a parent-child hierarchy, a relationship is established between the corporate customer—the parent—and the individual customer—the child. This relationship is useful in Spend Management and Payroll use cases. In Spend Management and Payroll Management use cases, you need to onboard your parent corporate customer's child, or individual employee, under them. In Spend Management, your corporate customer funds the business expenses the employee makes. The corporate customer issues a card on their accounts that the employee can use. Your corporate customer's account funds the expenses. The funds belong to your corporate customer and the employee can only use the money for business purposes. In Payroll Management, your corporate customer credits salaries to their employees from their corporate customer account and into their individual accounts. Those funds belong to the employees, and they can use them as needed. The cards issued to the individual accounts use their own funds for personal expenses. ## Prerequisites - If the flag `childMustHaveParent` is set to `true`, you're required to link the individual customer or employee, to your corporate customer. If the flag is set to `false`, you can choose to either link or not link the individual customer to your corporate customer. - The flag `billingAddressAsCorporate` lets the individual customer and the corporate customer have the same billing address. - For Spend Management clients, you need to configure the `billingAddressAsCorporate` flag to `true`. - For Payroll Management clients, you need to configure the `billingAddressAsCorporate` flag to `false`. If the corporate customer's billing address changes, the platform automatically updates the individual customer's billing address to be the same. You need to onboard your corporate customer before you onboard their individual employees or customers. ## API server URLs Use the following host names to distinguish the API calls between the different working environments. - Sandbox: `https://gateway.nium.com` - Production: `https://api.spend.nium.com` ## Supported countries and currencies To see all the countries and currencies that the Spend and Payroll Management capabilities support, refer to the [Nium Playbook](https://playbook.nium.com/). ## API requests The following APIs support the Spend and Payroll Management use cases: | HTTP method | API name                    | Action | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | [Client Details](/api#tag/client-settings/GET/api/v1/client/{clientHashId}) | Helps you fetch the configuration details about a client. | | POST | [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) | Helps you onboard customers based on the client's configuration and preference. Links the individual customer to the corporate customer. | | GET | [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | Helps you fetch a customer's details. | | GET | [Customer List V3](/api#tag/customer-management/GET/api/v3/client/{clientHashId}/customers) | Helps you fetch the customers for a client. Supports query parameters based on filtering to fetch details about a linked customer to a corporate customer. | | POST | [Add Card V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) | Helps you issue a card for a customer. | | GET | [Card List](/api#tag/lifecycle/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/cards) | Helps you return all the cards issued for a given wallet. | | GET | [Card Details V2](/api#tag/lifecycle/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}) | Helps you get details about a card. | | GET | [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) | Helps you fetch the transaction details for a customer. | | GET | [Client Transactions](/api#tag/client-transactions/GET/api/v1/client/{clientHashId}/transactions) | Helps you fetch the transaction details at the client level. It also supports query parameters based on filtering to fetch details of the transactions for the customer. | ## Configure employee relationship To establish the connection between your corporate customer and an individual customer or employee, [onboard the corporate customer](/docs/onboarding/corporate-customers/corporate-constants) first and then onboard the employee using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API. The following table gives information about the above API parameters which are needed to connect the individual customer to the corporate customer. | Unified Add Customer API parameter | Spend Management | Payroll Management | Other use cases | | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Client configuration `ChildMustHaveParent = True` `BillingAddressAsCorporate = True` | Client configuration `ChildMustHaveParent = True` `BillingAddressAsCorporate = False` | Client configuration `ChildMustHaveParent = True` `BillingAddressAsCorporate = False` | | `parentCustomerHashId` | Required The acceptable value is corporate `customerHashId` to which the employee is linked. The corporate customer's Know Your Customer (KYC) status needs to be clear. The corporate customer and the individual customer should be from the same client setup. | Required The acceptable value is corporate `customerHashId` to which the employee is linked. The corporate customer's KYC status needs to be clear. The corporate customer and the individual customer should be from the same client setup | Optional The acceptable value is corporate `customerHashId` to which the individual customer is linked. | | `kycMode` | RequiredThe acceptable value is:`MANUAL_KYC`KYC document required is employment letter | RequiredThis field only accepts the following values:`E_KYC``MANUAL_KYC``SCREENING``E_DOC_VERIFY`KYC document is based on region-specific guidelines mentioned in the [Individual Customer Onboarding](/docs/onboarding/individual-customers) Overview guide | RequiredThis field only accepts the following values:`E_KYC``MANUAL_KYC``SCREENING``E_DOC_VERIFY`KYC document is based on region-specific guidelines mentioned in the [Individual Customer Onboarding](/docs/onboarding/individual-customers) Overview guide | | `billingAddress1` | Optional | Required | Required | | `billingAddress2` | Optional | Required | Required | | `billingCity` | Optional | Required | Required | | `billingCountry` | Optional | Required | Required | | `billingLandmark` | Optional | Required | Required | | `billingState` | Optional | Required | Required | | `billingZipCode` | Optional | Required | Required | The following diagram shows the relationship between a corporate customer and an employee. Sign up You can fetch the customer details using the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API. You can find the corporate customer's `parentCustomerHashId` in the customer details. Once an individual customer is created, with the `parentCustomerHashId` parameter, you won't be able to update that property. If you need to update that property, you need to block the previous individual customer and create a new one to link them to another corporate customer. You can also fetch a customer list using the [Customer List V3](/api#tag/customer-management/GET/api/v3/client/{clientHashId}/customers) API. This endpoint shows the `parentCustomerHashId` parameter for all individual customers. You can fetch all the individual customers linked to a corporate customer by providing the `parentCustomerHashId` as a part of the query parameter. ### Add a card to an employee To add a card for your corporate customers' employees or individual customers, who are linked to the corporate wallet, follow these steps: 1. Issue a card in your corporate customer's account using the [Add Card V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) API. 2. In the Add Card V2 API include the following information: 1. `customerHashId`: This parameter is required. This field accepts the value as the `customerHashId` of your corporate customer. 2. `walletHashId`: This parameter is required. This field accepts the value as the `walletHashId` of your corporate customer. 3. `childCustomerHashId`: This parameter is optional. This field accepts the value as `customerHashId` of the individual customer, or employee, who uses the card. 1. The `customerHashId`, included in the `childCustomerHashId` field, needs to belong to the individual customer linked to the corporate customer. 2. The corporate customer, whose wallet is used, and the individual customer should be from the same client setup. 3. Make sure your individual customer and the corporate customer associated with the given corporate customer wallet, have their KYC status clear. The corporate customer is the owner of the card, and the employee is the user of the card. Sign up Fetch the `childCustomerHashId` with the [Card Details V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) API. The `childCustomerHashId` is visible in the details section of the API. To fetch the details for **Card B**, in the above diagram, provide the values for the following parameters: - `cardHashId`: `cardHashId` of Card B - `customerHashId`: `customerHashId` of the corporate customer A - `walletHashId`: `walletHashId` of the corporate customer All path parameters are required to fetch any of the card details. You can retrieve the card list using the [Card List](/api#tag/lifecycle/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/cards) API, which contains the `childCustomerHashId` field. This operation lets you fetch all the cards listed that are linked to a corporate customer by providing the `customerHashId` in the path parameter. The query parameter includes the `childCustomerHashId`. ### Assigning a card to an employee This use case applies to Payroll Management where the funds belong to the employees, and they can spend the funds for their own purposes. For such a scenario, you can establish the relationship between a corporate customer and its employees, and the cards are assigned to an employee linked to their own account.  In this event, the `childCustomerHashId` is `null` and the `customerhashId` and the `walletHashId` are of the individual customer. Sign up ### Transaction management You can fetch transactions at the client and wallet level via the [Client Transactions](/api#tag/client-transactions) API and the [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) API, respectively. The transaction details include the `childCustomerHashId` parameter, which provides the `customerHashId` of the individual customer, or employee, who made the transaction. You can also retrieve all employee transactions by providing the `childCustomerHashId` parameter in the query of the Client Transactions API and the Transactions API. You need to include the `customerHashId` of the individual customer or employee, in the `childCustomerHashId` field and include it as a query parameter in the API. The response provides all the transactions the employee makes. ### Use cases | Target segment | Client type | Use case | | :--------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Payroll | Non-financial platform clients | As a payroll client, you want to onboard the employees under the corporate customer they belong to. | | Spend Management | Non-financial platform clients | As a spend management client, you want to onboard the employees under the corporate customer they belong to. You want to fund the expenses made by the employees from the corporate customer’s account. | --- # Glossary URL: https://docs.nium.com/docs/getting-started/glossary | Term | Description | | Term | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | — A — | | **Allowlist** | An allowlist is a list of email addresses or domains that you want to receive emails from. | | **Applicant** | An authorized representative or a signatory of the corporate customer who fills out the application for onboarding on the corporate customer's behalf. | | | — C — | | **Chargeback** | A chargeback—also called a reversal—is the return of credit-card or direct-debit funds used to make a purchase to the buyer. | | **CoP** | Confirmation of Payee. | | **Corporate customer** | A business organization that's being onboarded by a client on the Nium One platform. The corporate customer includes Small and Medium Enterprises (SME). | | **Customer** | The entity who onboards to Nium through a client and whom Nium has verified their identity and assigned them a wallet. An **individual customer** is the end user who holds the balance. A **corporate customer** is the business entity that holds the balance. | | | — D — | | **Denylist** | A denylist is a list of email addresses or domains that you don't want to receive emails from. | | **Direct debit** | A way to pay someone by allowing Nium to take money directly from a customer's bank account. | | | — E — | | **E\_DOC\_VERIFY** | A real-time Know Your Customer (KYC) process where a selfie photograph and document are uploaded on the vendor's page. The vendor verifies the authenticity of the documents provided. This is available for individual customers or for applicants of corporate customers. | | **eKYB** | Electronic Know Your Business (eKYB) is a process of verification of the corporate customer and its associated entities real-time using Nium APIs. Using eKYB, applications can get approved in a few minutes. | | **E\_KYC** | Electronic Know Your Customer (E\_KYC) is the real-time KYC verification process applicable for applicants or stakeholders of a corporate customer or individual customers. `E_KYC`​ is usually done via database verification apart from SG where `E_KYC` involves authentication in Singpass portal. | | **EOR** | An employer of record (EOR) is an entity that legally employs workers on behalf of another business. An EOR takes full responsibility for all aspects of employment including compliance, payroll, taxes, and benefits. | | | — F — | | **FAST** | Fast and Secure Transfers. | | **FI** | Financial Institutions (FI) are business entities that provide services as intermediaries for different types of financial monetary transactions. | | **Fund** | To make provision of monetary resources for discharging the interest or principal of. To provide funds for something. The act of a Nium customer using a direct debit or funding transaction to pull money from the end customer’s bank account and adding it to the end customer’s Nium wallet. | | | — G — | | **GL** | A general ledger, or GL, is a means for keeping record of a company's total financial accounts. Accounts typically recorded in a GL include: assets, liabilities, equity, expenses, and income or revenue. | | **GPI** | Global Payments Innovation. | | | — I — | | **ICC** | Inward Credit Confirmation. | | | — K — | | **KYB** | Know Your Business (KYB) is a process of collection of information and verification of information of a corporate customer. The process is part of Anti-Money Laundering and Countering the Financing of Terrorism (AML/CFT) regulations. eKYB and Manual KYB are available options. | | **KYC** | Know Your Customer (KYC) is a process that requires Nium to collect and verify information about applicants or stakeholders of a corporate customer or individual customers. The process is part of AML/CFT regulations. `E_KYC`, `MANUAL_KYC`, `E_DOC_VERIFY` are available options. | | | — M — | | **Manual KYB** | Manual Know Your Business (KYB) refers to the KYB flow in which the client needs to submit all the data and documents of the corporate customer which are manually verified by Nium's compliance team. | | **Manual Review** | In any process, if the automatic verification isn't successful, the onboarding application or transaction is sent for manual review. The compliance agent manually verifies the information. This applies to the eKYB flow for onboarding a corporate customer or in the eKYC flow for the individual customer or in any transaction. | | **MCC** | Merchant Category Code. | | **MCW** | Multicurrency wallet (MCW) is the storage mechanism for all the configured currencies. | | | — O — | | **OCT** | Original Credit Transfer. | | | — P — | | **Payin** | The Nium product that puts money in an account as a result of making a deposit. | | **Payout** | The Nium product that lets you make payments to more than 220+ markets all over the world. | | **PEP** | Politically Exposed Person. | | **PP** | Payment Processor. | | | — R — | | **RFI** | Request for information (RFI) are requests the compliance agent asks for more information. The customer then submits the requested information. | | | — S — | | **Screening** | All individual and corporate customers undergo screening during onboarding and periodically. They're screened against global and Nium-maintained sanctions, PEP lists, and deny lists. | | **Stakeholder** | A stakeholder is an individual or entity that's declared in the registration documents of the business as an officer or director or shareholder. | | | — T — | | **T\&C** | Terms and Conditions (T\&C) represent an existing agreement between parties such as a person or individual which includes corporate bodies, unincorporated associations, partnerships, and individuals. | | **T\&E** | Travel and expenses. | | | — V — | | **VAN** | A virtual account number (VAN) is linked to a central account and allows incoming funds for collection or funding to be reconciled into the customer's wallet. | | | — W — | | **Wallet** | The storage mechanism to keep balances in multiple currencies. A Nium application for organizing cards and bank accounts. | | **Withdrawal** | A withdrawal is when the client initiates a payout request where Nium debits the customer's Nium wallet and credits it to their own bank account. | --- # Currency and Country Codes URL: https://docs.nium.com/docs/getting-started/currency-and-country-codes For your reference, below you'll find a list of all the currencies and countries that are recognized throughout the world. > 📌 **IMPORTANT** > > This list **is not** indicative of the countries and currencies supported by Nium. - For a list of ***supported countries and currencies***, see the [Nium Playbook](https://playbook.nium.com/). - For a list of ***prohibited countries***, see [Prohibited Countries](/docs/transactions/prohibited-countries). ## Africa | Currency code | Currency name | ISO2 name | Country name | Phone code | | :------------ | :---------------------------- | :-------- | :------------------------------------ | :--------- | | DZD | Algerian Dinar | DZ | Algeria | 213 | | AOA | Angolan Kwanza | AO | Angola | 244 | | XOF | CFA Franc BCEAO | BJ | Benin | 229 | | BWP | Botswana Pula | BW | Botswana | 267 | | XOF | CFA Franc BCEAO | BF | Burkina Faso | 226 | | BIF | Burundian Franc | BI | Burundi | 257 | | XAF | CFA Franc BEAC | CM | Cameroon | 237 | | CVE | Cape Verdean Escudo | CV | Cape Verde | 238 | | XAF | CFA Franc BEAC | CF | Central African Republic | 236 | | XAF | CFA Franc BEAC | TD | Chad | 235 | | KMF | Comorian Franc | KM | Comoros | 269 | | XAF | CFA Franc BEAC | CG | Congo | 242 | | CDF | Congolese Franc | CD | Congo, The Democratic Republic of the | 243 | | XOF | CFA Franc BCEAO | CI | Cote D'Ivoire | 225 | | DJF | Djiboutian Franc | DJ | Djibouti | 253 | | EGP | Egypt Pound | EG | Egypt | 20 | | XAF | CFA Franc BEAC | GQ | Equatorial Guinea | 240 | | ERN | Eritrean Nakfa | ER | Eritrea | 291 | | ETB | Ethiopian Birr | ET | Ethiopia | 251 | | XAF | CFA Franc BEAC | GA | Gabon | 241 | | GMD | Gambian Dalasi | GM | Gambia | 220 | | GHS | Ghanaian Cedi | GH | Ghana | 233 | | GNF | Guinean Franc | GN | Guinea | 224 | | XOF | CFA Franc BCEAO | GW | Guinea-Bissau | 245 | | KES | Kenyan Shilling | KE | Kenya | 254 | | LSL | Lesotho Loti | LS | Lesotho | 266 | | LRD | Liberia Dollar | LR | Liberia | 231 | | LYD | Libyan Dinar | LY | Libyan Arab Jamahiriya | 218 | | MGA | Malagasy Ariary | MG | Madagascar | 261 | | MWK | Malawian Kwacha | MW | Malawi | 265 | | XOF | CFA Franc BCEAO | ML | Mali | 223 | | MRO | Mauritanian Ouguiya (pre2018) | MR | Mauritania | 222 | | MUR | Mauritius Rupee | MU | Mauritius | 230 | | MAD | Moroccan Dirham | MA | Morocco | 212 | | MZN | Mozambique Metical | MZ | Mozambique | 258 | | NAD | Namibia Dollar | NA | Namibia | 264 | | XOF | CFA Franc BCEAO | NE | Niger | 227 | | NGN | Nigeria Naira | NG | Nigeria | 234 | | RWF | Rwandan Franc | RW | Rwanda | 250 | | XOF | CFA Franc BCEAO | SN | Senegal | 221 | | SCR | Seychelles Rupee | SC | Seychelles | 248 | | SLL | Sierra Leonean Leone | SL | Sierra Leone | 232 | | SOS | Somalia Shilling | SO | Somalia | 252 | | ZAR | South Africa Rand | ZA | South Africa | 27 | | SDG | Sudanese Pound | SD | Sudan | 249 | | SZL | Swazi Lilangeni | SZ | Eswatini | 268 | | TZS | Tanzanian Shilling | TZ | Tanzania, United Republic of | 255 | | XOF | CFA Franc BCEAO | TG | Togo | 228 | | TND | Tunisian Dinar | TN | Tunisia | 216 | | UGX | Ugandan Shilling | UG | Uganda | 256 | | MAD | Moroccan Dirham | EH | Western Sahara | 212 | | ZMK | Zambian Kwacha | ZM | Zambia | 260 | | ZWL | Zimbabwean Dollar | ZW | Zimbabwe | 263 | ## Asia | Currency code | Currency name | ISO2 name | Country name | Phone code | | :------------ | :----------------------- | :-------- | :------------------------------------- | :--------- | | AMD | Armenian Dram | AM | Armenia | 374 | | BDT | Bangladeshi Taka | BD | Bangladesh | 880 | | BTN | Bhutanese Ngultrum | BT | Bhutan | 975 | | BND | Brunei Darussalam Dollar | BN | Brunei Darussalam | 673 | | KHR | Cambodia Riel | KH | Cambodia | 855 | | CNY | China Yuan Renminbi | CN | China | 86 | | HKD | Hong Kong Dollar | HK | Hong Kong | 852 | | INR | India Rupee | IN | India | 91 | | IDR | Indonesia Rupiah | ID | Indonesia | 62 | | JPY | Japan Yen | JP | Japan | 81 | | KPW | Korea (North) Won | KP | Korea, Democratic People's Republic of | 850 | | KRW | Korea (South) Won | KR | Korea, Republic of | 82 | | LAK | Laos Kip | LA | Lao People's Democratic Republic | 856 | | MOP | Macanese Pataca | MO | Macao | 853 | | MYR | Malaysia Ringgit | MY | Malaysia | 60 | | MVR | Maldivian Rufiyaa | MV | Maldives | 960 | | MNT | Mongolia Tugrik | MN | Mongolia | 976 | | MMK | Myanma Kyat | MM | Myanmar | 95 | | NPR | Nepal Rupee | NP | Nepal | 977 | | PHP | Philippines Peso | PH | Philippines | 63 | | RUB | Russia Ruble | RU | Russian Federation | 7 | | SGD | Singapore Dollar | SG | Singapore | 65 | | LKR | Sri Lanka Rupee | LK | Sri Lanka | 94 | | TWD | New Taiwan Dollar | TW | Taiwan, Republic of China | 886 | | THB | Thailand Baht | TH | Thailand | 66 | | USD | United States Dollar | TL | Timor-Leste | 670 | | VND | Vietnam Dong | VN | Vietnam | 84 | ## Australia and Oceania | Currency code | Currency name | ISO2 name | Country name | Phone code | | :------------ | :--------------------- | :-------- | :-------------------------------- | :--------- | | AUD | Australia Dollar | AU | Australia | 61 | | AUD | Australia Dollar | CX | Christmas Island | 61 | | AUD | Australia Dollar | CC | Cocos (Keeling) Islands | 61 | | NZD | New Zealand Dollar | CK | Cook Islands | 682 | | AUD | Australia Dollar | HM | Heard Island and McDonald Islands | 0 | | AUD | Australia Dollar | KI | Kiribati | 686 | | USD | United States Dollar | MH | Marshall Islands | 692 | | AUD | Australia Dollar | NR | Nauru | 674 | | XPF | CFP Franc | NC | New Caledonia | 687 | | NZD | New Zealand Dollar | NZ | New Zealand | 64 | | NZD | New Zealand Dollar | NU | Niue | 683 | | AUD | Australia Dollar | NF | Norfolk Island | 672 | | PGK | Papua New Guinean Kina | PG | Papua New Guinea | 675 | | NZD | New Zealand Dollar | PN | Pitcairn | 870 | | SBD | Solomon Islands Dollar | SB | Solomon Islands | 677 | | NZD | New Zealand Dollar | TK | Tokelau | 690 | | TOP | Tongan Pa'anga | TO | Tonga | 676 | | AUD | Australia Dollar | TV | Tuvalu | 688 | | VUV | Vanuatu Vatu | VU | Vanuatu | 678 | | XPF | CFP Franc | WF | Wallis and Futuna | 681 | ## Caribbean | Currency code | Currency name | ISO2 name | Country name | Phone code | | :------------ | :------------------------- | :-------- | :------------------------------- | :--------- | | XCD | East Caribbean Dollar | AI | Anguilla | 264 | | XCD | East Caribbean Dollar | AG | Antigua and Barbuda | 268 | | AWG | Aruba Guilder | AW | Aruba | 297 | | BSD | Bahamas Dollar | BS | Bahamas | 1 | | BBD | Barbados Dollar | BB | Barbados | 246 | | BMD | Bermuda Dollar | BM | Bermuda | 440 | | KYD | Cayman Islands Dollar | KY | Cayman Islands | 245 | | CUP | Cuba Peso | CU | Cuba | 53 | | XCD | East Caribbean Dollar | DM | Dominica | 767 | | DOP | Dominican Republic Peso | DO | Dominican Republic | 1 | | XCD | East Caribbean Dollar | GD | Grenada | 473 | | HTG | Haitian Gourde | HT | Haiti | 509 | | JMD | Jamaica Dollar | JM | Jamaica | 1 | | XCD | East Caribbean Dollar | MS | Montserrat | 1 | | USD | United States Dollar | PR | Puerto Rico | 1 | | XCD | East Caribbean Dollar | KN | Saint Kitts and Nevis | 868 | | XCD | East Caribbean Dollar | LC | Saint Lucia | 757 | | XCD | East Caribbean Dollar | VC | Saint Vincent and the Grenadines | 783 | | TTD | Trinidad and Tobago Dollar | TT | Trinidad and Tobago | 868 | | USD | United States Dollar | TC | Turks and Caicos Islands | 1 | | USD | United States Dollar | VG | Virgin Islands, British | 1 | | USD | United States Dollar | VI | Virgin Islands, U.S. | 1 | ## Europe | Currency code | Currency name | ISO2 name | Country name | Phone code | | :------------ | :--------------------------------------- | :-------- | :----------------------------------------- | :--------- | | EUR | Euro Member Countries | AX | Aland Islands | 340 | | ALL | Albania Lek | AL | Albania | 355 | | EUR | Euro Member Countries | AD | Andorra | 376 | | EUR | Euro Member Countries | AT | Austria | 43 | | BYR | Belarus Ruble | BY | Belarus | 375 | | EUR | Euro Member Countries | BE | Belgium | 32 | | BAM | Bosnia and Herzegovina Convertible Marka | BA | Bosnia and Herzegovina | 387 | | NOK | Norway Krone | BV | Bouvet Island | 55 | | BGN | Bulgaria Lev | BG | Bulgaria | 359 | | HRK | Croatia Kuna | HR | Croatia | 385 | | EUR | Euro Member Countries | CY | Cyprus | 357 | | CZK | Czech Republic Koruna | CZ | Czech Republic | 420 | | DKK | Denmark Krone | DK | Denmark | 45 | | EUR | Euro Member Countries | EE | Estonia | 372 | | FKP | Falkland Islands (Malvinas) Pound | FK | Falkland Islands (Malvinas) | 500 | | DKK | Denmark Krone | FO | Faroe Islands | 298 | | EUR | Euro Member Countries | FI | Finland | 358 | | EUR | Euro Member Countries | FR | France | 33 | | EUR | Euro Member Countries | GF | French Guiana | 594 | | EUR | Euro Member Countries | TF | French Southern Territories | 262 | | GEL | Georgian Lari | GE | Georgia | 995 | | EUR | Euro Member Countries | DE | Germany | 49 | | GIP | Gibraltar Pound | GI | Gibraltar | 350 | | EUR | Euro Member Countries | GR | Greece | 30 | | DKK | Denmark Krone | GL | Greenland | 299 | | EUR | Euro Member Countries | GP | Guadeloupe | 590 | | GBP | United Kingdom Pound | GG | Guernsey | 1437 | | EUR | Euro Member Countries | VA | Holy See (Vatican City State) | 379 | | HUF | Hungary Forint | HU | Hungary | 36 | | ISK | Iceland Krona | IS | Iceland | 354 | | EUR | Euro Member Countries | IE | Ireland | 353 | | GBP | United Kingdom Pound | IM | Isle of Man | 44 | | EUR | Euro Member Countries | IT | Italy | 39 | | GBP | United Kingdom Pound | JE | Jersey | 44 | | EUR | Euro Member Countries | LV | Latvia | 371 | | CHF | Switzerland Franc | LI | Liechtenstein | 423 | | LTL | Lithuania Litas | LT | Lithuania | 370 | | EUR | Euro Member Countries | LU | Luxembourg | 352 | | MKD | Macedonia Denar | MK | Macedonia, The Former Yugoslav Republic of | 389 | | EUR | Euro Member Countries | MT | Malta | 356 | | EUR | Euro Member Countries | MQ | Martinique | 596 | | EUR | Euro Member Countries | YT | Mayotte | 262 | | MDL | Moldovan Leu | MD | Moldova, Republic of | 373 | | EUR | Euro Member Countries | MC | Monaco | 377 | | EUR | Euro Member Countries | ME | Montenegro | 382 | | EUR | Euro Member Countries | NL | Netherlands | 31 | | ANG | Dutch Guilder | AN | Netherlands Antilles | 599 | | NOK | Norway Krone | NO | Norway | 47 | | PLN | Poland Zloty | PL | Poland | 48 | | EUR | Euro Member Countries | PT | Portugal | 351 | | EUR | Euro Member Countries | RE | Reunion | 262 | | RON | Romania New Leu | RO | Romania | 40 | | EUR | Euro Member Countries | PM | Saint Pierre and Miquelon | 508 | | EUR | Euro Member Countries | SM | San Marino | 378 | | RSD | Serbian dinar | RS | Serbia | 381 | | EUR | Euro Member Countries | ES | Spain | 34 | | EUR | Euro Member Countries | SK | Slovakia | 421 | | EUR | Euro Member Countries | SI | Slovenia | 386 | | NOK | Norway Krone | SJ | Svalbard and Jan Mayen | 47 | | SEK | Sweden Krona | SE | Sweden | 46 | | CHF | Switzerland Franc | CH | Switzerland | 41 | | UAH | Ukraine Hryvna | UA | Ukraine | 380 | | GBP | United Kingdom Pound | GB | United Kingdom | 44 | ## Island territories | Currency code | Currency name | ISO2 name | Country name | Phone code | | :------------ | :------------------------------------- | :-------- | :------------------------------------------- | :--------- | | | | AQ | Antarctica | 672 | | USD | United States Dollar | AS | American Samoa | 648 | | USD | United States Dollar | IO | British Indian Ocean Territory | 246 | | FJD | Fiji Dollar | FJ | Fiji | 679 | | XPF | CFP Franc | PF | French Polynesia | 689 | | USD | United States Dollar | GU | Guam | 1 | | USD | United States Dollar | FM | Micronesia, Federated States of | 691 | | USD | United States Dollar | MP | Northern Mariana Islands | 1 | | USD | United States Dollar | PW | Palau | 680 | | SHP | Saint Helena Pound | SH | Saint Helena | 290 | | WST | Samoan Tala | WS | Samoa | 685 | | STD | Sao Tome and Principe Dobra (pre-2018) | ST | Sao Tome and Principe | 239 | | GBP | United Kingdom Pound | GS | South Georgia and the South Sandwich Islands | 500 | ## Middle East | Currency code | Currency name | ISO2 name | Country name | Phone code | | :------------ | :-------------------------- | :-------- | :------------------------------ | :--------- | | AFN | Afghanistan Afghani | AF | Afghanistan | 93 | | AZN | Azerbaijan New Manat | AZ | Azerbaijan | 994 | | BHD | Bahraini Dinar | BH | Bahrain | 973 | | IRR | Iran Rial | IR | Iran, Islamic Republic Of | 98 | | IQD | Iraqi Dinar | IQ | Iraq | 964 | | ILS | Israel Shekel | IL | Israel | 972 | | JOD | Jordanian Dinar | JO | Jordan | 962 | | KZT | Kazakhstan Tenge | KZ | Kazakhstan | 7 | | KWD | Kuwaiti Dinar | KW | Kuwait | 965 | | KGS | Kyrgyzstan Som | KG | Kyrgyzstan | 996 | | LBP | Lebanon Pound | LB | Lebanon | 961 | | OMR | Oman Rial | OM | Oman | 968 | | PKR | Pakistan Rupee | PK | Pakistan | 92 | | ILS | Israel Shekel | PS | Palestinian Territory, Occupied | 970 | | QAR | Qatar Riyal | QA | Qatar | 974 | | SAR | Saudi Arabia Riyal | SA | Saudi Arabia | 966 | | SYP | Syria Pound | SY | Syrian Arab Republic | 963 | | TJS | Tajikistani Somoni | TJ | Tajikistan | 992 | | TRY | Turkey Lira | TR | Turkey | 90 | | TMT | Turkmenistani Manat | TM | Turkmenistan | 993 | | AED | United Arab Emirates Dirham | AE | United Arab Emirates | 971 | | UZS | Uzbekistani Som | UZ | Uzbekistan | 998 | | YER | Yemen Rial | YE | Yemen | 967 | ## North America and Central America | Currency code | Currency name | ISO2 name | Country name | Phone code | | :------------ | :------------------- | :-------- | :----------------------------------- | :--------- | | BZD | Belize Dollar | BZ | Belize | 501 | | CAD | Canada Dollar | CA | Canada | 1 | | CRC | Costa Rica Colon | CR | Costa Rica | 506 | | USD | United States Dollar | SV | El Salvador | 503 | | GTQ | Guatemala Quetzal | GT | Guatemala | 502 | | HNL | Honduras Lempira | HN | Honduras | 504 | | MXN | Mexico Peso | MX | Mexico | 52 | | NIO | Nicaragua Cordoba | NI | Nicaragua | 505 | | PAB | Panama Balboa | PA | Panama | 507 | | USD | United States Dollar | US | United States | 1 | | USD | United States Dollar | UM | United States Minor Outlying Islands | 1 | ## South America | Currency Code | Currency Name | ISO2 Name | Country Name | Phone Code | | :------------ | :------------------- | :-------- | :----------- | :--------- | | ARS | Argentina Peso | AR | Argentina | 54 | | BOB | Bolivia Boliviano | BO | Bolivia | 591 | | BRL | Brazil Real | BR | Brazil | 55 | | CLP | Chile Peso | CL | Chile | 56 | | COP | Colombia Peso | CO | Colombia | 57 | | USD | United States Dollar | EC | Ecuador | 593 | | GYD | Guyana Dollar | GY | Guyana | 592 | | PYG | Paraguay Guarani | PY | Paraguay | 595 | | PEN | Peru Nuevo Sol | PE | Peru | 51 | | SRD | Suriname Dollar | SR | Suriname | 597 | | UYU | Uruguay Peso | UY | Uruguay | 598 | | VEF | Venezuela Bolivar | VE | Venezuela | 58 | --- # Status Page URL: https://docs.nium.com/docs/getting-started/nium-status-page The Nium Status page provides real-time updates on the operational status of Nium's different services. You can use this page to monitor the availability and performance of key Nium components, ensuring transparency and timely information regarding any issues that may impact you or your customer's experience with Nium's services. The [Nium Status page](https://status.nium.com/) provides real-time updates on the operational status of Nium's different services. You can use this page to monitor the availability and performance of key Nium components, ensuring transparency and timely information regarding any issues that may impact you or your customer's experience with Nium's services. Status Page ## System Statuses All systems aim to ensure uninterrupted access to Nium’s services. The table below provides an overview of the key services available on the Nium platform. Each service is designed to enhance your experience by offering reliable and efficient solutions for your financial needs. Please note, this page only reflects the status of Nium’s services. It does not reflect the availability of any third-party partners that Nium may use. Please reach out to your Nium account manager or [Nium support](mailto:support@nium.com) for additional service updates. | Service | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Nium Portal** | The main frontend component to access Nium's platform, providing tools and resources for account and fund management. | | **Payouts** | Enables users to send payments globally, supporting multiple currencies and payment methods. | | **Payins** | Allows clients to receive payments from various sources, facilitating easy and efficient fund collection. | | **Customer Onboarding** | Supports registration and verification of new customers, ensuring compliance and smooth onboarding. | | **Issuance and Cards** | Manages the issuance of virtual and physical cards, including customization and transaction tracking. | | **FX** (Foreign Exchange) | Provides competitive foreign exchange rates and supports currency conversion for global transactions. | | **Reports** | Generates detailed reports on transactions, balances, and other financial activities for analysis. | ## Incident History The status page also allows you to view historical incidents, offering insights into the stability and reliability of Nium services over time. To explore past incidents or to check on the performance of specific services in the last 60 days, click **Incident History**. This feature is useful for tracking any service disruptions or performance issues that have been resolved. ## Subscribe to Updates To ensure you are always informed about any changes, incidents, or updates regarding Nium's services, you can subscribe to updates directly from the status page. By entering your email address, you will receive notifications whenever Nium creates, updates, or resolves an incident. To subscribe to updates click **Subscribe to Updates** and enter your email address. ## Nium Support If you experience any issues not reflected on the status page, or if you need further assistance, please contact [Nium support](mailto:support@nium.com). Our team is ready to help ensure a smooth and reliable experience with all Nium services. --- # Playbook URL: https://docs.nium.com/docs/getting-started/nium-playbook The Nium Playbook is your go-to guide for understanding how to send and receive payments globally using Nium’s network. Whether you're a business looking to streamline payouts, accept funds, or operate as a financial institution, the playbook provides all the essential details to navigate Nium’s payment solutions effectively. The [Nium Playbook](https://playbook.nium.com/) is your go-to guide for understanding how to send and receive payments globally using Nium’s network. Whether you're a business looking to streamline payouts, accept funds, or operate as a financial institution, the playbook provides all the essential details to navigate Nium’s payment solutions effectively. The Playbook provides detailed insights into payout and payin capabilities across different regions, supported payment methods, and regulatory considerations. - Clarity & Transparency: Get clear, structured information about payout and payin options. - Efficiency: Quickly find the right payment method for your needs. - Up-to-Date Information: Access real-time updates on new capabilities and changes. The Playbook is divided into two sections: ## Payouts Guides users on sending money globally through Nium’s network. You can explore: - Supported payout methods (e.g., bank transfers, cards, wallets) - Country-specific requirements - Processing times and settlement details The [Payouts Playbook](https://playbook.nium.com/) is available on our Playbook site. - Use the filters to find payout options for a specific country or payment method. - Review the eligibility criteria and processing details. ## Payins Explains how to receive payments using Nium’s network. It covers: - Available payin methods by country - Account funding options - Compliance and regulatory considerations The [Payins Playbook](https://playbook.nium.com/payins) is available on our Playbook site. - Search for a country or method to see available payin options. - Understand the settlement timelines and requirements for accepting funds. - A [User Guide](https://playbook.nium.com/payins/user-guide) is also available to help you use the Payins Playbook. ## Additional resources These resources complement the Playbook and help you stay up to date: ### Financial institutions This portion of the playbook is tailored for banks, money service businesses, and fintechs that want to use Nium’s network to send money. A Playbook dedicated to financial institutions can be found on our Playbook site: [Financial institutions Playbook](https://playbook.nium.com/financial-institutions). - Identify the most suitable payout methods for your institution - Click the **Data for Financial Institutions** toggle in the top-right to quickly review how details change. ### Changelog Track updates to Nium’s global payment capabilities. The changelog includes new country support, added payout methods, regulatory changes, and other product enhancements. - Visit the [Changelog](https://playbook.nium.com/) to see the latest updates. - Check it regularly to stay ahead of changes that may impact your payment flows. ### PDF Download Prefer working offline? The payouts Playbook is available as a downloadable PDF. Go to the Playbook homepage and click **Download PDF** to get the latest version. --- # Supported Countries URL: https://docs.nium.com/docs/getting-started/supported-countries Learn the different countries you can send money to using Nium. Send money globally using Nium. Our platform supports payouts to over 190 countries through multiple methods, including local bank transfers, mobile wallets, Visa Direct, and SWIFT wire transfers. Whether you're a business managing supplier payments (B2B), or a fintech platform offering personal transfers (P2P), this guide covers everything you need to know about the different payment options avilable to you through Nium.. Use this guide to: - Check if Nium supports payouts or payins to your destination country. - Review the currencies and payout methods available. - Confirm delivery timelines and transaction limits. For more detailed information, see the [Nium Playbook](https://playbook.nium.com/). This guide applies to Nium customers. For details about Masspay, see [Masspay](https://mpdocs.nium.com/). ## Financial Institutions If you're a bank, credit union, fintech company, or other regulated financial institution, there are additional capabilities and/or regulatory requirements specific to your business. Please review this guide carefully to understand differences such as: - Differences in supported payout rails. - Specific transaction limits or cut-off times. - Available payment methods and expected delivery times. Contact your Nium representative for detailed guidance tailored to financial institutions. ### Where can I send money with Nium? The following tables breakdown where [**Payouts**](/docs/payouts) are supported for *financial* institutions, and which currencies can be used at that location. Each country listing includes: - Supported payout methods - Available currencies - Use cases (B2B, P2P, etc.) - Delivery time and cut-off - Limits (min/max) - Link to full country details #### Africa Africa ##### Bank Account (ACH) - [Algeria](https://playbook.nium.com/country/algeria/institutions) - [Benin](https://playbook.nium.com/country/benin/institutions) - [Egypt](https://playbook.nium.com/country/egypt/institutions) - [Ghana](https://playbook.nium.com/country/ghana/institutions) - [Burkina Faso](https://playbook.nium.com/country/burkina-faso/institutions) - [Cameroon](https://playbook.nium.com/country/cameroon/institutions) - [Senegal](https://playbook.nium.com/country/senegal/institutions) - [Togo](https://playbook.nium.com/country/togo/institutions) - [Guinea](https://playbook.nium.com/country/guinea/institutions) - [Kenya](https://playbook.nium.com/country/kenya/institutions) - [Morocco](https://playbook.nium.com/country/morocco/institutions) - [Mozambique](https://playbook.nium.com/country/mozambique/institutions) - [Namibia](https://playbook.nium.com/country/namibia/institutions) - [Nigeria](https://playbook.nium.com/country/nigeria/institutions) - [Rwanda](https://playbook.nium.com/country/rwanda/institutions) - [Uganda](https://playbook.nium.com/country/uganda/institutions) - [Botswana](https://playbook.nium.com/country/botswana/institutions) - [Burundi](https://playbook.nium.com/country/burundi/institutions) - [Cape Verde](https://playbook.nium.com/country/cape-verde/institutions) - [Chad](https://playbook.nium.com/country/chad/institutions) - [Comoros](https://playbook.nium.com/country/comoros/institutions) - [Djibouti](https://playbook.nium.com/country/djibouti/institutions) - [Equatorial Guinea](https://playbook.nium.com/country/equatorial-guinea/institutions) - [Eritrea](https://playbook.nium.com/country/eritrea/institutions) ##### Wallet - [Algeria](https://playbook.nium.com/country/algeria/institutions) - [Egypt](https://playbook.nium.com/country/egypt/institutions) - [Ghana](https://playbook.nium.com/country/ghana/institutions) - [Cameroon](https://playbook.nium.com/country/cameroon/institutions) - [Senegal](https://playbook.nium.com/country/senegal/institutions) - [Ivory Coast](https://playbook.nium.com/country/ivory-coast/institutions) - [Ghana](https://playbook.nium.com/country/ghana/institutions) - [Nigeria](https://playbook.nium.com/country/nigeria/institutions) - [Uganda](https://playbook.nium.com/country/uganda/institutions) - [Chad](https://playbook.nium.com/country/chad/institutions) - [Gambia](https://playbook.nium.com/country/gambia/institutions) ##### SWIFT - [Algeria](https://playbook.nium.com/country/algeria/institutions) - [Angola](https://playbook.nium.com/country/angola/institutions) - [Benin](https://playbook.nium.com/country/benin/institutions) - [Egypt](https://playbook.nium.com/country/egypt/institutions) - [Ghana](https://playbook.nium.com/country/ghana/institutions) - [Burkina Faso](https://playbook.nium.com/country/burkina-faso/institutions) - [Cameroon](https://playbook.nium.com/country/cameroon/institutions) - [Senegal](https://playbook.nium.com/country/senegal/institutions) - [Togo](https://playbook.nium.com/country/togo/institutions) - [Ivory Coast](https://playbook.nium.com/country/ivory-coast/institutions) - [Guinea](https://playbook.nium.com/country/guinea/institutions) - [Kenya](https://playbook.nium.com/country/kenya/institutions) - [Morocco](https://playbook.nium.com/country/morocco/institutions) - [Mozambique](https://playbook.nium.com/country/mozambique/institutions) - [Namibia](https://playbook.nium.com/country/namibia/institutions) - [Nigeria](https://playbook.nium.com/country/nigeria/institutions) - [Rwanda](https://playbook.nium.com/country/rwanda/institutions) - [Uganda](https://playbook.nium.com/country/uganda/institutions) - [Lesotho](https://playbook.nium.com/country/lesotho/institutions) - [Liberia](https://playbook.nium.com/country/liberia/institutions) - [Mauritania](https://playbook.nium.com/country/mauritania/institutions) - [Mauritius](https://playbook.nium.com/country/mauritius/institutions) - [Sierra Leone](https://playbook.nium.com/country/sierra-leone/institutions) - [South Africa](https://playbook.nium.com/country/south-africa/institutions) - [Zambia](https://playbook.nium.com/country/zambia/institutions) - [Republic of the Congo](https://playbook.nium.com/country/republic-of-the-congo/institutions) - [Reunion](https://playbook.nium.com/country/reunion/institutions) - [Sao Tome and Principe](https://playbook.nium.com/country/sao-tome-and-principe/institutions) - [Seychelles](https://playbook.nium.com/country/seychelles/institutions) - [Swaziland](https://playbook.nium.com/country/eswatini/institutions) - [Tanzania](https://playbook.nium.com/country/tanzania/institutions) - [Tunisia](https://playbook.nium.com/country/tunisia/institutions) - [Western Sahara](https://playbook.nium.com/country/western-sahara/institutions) - [Zimbabwe](https://playbook.nium.com/country/zimbabwe/institutions) ##### Visa Direct - [Algeria](https://playbook.nium.com/country/algeria/institutions) - [Angola](https://playbook.nium.com/country/angola/institutions) - [Benin](https://playbook.nium.com/country/benin/institutions) - [Egypt](https://playbook.nium.com/country/egypt/institutions) - [Ghana](https://playbook.nium.com/country/ghana/institutions) - [Burkina Faso](https://playbook.nium.com/country/burkina-faso/institutions) - [Cameroon](https://playbook.nium.com/country/cameroon/institutions) - [Senegal](https://playbook.nium.com/country/senegal/institutions) - [Ivory Coast](https://playbook.nium.com/country/ivory-coast/institutions) - [Guinea](https://playbook.nium.com/country/guinea/institutions) - [Kenya](https://playbook.nium.com/country/kenya/institutions) - [Morocco](https://playbook.nium.com/country/morocco/institutions) - [Nigeria](https://playbook.nium.com/country/nigeria/institutions) - [Uganda](https://playbook.nium.com/country/uganda/institutions) - [Zambia](https://playbook.nium.com/country/zambia/institutions) - [Lesotho](https://playbook.nium.com/country/lesotho/institutions) - [Liberia](https://playbook.nium.com/country/liberia/institutions) - [Madagascar](https://playbook.nium.com/country/madagascar/institutions) - [Malawi](https://playbook.nium.com/country/malawi/institutions) - [Sao Tome and Principe](https://playbook.nium.com/country/sao-tome-and-principe/institutions) - [Seychelles](https://playbook.nium.com/country/seychelles/institutions) - [Swaziland](https://playbook.nium.com/country/eswatini/institutions) - [Zambia](https://playbook.nium.com/country/zambia/institutions) #### Asia Asia ##### Bank Account (ACH) - [Bangladesh](https://playbook.nium.com/country/bangladesh/institutions) - [Guam](https://playbook.nium.com/country/guam/institutions) - [Hong Kong](https://playbook.nium.com/country/hong-kong/institutions) - [Hong Kong](https://playbook.nium.com/country/hong-kong/institutions) - [India](https://playbook.nium.com/country/india/institutions) - [Indonesia](https://playbook.nium.com/country/indonesia/institutions) - [Israel](https://playbook.nium.com/country/israel/institutions) - [Nepal](https://playbook.nium.com/country/nepal/institutions) - [Pakistan](https://playbook.nium.com/country/pakistan/institutions) - [Saudi Arabia](https://playbook.nium.com/country/saudi-arabia/institutions) - [South Korea](https://playbook.nium.com/country/south-korea/institutions) - [Thailand](https://playbook.nium.com/country/thailand/institutions) - [United Arab Emirates](https://playbook.nium.com/country/united-arab-emirates/institutions) - [Vietnam](https://playbook.nium.com/country/vietnam/institutions) ##### Bank Account (Other) - [Japan](https://playbook.nium.com/country/japan/institutions) - [Malaysia](https://playbook.nium.com/country/malaysia/institutions) - [Philippines](https://playbook.nium.com/country/philippines/institutions) - [Singapore](https://playbook.nium.com/country/singapore/institutions) - [Sri Lanka](https://playbook.nium.com/country/sri-lanka/institutions) ##### Local Currency Wire Transfer - [China](https://playbook.nium.com/country/china/institutions) - [India](https://playbook.nium.com/country/india/institutions) - [Saudi Arabia](https://playbook.nium.com/country/saudi-arabia/institutions) - [United Arab Emirates](https://playbook.nium.com/country/united-arab-emirates/institutions) - [Vietnam](https://playbook.nium.com/country/vietnam/institutions) ##### Proxy - [China](https://playbook.nium.com/country/china/institutions) - [Hong Kong](https://playbook.nium.com/country/hong-kong/institutions) - [India](https://playbook.nium.com/country/india/institutions) ##### SWIFT - [Armenia](https://playbook.nium.com/country/armenia/institutions) - [Bahrain](https://playbook.nium.com/country/bahrain/institutions) - [Bangladesh](https://playbook.nium.com/country/bangladesh/institutions) - [Bhutan](https://playbook.nium.com/country/bhutan/institutions) - [Brunei](https://playbook.nium.com/country/brunei/institutions) - [Cambodia](https://playbook.nium.com/country/cambodia/institutions) - [China](https://playbook.nium.com/country/china/institutions) - [Christmas Island](https://playbook.nium.com/country/christmas-island/institutions) - [Cocos (Keeling)](https://playbook.nium.com/country/cocos-keeling-islands/institutions) - [Timor-Leste](https://playbook.nium.com/country/timor-leste/institutions) - [Diego Garcia](https://playbook.nium.com/country/diego-garcia/institutions) - [Georgia](https://playbook.nium.com/country/georgia/institutions) - [Guam](https://playbook.nium.com/country/guam/institutions) - [Hong Kong](https://playbook.nium.com/country/hong-kong/institutions) - [India](https://playbook.nium.com/country/india/institutions) - [Indonesia](https://playbook.nium.com/country/indonesia/institutions) - [Israel](https://playbook.nium.com/country/israel/institutions) - [Japan](https://playbook.nium.com/country/japan/institutions) - [Jordan](https://playbook.nium.com/country/jordan/institutions) - [Kazakhstan](https://playbook.nium.com/country/kazakhstan/institutions) - [Kuwait](https://playbook.nium.com/country/kuwait/institutions) - [Kyrgyzstan](https://playbook.nium.com/country/kyrgyzstan/institutions) - [Laos](https://playbook.nium.com/country/laos/institutions) - [Malaysia](https://playbook.nium.com/country/malaysia/institutions) - [Maldives](https://playbook.nium.com/country/maldives/institutions) - [Mongolia](https://playbook.nium.com/country/mongolia/institutions) - [Nepal](https://playbook.nium.com/country/nepal/institutions) - [Oman](https://playbook.nium.com/country/oman/institutions) - [Pakistan](https://playbook.nium.com/country/pakistan/institutions) - [Palestine](https://playbook.nium.com/country/palestine/institutions) - [Philippines](https://playbook.nium.com/country/philippines/institutions) - [Qatar](https://playbook.nium.com/country/qatar/institutions) - [Saudi Arabia](https://playbook.nium.com/country/saudi-arabia/institutions) - [Singapore](https://playbook.nium.com/country/singapore/institutions) - [South Korea](https://playbook.nium.com/country/south-korea/institutions) - [Sri Lanka](https://playbook.nium.com/country/sri-lanka/institutions) - [Taiwan](https://playbook.nium.com/country/taiwan/institutions) - [Tajikistan](https://playbook.nium.com/country/tajikistan/institutions) - [Thailand](https://playbook.nium.com/country/thailand/institutions) - [Turkmenistan](https://playbook.nium.com/country/turkmenistan/institutions) - [United Arab Emirates](https://playbook.nium.com/country/united-arab-emirates/institutions) - [Uzbekistan](https://playbook.nium.com/country/uzbekistan/institutions) - [Vietnam](https://playbook.nium.com/country/vietnam/institutions) ##### Visa Direct - [Armenia](https://playbook.nium.com/country/armenia/institutions) - [Bahrain](https://playbook.nium.com/country/bahrain/institutions) - [Bangladesh](https://playbook.nium.com/country/bangladesh/institutions) - [Brunei](https://playbook.nium.com/country/brunei/institutions) - [Cambodia](https://playbook.nium.com/country/cambodia/institutions) - [China](https://playbook.nium.com/country/china/institutions) - [Georgia](https://playbook.nium.com/country/georgia/institutions) - [Guam](https://playbook.nium.com/country/guam/institutions) - [India](https://playbook.nium.com/country/india/institutions) - [Indonesia](https://playbook.nium.com/country/indonesia/institutions) - [Kazakhstan](https://playbook.nium.com/country/kazakhstan/institutions) - [Malaysia](https://playbook.nium.com/country/malaysia/institutions) - [Philippines](https://playbook.nium.com/country/philippines/institutions) - [Thailand](https://playbook.nium.com/country/thailand/institutions) - [Turkmenistan](https://playbook.nium.com/country/turkmenistan/institutions) - [United Arab Emirates](https://playbook.nium.com/country/united-arab-emirates/institutions) - [Uzbekistan](https://playbook.nium.com/country/uzbekistan/institutions) - [Vietnam](https://playbook.nium.com/country/vietnam/institutions) ##### Wallet - [Bangladesh](https://playbook.nium.com/country/bangladesh/institutions) - [China](https://playbook.nium.com/country/china/institutions) - [Indonesia](https://playbook.nium.com/country/indonesia/institutions) #### Europe Europe ##### Bank Account (ACH) - [Bailiwick of Guernsey](https://playbook.nium.com/country/bailiwick-of-guernsey/institutions) - [Bulgaria](https://playbook.nium.com/country/bulgaria/institutions) - [Czech Republic](https://playbook.nium.com/country/czech-republic/institutions) - [Denmark](https://playbook.nium.com/country/denmark/institutions) - [Gibraltar](https://playbook.nium.com/country/gibraltar/institutions) - [Hungary](https://playbook.nium.com/country/hungary/institutions) - [Iceland](https://playbook.nium.com/country/iceland/institutions) - [Isle of Man](https://playbook.nium.com/country/isle-of-man/institutions) - [Jersey](https://playbook.nium.com/country/jersey/institutions) - [Macedonia](https://playbook.nium.com/country/macedonia/institutions) - [Moldova](https://playbook.nium.com/country/moldova/institutions) - [Norway](https://playbook.nium.com/country/norway/institutions) - [Poland](https://playbook.nium.com/country/poland/institutions) - [Romania](https://playbook.nium.com/country/romania/institutions) - [Serbia](https://playbook.nium.com/country/serbia/institutions) - [Sweden](https://playbook.nium.com/country/sweden/institutions) - [Switzerland](https://playbook.nium.com/country/switzerland/institutions) - [Turkey](https://playbook.nium.com/country/turkey/institutions) - [Ukraine](https://playbook.nium.com/country/ukraine/institutions) - [United Kingdom](https://playbook.nium.com/country/united-kingdom/institutions) ##### SEPA - [Aland Islands](https://playbook.nium.com/country/aland-islands/institutions) - [Albania](https://playbook.nium.com/country/albania/institutions) - [Andorra](https://playbook.nium.com/country/andorra/institutions) - [Austria](https://playbook.nium.com/country/austria/institutions) - [Azerbaijan](https://playbook.nium.com/country/azerbaijan/institutions) - [Bailiwick of Guernsey](https://playbook.nium.com/country/bailiwick-of-guernsey/institutions) - [Belgium](https://playbook.nium.com/country/belgium/institutions) - [Bulgaria](https://playbook.nium.com/country/bulgaria/institutions) - [Croatia (Hrvatska)](https://playbook.nium.com/country/croatia-hrvatska/institutions) - [Cyprus](https://playbook.nium.com/country/cyprus/institutions) - [Czech Republic](https://playbook.nium.com/country/czech-republic/institutions) - [Denmark](https://playbook.nium.com/country/denmark/institutions) - [Estonia](https://playbook.nium.com/country/estonia/institutions) - [Finland](https://playbook.nium.com/country/finland/institutions) - [France](https://playbook.nium.com/country/france/institutions) - [Germany](https://playbook.nium.com/country/germany/institutions) - [Gibraltar](https://playbook.nium.com/country/gibraltar/institutions) - [Greece](https://playbook.nium.com/country/greece/institutions) - [Hungary](https://playbook.nium.com/country/hungary/institutions) - [Iceland](https://playbook.nium.com/country/iceland/institutions) - [Ireland](https://playbook.nium.com/country/ireland/institutions) - [Isle of Man](https://playbook.nium.com/country/isle-of-man/institutions) - [Italy](https://playbook.nium.com/country/italy/institutions) - [Jersey](https://playbook.nium.com/country/jersey/institutions) - [Kosovo](https://playbook.nium.com/country/kosovo/institutions) - [Latvia](https://playbook.nium.com/country/latvia/institutions) - [Liechtenstein](https://playbook.nium.com/country/liechtenstein/institutions) - [Lithuania](https://playbook.nium.com/country/lithuania/institutions) - [Luxembourg](https://playbook.nium.com/country/luxembourg/institutions) - [Macedonia](https://playbook.nium.com/country/macedonia/institutions) - [Malta](https://playbook.nium.com/country/malta/institutions) - [Moldova](https://playbook.nium.com/country/moldova/institutions) - [Monaco](https://playbook.nium.com/country/monaco/institutions) - [Montenegro](https://playbook.nium.com/country/montenegro/institutions) - [Netherlands](https://playbook.nium.com/country/netherlands/institutions) - [Norway](https://playbook.nium.com/country/norway/institutions) - [Poland](https://playbook.nium.com/country/poland/institutions) - [Portugal](https://playbook.nium.com/country/portugal/institutions) - [Romania](https://playbook.nium.com/country/romania/institutions) - [San Marino](https://playbook.nium.com/country/san-marino/institutions) - [Serbia](https://playbook.nium.com/country/serbia/institutions) - [Slovakia](https://playbook.nium.com/country/slovakia/institutions) - [Slovenia](https://playbook.nium.com/country/slovenia/institutions) - [Spain](https://playbook.nium.com/country/spain/institutions) - [Svalbard and Jan Mayen Islands](https://playbook.nium.com/country/svalbard-and-jan-mayen-islands/institutions) - [Sweden](https://playbook.nium.com/country/sweden/institutions) - [Switzerland](https://playbook.nium.com/country/switzerland/institutions) - [United Kingdom](https://playbook.nium.com/country/united-kingdom/institutions) - [Vatican City State](https://playbook.nium.com/country/vatican-city-state/institutions) ##### SWIFT - [Aland Islands](https://playbook.nium.com/country/aland-islands/institutions) - [Albania](https://playbook.nium.com/country/albania/institutions) - [Andorra](https://playbook.nium.com/country/andorra/institutions) - [Austria](https://playbook.nium.com/country/austria/institutions) - [Azerbaijan](https://playbook.nium.com/country/azerbaijan/institutions) - [Bailiwick of Guernsey](https://playbook.nium.com/country/bailiwick-of-guernsey/institutions) - [Belgium](https://playbook.nium.com/country/belgium/institutions) - [Bulgaria](https://playbook.nium.com/country/bulgaria/institutions) - [Croatia (Hrvatska)](https://playbook.nium.com/country/croatia-hrvatska/institutions) - [Cyprus](https://playbook.nium.com/country/cyprus/institutions) - [Czech Republic](https://playbook.nium.com/country/czech-republic/institutions) - [Denmark](https://playbook.nium.com/country/denmark/institutions) - [Estonia](https://playbook.nium.com/country/estonia/institutions) - [Finland](https://playbook.nium.com/country/finland/institutions) - [France](https://playbook.nium.com/country/france/institutions) - [Germany](https://playbook.nium.com/country/germany/institutions) - [Gibraltar](https://playbook.nium.com/country/gibraltar/institutions) - [Greece](https://playbook.nium.com/country/greece/institutions) - [Hungary](https://playbook.nium.com/country/hungary/institutions) - [Iceland](https://playbook.nium.com/country/iceland/institutions) - [Ireland](https://playbook.nium.com/country/ireland/institutions) - [Isle of Man](https://playbook.nium.com/country/isle-of-man/institutions) - [Italy](https://playbook.nium.com/country/italy/institutions) - [Jersey](https://playbook.nium.com/country/jersey/institutions) - [Kosovo](https://playbook.nium.com/country/kosovo/institutions) - [Latvia](https://playbook.nium.com/country/latvia/institutions) - [Liechtenstein](https://playbook.nium.com/country/liechtenstein/institutions) - [Lithuania](https://playbook.nium.com/country/lithuania/institutions) - [Luxembourg](https://playbook.nium.com/country/luxembourg/institutions) - [Macedonia](https://playbook.nium.com/country/macedonia/institutions) - [Malta](https://playbook.nium.com/country/malta/institutions) - [Moldova](https://playbook.nium.com/country/moldova/institutions) - [Monaco](https://playbook.nium.com/country/monaco/institutions) - [Montenegro](https://playbook.nium.com/country/montenegro/institutions) - [Netherlands](https://playbook.nium.com/country/netherlands/institutions) - [Norway](https://playbook.nium.com/country/norway/institutions) - [Poland](https://playbook.nium.com/country/poland/institutions) - [Portugal](https://playbook.nium.com/country/portugal/institutions) - [Romania](https://playbook.nium.com/country/romania/institutions) - [San Marino](https://playbook.nium.com/country/san-marino/institutions) - [Serbia](https://playbook.nium.com/country/serbia/institutions) - [Slovakia](https://playbook.nium.com/country/slovakia/institutions) - [Slovenia](https://playbook.nium.com/country/slovenia/institutions) - [Spain](https://playbook.nium.com/country/spain/institutions) - [Svalbard and Jan Mayen Islands](https://playbook.nium.com/country/svalbard-and-jan-mayen-islands/institutions) - [Sweden](https://playbook.nium.com/country/sweden/institutions) - [Switzerland](https://playbook.nium.com/country/switzerland/institutions) - [Turkey](https://playbook.nium.com/country/turkey/institutions) - [Ukraine](https://playbook.nium.com/country/ukraine/institutions) - [United Kingdom](https://playbook.nium.com/country/united-kingdom/institutions) - [Vatican City State](https://playbook.nium.com/country/vatican-city-state/institutions) ##### Visa Direct - [Albania](https://playbook.nium.com/country/albania/institutions) - [Austria](https://playbook.nium.com/country/austria/institutions) - [Azerbaijan](https://playbook.nium.com/country/azerbaijan/institutions) - [Bailiwick of Guernsey](https://playbook.nium.com/country/bailiwick-of-guernsey/institutions) - [Czech Republic](https://playbook.nium.com/country/czech-republic/institutions) - [Denmark](https://playbook.nium.com/country/denmark/institutions) - [Gibraltar](https://playbook.nium.com/country/gibraltar/institutions) - [Hungary](https://playbook.nium.com/country/hungary/institutions) - [Isle of Man](https://playbook.nium.com/country/isle-of-man/institutions) - [Italy](https://playbook.nium.com/country/italy/institutions) - [Jersey](https://playbook.nium.com/country/jersey/institutions) - [Poland](https://playbook.nium.com/country/poland/institutions) - [Sweden](https://playbook.nium.com/country/sweden/institutions) - [Turkey](https://playbook.nium.com/country/turkey/institutions) - [United Kingdom](https://playbook.nium.com/country/united-kingdom/institutions) #### North America North America ##### Bank Account (ACH) - [Canada](https://playbook.nium.com/country/canada/institutions) - [Costa Rica](https://playbook.nium.com/country/costa-rica/institutions) - [Dominican Republic](https://playbook.nium.com/country/dominican-republic/institutions) - [Guatemala](https://playbook.nium.com/country/guatemala/institutions) - [Mexico](https://playbook.nium.com/country/mexico/institutions) - [Puerto Rico](https://playbook.nium.com/country/puerto-rico/institutions) - [United States](https://playbook.nium.com/country/united-states-of-america/institutions) - [Virgin Islands (U.S.)](https://playbook.nium.com/country/virgin-islands-us/institutions) ##### Interac (Canada only) - [Canada](https://playbook.nium.com/country/canada/institutions) ##### SEPA - [Guadeloupe](https://playbook.nium.com/country/guadeloupe/institutions) - [Martinique](https://playbook.nium.com/country/martinique/institutions) - [Saint Martin (French part)](https://playbook.nium.com/country/saint-martin/institutions) ##### SWIFT - [Anguilla](https://playbook.nium.com/country/anguilla/institutions) - [Antigua](https://playbook.nium.com/country/antigua/institutions) - [Aruba](https://playbook.nium.com/country/aruba/institutions) - [Bahamas](https://playbook.nium.com/country/bahamas/institutions) - [Barbados](https://playbook.nium.com/country/barbados/institutions) - [Belize](https://playbook.nium.com/country/belize/institutions) - [Bermuda](https://playbook.nium.com/country/bermuda/institutions) - [Bonaire, Sint Eustatius & Saba](https://playbook.nium.com/country/carib-beh/institutions) - [British Virgin Islands](https://playbook.nium.com/country/british-virgin-islands/institutions) - [Canada](https://playbook.nium.com/country/canada/institutions) - [Caribbean Netherlands](https://playbook.nium.com/country/carib-nld/institutions) - [Cayman Islands](https://playbook.nium.com/country/cayman-islands/institutions) - [Costa Rica](https://playbook.nium.com/country/costa-rica/institutions) - [Dominica](https://playbook.nium.com/country/dominica/institutions) - [Dominican Republic](https://playbook.nium.com/country/dominican-republic/institutions) - [El Salvador](https://playbook.nium.com/country/el-salvador/institutions) - [Greenland](https://playbook.nium.com/country/greenland/institutions) - [Grenada](https://playbook.nium.com/country/grenada/institutions) - [Guatemala](https://playbook.nium.com/country/guatemala/institutions) - [Haiti](https://playbook.nium.com/country/haiti/institutions) - [Honduras](https://playbook.nium.com/country/honduras/institutions) - [Jamaica](https://playbook.nium.com/country/jamaica/institutions) - [Martinique](https://playbook.nium.com/country/martinique/institutions) - [Mexico](https://playbook.nium.com/country/mexico/institutions) - [Montserrat](https://playbook.nium.com/country/montserrat/institutions) - [Nicaragua](https://playbook.nium.com/country/nicaragua/institutions) - [Panama](https://playbook.nium.com/country/panama/institutions) - [Puerto Rico](https://playbook.nium.com/country/puerto-rico/institutions) - [Saint Kitts and Nevis](https://playbook.nium.com/country/saint-kitts-and-nevis/institutions) - [Saint Lucia](https://playbook.nium.com/country/saint-lucia/institutions) - [Saint Martin (French part)](https://playbook.nium.com/country/saint-martin/institutions) - [Saint Vincent & the Grenadines](https://playbook.nium.com/country/saint-vincent-and-the-grenadines/institutions) - [Sint Maarten (Dutch part)](https://playbook.nium.com/country/sint-maarten/institutions) - [Trinidad & Tobago](https://playbook.nium.com/country/trinidad-and-tobago/institutions) - [Turks & Caicos Islands](https://playbook.nium.com/country/turks-and-caicos-islands/institutions) - [United States](https://playbook.nium.com/country/united-states-of-america/institutions) - [Virgin Islands (US)](https://playbook.nium.com/country/virgin-islands-usa/institutions) - [U.S. Minor Outlying Islands](https://playbook.nium.com/country/united-states-minor-outlying-islands/institutions) ##### Visa Direct - [Bahamas](https://playbook.nium.com/country/bahamas/institutions) - [Dominica](https://playbook.nium.com/country/dominica/institutions) - [Dominican Republic](https://playbook.nium.com/country/dominican-republic/institutions) - [Guatemala](https://playbook.nium.com/country/guatemala/institutions) - [Honduras](https://playbook.nium.com/country/honduras/institutions) #### South America South America ##### Bank Account (ACH) - [Argentina](https://playbook.nium.com/country/argentina/institutions) - [Bolivia](https://playbook.nium.com/country/bolivia/institutions) - [Brazil](https://playbook.nium.com/country/brazil/institutions) - [Chile](https://playbook.nium.com/country/chile/institutions) - [Colombia](https://playbook.nium.com/country/colombia/institutions) - [Peru](https://playbook.nium.com/country/peru/institutions) - [Uruguay](https://playbook.nium.com/country/uruguay/institutions) ##### Proxy - [Brazil](https://playbook.nium.com/country/brazil/institutions) ##### SWIFT - [Argentina](https://playbook.nium.com/country/argentina/institutions) - [Bolivia](https://playbook.nium.com/country/bolivia/institutions) - [Brazil](https://playbook.nium.com/country/brazil/institutions) - [Chile](https://playbook.nium.com/country/chile/institutions) - [Colombia](https://playbook.nium.com/country/colombia/institutions) - [Curaçao](https://playbook.nium.com/country/curacao) - [Ecuador](https://playbook.nium.com/country/ecuador/institutions) - [Falkland Islands (Malvinas)](https://playbook.nium.com/country/falkland-islands-malvinas/institutions) - [French Guiana](https://playbook.nium.com/country/french-guiana/institutions) - [Guyana](https://playbook.nium.com/country/guyana/institutions) - [Paraguay](https://playbook.nium.com/country/paraguay/institutions) - [Peru](https://playbook.nium.com/country/peru/institutions) - [Suriname](https://playbook.nium.com/country/suriname/institutions) - [Uruguay](https://playbook.nium.com/country/uruguay/institutions) - [Venezuela](https://playbook.nium.com/country/venezuela/institutions) #### Oceania Oceania ##### Bank Account (ACH) - [American Samoa](https://playbook.nium.com/country/american-samoa/institutions) - [Australia](https://playbook.nium.com/country/australia/institutions) - [Guam](https://playbook.nium.com/country/guam/institutions) - [Northern Marina Islands](https://playbook.nium.com/country/northern-mariana-islands/institutions) ##### Proxy - [Australia](https://playbook.nium.com/country/australia/institutions) ##### SWIFT - [American Samoa](https://playbook.nium.com/country/american-samoa/institutions) - [Antarctica](https://playbook.nium.com/country/antarctica/institutions) - [Australia](https://playbook.nium.com/country/australia/institutions) - [Bouvet Island](https://playbook.nium.com/country/bouvet-island/institutions) - [Cook Islands](https://playbook.nium.com/country/cook-islands/institutions) - [Fiji](https://playbook.nium.com/country/fiji/institutions) - [Guam](https://playbook.nium.com/country/guam/institutions) - [French Polynesia](https://playbook.nium.com/country/french-polynesia/institutions) - [French Southern Territories](https://playbook.nium.com/country/french-southern-territories/institutions) - [Heard and Mc Donald Islands](https://playbook.nium.com/country/heard-and-mc-donald-islands/institutions) - [Kiribati](https://playbook.nium.com/country/kiribati/institutions) - [Micronesia, Federated States of](https://playbook.nium.com/country/micronesia-federated-states-of/institutions) - [Nauru](https://playbook.nium.com/country/nauru/institutions) - [New Caledonia](https://playbook.nium.com/country/new-caledonia/institutions) - [New Zealand](https://playbook.nium.com/country/new-zealand/institutions) - [Niue](https://playbook.nium.com/country/niue/institutions) - [Norfolk Island](https://playbook.nium.com/country/norfolk-island/institutions) - [Northern Mariana Islands](https://playbook.nium.com/country/northern-mariana-islands/institutions) - [Palau](https://playbook.nium.com/country/palau/institutions) - [Papua New Guinea](https://playbook.nium.com/country/papua-new-guinea/institutions) - [Pitcairn](https://playbook.nium.com/country/pitcairn/institutions) - [Samoa](https://playbook.nium.com/country/samoa/institutions) - [Solomon Islands](https://playbook.nium.com/country/solomon-islands/institutions) - [South Georgia South Sandwich Islands](https://playbook.nium.com/country/south-georgia-south-sandwich-islands/institutions) - [Tokelau](https://playbook.nium.com/country/tokelau/institutions) - [Tonga](https://playbook.nium.com/country/tonga/institutions) - [Tuvalu](https://playbook.nium.com/country/tuvalu/institutions) - [Vanuatu](https://playbook.nium.com/country/vanuatu/institutions) - [Wallis and Futuna Islands](https://playbook.nium.com/country/wallis-and-futuna-islands/institutions) ##### Visa Direct - [Fiji](https://playbook.nium.com/country/fiji/institutions) - [Guam](https://playbook.nium.com/country/guam/institutions) - [Papua New Guinea](https://playbook.nium.com/country/papua-new-guinea/institutions) - [Tonga](https://playbook.nium.com/country/tonga/institutions) ### Where can I receive money with Nium? The following breakdown where [**Payins**](/docs/payins) are supported for *financial* institutions,. - When *funding your own account*, the customer cannot be located in the US or the countries subject to sanctions or restrictions by the US government. - When *accpeting funds from third parties*, the customer cannot be located in the countries that are subject to sanctions or restrictions by US government. #### Africa Africa ##### South Africa - South African Rand - ZAR - [South Africa](https://playbook.nium.com/payin/institutions/ZAR?currencies=ZAR\&payin_service=Funding\&channel=Nium+One) #### Asia ##### China - Chinese Yuan - CNY - [China](https://playbook.nium.com/payin/institutions/CNY?payin_service=Funding\&channel=Nium+One\¤cies=CNY) ##### Hong Kong - Kong Kong Dollar - HKD [Hong Kong](https://playbook.nium.com/payin/institutions/HKD?payin_service=Funding\&channel=Nium+One\¤cies=HKD) ## Israel - Israeli New Shekel - ILS - [Israel](https://playbook.nium.com/payin/institutions/ILS?payin_service=Funding\&channel=Nium+One\¤cies=ILS) ##### Japan - Japanese Yen - JPY - [Japan](https://playbook.nium.com/payin/institutions/JPY?payin_service=Funding\&channel=Nium+One\¤cies=JPY) ##### Philippines - Philippine Peso - PHP - [Philippines](https://playbook.nium.com/payin/institutions/PHP?payin_service=Funding\&channel=Nium+One\¤cies=PHP) ##### Saudi Arabia - Saudi Riyal - SAR [Saudi Arabia](https://playbook.nium.com/payin/institutions/SAR?payin_service=Funding\&channel=Nium+One\¤cies=SAR) ##### Singapore - Singapore Dollar - SGD - [Singapore](https://playbook.nium.com/payin/institutions/SGD?payin_service=Funding\&channel=Nium+One\¤cies=SGD) ##### Thailand - Thai Baht - THB [Thailand](https://playbook.nium.com/payin/institutions/THB?payin_service=Funding\&channel=Nium+One\¤cies=THB) ##### United Arab Emirates - UAE Dirham - UAE - [United Arab Emirates](https://playbook.nium.com/payin/institutions/AED?payin_service=Funding\&channel=Nium+One\¤cies=AED) #### Europe Europe ##### Euro - EUR Please note, for SEPA transactions *under* $100,000: - Expected funds receipt is **Realtime**. - There is no cutoff time and there is 24/7 availability. For SEPA transactions over $100,000: - Expected funds receipt is **T0**. - The amount will be credited to the beneficiary on the sameday *if* funds are received before 14:00 EET. - [Andorra](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Austria](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Belgium](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Bulgaria](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Croatia](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Cyprus](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Czech Republic](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Denmark](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Estonia](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Finland](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [France](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Germany](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Greece](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Holy See (Vatican City State)](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channelNium+One) - [Hungary](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Iceland](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Italy](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Latvia](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Liechtenstein](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Lithuania](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Luxembourg](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Malta](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Monaco](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Netherlands](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Norway](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Poland](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Portugal](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Romania](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [San Marino](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Slovakia](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Slovenia](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Spain](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Sweden](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Switzerland](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Switzerland](https://playbook.nium.com/payin/institutions/CHF?currencies=CHF\&payin_service=Funding\&channel=Nium+One) - [Turkey](https://playbook.nium.com/payin/institutions/TRY?payin_service=Funding\&channel=Nium+One\¤cies=TRY) - [United Kingdom](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Anywhere except the US](https://playbook.nium.com/payin/institutions/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) #### North America North America - [Canada](https://playbook.nium.com/payin/institutions/CAD?payin_service=Funding\&channel=Nium+One\¤cies=CAD) - [Mexico](https://playbook.nium.com/payin/institutions/MXN?payin_service=Funding\&channel=Nium+One\¤cies=MXN) - [United States](https://playbook.nium.com/payin/institutions/USD?payin_service=Funding\&channel=Nium+One\¤cies=USD) #### Oceania Oceania - [Australia](https://playbook.nium.com/payin/institutions/AUD?currencies=AUD\&payin_service=Funding\&channel=Nium+One) - [New Zealand](https://playbook.nium.com/payin/institutions/NZD?payin_service=Funding\&channel=Nium+One\¤cies=NZD) ## Non-Financial Institutions This section applies if your business is **not** a financial institution. Typical examples include e-commerce platforms, marketplaces, apps, payroll providers, etc. ### Where can I send money with Nium? #### Africa Africa ##### Bank Account (ACH) - [Algeria](https://playbook.nium.com/country/algeria) - [Benin](https://playbook.nium.com/country/benin) - [Egypt](https://playbook.nium.com/country/egypt) - [Ghana](https://playbook.nium.com/country/ghana) - [Burkina Faso](https://playbook.nium.com/country/burkina-faso) - [Cameroon](https://playbook.nium.com/country/cameroon) - [Senegal](https://playbook.nium.com/country/senegal) - [Togo](https://playbook.nium.com/country/togo) - [Guinea](https://playbook.nium.com/country/guinea) - [Kenya](https://playbook.nium.com/country/kenya) - [Morocco](https://playbook.nium.com/country/morocco) - [Mozambique](https://playbook.nium.com/country/mozambique) - [Namibia](https://playbook.nium.com/country/namibia) - [Nigeria](https://playbook.nium.com/country/nigeria) - [Rwanda](https://playbook.nium.com/country/rwanda) - [Uganda](https://playbook.nium.com/country/uganda) - [Botswana](https://playbook.nium.com/country/botswana) - [Burundi](https://playbook.nium.com/country/burundi) - [Cape Verde](https://playbook.nium.com/country/cape-verde) - [Chad](https://playbook.nium.com/country/chad) - [Comoros](https://playbook.nium.com/country/comoros) - [Djibouti](https://playbook.nium.com/country/djibouti) - [Equatorial Guinea](https://playbook.nium.com/country/equatorial-guinea) - [Eritrea](https://playbook.nium.com/country/eritrea) ##### Wallet - [Algeria](https://playbook.nium.com/country/algeria)¨ - [Ghana](https://playbook.nium.com/country/ghana) ¨ - [Cameroon](https://playbook.nium.com/country/cameroon)¨ - [Senegal](https://playbook.nium.com/country/senegal)¨ - [Ivory Coast](https://playbook.nium.com/country/ivory-coast)¨ - [Ghana](https://playbook.nium.com/country/ghana)¨ - [Nigeria](https://playbook.nium.com/country/nigeria)¨ - [Uganda](https://playbook.nium.com/country/uganda) ¨ - [Chad](https://playbook.nium.com/country/chad) ¨ - [Gambia](https://playbook.nium.com/country/gambia) ¨ ##### SWIFT - [Algeria](https://playbook.nium.com/country/algeria) - [Angola](https://playbook.nium.com/country/angola) - [Benin](https://playbook.nium.com/country/benin) - [Egypt](https://playbook.nium.com/country/egypt) - [Ghana](https://playbook.nium.com/country/ghana) - [Burkina Faso](https://playbook.nium.com/country/burkina-faso) - [Cameroon](https://playbook.nium.com/country/cameroon) - [Senegal](https://playbook.nium.com/country/senegal) - [Togo](https://playbook.nium.com/country/togo) - [Ivory Coast](https://playbook.nium.com/country/ivory-coast) - [Guinea](https://playbook.nium.com/country/guinea) - [Kenya](https://playbook.nium.com/country/kenya) - [Morocco](https://playbook.nium.com/country/morocco) - [Mozambique](https://playbook.nium.com/country/mozambique) - [Namibia](https://playbook.nium.com/country/namibia) - [Nigeria](https://playbook.nium.com/country/nigeria) - [Rwanda](https://playbook.nium.com/country/rwanda) - [Uganda](https://playbook.nium.com/country/uganda) - [Lesotho](https://playbook.nium.com/country/lesotho) - [Liberia](https://playbook.nium.com/country/liberia) - [Mauritania](https://playbook.nium.com/country/mauritania) - [Mauritius](https://playbook.nium.com/country/mauritius) - [Sierra Leone](https://playbook.nium.com/country/sierra-leone) - [South Africa](https://playbook.nium.com/country/south-africa) - [Zambia](https://playbook.nium.com/country/zambia) - [Republic of the Congo](https://playbook.nium.com/country/republic-of-the-congo) - [Reunion](https://playbook.nium.com/country/reunion) - [Sao Tome and Principe](https://playbook.nium.com/country/sao-tome-and-principe) - [Seychelles](https://playbook.nium.com/country/seychelles) - [Swaziland](https://playbook.nium.com/country/eswatini) - [Tanzania](https://playbook.nium.com/country/tanzania) - [Tunisia](https://playbook.nium.com/country/tunisia) - [Western Sahara](https://playbook.nium.com/country/western-sahara) - [Zimbabwe](https://playbook.nium.com/country/zimbabwe) ##### Visa Direct - [Algeria](https://playbook.nium.com/country/algeria) - [Angola](https://playbook.nium.com/country/angola) - [Benin](https://playbook.nium.com/country/benin) - [Egypt](https://playbook.nium.com/country/egypt) - [Ghana](https://playbook.nium.com/country/ghana) - [Burkina Faso](https://playbook.nium.com/country/burkina-faso) - [Cameroon](https://playbook.nium.com/country/cameroon) - [Senegal](https://playbook.nium.com/country/senegal) - [Ivory Coast](https://playbook.nium.com/country/ivory-coast) - [Guinea](https://playbook.nium.com/country/guinea) - [Kenya](https://playbook.nium.com/country/kenya) - [Morocco](https://playbook.nium.com/country/morocco) - [Nigeria](https://playbook.nium.com/country/nigeria) - [Uganda](https://playbook.nium.com/country/uganda) - [Zambia](https://playbook.nium.com/country/zambia) - [Lesotho](https://playbook.nium.com/country/lesotho) - [Liberia](https://playbook.nium.com/country/liberia) - [Madagascar](https://playbook.nium.com/country/madagascar) - [Malawi](https://playbook.nium.com/country/malawi) - [Sao Tome and Principe](https://playbook.nium.com/country/sao-tome-and-principe) - [Seychelles](https://playbook.nium.com/country/seychelles) - [Swaziland](https://playbook.nium.com/country/eswatini) - [Zambia](https://playbook.nium.com/country/zambia) #### Asia Asia ##### Bank Account (ACH) - [Bangladesh](https://playbook.nium.com/country/bangladesh) - [Guam](https://playbook.nium.com/country/guam) - [Hong Kong](https://playbook.nium.com/country/hong-kong) - [India](https://playbook.nium.com/country/india) - [Indonesia](https://playbook.nium.com/country/indonesia) - [Israel](https://playbook.nium.com/country/israel) - [Pakistan](https://playbook.nium.com/country/pakistan) - [Saudi Arabia](https://playbook.nium.com/country/saudi-arabia) - [South Korea](https://playbook.nium.com/country/south-korea) - [Thailand](https://playbook.nium.com/country/thailand) - [United Arab Emirates](https://playbook.nium.com/country/united-arab-emirates) - [Vietnam](https://playbook.nium.com/country/vietnam) ##### Bank Account (Other) - [Japan](https://playbook.nium.com/country/japan) - [Malaysia](https://playbook.nium.com/country/malaysia) - [Philippines](https://playbook.nium.com/country/philippines) - [Singapore](https://playbook.nium.com/country/singapore) - [Sri Lanka](https://playbook.nium.com/country/sri-lanka) ##### Local Currency Wire Transfer - [Armenia](https://playbook.nium.com/country/armenia) - [Bahrain](https://playbook.nium.com/country/bahrain) - [Bangladesh](https://playbook.nium.com/country/bangladesh) - [Bhutan](https://playbook.nium.com/country/bhutan) - [Brunei](https://playbook.nium.com/country/brunei) - [Cambodia](https://playbook.nium.com/country/cambodia) - [China](https://playbook.nium.com/country/china) - [Christmas Island](https://playbook.nium.com/country/christmas-island) - [Cocos (Keeling)](https://playbook.nium.com/country/cocos-keeling-islands) - [Timor-Leste](https://playbook.nium.com/country/timor-leste) - [Diego Garcia](https://playbook.nium.com/country/diego-garcia) - [Georgia](https://playbook.nium.com/country/georgia) - [Guam](https://playbook.nium.com/country/guam) - [Hong Kong](https://playbook.nium.com/country/hong-kong) - [India](https://playbook.nium.com/country/india) - [Indonesia](https://playbook.nium.com/country/indonesia) - [Israel](https://playbook.nium.com/country/israel) - [Japan](https://playbook.nium.com/country/japan) - [Jordan](https://playbook.nium.com/country/jordan) - [Kazakhstan](https://playbook.nium.com/country/kazakhstan) - [Kuwait](https://playbook.nium.com/country/kuwait) - [Kyrgyzstan](https://playbook.nium.com/country/kyrgyzstan) - [Laos](https://playbook.nium.com/country/laos) - [Malaysia](https://playbook.nium.com/country/malaysia) - [Maldives](https://playbook.nium.com/country/maldives) - [Mongolia](https://playbook.nium.com/country/mongolia) - [Nepal](https://playbook.nium.com/country/nepal) - [Oman](https://playbook.nium.com/country/oman) - [Pakistan](https://playbook.nium.com/country/pakistan) - [Palestine](https://playbook.nium.com/country/palestine) - [Philippines](https://playbook.nium.com/country/philippines) - [Qatar](https://playbook.nium.com/country/qatar) - [Saudi Arabia](https://playbook.nium.com/country/saudi-arabia) - [Singapore](https://playbook.nium.com/country/singapore) - [South Korea](https://playbook.nium.com/country/south-korea) - [Sri Lanka](https://playbook.nium.com/country/sri-lanka) - [Taiwan](https://playbook.nium.com/country/taiwan) - [Tajikistan](https://playbook.nium.com/country/tajikistan) - [Thailand](https://playbook.nium.com/country/thailand) - [Turkmenistan](https://playbook.nium.com/country/turkmenistan) - [United Arab Emirates](https://playbook.nium.com/country/united-arab-emirates) - [Uzbekistan](https://playbook.nium.com/country/uzbekistan) - [Vietnam](https://playbook.nium.com/country/vietnam) ##### Wallet - [Bangladesh](https://playbook.nium.com/country/bangladesh) - [China](https://playbook.nium.com/country/china) - [Indonesia](https://playbook.nium.com/country/indonesia) #### Europe Europe ##### Bank Account (ACH) - [Bailiwick of Guernsey](https://playbook.nium.com/country/bailiwick-of-guernsey) - [Bulgaria](https://playbook.nium.com/country/bulgaria) - [Czech Republic](https://playbook.nium.com/country/czech-republic) - [Denmark](https://playbook.nium.com/country/denmark) - [Gibraltar](https://playbook.nium.com/country/gibraltar) - [Hungary](https://playbook.nium.com/country/hungary) - [Iceland](https://playbook.nium.com/country/iceland) - [Isle of Man](https://playbook.nium.com/country/isle-of-man) - [Jersey](https://playbook.nium.com/country/jersey) - [Macedonia](https://playbook.nium.com/country/macedonia) - [Moldova](https://playbook.nium.com/country/moldova) - [Norway](https://playbook.nium.com/country/norway) - [Poland](https://playbook.nium.com/country/poland) - [Romania](https://playbook.nium.com/country/romania) - [Serbia](https://playbook.nium.com/country/serbia) - [Aland Islands](https://playbook.nium.com/country/aland-islands) - [Albania](https://playbook.nium.com/country/albania) - [Andorra](https://playbook.nium.com/country/andorra) - [Austria](https://playbook.nium.com/country/austria) - [Azerbaijan](https://playbook.nium.com/country/azerbaijan) - [Bailiwick of Guernsey](https://playbook.nium.com/country/bailiwick-of-guernsey) - [Belgium](https://playbook.nium.com/country/belgium) - [Bulgaria](https://playbook.nium.com/country/bulgaria) - [Croatia (Hrvatska)](https://playbook.nium.com/country/croatia-hrvatska) - [Cyprus](https://playbook.nium.com/country/cyprus) - [Czech Republic](https://playbook.nium.com/country/czech-republic) - [Denmark](https://playbook.nium.com/country/denmark) - [Estonia](https://playbook.nium.com/country/estonia) - [Finland](https://playbook.nium.com/country/finland) - [France](https://playbook.nium.com/country/france) - [Germany](https://playbook.nium.com/country/germany) - [Gibraltar](https://playbook.nium.com/country/gibraltar) - [Greece](https://playbook.nium.com/country/greece) - [Hungary](https://playbook.nium.com/country/hungary) - [Iceland](https://playbook.nium.com/country/iceland) - [Ireland](https://playbook.nium.com/country/ireland) - [Isle of Man](https://playbook.nium.com/country/isle-of-man) - [Italy](https://playbook.nium.com/country/italy) - [Jersey](https://playbook.nium.com/country/jersey) - [Kosovo](https://playbook.nium.com/country/kosovo) - [Latvia](https://playbook.nium.com/country/latvia) - [Liechtenstein](https://playbook.nium.com/country/liechtenstein) - [Lithuania](https://playbook.nium.com/country/lithuania) - [Luxembourg](https://playbook.nium.com/country/luxembourg) - [Macedonia](https://playbook.nium.com/country/macedonia) - [Malta](https://playbook.nium.com/country/malta) - [Moldova](https://playbook.nium.com/country/moldova) - [Monaco](https://playbook.nium.com/country/monaco) - [Montenegro](https://playbook.nium.com/country/montenegro) - [Netherlands](https://playbook.nium.com/country/netherlands) - [Norway](https://playbook.nium.com/country/norway) - [Poland](https://playbook.nium.com/country/poland) - [Portugal](https://playbook.nium.com/country/portugal) - [Romania](https://playbook.nium.com/country/romania) - [San Marino](https://playbook.nium.com/country/san-marino) - [Serbia](https://playbook.nium.com/country/serbia) - [Slovakia](https://playbook.nium.com/country/slovakia) - [Slovenia](https://playbook.nium.com/) - [Aland Islands](https://playbook.nium.com/country/aland-islands) - [Albania](https://playbook.nium.com/country/albania) - [Andorra](https://playbook.nium.com/country/andorra) - [Austria](https://playbook.nium.com/country/austria) - [Azerbaijan](https://playbook.nium.com/country/azerbaijan) - [Bailiwick of Guernsey](https://playbook.nium.com/country/bailiwick-of-guernsey) - [Belgium](https://playbook.nium.com/country/belgium) - [Bulgaria](https://playbook.nium.com/country/bulgaria) - [Croatia (Hrvatska)](https://playbook.nium.com/country/croatia-hrvatska) - [Cyprus](https://playbook.nium.com/country/cyprus) - [Czech Republic](https://playbook.nium.com/country/czech-republic) - [Denmark](https://playbook.nium.com/country/denmark) - [Estonia](https://playbook.nium.com/country/estonia) - [Finland](https://playbook.nium.com/country/finland) - [France](https://playbook.nium.com/country/france) - [Germany](https://playbook.nium.com/country/germany) - [Gibraltar](https://playbook.nium.com/country/gibraltar) - [Greece](https://playbook.nium.com/country/greece) - [Hungary](https://playbook.nium.com/country/hungary) - [Iceland](https://playbook.nium.com/country/iceland) - [Ireland](https://playbook.nium.com/country/ireland) - [Isle of Man](https://playbook.nium.com/country/isle-of-man) - [Italy](https://playbook.nium.com/country/italy) - [Jersey](https://playbook.nium.com/country/jersey) - [Kosovo](https://playbook.nium.com/country/kosovo) - [Latvia](https://playbook.nium.com/country/latvia) - [Liechtenstein](https://playbook.nium.com/country/liechtenstein) - [Lithuania](https://playbook.nium.com/country/lithuania) - [Luxembourg](https://playbook.nium.com/country/luxembourg) - [Macedonia](https://playbook.nium.com/country/macedonia) - [Malta](https://playbook.nium.com/country/malta) - [Moldova](https://playbook.nium.com/country/moldova) - [Monaco](https://playbook.nium.com/country/monaco) - [Montenegro](https://playbook.nium.com/country/montenegro) - [Netherlands](https://playbook.nium.com/country/netherlands) - [Norway](https://playbook.nium.com/country/norway) - [Poland](https://playbook.nium.com/country/poland) - [Portugal](https://playbook.nium.com/country/portugal) - [Romania](https://playbook.nium.com/country/romania) - [San Marino](https://playbook.nium.com/country/san-marino) - [Serbia](https://playbook.nium.com/country/serbia) - [Slovakia](https://playbook.nium.com/country/slovakia) - [Slovenia](https://playbook.nium.com/country/slovenia) - [Spain](https://playbook.nium.com/country/spain) - [Svalbard and Jan Mayen Islands](https://playbook.nium.com/country/svalbard-and-jan-mayen-islands) - [Sweden](https://playbook.nium.com/country/sweden) - [Switzerland](https://playbook.nium.com/country/) - [Albania](https://playbook.nium.com/country/albania) - [Austria](https://playbook.nium.com/country/austria) - [Azerbaijan](https://playbook.nium.com/country/azerbaijan) - [Bailiwick of Guernsey](https://playbook.nium.com/country/bailiwick-of-guernsey) - [Czech Republic](https://playbook.nium.com/country/czech-republic) - [Denmark](https://playbook.nium.com/country/denmark) - [Gibraltar](https://playbook.nium.com/country/gibraltar) - [Hungary](https://playbook.nium.com/country/hungary) - [Isle of Man](https://playbook.nium.com/country/isle-of-man) - [Italy](https://playbook.nium.com/country/italy) - [Jersey](https://playbook.nium.com/country/jersey) - [Poland](https://playbook.nium.com/country/poland) - [Sweden](https://playbook.nium.com/country/sweden) - [Turkey](https://playbook.nium.com/country/turkey) - [United Kingdom](https://playbook.nium.com/country/united-kingdom) #### North America North America ##### Bank Account (ACH) - [Canada](https://playbook.nium.com/country/canada) - [Costa Rica](https://playbook.nium.com/country/costa-rica) - [Dominican Republic](https://playbook.nium.com/country/dominican-republic) - [Guatemala](https://playbook.nium.com/country/guatemala) - [Mexico](https://playbook.nium.com/country/mexico) - [Puerto Rico](https://playbook.nium.com/country/puerto-rico) - [United States](https://playbook.nium.com/country/united-states) - [Virgin Islands (U.S.)](https://playbook.nium.com/country/virgin-islands-us) ##### Check (United States) - [United States](https://playbook.nium.com/country/united-states) ##### Fedwire (United States) [United States](https://playbook.nium.com/country/united-states) ##### Interac (Canada only) - [Canada](https://playbook.nium.com/country/canada) ##### SEPA - [Guadeloupe](https://playbook.nium.com/country/guadeloupe) - [Martinique](https://playbook.nium.com/country/martinique) - [Saint Martin (French part)](https://playbook.nium.com/country/saint-martin) ##### SWIFT - [Anguilla](https://playbook.nium.com/country/Aaguilla) - [Antigua](https://playbook.nium.com/country/antigua) - [Aruba](https://playbook.nium.com/country/aruba) - [Bahamas](https://playbook.nium.com/country/bahamas) - [Barbados](https://playbook.nium.com/country/barbados) - [Belize](https://playbook.nium.com/country/belize) - [Bermuda](https://playbook.nium.com/country/bermuda) - [Bonaire, Sint Eustatius & Saba](https://playbook.nium.com/country/bonaire-sint-eustatius-and-saba/institutions) - [British Virgin Islands](https://playbook.nium.com/country/british-virgin-island) - [Canada](https://playbook.nium.com/country/canada) - [Caribbean Netherlands](https://playbook.nium.com/country/carib-nld) - [Cayman Islands](https://playbook.nium.com/country/cayman-island) - [Costa Rica](https://playbook.nium.com/country/costa) - [Dominica](https://playbook.nium.com/country/Ddminica) - [Dominican Republic](https://playbook.nium.com/country/dominican-republic) - [El Salvador](https://playbook.nium.com/country/el-salvador) - [Greenland](https://playbook.nium.com/country/greenland) - [Grenada](https://playbook.nium.com/country/grenada) - [Guatemala](https://playbook.nium.com/country/guatemala) - [Haiti](https://playbook.nium.com/country/haiti) - [Honduras](https://playbook.nium.com/country/hondurus) - [Jamaica](https://playbook.nium.com/country/jamaica) - [Mexico](https://playbook.nium.com/country/mexico) - [Montserrat](https://playbook.nium.com/country/montserrat) - [Nicaragua](https://playbook.nium.com/country/nicaragua) - [Panama](https://playbook.nium.com/country/panama) - [Saint Kitts and Nevis](https://playbook.nium.com/country/saint-kitts-and-nevis) ##### Visa Direct - [Bahamas](https://playbook.nium.com/country/bahamas) - [Dominica](https://playbook.nium.com/country/dominica) - [Dominican Republic](https://playbook.nium.com/country/dominican-republic) - [Guatemala](https://playbook.nium.com/country/guatemala) - [Honduras](https://playbook.nium.com/country/honduras) #### South America South America ##### Bank Account (ACH) - [Argentina](https://playbook.nium.com/country/argentina) - [Bolivia](https://playbook.nium.com/country/bolivia) - [Brazil](https://playbook.nium.com/country/brazil) - [Chile](https://playbook.nium.com/country/chile) - [Colombia](https://playbook.nium.com/country/colombia) - [Peru](https://playbook.nium.com/country/peru) - [Uruguay](https://playbook.nium.com/country/uruguay) ##### Proxy - [Brazil](https://playbook.nium.com/country/brazil) ##### SWIFT - [Argentina](https://playbook.nium.com/country/argentina) - [Bolivia](https://playbook.nium.com/country/bolivia) - [Brazil](https://playbook.nium.com/country/brazil) - [Chile](https://playbook.nium.com/country/chile) - [Colombia](https://playbook.nium.com/country/colombia) - [Curaçao](https://playbook.nium.com/country/curacao) - [Ecuador](https://playbook.nium.com/country/ecuador) - [Falkland Islands (Malvinas)](https://playbook.nium.com/country/falkland-islands-malvinas) - [French Guiana](https://playbook.nium.com/country/french-guiana) - [Guyana](https://playbook.nium.com/country/guyana) - [Paraguay](https://playbook.nium.com/country/paraguay) - [Peru](https://playbook.nium.com/country/peru) - [Suriname](https://playbook.nium.com/country/suriname) - [Uruguay](https://playbook.nium.com/country/uruguay) - [Venezuela](https://playbook.nium.com/country/venezuela) #### Oceania Oceania ##### Bank Account (ACH) - [American Samoa](https://playbook.nium.com/country/american-samoa) - [Australia](https://playbook.nium.com/country/australia) - [Guam](https://playbook.nium.com/country/guam) - [Northern Marina Islands](https://playbook.nium.com/country/northern-mariana-islands) ##### Proxy - [Australia](https://playbook.nium.com/country/australia) ##### SWIFT - [American Samoa](https://playbook.nium.com/country/american-samoa) - [Antarctica](https://playbook.nium.com/country/antarctica) - [Australia](https://playbook.nium.com/country/australia) - [Bouvet Island](https://playbook.nium.com/country/bouvet-island) - [Cook Islands](https://playbook.nium.com/country/cook-islands) - [Fiji](https://playbook.nium.com/country/fiji) - [Guam](https://playbook.nium.com/country/guam) - [French Polynesia](https://playbook.nium.com/country/french-polynesia) - [French Southern Territories](https://playbook.nium.com/country/french-southern-territories) - [Heard and Mc Donald Islands](https://playbook.nium.com/country/heard-and-mc-donald-islands) - [Kiribati](https://playbook.nium.com/country/kiribati) - [Micronesia, Federated States of](https://playbook.nium.com/country/micronesia-federated-states-of) - [Nauru](https://playbook.nium.com/country/nauru) - [New Caledonia](https://playbook.nium.com/country/new-caledonia) - [New Zealand](https://playbook.nium.com/country/new-zealand) - [Niue](https://playbook.nium.com/country/niue/institutions) - [Norfolk Island](https://playbook.nium.com/country/norfolk-island) - [Northern Mariana Islands](https://playbook.nium.com/country/northern-mariana-islands) - [Palau](https://playbook.nium.com/country/palau) - [Papua New Guinea](https://playbook.nium.com/country/papua-new-guinea) - [Pitcairn](https://playbook.nium.com/country/pitcairn) - [Samoa](https://playbook.nium.com/country/samoa) - [Solomon Islands](https://playbook.nium.com/country/solomon-islands) - [South Georgia South Sandwich Islands](https://playbook.nium.com/country/south-georgia-south-sandwich-islands) - [Tokelau](https://playbook.nium.com/country/tokelau) - [Tonga](https://playbook.nium.com/country/tonga) - [Tuvalu](https://playbook.nium.com/country/tuvalu) - [Vanuatu](https://playbook.nium.com/country/vanuatu) - [Wallis and Futuna Islands](https://playbook.nium.com/country/wallis-and-futuna-islands) ##### Visa Direct - [Fiji](https://playbook.nium.com/country/fiji) - [Guam](https://playbook.nium.com/country/guam) - [Papua New Guinea](https://playbook.nium.com/country/papua-new-guinea) - [Tonga](https://playbook.nium.com/country/tonga) ### Where can I receive money with Nium? The following breakw down where **payins** are supported for *non-financial* institutions, - When *funding your own account*, the customer cannot be located in the US or the countries subject to sanctions or restrictions by the US government. - When *accpeting funds from third parties*, the customer cannot be located in the countries that are subject to sanctions or restrictions by US government. #### Africa Africa ##### South Africa - South African Rand - ZAR - [South Africa](https://playbook.nium.com/payin/ZAR?currencies=ZAR\&payin_service=Funding\&channel=Nium+One) #### Asia Asia ##### China - Chinese Yuan - CNY - [China](https://playbook.nium.com/payin/CNY?payin_service=Funding\&channel=Nium+One\¤cies=CNY) ##### Hong Kong - Kong Kong Dollar - HKD - [Hong Kong](https://playbook.nium.com/payin/HKD?payin_service=Funding\&channel=Nium+One\¤cies=HKD) ##### Israel - Israeli New Shekel - ILS - [Israel](https://playbook.nium.com/payin/ILS?payin_service=Funding\&channel=Nium+One\¤cies=ILS) ##### Japan - Japanese Yen - JPY - [Japan](https://playbook.nium.com/payin/JPY?payin_service=Funding\&channel=Nium+One\¤cies=JPY) ##### Philippines - Philippine Peso - PHP - [Philippines](https://playbook.nium.com/payin/PHP?payin_service=Funding\&channel=Nium+One\¤cies=PHP) ##### Saudi Arabia - Saudi Riyal - SAR - [Saudi Arabia](https://playbook.nium.com/payin/SAR?payin_service=Funding\&channel=Nium+One\¤cies=SAR) ##### Singapore - Singapore Dollar - SGD -[Singapore](https://playbook.nium.com/payin/SGD?payin_service=Funding\&channel=Nium+One\¤cies=SGD) ##### Thailand - Thai Baht - THB - [Thailand](https://playbook.nium.com/payin/THB?payin_service=Funding\&channel=Nium+One\¤cies=THB) ##### United Arab Emirates - UAE Dirham - UAE - [United Arab Emirates](https://playbook.nium.com/payin/AED?payin_service=Funding\&channel=Nium+One\¤cies=AED) #### Europe Europe ##### Euro - EUR Please note, for SEPA transactions *under* $100,000: - Expected funds receipt is **Realtime**. - There are no cutoff time and there is 24/7 availability. For SEPA transactions over $100,000: - Expected funds receipt is **T0**. - The amount will be credited to the beneficiary on the sameday *if* funds are received before 14:00 EET. - [Andorra](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Austria](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Belgium](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Bulgaria](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Switzerland](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Cyprus](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Czech Republic](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Germany](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Denmark](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Estonia](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Spain](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Finland](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [France](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [United Kingdom](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Greece](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Croatia](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Holy See (Vatican City State)](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Hungary](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Iceland](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Indonesia](https://playbook.nium.com/payin/IDR?payin_service=Funding\&channel=Nium+One\¤cies=IDR) - [Italy](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Liechtenstein](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Lithuania](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Luxembourg](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Latvia](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Monaco](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Malta](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Netherlands](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Norway](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Poland](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Portugal](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Romania](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Sweden](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Slovenia](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Slovakia](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [San Marino](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) - [Switzerland](https://playbook.nium.com/payin/CHF?currencies=CHF\&payin_service=Funding\&channel=Nium+One) - [Turkey](https://playbook.nium.com/payin/TRY?payin_service=Funding\&channel=Nium+One\¤cies=TRY) - [United Kingdom](https://playbook.nium.com/payin/GBP?payin_service=Funding\&channel=Nium+One\¤cies=GBP) - [Anywhere except the US](https://playbook.nium.com/payin/EUR?currencies=EUR\&payin_service=Funding\&channel=Nium+One) #### North America North America ##### Canada - Canadian Dollar - CAD - [Canada](https://playbook.nium.com/payin/CAD?payin_service=Funding\&channel=Nium+One\¤cies=CAD) - [Mexico](https://playbook.nium.com/payin/MXN?payin_service=Funding\&channel=Nium+One\¤cies=MXN) - [United States](https://playbook.nium.com/payin/USD?payin_service=Funding\&channel=Nium+One\¤cies=USD) #### Oceania Oceania - [Australia](https://playbook.nium.com/payin/AUD?currencies=AUD\&payin_service=Funding\&channel=Nium+One) | AUD | DE/BECS (Bank Account) | Anywhere except US | Australia | B2BP2P | Same day if before 19:00 AEST | No limit | T0 | Asynchronous (within 24 hrs) | Customer | - [New Zealand](https://playbook.nium.com/payin/NZD?payin_service=Funding\&channel=Nium+One\¤cies=NZD) --- # Testing Nium URL: https://docs.nium.com/docs/getting-started/testing-nium Learn how to test Nium's different services and build your integration with confidence. Please note, for testing purposes this article details how to test Nium's services in the US. See our [Testing - Postman](https://www.postman.com/nium-api/nium/folder/r230uvo/testing) collection for a breakdown of the different testing scenarios available. Please note, this feature is currently in beta and only available for select clients. If you're interested, or have any questions please contact your Nium account manager or [Nium Support](mailto:support@nium.com). ## Onboarding Use the [Simulate - Onboarding](/api#tag/customer/POST/api/v1/simulations/onboard/{customerHashId}/transition) request to test the onboarding status for individual and corporate accounts. ### Individual customers To comprehensively test onboarding, use the following requests which also help you create the resources you'll manipulate to test onboarding.. Onboarding - Individual Customers | **Request** | **Description** | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Step 1:** [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) | Add A customer.Include `PEP` in `firstName` to return an **ACTION\_REQUIRED** `status`. | | **Step 2:** [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | After creating a `customer`, use the Customer Details V2 request to verify the `complianceStatus` of the `customer` is **ACTION\_REQUIRED**. | | **Step 3:** [Transition Compliance Status](/api#tag/customer/POST/api/v1/simulations/onboard/{customerHashId}/transition) | Set `nextStatus` to `RFI_REQUESTED` and specify `requestInfoFor` as needed.Repeat Step 2 to confirm the `complianceStatus` updates to `RFI_REQUESTED`. | | **Step 4:** [Fetch Individual Customer RFI Details](/api#tag/customer-account---individual/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) | Fetch details about the Request for Information (RFI). | | **Step 5:** [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) | Respond to the RFI. | | **Step 6:** [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) | Set `nextStatus` to **COMPLETED** or **REJECT**.Repeat Step 2 to verify the **COMPLETED** final status.Please note, **REJECT** and **COMPLETED** are permanent states. | ### Corporate customers Testing how to onboard customers follows a similar flow to individual customers, with some variations in API parameters. Simulation API requirements remain the same except for values accepted in `requestInfoFor`. Onboarding - Corporate Customers | **Request** | **Description** | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Step 1:** [Onboard Corporate Customer](/api#tag/customer-account---corporate/POST/api/v1/client/{clientHashId}/corporate) | Add A customer.Include `BusinessHit` in `businessName` to return an **ACTION\_REQUIRED** `status`. | | **Step 2:** [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | After creating a `customer`, use the Customer Details V2 request to verify the `complianceStatus` of the `customer` is **ACTION\_REQUIRED**. | | **Step 3:** [Transition Compliance Status](/api#tag/customer/POST/api/v1/simulations/onboard/{customerHashId}/transition) | Set `nextStatus` to `RFI_REQUESTED` and specify `requestInfoFor` as needed.Repeat Step 2 to confirm the `complianceStatus` updates to `RFI_REQUESTED`. | | **Step 4:** [Fetch Corporate Customer RFI Details](/api#tag/customer-account---corporate/GET/api/v1/client/{clientHashId}/corporate/rfi) | Fetch details about the Request for Information (RFI). | | **Step 5:** [Respond to RFI for Corporate Customer](/api#tag/customer-account---corporate/POST/api/v1/client/{clientHashId}/corporate/rfi) | Respond to the RFI. | | **Step 6:** [Respond to RFI for Corporate Customer](/api#tag/customer-account---corporate/POST/api/v1/client/{clientHashId}/corporate/rfi) | Set `nextStatus` to **COMPLETED** or **REJECT**.Repeat Step 2 to verify the **COMPLETED** final status.Please note, **REJECT** and **COMPLETED** are permanent states. | ## Payouts To comprehensively test payouts, first use the following requests to create the resources you'll manipulate to test payouts. Please note: - Use the following endpoint - `/api/v1/simulations/transactions/{systemReferenceNumber}/transition` - `nextStatus` can accept the following values: - `EXPIRED` - `RFI_REQUESTED` - `COMPLIANCE_COMPLETED` - `REJECTED` - `PAID` - `RETURN` - `ERROR1` - Use the following request body to test out the different `nextStaus` statuses: ```json { "nextStatus":"RFI_REQUESTED", "requestInfoFor": "creditor_salaryStatement" } ``` Payouts - Prerequisites | **Request** | **Description** | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Step 1:** [Onboard Corporate Customer](/api#tag/customer-account---corporate/POST/api/v1/client/{clientHashId}/corporate) | Use the [Onboard Corporate Customer](/api#tag/customer-account---corporate/POST/api/v1/client/{clientHashId}/corporate) request to create a `customer`. | | **Step 2:** [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | After creating a `customer`, use the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) request to verify the `complianceStatus` of the `customer` is **COMPLETED**. | | **Step 3:** [Fund Wallet](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) | Fund the wallet for the `customer` to make funds available to debit. | | **Step 4:** [Assign a a Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) | [Assign a a Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) to the `customer` wallet to define the funding source for transactions. | ### Requests for Information (RFIs) For each scenario and detailed step, images and detailed instructions are provided for each stage in the testing process. Payouts - Requests for Information (RFIs) | **Request** | **Description** | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Step 1:** [Add Beneficiary V2](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) | Include **TransactionCreditorHit** in `beneficiaryName` in the request body to return `ACTION_REQUIRED` as a compliance status. Set the beneficiary account number to **000987654322** to return the payment status as 'PAID’. | | **Step 2:** [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) | Transfer funds between payment sources. | | **Step 3:** [Fetch Remittance Status](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) | After creating a `beneficiary`, use the Fetch Remittance Status request to verify the `complianceStatus` of the `customer` is **ACTION\_REQUIRED**. | | **Step 4:** [Test Payouts](/api#tag/payouts/POST/api/v1/simulations/transactions/{systemReferenceNumber}/transition) | Set the next `status` as **RFI\_REQUESTED** and set `requestInfoFor`. Repeat Step 3 to verify a a new payout with `status` as **RFI\_REQUESTED**. | | **Step 5:** [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) | Fetch details about the Request for Information (RFI). | | **Step 6:** [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) | Respond to the RFI. | | **Step 7:** [Payout Simulation](/api#tag/payouts/POST/api/v1/simulations/transactions/{systemReferenceNumber}/transition) | Set the `nextStatus` as `COMPLIANCE_COMPLETED`.Repeat Step 3 to verify the final status.Please note `REJECTED` is a permanent transaction `status`. | | **Step 8:** [Fetch Remittance Status](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) | Repeat Step 3 to verify if the final `status` is **PAID**. | ### Bank errors Payouts - Bank Error | **Request** | **Description** | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Step 1:** [Add Beneficiary V2](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) | Set the beneficiary account number to **00098765991** to return a **SENT\_TO\_BANK** transaction status. | | **Step 2:** [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) | Transfer funds between payment sources. | | **Step 3:** [Fetch Remittance Status](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) | Use the Fetch Remittance Status request to verify the status of the transaction is **SENT\_TO\_BANK**. | | **Step 4:** [Test Payouts](/api#tag/payouts/POST/api/v1/simulations/transactions/{systemReferenceNumber}/transition) | Set the `nextStatus` as `PAID` or `RETURN`.Repeat Step 3 to verify if a new entry with the expected `status`. | ### Bank returns Payouts - Bank Return | **Request** | **Description** | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Step 1:** [Add Beneficiary V2](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) | Set the beneficiary account number to **000712654321** to return an **ERROR** transaction status. | | **Step 2:** [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) | Transfer funds between payment sources. | | **Step 3:** [Fetch Remittance Status](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) | Use the Fetch Remittance Status request to verify the status of the transaction is **ERROR**. | | **Step 4:** [Test Payouts](/api#tag/payouts/POST/api/v1/simulations/transactions/{systemReferenceNumber}/transition) | Set the `nextStatus` as `PAID` or `RETURN`.Repeat Step 3 to verify if a new entry with the expected `status`. | ### Account owner returns Payouts - Account Owner Return | **Request** | **Description** | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | **Step 1:** [Add Beneficiary V2](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) | Set the beneficiary account number to **000987654322** to return a **PAID** transaction status. | | **Step 2:** [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) | Transfer funds between payment sources. | | **Step 3:** [Fetch Remittance Status](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) | Use the Fetch Remittance Status request to verify the status of the transaction is **PAID**. | | **Step 4:** [Test Payouts](/api#tag/payouts/POST/api/v1/simulations/transactions/{systemReferenceNumber}/transition) | Set the `nextStatus` as `RETURN`.Repeat Step 3 to verify if a new entry with the expected `status` | ## Testing transactions To simulate transaction status in sandbox, use the following table to replicate the following statuses: - `PG_PROCESSING` - `SENT TO BANK` - `PAID` - `RETURNED` Create a payout to test the above statuses: 1. Create a `beneficiary` using the [Add Beneficiary V2](/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) request and the parameters mentioned in the below table: - `beneficiaryCountryCode` as **US** - `destinationCurrency` as **USD** 2. Use the [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) request to create a transaction with the beneficiary hash ID obtained in Step 1. In the simulation scenarios listed below, all status changes occur in one minute intervals. | Scenario | Routing Code | Beneficiary Account Number | Description | | :----------------- | :----------- | :------------------------- | :------------------------------------------------------------------------------------- | | `PAID` | 111000000 | 000987654321 | The status transitions from `PG_PROCESSING` --> `SENT_TO_BANK`--> `PAID`. | | `RETURN` | 111000000 | 000897654321 | The status transitions from `PG_PROCESSING` --> `SENT_TO_BANK` --> `RETURN` | | `PAID` to `RETURN` | 111000000 | 000879654321 | The status transitions from `PG_PROCESSING` --> `SENT_TO_BANK` --> `PAID` --> `RETURN` | | `PAID` | 111000000 | 000987654322 | The status transitions from `SENT_TO_BANK` --> `PAID` | --- # Error Responses URL: https://docs.nium.com/docs/getting-started/error-responses In case of an error, the response may consist of following: | **Field** | **Present in Error Response \[Required/Optional]** | **Description** | **Example** | | --------- | -------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ | | `status` | Required | Status of the request. | **BAD\_REQUEST** | | `message` | Required | Human readable message describing the error. | Similar identification type and value found | | `code` | Optional | Error Code 400. | **BAD\_REQUEST** | | `errors` | Optional | Array with error details. | \[ "Customer has already been assigned with same email id" ] | Some examples are as follows: ```json { "status": "BAD_REQUEST", "message": "Unable to read request body or no request body provided", "errors": [ "JSON parse error: Illegal unquoted character ((CTRL-CHAR, code 13)): has to be escaped using backslash to be included in string value; nested exception is com.fasterxml.jackson.databind.JsonMappingException: Illegal unquoted character ((CTRL-CHAR, code 13)): has to be escaped using backslash to be included in string value at [Source: (PushbackInputStream); line: 28, column: 27] \(through reference chain: com.nium.spend.cards.customer.dto.request.CustomerDataRequestDTO[\"correspondenceCity\"])" ] } ``` ```json { "status": "BAD_REQUEST", "message": "Customer has already been assigned with same email id", "errors": [ "Customer has already been assigned with same email id" ] } ``` ### Error codes In case of successful API call, HTTP Status Code 200 is to be expected. In case of an error, HTTP Status Code 4xx or 5xx range is to be expected. Following table contains the most common error codes you may encounter: *** | **Error Code** | **Meaning** | | ------------------------- | ------------------------------------------------------------------------------------------------------- | | 400 Bad Request | The request could not be understood by the server due to malformed syntax | | 401 Unauthorized | The request requires user authentication. | | 403 Forbidden | The server understood the request, but is refusing to fulfill it. | | 405 Method Not Allowed | The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. | | 429 Too Many Requests | Request counts exceed our limit. Slow down! | | 500 Internal Server Error | We had a problem with our server. Try again later. | | 503 Service Unavailable | We're temporarily offline for maintenance. Please try again later. | --- # Onboarding URL: https://docs.nium.com/docs/onboarding Onboarding refers to the process your customers need follow to sign up for the financial services you plan to offer. *Onboarding* refers to the process your customers need follow to sign up for the financial services you plan to offer. Onboarding is a critical step, helping ensure compliance with regulatory standards and facilitating smooth operations as you bring your customer onto your platform. Onboarding includes: - **Regulatory Compliance**: Adherence to Know Your Customer (KYC) and Know Your Business (KYB) requirements across different regions. - **Risk Mitigation**: Identification and prevention of high-risk accounts. - **Operational Readiness**: Quick setup for customers to start transacting. Whether you're onboarding individual or corporate customers, using Nium you can automate and customize these onboarding processes to fit your business needs. ## Customer types There are two primary customer types when onboarding with Nium: - **Corporate customers**: Businesses or organizations, including small-to-medium market enterprises that can require more complex verification. - **Individual customers**: End-users, such as employees or retail customers, who hold balances and transact through your platform. By understanding the onboarding requirements and workflows for the different customer types, you can efficiently set up customers and ensure compliance with regional regulations. If you need help setting up your onboarding workflows, contact your Nium account manager for guidance or [Nium support](mailto:support@nium.com). ### Corporate customers Corporate customers represent businesses or organizations that interact with your platform. Onboarding includes: 1. **KYB Verification**: Validating the organization's legal and financial standing. 2. **Stakeholder and Applicant Checks**: Verifying key individuals involved with the organization. 3. **Account Setup**: Assigning wallets and enabling operations. ### Individual customers Individual customers are end-users who interact with your platform. Depending on the use case, they could be employees using expense cards or retail customers managing personal accounts. The onboarding process involves: 1. **KYC Verification**: Using automated or manual methods to validate identity. 2. **Compliance Checks**: Ensuring the individual meets regulatory and risk standards. 3. **Account Setup**: Creating an account and enabling transactions. ## Onboarding customers There are two ways to onboard customers onto Nium: - [Nium API](/api#tag/customer-onboarding-v5): Ideal for clients that need to build a highly tailored custom experience and has dedicated engineering resources readily available. - [Pre-built Forms](#pre-built-forms): Ideal for clients with limited engineering resources that can reuse forms and want to pass compliance updates off to Nium. ### Pre-built Forms Corporate Customers can also be onboarded on to Nium using Pre-built Forms. Pre-built forms are pre-built customer experiences you can use to collect customer information without needing to build your own front end experience. Pre-built forms are helpful if you: - Onboard high volumes - Require full UX/UI and workflow control - Have limited engineering resources For more information, see [Pre-built Forms](/docs/developers/pre-built-forms). --- # Customer Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding Nium is introducing a new version of our Customer Onboarding requests. This new version (v5) provides a unified and streamlined approach to onboarding both *corporate* and *individual* customers (across multiple regions) using a single request. This new request includes region-specific objects, which Nium processes automatically. See [Customer Onboarding v5](/api#tag/customer-onboarding-v5) for more details. Compared to previous versions, version 5 introduces: - A single onboarding request for all customer types that includes: - Corporate customers - Individual customers - Employee onboarding for spend management and payroll - Region-specific objects that are compliant and flexible - Clear requirements for fields and documents - A standardized `address` object - A clearer, optimized structure that enables faster onboarding and improves developer experience - An API- and form-based experience that: - Handles regional Know Your Customer (KYC) methods and documentation in a single flow - Enables inline verification to improve the customer experience ## Customer types Customers are broadly divided into three types in Nium: - Corporate customers - Individual customers - Employees of a corporation After completing their integration, clients can start onboarding their customers. To onboard customers, clients use the [Create a Customer](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request. Nium verifies the customer against local **Know Your Customer (KYC)** and **Know Your Business (KYB)** requirements. ### Corporate customers The following terms define key entity types involved in onboarding a corporate customer to Nium. | **Entity type** | **Definition** | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Business** | A *Business* is a corporate customer being onboarded to the Nium platform. This includes registered entities such as private limited companies, partnerships, and other legal organizations. During onboarding, the business must provide corporate information, stakeholder details, and supporting documents.These details are used to complete **Know Your Business (KYB)** verification in line with regional regulations. | | **Applicant** | An *Applicant* is the individual who submits the onboarding application on behalf of the business. The applicant is usually an authorized representative or signatory.As part of onboarding, the applicant must complete **Know Your Customer (KYC)** verification to meet compliance standards. | | **Stakeholder** | A *Stakeholder* is any individual or entity listed in the business’s registration documents—such as a director, officer, ultimate beneficial owner (UBO), control person, or shareholder.**Nium** requires full disclosure and **KYC verification** for all stakeholders.Stakeholders may be either natural persons (individuals) or legal entities (businesses). | ### Individual customers The following defines key entity types involved in onboarding an individual customer to Nium. | **Entity type** | **Definition** | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Individual Customer** | An *Individual Customer* is a natural person onboarded to Nium for the purpose of sending or receiving funds in a personal capacity (not on behalf of a business or organization). Individual customers must complete **Know Your Customer (KYC)** verification in line with the regional regulatory requirements. | | | | ### Employees (corporate program) Employees onboarded under a corporate program follow the individual-customer flow. While creating an employee as a customer, **parentCustomerHashId** is a mandatory parameter to be passed in the [create customer API](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). This is the associated corporate customerhashId. Other differences include: | **Employee type** | **Differences from standard individual onboarding** | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Corporate Customer – Payroll** | KYC requirements are the same as for individual customers. No additional documents typically required beyond standard KYC. | | **Corporate Customer – Spend Management** | KYC is not required except in certain jurisdictions like EU. An **employment letter** is required for onboarding such employees. | | | | ## Verification methods ### Businesses (KYB) Business customers can verify their details in two ways: - **Electronic KYB (eKYB):** Pre-populates business information from verified sources, significantly reducing approval time. In some regions, automated verification is available for corporate customers. - **Manual KYB:** Requires manual submission of business documents and a compliance review by Nium, resulting in longer processing times. ### Individuals (KYC) Individual customers can verify their details in three ways: - **Electronic KYC:** Enables real-time identity verification using region-specific electronic methods. Verification speed and data sources may vary by geography. - **Biometric KYC:** Verifies a customer's identity by matching a real-time selfie or liveness check against their government-issued document. Typically used when electronic verification is unavailable. - **Manual KYC:** Requires applicants or stakeholders to upload identity documents for manual review by Nium’s compliance team. For details on region-specific KYB and KYC options, see the respective regional onboarding pages. ## Onboarding customers ### Step 1: Configure your client account Before you begin, work with your Nium account manager to configure your client account and enable the [Customer Status](/docs/developers/notifications-and-webhooks/platform-events/customer-status) event. You also need to whitelist the required IP addresses. ### Step 2: Regulatory region A client account must exist in the corresponding region before you can onboard customers. | Customer registered country | Regulatory region | | --------------------------- | ------------------------------- | | GB, Switzerland, Monaco | UK | | EEA countries | EU | | SG | SG | | US | US | | AU or NZ | AU or NZ respectively | | CA, HK, JP, ID, MY | CA, HK, JP, MY, ID respectively | | None of the above | SG | ### Step 3: Prefill data (optional) Nium lets you prefill business and stakeholder data in your form for supported regions.\ Check the [region-specific guide](/docs/onboarding) to determine if the *Fetch Public Details* or *Fetch Exhaustive Corporate Details* requests are available: - [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) - [Fetch Exhaustive Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/exhaustiveDetailsSearch) ### Step 4: Upload required documentation Use the [Create a File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload the necessary documentation. ### Step 5: Submit onboarding application Use the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request. If you didn’t prefill details in Step 3, include: - Customer information - Registered business address - Business details - Applicant and stakeholder details - Document details using the `fileId` from Step 4: - Business documents for corporate applicants and a [Letter of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization). - For employee onboarding, an employment letter. Once submitted, Nium performs electronic verification on all directors and stakeholders. If additional KYC is required for any entity (for example, the applicant or a stakeholder), you receive a webhook with: - `status`: **pending** - `subStatus`: **awaiting\_kyc** Once KYC is complete, if a manual review from Nium is required, then the webhook returns: - `status`: **pending** - `subStatus`: **under\_review** If no manual review is required, the webhook returns `status`: **clear** immediately after submission. Once verified: - The `status` stays as **clear** - The `subStatus` updates to **null** ### Step 6: Complete KYC verification KYC verification can be completed in two ways: - **Pre-built KYC form:** Ask your customer to complete the [Pre-built KYC form](/docs/developers/pre-built-forms) for the applicant and all stakeholders, including any missing details or documents. - **Submit KYC API:** Use the [Submit KYC](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customer/{customerHashId}/submitKyc) request to programmatically submit KYC details for the applicant and all stakeholders. After completion, the `status` remains **pending** and the `subStatus` updates to **under\_review**. ### Step 7: Compliance review and RFIs At this point, Nium's compliance team reviews the application. If additional information is required, Nium raises a Request for Information (RFI) If the review is successful, the application `status` updates to **clear**. The customer is approved and ready to *start processing transactions*. ### Step 8: Update application Once the application `status` is **clear** or `rejected`, you can use the [Update Customer v5](/api#tag/customer-onboarding-v5/PUT/api/v5/client/{clientHashId}/customer/{customerHashId}) request to: #### Update customer details You can update the details of an approved customer to reflect the latest information. Details you can update include: - Update business details or expected account usage. - Add or modify stakeholder information, such as UBOs or directors. - Replace or update applicant details. - Upload additional documents for the business, stakeholders, or applicant. - Resubmit a rejected customer, if permitted. - Resubmission is allowed only when `status = rejected` and `isResubmissionAllowed` = **true**. - If `isResubmissionAllowed` = **false**, the application cannot be resubmitted. * The request body structure matches the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request, except for the `authenticationCode`, *which is required for clients operating under EU/UK/NL regulatory requirements*. * Always submit the complete request body with the latest details, including all supporting documents. Lifecycle ## Status lifecycle The following table defines the different statuses that can be returned when onboarding a customer. When onboarding customers, the most common changes in `status` include: - **pending** when the application is install submitted. - Then updates to **clear** or **rejected** when the initial review is complete. - RFIs may occur at **pending** or after **clear**. | `status` | `subStatus` | **Remarks** | **Next action** | | ------------ | ------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **pending** | **null** | Application is submitted. | Wait for the webhook event for next steps to take. | | **pending** | **awaiting\_kyc** | Application submitted and awaiting KYC completion. | The customer must complete verification for all applicants and stakeholders in the Pre-built KYC form or through KYC API | | **pending** | **under\_review** | Application under review by Nium. | Wait for Nium to take further action. | | `error` | — | The application encountered an error. | Contact [Nium Support](mailto:support@nium.com). | | **pending** | **rfi\_requested** | Nium has raised a Request for Information (RFI). | The customer must respond using the RFI hosted form. | | `rejected` | — | The application was rejected due to issues identified during review. | Check the webhook for the `resubmissionAllowed` flag. Reinitiate the application if allowed. | | **clear** | — | The customer has been successfully onboarded. | Start processing transactions. | | **clear** | **awaiting\_kyc** | Nium raised an RFI post-onboarding (for example, due to updates, ongoing screening, or ongoing due diligence). | The customer must respond using the RFI hosted form. | | **clear** | **rfi\_requested** | Nium raised an RFI post-onboarding (for example, due to updates, ongoing screening, or ongoing due diligence). | The customer must respond using the RFI hosted form. | | **clear** | **under\_review** | Application update or ongoing screening is under Nium’s review. | No action required unless Nium requests additional information. | | `suspended` | — | The customer account is suspended. | Await communication from Nium. | | `suspended` | **rfi\_requested** | The account is suspended and an RFI has been raised by compliance. | Respond to the RFI. | | `closed` | — | The customer account has been closed. | | | `terminated` | — | The customer account has been terminated by Nium compliance. | No further action is possible. | ## Webhooks **Customer Status Webhook** - After receiving the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) response, Nium sends a webhook to your configured URL whenever `status` or `subStatus` changes. In the webhook event, `template` is set to **CUSTOMER\_STATUS\_WEBHOOK**. #### Example event ```json { "customerHashId": "5993e016-21b1-4c8f-9282-e5491546c47a", "template": "CUSTOMER_STATUS_WEBHOOK", "customerType": "INDIVIDUAL", "walletHashIds": [ "70adc339-5b3f-4711-ad82-39ed6420bd62" ], "externalId": "c3a2c77a-f451-4e4d-a212-48283dec4eac", "isResubmissionAllowed": "true", "subStatus": "", "clientHashId": "b23b124c-9cc8-4550-b66f-ed8250ff8a5e", "status": "rejected", "tags": [ { "value": "value", "key": "key" } ] } ``` **Customer Entity KYC Status Webhook**: To receive KYC status of the applicant/stakeholder when you send KYC through Submit KYC API, Nium sends a webhook to your configured URL whenever `kycStatus` changes. In this webhook event, `template` is set to **CUSTOMER\_ENTITY\_KYC\_STATUS**. #### Example event ```json { "customerHashId": "e65a7cb7-7c27-4379-8fdb-b70c99ac3e43", "template": "CUSTOMER_ENTITY_KYC_STATUS", "customerType": "corporate", "kycStatus": "submitted", "kycMode": "manual_kyc", "entityType": "applicant", "externalId": "1234", "referenceId": "b80612ea-1822-4788-aa3d-f0b4585f6015", "clientHashId": "4b349b2e-6db2-41ea-9f2e-a6aed49987d0" } ``` For more information, see [Notifications and Webhooks](/docs/developers/notifications-and-webhooks). ## Requests for Information (RFIs) When the application `status` is **pending** and `subStatus` is **under\_review**, Nium’s compliance team may raise a Request for Information (RFI). This updates the `subStatus` to **rfi\_requested** in the webhook response. To respond, use the [Pre-built RFI Form](/docs/developers/pre-built-forms/rfi-forms) ## Response codes Perform the following actions based on the returned HTTP status code: | **HTTP code** | **Next step** | | ------------- | ----------------------------------------------------------------------------- | | `200` | Check the [status lifecycle](#status-lifecycle) to determine the next action. | | `400` | Correct the data and resubmit the application. | | `500` | Temporary server error. Retry the onboarding request. | ### 200 After submitting the Onboard Customer v5 request, Nium creates the customer record and returns key details in the response. Store the following information for future reference, along with any errors or remarks: - `customerHashId` - `walletHashId` - Customer details provided in the onboarding request ### 400 If basic validation fails, Nium returns an `HTTP 400 Bad Request` in response to the Onboard Customer v5 request. Review the `errors` field in the response, correct the customer details, and resubmit the request. ```json { "errors": [ { "code": "missing_required_documents", "description": "trust_deed is expected for business", "field": "documents" }, { "code": "missing_required_fields", "description": "businessName is required", "field": "businessName" } ] } ``` #### 400 error codes The following table lists common `HTTP 400 Bad Request` scenarios, their error codes, and example messages. | Scenario | Error Code | HTTP Code | Example Description | | ---------------------------------------------- | ---------------------------- | --------- | ------------------------------------------------------------------------ | | Missing mandatory fields | `missing_required_fields` | `400` | `Position title is required for individual stakeholder John Doe.` | | Invalid field value | `invalid_input` | `400` | `Field "countryCode" is invalid for stakeholder Jane Smith. Value: XYZ.` | | Customer already exists | `customer_exists` | `400` | `Customer already exists for the provided externalId.` | | Missing required documents | `missing_required_documents` | `400` | `Document is required for applicant John Doe. Value: Power of Attorney.` | | Duplicate external ID | `duplicate_external_id` | `400` | `Duplicate externalId detected.` | | Incomplete client setup (individual customers) | `incomplete_client_setup` | `400` | `Client configuration is incomplete. Contact Nium Support to resolve.` | ## Ongoing due diligence (ODD) Corporate customers approved more than one year ago are subject to *Ongoing Due Diligence (ODD)* — a periodic compliance review conducted based on each customer’s risk profile and transaction history. During the review, Nium’s compliance team may issue one or more *Requests for Information (RFIs)*. You must respond promptly to these requests to ensure the review is completed on time. Failure to respond can result in temporary account suspension. For more information, contact your Nium Account Manager or Nium Support. ### ODD process When a customer is undergoing *Ongoing Due Diligence (ODD)*, the following occurs: - The `status` field remains **clear**. - The **oddStatus** is set to `odd_due`. Customers can continue processing transactions as usual during this period and should update any outdated information as needed. Once Nium initiates the ODD process, - The `status` field remains **clear**. - The **oddStatus** changes to `odd_initiated`. - If an RFI is raised, the `subStatus` field changes to **rfi\_requested**, similar to the onboarding flow. - Use the *Hosted Form for RFI* request to respond. - Expired documents (for example, the latest *Business Registration Document* or other required records) will be requested through an RFI. - If new stakeholders are identified, you may be asked to provide their details and verification documents. - You may also be required to submit an updated ownership structure if any changes in shareholding are detected. To track ODD status changes, subscribe to the `CUSTOMER_ODD_STATUS_WEBHOOK` event. For more information, see [Customer ODD Status](/docs/developers/notifications-and-webhooks/platform-events/customer-odd-status). The `oddStatus` field returns the following: | **oddStatus** | **Description** | | --------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `odd_due` | The customer is due for **Ongoing Due Diligence (ODD)**. A compliance officer will initiate the review shortly. | | `odd_initiated` | The ODD process has been initiated by a compliance officer. You may receive one or more **Requests for Information (RFIs)**. | | `odd_completed` | The ODD process is complete. No further action is required until the next review is due. | #### Example event ```json { "clientHashId": "86ce8d7b-f3fa-46d5-8d1c-53212aade5b5", "customerHashId":"857dc08e-dffa-4e9a-ad96-79041c8a7025", "externalId":"875329", "oddStatus":"odd_due", "template": "CUSTOMER_ODD_STATUS_WEBHOOK", "customerType":"corporate" } ``` ## Pre-built onboarding forms In addition to direct request-based onboarding, Nium also offers Pre-built Forms that let you launch compliant customer workflows without building your own front-end experience. These secure, fully hosted forms support onboarding and RFIs, while automatically aligning with regional KYC and KYB requirements. To learn more about enabling and using hosted experiences, see [Pre-built Onboarding Forms](/docs/developers/pre-built-forms). ## Update customer Use the [Update Customer v5](/api#tag/customer-onboarding-v5/PUT/api/v5/client/{clientHashId}/customer/{customerHashId}) request to change details for individual and corporate customers. Using the request, you can: #### For corporate customers - Add a new stakeholder. - Replace the applicant entirely. - Update any stakeholder field - requires the `referenceId` returned in the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) response, or fetch the details using the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) request. - Update any applicant field (requires the `referenceId` as above). - Update any business-related field. - Update or replace addresses. - Update bank account details #### For individual customers - Update any customer field. - Update or replace addresses. - Update bank account details --- # Fetch Constant Enums URL: https://docs.nium.com/docs/onboarding/customer-onboarding/fetch-constants-enums The Fetch Corporate Constants The [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request returns acceptable values of various fields that need to be passed via the [Customer Onboarding v5](/api#tag/customer-onboarding-v5) request. ## Constants endpoint You need to integrate this API as part of your onboarding process. You need to also display its output to your customers as a dropdown list while they complete your onboarding form. Use this API for all the fields listed below. ## `fieldName` to `category` Pass the `fieldName` as the `category` listed in the table below. The following are the categories in [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API. | Fetch Corporate Constants API `category` | Onboard Customer v5 API `fieldName` | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `annualTurnover` | `sizeOfBusiness.annualTurnover` | | `averageTransactionValue` | `expectedAccountUsage.debit.averageTransactionValue``expectedAccountUsage.credit.averageTransactionValue` | | `businessType` | `businessType``stakeholders.corporate[*].businessType` | | `capitalContribution` | `applicant.positions[*].capitalContribution``stakeholders.individual[*].positions[*].capitalContribution``stakeholders.corporate[*].positions[*].capitalContribution` | | `countryName` | `addresses.businessAddress.country``addresses.registeredAddress.country``applicant.address.country``stakeholders.individual[*].address.country``stakeholders.corporate[*].registeredCountry``natureOfBusiness.operatingCountries[*]``expectedAccountUsage.debit.topTransactionCountries[*]``expectedAccountUsage.credit.topTransactionCountries[*]` | | `countryOfOperation` | `natureOfBusiness.operatingCountries[*]``expectedAccountUsage.debit.topTransactionCountries[*]``expectedAccountUsage.credit.topTransactionCountries[*]` | | `documentType` | `documents[*].type``applicant.documents[*].type``stakeholders.individual[*].documents[*].type` | | `intendedUseOfAccount` | `expectedAccountUsage.intendedUses[*]` | | `industrySector` | `natureOfBusiness.industryCodes[*]` | | `listedExchange` | `listedExchange` | | `monthlyTransactionVolume` | `expectedAccountUsage.debit.monthlyTransactionVolume``expectedAccountUsage.credit.monthlyTransactionVolume` | | `monthlyTransactions` | `expectedAccountUsage.debit.monthlyTransactions``expectedAccountUsage.credit.monthlyTransactions` | | `position` | `applicant.positions[*].title``stakeholders.individual[*].positions[*].title``stakeholders.corporate[*].positions[*].title` | | `regulatedTrustType` | `regulatedTrustType[*]`\\\* Valid only for AU | | `restrictedCountries` | `restrictedCountries[*]`\\\* Required for the UK | | `isoState` | `addresses.registeredAddress.state``addresses.businessAddress.state``applicant.address.state``stakeholders.individual[*].address.state`\\\* Also pass countryCode in the parameter to fetch the state of that respective country. | | `streetType` | `addresses.businessAddress.streetType``addresses.registeredAddress.streetType`\\\* Valid only for AU, NZ addresses. | | `totalEmployees` | `sizeOfBusiness.totalEmployees` | | `trustBeneficiaryClass` | `applicant.positions[*].trustBeneficiaryClass``stakeholders.individual[*].positions[*].trustBeneficiaryClass`\*\*\*\* | | `unregulatedTrustType` | `unregulatedTrustType[*]` | ## Response The API response contains an array of code-description pairs that are valid for the given field. | Response field | Usage | | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | The valid values that need to be used in the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request for the given field. | | `description` | A description of the category code which can be shown to the applicant as a dropdown list. | --- # Submit KYC API URL: https://docs.nium.com/docs/onboarding/customer-onboarding/submit-kyc-api The Submit KYC API lets you programmatically submit identity verification details for a customer or entity. Use this API as an alternative to the Pre-built KYC Form. The Submit KYC API lets you programmatically submit identity verification details for a customer or entity. Use this API as an alternative to the [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form). For corporate customers, the applicant and all individual stakeholders are treated as separate entities. You must call the Submit KYC API separately for each entity to complete their respective KYC process. Initiate KYC only after you receive a webhook with `subStatus: awaiting_kyc`. See [Step 6 of the onboarding flow](/docs/onboarding/customer-onboarding#step-6-complete-kyc-verification). ## API reference **`POST /api/v5/client/{clientHashId}/customer/{customerHashId}/submitKyc`** See [Submit KYC](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customer/{customerHashId}/submitKyc) for the full API reference. ## Path parameters | Parameter | Type | Required | Description | | ---------------- | ------ | -------- | -------------------------------------------------------------------------------------- | | `clientHashId` | string | Yes | Unique client identifier generated and shared before API handshake. | | `customerHashId` | string | Yes | Unique hash ID of the customer received in the response of the Create Customer v5 API. | ## Request body parameters | Field | Required | Type | Description | | ---------------------------------------------- | ----------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `region` | Mandatory | string | Regulatory region where the customer is being onboarded (for example, `US`). | | `entityType` | Mandatory | enum | Type of entity for which KYC is being submitted. Values: `individual_stakeholder`, `applicant`, `individual_customer`. | | `isResident` | Mandatory | boolean | Whether the entity is a resident of the specified `region`. Set to `false` if the entity resides outside the region (for example, if `region = US` and the entity resides in `GB`). | | `entityReferenceId` | Mandatory | string | The `referenceId` of the entity returned in the Create Customer v5 API response. You may also pass the `externalId` provided during customer creation. | | `kycMode` | Mandatory | enum | KYC verification method. Values: `e_kyc` (electronic, auto-verified), `biometric_kyc` (liveness check against their government-issued document) or`manual_kyc` (requires manual review by Nium compliance). | | `proofOfIdentityDocument` | Mandatory | array of object | Identity document details for the entity. See fields below. | | `proofOfIdentityDocument.type` | Mandatory | enum | Document type. Use `national_id` if `isResident = true`. If `isResident = false`, use `national_id`, `passport`, or `driver_licence`. | | `proofOfIdentityDocument.identificationNumber` | Mandatory | string | Identification number of the document (for example, nationalID number or passport number). | | `proofOfIdentityDocument.issuanceCountry` | Mandatory | string | Two-letter ISO country code of the country where the document was issued. Use the [Fetch Corporate Constants](/api#tag/customer-account---corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API with `category = countryName` for valid values. | | `proofOfIdentityDocument.expiryDate` | Conditional | date | Expiry date of the document. Required if `type` is `passport` or `driver_licence`. | | `proofOfIdentityDocument.fileIds` | Conditional | array of UUID | Required if `kycMode = manual_kyc`. Provide the `fileId` values from the [Upload File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) API response. | | `proofOfAddressDocument` | Optional | object | Address proof details. Acceptable documents are: Utility bill, bank statement, govt issued letter etc. | | `proofOfAddressDocument.type` | Optional | enum | Type of address document. Value: `proof_of_address`. | | `proofOfAddressDocument.fileIds` | Optional | array of string | `fileId` values from the [Upload File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) API response. | | `stakeholderDetails` | Optional | Object | New stakeholder data identified by Nium during verification. Applciable in case of AU region. | ## Sample requests ### For US Resident — electronic KYC (`isResident=true`, `kycMode=e_kyc`) ```json { "region": "US", "entityType": "applicant", "isResident": true, "kycMode": "e_kyc", "entityReferenceId": "REF123456", "proofOfIdentityDocument": [ { "type": "national_id", "identificationNumber": "1234", "issuanceCountry": "US" } ] } ``` ### For US Resident — manual KYC (`isResident=true`, `kycMode=manual_kyc`) ```json { "region": "US", "entityType": "individual_stakeholder", "isResident": true, "kycMode": "manual_kyc", "entityReferenceId": "8aaddf0f-a4c9-4c3c-bdd8-2534cb5a4008", "proofOfIdentityDocument": [ { "type": "passport", "identificationNumber": "123456789", "issuanceCountry": "US", "expiryDate":"2028-09-01", "fileIds": [ "6502ff10-86bf-43f9-ade8-3da16374acc2" ] },{ "type": "national_id", "identificationNumber": "123456789", "issuanceCountry": "US" } ], "proofOfAddressDocument": { "type": "proof_of_address", "fileIds": [ "1218ab50-500e-4c8c-98e8-2dd44068d044" ] } } ``` ### For US Non-resident — manual KYC (`isResident=false`, `kycMode=manual_kyc`) ```json { "region": "US", "entityType": "individual_stakeholder", "isResident": false, "kycMode": "manual_kyc", "entityReferenceId": "REF123456", "proofOfIdentityDocument": [ { "type": "passport", "identificationNumber": "JP10FAKAIV", "issuanceCountry": "GB", "fileIds": [ "1218ab50-500e-4c8c-98e8-2dd44068d044" ] } ], "proofOfAddressDocument": { "type": "proof_of_address", "fileIds": [ "1218ab50-500e-4c8c-98e8-2dd44068d044" ] } } ``` ### For US Non-resident — biometric KYC (`isResident=false`, `kycMode=biometric_kyc`) ```json { "region": "US", "entityType": "individual_stakeholder", "isResident": false, "kycMode": "manual_kyc", "entityReferenceId": "REF123456" } ``` ## Responses ### 200 — Success (manual\_kyc) ```json { "customerHashId": "83e9cb73-c8f3-4ada-8371-ac215826461q", "kycStatus": "initiated", "externalId": "357244f3-b4f9-4c54-92df-b472123a6067", "referenceId": "9215203c-8ba5-43e1-b780-70c2d77115ef", "entityType": "applicant", "kycMode": "manual_kyc" } ``` ### 200 — Success (biometric\_kyc) ```json { "customerHashId": "83e9cb73-c8f3-4ada-8371-ac215826461q", "kycStatus": "initiated", "externalId": "357244f3-b4f9-4c54-92df-b472123a6067", "referenceId": "9215203c-8ba5-43e1-b780-70c2d77115ef", "entityType": "applicant", "kycMode": "biometric_kyc", "redirectUrl":"https://idv.sandbox.nium.com/sandbox/compliance/callback/load?referenceNumber=4a72c7b1-ca24-4921-a414-470823f8e982" } ``` ### 400 — Bad Request The `errors` array in the response describes what failed. Correct the data and resubmit. ```json // Missing mandatory field { "errors": [ { "code": "missing_required_fields", "description": "entityReferenceId is required", "field": "entityReferenceId" } ] } // Invalid document type for the region/residency combination { "errors": [ { "code": "invalid_input", "description": "Invalid value 'passport'. Allowed values: [national_id]", "field": "proofOfIdentityDocument[0].type" } ] } // Invalid identification number format { "errors": [ { "code": "invalid_input", "description": "must match \"^\\d{4}$|^\\d{9}$\"", "field": "proofOfIdentityDocument[0].identificationNumber" } ] } ``` ## KYC status reference When a customer is created using the Create Customer v5 API, the response includes a `kycStatus` for each entity. | `kycStatus` | Description | Next action | | ------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------- | | `kyc_required` | KYC is required for this entity. | Call the Submit KYC API for this entity. | | `kyc_not_required` | KYC is not required for this entity. | No action required. | | `initiated` | KYC details submitted; verification initiated by Nium. | Wait for a `CUSTOMER_ENTITY_KYC_STATUS` webhook with the final status. | | `submitted` | Applicable for `manual_kyc`. KYC details submitted for review. | Terminal status — no further action required. | | `verified` | Applicable for `e_kyc`. KYC successfully verified. | Terminal status — no further action required. | | `failed` | Applicable for `e_kyc`. KYC verification failed. | Reinitiate KYC with `kycMode = manual_kyc`. | ## Webhooks Nium sends a `CUSTOMER_ENTITY_KYC_STATUS` webhook whenever the `kycStatus` of an entity changes. ```json { "clientHashId": "9f9e58c3-7b48-4cf7-8195-76a8a94f36ed", "customerHashId": "83e9cb73-c8f3-4ada-8371-ac215826461e", "template": "CUSTOMER_ENTITY_KYC_STATUS", "customerType": "corporate", "kycStatus": "verified", "kycMode": "e_kyc", "externalId": "357244f3-b4f9-4c54-92df-b472123a6067", "referenceId": "9215203c-8ba5-43e1-b780-70c2d77115ef" } ``` | Field | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------------------------------------------- | | `clientHashId` | UUID | Unique client identifier. | | `customerHashId` | UUID | Unique customer identifier. | | `template` | string | Always `CUSTOMER_ENTITY_KYC_STATUS`. | | `customerType` | enum | `individual` or `corporate`. | | `kycStatus` | enum | KYC status of the entity: `submitted`, `verified`, or `failed`. | | `kycMode` | enum | Verification mode used: `e_kyc` or `manual_kyc`. | | `externalId` | string | Client-provided unique ID of the entity. | | `referenceId` | UUID | Nium-generated unique ID of the entity. | | `redirectUrl` | string | Client needs to send this link to the applicant/stakehodler to complete the KYC verification on Nium page. | For more information, see [Notifications and Webhooks](/docs/developers/notifications-and-webhooks). --- # Letter of Authorization URL: https://docs.nium.com/docs/onboarding/customer-onboarding/letter-of-authorization A Letter of Authorization (LOA) or Power of Attorney (POWER_OF_ATTORNEY) is a document signed by a business signatory that authorizes an applicant to conduct financial transactions and related activities on behalf of the business. This document is critical because it verifies the applicant's authority to represent the business. A **Letter of Authorization (LOA)** or **Power of Attorney (POWER\_OF\_ATTORNEY)** is a document signed by a business signatory that authorizes an applicant to conduct financial transactions and related activities on behalf of the business. This document is critical because it verifies the applicant's authority to represent the business. *Live-authorization* is a digital process where a signatory authorizes the applicant without requiring physical documents or signatures. ## Regional requirements **APAC/UK** For customers in AU, NZ, SG, HK, UK, CA, and JP: If the applicant is not a *DIRECTOR*, *UBO* (Ultimate Beneficial Owner), or an equivalent role, they must submit a Letter of Authorization (`documentType` = **LOA**). - In the UK, use `POWER_OF_ATTORNEY`. - If the LOA is missing or incorrect, a compliance agent will raise an RFI (Request for Information). - The LOA must be issued and signed by directors or other authorized signatories. **US** For customers in the US: - If the applicant is not an officer, an LOA can be submitted. - If not submitted, the LOA will be requested via an RFI. **EU** For customers in the EU: - If the applicant is not a *DIRECTOR*, they must submit a `POWER_OF_ATTORNEY`. - If issued in a non-EEA country, the Power of Attorney must be certified by an apostille. - Alternatively, the applicant can nominate a director to provide live-authorization. - A live-authorization does not require an apostille, regardless of where it is issued. ## LOA template Applicants can use the following application, have it signed by directors or authorized signatories (or officers in the US): [Letter of Authorization (LOA)](https://github.com/nium-global/nium-assets/raw/014de0b57ef62158e8dd8aa7213e6f7d39631105/Letter%20of%20Authorizations%20\(LOA\)/LOA-letter-of-authorizatio.pdf) ## Live-authorization Live-authorization is an alternative to submitting a Power of Attorney. Applicants can nominate a director (or other signatory with equivalent powers) to provide digital authorization. Benefits of live-authorization include: - Removing the need for physical documents. - In the EU, avoids the requirement for a Power of Attorney certified by an apostille. Currently, live-authorization is available only in the EU but we're on brining this capability to more regions. ### Process 1. Applicant nominates a director as the Live-Authorizer and skips submitting a Power of Attorney. 2. Applicant completes biometric verification using a link (Onfido). 3. The nominated director receives a separate link (shared by the client), reviews applicant and authorization details, provides consent, and completes biometric verification. 4. This process creates a legally enforceable authorization equivalent to a signed LOA or Power of Attorney. Authorization page ## Implementation notes - If the applicant is not a Director, your UI should allow them to either: - Submit a Power of Attorney, or - Nominate a director for Live-authorization. - For the nominated director: - Pass `stakeholderDetails.isLiveAuthorizer` as **true** and `kycMode` as **biometric\_kyc**. - You receive an additional `kycUrl` in the Submit KYC API response. Share this link with the nominated director. - Do not submit a Power of Attorney for this applicant. - Once all required documents and biometric checks are completed (by the applicant, director, and others), the `substatus` updates to `under_review` and Nium reviews the application. - If Live-authorization fails, operations may request re-authorization or a Power of Attorney via RFI. ## Validations - Only one stakeholder can be nominated for live-authorization. - The position field must contain **DIRECTOR** if `isLiveAuthorizer` is set to **true**. - Currently, only directors are eligible for live-authorization. - `kycMode` **biometric\_kyc** must be used when `isLiveAuthorizer = true`. --- # Simulate v5 Onboarding Status URL: https://docs.nium.com/docs/onboarding/customer-onboarding/simulate-v5-onboarding-status Use the Simulate v5 Onboarding API to transition a customer's status and sub-status during sandbox testing. This lets you reproduce compliance scenarios—such as RFI requests, KYC submission, approvals, and rejections—without waiting for Nium's compliance team to act. This API is available in **sandbox only**. It has no effect in production environments. ## API reference **`POST /api/v5/simulations/onboard/{customerHashId}/transition`** **Base URL (Sandbox):** `https://gatewaysandbox.nium.com` See the [v1 simulation API](/api#tag/Customer/POST/api/v1/simulations/onboard/{customerHashId}/transition) for the previous-version equivalent. ## Request headers | Header | Type | Description | | --------------- | ------------------ | -------------------------------------------------- | | `x-api-key` | string | API key for authentication. | | `x-client-name` | string (≤32 chars) | Client name, required on every request. | | `x-request-id` | UUID (36 chars) | Unique request identifier; required on every call. | | `Content-Type` | string | Must be `application/json`. | ## Path parameters | Parameter | Type | Description | | ---------------- | ---- | ----------------------------------------------------------------------------------------------------------------- | | `customerHashId` | UUID | Unique identifier for the customer, generated during onboarding. The customer must be onboarded as a v5 customer. | ## Request body | Field | Type | Required | Description | | ----------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `nextAction` | string | Yes | The action to simulate. See [Supported actions](#supported-actions) for allowed values and state prerequisites. | | `requestInfoFor` | object | Conditional | Required when `nextAction` is `raise_rfi`. Specifies the document or field to request. See [requestInfoFor object](#requestinfofor-object). | | `isResubmissionAllowed` | boolean | Optional | Only applicable when `nextAction` is `reject`. When `false`, the customer cannot resubmit their application. Defaults to `true`. | ### Supported actions | `nextAction` | Prerequisite state | Expected outcome | Response message | | ------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------ | | `submit_kyc` | `subStatus` = `awaiting_kyc` | Customer moves out of `awaiting_kyc` to `rfi_requested`, `null`, or `under_review`. | `KYC submitted successfully.` | | `raise_rfi` | `subStatus` = `under_review`, `null`, or `rfi_requested` | `subStatus` updates to `rfi_requested`. Fetch RFI details to see the requested field. | `RFI Raised Successfully.` | | `clear` | `status` = `pending` or `error` | `status` updates to `clear`. | `Status updated successfully.` | | `reject` | `status` = `pending` or `error` | `status` updates to `rejected`. The `isResubmissionAllowed` flag is set as specified. | `Status updated successfully.` | ### `requestInfoFor` object Required when `nextAction` is `raise_rfi`. The object shape differs by customer type. **Individual customer** | Field | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `customerType` | string | Must be `individual`. | | `request` | string | Document or field to request. Allowed values: `passport`, `bankStatement`, `firstName`, `lastName`, `dateOfBirth`, `driversLicence`. | **Corporate customer** | Field | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `customerType` | string | Must be `corporate`. | | `request` | string | Document or field to request. Allowed values: `applicant_Address`, `applicant_Identity`, `stakeholder_Address`, `stakeholder_Identity`, `businessRegistrationDocument`, `corporateAddressProof`. | ## Sample requests ### Submit KYC Transitions a customer out of `awaiting_kyc`. ```json { "nextAction": "submit_kyc" } ``` ### Raise RFI — individual customer Transitions `subStatus` to `rfi_requested` and flags that the customer's first name is required. ```json { "nextAction": "raise_rfi", "requestInfoFor": { "customerType": "individual", "request": "firstName" } } ``` ### Raise RFI — corporate customer Transitions `subStatus` to `rfi_requested` and requests an applicant identity document. ```json { "nextAction": "raise_rfi", "requestInfoFor": { "customerType": "corporate", "request": "applicant_Identity" } } ``` ### Raise RFI — minimal (no document specified) ```json { "nextAction": "raise_rfi" } ``` ### Clear (approve) Transitions `status` to `clear`. ```json { "nextAction": "clear" } ``` ### Reject — resubmission allowed ```json { "nextAction": "reject" } ``` ### Reject — resubmission not allowed ```json { "nextAction": "reject", "isResubmissionAllowed": false } ``` ## Responses ### 200 — Success The action was applied. The customer's `status` or `subStatus` is updated and a webhook is dispatched to the configured callback URL. ```json { "message": "RFI Raised Successfully." } ``` Possible messages correspond to the action performed: | `nextAction` | `message` | | ------------ | ------------------------------ | | `submit_kyc` | `KYC submitted successfully.` | | `raise_rfi` | `RFI Raised Successfully.` | | `clear` | `Status updated successfully.` | | `reject` | `Status updated successfully.` | ### 404 — Customer not found or not a v5 customer ```json // Customer not found { "errors": [ { "code": "sim_invalid_customer_hash_id", "description": "Customer Not found with customerHashId - {customerHashId}" } ] } // Customer exists but was not onboarded as v5 { "errors": [ { "code": "sim_customer_not_v5", "description": "Customer with customerHashId - {customerHashId} is not onboarded as a v5 customer" } ] } ``` ### 422 — Invalid action for current state Returned when the requested `nextAction` is not allowed from the customer's current `status` or `subStatus`. ```json { "errors": [ { "code": "sim_invalid_next_action", "description": "Current status - 'pending'/subStatus - 'awaiting_kyc' doesn't allow action 'raise_rfi'. Allowed action from current state: submit_kyc." } ] } ``` ## Related - [Customer Onboarding v5](/docs/onboarding/customer-onboarding) — full onboarding flow and status lifecycle. - [Submit KYC API](/docs/onboarding/customer-onboarding/submit-kyc-api) — programmatic KYC submission. - [Notifications and Webhooks](/docs/developers/notifications-and-webhooks) — customer status webhook reference. --- # AU Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/au-onboarding AU onboarding combines regulatory obligations under Australia’s AML/CTF regime with configurable identity verification methods. It includes: - Business verification (KYB) - Individual identity verification (KYC) - Beneficial ownership disclosure (> 25%) - Compliance review and approval This guide explains how onboarding works in Australia for business, implementation, and technical teams. ## Regulatory context Australian onboarding is governed by Anti-Money Laundering and Counter-Terrorism Financing (AML/CTF) requirements. These regulations require: - Verification of business existence - Identification of Ultimate Beneficial Owners (UBOs) - Identity verification of authorized representatives As a result: - Registry lookup may be used for corporate verification - Document submission may be required - Compliance approval is mandatory before activation ## Onboarding overview Australia onboarding supports: - Electronic KYB (eKYB) - Manual KYB - Electronic KYC (eKYC) - Manual KYC (for individuals, corporate applicants, and stakeholders) Manual review may occur when: - Registry lookup fails - Electronic verification fails - Required stakeholder roles are missing - Ownership structures are complex - Documentation is incomplete or inconsistent ## Responsibility ### Client responsibilities The client's onboarding responsibilities include: - Collect accurate business and stakeholder information - Declare all required stakeholder roles - Declare UBOs (> 25% ownership) - Capture applicant attestation - Upload required documents - Ensure stakeholders complete identity verification ### Nium responsibilities Nium's onboarding responsibilities include: - Retrieve registry information - Validate identity and document submissions - Conduct compliance checks - Raise RFIs (Requests for Information) if required - Approve or reject onboarding ## Business verification (KYB) Australia supports both **Electronic KYB (eKYB)** and **Manual KYB**. ### Electronic KYB (eKYB) Electronic KYB retrieves publicly available company information from Australian registries; It: - Pre-fills corporate data - Reduces document collection requirements - Helps reduce onboarding friction - Speeds up approvals #### Step 1: Fetch public corporate details To support electronic KYB (eKYB), you can retrieve publicly available corporate details before creating the customer. This step is optional and helps the customer confirm the correct registered entity. Collect the following from the customer: - `businessRegistrationNumber` - `countryCode` Use the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) request to fetch details that are available for the corporation. This request returns publicly available information associated with the included `businessRegistrationNumber`. Display the returned results to the applicant and allow them to: - Select the correct `businessName` - Confirm the `businessRegistrationNumber` - Review any additional returned details The request may return multiple results for a given `businessRegistrationNumber`. In this case, the applicant must select the correct entity. If no results are returned: - Use the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) and include all the details you have available in the request body. - The application will follow the manual KYB flow. - Electronic KYB (eKYB) will not apply. #### Step 2: Verify and complete corporate details Verify the submitted details: - Confirm submitted data with the applicant - Collect any missing information - Add stakeholder details #### Step 4: Upload required documents Document upload is required when: - Registry data is incomplete - Additional documents as required for verification. For more information, see [AU Required Documents](/docs/onboarding/customer-onboarding/au-onboarding/required-documents) Use the [Create a File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload the required documents. For more information, see [Uploading documents](/docs/onboarding/customer-onboarding#uploading-documents). The response returns a `fileId`. This `fileId` must be referenced in the onboarding request. For a complete list, see [AU Required Documents](/docs/onboarding/customer-onboarding/au-onboarding/required-documents). #### Step 5: Applicant declaration The authorized representative must confirm: > I certify that I am an authorized representative of the customer.\ > All information and documents provided are complete and accurate.\ > I confirm that all UBOs have been disclosed and that I have accepted > the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture via clickwrap and submit: | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ----------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of declaration | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | #### Step 6: Submit onboarding request Use [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) and include: - Corporate details - Stakeholder details - `searchId` (if applicable) - Uploaded `fileId` references - Applicant attestation fields ## Individual verification (KYC) Australia supports both **Electronic KYC (eKYC)** and **Manual KYC** for: - Individual customers - Corporate applicants - Directors - UBOs - Stakeholders ### Step 1: Create customer Create the individual using [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). After submission: | status | substatus | | --------- | --------- | | `pending` | `null` | Nium will send the webhook once substatus changes to `awaiting_kyc`. **Please note:** Initiate KYC verification process only after you receive substatus as `awaiting_kyc`. When the client submits an application, it goes through a verification process. During this verification, additional stakeholders may be identified. Therefore, whenever the application sub-status changes to `awaiting_kyc`, perform a Get Customer API call to check whether any new stakeholders have been added. If new stakeholders are present, initiate the KYC process for those stakeholders as well before proceeding with the application. ### Step 2: Access Pre-built KYC form Send the Pre-built KYC Form link to the applicant. The applicant accesses the Pre-built KYC form. Access is protected by a One-Time Password (OTP) sent to the email the applicant used to register. ### Step 3: Verify identity In Australia, identity verification is determined by **residency status**, not by role (applicant vs stakeholder). Each applicant and individual stakeholder must complete identity verification separately. Verification options differ for: - AU residents - Non-AU residents | Residency | Electronic | Biometric | Manual | | --------------- | --------------- | --------------- | ------ | | AU resident | Yes (preferred) | Yes (fallback) | Yes | | Non-AU resident | No | Yes (preferred) | Yes | ##### AU residents AU residents can complete verification using one of the following: - Electronic verification (preferred):\ Identity is verified automatically when the individual clicks **Verify** in the Pre-built KYC form.\ No document upload is required if verification succeeds. - Biometric verification: If automatic verification fails, the individual can complete biometric verification using: - A live selfie - A passport or driver licence - Manual verification: The individual uploads either a: - Passport - Drivers licence Manual verification can result in longer review times due to compliance review. ##### Non-AU resident individuals Non-AU residents cannot use electronic verification. They must verify their identity using one of the following: - Biometric verification: Live selfie with either a: - Passport, - Drivers licence Biometric verification typically results in faster approval than manual review. - Manual verification: The applicant uploads either a: - Passport - Drivers licence Manual submissions are reviewed by Nium's compliance team. ### Step 4: Compliance review After KYC completion: | status | substatus | | --------- | -------------- | | `PENDING` | `UNDER_REVIEW` | Nium’s compliance team then reviews submissions offline. If additional information is required: - An RFI is raised - The customer responds via the RFI Hosted Form Final decision: | Outcome | status | | -------- | ---------- | | Approved | `clear` | | Rejected | `rejected` | Webhook notifications are sent for all status transitions. For next steps based on application status, see[Customer Lifecycle](/docs/onboarding/individual-customers/customer-lifecycle). ## Stakeholder and UBO requirements ### Ultimate Beneficial Owner - All shareholders owning more than 25% of shares (directly or indirectly) must be declared as an Ultimate Beneficial Owner (UBOs). - If no individual owns more than 25%, the most senior director must be declared as the UBO. - If no UBO is submitted, Nium may identify the UBO during compliance review. - For sole traders, the owner must be declared as the UBO. ### Multi-layer ownership If the customer has a multi-layer ownership structure: - All corporate stakeholders owning more than 25% (directly or indirectly) must be declared. - Corporate structure (ownership structure) documentation must be submitted to validate the ownership chain. For more information, see [Multi-layer ownership structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6). ## Position mapping | Business Entity Type | Director | Members | Partner | Representative | Settlor | Trustee | UBO | Shareholder | Signatory | Executor | Protector | Trust Beneficiary | | -------------------- | -------- | ------- | ------- | -------------- | ------- | ------- | --- | ----------- | --------- | -------- | --------- | ----------------- | | ASSOCIATION | Yes | — | Yes | — | Yes | Yes | Yes | — | — | — | — | — | | GOVERNMENT\_ENTITY | Yes | — | — | Yes | — | — | Yes | Yes | Yes | — | — | — | | PARTNERSHIP | Yes | — | Yes | — | — | — | Yes | Yes | Yes | — | — | — | | PRIVATE\_COMPANY | Yes | — | — | Yes | — | — | Yes | Yes | Yes | — | — | — | | PUBLIC\_COMPANY | Yes | — | — | Yes | — | — | Yes | Yes | Yes | — | — | — | | REGULATED\_TRUST | — | — | — | — | Yes | Yes | Yes | Yes | Yes | — | — | Yes | | SOLE\_TRADER | Yes | — | — | Yes | — | — | Yes | Yes | Yes | — | — | — | | UNREGULATED\_TRUST | — | — | — | — | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | A blank cell means the role is not applicable for that business type. To dynamically retrieve valid roles use the [Fetch Corporate Constants](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate) request. ## Adding Positions - **Directors:** Add all management directors as stakeholders. - **UBOs:** Tag anyone owning ≥ 25% (direct or indirect). If none, the most senior director becomes the UBO. - **Representatives/Signatories:** Add individuals authorized to transact or manage users (applicant is a Representative by default). - **Partners/Trustees/Settlors:** Include when applicable by entity type. - **Multi-layered companies:** Include all corporate stakeholders with ≥ 25% ownership and upload a **Corporate Structure** document (`documentType: CORPORATE_STRUCTURE`). ### Additional clarifications - For Associations, use `REPRESENTATIVE` for roles such as chair, secretary, or treasurer. - Some Partnerships may include `DIRECTOR` roles depending on structure. - Private and Public companies without an identifiable UBO may pass `SHAREHOLDER` with ownership percentage details. ## Related resources - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [Customer Onboarding v5](/api#tag/customer-onboarding-v5) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/au-onboarding/required-documents Learn which documents are required to onboard businesses and individuals registered in Australia. ## Corporate customers The following lists the documents required for all businesses and corporations. | Business Type | Document Type | | -------------------------------------------------------------------------------------- | --------------------- | | **ASSOCIATION** | **ASSOCIATION\_DEE** | | **GOVERNMENT\_ENTITY** / **SOLE\_TRADER** / **PUBLIC\_COMPANY** / **PRIVATE\_COMPANY** | N/A | | **LIMITED\_LIABILITY\_PARTNERSHIP** | **PARTNERSHIP\_DEED** | | **REGULATED\_TRUST** / **UNREGULATED\_TRUST** | **TRUST\_DEED** | Submit notarized business registration documents whenever possible. Non-notarized documents may delay approval as Nium verifies them from the source. ### Additional business documents Submit the following documents when applicable: #### REGISTER\_OF\_DIRECTORS and REGISTER\_OF\_SHAREHOLDERS Provide this document if the business registration document does not include a list of directors or shareholders. For faster approval, submit notarized copies. When using eKYB: - Include this document if a new director or shareholder is added who isn’t in the stakeholder list returned by the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) request. - If omitted, Nium will raise a \*\*Request for Information (RFI). #### PROOF\_OF\_BUSINESS Submit this document if no website is provided. It helps Nium verify the customer’s business activity. Accepted documents include: - Product catalog, brochure, marketing material, or business plan (preferred). - Contract, business agreement, or vendor agreement. - Photo of a physical store. - Invoice describing business operations, issued within the last year not preferred. #### CORPORATE\_STRUCTURE (Ownership Structure) Submit this document if the company has multiple ownership layers. It should include the names and share percentages of all shareholders to identify the ultimate beneficial owner (UBO). - See [Verifying Your Business in AU](https://www.nium.com/corporate-onboarding/verifying-your-business-in-australia#heading-6) for an example template. - For a complete list of accepted document types, see [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category). Ownership Chart ### Stakeholder verification Stakeholders such as **SIGNATORY**, **REPRESENTATIVE**, **ultimate beneficial owners (UBOs)**, **TRUSTEE**, or \*\*PARTNER \*\* can verify their identity through **manual KYC** or **electronic KYC (eKYC)**. #### Electronic KYC Submit: - A live selfie with a valid passport or national ID. #### Manual KYC Ask the customer to submit a color copy of a valid passport or driver's licence (black-and-white copies are not accepted). All manual KYC documents undergo fraud checks. If Nium cannot verify authenticity, an **RFI** will be raised. ## Individual customers Individual applicants must always complete **electronic KYC**. Submit: - A live selfie with a **passport** or **driver's license**. - **Power of Attorney**, certified by Apostille, if the applicant is not a company director. For more information, see: - [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category) - [Verifying Your Business in Australia](https://www.nium.com/corporate-onboarding/verifying-your-business-in-australia) --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/au-onboarding/required-parameters Learn the required parameters, validation rules, and sample payloads for onboarding individual and corporate customers in Australia using the Customer Onboarding v5 request. The following guide includes the details that are required when creating a customer using the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request, along with validation rules and sample requests. Use this request to create customers to onboard in Australia. The endpoint accepts both individual and corporate customer. For a breakdown of the request and parameters, see [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). ## Endpoint URL POST `/api/v5/client/{clientHashId}/customers` ## Path Parameters | **Parameter** | **Type** | **Required** | **Description** | | -------------- | -------- | :----------: | ------------------------------------------------------------------------ | | `clientHashId` | string | Yes | Unique client identifier, generated and shared before the API handshake. | ## Body Parameters | **Parameter** | **Type** | **Required** | **Accepted Values / Notes** | | ------------- | -------- | :----------: | --------------------------------------------------------------------- | | `type` | string | Yes | `individual` or `corporate`. | | `kycType` | string | Yes | `minimum` or `full`. Use `full` when onboarding for payouts. | | `region` | string | Yes | Use `AU`. | | `externalId` | string | Optional | Client-defined unique ID (max 36). Returned in webhooks and GET APIs. | ## Individual Customers ### Personal Information | **Field** | **Type** | **Required** | **Notes** | | ------------------- | -------- | :----------: | --------------------------------------------------------------------------------------------------- | | `firstName` | string | Yes | Max 40. | | `middleName` | string | Optional | Max 40. | | `lastName` | string | Yes | Max 40. | | `email` | string | Yes | Max 60; must match the [valid email regex](/docs/developers/nium-api#regular-expression-for-email). | | `nationality` | enum | Yes | Category: `countryName`. | | `mobile` | numeric | Yes | Without country code; max 15 digits. | | `mobileCountryCode` | numeric | Yes | Max 6 digits. | | `dateOfBirth` | date | Yes | `YYYY-MM-DD`; age ≥ 18. | | `isPep` | boolean | Yes | `true` if PEP. | | `birthCountry` | enum | Yes | Category: `countryName`. | ### Tax Details Provide at least one entry. | **Field** | **Type** | **Required** | **Notes** | | ------------ | -------- | :----------: | ------------------------ | | `taxCountry` | enum | Yes | Category: `countryName`. | | `taxNumber` | string | Yes | Max 64. | ### Billing Address | **Field** | **Type** | **Required** | **Notes** | | -------------- | ----------- | :----------: | ------------------------------------------------------- | | `addressLine1` | string | Yes | Max 100. | | `addressLine2` | string | Optional | Max 100. | | `city` | string | Yes | Max 50. | | `state` | enum/string | Conditional | Category: `state`. Optional if unavailable for country. | | `postcode` | string | Yes | Max 10. | | `country` | enum | Yes | Category: `countryName`. | ### Expected Account Usage | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `credit.topTransactionCountries` | Yes | Category: `countryName`. | | `debit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `debit.topTransactionCountries` | Yes | Destination countries for payouts. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other` is selected. Max 300 chars. | ### Bank Account Details (for refunds/returns) | **Field** | **Type** | **Required** | **Notes** | | -------------------- | -------- | :----------: | ---------------------------------------------- | | `accountName` | string | Yes | Registered bank name; max 140. | | `accountNumber` | string | Yes | Max 35. | | `bankCountry` | string | Yes | ISO 3166-1 alpha-2. | | `bankAccountType` | string | Conditional | For example, `savings`, `checking`, `current`. | | `bankName` | string | Conditional | Max 255. | | `currency` | string | Yes | ISO 4217 (for example, `USD`, `AUD`). | | `routingCodes.type` | string | Yes | For example, `SWIFT`, `ABA`, `BRANCH_CODE`. | | `routingCodes.value` | string | Yes | Matches the selected type. | ## Corporate Customers (Full KYC) ### Business Information | **Field** | **Type** | **Required** | **Notes** | | ---------------------------- | -------- | :----------: | ---------------------------------------------------------------- | | `businessType` | enum | Yes | Category: `businessType`. | | `businessName` | string | Yes | Max 80. | | `tradeName` | string | Optional | If not available, set equal to `businessName`. | | `businessRegistrationNumber` | string | Yes | Max 30. | | `registeredDate` | date | Yes | `YYYY-MM-DD`; past date. | | `registeredCountry` | enum | Yes | Category: `countryName`. | | `website` | string | Optional | URL or verified social profile; else upload `PROOF_OF_BUSINESS`. | | `isMultiLayeredCompany` | boolean | Yes | `true`/`false`. See the multi-layered structure guide. | ### Applicant Details | **Field** | **Type** | **Required** | **Notes** | | ------------------------------ | -------- | :----------: | ------------------------------------------------------------ | | `firstName` / `lastName` | string | Yes | Max 40 each. | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Yes | Max 60; valid email. | | `mobile` / `mobileCountryCode` | string | Yes | 15/6 digit limits. | | `isPep` | boolean | Yes | `true` if PEP. | | `positions` | array | Yes | Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable. | | `documents` | array | Conditional | `POWER_OF_ATTORNEY` required if applicant is not a director. | ### Stakeholders Stakeholders can be **individuals** or **corporates** with roles such as **UBO**, **Director**, **Partner**, \*\*Trustee \*\*, **Shareholder**. **Individual Stakeholders** | **Field** | **Required** | **Notes** | | ----------------------------------------------------- | :----------: | ------------------------------------------ | | `firstName`, `lastName`, `dateOfBirth`, `nationality` | Yes | Personal details. | | `isPep` | Yes | `true` if PEP. | | `positions` | Optional | For example, `UBO`, `Partner`, `Director`. | | `sharePercentage` | Conditional | Required when ownership ≥ 25%. | | `address` | Yes | Full residential address. | **Corporate Stakeholders** | **Field** | **Required** | **Notes** | | ---------------------------- | :----------: | --------------------------------------------- | | `businessName` | Yes | Registered name. | | `businessRegistrationNumber` | Yes | Max 30. | | `registeredCountry` | Yes | Category: `countryName`. | | `positions.title` | Yes | For example, `UBO`, `Shareholder`, `Trustee`. | | `sharePercentage` | Conditional | Required for UBO/Shareholder. | ### Nature of Business | **Field** | **Required** | **Notes** | | --------------------- | :----------: | ---------------------------------------------------------------- | | `operatingCountries` | Yes | All countries where the business operates. | | `industryCodes` | Yes | Category: `industrySector`. Multiple allowed. | | `industryDescription` | Conditional | 2–3 sentences if “Other” is selected or requested by Compliance. | > See [Prohibited Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories). ### Expected Account Usage (Corporate) | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Estimated total payins (AUD). | | `credit.monthlyTransactions` | Yes | Estimated count of monthly payins. | | `credit.averageTransactionValue` | Yes | Average payin value (AUD). | | `credit.topTransactionCountries` | Yes | Origin countries. | | `credit.topRemitters` | Yes | Up to 20 primary remitters (company names or entity types). | | `debit.monthlyTransactionVolume` | Yes | Estimated total payouts (AUD). | | `debit.monthlyTransactions` | Yes | Estimated count of monthly payouts. | | `debit.averageTransactionValue` | Yes | Average payout value (AUD). | | `debit.topTransactionCountries` | Yes | Destination countries. | | `debit.topBeneficiaries` | Yes | Up to 20 primary beneficiaries. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other`. | ### Size of business | **Field** | **Required** | **Notes** | | ---------------- | :----------: | ----------------------------------------------------------------------- | | `totalEmployees` | Yes | Category: `totalEmployees`. | | `annualTurnover` | Yes | Category: `annualTurnover`. If < 1 year old, provide expected turnover. | ## Device details | **Field** | **Type** | **Required** | **Notes** | | --------------- | -------- | :----------: | ----------------------------------------------------- | | `ipCountryCode` | enum | Yes | Country of origin of the IP; category: `countryName`. | | `deviceInfo` | string | Yes | OS of the device initiating the request. | | `ipAddress` | string | Yes | Valid IPv4 address. | | `sessionId` | string | Yes | Session identifier for the request. | ## Tags | **Field** | **Type** | **Required** | **Notes** | | ------------ | -------- | :----------: | ---------------------------------------- | | `tags` | object | Optional | Up to 15 client-defined key/value pairs. | | `tags.key` | string | Optional | Max 128; keys must be unique. | | `tags.value` | string | Optional | Max 255. | ## Examples ### Individual Customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "AU", "externalId": "ext-123", "firstName": "Jane1", "middleName": "", "lastName": "Smith1", "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-31 11:30:00", "email": "jane.smith3@example.com", "nationality": "AU", "dateOfBirth": "1990-05-15", "mobile": "41234589", "mobileCountryCode": "61", "billingAddress": { "addressLine1": "123 George Street", "addressLine2": "Suite 4", "city": "Sydney", "state": "AU-NSW", "postcode": "2000", "streetType": "CH", "country": "AU" }, "expectedAccountUsage": { "intendedUses": [ "IU104" ], "intendedUsesDescription": "", "credit": { "monthlyTransactionVolume": "MVAU01", "topTransactionCountries": [ "AU" ] }, "debit": { "monthlyTransactionVolume": "MVAU01", "topTransactionCountries": [ "AU" ] } }, "bankAccountDetails": { "accountName": "Jane Smith", "bankName": "Commonwealth Bank of Australia", "accountNumber": "12345678", "bankCountry": "AU", "currency": "AUD", "bankAccountType": "saving", "routingCodes": [ { "type": "BSB CODE", "value": "062000" } ] }, "deviceDetails": { "ipCountryCode": "AU", "deviceInfo": "Mac OS X 14.0", "ipAddress": "203.0.113.10", "sessionId": "sess-abc123-def456-ghi789" }, "tags": [ { "key": "source", "value": "web_app" } ] } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "c0ae32d9-8d28-482b-9f54-c8577b9741f4", "walletType": "base" } ], "customerHashId": "c763fd2f-8476-4f8a-bb0f-fd6f0aa19d7f", "referenceId": "cc8c06cb-f300-4cd3-8d90-6e47605744c5", "status": "pending", "subStatus": null, "type": "individual", "kycType": "full", "region": "AU", "externalId": "ext-123", "tags": [ { "key": "source", "value": "web_app" } ], "segment": null, "firstName": "Jane1", "middleName": "", "lastName": "Smith1", "email": "jane.smith3@example.com", "nationality": "AU", "dateOfBirth": "1990-05-15", "mobile": "41234589", "mobileCountryCode": "61", "kycStatus": "kyc_required", "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-31 11:30:00", "deviceDetails": { "ipCountryCode": "AU", "deviceInfo": "Mac OS X 14.0", "ipAddress": "203.0.113.10", "sessionId": "sess-abc123-def456-ghi789" }, "expectedAccountUsage": { "intendedUses": [ "IU104" ], "intendedUsesDescription": "", "credit": { "monthlyTransactionVolume": "MVAU01", "topTransactionCountries": [ "AU" ] }, "debit": { "monthlyTransactionVolume": "MVAU01", "topTransactionCountries": [ "AU" ] } }, "bankAccountDetails": { "accountName": "Jane Smith", "accountNumber": "xxxxxxxx", "bankAccountType": "saving", "bankName": "Commonwealth Bank of Australia", "bankCountry": "AU", "currency": "AUD", "bankCode": null, "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "BSB CODE", "value": "xxxxxx" } ] }, "billingAddress": { "addressLine1": "123 George Street", "addressLine2": "Suite 4", "city": "Sydney", "postcode": "2000", "country": "AU", "state": "AU-NSW", "streetType": "CH" }, "kycMode": null, "documents": null, "redirectUrl": null } ``` ### Corporate Customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "AU", "externalId": "ext-1234", "businessName": "AU_BusinessName_1", "website": "https://monserrat.biz", "businessDescription": "Technology solutions and consulting services provider", "businessRegistrationNumber": "789564312", "registeredDate": "2015-03-15", "registeredCountry": "AU", "isMultiLayeredCompany": false, "businessType": "private_company", "tradeName": "Greenholt - West Inc", "bankAccountDetails": { "accountName": "Champlin - Spinka Corporate Account", "bankName": "Commonwealth Bank of Australia", "accountNumber": "12345678", "bankCountry": "AU", "currency": "AUD", "bankAccountType": "saving", "routingCodes": [ { "type": "BSB CODE", "value": "062000" } ] }, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-15 10:30:00", "addresses": { "isBusinessAddressSameAsRegisteredAddress": false, "registeredAddress": { "addressLine1": "1234 Corporate Blvd Suite 100", "addressLine2": "Building A", "city": "Wilmington", "state": "AU-NT", "postcode": "1980", "country": "AU" }, "businessAddress": { "addressLine1": "5678 Business Park Drive", "addressLine2": "Floor 5", "city": "Newark", "state": "AU-NT", "postcode": "0710", "country": "AU" } }, "applicant": { "externalId": "95d4c75b-089b-4aad-a9ab-f3b2360aa171", "firstName": "Tierra", "middleName": "James", "lastName": "White", "dateOfBirth": "1985-06-20", "nationality": "AU", "trustBeneficiaryClass": "C", "email": "test@nium.com", "mobile": "197894", "mobileCountryCode": "1", "sharePercentage": 45, "address": { "addressLine1": "123 George Street", "addressLine2": "Suite 4", "city": "Sydney", "state": "AU-NSW", "postcode": "2000", "country": "AU" }, "documents": [ { "type": "loa", "fileIds": [ "a9f55262-77ea-44a0-a5b8-b01bca79cc84" ] } ], "positions": [ { "title": "trust_beneficiary", "startDate": "2015-03-15" } ] }, "stakeholders": { "individual": [ { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16805", "firstName": "Robert", "middleName": "", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "AU", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": 30, "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "state": "AU-WA", "postcode": "10001", "country": "AU" }, "positions": [ { "title": "ubo", "startDate": "2016-01-20" } ] }, { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16802", "firstName": "Michael", "middleName": "", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "US", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": 30, "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "state": "US-NY", "postcode": "10001", "country": "SG" }, "positions": [ { "title": "SHAREHOLDER", "startDate": "2016-01-20" } ] } ], "corporate": [ { "externalId": "859ac163-08f0-4152-b26a-e96fce664372", "businessName": "Investment Holdings LLC", "businessRegistrationNumber": "123456789", "registeredCountry": "US", "sharePercentage": 25, "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "US", "CA", "GB" ], "industryCodes": [ "IS134" ], "industryDescription": "Comprehensive technology consulting and software development services specializing in enterprise solutions, cloud infrastructure, and digital transformation initiatives for Fortune 500 companies across North America and Europe" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "Business operations including vendor payments, payroll processing, and international transactions", "credit": { "monthlyTransactionVolume": "MVAU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVAU01", "topTransactionCountries": [ "US", "CA", "GB" ], "topRemitters": [ "Enterprise Client A", "Corporate Partner B" ] }, "debit": { "monthlyTransactionVolume": "MVAU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVAU01", "topTransactionCountries": [ "US", "CA", "MX" ], "topBeneficiaries": [ "Vendor Services Inc", "Technology Suppliers Ltd" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "AU008" }, "deviceDetails": { "ipCountryCode": "us", "deviceInfo": "Mozilla/5.0 Windows", "ipAddress": "192.168.1.100", "sessionId": "15aaa7ad-7625-4047-a2ce-6fe4ac476728" }, "tags": [ { "key": "customer_type", "value": "enterprise" }, { "key": "priority", "value": "high" } ], "documents": [ { "type": "business_registration_doc", "fileIds": [ "3bb4595c-2d1b-47b3-a951-08175b9013c2" ] } ] } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "ca60a683-62df-4068-a85a-ced831419ac9", "walletType": "base" } ], "customerHashId": "09485f49-4bee-4f35-bb8a-0e9c94c1a972", "referenceId": "fb3bf75a-e957-4af4-9e44-1a2ced66ee85", "status": "pending", "subStatus": null, "type": "corporate", "kycType": "full", "region": "AU", "externalId": "ext-1234", "tags": [ { "key": "customer_type", "value": "enterprise" }, { "key": "priority", "value": "high" } ], "segment": null, "businessName": "AU_BusinessName_1", "businessRegistrationNumber": "789564312", "registeredDate": "2015-03-15", "registeredCountry": "AU", "website": "https://monserrat.biz", "businessType": "private_company", "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-15 10:30:00", "formerName": null, "tradeName": "Greenholt - West Inc", "isMultiLayeredCompany": false, "addresses": { "registeredAddress": { "addressLine1": "1234 Corporate Blvd Suite 100", "addressLine2": "Building A", "city": "Wilmington", "postcode": "1980", "country": "AU", "state": "AU-NT", "streetType": null }, "isBusinessAddressSameAsRegisteredAddress": false, "businessAddress": { "addressLine1": "5678 Business Park Drive", "addressLine2": "Floor 5", "city": "Newark", "postcode": "0710", "country": "AU", "state": "AU-NT", "streetType": null } }, "natureOfBusiness": { "operatingCountries": [ "US", "CA", "GB" ], "industryCodes": [ "IS134" ], "industryDescription": "Comprehensive technology consulting and software development services specializing in enterprise solutions, cloud infrastructure, and digital transformation initiatives for Fortune 500 companies across North America and Europe" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "Business operations including vendor payments, payroll processing, and international transactions", "credit": { "averageTransactionValue": "ATVAU01", "monthlyTransactionVolume": "MVAU01", "monthlyTransactions": "ATC01", "topTransactionCountries": [ "US", "CA", "GB" ] }, "debit": { "averageTransactionValue": "ATVAU01", "monthlyTransactionVolume": "MVAU01", "monthlyTransactions": "ATC01", "topTransactionCountries": [ "US", "CA", "MX" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "AU008" }, "deviceDetails": { "ipCountryCode": "us", "deviceInfo": "Mozilla/5.0 Windows", "ipAddress": "192.168.1.100", "sessionId": "15aaa7ad-7625-4047-a2ce-6fe4ac476728" }, "bankAccountDetails": { "accountName": "Champlin - Spinka Corporate Account", "accountNumber": "xxxxxxxx", "bankAccountType": "saving", "bankName": "Commonwealth Bank of Australia", "bankCountry": "AU", "currency": "AUD", "bankCode": null, "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "BSB CODE", "value": "xxxxxx" } ] }, "applicant": { "externalId": "95d4c75b-089b-4aad-a9ab-f3b2360aa171", "firstName": "Tierra", "middleName": "James", "lastName": "White", "dateOfBirth": "1985-06-20", "nationality": "AU", "email": "test@nium.com", "mobile": "197894", "mobileCountryCode": "1", "sharePercentage": "45", "address": { "addressLine1": "123 George Street", "addressLine2": "Suite 4", "city": "Sydney", "postcode": "2000", "country": "AU", "state": "AU-NSW", "streetType": null }, "kycMode": null, "birthCountry": null, "taxDetails": null, "trustBeneficiaryClass": "C", "positions": [ { "title": "trust_beneficiary" } ], "referenceId": "e90178c7-76f4-4fe5-8fc5-83fbd7096e11", "kycStatus": "kyc_required", "documents": [ { "type": "loa", "fileIds": [ "a9f55262-77ea-44a0-a5b8-b01bca79cc84" ], "identificationNumber": null, "issuanceCountry": null, "expiryDate": null } ], "redirectUrl": null }, "stakeholders": { "individual": [ { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16805", "firstName": "Robert", "middleName": "", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "AU", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": "30", "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "postcode": "10001", "country": "AU", "state": "AU-WA", "streetType": null }, "trustBeneficiaryClass": null, "positions": [ { "title": "ubo" } ], "documents": null, "referenceId": "981752f4-fc3b-4fb2-805d-33c46fd0aa57", "kycMode": null, "kycStatus": "kyc_required", "redirectUrl": null }, { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16802", "firstName": "Michael", "middleName": "", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "US", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": "30", "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "postcode": "10001", "country": "SG", "state": "US-NY", "streetType": null }, "trustBeneficiaryClass": null, "positions": [ { "title": "SHAREHOLDER" } ], "documents": null, "referenceId": "8ad07371-dc95-4fe3-8b2d-32506280a2cb", "kycMode": null, "kycStatus": "kyc_not_required", "redirectUrl": null } ], "corporate": [ { "externalId": "859ac163-08f0-4152-b26a-e96fce664372", "businessName": "Investment Holdings LLC", "businessRegistrationNumber": "123456789", "registeredCountry": "US", "sharePercentage": "25", "businessType": null, "listedExchange": null, "positions": [ { "title": "UBO" } ], "referenceId": "b8341423-b8e6-46a8-ae4e-bdb852a85444", "kycStatus": "kyc_not_required" } ] }, "documents": [ { "type": "business_registration_doc", "fileIds": [ "3bb4595c-2d1b-47b3-a951-08175b9013c2" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). --- # EU Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/eu-onboarding EU onboarding combines regulatory obligations under European AML directives with configurable identity verification methods. It includes: - Business verification (KYB) - Individual identity verification (KYC) - Beneficial ownership disclosure (≥ 25%) - Compliance review and approval This guide explains how onboarding works in the European Union for business, implementation, and technical teams. ## Regulatory context EU onboarding is governed by Anti-Money Laundering (AML) directives and local regulatory requirements across EU member states. These regulations require: - Verification of business existence - Identification of Ultimate Beneficial Owners (UBOs ≥ 25%) - Identification of authorized representatives - Identity verification of applicants and required stakeholders As a result: - Registry lookup may be used for corporate verification - Document submission may be required - Compliance approval is mandatory before activation ## Onboarding overview EU onboarding supports: - Electronic KYB (eKYB) - Manual KYB - Electronic KYC (eKYC) - Manual KYC (for stakeholders only) Manual review may occur when: - Registry lookup fails - Electronic verification fails - Required stakeholder roles are missing - Ownership structures are complex - Documentation is incomplete or inconsistent ## Responsibility ### Client responsibilities The client's onboarding responsibilities include: - Collect accurate business and stakeholder information - Declare all required stakeholder roles - Declare UBOs (≥ 25% ownership) - Capture applicant attestation - Upload required documents - Ensure stakeholders complete identity verification ### Nium responsibilities Nium's onboarding responsibilities include: - Retrieve registry information (when eKYB is used) - Validate identity and document submissions - Conduct compliance checks - Raise RFIs (Requests for Information) if required - Approve or reject onboarding ## Business verification (KYB) Nium supports both **Electronic KYB (eKYB)** and **Manual KYB** for EU businesses. ### Electronic KYB (eKYB) Electronic KYB retrieves publicly available company information from EU registries. It: - Pre-fills corporate data - Reduces document collection requirements - Improves customer experience - Speeds up approvals #### Step 1: Fetch public corporate details Collect: - `businessRegistrationNumber` - `countryCode` Use the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) request. Store the returned `publicDetailsId`. If no details are returned, proceed with manual KYB using [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). #### Step 2: Fetch exhaustive corporate details Use the [Fetch Exhaustive Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/exhaustiveDetailsSearch) request and include the `publicDetailsId`. Store the returned `searchId`. This is a chargeable API. Use it only once per customer. Contact your Nium account manager or [Nium Support](mailto:support@nium.com) for pricing details. #### Step 3: Verify and complete corporate details - Confirm submitted data with the applicant - Verify directors and UBO information - Collect any missing required information - Add stakeholder details Stakeholders may complete verification electronically or manually. #### Step 4: Upload required documents Document upload is required when: - `searchId` is not provided - Registry data is incomplete - Additional documents are requested during review Use the [Create a File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload the required documents. For more information, see [Uploading documents](/docs/onboarding/customer-onboarding#uploading-documents). The response returns a `fileId`. This `fileId` must be referenced in the onboarding request. For a complete list, see [EU Required Documents](/docs/onboarding/customer-onboarding/eu-onboarding/required-documents). #### Step 5: Applicant declaration The authorized representative must confirm: > I certify that I am an authorized representative of the customer.\ > All information and documents provided are complete and accurate.\ > I confirm that all UBOs have been disclosed and that I have accepted > the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture via clickwrap and submit: - `applicantDeclaration` - `applicantDeclarationTimestamp` (format: `YYYY-MM-DD HH:MM:SS`) #### Step 6: Submit onboarding request Use [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) and include: - Corporate details - Stakeholder details - `searchId` (if applicable) - Uploaded `fileId` references - Applicant attestation fields If `searchId` is omitted, the application proceeds through manual review. ## Individual verification (KYC) EU onboarding supports **Electronic KYC (eKYC)** for: - Individual customers - Corporate applicants - Directors - UBOs - Required stakeholders Manual KYC is available for stakeholders when required. ### Step 1: Submit application Create a customer using [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). After submission: After submission: | status | substatus | | --------- | --------- | | `pending` | `null` | Nium will send the webhook once substatus changes to `awaiting_kyc`. **Please note:** Initiate KYC verification process only after you receive substatus as `awaiting_kyc`. ### Step 2: Access Pre-built KYC form The applicant accesses Nium’s Pre-built KYC form. Access is protected by a One-Time Password (OTP) sent to the registered email. ### Step 3: Complete identity verification The applicant: - Uploads proof of identity - Completes live selfie verification Stakeholders must complete verification individually. ### Step 4: Compliance review After KYC completion: | status | substatus | | --------- | -------------- | | `PENDING` | `UNDER_REVIEW` | Nium’s compliance team reviews submissions offline. If additional information is required: - An RFI is raised - The customer responds via the RFI Hosted Form Webhook notifications are sent for all status transitions. ## Stakeholder and UBO requirements ### Ultimate Beneficial Owner (UBO) - All individuals owning ≥ 25% (directly or indirectly) must be declared as UBOs. - If no individual meets the threshold, the most senior director must be declared. - Corporate shareholders owning ≥ 25% must be declared. ### Stakeholder verification - All declared stakeholders must complete identity verification. - Electronic KYC is supported. - Manual verification is available for stakeholders when required. ### Multi-layer ownership If the customer has a multi-layer ownership structure: - All corporate stakeholders owning ≥ 25% (directly or indirectly) must be declared. - Corporate structure documentation must be submitted to validate the ownership chain. For more information, see [Multi-layer ownership structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6). ## Position mapping | Business type | DIRECTOR | PARTNER | REPRESENTATIVE | SETTLOR | SHAREHOLDER | SIGNATORY | TRUSTEE | UBO | | ------------------------------- | -------- | ------- | -------------- | ------- | ----------- | --------- | ------- | --- | | ASSOCIATION | Yes | | Yes | | Yes | Yes | | | | LIMITED\_LIABILITY\_PARTNERSHIP | | Yes | Yes | | | Yes | | Yes | | GOVERNMENT\_ENTITY | | | Yes | | | Yes | | | | PRIVATE\_COMPANY | Yes | | Yes | | Yes | Yes | | Yes | | PUBLIC\_COMPANY | Yes | | Yes | | Yes | Yes | | Yes | | SOLE\_TRADER | | | Yes | | | Yes | | Yes | | TRUST | | | Yes | Yes | | Yes | Yes | Yes | A blank cell means the role is not applicable for that business type. To dynamically retrieve valid roles use the [Fetch Corporate Constants](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate) request. ## Adding Positions - **Directors:** Add all management directors as stakeholders. - **UBOs:** Tag anyone owning ≥ 25% (direct or indirect). If none, the most senior director becomes the UBO. - **Representatives/Signatories:** Add individuals authorized to transact or manage users (applicant is a Representative by default). - **Partners/Trustees/Settlors:** Include when applicable by entity type. - **Multi-layered companies:** Include all corporate stakeholders with ≥ 25% ownership and upload a **Corporate Structure** document (`documentType: CORPORATE_STRUCTURE`). ## Related resources - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [Customer Onboarding v5](/api#tag/customer-onboarding-v5) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/eu-onboarding/required-documents Learn which documents are required to onboard businesses and individuals registered in the European Union (EU). For more details about onboarding applicants in Europe, see [EU Onboarding](/docs/onboarding/customer-onboarding/eu-onboarding). ## Corporate customers The documents required for both **manual KYB** and **electronic KYB (eKYB)**, based on the business entity type. | Business Type | Document Type (Manual KYB) | Document Type (eKYB) | | :----------------------------------------- | :--------------------------------------------------------------------------------------------- | :-------------------- | | **ASSOCIATION** | **ASSOCIATION\_DEED** | **ASSOCIATION\_DEED** | | **GOVERNMENT\_ENTITY** / **SOLE\_TRADER** | **BUSINESS\_REGISTRATION\_DOC** | N/A | | **LIMITED\_LIABILITY\_PARTNERSHIP** | **PARTNERSHIP\_DEE**D | **PARTNERSHIP\_DEED** | | **PUBLIC\_COMPANY** / **PRIVATE\_COMPANY** | **BUSINESS\_REGISTRATION\_DOC** / **REGISTER\_OF\_DIRECTORS** / **REGISTER\_OF\_SHAREHOLDERS** | N/A | | **TRUST** | **TRUST\_DEED** | **TRUST\_DEED** | Submit notarized business registration documents whenever possible. Non-notarized documents may delay approval as Nium verifies them from the source. ### Additional business documents Submit the following documents when applicable: #### REGISTER\_OF\_DIRECTORS and REGISTER\_OF\_SHAREHOLDERS Provide this document if the business registration document does not include a list of directors or shareholders. For faster approval, submit notarized copies. When using eKYB: - Include this document if a new director or shareholder is added who isn’t in the stakeholder list returned by the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) endpoint. - If omitted, Nium will raise a Request for Information (RFI). #### PROOF\_OF\_BUSINESS Submit this document if no website is provided. It helps Nium verify the customer’s business activity. Accepted documents include: - Product catalog, brochure, marketing material, or business plan (preferred). - Contract, business agreement, or vendor agreement. - Photo of a physical store. - Invoice describing business operations, issued within the last year not preferred. #### CORPORATE\_STRUCTURE (Ownership Structure) Submit this document if the company has multiple ownership layers. It should include the names and share percentages of all shareholders to identify the ultimate beneficial owner (UBO). - See [Verifying Your Business in EU](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6) for an example template. - For a complete list of accepted document types, see [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category). Ownership Chart ### Stakeholder documents Stakeholders such as **SIGNATORY**, **REPRESENTATIVE**, **ultimate beneficial owners (UBOs)**, **TRUSTEE**, or \*\*PARTNER \*\* can verify their identity through **manual KYC** or **electronic KYC (eKYC)**. #### Electronic KYC Submit: - A live selfie with a valid passport or national ID. - **Source of wealth**, if `isPEP` is **true**. #### Manual KYC Submit: - A color copy of a valid passport or national ID (black-and-white copies are not accepted). - **Source of wealth**, if `isPEP` = **true**. All manual KYC documents undergo fraud checks. If Nium cannot verify authenticity, an **RFI** will be raised. #### Source of wealth If any shareholder is a **Politically Exposed Person (PEP)**, include a document that explains the source of their wealth. This helps confirm the legitimacy of the funds used to operate the business. Include a written explanation and supporting documents: - Bank statements (personal or joint). - Employment income (salary, bonuses, or pension). - Loan or contract agreements. - Sale of assets (property or shares). - Inheritance or family wealth transfer. - Legal settlement compensation. - Profits or returns from legitimate businesses or investments. - Documents showing ownership of businesses or investments. - Other financial documents showing lawful income or assets. ## Individual customers Individual applicants must always complete **electronic KYC**. Submit: - A live selfie with a **passport** (for non-EU citizens) or **passport/national ID** (for EU citizens). - **Power of Attorney**, certified by Apostille, if the applicant is not a company director. - **Source of wealth**, if `isPEP` = **true**. For more information, see: - [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category) - [Verifying Your Business in the EU](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6) --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/eu-onboarding/required-parameters Learn the required parameters, validation rules, and sample payloads for onboarding individual and corporate customers in the EU using the Customer Onboarding v5 request. The following guide includes the details that are required when creating a customer using the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request, along with validation rules and sample requests. Use this request to create customers to onboard in Europe. The endpoint accepts both individual and corporate customer. For a breakdown of the request and parameters, see [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). ## Endpoint URL POST `/api/v5/client/{clientHashId}/customers` ## Path parameters | **Parameter** | **Type** | **Required** | **Description** | | -------------- | -------- | :----------: | ------------------------------------------------------------------------ | | `clientHashId` | string | Yes | Unique client identifier, generated and shared before the API handshake. | ## Body parameters | **Parameter** | **Type** | **Required** | **Accepted Values / Notes** | | ------------- | -------- | :----------: | --------------------------------------------------------------------- | | `type` | string | Yes | `individual` or `corporate`. | | `kycType` | string | Yes | `minimum` or `full`. Use `full` when onboarding for payouts. | | `region` | string | Yes | Use `EU`. | | `externalId` | string | Optional | Client-defined unique ID (max 36). Returned in webhooks and GET APIs. | ## Individual Customers ### Personal Information | **Field** | **Type** | **Required** | **Notes** | | ------------------- | -------- | :----------: | --------------------------------------------------------------------------------------------------- | | `firstName` | string | Yes | Max 40. | | `middleName` | string | Optional | Max 40. | | `lastName` | string | Yes | Max 40. | | `email` | string | Yes | Max 60; must match the [valid email regex](/docs/developers/nium-api#regular-expression-for-email). | | `nationality` | enum | Yes | Category: `countryName`. | | `mobile` | numeric | Yes | Without country code; max 15 digits. | | `mobileCountryCode` | numeric | Yes | Max 6 digits. | | `dateOfBirth` | date | Yes | `YYYY-MM-DD`; age ≥ 18. | | `isPep` | boolean | Yes | `true` if PEP. | | `birthCountry` | enum | Yes | Category: `countryName`. | ### Tax Details Provide at least one entry. | **Field** | **Type** | **Required** | **Notes** | | ------------ | -------- | :----------: | ------------------------ | | `taxCountry` | enum | Yes | Category: `countryName`. | | `taxNumber` | string | Yes | Max 64. | ### Billing Address | **Field** | **Type** | **Required** | **Notes** | | -------------- | ----------- | :----------: | ------------------------------------------------------- | | `addressLine1` | string | Yes | Max 100. | | `addressLine2` | string | Optional | Max 100. | | `city` | string | Yes | Max 50. | | `state` | enum/string | Conditional | Category: `state`. Optional if unavailable for country. | | `postcode` | string | Yes | Max 10. | | `country` | enum | Yes | Category: `countryName`. | ### Expected Account Usage | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `credit.topTransactionCountries` | Yes | Category: `countryName`. | | `debit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `debit.topTransactionCountries` | Yes | Destination countries for payouts. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other` is selected. Max 300 chars. | ### Bank Account Details (for refunds/returns) | **Field** | **Type** | **Required** | **Notes** | | -------------------- | -------- | :----------: | ---------------------------------------------- | | `accountName` | string | Yes | Registered bank name; max 140. | | `accountNumber` | string | Yes | Max 35. | | `bankCountry` | string | Yes | ISO 3166-1 alpha-2. | | `bankAccountType` | string | Conditional | For example, `savings`, `checking`, `current`. | | `bankName` | string | Conditional | Max 255. | | `currency` | string | Yes | ISO 4217 (for example, `USD`, `EUR`). | | `routingCodes.type` | string | Yes | For example, `SWIFT`, `ABA`, `BRANCH_CODE`. | | `routingCodes.value` | string | Yes | Matches the selected type. | ## Corporate Customers (Full KYC) ### Business Information | **Field** | **Type** | **Required** | **Notes** | | ---------------------------- | -------- | :----------: | ---------------------------------------------------------------- | | `businessType` | enum | Yes | Category: `businessType`. | | `businessName` | string | Yes | Max 80. | | `tradeName` | string | Optional | If not available, set equal to `businessName`. | | `businessRegistrationNumber` | string | Yes | Max 30. | | `registeredDate` | date | Yes | `YYYY-MM-DD`; past date. | | `registeredCountry` | enum | Yes | Category: `countryName`. | | `website` | string | Optional | URL or verified social profile; else upload `PROOF_OF_BUSINESS`. | | `isMultiLayeredCompany` | boolean | Yes | `true`/`false`. See the multi-layered structure guide. | ### Applicant Details | **Field** | **Type** | **Required** | **Notes** | | ------------------------------ | -------- | :----------: | ------------------------------------------------------------ | | `firstName` / `lastName` | string | Yes | Max 40 each. | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Yes | Max 60; valid email. | | `mobile` / `mobileCountryCode` | string | Yes | 15/6 digit limits. | | `isPep` | boolean | Yes | `true` if PEP. | | `positions` | array | Yes | Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable. | | `documents` | array | Conditional | `POWER_OF_ATTORNEY` required if applicant is not a director. | ### Stakeholders Stakeholders can be **individuals** or **corporates** with roles such as **UBO**, **Director**, **Partner**, \*\*Trustee \*\*, **Shareholder**. **Individual Stakeholders** | **Field** | **Required** | **Notes** | | ----------------------------------------------------- | :----------: | ------------------------------------------ | | `firstName`, `lastName`, `dateOfBirth`, `nationality` | Yes | Personal details. | | `isPep` | Yes | `true` if PEP. | | `positions` | Optional | For example, `UBO`, `Partner`, `Director`. | | `sharePercentage` | Conditional | Required when ownership ≥ 25%. | | `address` | Yes | Full residential address. | **Corporate Stakeholders** | **Field** | **Required** | **Notes** | | ---------------------------- | :----------: | --------------------------------------------- | | `businessName` | Yes | Registered name. | | `businessRegistrationNumber` | Yes | Max 30. | | `registeredCountry` | Yes | Category: `countryName`. | | `positions.title` | Yes | For example, `UBO`, `Shareholder`, `Trustee`. | | `sharePercentage` | Conditional | Required for UBO/Shareholder. | ### Nature of Business | **Field** | **Required** | **Notes** | | --------------------- | :----------: | ---------------------------------------------------------------- | | `operatingCountries` | Yes | All countries where the business operates. | | `industryCodes` | Yes | Category: `industrySector`. Multiple allowed. | | `industryDescription` | Conditional | 2–3 sentences if “Other” is selected or requested by Compliance. | > See [Prohibited Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories). ### Expected Account Usage (Corporate) | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Estimated total payins (EUR). | | `credit.monthlyTransactions` | Yes | Estimated count of monthly payins. | | `credit.averageTransactionValue` | Yes | Average payin value (EUR). | | `credit.topTransactionCountries` | Yes | Origin countries. | | `credit.topRemitters` | Yes | Up to 20 primary remitters (company names or entity types). | | `debit.monthlyTransactionVolume` | Yes | Estimated total payouts (EUR). | | `debit.monthlyTransactions` | Yes | Estimated count of monthly payouts. | | `debit.averageTransactionValue` | Yes | Average payout value (EUR). | | `debit.topTransactionCountries` | Yes | Destination countries. | | `debit.topBeneficiaries` | Yes | Up to 20 primary beneficiaries. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other`. | ### Size of business | **Field** | **Required** | **Notes** | | ---------------- | :----------: | ----------------------------------------------------------------------- | | `totalEmployees` | Yes | Category: `totalEmployees`. | | `annualTurnover` | Yes | Category: `annualTurnover`. If < 1 year old, provide expected turnover. | ## Device details | **Field** | **Type** | **Required** | **Notes** | | --------------- | -------- | :----------: | ----------------------------------------------------- | | `ipCountryCode` | enum | Yes | Country of origin of the IP; category: `countryName`. | | `deviceInfo` | string | Yes | OS of the device initiating the request. | | `ipAddress` | string | Yes | Valid IPv4 address. | | `sessionId` | string | Yes | Session identifier for the request. | ## Tags | **Field** | **Type** | **Required** | **Notes** | | ------------ | -------- | :----------: | ---------------------------------------- | | `tags` | object | Optional | Up to 15 client-defined key/value pairs. | | `tags.key` | string | Optional | Max 128; keys must be unique. | | `tags.value` | string | Optional | Max 255. | ## Examples ### Individual customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "EU", "externalId": "C2ZfvtLAek9FKMmSHY", "firstName": "Sharma", "middleName": "", "lastName": "Test", "email": "pasumarthi.sashank+480@nium.com", "nationality": "FR", "isPep": false, "dateOfBirth": "2000-08-01", "birthCountry": "fr", "mobile": "2000000467", "mobileCountryCode": "31", "website": "www.test4.com", "taxDetails": [ { "taxNumber": "TAX123", "taxCountry": "FR" } ], "tags": [ { "key": "testing", "value": "Automation" }, { "key": "key1", "value": "value1" } ], "deviceDetails": { "ipCountryCode": "eu", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "intendedUsesDescription": "", "credit": { "monthlyTransactionVolume": "MVEU01", "averageTransactionValue": "", "topTransactionCountries": [ "GB" ] }, "intendedUses": [ "IU104" ], "debit": { "monthlyTransactionVolume": "MVEU01", "averageTransactionValue": "ATVEU01", "topTransactionCountries": [ "GB" ] } }, "bankAccountDetails": { "accountName": "Shane Sahrma", "bankName": "Bank of Shanghai (Hong Kong) Limited", "accountNumber": "77802", "bankCountry": "HK", "currency": "HKD", "bankAccountType": "saving", "routingCodes": [ { "type": "swift", "value": "BOSHHKHH" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1, Block 2, Area 3", "addressLine2": "Test Add 123, Building 1, Block 2, Area 3", "city": "Lorem ipsum dolor sit amet, consectetuer.", "state": "ddfd", "postcode": "SW1W", "country": "LT" } } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "a2f984d9-c978-4ec7-9dff-7281644efd65", "walletType": "base" } ], "customerHashId": "bec92c44-de95-4f09-8b54-3004548b6643", "status": "pending", "subStatus": null, "type": "individual", "kycType": "full", "region": "EU", "externalId": "C2ZfvtLAek9FKMmSHY", "tags": [ { "key": "testing", "value": "Automation" }, { "key": "key1", "value": "value1" } ], "segment": null, "firstName": "Sharma", "middleName": "", "lastName": "Test", "email": "pasumarthi.sashank+480@nium.com", "nationality": "FR", "dateOfBirth": "2000-08-01", "mobile": "2000000467", "mobileCountryCode": "31", "birthCountry": "fr", "taxDetails": [ { "taxCountry": "FR", "taxNumber": "TAX123" } ], "isPep": false, "deviceDetails": { "ipCountryCode": "eu", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "intendedUses": [ "IU104" ], "intendedUsesDescription": "", "credit": { "averageTransactionValue": "", "monthlyTransactionVolume": "MVEU01", "topTransactionCountries": [ "GB" ] }, "debit": { "averageTransactionValue": "ATVEU01", "monthlyTransactionVolume": "MVEU01", "topTransactionCountries": [ "GB" ] } }, "bankAccountDetails": { "accountName": "Shane Sahrma", "accountNumber": "xxxxx", "bankAccountType": "saving", "bankName": "Bank of Shanghai (Hong Kong) Limited", "bankCountry": "HK", "currency": "HKD", "routingCodes": [ { "type": "swift", "value": "xxxxxxxx" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1, Block 2, Area 3", "addressLine2": "Test Add 123, Building 1, Block 2, Area 3", "city": "Lorem ipsum dolor sit amet, consectetuer.", "postcode": "SW1W", "country": "LT", "state": "ddfd" }, "kycMode": null, "documents": null } ``` ### Corporate customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "EU", "businessName": "ABC corporation", "businessRegistrationNumber": "ABC26_127", "registeredDate": "2024-05-21", "registeredCountry": "SG", "website": "www.idfc348.com", "isMultiLayeredCompany": false, "businessType": "public_company", "bankAccountDetails": { "accountName": "Name", "bankName": "Bank of Shanghai (Hong Kong) Limited", "accountNumber": "GB29NWBK6016133926820", "currency": "SGD", "bankAccountType": "saving", "bankCountry": "SG", "routingCodes": [ { "type": "SWIFT", "value": "DBSSSGSG" } ] }, "taxDetails": [ { "taxCountry": "FR", "taxNumber": "4883935956" } ], "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "addresses": { "isBusinessAddressSameAsRegisteredAddress": false, "registeredAddress": { "addressLine1": "addressLine1", "addressLine2": "addressLine2", "city": "city", "state": "FR-20R", "postcode": "4857832", "country": "FR" }, "businessAddress": { "addressLine1": "busaddressLine1", "addressLine2": "addressLine2", "city": "city", "state": "FR-20R", "postcode": "387593", "country": "FR" } }, "applicant": { "firstName": "applicantFirst", "middleName": "applicantMiddle", "lastName": "applicantLast", "dateOfBirth": "1990-04-21", "isPep": false, "nationality": "SG", "email": "pasumarthi.shank@trin.com", "mobile": "7337223608", "mobileCountryCode": "65", "sharePercentage": 98, "address": { "addressLine1": "applicantLine1", "addressLine2": "applicantLine2", "city": "applicantCity", "state": "FR-20R", "postcode": "478547", "country": "FR" }, "birthCountry": "SG", "taxDetails": [ { "taxCountry": "SG", "taxNumber": "3874684" } ], "documents": [ { "type": "power_of_attorney", "fileIds": [ "087244f3-b4f9-4c54-92df-b472123a6166" ] } ], "positions": [ { "title": "ubo", "startDate": "2025-04-21" } ] }, "stakeholders": { "individual": [ { "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d861", "firstName": "stake1", "middleName": "stake1Mid", "lastName": "stake1Last", "dateOfBirth": "1990-04-21", "isPep": false, "nationality": "LT", "email": "pasumarthi.sashank@nium.com", "mobile": "8106869840", "mobileCountryCode": "65", "sharePercentage": 80, "address": { "addressLine1": "indiviAdd1", "addressLine2": "indiviAdd2", "city": "indiviCity", "state": "FR-20R", "postcode": "63535", "country": "FR" }, "birthCountry": "SG", "taxDetails": [ { "taxCountry": "SG", "taxNumber": "73537935" } ], "positions": [ { "title": "DIRECTOR", "startDate": "2025-04-21" } ] }, { "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d863", "firstName": "applicantFirst", "middleName": "applicantMiddle", "lastName": "applicantLast", "dateOfBirth": "1990-04-21", "isPep": false, "nationality": "SG", "email": "pasumarthi.sashank@nium.com", "mobile": "8106869840", "mobileCountryCode": "65", "sharePercentage": 80, "address": { "addressLine1": "indiviAdd1", "addressLine2": "indiviAdd2", "city": "indiviCity", "state": "FR-20R", "postcode": "63535", "country": "FR" }, "birthCountry": "SG", "taxDetails": [ { "taxCountry": "SG", "taxNumber": "73537935" } ], "positions": [ { "title": "DIRECTOR", "startDate": "2025-04-21" } ] }, { "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d864", "firstName": "applicantFirst1", "middleName": "applicantMiddle1", "lastName": "applicantLast1", "dateOfBirth": "2000-04-21", "isPep": false, "nationality": "EU", "email": "pasumarthi.sashank@nium.com", "mobile": "8106869830", "mobileCountryCode": "65", "sharePercentage": 80, "address": { "addressLine1": "indiviAdd1", "addressLine2": "indiviAdd2", "city": "indiviCity", "state": "FR-20R", "postcode": "63535", "country": "FR" }, "birthCountry": "SG", "taxDetails": [ { "taxCountry": "SG", "taxNumber": "73537935" } ], "positions": [ { "title": "SETTLOR", "startDate": "2025-04-21" } ] } ], "corporate": [ { "externalId": "90ab1818-ef2d-44ee-96c0-7d367842d869", "businessName": "ABC Pvt Ltd", "businessRegistrationNumber": "BRN123456", "registeredCountry": "SG", "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "SG" ], "industryCodes": [ "IS134" ], "industryDescription": "industryDescription_864de5f58049" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "intendedUsesDescription_78d7fdff1d03", "credit": { "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVEU01", "topTransactionCountries": [ "SG" ], "topRemitters": [ "TEST" ] }, "debit": { "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVEU01", "topTransactionCountries": [ "SG" ], "topBeneficiaries": [ "topBeneficiaries_7aaf5e207bab" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "EU012" }, "deviceDetails": { "ipCountryCode": "eu", "deviceInfo": "MAC", "ipAddress": "192.168.1.1", "sessionId": "40531ac01a6f11edafc28dba55d51275" }, "tags": [ { "key": "key_67cef24340df", "value": "value_56606dcf8aa4" } ], "tradeName": "tradeName_f57f429a7dfb", "documents": [ { "type": "business_registration_doc", "fileIds": [ "787244f3-b4f9-4c54-02af-b472123a6067" ] } ] } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "d2b709b2-be2b-46ac-aade-3132da8d534e", "walletType": "base" } ], "customerHashId": "14235ce5-a979-4d22-9692-2bdaf486f2d1", "status": "pending", "subStatus": null, "type": "corporate", "kycType": "full", "region": "EU", "externalId": null, "tags": [ { "key": "key_67cef24340df", "value": "value_56606dcf8aa4" } ], "segment": null, "businessName": "ABC Pvt Ltd", "businessRegistrationNumber": "ABC26_127", "registeredDate": "2024-05-21", "registeredCountry": "SG", "website": "www.idfc348.com", "businessType": "public_company", "taxDetails": [ { "taxCountry": "SG", "taxNumber": "4883935956" } ], "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "tradeName": "tradeName_f57f429a7dfb", "isMultiLayeredCompany": false, "addresses": { "registeredAddress": { "addressLine1": "addressLine1", "addressLine2": "addressLine2", "city": "city", "postcode": "4857832", "country": "FR", "state": "FR-20R" }, "isBusinessAddressSameAsRegisteredAddress": false, "businessAddress": { "addressLine1": "busaddressLine1", "addressLine2": "addressLine2", "city": "city", "postcode": "387593", "country": "FR", "state": "FR-20R" } }, "natureOfBusiness": { "operatingCountries": [ "SG" ], "industryCodes": [ "IS134" ], "industryDescription": "industryDescription_864de5f58049" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "intendedUsesDescription_78d7fdff1d03", "credit": { "averageTransactionValue": "ATVEU01", "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "topTransactionCountries": [ "SG" ], "topRemitters": [ "TEST" ] }, "debit": { "averageTransactionValue": "ATVEU01", "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "topTransactionCountries": [ "SG" ], "topBeneficiaries": [ "topBeneficiaries_7aaf5e207bab" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "EU012" }, "deviceDetails": { "ipCountryCode": "eu", "deviceInfo": "MAC", "ipAddress": "192.168.1.1", "sessionId": "40531ac01a6f11edafc28dba55d51275" }, "bankAccountDetails": { "accountName": "Name", "accountNumber": "xxxxxxxxxxxxxxxxxxxxx", "bankAccountType": "saving", "bankName": "Bank of Shanghai (Hong Kong) Limited", "bankCountry": "SG", "currency": "SGD", "routingCodes": [ { "type": "SWIFT", "value": "xxxxxxxx" } ] }, "applicant": { "externalId": null, "firstName": "applicantFirst", "middleName": "applicantMiddle", "lastName": "applicantLast", "dateOfBirth": "1990-04-21", "nationality": "SG", "email": "pasumarthi.sashank@nium.com", "mobile": "7337223608", "mobileCountryCode": "65", "sharePercentage": 98, "address": { "addressLine1": "applicantLine1", "addressLine2": "applicantLine2", "city": "applicantCity", "postcode": "478547", "country": "FR", "state": "FR-20R" }, "isPep": false, "birthCountry": "SG", "taxDetails": [ { "taxCountry": "SG", "taxNumber": "3874684" } ], "positions": [ { "title": "ubo", "startDate": "2025-04-21" } ], "documents": [ { "type": "power_of_attorney", "fileIds": [ "087244f3-b4f9-4c54-92df-b472123a6166" ], "identificationNumber": null, "issuanceCountry": null, "expiryDate": null } ], "referenceId": "b4b42891-29c3-4cbb-a6eb-236e2a491598" }, "stakeholders": { "individual": [ { "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d861", "firstName": "stake1", "middleName": "stake1Mid", "lastName": "stake1Last", "dateOfBirth": "1990-04-21", "nationality": "LT", "email": "pasumarthi.sashank@nium.com", "mobile": "8106869840", "mobileCountryCode": "65", "sharePercentage": 80, "address": { "addressLine1": "indiviAdd1", "addressLine2": "indiviAdd2", "city": "indiviCity", "postcode": "63535", "country": "FR", "state": "FR-20R" }, "birthCountry": "SG", "taxDetails": [ { "taxCountry": "SG", "taxNumber": "73537935" } ], "isPep": false, "positions": [ { "title": "DIRECTOR", "startDate": "2025-04-21" } ], "kycMode": null, "documents": null, "referenceId": "8d8a36d9-0909-43e9-88a4-7907454afccc" } ], "corporate": [ { "externalId": "90ab1818-ef2d-44ee-96c0-7d367842d869", "businessName": "ABC Pvt Ltd", "businessRegistrationNumber": "BRN123456", "registeredCountry": "SG", "sharePercentage": null, "positions": [ { "title": "UBO", "startDate": null } ], "referenceId": "5d866918-06d6-44fb-bf34-0041ecfb6f3b" } ] }, "documents": [ { "type": "business_registration_doc", "fileIds": [ "787244f3-b4f9-4c54-02af-b472123a6067" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). --- # SG Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/sg-onboarding Singapore onboarding combines regulatory obligations under Singapore’s AML/CFT framework with configurable identity and business verification methods. It includes: - Business verification (KYB) - Individual identity verification (KYC) - Beneficial ownership disclosure (≥ 25%) - Screening and compliance review - Final approval before activation This guide explains how onboarding works in Singapore for business, implementation, and technical teams. ## Regulatory Context Singapore onboarding is governed by Anti-Money Laundering and Countering the Financing of Terrorism (AML/CFT) requirements issued by the **Monetary Authority of Singapore (MAS)**. These regulations require: - Verification of business existence through official registry sources (e.g., UEN validation) - Identification of Ultimate Beneficial Owners (≥ 25% ownership threshold) - Identification of directors and control individuals - Identity verification of authorized representatives and signatories - Sanctions, PEP, and adverse media screening As a result: - Registry lookup may be used for corporate verification (e.g., ACRA-based validation via UEN) - Document submission may be required (e.g., Biz Profile, ID documents, proof of address) - Enhanced due diligence (EDD) may apply based on risk assessment - Compliance approval is mandatory before activation ## Onboarding overview Singapore onboarding supports: - Electronic KYB (eKYB) - Manual KYB - Electronic KYC (eKYC) - Manual KYC (for individuals, corporate applicants, and stakeholders) Manual review may occur when: - Registry lookup fails - Electronic verification fails - Required stakeholder roles are missing - Ownership structures are complex - Documentation is incomplete or inconsistent ## Responsibility ### Client responsibilities The client's onboarding responsibilities include: - Collect accurate business and stakeholder information - Declare all required stakeholder roles - Declare UBOs (> 25% ownership) - Capture applicant attestation - Upload required documents - Ensure stakeholders complete identity verification ### Nium responsibilities Nium's onboarding responsibilities include: - Retrieve registry information - Validate identity and document submissions - Conduct compliance checks - Raise RFIs (Requests for Information) if required - Approve or reject onboarding ## Business verification (KYB) Australia supports both **Electronic KYB (eKYB)** and **Manual KYB**. ### Electronic KYB (eKYB) Electronic KYB retrieves publicly available company information from Singapore registries; It: - Pre-fills corporate data - Reduces document collection requirements - Helps reduce onboarding friction - Speeds up approvals #### Step 1: Fetch public corporate details Collect: - `businessRegistrationNumber` - `countryCode` Use the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) request. Store the returned `publicDetailsId`. If no details are returned, proceed with manual KYB using [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). #### Step 2: Fetch exhaustive corporate details Use the [Fetch Exhaustive Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/exhaustiveDetailsSearch) request and include the `publicDetailsId`. Store the returned `searchId`. This is a chargeable API. Use it only once per customer. Contact your Nium account manager or [Nium Support](mailto:support@nium.com) for pricing details. #### Step 3: Verify and complete corporate details Verify the submitted details: - Confirm submitted data with the applicant - Collect any missing information - Add stakeholder details #### Step 4: Upload required documents Document upload is required when: - `searchId` is not provided - Registry data is incomplete - Additional documents required for verification. For a complete required document list, see[SG Required Documents](https://instarem.atlassian.net/wiki/spaces/CMM/pages/5096079428/SG+Required+Documents).” Use the [Create a File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload the required documents. For more information, see [Uploading documents](/docs/onboarding/customer-onboarding#uploading-documents). The response returns a `fileId`. This `fileId` must be referenced in the onboarding request. #### Step 5: Applicant declaration The authorized representative must confirm: I certify that I am an authorized representative of the customer. \ All information and documents provided are complete and accurate. \ I confirm that all UBOs have been disclosed and that I have accepted the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture via clickwrap and submit: | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ----------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of declaration | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | #### Step 6: Submit onboarding request Use [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) and include: - Corporate details - Stakeholder details - `searchId` (if applicable) - Uploaded `fileId` references - Applicant attestation fields If `searchId` is omitted, the application proceeds through manual review. ## Individual verification (KYC) Singapore supports both **Electronic KYC (eKYC)** and **Manual KYC** for: - Individual customers - Corporate applicants - Directors - UBOs - Stakeholders ### Step 1: Create customer Create the individual using [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). After submission: | status | substatus | | --------- | --------- | | `pending` | `null` | Nium will send the webhook once substatus changes to `awaiting_kyc`. **Please note:** Initiate KYC verification process only after you receive substatus as `awaiting_kyc`. ### Step 2: Access hosted KYC form The applicant accesses the hosted KYC form. Access is protected by a One-Time Password (OTP) sent to the registered email. ### Step 3: Complete identity verification User completes the identity verification as per below available KYC modes. For SG resident applicant/individual stakeholders - Electronic - Once user accesses the KYC form and proceed for verification, user will be redirected to the KYC vendor's page, where he can complete the IDV using Singpass authentication. \[Preferred for faster approval]\* Manual - Another option is to complete the complete the KYC by uploading `PASSPORT` or `NATIONAL_ID`. If `PASSPORT` is provided then `PROOF_OF_ADDRESS` is required \[Least preferred] Non-SG resident applicant/individual stakeholders - Biometric- They can complete the IDV through biometric verification (live selfie with passport/National Id) \[Preferred for faster approval]\* Manual - Another option is to complete the complete the KYC by uploading `PASSPORT` or `NATIONAL_ID`. If `PASSPORT` is provided then `PROOF_OF_ADDRESS` is required. ### Step 4: Compliance review After KYC completion: | status | substatus | | --------- | -------------- | | `PENDING` | `UNDER_REVIEW` | Nium’s compliance team then reviews submissions offline. If additional information is required: - An RFI is raised - The customer responds via the RFI Hosted Form Final decision: | Outcome | status | | -------- | ---------- | | Approved | `clear` | | Rejected | `rejected` | Webhook notifications are sent for all status transitions. For next steps based on application status, see [Customer Lifecycle](/docs/onboarding/individual-customers/customer-lifecycle). ## Stakeholder and UBO requirements ### Ultimate Beneficial Owner - All shareholders owning more than 25% of shares (directly or indirectly) must be declared as an Ultimate Beneficial Owner (UBOs). - If no individual owns more than 25%, the most senior director must be declared as the UBO. - If no UBO is submitted, Nium may identify the UBO during compliance review. - For sole traders, the owner must be declared as the UBO. ### Multi-layer ownership If the customer has a multi-layer ownership structure: - All corporate stakeholders owning more than 25% (directly or indirectly) must be declared. - Corporate structure (ownership structure) documentation must be submitted to validate the ownership chain. For more information, see [Multi-layer ownership structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6). ## Position mapping | businessType | DIRECTOR | EXECUTOR | MEMBERS | PARTNER | PROTECTOR | REPRESENTATIVE | SETTLOR | TRUSTEE | UBO | SHAREHOLDER | SIGNATORY | CONTROL\_PERSON | TRUST\_BENEFICIARY | | ----------------- | -------- | -------- | ------- | ------- | --------- | -------------- | ------- | ------- | --- | ----------- | --------- | --------------- | ------------------ | | Association | | | Yes | | | | | | | Yes | Yes | Yes | | | Government entity | Yes | | | | | Yes | | | | Yes | Yes | Yes | | | Partnership | Yes | | | Yes | | | | | | Yes | Yes | Yes | | | Private company | Yes | | | | | Yes | | | Yes | Yes | Yes | Yes | | | Public company | Yes | | | | | Yes | | | | Yes | Yes | Yes | | | Sole trader | Yes | | | | | Yes | | | Yes | Yes | Yes | Yes | | | Trust | | Yes | | | Yes | | Yes | Yes | Yes | Yes | Yes | Yes | Yes | A blank cell means the role is not applicable for that business type. To dynamically retrieve valid roles use the [Fetch Corporate Constants](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate) request. ### Additional clarifications - For Associations, use `REPRESENTATIVE` for roles such as chair, secretary, or treasurer. - Some Partnerships may include `DIRECTOR` roles depending on structure. - Private and Public companies without an identifiable UBO may pass `SHAREHOLDER` with ownership percentage details. ## Related resources - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [Customer Onboarding v5](/docs/onboarding/customer-onboarding) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/sg-onboarding/required-documents This page outlines the documents required for stakeholders, applicants for all business types to onboard a customer registered in Singapore. ## Business Documents The following table lists the required document types for both manual KYB and eKYB for all business entity types. | businessType | Manual KYB | eKYB | | ------------------ | --------------------------- | ----------------- | | ASSOCIATION | ASSOCIATION\_DEED | ASSOCIATION\_DEED | | GOVERNMENT\_ENTITY | BUSINESS\_REGISTRATION\_DOC | N/A | | PARTNERSHIP | PARTNERSHIP\_DEED | PARTNERSHIP\_DEED | | PRIVATE\_COMPANY | BUSINESS\_REGISTRATION\_DOC | N/A | | PUBLIC\_COMPANY | BUSINESS\_REGISTRATION\_DOC | N/A | | SOLE\_TRADER | BUSINESS\_REGISTRATION\_DOC | N/A | | TRUST | TRUST\_DEED | TRUST\_DEED | ## Additional business documents - **BUSINESS\_REGISTRATION\_DOCUMENT**: Any of the following could be submitted as business registration document. See Verifying Ownership to understand the documents that can be obtained for different businessTypes. - Certificate of Incorporation - Company Bylaws - Board resolutions - Any Operating Agreement - **PROOF\_OF\_BUSINESS**: This document has to be submitted in case website is not provided. Any document that will help us validate the business of the customer. Proof of Business can be any one of the following documents: - Any document depicting the product catalogue such as company brochures or marketing material or detailed business plan. \[Preferred] - Contracts or business agreements or vendor agreements. - Photo of store, in case of brick and mortar store. - Invoice containing clear description of business operations (issued within 1 year) \[Not preferred] - **CORPORATE\_STRUCTURE (Ownership Structure)**: This document should be provided if the customer is a multi-layered company. Refer Multi-layered ownership structure to understand if the customer is a multi-layered company. Corporate structure can be drafted by the customer and contains the names of the shareholders, along with the percent of shares held which will help us to establish the ultimate beneficial owner. See below for an example. You can use a similar template, if you don't have one. For a complete list of business document types, see the values obtained from Fetch corporate constants API with category=documentType. ## KYC Documents Applicable for Individual Customer / Applicant / Ind. Stakeholder: ### Electronic KYC (Preferred for faster approval) - SG residents can be verified through Signpass authentication. - Non SG residents can verify themselves as Live Selfie with Passport/National ID ### Manual KYC - SG residents can be verified by uploading National ID in the KYC Form - Non SG residents can verify themselves by uploading either Passport/National ID. Photocopies or scanned documents in black-and-white are not accepted. These documents undergo fraud checks at Nium. And if were not able establish the authenticity, we will reach out for RFI. ## Additional Documents ### 1. PROOF\_OF\_ADDRESS If the KYC documents submitted does not contains the address then you much submit a valid proof of address. Acceptable proof of address are: 1. Utility bill 2. Bank statement 3. Government issued letter 4. Phone bill (landline only) 5. Driver’s license 6. National ID card All Proof of Address documents must be issued within the last 90 days at the time of submission. Cropped documents are not accepted. Invoices are not accepted. PO BOX and CMRA addresses are not accepted. ### 2. LOA In case applicant is not a DIRECTOR, UBO, PARTNER then LOA is required. --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/sg-onboarding/required-parameters The following guide includes the details that are required when creating a customer using the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request, along with validation rules and sample requests. Use this request to create customers to onboard in Singapore. The endpoint accepts both individual and corporate customer. For a breakdown of the request and parameters, see [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). ### Endpoint URL **POST** `/api/v5/client/{clientHashId}/customers` ## Path Params | Param | Description | | -------------------------------- | ------------------------------------------------------------------- | | clientHashId - string (required) | Unique client identifier generated and shared before API handshake. | ## Body Parameters | Field | M - Mandatory, O - Optional | Description | Data Type | Accepted values | | -------------- | --------------------------- | ------------------------------------------------------- | --------- | --------------------------------------------------------------- | | type (M) | M | Type of the customer | enum | individual, corporate | | kycType (M) | M | The type of KYC that will be performed on this customer | enum | full | | region (M) | M | Regulatory region under which the client is onboarded | enum | e.g. AU/SG | | externalId (O) | O | Customer specified reference ID | string | Max 36 char. Alphanumeric. Unique for a customer under a client | ## Details when kycType=individual | Field | M/O | Description | Data Type | Accepted values | | --------------------- | --- | ---------------------------------------------- | --------- | ----------------------------------------------- | | firstName (M) | M | First name of the customer | string | Max 40 char | | middleName (O) | O | Middle name of the customer | string | Max 40 char | | lastName (M) | M | Last name of the customer | string | Max 40 char | | email (M) | M | Email of the customer | string | Max 60 char; valid email id | | nationality (M) | M | Nationality of the customer | string | category: countryName | | mobile (M) | M | Numeric mobile number without the country code | string | max 15 char | | mobileCountryCode (M) | M | Numeric country code for mobile numbers | string | max 6 char | | dateOfBirth (M) | M | DOB of the customer | date | YYYY-MM-DD. Atleast 18 yrs. Should be past date | ### taxDetails (C) | Field | Description | Data Type | Accepted values | | ---------- | ---------------------------------------------------- | --------- | --------------------------------- | | taxCountry | 2-letter ISO Alpha-2 country code denoting residence | enum | Max 2 char; category: CountryName | | taxNumber | Tax ID number. Send CNPJ for Brazilian Tax Number | string | Max 64 | ### billingAddress (M) | Field | Description | Data Type | Accepted values | | ---------------- | -------------- | ----------- | ---------------------------------- | | addressLine1 (M) | Address line 1 | string | Max 100 char | | addressLine2 (O) | Address line 2 | string | Max 100 char | | city (M) | City | string | Max 50 char | | state (M) | State | string/enum | Max 50 char | | postcode (M) | Post Code | string | Max 10 char, Alphanumeric & spaces | | country (M) | Country | enum | category: countryName | ### expectedAccountUsage (M) #### credit (M) | Field | Description | Data Type | Accepted values | | ------------------------ | --------------------------------------- | --------- | ---------------------------------- | | monthlyTransactionVolume | Monthly transaction volume range in AUD | enum | category: monthlyTransactionVolume | | topTransactionCountries | List of top 5 countries | enum | category: monthlyTransactionVolume | #### debit (M) | Field | Description | Data Type | Accepted values | | ---------------------------- | --------------------------------------- | --------- | ---------------------------------- | | monthlyTransactionVolume | Monthly transaction volume range in AUD | enum | category: monthlyTransactionVolume | | debittopTransactionCountries | List of top 5 countries | enum | category: monthlyTransactionVolume | | Field | Description | Data Type | Accepted values | | --------------------------- | -------------------------------- | -------------- | ------------------------------ | | intendedUses (M) | List of intended uses | array of enums | category: intendedUseOfAccount | | intendedUsesDescription (C) | Description if “Others” selected | string | Max 500 char | ### bankAccountDetails (M) | Field | Description | Data Type | Accepted values | | ---------------------- | -------------------------- | --------- | -------------------- | | accountName (M) | Name exactly as registered | string | Max 140 char | | accountNumber (M) | Bank account number | string | Max 35 char | | bankCountry (M) | ISO 3166-1 alpha-2 | string | | | bankAccountType (C) | Type of bank account | string | Call Bene schema API | | bankName (C) | Full legal bank name | string | Max 255 char | | currency (M) | ISO 4217 currency | string | | | routingCodes.type (M) | Type of routing identifier | string | "SWIFT" | | routingCodes.value (M) | Routing code value | string | | ### deviceDetails (M) | Field | Description | Data Type | Accepted values | | ----------------- | ----------------------- | --------- | --------------------- | | ipCountryCode (M) | Country of origin of IP | enum | category: countryName | | deviceInfo (M) | OS of device | string | | | ipAddress (M) | IP address | string | valid IP4 address | | sessionId (M) | Session ID | string | | ### applicantDeclaration | Field | Description | Data Type | Accepted values | | --------------------------------- | ------------------------ | --------- | --------------- | | applicantDeclaration (M) | Declaration confirmation | boolean | true | | applicantDeclarationTimeStamp (M) | Timestamp | date | | ## Details required when type=corporate | Field | Description | Data Type | Accepted values | | ------------------------------ | ---------------------------- | --------- | ---------------------- | | businessType (M) | Business type | enum | category: businessType | | businessName (M) | Business name | string | Max 80 char | | businessRegistrationNumber (M) | Registration number | string | Max 30 char | | registeredDate (M) | Date of registration | date | YYYY-MM-DD | | registeredCountry (M) | Country of registration | enum | category: countryName | | website (O) | Website | string | Max 255 char | | isMultiLayeredCompany (M) | Multi-layer ownership exists | boolean | | ## Examples ### Individual Customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "SG", "externalId": "ext-1234", "firstName": "SG_FirstName_1", "middleName": "test", "lastName": "SG_LastName_1", "email": "test1@nium.com", "nationality": "SG", "mobile": "567890876", "mobileCountryCode": "1", "dateOfBirth": "2000-08-01", "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "applicantDeclaration": "true", "tags": [ { "key": "testing", "value": "Automation" } ], "deviceDetails": { "ipCountryCode": "sg", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "7676sdsd-2787aadsdsf" }, "expectedAccountUsage": { "intendedUsesDescription": "test intendedintendedtest", "credit": { "monthlyTransactionVolume": "MVSG01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "intendedUses": [ "IU108", "IU107" ], "debit": { "monthlyTransactionVolume": "MVSG01", "topTransactionCountries": [ "GB", "GB", "GB", "IN", "US" ] } }, "bankAccountDetails": { "accountName": "Test account", "accountNumber": "AT483200000012345", "bankName": "DEUTSCHE BANK AG - POSTBANK BRANCH", "bankCountry": "SG", "bankAccountType": "saving", "currency": "SGD", "routingCodes": [ { "type": "SWIFT", "value": "DBSSSGSGXXX" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1", "addressLine2": "Test Add 123, Building 1", "city": "Test Add 123, Building 1, Block 2, Area 3Test Add1", "state": "Singapore", "postcode": "12346", "country": "SG" } } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "aff0c780-c7d0-4455-aafc-5589c796ea50", "walletType": "base" } ], "customerHashId": "e9d6c1b9-b27c-4c83-a25f-75fa1f85bb0d", "referenceId": "3f38e990-aab4-4f84-a2c1-9331fd1e0a03", "status": "pending", "subStatus": null, "type": "individual", "kycType": "full", "region": "SG", "externalId": "ext-1234", "tags": [ { "key": "testing", "value": "Automation" } ], "segment": null, "firstName": "SG_FirstName_1", "middleName": "test", "lastName": "SG_LastName_1", "email": "test1@nium.com", "nationality": "SG", "dateOfBirth": "2000-08-01", "mobile": "567890876", "mobileCountryCode": "1", "kycStatus": "kyc_required", "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "taxDetails": null, "deviceDetails": { "ipCountryCode": "sg", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "7676sdsd-2787aadsdsf" }, "expectedAccountUsage": { "intendedUses": [ "IU108", "IU107" ], "intendedUsesDescription": "test intendedintendedtest", "credit": { "monthlyTransactionVolume": "MVSG01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "debit": { "monthlyTransactionVolume": "MVSG01", "topTransactionCountries": [ "GB", "GB", "GB", "IN", "US" ], "bankAccountDetails": null } }, "bankAccountDetails": { "accountName": "Test account", "accountNumber": "xxxxxxxxxxxxxxxxx", "bankAccountType": "saving", "bankName": "DEUTSCHE BANK AG - POSTBANK BRANCH", "bankCountry": "SG", "currency": "SGD", "bankCode": null, "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "SWIFT", "value": "xxxxxxxxxxx" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1", "addressLine2": "Test Add 123, Building 1", "city": "Test Add 123, Building 1, Block 2, Area 3Test Add1", "postcode": "12346", "country": "SG", "state": "Singapore" }, "kycMode": null, "documents": null, "redirectUrl": null } ``` ### Corporate Customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "SG", "businessName": "Acme Pvt Ltd.", "businessRegistrationNumber": "2026040609M", "registeredDate": "2020-07-20", "registeredCountry": "SG", "website": "https://www.abc.com", "isMultiLayeredCompany": false, "listedExchange": "SGX", "businessType": "private_company", "bankAccountDetails": { "accountName": "ABC Pte Ltd", "bankName": "DBS Bank", "accountNumber": "1234567890", "currency": "SGD", "bankAccountType": "current", "bankCountry": "SG", "routingCodes": [ { "type": "SWIFT", "value": "DBSSSGSG" } ] }, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2026-04-07 12:30:00", "addresses": { "isBusinessAddressSameAsRegisteredAddress": false, "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "state": "Singapore", "postcode": "AA9890", "country": "SG" }, "businessAddress": { "addressLine1": "High Street 1, 6th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "state": "SG", "postcode": "28046", "country": "SG" } }, "applicant": { "firstName": "Hardik", "middleName": "Kumar", "lastName": "Roshan", "dateOfBirth": "1982-07-17", "nationality": "SG", "email": "hardik+093920@abc.com", "mobile": "222268870", "mobileCountryCode": "65", "sharePercentage": 80, "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "state": "SG", "postcode": "28046", "country": "SG" }, "documents": [ { "type": "loa", "fileIds": [ "b3cdc844-71cd-4c01-907e-593ddd91debd" ] } ], "positions": [ { "title": "signatory", "startDate": "2020-07-20" } ] }, "stakeholders": { "individual": [ { "externalId": "ind-001", "firstName": "John", "middleName": "A", "lastName": "Doe", "dateOfBirth": "1990-01-01", "nationality": "SG", "email": "john.doe@example.com", "mobile": "9876543210", "mobileCountryCode": "65", "sharePercentage": 10, "address": { "addressLine1": "Street 1", "addressLine2": "Block A", "city": "Singapore", "state": "SG", "postcode": "123456", "country": "SG" }, "positions": [ { "title": "DIRECTOR", "startDate": "2021-01-01" } ] }, { "externalId": "ind-002", "firstName": "Jane", "middleName": "B", "lastName": "Smith", "dateOfBirth": "1992-02-02", "nationality": "SG", "email": "jane.smith@example.com", "mobile": "9123456780", "mobileCountryCode": "65", "sharePercentage": 10, "address": { "addressLine1": "Street 2", "addressLine2": "Block B", "city": "Singapore", "state": "SG", "postcode": "654321", "country": "SG" }, "positions": [ { "title": "SHAREHOLDER", "startDate": "2021-02-01" } ] } ], "corporate": [ { "externalId": "corp-001", "businessName": "XYZ Holdings", "businessRegistrationNumber": "BRN987654", "listedExchange": "NYSE", "registeredCountry": "US", "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "HK", "IN" ], "industryCodes": [ "IS144" ] }, "expectedAccountUsage": { "intendedUses": [ "IU003" ], "credit": { "monthlyTransactionVolume": "MVSG10", "monthlyTransactions": "ATC03", "averageTransactionValue": "ATVSG02", "topTransactionCountries": [ "SG", "HK" ] }, "debit": { "monthlyTransactionVolume": "MVSG05", "monthlyTransactions": "ATC02", "averageTransactionValue": "ATVSG01", "topTransactionCountries": [ "IN", "SG" ] } }, "sizeOfBusiness": { "totalEmployees": "EM009", "annualTurnover": "SG011" }, "deviceDetails": { "ipCountryCode": "SG", "deviceInfo": "Windows Laptop", "ipAddress": "192.168.0.1", "sessionId": "session-123456" }, "tags": [ { "key": "priority", "value": "high" } ], "tradeName": "BusinessName Trade", "documents": [ { "type": "business_registration_doc", "fileIds": [ "b3cdc844-71cd-4c01-907e-593ddd91debd" ] } ] } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "39d4c1c1-651e-441c-aea0-3d0d2974e006", "walletType": "base" } ], "customerHashId": "55affdfe-9d1d-4312-ac06-4286465b723b", "referenceId": "123adf30-67c3-4d79-bae5-c41153ccc20d", "status": "pending", "subStatus": null, "type": "corporate", "kycType": "full", "region": "SG", "externalId": null, "tags": [ { "key": "priority", "value": "high" } ], "segment": null, "businessName": "Acme Pvt Ltd.", "businessRegistrationNumber": "2026040609M", "registeredDate": "2020-07-20", "registeredCountry": "SG", "website": "https://www.abc.com", "businessType": "private_company", "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2026-04-07 12:30:00", "formerName": null, "tradeName": "BusinessName Trade", "isMultiLayeredCompany": false, "addresses": { "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "postcode": "AA9890", "country": "SG", "state": "Singapore" }, "isBusinessAddressSameAsRegisteredAddress": false, "businessAddress": { "addressLine1": "High Street 1, 6th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "postcode": "28046", "country": "SG", "state": "SG" } }, "taxDetails": null, "natureOfBusiness": { "operatingCountries": [ "HK", "IN" ], "industryCodes": [ "IS144" ], "industryDescription": null }, "expectedAccountUsage": { "intendedUses": [ "IU003" ], "intendedUsesDescription": null, "credit": { "averageTransactionValue": "ATVSG02", "monthlyTransactionVolume": "MVSG10", "monthlyTransactions": "ATC03", "topTransactionCountries": [ "SG", "HK" ] }, "debit": { "averageTransactionValue": "ATVSG01", "monthlyTransactionVolume": "MVSG05", "monthlyTransactions": "ATC02", "topTransactionCountries": [ "IN", "SG" ] } }, "sizeOfBusiness": { "totalEmployees": "EM009", "annualTurnover": "SG011" }, "deviceDetails": { "ipCountryCode": "SG", "deviceInfo": "Windows Laptop", "ipAddress": "192.168.0.1", "sessionId": "session-123456" }, "bankAccountDetails": { "accountName": "ABC Pte Ltd", "accountNumber": "xxxxxxxxxx", "bankAccountType": "current", "bankName": "DBS Bank", "bankCountry": "SG", "currency": "SGD", "bankCode": null, "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "SWIFT", "value": "xxxxxxxx" } ] }, "applicant": { "externalId": null, "firstName": "Hardik", "middleName": "Kumar", "lastName": "Roshan", "dateOfBirth": "1982-07-17", "nationality": "SG", "email": "hardik+093920@abc.com", "mobile": "222268870", "mobileCountryCode": "65", "sharePercentage": "80", "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "postcode": "28046", "country": "SG", "state": "SG" }, "positions": [ { "title": "signatory" } ], "referenceId": "64193aff-227c-4f8f-bba6-26d55c0c7bd7", "kycMode": null, "kycStatus": "kyc_required", "documents": [ { "type": "loa", "fileIds": [ "b3cdc844-71cd-4c01-907e-593ddd91debd" ], "identificationNumber": null, "issuanceCountry": null, "expiryDate": null } ], "redirectUrl": null }, "stakeholders": { "individual": [ { "externalId": "ind-001", "firstName": "John", "middleName": "A", "lastName": "Doe", "dateOfBirth": "1990-01-01", "nationality": "SG", "email": "john.doe@example.com", "mobile": "9876543210", "mobileCountryCode": "65", "sharePercentage": "10", "address": { "addressLine1": "Street 1", "addressLine2": "Block A", "city": "Singapore", "postcode": "123456", "country": "SG", "state": "SG" }, "positions": [ { "title": "DIRECTOR" } ], "documents": null, "referenceId": "3241d37a-a15d-44d2-aa48-e46b068590b3", "kycMode": null, "kycStatus": "kyc_required", "redirectUrl": null }, { "externalId": "ind-002", "firstName": "Jane", "middleName": "B", "lastName": "Smith", "dateOfBirth": "1992-02-02", "nationality": "SG", "email": "jane.smith@example.com", "mobile": "9123456780", "mobileCountryCode": "65", "sharePercentage": "10", "address": { "addressLine1": "Street 2", "addressLine2": "Block B", "city": "Singapore", "postcode": "654321", "country": "SG", "state": "SG" }, "positions": [ { "title": "SHAREHOLDER" } ], "documents": null, "referenceId": "4157806a-fdb5-4582-9fb8-e250c22fccac", "kycMode": null, "kycStatus": "kyc_not_required", "redirectUrl": null } ], "corporate": [ { "externalId": "corp-001", "businessName": "XYZ Holdings", "businessRegistrationNumber": "BRN987654", "registeredCountry": "US", "sharePercentage": null, "positions": [ { "title": "UBO" } ], "referenceId": "89b3ee2d-8bc3-4cb6-afe0-dcb37543be25", "kycStatus": "kyc_not_required" } ] }, "documents": [ { "type": "business_registration_doc", "fileIds": [ "b3cdc844-71cd-4c01-907e-593ddd91debd" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). --- # CA Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/ca-onboarding Learn how to onboard businesses and individuals in the Canada using Customer Onboarding v5. CA onboarding includes: - Manual business verification - Electronic and manual identity verification (KYC) - Beneficial ownership disclosure (≥ 25%) - Compliance review before activation [//]: # "For more information about onboarding, see [Customer Onboarding](/docs/onboarding/customer)." ## Onboarding Flow Nium offers only Manual KYB flows for customers in Canada. Submission of business documents may be required depending on the business type. Check [Required Documents](/docs/onboarding/customer-onboarding/ca-onboarding/required-documents). Please note that businesses registered in Quebec cannot be onboarded on Nium platform to comply with fintech requirements ### Step 1: Upload required documents Use the [Files API](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload required business documents. The response returns a `fileId`. You must reference this `fileId` when submitting the onboarding request. For the full list of required documents, see [CA Required Documents](/docs/onboarding/customer-onboarding/ca-onboarding/required-documents). ### Step 2: Applicant declaration The authorized representative must confirm the following statement: > I certify that I am the authorized representative of the customer; all information provided and documents submitted > are complete and correct. I confirm that I have provided all the UBOs present. I have read and accepted > the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture this confirmation using a clickwrap and submit the following fields in your onboarding request: | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ---------------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of the declaration. | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | ### Step 3: Submit customer details Use the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request and include: - customer details - Customer Registered address - Stakeholder & applicant details (applicable for corporate customer) - Uploaded `fileId` references - Applicant declaration fields - Bank Account Details After submission, the applicant proceeds for KYC Verification. | status | substatus | | --------- | -------------- | | `pending` | `awaiting_kyc` | ### Step 4: Complete Identity Verification (KYC) The applicant opens the Nium’s hosted KYC form. Access is protected by a One-Time Password (OTP) sent to the registered email address of the applicant. CA onboarding supports both electronic and manual identity verification for Individual customers and Applicants of corporate customers. KYC verification is not required for stakeholders. Verification options differ for: - CA residents - Non-CA residents | Residency | Electronic | Biometric | Manual | | --------------- | --------------- | --------------- | ------ | | CA resident | Yes (preferred) | Yes (fallback) | Yes | | Non-CA resident | No | Yes (preferred) | Yes | See [CA Required Documents](/docs/onboarding/customer-onboarding/ca-onboarding/required-documents) for more information on POI/ POA documents ### Step 5: Compliance review After KYC is completed for the applicant | status | substatus | | --------- | -------------- | | `pending` | `under_review` | Nium’s compliance team reviews submitted information offline. If additional details are required: - An RFI (Request for Information) is raised - The customer responds through the RFI Hosted Form Nium returns the final outcome via webhook. For next steps based on application status, see [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle). ### Multi-layer ownership If another corporate entity owns more than 25% (directly or indirectly): - Declare all corporate stakeholders in the ownership chain. - Submit ownership structure documentation. See [CA Required Documents](/docs/onboarding/customer-onboarding/ca-onboarding/required-documents) for more information. ## Position mapping A `Yes` value indicates that the position can be submitted for that `businessType`.\ A blank cell means the position is not applicable. You can also retrieve valid positions dynamically using [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category = positions`. | businessType | SIGNATORY | DIRECTOR | EXECUTOR | PARTNER | PROTECTOR | SETTLOR | SHAREHOLDER | TRUSTEE | UBO | | ------------------- | --------- | -------- | -------- | ------- | --------- | ------- | ----------- | ------- | --- | | PRIVATE\_COMPANY | Yes | Yes | | | | | Yes | | Yes | | PUBLIC\_COMPANY | Yes | Yes | | | | | Yes | | Yes | | TRUST | Yes | Yes | Yes | Yes | Yes | | Yes | Yes | Yes | | CHARITY | Yes | Yes | Yes | | Yes | Yes | | | | | PARTNERSHIP | Yes | Yes | | Yes | | | | | | | WIDELY\_HELD\_TRUST | Yes | Yes | Yes | Yes | Yes | | Yes | Yes | Yes | | SOLE\_TRADER | Yes | | | | | | | | Yes | ## Adding Positions - **Directors:** Add all management directors as stakeholders. - **UBOs:** Tag anyone owning ≥ 25% (direct or indirect). If none, the most senior director becomes the UBO. - **Representatives/Signatories:** Add individuals authorized to transact or manage users (applicant is a Representative by default). - **Partners/Trustees/Settlors:** Include when applicable by entity type. - **Multi-layered companies:** Include all corporate stakeholders with ≥ 25% ownership and upload a **Corporate Structure** document (`documentType: CORPORATE_STRUCTURE`). ## Related resources - [CA Required Documents](/docs/onboarding/customer-onboarding/ca-onboarding/required-documents) - [CA Required Parameters](/docs/onboarding/customer-onboarding/ca-onboarding/required-parameters) - [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/ca-onboarding/required-documents Learn which documents are required to onboard businesses and individuals registered in the Canada. ## Corporate customers The following documents are required for **manual KYB**, based on the business entity type. | Entity type | Document Type (enum) | Documents required | | ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PRIVATE\_COMPANY | BUSINESS\_REGISTRATION\_DOC | Articles of incorporation (optional) Certificate of corporate Status (optional) If Article of incorporation does not contain shareholder details: Shareholder registry | | PUBLIC\_COMPANY | BUSINESS\_REGISTRATION\_DOC | Certificate of incumbency, the articles of incorporation, or the bylaws of the corporation or subsequent board resolutions that set out the officers duly authorized to sign on behalf of the corporation | | TRUST | TRUST\_DEED | Deed of trust | | CHARITY | | N/A | | PARTNERSHIP | PARTNERSHIP\_AGREEMENT | Partnership Agreement | | WIDELY\_HELD\_TRUST | TRUST\_DEED | Deed of trust | | SOLE\_TRADER | | N/A | ### Additional business documents\*\*\*\* Submit the following documents when applicable: #### PROOF\_OF\_BUSINESS Submit this document if no website is provided. It helps Nium verify the customer’s business activity. Accepted documents include: - Contract, business agreement, or vendor agreement. - Product catalog, brochure, marketing material, or business plan along with invoice describing business operations, issued within the last year - Photo of a physical store. #### CORPORATE\_STRUCTURE (Ownership Chart) Submit this document if the company has multiple ownership layers. It should include the names and share percentages of all shareholders to help identify the ultimate beneficial owner (UBO). Ownership Chart For guidance on multi-layer ownership, see [Verifying Your Business in the CA](https://www.nium.com/corporate-onboarding/verifying-your-business-in-canada#heading-7). For a complete list of accepted document types, see [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category). ### LOA (Letter of Authorization) Provide LOA, if the applicant is not a UBO/ DIRECTOR/ TRUSTEE/ PARTNER ### Proof of Identity documents Individual customers, applicants can verify their identity through **electronic KYC** or **manual KYC** using the KYC hosted form. | Residency | Electronic | Biometric | Manual | | --------------- | --------------- | --------------- | ------ | | CA resident | Yes (preferred) | Yes (fallback) | Yes | | Non-CA resident | No | Yes (preferred) | Yes | #### CA residents CA residents can complete verification using one of the following: - Electronic verification (preferred):\ Identity is verified automatically when the individual clicks **Verify** in the hosted KYC form.\ No document upload is required if verification succeeds. - Biometric verification: If automatic verification fails, the individual can complete biometric verification using: - A live selfie - A Passport or Driver licence or National Id - Manual verification: The individual uploads either a: - Passport - National ID (Residence / citizernship card) - Drivers licence Manual verification can result in longer review times due to compliance review. #### Non-CA resident individuals They must verify their identity using one of the following: - Biometric verification: Live selfie with either a: - Passport, - Drivers licence, - National Id (Residence / citizernship card) Biometric verification typically results in faster approval than manual review. - Manual verification: The applicant uploads either a: - Passport - Drivers licence - National Id (Residence / citizernship card) All manual KYC documents undergo manual checks. If Nium cannot verify authenticity, an RFI may be raised. > **Note:** > > - A copy of a copy is not acceptable; the image must be taken directly from the original document. > - Black-and-white images are not acceptable; the document must be in color. > - Paper-based (“paper”) IDs are not acceptable (e.g., temporary, interim, or printed versions). > - All information must be clearly legible. ### PROOF\_OF\_ADDRESS documents Submit a valid proof of address. Acceptable proof of address are: - Utility bill (gas, electric, telephone, cable) - Credit card bill - Bank or brokerage account statement - Government issued letter - Driver’s license/Passport/National ID card (if address is listed) * All Proof of Address documents must be dated within 60 days (not applicable to Driver’s license and National ID card). * Cropped documents are not accepted. * Invoices are not accepted. * PO BOX and CMRA addresses are not accepted. * The same document cannot be used for Proof of Identity and Proof of Address. For details, see: - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [CA Onboarding](/docs/onboarding/customer-onboarding/ca-onboarding) --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/ca-onboarding/required-parameters Learn the required parameters, validation rules, and sample payloads for onboarding individual and corporate customers in the CA using the Customer Onboarding v5 request. The following details the required parameters for the Customer Onboarding v5 request, along with validation rules and sample requests. Use this request to create customers to onboard in the CA region. The endpoint accepts both individual and corporate customers. For API reference, see [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). ## Create Customer v5 POST `/api/v5/client/{clientHashId}/customers` ### Path parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------------------- | | `clientHashId` | string | Yes | Unique client identifier, generated and shared before the integration is set up. | ## Body Parameters | **Parameter** | **Type** | **Required** | **Accepted Values / Notes** | | ------------- | -------- | :----------: | --------------------------------------------------------------------- | | `type` | string | Yes | `individual` or `corporate`. | | `kycType` | string | Yes | `minimum` or `full`. Use `full` when onboarding for payouts. | | `region` | string | Yes | Use `CA`. | | `externalId` | string | Optional | Client-defined unique ID (max 36). Returned in webhooks and GET APIs. | ## Individual Customers ### Personal Information | **Field** | **Type** | **Required** | **Notes** | | ------------------- | -------- | :----------: | --------------------------------------------------------------------------------------------------- | | `firstName` | string | Yes | Max 40. | | `middleName` | string | Optional | Max 40. | | `lastName` | string | Yes | Max 40. | | `email` | string | Yes | Max 60; must match the [valid email regex](/docs/developers/nium-api#regular-expression-for-email). | | `nationality` | enum | Yes | Category: `countryName`. | | `mobile` | numeric | Yes | Without country code; max 15 digits. | | `mobileCountryCode` | numeric | Yes | Max 6 digits. | | `dateOfBirth` | date | Yes | `YYYY-MM-DD`; age ≥ 18. | | `occupation` | enum | Yes | category=occupation | ### `billingAddress` Object | **Field** | **Type** | **Required** | **Notes** | | -------------- | ----------- | :----------: | --------------------------------------------------------------------------------------------------------------- | | `addressLine1` | string | Yes | Max 100. | | `addressLine2` | string | Optional | Max 100. | | `city` | string | Yes | Max 50. | | `state` | enum/string | Conditional | category=isoState for countryCode=xx (e.g., US, CA). If enum list is empty, pass state manually (max 50 chars). | | `postcode` | string | Yes | Max 10. | | `country` | enum | Yes | Category: `countryName`. | ### `expectedAccountUsage` Object | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `credit.topTransactionCountries` | Yes | Category: `countryName`. | | `debit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `debit.topTransactionCountries` | Yes | Destination countries for payouts. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other` is selected. Max 300 chars. | ## Corporate Customers (Full KYC) ### Business Information | **Field** | **Type** | **Required** | **Notes** | | ---------------------------- | -------- | :----------: | -------------------------------------------------------------------- | | `businessType` | enum | Yes | Category: `businessType`. | | `businessName` | string | Yes | Max 80. | | `tradeName` | string | Yes | If not available, set equal to `businessName`. | | `businessRegistrationNumber` | string | Yes | Max 30. | | `registeredDate` | date | Yes | `YYYY-MM-DD`; past date. | | `registeredCountry` | enum | Yes | Category: `countryName`. | | `website` | string | Optional | website or verified social profile; else upload `PROOF_OF_BUSINESS`. | | `isMultiLayeredCompany` | boolean | Yes | `true`/`false`. If `true` upload `CORPORATE_STRUCTURE` | | `stockSymbol` | string | Optional | Required for Public Company | | `listedExchange` | string | Yes | Required for Public Company | ### `addresses` Object | **Field** | **Type** | **Required** | **Notes** | | ------------------------------------------ | ----------- | :----------: | --------------------------------------------------------------------------------------------------------------- | | `registeredAddress.addressLine1` | string | Yes | Max 100. | | `registeredAddress.addressLine2` | string | Optional | Max 100. | | `registeredAddress.city` | string | Yes | Max 50. | | `registeredAddress.state` | enum/string | Conditional | category=isoState for countryCode=xx (e.g., US, CA). If enum list is empty, pass state manually (max 50 chars). | | `registeredAddress.postcode` | string | Yes | Max 10. | | `registeredAddress.country` | enum | Yes | Category: `countryName`. | | `isBusinessAddressSameAsRegisteredAddress` | boolean | Yes | If `false`, provide businessAddress details | ### `documents` (array of object) Provide business documents | **Field** | **Type** | **Required** | **Notes** | | --------- | -------- | :----------: | --------------------------------------------- | | `type` | enum | Yes | category: `documentType` | | `fileIds` | uuid | Yes | Received from the response of Upload file API | ### `applicant` object | **Field** | **Type** | **Required** | **Notes** | | ------------------------------ | --------------- | :----------: | ----------------------------------------------------------------------------------- | | `externalId` | string | Optional | referenceId to identify the applicant. | | `firstName` / `lastName` | string | Yes | Max 40 each. | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Yes | Max 60; valid email. | | `mobile` / `mobileCountryCode` | string | Yes | 15/6 digit limits. | | `nationality` | string | Yes | Max 2 char. | | `sharePercentage` | numeric | Optional | Required only if position title is `UBO`/`PARTNER`/`SHAREHOLDER`. | | `occupation` | enum | Yes | category=occupation | | `positions` | array of object | Yes | Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable. | | `documents` | array of object | Conditional | `POWER_OF_ATTORNEY` required if applicant is not a UBO/ DIRECTOR/ TRUSTEE/ PARTNER. | | `address` | object | Yes | address of the applicant | ### Stakeholders Stakeholders can be **individuals** or **corporates** with roles such as **UBO**, **Director**, **Partner**, \*\*Trustee \*\*, **Shareholder**. **Individual Stakeholders** | **Field** | **Type** | **Required** | **Notes** | | ------------------------------ | --------------- | :----------: | ------------------------------------------------------------------------- | | `externalId` | string | Optional | referenceId to identify the applicant. | | `firstName` / `lastName` | string | Yes | Max 40 each. | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Optional | Max 60; valid email. | | `mobile` / `mobileCountryCode` | string | Optional | 15/6 digit limits. | | `nationality` | string | Yes | Max 2 char. | | `sharePercentage` | numeric | Optional | Required only if position title is `UBO`/`PARTNER`/`SHAREHOLDER`. | | `occupation` | enum | Yes | category=occupation. required only if position title is `REPRESENTATIVE`. | | `positions` | array of object | Yes | Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable. | | `address` | object | Conditional | required only if position title is UBO/ TRUSTEE/ PARTNER/REPRESENTATIVE | **Corporate Stakeholders** | **Field** | **Required** | **Notes** | | ---------------------------- | :----------: | --------------------------------------------- | | `externalId` | Optional | unique Id | | `businessName` | Yes | Registered name. | | `businessRegistrationNumber` | Yes | Max 30. | | `registeredCountry` | Yes | Category: `countryName`. | | `positions.title` | Yes | For example, `UBO`, `Shareholder`, `Trustee`. | | `sharePercentage` | Conditional | Required for UBO/Shareholder/Partner. | ### `natureOfBusiness` object | **Field** | **Required** | **Notes** | | --------------------- | :----------: | ------------------------------------------------------------------------------------------------------- | | `operatingCountries` | Yes | category:`countryOfOperation` All countries where the business operates. | | `industryCodes` | Yes | Category: `industrySector`. Industry sectors that the corporate customer operates in. Multiple allowed. | | `industryDescription` | Conditional | 2–3 sentences if “Other” is selected in industryCodes | > See [Prohibited Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories). ### `expectedAccountUsage` object | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | --------------------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Estimated total payins (CAD). | | `credit.monthlyTransactions` | Yes | Estimated count of monthly payins. | | `credit.averageTransactionValue` | Yes | Average payin value (CAD). | | `credit.topTransactionCountries` | Yes | Origin countries. | | `credit.topRemitters` | Yes | Up to 20 primary remitters (company or individual names). | | `debit.monthlyTransactionVolume` | Yes | Estimated total payouts (CAD). | | `debit.monthlyTransactions` | Yes | Estimated count of monthly payouts. | | `debit.averageTransactionValue` | Yes | Average payout value (CAD). | | `debit.topTransactionCountries` | Yes | Destination countries. | | `debit.topBeneficiaries` | Yes | Up to 20 primary beneficiaries. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other`. | ### `sizeOfBusiness` object | **Field** | **Required** | **Notes** | | ---------------- | :----------: | ----------------------------------------------------------------------- | | `totalEmployees` | Yes | Category: `totalEmployees`. | | `annualTurnover` | Yes | Category: `annualTurnover`. If < 1 year old, provide expected turnover. | ## `bankAccountDetails` object (for refunds/returns- applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | -------------------- | -------- | :----------: | --------------------------------------------------- | | `accountName` | string | Yes | Registered bank name; max 140. | | `accountNumber` | string | Yes | Max 35. | | `bankCountry` | string | Yes | ISO 3166-1 alpha-2. | | `bankName` | string | Yes | Max 255. | | `currency` | string | Yes | ISO 4217 (for example, `USD`, `CAD`). | | `routingCodes.type` | string | Yes | For example, `SWIFT`, `TRANSIT NUMBER`. | | `routingCodes.value` | string | Yes | Matches the selected type. | | `bankCode` | string | Conditional | Required if `routingCodes.type` is `TRANSIT NUMBER` | ## `applicantDeclaration` (applicable for individual and corporate) | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ---------------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of the declaration. | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | ## `devicedetails` object (applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | --------------- | -------- | :----------: | ----------------------------------------------------- | | `ipCountryCode` | enum | Yes | Country of origin of the IP; category: `countryName`. | | `deviceInfo` | string | Yes | OS of the device initiating the request. | | `ipAddress` | string | Yes | Valid IPv4 address. | | `sessionId` | string | Yes | Session identifier for the request. | ## `tags` object (applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | ------------ | -------- | :----------: | ---------------------------------------- | | `tags` | object | Optional | Up to 15 client-defined key/value pairs. | | `tags.key` | string | Optional | Max 128; keys must be unique. | | `tags.value` | string | Optional | Max 255. | ## Examples ### Individual Customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "CA", "externalId": "ext-1234", "firstName": "CA_FirstName_1", "middleName": "test", "lastName": "CA_LastName_1", "email": "test2@nium.com", "nationality": "CA", "mobile": "567890876", "mobileCountryCode": "1", "dateOfBirth": "2000-08-01", "occupation": "OC1002", "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "applicantDeclaration": "true", "tags": [ { "key": "testing", "value": "Automation" }, { "key": "key1", "value": "value1" } ], "deviceDetails": { "ipCountryCode": "ca", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "7676sdsd-2787aadsdsf" }, "expectedAccountUsage": { "intendedUsesDescription": "test intendedintendedtest", "credit": { "monthlyTransactionVolume": "MVCA01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "intendedUses": [ "IU108", "IU107" ], "debit": { "monthlyTransactionVolume": "MVCA01", "topTransactionCountries": [ "GB", "GB", "GB", "IN", "US" ] } }, "bankAccountDetails": { "accountName": "Test account", "accountNumber": "AT483200000012345", "bankName": "DEUTSCHE BANK AG - POSTBANK BRANCH", "bankCountry": "CA", "bankAccountType": "saving", "currency": "CAD", "bankCode": "003", "routingCodes": [ { "type": "TRANSIT NUMBER", "value": "01011" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1", "addressLine2": "Test Add 123, Building 1", "city": "Test Add 123, Building 1, Block 2, Area 3Test Add1", "state": "CA-AB", "postcode": "A1A 1A1", "country": "CA" } } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "f409b385-15ef-4d18-b4a3-7897f0577dc4", "walletType": "base" } ], "customerHashId": "be1a2062-9017-4ef7-be8f-71d95d76a935", "referenceId": "a0ca80a0-1afb-409f-bcc5-87fe51a42085", "status": "pending", "subStatus": null, "type": "individual", "kycType": "full", "region": "CA", "externalId": "ext-1234", "firstName": "CA_FirstName_1", "middleName": "test", "lastName": "CA_LastName_1", "email": "test2@nium.com", "nationality": "CA", "dateOfBirth": "2000-08-01", "mobile": "567890876", "mobileCountryCode": "1", "kycStatus": "kyc_required", "occupation": "OC1002", "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "deviceDetails": { "ipCountryCode": "ca", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "7676sdsd-2787aadsdsf" }, "expectedAccountUsage": { "intendedUses": [ "IU108", "IU107" ], "intendedUsesDescription": "test intendedintendedtest", "credit": { "averageTransactionValue": null, "monthlyTransactionVolume": "MVCA01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "debit": { "averageTransactionValue": null, "monthlyTransactionVolume": "MVCA01", "topTransactionCountries": [ "GB", "GB", "GB", "IN", "US" ] } }, "bankAccountDetails": { "accountName": "Test account", "accountNumber": "xxxxxxxxxxxxxxxxx", "bankAccountType": "saving", "bankName": "DEUTSCHE BANK AG - POSTBANK BRANCH", "bankCountry": "CA", "currency": "CAD", "bankCode": "003", "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "TRANSIT NUMBER", "value": "xxxxx" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1", "addressLine2": "Test Add 123, Building 1", "city": "Test Add 123, Building 1, Block 2, Area 3Test Add1", "postcode": "A1A 1A1", "country": "CA", "state": "CA-AB" }, "kycMode": null, "documents": null, "redirectUrl": null } ``` ### Corporate Customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "CA", "externalId": "ext-1234", "businessName": "Canada pvlt. ltd.", "website": "https://monserrat.biz", "businessDescription": "Technology solutions and consulting services provider", "businessRegistrationNumber": "123456700", "registeredDate": "2015-03-15", "registeredCountry": "CA", "isMultiLayeredCompany": false, "businessType": "private_company", "tradeName": "Greenholt - West Inc", "bankAccountDetails": { "accountName": "Champlin - Spinka Corporate Account", "bankName": "Bank of America", "accountNumber": "802731561", "currency": "CAD", "bankAccountType": "saving", "bankCountry": "CA", "bankCode": "003", "routingCodes": [ { "type": "TRANSIT NUMBER", "value": "00012" } ] }, "taxDetails": [ { "taxCountry": "CA", "taxNumber": "321364" } ], "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-15 10:30:00", "addresses": { "isBusinessAddressSameAsRegisteredAddress": false, "registeredAddress": { "addressLine1": "1234 Corporate Blvd Suite 100", "addressLine2": "Building A", "city": "Wilmington", "state": "CA-NT", "postcode": "K1A 0B2", "country": "CA" }, "businessAddress": { "addressLine1": "5678 Business Park Drive", "addressLine2": "Floor 5", "city": "Newark", "state": "CA-NT", "postcode": "K1A 0B1", "country": "CA" } }, "applicant": { "externalId": "95d4c75b-089b-4aad-a9ab-f3b2360aa171", "firstName": "Tierra", "middleName": "James", "occupation": "OC1210", "lastName": "White", "dateOfBirth": "1985-06-20", "nationality": "CA", "email": "rashmi.kapasi@nium.com", "mobile": "197894", "mobileCountryCode": "1", "sharePercentage": 45, "address": { "addressLine1": "789 Executive Lane", "addressLine2": "Apt 12B", "city": "Newark", "state": "CA-NT", "postcode": "K1A 0B1", "country": "CA" }, "taxDetails": [ { "taxCountry": "CA", "taxNumber": "568379" } ], "documents": [ { "type": "loa", "fileIds": [ "a9f55262-77ea-44a0-a5b8-b01bca79cc84" ] } ], "positions": [ { "title": "UBO", "startDate": "2015-03-15" } ] }, "stakeholders": { "individual": [ { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16805", "firstName": "Robert", "middleName": "", "lastName": "Volkman", "isPep": false, "dateOfBirth": "1980-11-10", "nationality": "US", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": 30, "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "Newark", "state": "CA-NT", "postcode": "K1A 0B1", "country": "CA" }, "taxDetails": [ { "taxCountry": "CA", "taxNumber": "756668" } ], "positions": [ { "title": "DIRECTOR", "startDate": "2016-01-20" } ] }, { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16802", "firstName": "Michael", "middleName": "", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "US", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": 30, "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "state": "US-NY", "postcode": "10001", "country": "US" }, "taxDetails": [ { "taxCountry": "US", "taxNumber": "756668" } ], "positions": [ { "title": "SHAREHOLDER", "startDate": "2016-01-20" } ] } ], "corporate": [ { "externalId": "859ac163-08f0-4152-b26a-e96fce664372", "businessName": "Investment Holdings LLC", "businessRegistrationNumber": "123456789", "registeredCountry": "CA", "sharePercentage": 25, "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "US", "CA", "GB" ], "industryCodes": [ "IS134" ], "industryDescription": "Comprehensive technology consulting and software development services specializing in enterprise solutions, cloud infrastructure, and digital transformation initiatives for Fortune 500 companies across North America and Europe" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "Business operations including vendor payments, payroll processing, and international transactions", "credit": { "monthlyTransactionVolume": "MVCA01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVCA01", "topTransactionCountries": [ "US", "CA", "GB" ], "topRemitters": [ "Enterprise Client A", "Corporate Partner B" ] }, "debit": { "monthlyTransactionVolume": "MVCA01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVCA01", "topTransactionCountries": [ "US", "CA", "MX" ], "topBeneficiaries": [ "Vendor Services Inc", "Technology Suppliers Ltd" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "CA008" }, "deviceDetails": { "ipCountryCode": "ca", "deviceInfo": "Mozilla/5.0 Windows", "ipAddress": "192.168.1.100", "sessionId": "15aaa7ad-7625-4047-a2ce-6fe4ac476728" }, "tags": [ { "key": "customer_type", "value": "enterprise" }, { "key": "priority", "value": "high" } ], "documents": [ { "type": "business_registration_doc", "fileIds": [ "3bb4595c-2d1b-47b3-a951-08175b9013c2" ] } ] } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "60b17829-254f-4ee4-b700-90a301558fd1", "walletType": "base" } ], "customerHashId": "71800fd1-93aa-4e07-9093-de94255c4592", "referenceId": "34dbd0c9-9b91-483b-8f2d-08ce57eed9dd", "status": "pending", "subStatus": null, "type": "corporate", "kycType": "full", "region": "CA", "externalId": "ext-1234", "businessName": "Canada pvlt. ltd.", "businessRegistrationNumber": "123456700", "registeredDate": "2015-03-15", "registeredCountry": "CA", "website": "https://monserrat.biz", "businessType": "private_company", "taxDetails": [ { "taxCountry": "CA", "taxNumber": "321364" } ], "stockSymbol": null, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-15 10:30:00", "tradeName": "Greenholt - West Inc", "isMultiLayeredCompany": false, "addresses": { "registeredAddress": { "addressLine1": "1234 Corporate Blvd Suite 100", "addressLine2": "Building A", "city": "Wilmington", "postcode": "K1A 0B2", "country": "CA", "state": "CA-NT" }, "isBusinessAddressSameAsRegisteredAddress": false, "businessAddress": { "addressLine1": "5678 Business Park Drive", "addressLine2": "Floor 5", "city": "Newark", "postcode": "K1A 0B1", "country": "CA", "state": "CA-NT" } }, "natureOfBusiness": { "operatingCountries": [ "US", "CA", "GB" ], "industryCodes": [ "IS134" ], "industryDescription": "Comprehensive technology consulting and software development services specializing in enterprise solutions, cloud infrastructure, and digital transformation initiatives for Fortune 500 companies across North America and Europe" }, "listedExchange": null, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "Business operations including vendor payments, payroll processing, and international transactions", "credit": { "averageTransactionValue": "ATVCA01", "monthlyTransactionVolume": "MVCA01", "monthlyTransactions": "ATC01", "topTransactionCountries": [ "US", "CA", "GB" ] }, "debit": { "averageTransactionValue": "ATVCA01", "monthlyTransactionVolume": "MVCA01", "monthlyTransactions": "ATC01", "topTransactionCountries": [ "US", "CA", "MX" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "CA008" }, "deviceDetails": { "ipCountryCode": "ca", "deviceInfo": "Mozilla/5.0 Windows", "ipAddress": "192.168.1.100", "sessionId": "15aaa7ad-7625-4047-a2ce-6fe4ac476728" }, "bankAccountDetails": { "accountName": "Champlin - Spinka Corporate Account", "accountNumber": "xxxxxxxxx", "bankAccountType": "saving", "bankName": "Bank of America", "bankCountry": "CA", "currency": "CAD", "bankCode": "003", "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "TRANSIT NUMBER", "value": "xxxxx" } ] }, "applicant": { "externalId": "95d4c75b-089b-4aad-a9ab-f3b2360aa171", "firstName": "Tierra", "middleName": "James", "lastName": "White", "dateOfBirth": "1985-06-20", "nationality": "CA", "email": "rashmi.kapasi@nium.com", "mobile": "197894", "mobileCountryCode": "1", "sharePercentage": "45", "address": { "addressLine1": "789 Executive Lane", "addressLine2": "Apt 12B", "city": "Newark", "postcode": "K1A 0B1", "country": "CA", "state": "CA-NT" }, "occupation": "OC1210", "positions": [ { "title": "UBO" } ], "kycMode": null, "documents": [ { "type": "loa", "fileIds": [ "a9f55262-77ea-44a0-a5b8-b01bca79cc84" ], "identificationNumber": null, "issuanceCountry": null, "expiryDate": null } ], "redirectUrl": null, "referenceId": "294ea3af-3d11-4405-bdbc-80b791b35087", "kycStatus": "kyc_required" }, "stakeholders": { "individual": [ { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16805", "firstName": "Robert", "middleName": "", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "US", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": "30", "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "Newark", "postcode": "K1A 0B1", "country": "CA", "state": "CA-NT" }, "occupation": null, "positions": [ { "title": "DIRECTOR" } ], "documents": null, "kycMode": null, "redirectUrl": null, "referenceId": "4bfd54f5-107a-41cd-a51d-d63814f4d546", "kycStatus": "kyc_not_required" }, { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16802", "firstName": "Michael", "middleName": "", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "US", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": "30", "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "postcode": "10001", "country": "US", "state": "US-NY" }, "occupation": null, "positions": [ { "title": "SHAREHOLDER" } ], "documents": null, "kycMode": null, "redirectUrl": null, "referenceId": "8bde135f-d3ee-49c6-97ec-963d77a11d04", "kycStatus": "kyc_not_required" } ], "corporate": [ { "externalId": "859ac163-08f0-4152-b26a-e96fce664372", "businessName": "Investment Holdings LLC", "businessRegistrationNumber": "123456789", "registeredCountry": "CA", "sharePercentage": "25", "positions": [ { "title": "UBO" } ], "referenceId": "ad691eba-3d95-4cc8-bd04-b6b506ba9ac2", "kycStatus": "kyc_not_required" } ] }, "documents": [ { "type": "business_registration_doc", "fileIds": [ "3bb4595c-2d1b-47b3-a951-08175b9013c2" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). --- # UK Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/uk-onboarding UK onboarding combines regulatory requirements under the UK’s AML (Anti-Money Laundering) framework with configurable verification methods. It includes: - Business verification (KYB) - Individual identity verification (KYC)\*\*\*\* - Beneficial ownership disclosure (> 25%) - Compliance review and approval This guide explains how onboarding works in the United Kingdom. ## Regulatory context UK onboarding is governed by Anti-Money Laundering (AML) and Know Your Customer (KYC) regulations. These regulations require: - Verification of business existence via public registries - Identification of Ultimate Beneficial Owners (UBOs) - Identity verification of authorized representatives As a result: - Registry lookup is commonly used for UK companies (eKYB) - Document submission may still be required - Compliance approval is mandatory before activation ## Onboarding overview UK onboarding supports: - Electronic KYB (eKYB) - Manual KYB - Electronic KYC (default) - Manual KYC (stakeholders only) Manual review may occur when: - Registry lookup fails or returns incomplete data - Electronic verification fails - Required stakeholder roles are missing - Ownership structures are complex or multi-layered - Documentation is incomplete or inconsistent For document requirements, see [UK Required Documents](/docs/onboarding/customer-onboarding/uk-onboarding/required-documents) For request structure, see [UK Required Parameters](/docs/onboarding/customer-onboarding/uk-onboarding/required-parameters) ## Responsibility ### Client responsibilities The client is responsible for: - Collecting accurate business and stakeholder information. - Declaring all required stakeholder roles. - Declaring all Ultimate Beneficial Owners (UBOs) (>25%). - Capturing applicant attestation. - Uploading required documents. - Ensuring stakeholders complete identity verification via the [Pre-built KYC form](/docs/developers/pre-built-forms/kyc-form). ### Nium responsibilities Nium is responsible for: - Retrieving registry information. - Validating identity and documents. - Conducting compliance checks. - Raising RFIs (Requests for Information) if required. - Approving or rejecting onboarding. ## Business verification (KYB) UK supports both **Electronic KYB (eKYB)** and **Manual KYB**. ### Electronic KYB (eKYB) Electronic KYB retrieves publicly available company information from UK registries. Once retrieved, it: - Pre-fills corporate data - Reduces document requirements - Improves onboarding speed - Minimizes manual input #### Step 1: Fetch public corporate details To support electronic KYB (eKYB), retrieve publicly available company details before creating the customer. Collect: - `businessRegistrationNumber` - `countryCode` Use the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) request. This returns publicly available company data. Display results to the applicant and allow them to: - Select the correct entity - Confirm the registration number - Review returned details If multiple results are returned: - The applicant must select the correct entity If no results are returned: - Use [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) - Provide all details manually - The application will follow the **manual KYB flow** #### Step 2: Fetch exhaustive corporate details Use the [Fetch Exhaustive Corporate Details](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/corporate/exhaustiveDetails) - Input: `publicDetailsId` - Output: `searchId` This is a chargeable API and should only be called once per customer. This returns: - Directors - Shareholders - Ownership structure #### Step 3: Verify and complete corporate details - Confirm all data with the applicant - Add missing required fields - Add stakeholders (directors, UBOs, etc.) For more information, see [Stakeholder and UBO requirements](#stakeholder-and-ubo-requirements) #### Step 4: Upload required documents Document upload is required when: - `searchId` is not used - Registry data is incomplete - Additional verification is required Use the [Create a File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request. The response returns a `fileId`. This `fileId` must be included in the onboarding request. For additional details, see [UK Required Documents](/docs/onboarding/customer-onboarding/uk-onboarding/required-documents) #### Step 5: Applicant declaration The authorized representative must confirm: > I certify that I am an authorized representative of the customer.\ > All information and documents provided are complete and accurate.\ > I confirm that all UBOs have been disclosed and that I have accepted > the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture via clickwrap and submit: | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ----------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | #### Step 6: Submit onboarding request Use [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) and include: - Corporate details - Stakeholder details - `searchId` (if applicable) - Uploaded `fileId` references - Applicant declaration ### Manual KYB Manual KYB is required when: - Registry lookup fails - eKYB is not used - Additional verification is required All required documents must be uploaded before submission. For more information, see [UK Required Documents](/docs/onboarding/customer-onboarding/uk-onboarding/required-documents) ## Individual verification (KYC) UK onboarding requires identity verification for: - Applicants - Individual customers - Directors - UBOs - Stakeholders ### Step 1: Create customer Create the customer using [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) After submission: | status | substatus | | --------- | -------------- | | `PENDING` | `AWAITING_KYC` | For status transitions, see [Customer Lifecycle](/docs/onboarding/individual-customers/customer-lifecycle) ### Step 2: Access Pre-built KYC form The applicant accesses the [Pre-built KYC form](/docs/developers/pre-built-forms/kyc-form) Access is secured via a One-Time Password (OTP) sent to the registered email address. ### Step 3: Verify identity Each individual must complete verification using the [Pre-built KYC form](/docs/developers/pre-built-forms/kyc-form): - Identity document submission - Live selfie (biometric verification) ### Step 4: Stakeholder verification #### Electronic verification - Applicant shares verification link - Stakeholders complete KYC via the [Pre-built KYC form](/docs/developers/pre-built-forms/kyc-form) #### Manual verification - Applicant uploads documents on behalf of stakeholders For more information, see [UK Required Documents](/docs/onboarding/customer-onboarding/uk-onboarding/required-documents) ### Step 5: Compliance review After KYC completion: | status | substatus | | --------- | -------------- | | `PENDING` | `UNDER_REVIEW` | Nium reviews the application offline. If additional information is required: - An RFI is raised - The customer responds via the [Pre-built RFI Form](/docs/developers/pre-built-forms/rfi-forms) ### Final decision | Outcome | status | | -------- | ---------- | | Approved | `clear` | | Rejected | `rejected` | Webhook notifications are sent for all transitions. For next steps, see [Customer Lifecycle](/docs/onboarding/individual-customers/customer-lifecycle) ## Stakeholder and UBO requirements ### Ultimate Beneficial Owner (UBO) All individuals owning more than 25% must be declared. If there are none: - The most senior director must be declared - If left blank, Nium will request this information during compliance review. ### Multi-layer ownership If a corporate entity owns more than 25%: - Declare corporate stakeholders - Submit ownership structure documentation For more information, see [UK Required Documents](/docs/onboarding/customer-onboarding/uk-onboarding/required-documents) ## Position mapping | Business Type | CONTROL\_PERSON | DIRECTOR | MEMBERS | PARTNER | REPRESENTATIVE | SETTLOR | SHAREHOLDER | SIGNATORY | TRUSTEE | UBO | | ------------------------------- | --------------- | -------- | ------- | ------- | -------------- | ------- | ----------- | --------- | ------- | --- | | ASSOCIATION | Yes | | Yes | | Yes | | | Yes | | Yes | | GOVERNMENT\_ENTITY | Yes | | | | Yes | | | Yes | | Yes | | LIMITED\_LIABILITY\_PARTNERSHIP | Yes | | | Yes | Yes | | | Yes | | Yes | | PRIVATE\_COMPANY | Yes | Yes | | | Yes | | Yes | Yes | | Yes | | PUBLIC\_COMPANY | Yes | Yes | | | Yes | | Yes | Yes | | Yes | | SOLE\_TRADER | Yes | | | | Yes | | | Yes | | Yes | | TRUST | Yes | | | | Yes | Yes | | Yes | Yes | Yes | | UNINCORP\_PARTNERSHIP | Yes | | | Yes | Yes | | | Yes | | Yes | A blank cell means the role doesn't apply. ## Adding positions Add all management directors as stakeholders. Tag anyone owning 25% or more, directly or indirectly, as a UBO. If no individual owns 25% or more, declare the most senior director as the UBO. The applicant is treated as a representative by default. Add other representatives or signatories if they are authorized to perform transactions or manage users. Include partners, trustees, settlors, or other applicable roles based on the business entity type. For multi-layered companies, include all corporate stakeholders owning 25% or more and upload a `CORPORATE_STRUCTURE` document. ## Related resources - [UK Required Documents](/docs/onboarding/customer-onboarding/uk-onboarding/required-documents) - [UK Required Parameters](/docs/onboarding/customer-onboarding/uk-onboarding/required-parameters) - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [Pre-built RFI Form](/docs/developers/pre-built-forms/rfi-forms) - [Customer Lifecycle](/docs/onboarding/individual-customers/customer-lifecycle) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/uk-onboarding/required-documents Learn which documents are required to onboard businesses and individuals in the United Kingdom (UK). For onboarding steps, see [UK Onboarding](/docs/onboarding/customer-onboarding/uk-onboarding). ## Corporate customers Document requirements depend on the business entity type, whether electronic KYB (eKYB) is used, and whether additional verification is required. ### Business documents | Business Type | Document Type (Manual KYB) | Document Type (eKYB, when searchId is present) | | :------------------------------------------------------ | :-------------------------- | :--------------------------------------------- | | ASSOCIATION | ASSOCIATION\_DEED | ASSOCIATION\_DEED | | GOVERNMENT\_ENTITY / SOLE\_TRADER | BUSINESS\_REGISTRATION\_DOC | N/A | | LIMITED\_LIABILITY\_PARTNERSHIP / UNINCORP\_PARTNERSHIP | PARTNERSHIP\_DEED | PARTNERSHIP\_DEED | | PUBLIC\_COMPANY / PRIVATE\_COMPANY | BUSINESS\_REGISTRATION\_DOC | N/A | | TRUST | TRUST\_DEED | TRUST\_DEED | ## Additional business documents Submit additional documents when the standard business registration documents do not provide enough information for verification. ### REGISTER\_OF\_DIRECTORS and REGISTER\_OF\_SHAREHOLDERS Provide this document when the business registration document does not include directors or shareholders. When using eKYB, this document is required if a new director or shareholder is added who is not returned by the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) request. If not provided, Nium will raise an RFI. ### PROOF\_OF\_BUSINESS Provide this document when no website is available. It helps Nium validate the nature of the business. Accepted documents include product catalogs, brochures, business plans (preferred), contracts or agreements, store photos, or invoices describing business activity. Invoices should be recent and clearly reflect operations. ### CORPORATE\_STRUCTURE (Ownership Structure) Provide this document when the company has a multi-layer ownership structure. The document must clearly show shareholders, ownership percentages, and the ownership chain. This is used to identify Ultimate Beneficial Owners (UBOs). ## Stakeholder documents Stakeholders such as SIGNATORY, REPRESENTATIVE, UBO, TRUSTEE, or PARTNER must complete identity verification. ### Electronic KYC (default) Stakeholders complete verification using the [Pre-built KYC form](/docs/developers/pre-built-forms/kyc-form). They must submit a live selfie along with a valid passport or national ID. If `isPEP = true`, source of wealth documentation is also required. ### Manual KYC Manual verification is used when electronic verification fails or is not possible. The applicant uploads a passport or national ID on behalf of the stakeholder. Documents must be clear, valid, and not submitted as black-and-white copies. If Nium cannot verify the documents, an RFI is raised. The customer must respond using the [Pre-built RFI Form](/docs/developers/pre-built-forms/rfi-forms). ### SOURCE\_OF\_WEALTH Provide this document when `isPEP = true`. Submit a written explanation with supporting evidence such as bank statements, employment income, investment income, asset sales, inheritance, loan agreements, or business ownership documents. ### PROOF\_OF\_ADDRESS Provide this document when the address cannot be verified through submitted identity documents. The document must be issued within 90 days. ### CONTROL\_PERSON\_DECLARATION Provide this document when no individual owns 25% or more of the business. ## Individual customers Individual applicants must complete electronic KYC using the [Pre-built KYC form](/docs/developers/pre-built-forms/kyc-form). ### Required submission Submit a live selfie with a passport (for non-UK individuals) or a passport or national ID (for UK or EEA individuals). ### Additional requirements #### POWER\_OF\_ATTORNEY Provide this document when the applicant is not a director or authorized representative of the business. #### SOURCE\_OF\_WEALTH Provide this document when `isPEP = true`. ## Related resources - [UK Onboarding](/docs/onboarding/customer-onboarding/uk-onboarding) - [UK Required Parameters](/docs/onboarding/customer-onboarding/uk-onboarding/required-parameters) - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [Pre-built RFI Form](/docs/developers/pre-built-forms/rfi-forms)2 --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/uk-onboarding/required-parameters Learn the required parameters, validation rules, and sample payloads for onboarding individual and corporate customers in the UK using the Customer Onboarding v5 request. The following guide includes the details that are required when creating a customer using the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request, along with validation rules and sample requests. Use this request to create customers to onboard in United Kingdom. The endpoint accepts both individual and corporate customer. For a breakdown of the request and parameters, see [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). For onboarding steps, see [UK Onboarding](/docs/onboarding/customer-onboarding/uk-onboarding). For document requirements, see [UK Required Documents](/docs/onboarding/customer-onboarding/uk-onboarding/required-documents). ## Endpoint URL POST `/api/v5/client/{clientHashId}/customers` ## Path parameters | **Parameter** | **Type** | **Required** | **Description** | | -------------- | -------- | :----------: | ------------------------------------------------------------------------ | | `clientHashId` | string | Yes | Unique client identifier, generated and shared before the API handshake. | ## Body parameters | **Parameter** | **Type** | **Required** | **Accepted Values / Notes** | | ------------- | -------- | :----------: | ------------------------------------------------------------ | | `type` | string | Yes | `individual` or `corporate`. | | `kycType` | string | Yes | `minimum` or `full`. Use `full` when onboarding for payouts. | | `region` | string | Yes | Use `UK`. | | `externalId` | string | Optional | Client-defined unique ID. Returned in webhooks and GET APIs. | ## Individual customers Individual customers in the UK complete **electronic KYC** through the [Pre-built KYC form](/docs/developers/pre-built-forms/kyc-form). ### Personal information | **Field** | **Type** | **Required** | **Notes** | | ------------------- | -------------- | :----------: | ------------------------------------------ | | `firstName` | string | Yes | Max 40. | | `middleName` | string | Optional | Max 40. | | `lastName` | string | Yes | Max 40. | | `email` | string | Yes | Max 60; must match the valid email format. | | `nationality` | enum | Yes | Category: `countryName`. | | `mobile` | numeric/string | Yes | Without country code; max 15 digits. | | `mobileCountryCode` | numeric/string | Yes | Max 6 digits. | | `dateOfBirth` | date | Yes | `YYYY-MM-DD`; age must be 18 or older. | | `isPep` | boolean | Yes | `true` if PEP. | ### Billing address | **Field** | **Type** | **Required** | **Notes** | | -------------- | ----------- | :----------: | -------------------------------------------------------------- | | `addressLine1` | string | Yes | Max 100. | | `addressLine2` | string | Optional | Max 100. | | `city` | string | Yes | Max 50. | | `state` | enum/string | Conditional | Category: `state`. Optional if not applicable for the country. | | `postcode` | string | Yes | Max 10. | | `country` | enum | Yes | Category: `countryName`. | ### Expected account usage | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `credit.topTransactionCountries` | Yes | Category: `countryName`. | | `debit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `debit.topTransactionCountries` | Yes | Destination countries for payouts. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other` is selected. Max 300 chars. | ### Bank account details Use these details for refunds and returns. | **Field** | **Type** | **Required** | **Notes** | | -------------------- | -------- | :----------: | ------------------------------------------------------------ | | `accountName` | string | Yes | Registered bank account name; max 140. | | `accountNumber` | string | Yes | Max 35. | | `bankCountry` | string | Yes | ISO 3166-1 alpha-2. | | `bankAccountType` | string | Conditional | For example, `savings`, `checking`, or `current`. | | `bankName` | string | Conditional | Max 255. | | `currency` | string | Yes | ISO 4217. | | `routingCodes.type` | string | Yes | For example, `SWIFT`, `SORT_CODE`, or other supported value. | | `routingCodes.value` | string | Yes | Must match the selected routing code type. | ## Corporate customers (Full KYC) ### Business information | **Field** | **Type** | **Required** | **Notes** | | ---------------------------- | -------- | :----------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `businessType` | enum | Yes | Category: `businessType`. | | `businessName` | string | Yes | Max 80. | | `tradeName` | string | Optional | If not available, use the registered business name. | | `businessRegistrationNumber` | string | Yes | Max 30. | | `registeredDate` | date | Yes | `YYYY-MM-DD`; must be a past date. | | `registeredCountry` | enum | Yes | Category: `countryName`. | | `website` | string | Optional | URL or verified social profile. If omitted, upload `PROOF_OF_BUSINESS`. | | `isMultiLayeredCompany` | boolean | Yes | `true` or `false`. Upload `CORPORATE_STRUCTURE` when `true`. | | `searchId` | string | Conditional | Include when using the [Fetch Exhaustive Corporate Details](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/corporate/exhaustiveDetails) request. If omitted, the application follows the manual KYB flow. | ### Applicant declaration These fields are required before you submit the onboarding request. | **Field** | **Type** | **Required** | **Notes** | | ------------------------------- | --------- | :----------: | ----------------------------------------------------------- | | `applicantDeclaration` | boolean | Yes | Must be `true` after the applicant accepts the declaration. | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS`. | ### Applicant details | **Field** | **Type** | **Required** | **Notes** | | ------------------- | -------- | :----------: | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `firstName` | string | Yes | Max 40. | | `middleName` | string | Optional | Max 40. | | `lastName` | string | Yes | Max 40. | | `dateOfBirth` | date | Yes | `YYYY-MM-DD`; age must be 18 or older. | | `email` | string | Yes | Max 60; valid email. | | `mobile` | string | Yes | Max 15 digits. | | `mobileCountryCode` | string | Yes | Max 6 digits. | | `nationality` | enum | Yes | Category: `countryName`. | | `isPep` | boolean | Yes | `true` if PEP. | | `sharePercentage` | numeric | Conditional | Required if the applicant is also a shareholder or UBO. | | `address` | object | Yes | Full residential address. | | `positions` | array | Yes | Include all applicable roles such as `DIRECTOR`, `REPRESENTATIVE`, `UBO`, `PARTNER`, or `TRUSTEE`. | | `documents` | array | Conditional | Include `POWER_OF_ATTORNEY` if the applicant is not a director or otherwise not authorized by role. Include `SOURCE_OF_WEALTH` when `isPep = true`. | ### Registered and business addresses | **Field** | **Type** | **Required** | **Notes** | | ---------------------------------------------------- | ----------- | :----------: | ---------------------------------------------------------------------------- | | `addresses.registeredAddress.addressLine1` | string | Yes | Max 100. | | `addresses.registeredAddress.addressLine2` | string | Optional | Max 100. | | `addresses.registeredAddress.city` | string | Yes | Max 50. | | `addresses.registeredAddress.state` | enum/string | Conditional | Category: `state`. Optional if not applicable. | | `addresses.registeredAddress.postcode` | string | Yes | Max 10. | | `addresses.registeredAddress.country` | enum | Yes | Category: `countryName`. | | `addresses.isBusinessAddressSameAsRegisteredAddress` | boolean | Yes | `true` or `false`. | | `addresses.businessAddress` | object | Conditional | Required when the business address is different from the registered address. | ### Stakeholders Stakeholders can be **individuals** or **corporates** with roles such as **UBO**, **Director**, **Partner**, \*\*Trustee \*\*, **Shareholder**, or **CONTROL\_PRONG**. #### Individual stakeholders | **Field** | **Required** | **Notes** | | ----------------------------------------------------- | :----------: | ------------------------------------------------------------------------- | | `firstName`, `lastName`, `dateOfBirth`, `nationality` | Yes | Personal details. | | `email`, `mobile`, `mobileCountryCode` | Yes | Contact details used for KYC. | | `isPep` | Yes | `true` if PEP. | | `positions` | Yes | Include all applicable roles. | | `sharePercentage` | Conditional | Required when ownership is declared. | | `address` | Yes | Full residential address. | | `documents` | Conditional | Used for manual KYC or when additional supporting documents are required. | #### Corporate stakeholders | **Field** | **Required** | **Notes** | | ---------------------------- | :----------: | ------------------------------------------------ | | `businessName` | Yes | Registered business name. | | `businessRegistrationNumber` | Yes | Max 30. | | `registeredCountry` | Yes | Category: `countryName`. | | `positions.title` | Yes | For example, `UBO`, `Shareholder`, or `Trustee`. | | `sharePercentage` | Conditional | Required for ownership-based roles. | ### Nature of business | **Field** | **Required** | **Notes** | | --------------------- | :----------: | -------------------------------------------------------------------------- | | `operatingCountries` | Yes | All countries where the business operates. | | `industryCodes` | Yes | Category: `industrySector`. Multiple values allowed. | | `industryDescription` | Conditional | Required when `Other` is selected or when Compliance requests more detail. | ### Expected account usage (Corporate) | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Estimated total payins. | | `credit.monthlyTransactions` | Yes | Estimated count of monthly payins. | | `credit.averageTransactionValue` | Yes | Average payin value. | | `credit.topTransactionCountries` | Yes | Origin countries. | | `credit.topRemitters` | Yes | Up to 20 primary remitters. | | `debit.monthlyTransactionVolume` | Yes | Estimated total payouts. | | `debit.monthlyTransactions` | Yes | Estimated count of monthly payouts. | | `debit.averageTransactionValue` | Yes | Average payout value. | | `debit.topTransactionCountries` | Yes | Destination countries. | | `debit.topBeneficiaries` | Yes | Up to 20 primary beneficiaries. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other` is selected. | ### Size of business | **Field** | **Required** | **Notes** | | ---------------- | :----------: | ------------------------------------------------------------------------------------------------- | | `totalEmployees` | Yes | Category: `totalEmployees`. | | `annualTurnover` | Yes | Category: `annualTurnover`. If the business is less than one year old, provide expected turnover. | ## Device details | **Field** | **Type** | **Required** | **Notes** | | --------------- | -------- | :----------: | ----------------------------------------------------- | | `ipCountryCode` | enum | Yes | Country of origin of the IP; category: `countryName`. | | `deviceInfo` | string | Yes | OS or device information for the request. | | `ipAddress` | string | Yes | Valid IPv4 or IPv6 address. | | `sessionId` | string | Yes | Session identifier for the request. | ## Tags | **Field** | **Type** | **Required** | **Notes** | | ------------ | ------------ | :----------: | ---------------------------------------- | | `tags` | array/object | Optional | Up to 15 client-defined key/value pairs. | | `tags.key` | string | Optional | Max 128; keys must be unique. | | `tags.value` | string | Optional | Max 255. | ## Examples ### Individual Customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "UK", "externalId": "ext-123456", "firstName": "Rahul", "middleName": "Kumar", "lastName": "Rajawat", "isPep": "false", "email": "support@nium.com", "nationality": "GB", "mobile": "123489767", "mobileCountryCode": "1", "dateOfBirth": "2000-08-01", "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "applicantDeclaration": "true", "tags": [ { "key": "testing", "value": "Automation" } ], "deviceDetails": { "ipCountryCode": "gb", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "intendedUsesDescription": "Business Description or the purpose of account", "credit": { "monthlyTransactionVolume": "MVUK01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "intendedUses": [ "IU108", "IU107" ], "debit": { "monthlyTransactionVolume": "MVUK01", "topTransactionCountries": [ "GB", "GB", "GB", "IN", "US" ] } }, "bankAccountDetails": { "accountName": "Rahul Rajawat", "bankName": "HSBC Bank", "accountNumber": "78956432", "currency": "GBP", "bankAccountType": "current", "bankCountry": "GB", "routingCodes": [ { "type": "SORT CODE", "value": "230363" } ] }, "billingAddress": { "addressLine1": "AddressLine1 Building Floor", "addressLine2": "", "city": "London", "state": "GB-ENG", "postcode": "SW1A 1AA", "country": "GB" } } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "b48501dd-14d8-48b6-bfd6-7d4fb5440f48", "walletType": "base" } ], "customerHashId": "705fe3a8-0820-4bb5-ad68-d3cbb0b7712c", "referenceId": "c3cd4b74-2da8-42cf-9503-5e092747ceda", "status": "pending", "subStatus": null, "type": "individual", "kycType": "full", "region": "UK", "externalId": "ext-123456", "tags": [ { "key": "testing", "value": "Automation" } ], "segment": null, "firstName": "Rahul", "middleName": "Kumar", "lastName": "Rajawat", "email": "support@nium.com", "nationality": "GB", "dateOfBirth": "2000-08-01", "mobile": "123489767", "mobileCountryCode": "1", "kycStatus": "kyc_required", "isPep": false, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "deviceDetails": { "ipCountryCode": "gb", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "intendedUses": [ "IU108", "IU107" ], "intendedUsesDescription": "Business Description or the purpose of account", "credit": { "monthlyTransactionVolume": "MVUK01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "debit": { "monthlyTransactionVolume": "MVUK01", "topTransactionCountries": [ "GB", "GB", "GB", "IN", "US" ], "bankAccountDetails": null } }, "bankAccountDetails": { "accountName": "Rahul Rajawat", "accountNumber": "xxxxxxxx", "bankAccountType": "current", "bankName": "HSBC Bank", "bankCountry": "GB", "currency": "GBP", "bankCode": null, "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "SORT CODE", "value": "xxxxxx" } ] }, "billingAddress": { "addressLine1": "AddressLine1 Building Floor", "addressLine2": "", "city": "London", "postcode": "SW1A 1AA", "country": "GB", "state": "GB-ENG" }, "kycMode": null, "documents": null, "redirectUrl": null } ``` ### Corporate Customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "UK", "externalId": "ext-1234", "businessName": "UK_BusinessName", "businessRegistrationNumber": "2026040609339M", "registeredDate": "2020-07-20", "registeredCountry": "GB", "website": "https://www.ukcompany.com", "isMultiLayeredCompany": false, "businessType": "private_company", "bankAccountDetails": { "accountName": "BusinessName Pvt Ltd", "bankName": "HSBC Bank", "accountNumber": "78956432", "currency": "GBP", "bankAccountType": "current", "bankCountry": "GB", "routingCodes": [ { "type": "SORT CODE", "value": "230363" } ] }, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2026-04-07 12:30:00", "addresses": { "isBusinessAddressSameAsRegisteredAddress": false, "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "London", "state": "GB-ENG", "postcode": "SW1A 1AA", "country": "GB" }, "businessAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "state": "SG", "postcode": "28046", "country": "SG" } }, "applicant": { "firstName": "Hardik", "middleName": "Kumar", "lastName": "Roshan", "dateOfBirth": "1982-07-17", "nationality": "IN", "isPep": true, "email": "hardik+093920@roecny.com", "mobile": "222268870", "mobileCountryCode": "91", "sharePercentage": 80, "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "London", "state": "GB-ENG", "postcode": "SW1A 1AA", "country": "GB" }, "documents": [ { "type": "power_of_attorney", "fileIds": [ "b3cdc844-71cd-4c01-907e-593ddd91debd" ] } ], "positions": [ { "title": "signatory", "startDate": "2020-07-20" } ] }, "stakeholders": { "individual": [ { "externalId": "ind-001", "firstName": "John", "middleName": "A", "lastName": "Doe", "dateOfBirth": "1990-01-01", "isPep": true, "nationality": "SG", "email": "john.doe@example.com", "mobile": "9876543210", "mobileCountryCode": "65", "sharePercentage": 10, "address": { "addressLine1": "Street 1", "addressLine2": "Block A", "city": "Singapore", "state": "SG", "postcode": "123456", "country": "SG" }, "positions": [ { "title": "DIRECTOR", "startDate": "2021-01-01" } ] }, { "externalId": "ind-002", "firstName": "Jane", "middleName": "B", "lastName": "Smith", "dateOfBirth": "1992-02-02", "nationality": "SG", "isPep": false, "email": "jane.smith@example.com", "mobile": "9123456780", "mobileCountryCode": "65", "sharePercentage": 10, "address": { "addressLine1": "Street 2", "addressLine2": "Block B", "city": "London", "state": "GB-ENG", "postcode": "SW1A 1AA", "country": "GB" }, "positions": [ { "title": "SHAREHOLDER", "startDate": "2021-02-01" } ] } ], "corporate": [ { "externalId": "corp-001", "businessName": "XYZ Holdings", "businessRegistrationNumber": "BRN987654", "listedExchange": "NYSE", "registeredCountry": "US", "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "HK", "IN" ], "industryCodes": [ "IS144" ], "industryDescription": "Retail, Wholesale, E-commerce - Household items" }, "expectedAccountUsage": { "intendedUses": [ "IU003" ], "intendedUsesDescription": "Payments to the Supplier", "credit": { "monthlyTransactionVolume": "MVUK10", "monthlyTransactions": "ATC03", "averageTransactionValue": "ATVUK02", "topTransactionCountries": [ "SG", "HK" ] }, "debit": { "monthlyTransactionVolume": "MVUK05", "monthlyTransactions": "ATC02", "averageTransactionValue": "ATVUK01", "topTransactionCountries": [ "IN", "SG" ] } }, "sizeOfBusiness": { "totalEmployees": "EM009", "annualTurnover": "GB008" }, "deviceDetails": { "ipCountryCode": "SG", "deviceInfo": "Windows Laptop", "ipAddress": "192.168.0.1", "sessionId": "session-123456" }, "tags": [ { "key": "priority", "value": "high" } ], "tradeName": "BusinessHit Trade", "documents": [ { "type": "business_registration_doc", "fileIds": [ "b3cdc844-71cd-4c01-907e-593ddd91debd" ] } ] } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "507f8a63-28f9-4b4d-a85b-bc2c22faabeb", "walletType": "base" } ], "customerHashId": "7ddcbea5-2fbe-4b1d-948e-be753cde2043", "referenceId": "bbd2c8a6-4a93-4029-8063-540933647063", "status": "pending", "subStatus": null, "type": "corporate", "kycType": "full", "region": "UK", "externalId": "ext-1234", "tags": [ { "key": "priority", "value": "high" } ], "segment": null, "businessName": "UK_BusinessName", "businessRegistrationNumber": "2026040609339M", "registeredDate": "2020-07-20", "registeredCountry": "GB", "website": "https://www.ukcompany.com", "businessType": "private_company", "applicantDeclaration": true, "isMultiLayeredCompany": false, "applicantDeclarationTimeStamp": "2026-04-07 12:30:00", "tradeName": "BusinessHit Trade", "addresses": { "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "London", "postcode": "SW1A 1AA", "country": "GB", "state": "GB-ENG" }, "isBusinessAddressSameAsRegisteredAddress": false, "businessAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "postcode": "28046", "country": "SG", "state": "SG" } }, "natureOfBusiness": { "operatingCountries": [ "HK", "IN" ], "industryCodes": [ "IS144" ], "industryDescription": "Retail, Wholesale, E-commerce - Household items" }, "expectedAccountUsage": { "intendedUses": [ "IU003" ], "intendedUsesDescription": "Payments to the Supplier", "credit": { "averageTransactionValue": "ATVUK02", "monthlyTransactionVolume": "MVUK10", "monthlyTransactions": "ATC03", "topTransactionCountries": [ "SG", "HK" ] }, "debit": { "averageTransactionValue": "ATVUK01", "monthlyTransactionVolume": "MVUK05", "monthlyTransactions": "ATC02", "topTransactionCountries": [ "IN", "SG" ] } }, "sizeOfBusiness": { "totalEmployees": "EM009", "annualTurnover": "GB008" }, "deviceDetails": { "ipCountryCode": "SG", "deviceInfo": "Windows Laptop", "ipAddress": "192.168.0.1", "sessionId": "session-123456" }, "bankAccountDetails": { "accountName": "BusinessName Pvt Ltd", "accountNumber": "xxxxxxxx", "bankAccountType": "current", "bankName": "HSBC Bank", "bankCountry": "GB", "currency": "GBP", "bankCode": null, "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "SORT CODE", "value": "xxxxxx" } ] }, "applicant": { "externalId": null, "firstName": "Hardik", "middleName": "Kumar", "lastName": "Roshan", "dateOfBirth": "1982-07-17", "nationality": "IN", "email": "hardik+093920@roecny.com", "mobile": "222268870", "mobileCountryCode": "91", "sharePercentage": "80", "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "London", "postcode": "SW1A 1AA", "country": "GB", "state": "GB-ENG" }, "isPep": true, "positions": [ { "title": "signatory" } ], "kycMode": null, "documents": [ { "type": "power_of_attorney", "fileIds": [ "b3cdc844-71cd-4c01-907e-593ddd91debd" ], "identificationNumber": null, "issuanceCountry": null, "expiryDate": null } ], "redirectUrl": null, "referenceId": "11d26e4c-83f0-4bea-a20e-ed99d982b3ab", "kycStatus": "kyc_required" }, "stakeholders": { "individual": [ { "externalId": "ind-001", "firstName": "John", "middleName": "A", "lastName": "Doe", "dateOfBirth": "1990-01-01", "nationality": "SG", "email": "john.doe@example.com", "mobile": "9876543210", "mobileCountryCode": "65", "sharePercentage": "10", "address": { "addressLine1": "Street 1", "addressLine2": "Block A", "city": "Singapore", "postcode": "123456", "country": "SG", "state": "SG" }, "isPep": true, "positions": [ { "title": "DIRECTOR" } ], "documents": null, "kycMode": null, "redirectUrl": null, "referenceId": "e5bb7965-4771-4d2f-8c8e-2b7b9bbd28c0", "kycStatus": "kyc_not_required" }, { "externalId": "ind-002", "firstName": "Jane", "middleName": "B", "lastName": "Smith", "dateOfBirth": "1992-02-02", "nationality": "SG", "email": "jane.smith@example.com", "mobile": "9123456780", "mobileCountryCode": "65", "sharePercentage": "10", "address": { "addressLine1": "Street 2", "addressLine2": "Block B", "city": "London", "postcode": "SW1A 1AA", "country": "GB", "state": "GB-ENG" }, "isPep": false, "positions": [ { "title": "SHAREHOLDER" } ], "documents": null, "kycMode": null, "redirectUrl": null, "referenceId": "8c0c5f45-75d3-4192-8192-48a895b603d8", "kycStatus": "kyc_not_required" } ], "corporate": [ { "externalId": "corp-001", "businessName": "XYZ Holdings", "businessRegistrationNumber": "BRN987654", "registeredCountry": "US", "sharePercentage": null, "positions": [ { "title": "UBO" } ], "referenceId": "dfd5b84f-4de4-4353-b51a-d81ea3c6de44", "kycStatus": "kyc_not_required" } ] }, "documents": [ { "type": "business_registration_doc", "fileIds": [ "b3cdc844-71cd-4c01-907e-593ddd91debd" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). --- # US Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/us-onboarding Learn how to onboard businesses and individuals in the United States using Customer Onboarding v5. US onboarding includes: - Automated business verification (eKYB) - Electronic and manual identity verification (KYC) - Beneficial ownership disclosure (≥ 25%) - Compliance review before activation For more information about onboarding, see [Customer Onboarding](/docs/onboarding/customer-onboarding). ## Business verification (eKYB) After you submit the required details, Nium automatically verifies the business. Depending on the business information provided, you may need to submit supporting documents such as a Certificate of Good Standing or Proof of Business. For more information, see [Required Documents](/docs/onboarding/customer-onboarding/us-onboarding/required-documents). There is no public registry lookup flow for US businesses. ### Step 1: Upload required documents Use the [Create a File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload required business documents. The response returns a `fileId`. You must reference this `fileId` when submitting the onboarding request. For the full list of required documents, see [Required Documents](/docs/onboarding/customer-onboarding/us-onboarding/required-documents). ### Step 2: Applicant declaration The authorized representative must confirm the following statement: > I certify that I am the authorized representative of the customer; all information provided and documents submitted > are complete and correct. I confirm that I have provided all the UBOs present. I have read and accepted > the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture this confirmation using a clickwrap and submit the following fields in your onboarding request: | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | --------------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of the declaration | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | ### Step 3: Submit corporate details Use the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request and include: - Corporate details - Stakeholder details - Uploaded `fileId` references - Applicant declaration fields After submission, the application proceeds to compliance review. ## Individual verification (KYC) US onboarding supports both electronic and manual identity verification for: - Individual customers - Authorized representatives - Directors - Ultimate Beneficial Owners (UBOs) - Other required stakeholders ### Electronic KYC - US residents: Identity is verified automatically where available. If unsuccessful, document upload is required. - Non-US residents: Complete verification using live selfie and passport. If unsuccessful, document upload is required. ### Manual KYC Manual verification is required when: - Electronic verification fails - The customer chooses manual verification - Additional documentation is requested Document requirements: - US residents: National ID - Non-US residents: Passport, National ID, or Driver’s License ## KYC verification ### Step 1: Submit application Create the customer using [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). After submission: | status | substatus | | --------- | --------- | | `pending` | `null` | Nium will send the webhook once substatus changes to `awaiting_kyc`. **Please note:** Initiate KYC verification process only after you receive substatus as `awaiting_kyc`. ### Step 2: Access Pre-built KYC form The applicant opens Nium’s [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form). Access is protected by a One-Time Password (OTP) sent to the registered email address. ### Step 3: Complete identity verification The applicant completes verification in the hosted form. Depending on the flow, this may include: - Automatic verification, or - Uploading a valid proof of identity and completing live selfie verification Stakeholders must complete verification individually. ### Step 4: Compliance review After KYC is completed for the applicant and all required stakeholders: | status | substatus | | --------- | -------------- | | `pending` | `under_review` | Nium’s compliance team reviews submitted information offline. If additional details are required: - An RFI (Request for Information) is raised - The customer responds through the RFI Hosted Form Nium returns the final outcome via webhook. For next steps based on application status, see [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle). ## Stakeholder and ownership requirements ### Ultimate Beneficial Owner (UBO) - All shareholders owning more than 25% (directly or indirectly) must be tagged as `UBO`. - If no individual owns ≥ 25%, declare the most senior director as `UBO`. - If no UBO is submitted, Nium may identify one during compliance review. - For sole traders, the owner must be declared as `UBO`. ### Control person - At least one control person or `CONTROL_PRONG` must be included in the application. - The control prong must be an officer. ### Required UBO coverage At least one `UBO` must be submitted for: - `LIMITED_LIABILITY_COMPANY` - `CORPORATION` - `PUBLIC_COMPANY` ### Signatory / Representative - Individuals who will conduct transactions must be declared as `SIGNATORY` and/or `REPRESENTATIVE`. - The applicant is considered a `REPRESENTATIVE` by default. - Additional representatives may be added during onboarding or after approval (KYC required). ### Multi-layer ownership If another corporate entity owns more than 25% (directly or indirectly): - Declare all corporate stakeholders in the ownership chain. - Submit ownership structure documentation. See [Required Documents](/docs/onboarding/customer-onboarding/us-onboarding/required-documents) for more information. ## Position mapping A `Yes` value indicates that the position can be submitted for that `businessType`.\ A blank cell means the position is not applicable. You can also retrieve valid positions dynamically using [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category = positions`. | businessType | CONTROL\_PRONG | DIRECTOR | EXECUTOR | MEMBERS | PARTNER | PROTECTOR | SETTLOR | SHAREHOLDER | SIGNATORY | TRUSTEE | UBO | | ------------------------------- | -------------- | -------- | -------- | ------- | ------- | --------- | ------- | ----------- | --------- | ------- | --- | | CORPORATION | Yes | Yes | | | | | | Yes | | Yes | | | ESTATE | Yes | | Yes | | | | | Yes | | | | | GENERAL\_PARTNERSHIP | Yes | Yes | | | Yes | | | Yes | | Yes | | | LIMITED\_LIABILITY\_COMPANY | Yes | Yes | | | | | | Yes | | Yes | | | LIMITED\_LIABILITY\_PARTNERSHIP | Yes | Yes | | | Yes | | | Yes | | Yes | | | LIMITED\_PARTNERSHIP | Yes | Yes | | | Yes | | | Yes | | Yes | | | PUBLIC\_COMPANY | Yes | Yes | | | | | | Yes | | Yes | | | TRUST | Yes | | Yes | | Yes | Yes | Yes | Yes | Yes | Yes | | | UNINCORP\_ASSOCIATION | Yes | | | Yes | | | | Yes | | Yes | | ## Related resources - [Required Documents](/docs/onboarding/customer-onboarding/us-onboarding/required-documents) - [US Required Parameters](/docs/onboarding/customer-onboarding/us-onboarding/required-parameters) - [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/us-onboarding/required-documents Learn which documents are required to onboard businesses and individuals registered in the United States. ## Corporate customers The following documents are required for both **manual KYB** and **electronic KYB (eKYB)**, based on the business entity type. | **Business Type** | **Document Type (Manual KYB)** | **Document Type (eKYB)** | | ----------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------ | | **Corporation** / **Limited liability company (LLC)** | `BUSINESS_REGISTRATION_DOC` (Articles of Incorporation) | N/A | | **Sole trader** | `BUSINESS_REGISTRATION_DOC` or `IRS_CERTIFICATE` | `BUSINESS_REGISTRATION_DOC` or `IRS_CERTIFICATE` | | **Unincorporated association** | `BUSINESS_REGISTRATION_DOC` | `BUSINESS_REGISTRATION_DOC` | | **Estate** | `BUSINESS_REGISTRATION_DOC` | `BUSINESS_REGISTRATION_DOC` | | **General partnership** | `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | | **Limited liability partnership** | `BUSINESS_REGISTRATION_DOC`, `PARTNERSHIP_DEED` | `BUSINESS_REGISTRATION_DOC`, `PARTNERSHIP_DEED` | | **Limited partnership** | `BUSINESS_REGISTRATION_DOC`, `PARTNERSHIP_DEED` | `BUSINESS_REGISTRATION_DOC`, `PARTNERSHIP_DEED` | | **Public company** | `PROOF_OF_EXISTENCE` | N/A | | **Trust** | `TRUST_DEED` | `TRUST_DEED` | ### Additional business documents Submit the following documents when applicable: #### CERTIFICATE\_OF\_GOOD\_STANDING Required when the registered address state is `DE` or `NJ`. #### BUSINESS\_REGISTRATION\_DOCUMENT Acceptable examples include: - Articles of Incorporation - Certificate of Formation - Company bylaws - Board resolutions - Operating agreement For details, see [Verifying Your Business in the US](https://www.nium.com/corporate-onboarding/verifying-your-business-in-us#heading-2). #### PROOF\_OF\_BUSINESS Submit this document if no website is provided. It helps Nium verify the customer’s business activity. Accepted documents include: - Product catalog, brochure, marketing material, or business plan (preferred). - Contract, business agreement, or vendor agreement. - Photo of a physical store. - Invoice describing business operations, issued within the last year (not preferred). #### CORPORATE\_STRUCTURE (Ownership Chart) Submit this document if the company has multiple ownership layers. It should include the names and share percentages of all shareholders to help identify the ultimate beneficial owner (UBO). Ownership Chart For guidance on multi-layer ownership, see [Verifying Your Business in the US](https://www.nium.com/corporate-onboarding/verifying-your-business-in-us). For a complete list of accepted document types, see [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category). #### LOA (Letter of Authorization) Provide LOA, if the applicant is not one of the officer. ### Identity Verification documents Individual customers, applicants, and individual stakeholders can verify their identity through \*\*electronic KYC (eKYC) \*\* or **manual KYC** using the hosted form. #### Electronic KYC - **US residents:** Verification may use a national ID and, where applicable, SSN details (for example, the last 4 digits). - **Non-US residents:** Verification typically requires a live selfie with a valid passport, national ID, or driver’s license. #### Manual KYC - Submit a color copy of a valid passport, national ID, or driver’s license (black-and-white copies are not accepted). - If the proof-of-identity document does not contain an address, also provide a separate `PROOF_OF_ADDRESS` document. - Proof of address must be issued within the last 60 days. #### PROOF\_OF\_ADDRESS If the KYC documents submitted does not contains the address then you much submit a valid proof of address. Acceptable proof of address are: - Utility bill. - Bank statement. - Government issued letter. - Phone bill (landline only) - Driver’s license(if address is listed). - National ID card(if address is listed). All Proof of Address documents must be dated within 60 days (not applicable to Driver’s license and National ID card). Cropped documents are not accepted. Invoices are not accepted. PO BOX and CMRA addresses are not accepted. All manual KYC documents undergo fraud checks. If Nium cannot verify authenticity, an RFI may be raised. ## Tips to reduce RFIs and speed up approval - Use an applicant who is an officer registered with the Secretary of State (or submit an `LOA` where required). - Include at least one `CONTROL_PRONG`. `CONTROL_PRONG` should be one of the officers. - Include at least one `UBO` for LLC, Corporation and Public Company. - Ensure the business has an active Secretary of State filing. - Match the registered address to the Secretary of State record (or include supporting address proof where mismatched). - Verify the EIN up front where possible. If you can’t verify it, include supporting tax documentation (for example, an IRS document). - Proof of Address must be submitted in case Passport/ National Id doesn’t contain address. For details, see: - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [US Onboarding](/docs/onboarding/customer-onboarding/us-onboarding) --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/us-onboarding/required-parameters Learn the required parameters, validation rules, and sample payloads for onboarding individual and corporate customers in the US using the Customer Onboarding v5 request. The following guide includes the details that are required when creating a customer using the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request, along with validation rules and sample requests. Use this request to create customers to onboard in United Kingdom. The endpoint accepts both individual and corporate customer. For a breakdown of the request and parameters, see [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). ## Endpoint URL POST `/api/v5/client/{clientHashId}/customers` ### Path parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------------------- | | `clientHashId` | string | Yes | Unique client identifier, generated and shared before the integration is set up. | ### Body parameters | Field (M/O/C) | Description | Data type | Accepted values | | ---------------- | -------------------------------------------------- | --------- | --------------------------------------------------------------- | | `type` (M) | Customer type. | enum | `individual`, `corporate` | | `kycType` (M) | KYC type performed for this customer. | enum | `minimum`, `full` | | `region` (M) | Regulatory region the customer is onboarded under. | enum | Use `US` | | `externalId` (O) | Customer-provided reference ID. | string | Max 36 chars; alphanumeric; unique per customer under a client. | ## Individual Customers ### billingAddress | Field (M/O/C) | Description | Data type | Accepted values | | --------------------------------- | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | `billingAddress` (M) | Customer billing address. | object | — | | `billingAddress.addressLine1` (M) | Address line 1. | string | Max 100 chars | | `billingAddress.addressLine2` (O) | Address line 2. | string | Max 100 chars | | `billingAddress.city` (M) | City. | string | Max 50 chars | | `billingAddress.state` (M) | State/region. | string/enum | enum: `icategory=isoState` for `countryCode=xx` (e.g., `US`, `SG`). If enum list is empty, pass as string (max 50 chars). | | `billingAddress.postcode` (M) | Postal/ZIP code. | string | Max 10 chars; alphanumeric and spaces | | `billingAddress.country` (M) | Country. | enum | category: `countryName` | ### expectedAccountUsage | Field (M/O/C) | Description | Data type | Accepted values | | ---------------------------------------------------------- | ------------------------------------------------------- | -------------- | ------------------------------------ | | `expectedAccountUsage` (M) | Account usage activity profile. | object | — | | `expectedAccountUsage.credit` (M) | Expected account usage for payins. | object | — | | `expectedAccountUsage.credit.monthlyTransactionVolume` (M) | Monthly transaction volume range. | enum | category: `monthlyTransactionVolume` | | `expectedAccountUsage.credit.topTransactionCountries` (M) | Top 5 countries where funding is expected to originate. | array of enums | category: `countryName` | | `expectedAccountUsage.debit` (M) | Expected account usage for payouts. | object | — | | `expectedAccountUsage.debit.monthlyTransactionVolume` (M) | Monthly transaction volume range. | enum | category: `monthlyTransactionVolume` | | `expectedAccountUsage.debit.topTransactionCountries` (M) | Top 5 countries for payouts. | array of enums | category: `countryName` | | `expectedAccountUsage.intendedUses` (M) | Intended uses of the account. | array of enums | category: `intendedUseOfAccount` | | `expectedAccountUsage.intendedUsesDescription` (C) | Required if `intendedUses` includes `Others`. | string | Max 500–1000 chars (varies by flow) | ### bankAccountDetails | Field (M/O/C) | Description | Data type | Accepted values | | ------------------------------------------- | ------------------------------------------------------------ | --------- | --------------------------------------------------------- | | `bankAccountDetails` (M) | Bank account details used to return funds (returns/refunds). | object | — | | `bankAccountDetails.accountName` (M) | Account holder name as registered with the bank. | string | Alphanumeric plus: `& . , ( ) _ ' / -`; max 140 chars | | `bankAccountDetails.accountNumber` (M) | Bank account number for returns/refunds. | string | Alphanumeric; max 35 chars | | `bankAccountDetails.bankCountry` (M) | Country where the bank account is held (ISO 3166-1 alpha-2). | string | category: `countryName` | | `bankAccountDetails.bankAccountType` (C) | Bank account type (e.g., `savings`, `checking`, `current`). | string | Use the Bene schema endpoint to fetch exact requirements. | | `bankAccountDetails.bankName` (C) | Full legal bank name. | string | Max 255 chars | | `bankAccountDetails.currency` (M) | Bank account currency (ISO 4217). | string | Example: `USD`, `INR` | | `bankAccountDetails.routingCodes.type` (M) | Routing identifier type. | string | `ACH CODE`, `SWIFT` | | `bankAccountDetails.routingCodes.value` (M) | Routing identifier value for the specified type. | string | — | ### deviceDetails | Field (M/O/C) | Description | Data type | Accepted values | | --------------------------------- | --------------------------------------- | --------- | ----------------------- | | `deviceDetails` (M) | Device/session details (security/risk). | object | — | | `deviceDetails.ipCountryCode` (M) | Country of origin for the IP address. | enum | category: `countryName` | | `deviceDetails.deviceInfo` (M) | Device operating system information. | string | — | | `deviceDetails.ipAddress` (M) | Device IP address. | string | Valid IPv4 address | | `deviceDetails.sessionId` (M) | Session ID that initiated the request. | string | — | ### declarations | Field (M/O/C) | Description | Data type | Accepted values | | ----------------------------------- | --------------------------------------------------- | --------- | --------------- | | `applicantDeclaration` (M) | Applicant confirmation they accept the declaration. | boolean | Must be `true` | | `applicantDeclarationTimeStamp` (M) | Timestamp when the declaration was accepted. | date | — | ### tags | Field (M/O/C) | Description | Data type | Accepted values | | ---------------- | ---------------------- | --------- | --------------------- | | `tags` (O) | User-defined metadata. | object | — | | `tags.key` (O) | User-defined key. | string | Example: `merchantID` | | `tags.value` (O) | User-defined value. | string | Example: `MID123` | ### Corporate Customers ### corporateCustomerFields | Field (M/O/C) | Description | Data type | Accepted values | | -------------------------------- | ------------------------------------------------------------------------------------------ | --------- | --------------------------------- | | `businessType` (M) | Business type for the corporate customer. | enum | category: `businessType` | | `businessName` (M) | Legal business name. | string | Max 80 chars | | `tradeName` (M) | Doing-business-as name (if different from legal name). | string | Max 80 chars | | `businessRegistrationNumber` (M) | Business registration number (EIN). Sole traders may submit TIN/SSN if EIN is unavailable. | string | 9 digits | | `registeredDate` (M) | Business registration date. | date | `YYYY-MM-DD`; must be a past date | | `registeredCountry` (M) | Country of registration. | enum | category: `countryName` | | `website` (C) | Business website. If unavailable, provide a proof-of-business document. | string | Max 255 chars | | `isMultiLayeredCompany` (M) | Whether the business has multi-layer ownership (via intermediaries). | boolean | — | | `listedExchange` (C) | Required for public companies. | enum | — | | `stockSymbol` (C) | Public ticker symbol (public companies). | string | — | | `trustType` (C) | Unregulated trust type (trust companies). | string | — | ### registeredAddress | Field (M/O/C) | Description | Data type | Accepted values | | ------------------------------------ | ---------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | `registeredAddress` (M) | Registered address for the corporate customer. | object | — | | `registeredAddress.addressLine1` (M) | Address line 1. | string | Max 100 chars | | `registeredAddress.addressLine2` (O) | Address line 2. | string | Max 100 chars | | `registeredAddress.city` (M) | City. | string | Max 50 chars | | `registeredAddress.state` (M) | State/region. | string/enum | enum: `icategory=isoState` for `countryCode=xx` (e.g., `US`, `SG`). If enum list is empty, pass as string (max 50 chars). | | `registeredAddress.postcode` (M) | Postal/ZIP code. | string | Max 10 chars; alphanumeric and spaces | | `registeredAddress.country` (M) | Country. | enum | category: `countryName` | ### businessAddress | Field (M/O/C) | Description | Data type | Accepted values | | ---------------------------------- | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | `businessAddress` (M) | Communication/business address. | object | — | | `businessAddress.addressLine1` (M) | Address line 1. | string | Max 100 chars | | `businessAddress.addressLine2` (O) | Address line 2. | string | Max 100 chars | | `businessAddress.city` (M) | City. | string | Max 50 chars | | `businessAddress.state` (M) | State/region. | string/enum | enum: `icategory=isoState` for `countryCode=xx` (e.g., `US`, `SG`). If enum list is empty, pass as string (max 50 chars). | | `businessAddress.postcode` (M) | Postal/ZIP code. | string | Max 10 chars; alphanumeric and spaces | | `businessAddress.country` (M) | Country. | enum | category: `countryName` | ### natureOfBusiness | Field (M/O/C) | Description | Data type | Accepted values | | ------------------------------------------ | ------------------------------------------------------------- | -------------- | ------------------------------ | | `natureOfBusiness` (M) | Business profile for the corporate customer. | object | — | | `natureOfBusiness.operatingCountries` (M) | Countries where the business operates. | array of enums | category: `countryOfOperation` | | `natureOfBusiness.industryCodes` (M) | Industry sectors the business operates in (multiple allowed). | array of enums | category: `industrySector` | | `natureOfBusiness.industryDescription` (M) | Description of the business. | string | Max 1000 chars | ### sizeOfBusiness | Field (M/O/C) | Description | Data type | Accepted values | | ----------------------------------- | ------------------------------ | --------- | -------------------------- | | `sizeOfBusiness` (M) | Business size profile. | object | — | | `sizeOfBusiness.totalEmployees` (M) | Total number of employees. | enum | — | | `sizeOfBusiness.annualTurnover` (M) | Annual revenue/turnover range. | enum | category: `annualTurnover` | ### applicant | Field (M/O/C) | Description | Data type | Accepted values | | --------------------------------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------------ | | `applicant` (M) | Individual submitting the application on behalf of the customer. | object | — | | `applicant.externalId` (O) | Applicant reference identifier. | string | Max 36 chars; alphanumeric; unique across applicant + stakeholders | | `applicant.firstName` (M) | Applicant first name. | string | Max 40 chars | | `applicant.middleName` (O) | Applicant middle name. | string | Max 40 chars | | `applicant.lastName` (M) | Applicant last name. | string | Max 40 chars | | `applicant.dateOfBirth` (M) | Applicant date of birth. | date/string | `YYYY-MM-DD`; must be a past date | | `applicant.nationality` (M) | Applicant nationality. | enum | category: `countryName` | | `applicant.email` (M) | Applicant email. | string | Max 60 chars; valid email | | `applicant.mobile` (M) | Mobile number (without country code). | string | Max 15 chars | | `applicant.mobileCountryCode` (M) | Mobile country calling code. | string | Max 6 chars | | `applicant.sharePercentage` (O) | Applicant ownership share percentage. | numeric | 0–100 (decimal). Required if applicant is UBO/shareholder. | ### address | Field (M/O/C) | Description | Data type | Accepted values | | -------------------------- | --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | `address` (M) | Residential address (used for applicant and individual stakeholders). | object | — | | `address.addressLine1` (M) | Address line 1. | string | Max 100 chars | | `address.addressLine2` (O) | Address line 2. | string | Max 50–100 chars (varies by flow) | | `address.city` (M) | City. | string | Max 50 chars | | `address.state` (M) | State/region. | string/enum | enum: `icategory=isoState` for `countryCode=xx` (e.g., `US`, `SG`). If enum list is empty, pass as string (max 50 chars). | | `address.country` (M) | Country. | enum | category: `countryName` | | `address.postcode` (M) | Postal/ZIP code. | string | Max 10 chars; alphanumeric and spaces | ### positions | Field (M/O/C) | Description | Data type | Accepted values | | --------------------- | ---------------------------------------------------------------- | ---------------- | ---------------------------------- | | `positions` (M) | Positions held (multiple allowed). | array of objects | — | | `positions.title` (M) | Position title (e.g., authorised representative, director, UBO). | enum | category: `positions` / `position` | ### documents | Field (M/O/C) | Description | Data type | Accepted values | | ---------------------- | -------------------------------------------------- | ---------------- | ----------------------------------------------------------------- | | `documents` (C) | Documents for the customer or applicant. | array of objects | Examples: `PROOF_OF_BUSINESS`, `OWNERSHIP_CHART` (varies by flow) | | `documents.type` (C) | Document type. | enum | category: `documentType` | | `documents.fields` (C) | File IDs returned by the Upload Document endpoint. | — | — | ### stakeholders | Field (M/O/C) | Description | Data type | Accepted values | | ----------------------------- | ----------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------- | | `stakeholders` (O) | Stakeholders who hold positions in the corporate customer (as shown in official records). | object | At least one control prong must exist between applicant and individual stakeholder. | | `stakeholders.individual` (O) | Individual stakeholders (natural persons). | array of objects | — | | `stakeholders.corporate` (O) | Corporate stakeholders (organizations). | array of objects | — | ### stakeholders.individual | Field (M/O/C) | Description | Data type | Accepted values | | ----------------------- | -------------------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------- | | `externalId` (O) | Reference identifier used to identify the stakeholder. Must be unique across stakeholders and applicant. | string | Max 36 chars; alphanumeric | | `firstName` (M) | Stakeholder first name. | string | Max 40 chars | | `middleName` (O) | Stakeholder middle name. | string | Max 40 chars | | `lastName` (M) | Stakeholder last name. | string | Max 40 chars | | `dateOfBirth` (M) | Stakeholder date of birth. | date | `YYYY-MM-DD`; must be a past date | | `nationality` (M) | Stakeholder nationality. | enum | category: `countryName` | | `email` (O) | Stakeholder email address. | string | Max 60 chars; valid email | | `mobile` (O) | Stakeholder mobile number (without country code). | string | Max 15 chars | | `mobileCountryCode` (O) | Stakeholder mobile country calling code. | string | Max 6 chars | | `sharePercentage` (O) | Ownership percentage held by the stakeholder. | numeric | 0–100 (decimal). Required if stakeholder holds a UBO or shareholder position. | | `address` (M) | Residential address of the stakeholder. | object | — | | `positions` (M) | Positions held by the stakeholder. | array of objects | — | ### stakeholders.corporate | Field (M/O/C) | Description | Data type | Accepted values | | -------------------------------- | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------- | | `externalId` (O) | Reference identifier used to identify the stakeholder. | string | Max 36 chars; alphanumeric | | `businessName` (M) | Legal name of the corporate stakeholder. | string | Max 80 chars | | `businessRegistrationNumber` (M) | Registration number of the corporate stakeholder. | string | Max 30 chars | | `registeredCountry` (M) | Country of registration for the corporate stakeholder. | enum | category: `countryName` | | `sharePercentage` (O) | Ownership percentage held by the stakeholder. | numeric | 0–100 (decimal). Required if stakeholder also holds a UBO/shareholder position. | | `positions` (M) | Positions held by the stakeholder in the corporate customer. | array of objects | — | ### bankAccountDetails | Field (M/O/C) | Description | Data type | Accepted values | | ------------------------------------------- | ------------------------------------------------------------ | --------- | --------------------------------------------------------- | | `bankAccountDetails` (M) | Bank account details used to return funds (returns/refunds). | object | — | | `bankAccountDetails.accountName` (M) | Account holder name as registered with the bank. | string | Alphanumeric plus: `& . , ( ) _ ' / -`; max 140 chars | | `bankAccountDetails.accountNumber` (M) | Bank account number for returns/refunds. | string | Alphanumeric; max 35 chars | | `bankAccountDetails.bankCountry` (M) | Country where the bank account is held (ISO 3166-1 alpha-2). | string | category: `countryName` | | `bankAccountDetails.bankAccountType` (C) | Bank account type (e.g., `savings`, `checking`, `current`). | string | Use the Bene schema endpoint to fetch exact requirements. | | `bankAccountDetails.bankName` (C) | Full legal bank name. | string | Max 255 chars | | `bankAccountDetails.currency` (M) | Bank account currency (ISO 4217). | string | Example: `USD`, `INR` | | `bankAccountDetails.routingCodes.type` (M) | Routing identifier type. | string | `ACH CODE`, `SWIFT` | | `bankAccountDetails.routingCodes.value` (M) | Routing identifier value for the specified type. | string | — | ### deviceDetails | Field (M/O/C) | Description | Data type | Accepted values | | --------------------------------- | --------------------------------------- | --------- | ----------------------- | | `deviceDetails` (M) | Device/session details (security/risk). | object | — | | `deviceDetails.ipCountryCode` (M) | Country of origin for the IP address. | enum | category: `countryName` | | `deviceDetails.deviceInfo` (M) | Device operating system information. | string | — | | `deviceDetails.ipAddress` (M) | Device IP address. | string | Valid IPv4 address | | `deviceDetails.sessionId` (M) | Session ID that initiated the request. | string | — | ### declarations | Field (M/O/C) | Description | Data type | Accepted values | | ----------------------------------- | --------------------------------------------------- | --------- | --------------- | | `applicantDeclaration` (M) | Applicant confirmation they accept the declaration. | boolean | Must be `true` | | `applicantDeclarationTimestamp` (M) | Timestamp when the declaration was accepted. | date | — | ### tags | Field (M/O/C) | Description | Data type | Accepted values | | ---------------- | ---------------------- | ---------------- | --------------------- | | `tags` (O) | User-defined metadata. | Array of objects | — | | `tags.key` (O) | User-defined key. | string | Example: `merchantID` | | `tags.value` (O) | User-defined value. | string | Example: `MID123` | **Note** : For all data type as enum, please refer to the category mentioned in the column - “Accepted values” in the above table and pass that as a query parameter to the \ API. The API response contains an array of code-description pairs that are valid for the given field. Please refer to the sample request for more clarity. ## Sample Request & Response ### Individual Customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "US", "externalId": "ext-123456", "firstName": "Rahul", "middleName": "Kumar", "lastName": "Rajawat", "email": "support@nium.com", "nationality": "FR", "mobile": "123489767", "mobileCountryCode": "1", "dateOfBirth": "2000-08-01", "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "applicantDeclaration": "true", "tags": [ { "key": "testing", "value": "Automation" } ], "deviceDetails": { "ipCountryCode": "us", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "intendedUsesDescription": "Business Description or the purpose of account", "credit": { "monthlyTransactionVolume": "MVUS01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "intendedUses": [ "IU108", "IU107" ], "debit": { "monthlyTransactionVolume": "MVUS01", "topTransactionCountries": [ "GB", "GB", "GB", "IN", "US" ] } }, "bankAccountDetails": { "accountName": "Rahul Rajawat", "accountNumber": "AT483200000012345", "bankName": "DEUTSCHE BANK AG - POSTBANK BRANCH", "bankCountry": "US", "bankAccountType": "saving", "currency": "USD", "routingCodes": [ { "type": "ACH CODE", "value": "042100175" } ] }, "billingAddress": { "addressLine1": "AddressLine1 Building Floor", "addressLine2": "", "city": "California", "state": "US-AK", "postcode": "102034", "country": "US" } } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "be8e8d76-0d1f-49c1-8ca2-1c37926aa428", "walletType": "base" } ], "customerHashId": "8ff562fa-2a6e-4e7a-821a-9544e587de42", "referenceId": "b99df203-87bf-4bd3-ae0b-0b750552c89a", "status": "pending", "subStatus": null, "type": "individual", "kycType": "full", "region": "US", "externalId": "ext-123456", "tags": [ { "key": "testing", "value": "Automation" } ], "segment": null, "firstName": "Rahul", "middleName": "Kumar", "lastName": "Rajawat", "email": "support@nium.com", "nationality": "FR", "dateOfBirth": "2000-08-01", "mobile": "123489767", "mobileCountryCode": "1", "kycStatus": "kyc_required", "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "deviceDetails": { "ipCountryCode": "us", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "intendedUses": [ "IU108", "IU107" ], "intendedUsesDescription": "Business Description or the purpose of account", "credit": { "monthlyTransactionVolume": "MVUS01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "debit": { "monthlyTransactionVolume": "MVUS01", "topTransactionCountries": [ "GB", "GB", "GB", "IN", "US" ], "bankAccountDetails": null } }, "bankAccountDetails": { "accountName": "Rahul Rajawat", "accountNumber": "xxxxxxxxxxxxxxxxx", "bankAccountType": "saving", "bankName": "DEUTSCHE BANK AG - POSTBANK BRANCH", "bankCountry": "US", "currency": "USD", "bankCode": null, "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "ACH CODE", "value": "xxxxxxxxx" } ] }, "billingAddress": { "addressLine1": "AddressLine1 Building Floor", "addressLine2": "", "city": "California", "postcode": "102034", "country": "US", "state": "US-AK" }, "kycMode": null, "documents": null } ``` ### Corporate Customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "US", "businessName": "ABC corporation", "businessRegistrationNumber": "123456788", "registeredDate": "2024-05-21", "registeredCountry": "US", "website": "www.idfc348.com", "isMultiLayeredCompany": false, "listedExchange": "EX101", "stockSymbol": "NSE", "businessType": "public_company", "bankAccountDetails": { "accountName": "ABC corporation", "accountNumber": "AT483200000012345", "bankName": "DEUTSCHE BANK AG - POSTBANK BRANCH", "bankCountry": "US", "bankAccountType": "saving", "currency": "USD", "routingCodes": [ { "type": "ACH CODE", "value": "042100175" } ] }, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "addresses": { "isBusinessAddressSameAsRegisteredAddress": false, "registeredAddress": { "addressLine1": "addressLine1", "addressLine2": "addressLine2", "city": "city", "state": "US-AL", "postcode": "35203", "country": "US" }, "businessAddress": { "addressLine1": "busaddressLine1", "addressLine2": "addressLine2", "city": "city", "state": "US-AK", "postcode": "35203", "country": "US" } }, "applicant": { "firstName": "applicantFirst", "middleName": "applicantMiddle", "lastName": "applicantLast", "dateOfBirth": "1990-04-21", "nationality": "US", "email": "test.shank@trin.com", "mobile": "7337223608", "mobileCountryCode": "65", "sharePercentage": 98, "address": { "addressLine1": "applicantLine1", "addressLine2": "applicantLine2", "city": "applicantCity", "state": "FR-20R", "postcode": "478547", "country": "FR" }, "documents": [ { "type": "LOA", "fileIds": [ "087244f3-b4f9-4c54-92df-b472123a6166" ] } ], "positions": [ { "title": "control_prong", "startDate": "2025-04-21" } ] }, "stakeholders": { "individual": [ { "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d861", "firstName": "stake1", "middleName": "stake1Mid", "lastName": "stake1Last", "dateOfBirth": "1990-04-21", "nationality": "LT", "email": "test@nium.com", "mobile": "8106869840", "mobileCountryCode": "65", "sharePercentage": 80, "address": { "addressLine1": "indiviAdd1", "addressLine2": "indiviAdd2", "city": "indiviCity", "state": "US-CA", "postcode": "63535", "country": "US" }, "positions": [ { "title": "director", "startDate": "2025-04-21" } ] }, { "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d864", "firstName": "stake2", "middleName": "stake2Middle1", "lastName": "stake2Last1", "dateOfBirth": "2000-04-21", "nationality": "AU", "email": "test@nium.com", "mobile": "65656565656", "mobileCountryCode": "65", "sharePercentage": 80, "address": { "addressLine1": "indiviAdd1", "addressLine2": "indiviAdd2", "city": "indiviCity", "state": "FR-20R", "postcode": "63535", "country": "FR" }, "positions": [ { "title": "SETTLOR", "startDate": "2025-04-21" } ] } ], "corporate": [ { "externalId": "90ab1818-ef2d-44ee-96c0-7d367842d869", "businessName": "ABC Pvt Ltd", "businessRegistrationNumber": "BRN123456", "registeredCountry": "SG", "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "US" ], "industryCodes": [ "IS134" ], "industryDescription": "" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "intendedUsesDescription_78d7fdff1d03", "credit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS01", "topTransactionCountries": [ "SG" ] }, "debit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS01", "topTransactionCountries": [ "SG" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "US008" }, "deviceDetails": { "ipCountryCode": "sg", "deviceInfo": "MAC", "ipAddress": "192.168.1.1", "sessionId": "40531ac01a6f11edafc28dba55d51275" }, "tags": [ { "key": "key_67cef24340df", "value": "value_56606dcf8aa4" } ], "tradeName": "tradeName_f57f429a7dfb", "documents": [ { "type": "business_registration_doc", "fileIds": [ "787244f3-b4f9-4c54-02af-b472123a6067" ] } ] } ``` Sample Successful Response ```json { "wallets": [ { "walletHashId": "ec305b62-b529-4c23-aeff-ff0a76054cf9", "walletType": "base" } ], "customerHashId": "2691e5b0-db0d-4a21-a80f-eb3dd8dad4dd", "referenceId": "3cd0f914-9132-4055-8ad4-52c797358c71", "status": "pending", "subStatus": null, "type": "corporate", "kycType": "full", "region": "US", "externalId": null, "tags": [ { "key": "key_67cef24340df", "value": "value_56606dcf8aa4" } ], "segment": null, "businessName": "ABC corporation", "businessRegistrationNumber": "123456788", "registeredDate": "2024-05-21", "registeredCountry": "US", "website": "www.idfc348.com", "businessType": "public_company", "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "stockSymbol": "NSE", "listedExchange": "EX101", "trustType": null, "tradeName": "tradeName_f57f429a7dfb", "isMultiLayeredCompany": false, "addresses": { "registeredAddress": { "addressLine1": "addressLine1", "addressLine2": "addressLine2", "city": "city", "postcode": "35203", "country": "US", "state": "US-AL" }, "isBusinessAddressSameAsRegisteredAddress": false, "businessAddress": { "addressLine1": "busaddressLine1", "addressLine2": "addressLine2", "city": "city", "postcode": "35203", "country": "US", "state": "US-AK" } }, "natureOfBusiness": { "operatingCountries": [ "US" ], "industryCodes": [ "IS134" ], "industryDescription": "" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "intendedUsesDescription_78d7fdff1d03", "credit": { "averageTransactionValue": "ATVUS01", "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "topTransactionCountries": [ "SG" ] }, "debit": { "averageTransactionValue": "ATVUS01", "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "topTransactionCountries": [ "SG" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "US008" }, "deviceDetails": { "ipCountryCode": "sg", "deviceInfo": "MAC", "ipAddress": "192.168.1.1", "sessionId": "40531ac01a6f11edafc28dba55d51275" }, "bankAccountDetails": { "accountName": "ABC corporation", "accountNumber": "xxxxxxxxxxxxxxxxx", "bankAccountType": "saving", "bankName": "DEUTSCHE BANK AG - POSTBANK BRANCH", "bankCountry": "US", "currency": "USD", "bankCode": null, "identificationType": null, "identificationValue": null, "localRegisteredName": null, "routingCodes": [ { "type": "ACH CODE", "value": "xxxxxxxxx" } ] }, "applicant": { "externalId": null, "firstName": "applicantFirst", "middleName": "applicantMiddle", "lastName": "applicantLast", "dateOfBirth": "1990-04-21", "nationality": "US", "email": "test.shank@trin.com", "mobile": "7337223608", "mobileCountryCode": "65", "sharePercentage": "98", "address": { "addressLine1": "applicantLine1", "addressLine2": "applicantLine2", "city": "applicantCity", "postcode": "478547", "country": "FR", "state": "FR-20R" }, "positions": [ { "title": "control_prong" } ], "referenceId": "8b721568-f99c-458f-b2df-5c82f2fbddcc", "kycMode": null, "kycStatus": "kyc_required", "documents": [ { "type": "LOA", "fileIds": [ "087244f3-b4f9-4c54-92df-b472123a6166" ], "identificationNumber": null, "issuanceCountry": null, "expiryDate": null } ] }, "stakeholders": { "individual": [ { "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d861", "firstName": "stake1", "middleName": "stake1Mid", "lastName": "stake1Last", "dateOfBirth": "1990-04-21", "nationality": "LT", "email": "test@nium.com", "mobile": "8106869840", "mobileCountryCode": "65", "sharePercentage": "80", "address": { "addressLine1": "indiviAdd1", "addressLine2": "indiviAdd2", "city": "indiviCity", "postcode": "63535", "country": "US", "state": "US-CA" }, "positions": [ { "title": "director" } ], "documents": null, "referenceId": "44d5ca39-5f62-4611-855c-d5d7d51bc6d2", "kycMode": null, "kycStatus": "kyc_required" }, { "externalId": "10ab1818-ef2d-44ee-96c0-7d367842d864", "firstName": "stake2", "middleName": "stake2Middle1", "lastName": "stake2Last1", "dateOfBirth": "2000-04-21", "nationality": "AU", "email": "test@nium.com", "mobile": "65656565656", "mobileCountryCode": "65", "sharePercentage": "80", "address": { "addressLine1": "indiviAdd1", "addressLine2": "indiviAdd2", "city": "indiviCity", "postcode": "63535", "country": "FR", "state": "FR-20R" }, "positions": [ { "title": "SETTLOR" } ], "documents": null, "referenceId": "ba767e05-e838-484e-9968-f5e039ff9b4e", "kycMode": null, "kycStatus": "kyc_required" } ], "corporate": [ { "externalId": "90ab1818-ef2d-44ee-96c0-7d367842d869", "businessName": "ABC Pvt Ltd", "businessRegistrationNumber": "BRN123456", "registeredCountry": "SG", "sharePercentage": null, "positions": [ { "title": "UBO" } ], "referenceId": "bcb7c9ad-957d-426c-93e5-12867cf66a51", "kycStatus": "kyc_not_required" } ] }, "documents": [ { "type": "business_registration_doc", "fileIds": [ "787244f3-b4f9-4c54-02af-b472123a6067" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). | --- # HK Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/hk-onboarding Learn how to onboard businesses and individuals in the Hong Kong using Customer Onboarding v5. HK onboarding includes: - Manual business verification - Electronic and manual identity verification (KYC) - Beneficial ownership disclosure (≥ 25%) - Compliance review before activation [//]: # "For more information about onboarding, see [Customer Onboarding](/docs/onboarding/customer)." ## Onboarding Flow Nium offers only Manual KYB flows for customers in Hong Kong. Submission of business documents may be required depending on the business type. Check [HK Required Documents](/docs/onboarding/customer-onboarding/hk-onboarding/required-documents). ### Step 1: Upload required documents Use the [Files API](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload required business documents. The response returns a `fileId`. You must reference this `fileId` when submitting the onboarding request. For the full list of required documents, see [HK Required Documents](/docs/onboarding/customer-onboarding/hk-onboarding/required-documents). ### Step 2: Applicant declaration The authorized representative must confirm the following statement: > I certify that I am the authorized representative of the customer; all information provided and documents submitted > are complete and correct. I confirm that I have provided all the UBOs present. I have read and accepted > the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture this confirmation using a clickwrap and submit the following fields in your onboarding request: | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ---------------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of the declaration. | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | ### Step 3: Submit customer details Use the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request and include: - customer details - Customer Registered address - Stakeholder & applicant details (applicable for corporate customer) - Uploaded `fileId` references - Applicant declaration fields - Bank Account Details After submission, the applicant proceeds for KYC Verification. | status | substatus | | --------- | -------------- | | `pending` | `awaiting_kyc` | ### Step 4: Complete Identity Verification (KYC) The applicant opens the Nium’s Pre-built KYC form. Access is protected by a One-Time Password (OTP) sent to the registered email address of the applicant. HK onboarding supports both electronic and manual identity verification for applicant or stakeholders. ### Electronic KYC Complete verification using live selfie with documents like passport or national id. If unsuccessful, document upload is required. ### Manual KYC If Electronic verification fails customer can choose to complete the verification manually. Document requirements: Passport or National ID See [HK Required Documents](/docs/onboarding/customer-onboarding/hk-onboarding/required-documents) for more information on POI/ POA documents for identity verification ### Step 5: Compliance review After KYC is completed for the applicant | status | substatus | | --------- | -------------- | | `pending` | `under_review` | Nium’s compliance team reviews submitted information offline. If additional details are required: - An RFI (Request for Information) is raised - The customer responds through the RFI Hosted Form Nium returns the final outcome via webhook. For next steps based on application status, see [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle). ### Multi-layer ownership If another corporate entity owns more than 25% (directly or indirectly): - Declare all corporate stakeholders in the ownership chain. - Submit ownership structure documentation. See [HK Required Documents](/docs/onboarding/customer-onboarding/hk-onboarding/required-documents) for more information. ## Position mapping A `Yes` value indicates that the position can be submitted for that `businessType`.\ A blank cell means the position is not applicable. You can also retrieve valid positions dynamically using [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category = position`. | `businessType` | `DIRECTOR` | `PARTNER` | `REPRESENTATIVE` | `SHAREHOLDER` | `SIGNATORY` | `UBO` | | :------------------------ | :--------- | :-------- | :--------------- | :------------ | :---------- | :---- | | `FOREIGN_COMPANY_OFFICE` | Yes | | Yes | Yes | Yes | Yes | | `GENERAL_PARTNERSHIP` | | Yes | Yes | | Yes | | | `LIMITED_PARTNERSHIP` | | Yes | Yes | | Yes | | | `OTHERS` | Yes | | Yes | Yes | Yes | Yes | | `PRIVATE_LIMITED_COMPANY` | Yes | | Yes | Yes | Yes | Yes | | `PUBLIC_COMPANY` | Yes | | Yes | Yes | Yes | Yes | | `SOLE_TRADER` | | | Yes | | Yes | | ## Adding Positions - **Directors:** Add all management directors as stakeholders. - **UBOs:** Tag anyone owning ≥ 25% (direct or indirect). If none, the most senior director becomes the UBO. - **Representatives/Signatories:** Add individuals authorized to transact or manage users (applicant is a Representative by default). - **Partners/Trustees/Settlors:** Include when applicable by entity type. - **Multi-layered companies:** Include all corporate stakeholders with ≥ 25% ownership and upload a **Corporate Structure** document (`documentType: CORPORATE_STRUCTURE`). ## Related resources - [HK Required Documents](/docs/onboarding/customer-onboarding/hk-onboarding/required-documents) - [HK Required Parameters](/docs/onboarding/customer-onboarding/hk-onboarding/required-parameters) - [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/hk-onboarding/required-documents Learn which documents are required to onboard businesses and individuals registered in the Hong Kong. ## Corporate customers The following documents are required for business verification, based on the business entity type. | `businessType` | Manual KYB | | :----------------------- | :-------------------------------------------------------- | | `FOREIGN_COMPANY_OFFICE` | Any of the most recently lodged `NAR1` or `NNC1` or `NN3` | | `GENERAL_PARTNERSHIP` | `BUSINESS_REGISTRATION_DOC` `PARTNERSHIP_DEED` | | `LIMITED_PARTNERSHIP` | `BUSINESS_REGISTRATION_DOC` `PARTNERSHIP_DEED` | | `OTHER` | Either of the most recently lodged `NAR1` or `NNC1` | | `PRIVATE_COMPANY` | Either of the most recently lodged `NAR1` or `NNC1` | | `PUBLIC_COMPANY` | Either of the most recently lodged `NAR1` or `NNC1` | | `SOLE_TRADER` | `BUSINESS_REGISTRATION_DOC` | | | | For a complete list of business document types, see the values obtained from [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category) API with `category` as `documentType`. ### Additional business documents Submit the following documents when applicable: #### BUSINESS\_REGISTRATION\_DOCUMENT Acceptable examples include: - Business Registration (BR), issued within 12 months \[required] - Incorporation document (COI) OR Memorandum + Articles of Association For details, see [Verifying Your Business in the HK](https://www.nium.com/corporate-onboarding/verifying-your-business-in-hong-kong). #### PROOF\_OF\_BUSINESS Submit this document if no website is provided. It helps Nium verify the customer’s business activity. Accepted documents include: - Product catalog, brochure, marketing material, or business plan (preferred). - Contract, business agreement, or vendor agreement. - Photo of a physical store. - Invoice describing business operations, issued within the last year (not preferred). #### OWNERSHIP\_CHART Submit this document if the company has multiple ownership layers. It should include the names and share percentages of all shareholders to help identify the ultimate beneficial owner (UBO). Ownership Chart For guidance on multi-layer ownership, see [Verifying Your Business in the HK](https://www.nium.com/corporate-onboarding/verifying-your-business-in-hong-kong#heading-6). #### LOA (Letter of Authorization) Provide LOA, if the applicant's position is not director or ubo or partner. ### Identity Verification documents Individual customers, applicants, and individual stakeholders can verify their identity through **electronic KYC** or \* *manual KYC*\* using the Pre-built KYC form. #### Electronic KYC Verification typically requires a live selfie with a valid passport, national ID. #### Manual KYC - Submit a color copy of a valid Passport or National ID. Please note, - black-and-white copies are not accepted. - Copy of a copy is not accepted - Document should be with valid expiry date, good quality, colored copy, all four corners must be visible - If the proof-of-identity document does not contain an address, also provide a separate `PROOF_OF_ADDRESS` document. Proof of address must be issued within the last 90 days. #### PROOF\_OF\_ADDRESS If the KYC documents submitted does not contains the address then you much submit a valid proof of address. Acceptable proof of address are: - Utility bill. - Bank statement. - Government issued letter. - Phone bill (landline only) All Proof of Address documents must be dated within 90 days. Cropped documents are not accepted. Invoices are not accepted. PO BOX and CMRA addresses are not accepted. All manual KYC documents undergo fraud checks. If Nium cannot verify authenticity, an RFI may be raised. For details, see: - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [HK Onboarding](/docs/onboarding/customer-onboarding/hk-onboarding) --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/hk-onboarding/required-parameters Learn the required parameters, validation rules, and sample payloads for onboarding individual and corporate customers in the HK using the Customer Onboarding v5 request. The following details the required parameters for the Customer Onboarding v5 request, along with validation rules and sample requests. Use this request to create customers to onboard in the HK region. The endpoint accepts both individual and corporate customers. For API reference, see [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). ## Create Customer v5 POST `/api/v5/client/{clientHashId}/customers` ### Path parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------------------- | | `clientHashId` | string | Yes | Unique client identifier, generated and shared before the integration is set up. | ## Body Parameters | **Parameter** | **Type** | **Required** | **Accepted Values / Notes** | | ------------- | -------- | :----------: | --------------------------------------------------------------------- | | `type` | string | Yes | `individual` or `corporate`. | | `kycType` | string | Yes | `minimum` or `full`. Use `full` when onboarding for payouts. | | `region` | string | Yes | Use `HK`. | | `externalId` | string | Optional | Client-defined unique ID (max 36). Returned in webhooks and GET APIs. | ## Individual Customers ### Personal Information | **Field** | **Type** | **Required** | **Notes** | | ------------------- | -------- | :----------: | --------------------------------------------------------------------------------------------------- | | `firstName` | string | Yes | Max 40. | | `middleName` | string | Optional | Max 40. | | `lastName` | string | Yes | Max 40. | | `email` | string | Yes | Max 60; must match the [valid email regex](/docs/developers/nium-api#regular-expression-for-email). | | `nationality` | enum | Yes | Category: `countryName`. | | `mobile` | numeric | Yes | Without country code; max 15 digits. | | `mobileCountryCode` | numeric | Yes | Max 6 digits. | | `dateOfBirth` | date | Yes | `YYYY-MM-DD`; age ≥ 18. | ### `billingAddress` Object | **Field** | **Type** | **Required** | **Notes** | | -------------- | ----------- | :----------: | --------------------------------------------------------------------------------------------------------------- | | `addressLine1` | string | Yes | Max 100. | | `addressLine2` | string | Optional | Max 100. | | `city` | string | Yes | Max 50. | | `state` | enum/string | Conditional | category=isoState for countryCode=xx (e.g., HK, IN). If enum list is empty, pass state manually (max 50 chars). | | `postcode` | string | Yes | Max 10. | | `country` | enum | Yes | Category: `countryName`. | ### `expectedAccountUsage` Object | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `credit.topTransactionCountries` | Yes | Category: `countryName`. | | `debit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `debit.topTransactionCountries` | Yes | Destination countries for payouts. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other` is selected. Max 300 chars. | ## Corporate Customers (Full KYC) ### Business Information | **Field** | **Type** | **Required** | **Notes** | | ---------------------------- | -------- | :----------: | -------------------------------------------------------------------- | | `businessType` | enum | Yes | Category: `businessType`. | | `businessName` | string | Yes | Max 80. | | `tradeName` | string | Yes | If not available, set equal to `businessName`. | | `businessRegistrationNumber` | string | Yes | Max 30. | | `registeredDate` | date | Yes | `YYYY-MM-DD`; past date. | | `registeredCountry` | enum | Yes | Category: `countryName`. | | `website` | string | Optional | website or verified social profile; else upload `PROOF_OF_BUSINESS`. | | `isMultiLayeredCompany` | boolean | Yes | `true`/`false`. If `true` upload `CORPORATE_STRUCTURE` | ### `addresses` Object | **Field** | **Type** | **Required** | **Notes** | | ------------------------------------------ | ----------- | :----------: | --------------------------------------------------------------------------------------------------------------- | | `registeredAddress.addressLine1` | string | Yes | Max 100. | | `registeredAddress.addressLine2` | string | Optional | Max 100. | | `registeredAddress.city` | string | Yes | Max 50. | | `registeredAddress.state` | enum/string | Conditional | category=isoState for countryCode=xx (e.g., US, CA). If enum list is empty, pass state manually (max 50 chars). | | `registeredAddress.postcode` | string | Yes | Max 10. | | `registeredAddress.country` | enum | Yes | Category: `countryName`. | | `isBusinessAddressSameAsRegisteredAddress` | boolean | Yes | If `false`, provide businessAddress details | ### `documents` (array of object) Provide business documents | **Field** | **Type** | **Required** | **Notes** | | --------- | -------- | :----------: | -------------------------------------------------------------------------------------------------------------------------- | | `type` | enum | Yes | category: `documentType` Check [Required Documents](/docs/onboarding/customer-onboarding/hk-onboarding/required-documents) | | `fileIds` | uuid | Yes | Received from the response of Upload file API | ### `applicant` object | **Field** | **Type** | **Required** | **Notes** | | ------------------- | --------------- | :----------: | ------------------------------------------------------------ | | `externalId` | string | Optional | referenceId to identify the applicant. | | `firstName` | string | Yes | Max 40 each. | | `lastName` | string | Yes | Max 40 each. | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Yes | Max 60; valid email. | | `mobile` | numeric | Yes | 15 digit limits. | | `mobileCountryCode` | numeric | Yes | 1–3 digits | | `nationality` | string | Yes | Max 2 char. | | `sharePercentage` | numeric | Optional | Required only if position title is `UBO`/`SHAREHOLDER`. | | `positions.title` | array of object | Yes | Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable. | | `documents` | array of object | Conditional | `LOA` required if applicant is not a UBO/ DIRECTOR/ PARTNER. | | `address` | object | Yes | address of the applicant | ### Stakeholders Stakeholders can be **individuals** or **corporates** with position such as **UBO**, **Director**, **Partner**, \* *Trustee*\*, **Shareholder**. ### `stakeholders.individual` object | **Field** | **Type** | **Required** | **Notes** | | ------------------- | --------------- | :----------: | ---------------------------------------------------------- | | `externalId` | string | Optional | referenceId to identify the applicant. | | `firstName` | string | Yes | Max 40 each. | | `lastName` | string | Yes | Max 40 each. | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Optional | Max 60; valid email. | | `mobile` | numeric | Optional | 15 digit limits. | | `mobileCountryCode` | numeric | Optional | 1–3 digits | | `nationality` | string | Yes | Max 2 char. | | `sharePercentage` | numeric | Optional | Required only if position title is `UBO`/`SHAREHOLDER`. | | `positions.title` | array of object | Yes | Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable. | | `address` | object | Yes | address of the applicant | ### `stakeholders.corporate` object | **Field** | **Required** | **Notes** | | ---------------------------- | :----------: | --------------------------------------------- | | `externalId` | Optional | unique Id | | `businessName` | Yes | Registered name. | | `businessRegistrationNumber` | Yes | Max 30. | | `registeredCountry` | Yes | Category: `countryName`. | | `positions.title` | Yes | For example, `UBO`, `Shareholder`, `Trustee`. | | `sharePercentage` | Conditional | Required for UBO/Shareholder/Partner. | ### `natureOfBusiness` object | **Field** | **Required** | **Notes** | | --------------------- | :----------: | ------------------------------------------------------------------------------------------------------- | | `operatingCountries` | Yes | category:`countryOfOperation` All countries where the business operates. | | `industryCodes` | Yes | Category: `industrySector`. Industry sectors that the corporate customer operates in. Multiple allowed. | | `industryDescription` | Conditional | 2–3 sentences if “Other” is selected in industryCodes | > See [Prohibited Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories). ### `expectedAccountUsage` object | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Estimated total payins (HKD). | | `credit.monthlyTransactions` | Yes | Estimated count of monthly payins. | | `credit.averageTransactionValue` | Yes | Average payin value (HKD). | | `credit.topTransactionCountries` | Yes | Origin countries. | | `debit.monthlyTransactionVolume` | Yes | Estimated total payouts (CAD). | | `debit.monthlyTransactions` | Yes | Estimated count of monthly payouts. | | `debit.averageTransactionValue` | Yes | Average payout value (CAD). | | `debit.topTransactionCountries` | Yes | Destination countries. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other`. | ### `sizeOfBusiness` object | **Field** | **Required** | **Notes** | | ---------------- | :----------: | ------------------------------------------------------------------------------------------- | | `totalEmployees` | Yes | Category: `totalEmployees`. | | `annualTurnover` | Yes | Category: `annualTurnover`. If business is less than 1 year old, provide expected turnover. | ## `bankAccountDetails` object (for refunds/returns- applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | -------------------- | -------- | :----------: | ------------------------------------- | | `accountName` | string | Yes | Registered bank name; max 140. | | `accountNumber` | string | Yes | Max 35. | | `bankCountry` | string | Yes | ISO 3166-1 alpha-2. | | `bankName` | string | Yes | Max 255. | | `currency` | string | Yes | ISO 4217 (for example, `USD`, `HKD`). | | `routingCodes.type` | string | Yes | Pass `SWIFT` etc. | | `routingCodes.value` | string | Yes | Matches the selected type. | | `bankCode` | string | Optional | Bank code | ## `applicantDeclaration` (applicable for individual and corporate) | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ---------------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of the declaration. | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | ## `devicedetails` object (applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | --------------- | -------- | :----------: | ----------------------------------------------------- | | `ipCountryCode` | enum | Yes | Country of origin of the IP; category: `countryName`. | | `deviceInfo` | string | Yes | OS of the device initiating the request. | | `ipAddress` | string | Yes | Valid IPv4 address. | | `sessionId` | string | Yes | Session identifier for the request. | ## `tags` object (applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | ------------ | -------- | :----------: | ---------------------------------------- | | `tags` | object | Optional | Up to 15 client-defined key/value pairs. | | `tags.key` | string | Optional | Max 128; keys must be unique. | | `tags.value` | string | Optional | Max 255. | ## Examples ### Individual customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "HK", "externalId": "Jek2Vm6cw96xUA6GniQxKSd52VoaAXoBpp", "firstName": "Nium", "lastName": "HK Test", "email": "pasumarthi.sashank+2118@nium.com", "nationality": "HK", "mobile": "2000002105", "mobileCountryCode": "1", "dateOfBirth": "2008-02-25", "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "applicantDeclaration": "true", "deviceDetails": { "ipCountryCode": "hk", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "credit": { "monthlyTransactionVolume": "MVHK01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "debit": { "monthlyTransactionVolume": "MVHK01", "topTransactionCountries": [ "Gb", "GB", "GB", "IN", "US" ] }, "intendedUses": [ "Iu108", "IU107" ], "intendedUsesDescription": "test intendedintendedtest" }, "bankAccountDetails": { "accountName": "Greenholt West Inc Corporate Account", "bankName": "HSBC", "accountNumber": "802731561", "currency": "HKD", "bankAccountType": "saving", "bankCountry": "HK", "bankCode": "004", "routingCodes": [ { "type": "SWIFT", "value": "HSBCHKHHHKH" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1Test Add 123", "addressLine2": "Building 1Taa", "city": "Test Add 123, Building 1, Block 2, Area 3Test Add1", "state": "CA-ab", "postcode": "K1A 0B1", "country": "CA" } } ``` ### Corporate customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "HK", "externalId": "eaaac4cd-5730-4dba-8d67-e9242025b", "businessName": "Greenholt West Inc", "website": "https://monserrat.biz", "businessDescription": "Technology solutions and consulting services provider", "businessRegistrationNumber": "4567895", "registeredDate": "2015-03-15", "registeredCountry": "HK", "isMultiLayeredCompany": false, "businessType": "private_company", "tradeName": "Greenholt - West Inc", "bankAccountDetails": { "accountName": "Greenholt West Inc Corporate Account", "bankName": "HSBC", "accountNumber": "802731561", "currency": "HKD", "bankAccountType": "saving", "bankCountry": "HK", "bankCode": "004", "routingCodes": [ { "type": "SWIFT", "value": "HSBCHKHHHKH" } ] }, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-15 10:30:00", "addresses": { "isBusinessAddressSameAsRegisteredAddress": false, "registeredAddress": { "addressLine1": "1234 Corporate Blvd Suite 100", "addressLine2": "Building A", "city": "Newark", "state": "US-DE", "postcode": "19801", "country": "US" }, "businessAddress": { "addressLine1": "5678 Business Park Drive", "addressLine2": "Floor 5", "city": "Newark", "state": "US-CA", "postcode": "07102", "country": "US" } }, "applicant": { "externalId": "95d4c75b-089b-4aad-a9ab-f3b2360aa171", "firstName": "Tierra", "middleName": "James", "lastName": "White", "dateOfBirth": "1985-06-20", "nationality": "US", "email": "test@company.com", "mobile": "197894", "mobileCountryCode": "1", "sharePercentage": 45, "address": { "addressLine1": "789 Executive Lane", "addressLine2": "Apt 12B", "city": "Boston", "state": "US-DE", "postcode": "02101", "country": "US" }, "documents": [ { "type": "loa", "fileIds": [ "a9f55262-77ea-44a0-a5b8-b01bca79cc84" ] } ], "positions": [ { "title": "SIGNATORY", "startDate": "2015-03-15" } ] }, "stakeholders": { "individual": [ { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16805", "firstName": "Stake1", "middleName": "Robert", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "HK", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": 30, "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "state": "US-NY", "postcode": "10001", "country": "US" }, "positions": [ { "title": "UBO", "startDate": "2016-01-20" } ] } ], "corporate": [ { "externalId": "859ac163-08f0-4152-b26a-e96fce664372", "businessName": "Investment Holdings LLC", "businessRegistrationNumber": "123456789", "registeredCountry": "US", "sharePercentage": 25, "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "US", "CA", "GB" ], "industryCodes": [ "IS134" ], "industryDescription": "Comprehensive technology consulting and software development services specializing in enterprise solutions, cloud infrastructure, and digital transformation initiatives for Fortune 500 companies across North America and Europe" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "Business operations including vendor payments, payroll processing, and international transactions", "credit": { "monthlyTransactionVolume": "MVHK01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVHK01", "topTransactionCountries": [ "US", "CA", "GB" ] }, "debit": { "monthlyTransactionVolume": "MVHK01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVHK01", "topTransactionCountries": [ "US", "CA", "MX" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "HK008" }, "deviceDetails": { "ipCountryCode": "hk", "deviceInfo": "Mozilla/5.0 Windows", "ipAddress": "192.168.1.100", "sessionId": "15aaa7ad-7625-4047-a2ce-6fe4ac476728" }, "tags": [ { "key": "customer_type", "value": "enterprise" }, { "key": "priority", "value": "high" } ], "documents": [ { "type": "business_registration_doc", "fileIds": [ "3bb4595c-2d1b-47b3-a951-08175b9013c2" ] }, { "type": "nar1", "fileIds": [ "3bb4595c-2d1b-47b3-a951-08175b9013c2" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). See **Position Mapping** for the stakeholders required per business type. --- # JP Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/jp-onboarding Learn how to onboard businesses and individuals in the Japan using Customer Onboarding v5. JP onboarding includes: - Manual business verification - Electronic and manual identity verification (KYC) - Beneficial ownership disclosure (≥ 25%) - Compliance review before activation [//]: # "For more information about onboarding, see [Customer Onboarding](/docs/onboarding/customer)." ## Onboarding Flow Nium offers only Manual KYB flows for customers in Japan. Submission of business documents may be required depending on the business type. Check [JP Required Documents](/docs/onboarding/customer-onboarding/jp-onboarding/required-documents). ### Step 1: Upload required documents Use the [Files API](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload required business documents. The response returns a `fileId`. You must reference this `fileId` when submitting the onboarding request. For the full list of required documents, see [JP Required Documents](/docs/onboarding/customer-onboarding/jp-onboarding/required-documents). ### Step 2: Applicant declaration The authorized representative must confirm the following statement: > I certify that I am the authorized representative of the customer; all information provided and documents submitted > are complete and correct. I confirm that I have provided all the UBOs present. I have read and accepted > the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture this confirmation using a clickwrap and submit the following fields in your onboarding request: | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ---------------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of the declaration. | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | ### Step 3: Submit customer details Use the [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request and include: - customer details - Customer Registered address - Stakeholder & applicant details (applicable for corporate customer) - Uploaded `fileId` references - Applicant declaration fields - Bank Account Details After submission, the applicant proceeds for KYC Verification. | status | substatus | | --------- | -------------- | | `pending` | `awaiting_kyc` | ### Step 4: Complete Identity Verification (KYC) The applicant opens the Nium’s Pre-built KYC form. Access is protected by a One-Time Password (OTP) sent to the registered email address of the applicant. JP onboarding supports only manual identity verification for applicant or stakeholders. See [JP Required Documents](/docs/onboarding/customer-onboarding/jp-onboarding/required-documents) for more information on POI/ POA documents for identity verification ### Step 5: Compliance review After KYC is completed for the applicant | status | substatus | | --------- | -------------- | | `pending` | `under_review` | Nium’s compliance team reviews submitted information offline. If additional details are required: - An RFI (Request for Information) is raised - The customer responds through the RFI Hosted Form Nium returns the final outcome via webhook. For next steps based on application status, see [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle). ### Multi-layer ownership If another corporate entity owns more than 25% (directly or indirectly): - Declare all corporate stakeholders in the ownership chain. - Submit ownership structure documentation. See [JP Required Documents](/docs/onboarding/customer-onboarding/jp-onboarding/required-documents) for more information. ## Position mapping A `Yes` value indicates that the position can be submitted for that `businessType`.\ A blank cell means the position is not applicable. You can also retrieve valid positions dynamically using [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category = position`. | `businessType` | `DIRECTOR` | `SHAREHOLDER` | `SIGNATORY` | `UBO` | | :------------------------ | :--------- | :------------ | :---------- | :---- | | `PRIVATE_LIMITED_COMPANY` | Yes | Yes | Yes | Yes | | `PUBLIC_COMPANY` | Yes | Yes | Yes | Yes | ## Adding Positions - **Directors:** Add all management directors as stakeholders. - **UBOs:** Tag anyone owning ≥ 25% (direct or indirect). If none, the most senior director becomes the UBO. - **Representatives/Signatories:** Add individuals authorized to transact or manage users (applicant is a Representative by default). - **Multi-layered companies:** Include all corporate stakeholders with ≥ 25% ownership and upload a **Corporate Structure** document (`documentType: CORPORATE_STRUCTURE`). ## Related resources - [JP Required Documents](/docs/onboarding/customer-onboarding/jp-onboarding/required-documents) - [JP Required Parameters](/docs/onboarding/customer-onboarding/jp-onboarding/required-parameters) - [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/jp-onboarding/required-documents Learn which documents are required to onboard businesses and individuals registered in the Japan. ## Corporate customers The following documents are required for business verification, based on the business entity type. | `businessType` | Manual KYB | | :-------------------------------------------- | :---------------------------------------------------------------------------------------- | | `PRIVATE_COMPANY` | A copy of the corporate registry (登記事項証明書, Tokijiko Shomeisho) is required. This document | | must be issued within 6 months of submission. | | | `PUBLIC_COMPANY` | A copy of the corporate registry (登記事項証明書, Tokijiko Shomeisho) is required. This document | | must be issued within 6 months of submission. | | | | | For a complete list of business document types, see the values obtained from [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category) API with `category` as `documentType`. ### Additional business documents Submit the following documents when applicable: #### PROOF\_OF\_BUSINESS Submit this document if no website is provided. It helps Nium verify the customer’s business activity. Accepted documents include: - Product catalog, brochure, marketing material, or business plan (preferred). - Contract, business agreement, or vendor agreement. - Photo of a physical store. - Invoice describing business operations, issued within the last year (not preferred). #### CORPORATE\_STRUCTURE (Ownership Chart) Submit this document if the company has multiple ownership layers. It should include the names and share percentages of all shareholders to help identify the ultimate beneficial owner (UBO). Ownership Chart #### LOA (Letter of Authorization) Provide LOA, if the applicant's position is not director/ubo/partner. ### Identity Verification documents Individual customers, applicants, and individual stakeholders can verify their identity by uploading documents in the Pre-built KYC form. - Submit valid Passport or National ID or Driving License. Please note, - Copy of a copy is not accepted - Document should be with valid expiry date, good quality, all four corners must be visible - If the proof-of-identity document does not contain an address, also provide a separate `PROOF_OF_ADDRESS` document. Proof of address must be issued within the last 60 days. #### PROOF\_OF\_ADDRESS If the KYC documents submitted does not contains the address then you much submit a valid proof of address. Acceptable proof of address are: - Utility bill. - Bank statement. - Government issued letter. - Phone bill (landline only) All Proof of Address documents must be dated within 60 days. All KYC documents undergo fraud checks. If Nium cannot verify authenticity, an RFI may be raised. For details, see: - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [JP Onboarding](/docs/onboarding/customer-onboarding/jp-onboarding) --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/jp-onboarding/required-parameters Learn the required parameters, validation rules, and sample payloads for onboarding individual and corporate customers in the HK using the Customer Onboarding v5 request. The following details the required parameters for the Customer Onboarding v5 request, along with validation rules and sample requests. Use this request to create customers to onboard in the JP region. The endpoint accepts both individual and corporate customers. For API reference, see [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). ## Create Customer v5 POST `/api/v5/client/{clientHashId}/customers` ### Path parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------------------- | | `clientHashId` | string | Yes | Unique client identifier, generated and shared before the integration is set up. | ## Body Parameters | **Parameter** | **Type** | **Required** | **Accepted Values / Notes** | | ------------- | -------- | :----------: | --------------------------------------------------------------------- | | `type` | string | Yes | `individual` or `corporate`. | | `kycType` | string | Yes | `minimum` or `full`. Use `full` when onboarding for payouts. | | `region` | string | Yes | Use `JP`. | | `externalId` | string | Optional | Client-defined unique ID (max 36). Returned in webhooks and GET APIs. | ## Individual Customers ### Personal Information | **Field** | **Type** | **Required** | **Notes** | | ------------------- | -------- | :----------: | --------------------------------------------------------------------------------------------------- | | `firstName` | string | Yes | Max 40. | | `middleName` | string | Optional | Max 40. | | `lastName` | string | Yes | Max 40. | | `firstName_local` | string | Yes | Max 40. Name in Katakana | | `lastName_local` | string | Yes | Max 40. Name in Katakana | | `email` | string | Yes | Max 60; must match the [valid email regex](/docs/developers/nium-api#regular-expression-for-email). | | `nationality` | enum | Yes | Category: `countryName`. | | `occupation` | enum | Yes | category=occupation | | `mobile` | numeric | Yes | Without country code; max 15 digits. | | `mobileCountryCode` | numeric | Yes | Max 6 digits. | | `dateOfBirth` | date | Yes | `YYYY-MM-DD`; age ≥ 18. | ### `billingAddress` Object | **Field** | **Type** | **Required** | **Notes** | | -------------- | ----------- | :----------: | --------------------------------------------------------------------------------------------------------------- | | `addressLine1` | string | Yes | Max 100. | | `addressLine2` | string | Optional | Max 100. | | `city` | string | Yes | Max 50. | | `state` | enum/string | Conditional | category=isoState for countryCode=xx (e.g., JP, IN). If enum list is empty, pass state manually (max 50 chars). | | `postcode` | string | Yes | Max 10. | | `country` | enum | Yes | Category: `countryName`. | ### `expectedAccountUsage` Object | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `credit.topTransactionCountries` | Yes | Category: `countryName`. | | `debit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `debit.topTransactionCountries` | Yes | Destination countries for payouts. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other` is selected. Max 300 chars. | ## Corporate Customers (Full KYC) ### Business Information | **Field** | **Type** | **Required** | **Notes** | | ---------------------------- | -------- | :----------: | -------------------------------------------------------------------- | | `businessType` | enum | Yes | Category: `businessType`. | | `businessName` | string | Yes | Max 80. | | `businessName_local` | string | Yes | Max 80. Business name in Katakana | | `tradeName` | string | Yes | If not available, set equal to `businessName`. | | `businessRegistrationNumber` | string | Yes | Max 30. | | `registeredDate` | date | Yes | `YYYY-MM-DD`; past date. | | `registeredCountry` | enum | Yes | Category: `countryName`. | | `website` | string | Optional | website or verified social profile; else upload `PROOF_OF_BUSINESS`. | | `isMultiLayeredCompany` | boolean | Yes | `true`/`false`. If `true` upload `CORPORATE_STRUCTURE` | ### `addresses` Object | **Field** | **Type** | **Required** | **Notes** | | ------------------------------------------ | ----------- | :----------: | --------------------------------------------------------------------------------------------------------------- | | `registeredAddress.addressLine1` | string | Yes | Max 100. | | `registeredAddress.addressLine2` | string | Optional | Max 100. | | `registeredAddress.city` | string | Yes | Max 50. | | `registeredAddress.state` | enum/string | Conditional | category=isoState for countryCode=xx (e.g., US, CA). If enum list is empty, pass state manually (max 50 chars). | | `registeredAddress.postcode` | string | Yes | Max 10. | | `registeredAddress.country` | enum | Yes | Category: `countryName`. | | `isBusinessAddressSameAsRegisteredAddress` | boolean | Yes | If `false`, provide businessAddress details | ### `documents` (array of object) Provide business documents | **Field** | **Type** | **Required** | **Notes** | | --------- | -------- | :----------: | -------------------------------------------------------------------------------------------------------------------------- | | `type` | enum | Yes | category: `documentType` Check [Required Documents](/docs/onboarding/customer-onboarding/jp-onboarding/required-documents) | | `fileIds` | uuid | Yes | Received from the response of Upload file API | ### `applicant` object | **Field** | **Type** | **Required** | **Notes** | | ------------------- | --------------- | :----------: | ------------------------------------------------------------ | | `externalId` | string | Optional | referenceId to identify the applicant. | | `firstName` | string | Yes | Max 40 each. | | `lastName` | string | Yes | Max 40 each. | | `firstName_local` | string | Yes | Max 40. Name in Katakana. Required if JP nationals | | `lastName_local` | string | Yes | Max 40. Name in Katakana. Required if JP nationals | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Yes | Max 60; valid email. | | `mobile` | numeric | Yes | 15 digit limits. | | `mobileCountryCode` | numeric | Yes | 1–3 digits | | `nationality` | string | Yes | Max 2 char. | | `occupation` | enum | Optional | category=occupation | | `sharePercentage` | numeric | Optional | Required only if position title is `UBO`/`SHAREHOLDER`. | | `positions.title` | array of object | Yes | category: `position` | | `documents` | array of object | Conditional | `LOA` required if applicant is not a UBO/ DIRECTOR/ PARTNER. | | `address` | object | Yes | address of the applicant | ### Stakeholders Stakeholders can be **individuals** or **corporates** with position such as **UBO**, **Director**, **Partner**, \* *Trustee*\*, **Shareholder**. ### `stakeholders.individual` object | **Field** | **Type** | **Required** | **Notes** | | ------------------- | --------------- | :----------: | ----------------------------------------------------------------- | | `externalId` | string | Optional | referenceId to identify the applicant. | | `firstName` | string | Yes | Max 40 each. | | `lastName` | string | Yes | Max 40 each. | | `firstName_local` | string | Optional | Max 40. Name in Katakana. Required if JP nationals | | `lastName_local` | string | Optional | Max 40. Name in Katakana. Required if JP nationals | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Optional | Max 60; valid email. | | `mobile` | numeric | Optional | 15 digit limits. | | `mobileCountryCode` | numeric | Optional | 1–3 digits | | `occupation` | enum | Optional | Required if position title is `UBO`/`SIGNATORY`/ `REPRESENTATIVE` | | `nationality` | string | Yes | Max 2 char. | | `sharePercentage` | numeric | Optional | Required only if position title is `UBO`/`SHAREHOLDER`. | | `positions.title` | array of object | Yes | category: `position`. Include `DIRECTOR`, `UBO` as applicable. | | `address` | object | Yes | address of the applicant | ### `stakeholders.corporate` object | **Field** | **Required** | **Notes** | | ---------------------------- | :----------: | ------------------------------------- | | `externalId` | Optional | unique Id | | `businessName` | Yes | Registered name. | | `businessRegistrationNumber` | Yes | Max 30. | | `registeredCountry` | Yes | Category: `countryName`. | | `positions.title` | Yes | category: `position` | | `sharePercentage` | Conditional | Required for UBO/Shareholder/Partner. | ### `natureOfBusiness` object | **Field** | **Required** | **Notes** | | --------------------- | :----------: | ------------------------------------------------------------------------------------------------------- | | `operatingCountries` | Yes | category:`countryOfOperation` All countries where the business operates. | | `industryCodes` | Yes | Category: `industrySector`. Industry sectors that the corporate customer operates in. Multiple allowed. | | `industryDescription` | Conditional | 2–3 sentences if “Other” is selected in industryCodes | > See [Prohibited Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories). ### `expectedAccountUsage` object | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Estimated total payins (JPY). | | `credit.monthlyTransactions` | Yes | Estimated count of monthly payins. | | `credit.averageTransactionValue` | Yes | Average payin value (JPY). | | `credit.topTransactionCountries` | Yes | Origin countries. | | `debit.monthlyTransactionVolume` | Yes | Estimated total payouts (JPY). | | `debit.monthlyTransactions` | Yes | Estimated count of monthly payouts. | | `debit.averageTransactionValue` | Yes | Average payout value (JPY). | | `debit.topTransactionCountries` | Yes | Destination countries. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other`. | ### `sizeOfBusiness` object | **Field** | **Required** | **Notes** | | ---------------- | :----------: | ------------------------------------------------------------------------------------------- | | `totalEmployees` | Yes | Category: `totalEmployees`. | | `annualTurnover` | Yes | Category: `annualTurnover`. If business is less than 1 year old, provide expected turnover. | ## `bankAccountDetails` object (for refunds/returns- applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | -------------------- | -------- | :----------: | --------------------------------------------- | | `accountName` | string | Yes | Registered bank name; max 140. | | `accountNumber` | string | Yes | Max 35. | | `bankCountry` | string | Yes | ISO 3166-1 alpha-2. | | `bankName` | string | Yes | Max 255. | | `currency` | string | Yes | ISO 4217 (for example, `USD`, `JPY`). | | `routingCodes.type` | string | Yes | Pass `SWIFT`and `BRANCH CODE` for JPY Account | | `routingCodes.value` | string | Yes | Matches the selected type. | | `bankCode` | string | Optional | Provide Bank Code. Required for JPY account | ## `applicantDeclaration` (applicable for individual and corporate) | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ---------------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of the declaration. | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | ## `devicedetails` object (applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | --------------- | -------- | :----------: | ----------------------------------------------------- | | `ipCountryCode` | enum | Yes | Country of origin of the IP; category: `countryName`. | | `deviceInfo` | string | Yes | OS of the device initiating the request. | | `ipAddress` | string | Yes | Valid IPv4 address. | | `sessionId` | string | Yes | Session identifier for the request. | ## `tags` object (applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | ------------ | -------- | :----------: | ---------------------------------------- | | `tags` | object | Optional | Up to 15 client-defined key/value pairs. | | `tags.key` | string | Optional | Max 128; keys must be unique. | | `tags.value` | string | Optional | Max 255. | ## Examples ### Individual customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "JP", "externalId": "Jek2Vm6cw96xUA6GniQxKSd52VoaAXoBpp", "firstName": "Nium", "lastName": "Test", "firstName_local": "firstname local", "lastName_local": "lastName_local", "email": "pasumarthi.sashank+2118@nium.com", "nationality": "JP", "mobile": "2000002105", "mobileCountryCode": "1", "dateOfBirth": "2008-02-25", "applicantDeclarationTimeStamp": "2025-08-20 15:49:30", "applicantDeclaration": "true", "occupation": "OC0001", "deviceDetails": { "ipCountryCode": "jp", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "credit": { "monthlyTransactionVolume": "MVcA01", "topTransactionCountries": [ "GB", "GB", "GB", "IN" ] }, "debit": { "monthlyTransactionVolume": "MVcA01", "topTransactionCountries": [ "Gb", "GB", "GB", "IN", "US" ] }, "intendedUses": [ "Iu108", "IU107" ], "intendedUsesDescription": "test intendedintendedtest" }, "bankAccountDetails": { "accountName": "Individual Test", "bankName": "Japan Post Bank", "accountNumber": "8027315", "currency": "JPY", "bankAccountType": "saving", "bankCountry": "JP", "bankCode": "0004", "routingCodes": [ { "type": "SWIFT", "value": "JPPSJPJKXXX" }, { "type": "BRANCH CODE", "value": "897" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1Test Add 123", "addressLine2": "Building 1Taa", "city": "Test Add 123, Building 1, Block 2, Area 3Test Add1", "state": "JP-08", "postcode": "1234567", "country": "JP" } } ``` ### Corporate customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "JP", "externalId": "eaaac4cd-5730-4dba-8d67-e9242025c", "businessName": "Greenholt West Pvt", "businessName_local": "test", "website": "https://monserrat.biz", "businessDescription": "Technology solutions and consulting services provider", "businessRegistrationNumber": "1234567891224", "registeredDate": "2015-03-15", "registeredCountry": "JP", "isMultiLayeredCompany": false, "businessType": "private_company", "tradeName": "Greenholt - West Inc", "bankAccountDetails": { "accountName": "Greenholt West Inc Corporate Account", "bankName": "Japan Post Bank", "accountNumber": "8027315", "currency": "JPY", "bankAccountType": "saving", "bankCountry": "JP", "bankCode": "0004", "routingCodes": [ { "type": "SWIFT", "value": "JPPSJPJKXXX" }, { "type": "BRANCH CODE", "value": "897" } ] }, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-15 10:30:00", "addresses": { "isBusinessAddressSameAsRegisteredAddress": false, "registeredAddress": { "addressLine1": "1234 Corporate Blvd Suite 100", "addressLine2": "Building A", "city": "Ibaraki", "state": "JP-08", "postcode": "1980167", "country": "JP" }, "businessAddress": { "addressLine1": "5678 Business Park Drive", "addressLine2": "Floor 5", "city": "Kanagawa", "state": "JP-14", "postcode": "0710267", "country": "JP" } }, "applicant": { "externalId": "95d4c75b-089b-4aad-a9ab-f3b2360aa171", "firstName": "Tierra", "middleName": "James", "lastName": "White", "firstName_local": "firstname local", "lastName_local": "lastName_local", "dateOfBirth": "1985-06-20", "nationality": "JP", "email": "test@company.com", "mobile": "197894", "mobileCountryCode": "1", "sharePercentage": 45, "occupation": "OC1420", "address": { "addressLine1": "789 Executive Lane", "addressLine2": "Apt 12B", "city": "Boston", "state": "US-DE", "postcode": "02101", "country": "US" }, "documents": [ { "type": "loa", "fileIds": [ "a9f55262-77ea-44a0-a5b8-b01bca79cc84" ] } ], "positions": [ { "title": "SIGNATORY", "startDate": "2015-03-15" } ] }, "stakeholders": { "individual": [ { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16805", "firstName": "Stake1", "middleName": "Robert", "lastName": "Volkman", "firstName_local": "firstname local", "lastName_local": "lastName_local", "dateOfBirth": "1980-11-10", "nationality": "JP", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": 30, "occupation": "OC1420", "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "state": "US-NY", "postcode": "10001", "country": "US" }, "positions": [ { "title": "UBO", "startDate": "2016-01-20" } ] } ], "corporate": [ { "externalId": "859ac163-08f0-4152-b26a-e96fce664372", "businessName": "Investment Holdings LLC", "businessRegistrationNumber": "123456789", "registeredCountry": "US", "sharePercentage": 25, "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "US", "CA", "GB" ], "industryCodes": [ "IS134" ], "industryDescription": "Comprehensive technology consulting and software development services specializing in enterprise solutions, cloud infrastructure, and digital transformation initiatives for Fortune 500 companies across North America and Europe" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "Business operations including vendor payments, payroll processing, and international transactions", "credit": { "monthlyTransactionVolume": "MVJP01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVJP01", "topTransactionCountries": [ "US", "CA", "GB" ] }, "debit": { "monthlyTransactionVolume": "MVJP01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVJP01", "topTransactionCountries": [ "US", "CA", "MX" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "JP008" }, "deviceDetails": { "ipCountryCode": "jp", "deviceInfo": "Mozilla/5.0 Windows", "ipAddress": "192.168.1.100", "sessionId": "15aaa7ad-7625-4047-a2ce-6fe4ac476728" }, "tags": [ { "key": "customer_type", "value": "enterprise" }, { "key": "priority", "value": "high" } ], "documents": [ { "type": "business_registration_doc", "fileIds": [ "3bb4595c-2d1b-47b3-a951-08175b9013c2" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). --- # NL Onboarding URL: https://docs.nium.com/docs/onboarding/customer-onboarding/nl-onboarding NL onboarding is governed by Anti-Money Laundering (AML) directives and local regulatory requirements across EU member states. These regulations require: - Verification of business existence - Identification of Ultimate Beneficial Owners (UBOs ≥ 25%) - Identification of authorized representatives - Identity verification of applicants and required stakeholders As a result: - Registry lookup may be used for corporate verification - Document submission may be required - Compliance approval may be required before activation. Manual review may occur when: - Registry lookup fails - Electronic verification fails - Required stakeholder roles are missing - Ownership structures are complex - Documentation is incomplete or inconsistent ## Responsibility ### Client responsibilities The client's onboarding responsibilities include: - Collect accurate business and stakeholder information - Declare all required stakeholder roles - Declare UBOs (≥ 25% ownership) - Capture applicant attestation - Upload required documents - Ensure stakeholders complete identity verification ### Nium responsibilities Nium's onboarding responsibilities include: - Retrieve registry information (when eKYB is used) - Validate identity and document submissions - Conduct compliance checks - Raise RFIs (Requests for Information) if required - Approve or reject onboarding ## Onboarding Flow Nium supports both **Electronic KYB (eKYB)** and **Manual KYB** for NL region. Electronic KYB retrieves publicly available company information from EU registries. It helps to: - Pre-fills corporate data - Reduces document collection requirements - Improves customer experience - Speeds up approvals ### Step 1: Fetch public corporate details Collect: - `businessRegistrationNumber` - `countryCode` Use the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) request. Store the returned `publicDetailsId`. If no details are returned, proceed with manual KYB using [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). ### Step 2: Fetch exhaustive corporate details Use the [Fetch Exhaustive Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/exhaustiveDetailsSearch) request and include the `publicDetailsId`. Store the returned `searchId`. note: This is a chargeable API. Use it only once per customer. ### Step 3: Verify and complete corporate details - Confirm submitted data with the applicant - Verify directors and UBO information - Collect any missing required information - Add stakeholder details Stakeholders may complete verification electronically or manually. ### Step 4: Upload required documents Document upload is required when: - `searchId` is not provided - Registry data is incomplete - Additional documents are requested during review Use the [Create a File](/api#tag/files/POST/api/v1/client/{clientHashId}/files) request to upload the required documents. For more information, see [Uploading documents](/docs/onboarding/customer-onboarding#uploading-documents). The response returns a `fileId`. This `fileId` must be referenced in the onboarding request. For a complete list, see [NL Required Documents](/docs/onboarding/customer-onboarding/nl-onboarding/required-documents). ### Step 5: Applicant declaration The authorized representative must confirm: > I certify that I am an authorized representative of the customer.\ > All information and documents provided are complete and accurate.\ > I confirm that all UBOs have been disclosed and that I have accepted > the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Capture via clickwrap and submit: - `applicantDeclaration` - `applicantDeclarationTimestamp` (format: `YYYY-MM-DD HH:MM:SS`) ### Step 6: Submit onboarding request Use [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) and include: - Corporate details - Stakeholder details - `searchId` (if applicable) - Uploaded `fileId` references for documents If `searchId` is omitted, the application proceeds through manual review. Once application is submitted: | status | substatus | | --------- | -------------- | | `pending` | `awaiting_kyc` | ### Step 7: Complete Identity Verification of applicant/ stakeholders The applicant accesses Nium’s Pre-built KYC form. Access is protected by a One-Time Password (OTP) sent to the registered email address of the applicant. NL onboarding supports **Biometric KYC** for: - Individual customers - Corporate applicants - Directors - UBOs - Required stakeholders Manual document upload is also available for stakeholders when required. Available verification options: | Individual type | Biometric | Manual | | --------------------------------------- | --------------- | ------ | | Applicant (or individual customer) | Yes | No | | Stakeholder (Representative/ Signatory) | Yes | No | | Stakeholder (UBO/ Trustee/ Partner) | Yes (preferred) | Yes | See [NL Required Documents](/docs/onboarding/customer-onboarding/nl-onboarding/required-documents) for more information on POI/ POA documents ### Step 4: Compliance review After KYC completion: | status | substatus | | --------- | -------------- | | `pending` | `under_review` | Nium’s compliance team reviews submissions offline. If additional information is required: - An RFI is raised - The customer responds via the RFI Hosted Form Webhook notifications are sent for all status transitions. For next steps based on application status, see [Customer Onboarding Lifecycle](/docs/onboarding/customer-onboarding#status-lifecycle). ### Multi-layer ownership If the customer has a multi-layer ownership structure: - All corporate stakeholders owning ≥ 25% (directly or indirectly) must be declared. - Corporate structure documentation must be submitted to validate the ownership chain. For more information, see [Multi-layer ownership structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6). ## Position mapping | Business type | DIRECTOR | PARTNER | REPRESENTATIVE | SETTLOR | SHAREHOLDER | SIGNATORY | TRUSTEE | UBO | | ------------------------------- | -------- | ------- | -------------- | ------- | ----------- | --------- | ------- | --- | | ASSOCIATION | Yes | | Yes | | Yes | Yes | | | | LIMITED\_LIABILITY\_PARTNERSHIP | | Yes | Yes | | | Yes | | Yes | | GOVERNMENT\_ENTITY | | | Yes | | | Yes | | | | PRIVATE\_COMPANY | Yes | | Yes | | Yes | Yes | | Yes | | PUBLIC\_COMPANY | Yes | | Yes | | Yes | Yes | | Yes | | SOLE\_TRADER | | | Yes | | | Yes | | Yes | | TRUST | | | Yes | Yes | | Yes | Yes | Yes | A blank cell means the role is not applicable for that business type. To dynamically retrieve valid position use the [Fetch Corporate Constants](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate) request with category=`position` ## Related resources - [Pre-built KYC Form](/docs/developers/pre-built-forms/kyc-form) - [Customer Onboarding v5](/api#tag/customer-onboarding-v5) --- # Required Documents URL: https://docs.nium.com/docs/onboarding/customer-onboarding/nl-onboarding/required-documents Learn which documents are required to onboard businesses and individuals registered in the European Union (NL). ## Corporate customers Below documents required for both **manual KYB** and **electronic KYB (eKYB)**, based on the business entity type. | Business Type | Document Type (Manual KYB) | Document Type (eKYB) | | :----------------------------------------- | :--------------------------------------------------------------------------------------------- | :-------------------- | | **ASSOCIATION** | **ASSOCIATION\_DEED** | **ASSOCIATION\_DEED** | | **GOVERNMENT\_ENTITY** / **SOLE\_TRADER** | **BUSINESS\_REGISTRATION\_DOC** | N/A | | **LIMITED\_LIABILITY\_PARTNERSHIP** | **PARTNERSHIP\_DEED** | **PARTNERSHIP\_DEED** | | **PUBLIC\_COMPANY** / **PRIVATE\_COMPANY** | **BUSINESS\_REGISTRATION\_DOC** / **REGISTER\_OF\_DIRECTORS** / **REGISTER\_OF\_SHAREHOLDERS** | N/A | | **TRUST** | **TRUST\_DEED** | **TRUST\_DEED** | | | | | For a complete list of business document types, see the values obtained from [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category) API with `category` as `documentType`. ### Additional business documents Submit the following documents when applicable: #### REGISTER\_OF\_DIRECTORS and REGISTER\_OF\_SHAREHOLDERS Provide this document if the business registration document does not include a list of directors or shareholders. For faster approval, submit notarized copies. When using eKYB: - Include this document if a new director or shareholder is added who isn’t in the stakeholder list returned by the [Fetch Public Corporate Details](/api#tag/customer-onboarding-v5/GET/api/v5/client/{clientHashId}/corporate/publicDetails) endpoint. - If omitted, Nium will raise a Request for Information (RFI). #### PROOF\_OF\_BUSINESS Submit this document if no website is provided. It helps Nium verify the customer’s business activity. Accepted documents include: - Product catalog, brochure, marketing material, or business plan (preferred). - Contract, business agreement, or vendor agreement. - Photo of a physical store. - Invoice describing business operations, issued within the last year not preferred. #### CORPORATE\_STRUCTURE (Ownership Structure) Submit this document if the company has multiple ownership layers. It should include the names and share percentages of all shareholders to identify the ultimate beneficial owner (UBO). - See [Verifying Your Business in EU](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6) for an example template. - For a complete list of accepted document types, see [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category). Ownership Chart #### POWER\_OF\_ATTORNEY (Letter of Authorization) Provide POWER\_OF\_ATTORNEY, if the applicant is not a director ### Identity Verification documents Nium support Biometric and Manual KYC verification depending on the individual. Applicant to complete the KYC on Pre-build KYC form Available verification options: | Individual type | Biometric | Manual | | --------------------------------------- | --------------- | ------ | | Applicant (or individual customer) | Yes | No | | Stakeholder (Representative/ Signatory) | Yes | No | | Stakeholder (UBO/ Trustee/ Partner) | Yes (preferred) | Yes | #### Biomentric Verification Submit: - A live selfie with a **passport** (for non-EU citizens) or **passport/ national ID** (for EU citizens). #### Manual Verification Upload in Pre-built KYC form: - A color copy of a valid passport or national ID (black-and-white copies are not accepted). All manual KYC documents undergo fraud checks. If Nium cannot verify authenticity, an **RFI** will be raised. For othere references, see: - [Fetch Constants Enum](/docs/onboarding/customer-onboarding/fetch-constants-enums#fieldname-to-category) - [Verifying Your Business in the NL](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6) --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/customer-onboarding/nl-onboarding/required-parameters Learn the required parameters, validation rules, and sample payloads for onboarding individual and corporate customers in the NL using the Customer Onboarding v5 request. The following details the required parameters for the Customer Onboarding v5 request, along with validation rules and sample requests. Use this request to create customers to onboard in the NL region. The endpoint accepts both individual and corporate customers. For API reference, see [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers). ## Create Customer v5 POST `/api/v5/client/{clientHashId}/customers` ### Path parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------------------- | | `clientHashId` | string | Yes | Unique client identifier, generated and shared before the integration is set up. | ## Body Parameters | **Parameter** | **Type** | **Required** | **Accepted Values / Notes** | | ------------- | -------- | :----------: | --------------------------------------------------------------------- | | `type` | string | Yes | `individual` or `corporate`. | | `kycType` | string | Yes | `minimum` or `full`. Use `full` when onboarding for payouts. | | `region` | string | Yes | Use `CA`. | | `externalId` | string | Optional | Client-defined unique ID (max 36). Returned in webhooks and GET APIs. | ## Individual Customers ### Personal Information | **Field** | **Type** | **Required** | **Notes** | | ------------------- | -------- | :----------: | --------------------------------------------------------------------------------------------------- | | `firstName` | string | Yes | Max 40. | | `middleName` | string | Optional | Max 40. | | `lastName` | string | Yes | Max 40. | | `email` | string | Yes | Max 60; must match the [valid email regex](/docs/developers/nium-api#regular-expression-for-email). | | `nationality` | enum | Yes | Category: `countryName`. | | `mobile` | numeric | Yes | Without country code; max 15 digits. | | `mobileCountryCode` | numeric | Yes | Max 6 digits. | | `dateOfBirth` | date | Yes | `YYYY-MM-DD`; age ≥ 18. | ### `billingAddress` Object | **Field** | **Type** | **Required** | **Notes** | | -------------- | ----------- | :----------: | --------------------------------------------------------------------------------------------------------------- | | `addressLine1` | string | Yes | Max 100. | | `addressLine2` | string | Optional | Max 100. | | `city` | string | Yes | Max 50. | | `state` | enum/string | Conditional | category=isoState for countryCode=xx (e.g., US, CA). If enum list is empty, pass state manually (max 50 chars). | | `postcode` | string | Yes | Max 10. | | `country` | enum | Yes | Category: `countryName`. | ### `expectedAccountUsage` Object | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `credit.topTransactionCountries` | Yes | Category: `countryName`. | | `debit.monthlyTransactionVolume` | Yes | Category: `monthlyTransactionVolume`. | | `debit.topTransactionCountries` | Yes | Destination countries for payouts. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other` is selected. Max 300 chars. | ## Corporate Customers (Full KYC) ### Business Information | **Field** | **Type** | **Required** | **Notes** | | ---------------------------- | -------- | :----------: | -------------------------------------------------------------------- | | `businessType` | enum | Yes | Category: `businessType`. | | `businessName` | string | Yes | Max 80. | | `tradeName` | string | Yes | If not available, set equal to `businessName`. | | `businessRegistrationNumber` | string | Yes | Max 30. | | `registeredDate` | date | Yes | `YYYY-MM-DD`; past date. | | `registeredCountry` | enum | Yes | Category: `countryName`. | | `website` | string | Optional | website or verified social profile; else upload `PROOF_OF_BUSINESS`. | | `isMultiLayeredCompany` | boolean | Yes | `true`/`false`. If `true` upload `CORPORATE_STRUCTURE` | | `searchId` | string | Optional | Required for eKYB Company | ### `addresses` Object | **Field** | **Type** | **Required** | **Notes** | | ------------------------------------------ | ----------- | :----------: | --------------------------------------------------------------------------------------------------------------- | | `registeredAddress.addressLine1` | string | Yes | Max 100. | | `registeredAddress.addressLine2` | string | Optional | Max 100. | | `registeredAddress.city` | string | Yes | Max 50. | | `registeredAddress.state` | enum/string | Conditional | category=isoState for countryCode=xx (e.g., US, CA). If enum list is empty, pass state manually (max 50 chars). | | `registeredAddress.postcode` | string | Yes | Max 10. | | `registeredAddress.country` | enum | Yes | Category: `countryName`. | | `isBusinessAddressSameAsRegisteredAddress` | boolean | Yes | If `false`, provide businessAddress details | ### `documents` (array of object) Provide business documents | **Field** | **Type** | **Required** | **Notes** | | --------- | -------- | :----------: | --------------------------------------------- | | `type` | enum | Yes | category: `documentType` | | `fileIds` | uuid | Yes | Received from the response of Upload file API | ### `applicant` object | **Field** | **Type** | **Required** | **Notes** | | ------------------- | --------------- | :----------: | ----------------------------------------------------------- | | `externalId` | string | Optional | referenceId to identify the applicant. | | `firstName` | string | Yes | Max 40 each. | | `lastName` | string | Yes | Max 40 each. | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Yes | Max 60; valid email. | | `mobile` | numeric | Yes | 15 digit limits. | | `mobileCountryCode` | numeric | Yes | 1–3 digits | | `nationality` | string | Yes | Max 2 char. | | `sharePercentage` | numeric | Optional | Required only if position title is `UBO`/`SHAREHOLDER`. | | `positions.title` | array of object | Yes | Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable. | | `documents` | array of object | Conditional | `POWER_OF_ATTORNEY` required if applicant is not a DIRECTOR | | `address` | object | Yes | address of the applicant | ### Stakeholders Stakeholders can be **individuals** or **corporates** with roles such as **UBO**, **Director**, **Partner**, \*\*Trustee \*\*, **Shareholder**. **Individual Stakeholders** | **Field** | **Type** | **Required** | **Notes** | | ------------------- | --------------- | :----------: | ---------------------------------------------------------- | | `externalId` | string | Optional | referenceId to identify the applicant. | | `firstName` | string | Yes | Max 40 each. | | `lastName` | string | Yes | Max 40 each. | | `dateOfBirth` | date | Yes | Past date; age ≥ 18. | | `email` | string | Optional | Max 60; valid email. | | `mobile` | numeric | Optional | 15 digit limits. | | `mobileCountryCode` | numeric | Optional | 1–3 digits | | `nationality` | string | Yes | Max 2 char. | | `sharePercentage` | numeric | Optional | Required only if position title is `UBO`/`SHAREHOLDER`. | | `positions.title` | array of object | Yes | Include `DIRECTOR`, `REPRESENTATIVE`, `UBO` as applicable. | | `address` | object | Yes | address of the applicant | **Corporate Stakeholders** | **Field** | **Required** | **Notes** | | ---------------------------- | :----------: | ------------------------------------- | | `externalId` | Optional | unique Id | | `businessName` | Yes | Registered name. | | `businessRegistrationNumber` | Yes | Max 30. | | `registeredCountry` | Yes | Category: `countryName`. | | `positions.title` | Yes | For example, `UBO`, `Shareholder`. | | `sharePercentage` | Conditional | Required for UBO/Shareholder/Partner. | ### `natureOfBusiness` object | **Field** | **Required** | **Notes** | | --------------------- | :----------: | ------------------------------------------------------------------------------------------------------- | | `operatingCountries` | Yes | category:`countryOfOperation` All countries where the business operates. | | `industryCodes` | Yes | Category: `industrySector`. Industry sectors that the corporate customer operates in. Multiple allowed. | | `industryDescription` | Conditional | 2–3 sentences if “Other” is selected in industryCodes | > See [Prohibited Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories). ### `expectedAccountUsage` object | **Field** | **Required** | **Notes** | | --------------------------------- | :----------: | ----------------------------------- | | `credit.monthlyTransactionVolume` | Yes | Estimated total payins. | | `credit.monthlyTransactions` | Yes | Estimated count of monthly payins. | | `credit.averageTransactionValue` | Yes | Average payin value. | | `credit.topTransactionCountries` | Yes | Origin countries. | | `debit.monthlyTransactionVolume` | Yes | Estimated total payouts. | | `debit.monthlyTransactions` | Yes | Estimated count of monthly payouts. | | `debit.averageTransactionValue` | Yes | Average payout value. | | `debit.topTransactionCountries` | Yes | Destination countries. | | `intendedUses` | Yes | Category: `intendedUseOfAccount`. | | `intendedUsesDescription` | Conditional | Required if `Other`. | ### `sizeOfBusiness` object | **Field** | **Required** | **Notes** | | ---------------- | :----------: | ----------------------------------------------------------------------- | | `totalEmployees` | Yes | Category: `totalEmployees`. | | `annualTurnover` | Yes | Category: `annualTurnover`. If < 1 year old, provide expected turnover. | ## `bankAccountDetails` object (for refunds/returns- applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | -------------------- | -------- | :----------: | ------------------------------------- | | `accountName` | string | Yes | Registered bank name; max 140. | | `accountNumber` | string | Yes | Max 35. | | `bankCountry` | string | Yes | ISO 3166-1 alpha-2. | | `bankName` | string | Yes | Max 255. | | `currency` | string | Yes | ISO 4217 (for example, `USD`, `EUR`). | | `routingCodes.type` | string | Yes | For example, `SWIFT`. | | `routingCodes.value` | string | Yes | Matches the selected type. | ## `applicantDeclaration` (applicable for individual and corporate) | Field | Type | Required | Description | | ------------------------------- | --------- | -------- | ---------------------------------------- | | `applicantDeclaration` | boolean | Yes | Indicates acceptance of the declaration. | | `applicantDeclarationTimestamp` | timestamp | Yes | Format: `YYYY-MM-DD HH:MM:SS` | ## `devicedetails` object (applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | --------------- | -------- | :----------: | ----------------------------------------------------- | | `ipCountryCode` | enum | Yes | Country of origin of the IP; category: `countryName`. | | `deviceInfo` | string | Yes | OS of the device initiating the request. | | `ipAddress` | string | Yes | Valid IPv4 address. | | `sessionId` | string | Yes | Session identifier for the request. | ## `tags` object (applicable for individual and corporate) | **Field** | **Type** | **Required** | **Notes** | | ------------ | -------- | :----------: | ---------------------------------------- | | `tags` | object | Optional | Up to 15 client-defined key/value pairs. | | `tags.key` | string | Optional | Max 128; keys must be unique. | | `tags.value` | string | Optional | Max 255. | ## Examples ### Individual customer Sample Request ```json { "type": "individual", "kycType": "full", "region": "NL", "externalId": "ext-12345", "firstName": "Sharma", "middleName": "", "lastName": "Test", "email": "", "nationality": "FR", "dateOfBirth": "2000-08-01", "mobile": "98989898999", "mobileCountryCode": "31", "tags": [ { "key": "key1", "value": "value1" } ], "deviceDetails": { "ipCountryCode": "eu", "deviceInfo": "MAC", "ipAddress": "192.168.1.16", "sessionId": "hello-world" }, "expectedAccountUsage": { "intendedUsesDescription": "test intendedintended", "credit": { "monthlyTransactionVolume": "MVNL01", "topTransactionCountries": [ "GB","GB","GB","IN" ] }, "intendedUses": [ "IU104" ], "debit": { "monthlyTransactionVolume": "MVNL01", "topTransactionCountries": [ "GB","GB","GB","IN","US" ] } }, "documents": [ { "type": "trust_deed", "fileIds": [ "ad06526c-c0d1-4410-a11d-9431f28a00e2" ] } ], "bankAccountDetails": { "accountName": "Business Name", "bankName": "Bank of America", "accountNumber": "FR7630004028379876543210943", "currency": "EUR", "bankAccountType": "saving", "bankCountry": "FR", "routingCodes": [ { "type": "SWIFT", "value": "BDFEFR2TPOL" } ] }, "billingAddress": { "addressLine1": "Test Add 123, Building 1, Block 2, Area 3Test Add 123, Building 1, Block 2, Area 3Test Add 123, Buil", "addressLine2": "Test Add 123, Building 1, Block 2, Area 3Test Add 123, Building 1, Block 2, Area 3Test Add 123, Bui", "city": "Lorem ipsum dolor sit amet, consectetuer.", "state": "NL-DR", "postcode": "SW1W", "country": "NL" } } ``` ### Corporate customer Sample Request ```json { "type": "corporate", "kycType": "full", "region": "NL", "externalId": "eaaac4cd-5730-4dba-8d67-e9242025b69d", "businessName": "Sample Business Name", "website": "https://monserrat.biz", "businessDescription": "Technology solutions and consulting services provider", "businessRegistrationNumber": "BRN1234567", "registeredDate": "2015-03-15", "registeredCountry": "FR", "isMultiLayeredCompany": false, "businessType": "private_company", "tradeName": "Greenholt - West Inc", "bankAccountDetails": { "accountName": "Business Name", "bankName": "Bank of America", "accountNumber": "FR7630004028379876543210943", "currency": "EUR", "bankAccountType": "saving", "bankCountry": "FR", "routingCodes": [ { "type": "SWIFT", "value": "BDFEFR2TPOL" } ] }, "applicantDeclaration": true, "applicantDeclarationTimeStamp": "2024-01-15 10:30:00", "addresses": { "isBusinessAddressSameAsRegisteredAddress": true, "registeredAddress": { "addressLine1": "1234 Corporate Blvd Suite 100", "addressLine2": "Building A", "city": "Wilmington", "state": "FR-BFC", "postcode": "19801", "country": "FR" } }, "applicant": { "externalId": "95d4c75b-089b-4aad-a9ab-f3b2360aa171", "firstName": "Tierra", "middleName": "James", "lastName": "White", "dateOfBirth": "1985-06-20", "nationality": "FR", "email": "", "mobile": "197894", "mobileCountryCode": "1", "sharePercentage": 45, "address": { "addressLine1": "789 Executive Lane", "addressLine2": "Apt 12B", "city": "Boston", "state": "US-DE", "postcode": "02101", "country": "SG" }, "documents": [ { "type": "power_of_attorney", "fileIds": [ "a9f55262-77ea-44a0-a5b8-b01bca79cc84" ] } ], "positions": [ { "title": "REPRESENTATIVE" } ] }, "stakeholders": { "individual": [ { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16805", "firstName": "stake 5", "middleName": "Robert", "lastName": "Volkman", "isPep": false, "dateOfBirth": "1980-11-10", "nationality": "US", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": 30, "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "state": "US-NY", "postcode": "10001", "country": "US" }, "positions": [ { "title": "director" } ] }, { "externalId": "2a902305-bf54-41df-bfaa-d80c94d16802", "firstName": "stake 3+{{nameCounter}}", "middleName": "Robert", "lastName": "Volkman", "dateOfBirth": "1980-11-10", "nationality": "US", "email": "Rickie9@gmail.com", "mobile": "197786", "mobileCountryCode": "1", "sharePercentage": 30, "address": { "addressLine1": "456 Investor Street", "addressLine2": "Unit 8", "city": "New York", "state": "US-NY", "postcode": "10001", "country": "SG" }, "positions": [ { "title": "ubo" } ] } ], "corporate": [ { "externalId": "859ac163-08f0-4152-b26a-e96fce664372", "businessName": "Investment Holdings LLC", "businessRegistrationNumber": "123456789", "registeredCountry": "US", "sharePercentage": 25, "positions": [ { "title": "UBO" } ] } ] }, "natureOfBusiness": { "operatingCountries": [ "US", "CA", "GB" ], "industryCodes": [ "IS134" ], "industryDescription": "Comprehensive technology consulting and software development services specializing in enterprise solutions, cloud infrastructure, and digital transformation initiatives for Fortune 500 companies across North America and Europe" }, "expectedAccountUsage": { "intendedUses": [ "IU001" ], "intendedUsesDescription": "Business operations including vendor payments, payroll processing, and international transactions", "credit": { "monthlyTransactionVolume": "MVNL01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVNL01", "topTransactionCountries": [ "US", "CA", "GB" ], "topRemitters": [ "Enterprise Client A", "Corporate Partner B" ] }, "debit": { "monthlyTransactionVolume": "MVNL01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVNL01", "topTransactionCountries": [ "US", "CA", "MX" ], "topBeneficiaries": [ "Vendor Services Inc", "Technology Suppliers Ltd" ] } }, "sizeOfBusiness": { "totalEmployees": "EM006", "annualTurnover": "NL008" }, "deviceDetails": { "ipCountryCode": "fr", "deviceInfo": "Mozilla/5.0 Windows", "ipAddress": "192.168.1.100", "sessionId": "15aaa7ad-7625-4047-a2ce-6fe4ac476728" }, "tags": [ { "key": "customer_type", "value": "enterprise" }, { "key": "priority", "value": "high" } ], "documents": [ { "type": "business_registration_doc", "fileIds": [ "3bb4595c-2d1b-47b3-a951-08175b9013c2" ] } ] } ``` For response check [Response Codes](/docs/onboarding/customer-onboarding#response-codes). --- # Corporate Customers URL: https://docs.nium.com/docs/onboarding/corporate-customers This page describes an older version of corporate customer onboarding that is no longer supported. Visit the Customer Onboarding page for the latest v5 onboarding guide. This page describes an older version of corporate customer onboarding that is no longer supported. Visit the [Customer Onboarding](/docs/onboarding/customer-onboarding) page for the latest v5 onboarding guide. This page introduces the onboarding process and the Know Your Business (KYB) requirements for a corporate customer. The Nium One platform onboards a corporate customer through a client. It verifies their identity and assigns them a wallet that holds the balance. The term *corporate customer* includes: - Small and medium enterprise (SME) - Business - Business client ## Introduction ### Onboarding process flow After you complete your client setup you need to onboard your corporate customer. You need to submit an application through an API so Nium can complete the customer's KYB verification according to regional regulatory guidelines. Nium requires the customer to wait for the KYB process to complete before they can make transactions. Nium offers an eKYB flow to onboard a customer in most regions. The eKYB verification completes in a few minutes allowing the customer to transact quickly after submitting their application. The corporate customer onboarding process is composed of the following parts. | Corporate customer onboarding | Description | | :------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Submission of required information: Business detailsStakeholder detailsApplicant detailsDocumented proof of the above | You need to collect the following information from the corporate customer and submit it to Nium via APIs: Business name, registration number, registered addresses, etc.Stakeholder name, shareholding details, etc.Applicant name, contact details, shareholding details, etc.Corporate customer business registration documents, shareholder or applicant ID documents, etc. | | Information verification: Corporate customer KYBStakeholder or applicant verification | After the information is received, Nium starts the verification process: Nium verifies the information by eKYB or manual KYB.For details, see the [supported methods](#region-specific-kyb-and-kyc-offerings) below. | ### Definitions | Entity type | Definition | | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Applicant | An applicant is an individual who is submitting the application on behalf of the corporate customer. Usually, an applicant is an authorized representative or signatory of the corporate customer. An applicant has to undergo Know Your Customer (KYC) verification as part of the KYB process. | | Business | A business is a corporate customer that's being onboarded. | | Stakeholder | A stakeholder is an individual or entity that's declared in the registration documents of the business as an officer or shareholder. Information about all stakeholders needs to be submitted. Nium performs a KYC check on all stakeholders according to regulatory guidelines. Stakeholder can be a business or a natural person. | ### Region-specific KYB and KYC offerings For detailed onboarding steps about your region, click the *onboarding* link next to the region's name. #### Australia — [AU onboarding](/docs/onboarding/corporate-customers/au-onboarding) | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | eKYB | Real time | `E_KYC` for AU resident via database verification. `E_DOC_VERIFY` for non-AU resident via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | `E_KYC` for AU resident via database verification`MANUAL_KYC` for non-AU resident via manual submission of documents | | Manual KYB | Requires Nium compliance review and manual submission of documents | `E_KYC` for AU resident via the database verification. `E_DOC_VERIFY` for non-AU resident via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | `MANUAL_KYC` manual submission of documents, regardless of residence | #### Canada - [CA onboarding](/docs/onboarding/corporate-customers/ca-onboarding) | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :----------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- | | Manual KYB | Requires Nium compliance review and manual submission of documents | `E_KYC` for CA resident via the database verification. `E_DOC_VERIFY` for non-CA residents via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | `MANUAL_KYC` manual submission of documents, regardless of residence | #### European Union — [EU onboarding](/docs/onboarding/corporate-customers/eu-onboarding) Only customers registered in EEA are eligible to be onboarded under EU region. Please contact your account manager, in case you need to onboard customers registered outside of EEA. | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- | | eKYB | Enable the pre-population of data. Lesser time to approval. | `E_DOC_VERIFY` regardless of residence and is applicable via a live selfie photograph. | `E_DOC_VERIFY` or `MANUAL_KYC` based on the stakeholder's preference. | | Manual KYB | Requires Nium compliance review and manual submission of documents | `E_DOC_VERIFY` regardless of residence and is applicable via a live selfie photograph. | `E_DOC_VERIFY` or `MANUAL_KYC` based on the stakeholder's preference. | #### Hong Kong — [HK onboarding](/docs/onboarding/corporate-customers/hk-onboarding) | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------- | | Manual KYB | Requires Nium compliance review and manual submission of documents. | `E_DOC_VERIFY` regardless of residence and is applicable via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | `MANUAL_KYC` manual submission of documents, regardless of residence. | #### Japan — [JP onboarding](/docs/onboarding/corporate-customers/jp-onboarding) | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :------------------------------------------------------------------ | :-------------------------------------------- | :-------------------------------------------------------------------- | | Manual KYB | Requires Nium compliance review and manual submission of documents. | `MANUAL_KYC` manual submission of documents. | `MANUAL_KYC` manual submission of documents, regardless of residence. | #### New Zealand— [NZ onboarding](/docs/onboarding/corporate-customers/nz-onboarding) | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | eKYB | Real time | `E_KYC` for NZ resident via database verification. `E_DOC_VERIFY` for non-NZ resident via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | `E_KYC` for NZ resident via database verification`MANUAL_KYC` for non-NZ resident via manual submission of documents | | Manual KYB | Requires Nium compliance review and manual submission of documents. | `E_DOC_VERIFY` regardless of residence and is applicable via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | `MANUAL_KYC` manual submission of documents. | #### Singapore — [SG onboarding](/docs/onboarding/corporate-customers/sg-onboarding) | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | | eKYB | Real time | `E_KYC` for SG residents via Myinfo verification`E_DOC_VERIFY` for non-SG residents. This enum is used when verification is performed via a live selfie photograph. `MANUAL_KYC` manual submission of documents | For SG residents, `E_KYC` via Myinfo verification or `MANUAL_KYC` For non-residents `E_DOC_VERIFY` or `MANUAL_KYC` based on the stakeholder's preference. | | Manual KYB | Requires Nium compliance review and manual submission of documents | `E_KYC` for SG residents via the Myinfo verification`E_DOC_VERIFY` for non-SG residents and is applicable via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | For SG residents, `E_KYC` via Myinfo verification or `MANUAL_KYC` For non-residents `E_DOC_VERIFY` or `MANUAL_KYC` based on the stakeholder's preference. | #### United Kingdom — [UK onboarding](/docs/onboarding/corporate-customers/uk-onboarding) | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | eKYB | Real time | `E_DOC_VERIFY` regardless of residence and is applicable via a live selfie photograph. | `E_KYC` for UK residents via the database verification`E_DOC_VERIFY` or `MANUAL_KYC` based on the stakeholder's preference for non-UK residents. | | Manual KYB | Requires Nium compliance review and manual submission of documents | `E_DOC_VERIFY` regardless of residence and is applicable via a live selfie photograph. | `E_KYC` for UK residents via the database verification`E_DOC_VERIFY` or `MANUAL_KYC` based on the stakeholder's preference for non-UK residents. | #### United States — [US onboarding](/docs/onboarding/corporate-customers/us-onboarding) | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | | eKYB | Real-time | `E_KYC` for US residents via database verification. `E_DOC_VERIFY` for non-US residents and is applicable via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | `E_KYC` for US residents via the database verification. `MANUAL_KYC` for non-US resident via manual submission of documents. | | Manual KYB | Requires Nium compliance review and manual submission of documents | `E_KYC` for US residents via database verification. `E_DOC_VERIFY` for non-US residents and is applicable via a live selfie photograph. `MANUAL_KYC` manual submission of documents. | `MANUAL_KYC` manual submission of documents, regardless of residence. | #### Other Countries — [SG onboarding](/docs/onboarding/corporate-customers/sg-onboarding) Businesses which are not covered in any of the above regions can be onboarded through `SG` as the regulatory region. All the required parameters, required documents, and the onboarding flow are the same as that of `SG`. Currently, only Manual KYB is supported. | KYB offering | Business verification | Applicant verification | Stakeholder verification | | :----------- | :----------------------------------------------------------------- | :------------------------------------------------------------------ | :-------------------------------------------------------------------- | | Manual KYB | Requires Nium compliance review and manual submission of documents | `E_DOC_VERIFY` or `MANUAL_KYC` based on the applicant's preference. | `E_DOC_VERIFY` or `MANUAL_KYC` based on the stakeholder's preference. | ## Implementation You can onboard corporate customers with Nium in two ways: - **Custom API Integration**: Use Nium's Customer Account - Corporate APIs to build a tailored onboarding experience. This option is ideal for clients who want a fully customized onboarding journey. - **Onboarding Forms**: Use Nium's pre-built onboarding forms for a faster, low-effort setup. This is a good fit for clients with a smaller number of corporate customers to onboard and minimal engineering resources. For more details about our pre-built Onboarding Forms, see [Onboarding Forms](/docs/onboarding/corporate-customers/onboarding-forms). The following details how to onboard corporate customers using a custom Integration. Implementation ### Client Configuration Before you call our APIs for Onboarding, follow the steps below: 1. **IP Whitelisting**: Provide the IPs that make server calls to be whitelisted in our system. If you have IP based restriction to receive our webhooks, you can whitelist the below: *Sandbox*: 18.202.13.32 *Production*: 54.77.46.201 2. **Webhook notifications**: Provides an endpoint to receive onboarding webhooks. 3. **Webhooks**: We recommend subscribing to the following webhook onboarding updates. *CUSTOMER REGISTRATION WEBHOOK*: Sent when a customer is created and returns the **walletHashid** and **customerHashId**. *CARD CLIENT KYB STATUS WEBHOOK*: Provides status updates after a customer is successfully created. 4. **KYC redirect URL**: Provides an endpoint to receive browser redirects if you're using **E\_DOC\_VERIFY** or **E\_KYC** in **SG**. ### Choosing the regulatory region of the customer If you are client is getting onboarded in multiple regions, Nium will perform due diligence on the multiple entities of the client and generate multiple **clientHahsIds**, one for each region. Maintain the mapping of **clientHahsId** vs **region** and make sure onboarding requests for a customer are submitted only using the **clientHashId** configured for that region. Regulatory regions should be chosen based on the registered country of the customer as described in the table below. Please contact [Nium support](mailto:support@nium.com) if you have an arrangement that doesn't follow the table below. | Customer registered country | Regulatory region | | --------------------------- | ----------------------- | | AU or NZ | AU or NZ respectively | | CA, HK, JP | CA, HK, JP respectively | | GB, CH, MC | UK | | US | US | | EEA countries | EU | | SG | SG | | None of the above\* | SG | Customers with a `registeredCountry` of **China (CN)**, **India (IN)**, **Malaysia (MY)**, or **South Africa (ZA)** are not supported under Nium’s cross-border policy and cannot be onboarded under any regulatory region. Contact [Nium Support](mailto:support@nium.com) for additional guidance. ### Submitting information You need to send the required information below by one or more APIs summarized in the table. | Region | eKYB required steps | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **[AU](/docs/onboarding/corporate-customers/au-onboarding)** and **[NZ](/docs/onboarding/corporate-customers/nz-onboarding)** | 1. *(Optional)* [Public Corporate Details using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API2. [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API | | **[EU](/docs/onboarding/corporate-customers/eu-onboarding)** / **[SG](/docs/onboarding/corporate-customers/sg-onboarding)** / **[UK](/docs/onboarding/corporate-customers/uk-onboarding)** | 1. [Public Corporate Details using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API2. [Exhaustive Corporate Details using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) API3. [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API | | **[US](/docs/onboarding/corporate-customers/us-onboarding)** | [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API | For `MANUAL_KYB`, you only need to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. Before you onboard a corporate customer in a particular region, you need to create a `clientHashId` in that particular region. For more details, see [Getting Started](/docs/01-Getting%20Started/index.mdx) or contact [Nium Support](mailto:support@nium.com). ## Onboard API response You can implement the following actions based on the `status` field in the response. | HTTP code | Status | Next steps | | :---------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------ | | [200](#200) | `IN_PROGRESS` | 1. Use a redirect URL to complete KYC. 2. Upload required documents using Upload documents API. 3. Wait for the webhook response. | | [400](#400) | `BAD_REQUEST` | Correct the data and resubmit the application. | ### 200 response Once the application is submitted via the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API, a customer is created and you receive the following customer information in the response, along with any errors or remarks, to be stored for future use: - `caseId` - `clientId` - `customerHashId` - `walletHashId` The response also contains the `status` which is always `IN_PROGRESS`. One or both of the following can happen at this stage: - When a `redirectURL` is provided for applicant, it means the applicant has to be redirected to the vendor's page for completion of the applicant's KYC. If `redirectURL` is issued for a stakeholder, you are expected to distribute the URL to the stakeholder. Refer to the individual region pages for more information. Once the process is completed for the applicant and all the stakeholders, wait for webhook events to indicate the change in the corporate customers' `complianceStatus`. - Additional documents might be required, which can be submitted via the [Upload Document for Corporate Customer](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/uploadDocumentsforcorporatecustomer) API, regardless of a `redirectURL`. Refer to the individual regions for the complete list of documents required for eKYB and manual KYB flows. Also, you can make use of the `remarks` field in the response, which can be shown to the applicant, and collect documents accordingly. After either or both of the above-mentioned steps are completed as required, Nium initiates verification of the application. The application can either get verified in real time or through manual review. The status of the application changes to either `ACTION_REQUIRED`, `COMPLETED`, or `REJECT`, accordingly. Any change in status is communicated via webhook, so wait for the `webhook` event to complete. #### Response example for `IN_PROGRESS` with `redirectUrl` ```json { "clientId": "NIM1749530216XYN", "caseId": "680551ce-1189-495a-93ca-f22156ff619f", "status": "IN_PROGRESS", "remarks": "BUSINESS -> Application is being reviewed by our compliance agent", "customerHashId": "a90dc76e-4a09-4d07-ae98-aeab5c7fa1a7", "walletHashId": "7b6182fa-21a3-4dbb-b12e-adda0e66bc9c", "redirectUrl": "https://idv.preprod.nium.com/preprod/compliance/callback/load?referenceNumber=492d74c3-ebc6-4f8e-869e-be2822c4c622", "expiry": "43200", // deprecated "errors": [], "kycURLs": { "applicantKycUrl": { "redirectUrl": "https://idv.preprod.nium.com/preprod/compliance/callback/load?referenceNumber=492d74c3-ebc6-4f8e-869e-be2822c4c622", "referenceId": "49b7a26f-3f24-480e-94d9-bb24c6701ae4" }, "stakeholderKycUrls": [ { "redirectUrl": "https://idv.preprod.nium.com/preprod/compliance/callback/load?referenceNumber=2e07c4d8-241a-4282-a0a7-93ee2ecd193b&referenceId=247f2897-00ee-48f2-ad71-69be1887343b", "referenceId": "247f2897-00ee-48f2-ad71-69be1887343b", "firstName": "KATIE", "middleName": "ATIKINSON", "lastName": "RONTAK", "dateOfBirth": "1981-06-15", "nationality": "GB" } ] } } ``` - `redirectURL` and `kycURLs.applicantKycUrls.redirectUrl` are the same. Redirect URL is retained to support integrations of old clients. - `redirectURL` is returned only for those stakeholders or applicant for whom `kycMode` is submitted as `E_DOC_VERIFY`. Additionally `E_KYC` in `SG` region returns `redirectURL`. To know which regions support `E_DOC_VERIFY`, see [Region specific KYB and KYC offerings](#region-specific-kyb-and-kyc-offerings) - It is recommended to pass `referenceId` of the stakeholders in the Onboard Corporate Customer API. If not passed, you can use the name and date of birth to match with your stakeholder. - There is no expiry on the `redirectURL`. Customer can refresh the browser or click on the same link, in case the session expires. The field `expiry` provided in the response will be deprecated. - In case applicant and stakeholder are the same person (but submitted twice in the application) and both are submitted as E\_DOC\_VERIFY then only one redirectURL will be returned for the applicant, there will be no stakeholderKYCURL returned in this scenario. - See region wise guides for more tips on how to integrate the E\_DOC\_VERIFY flow. - You can also fetch the redirectURLs in customerDetails V2 and Customer List V3 APIs as shown below: ```JSON "stakeholders": [ { "referenceId": "ef08d819-1459-4058-84ab-7c8796c83cab", "redirectURL": "https://idv.preprod.nium.com/preprod/compliance/callback/load?referenceNumber=4eb841b6-7428-465a-8311-8c3dca93358a&referenceId=ef08d819-1459-4058-84ab-7c8796c83cab", "stakeholderDetails": { "firstName": "KATIE", "middleName": "ATIKINSON", "lastName": "RONTAK" } ] ``` ```JSON "applicantDetails": { "referenceId": "9f39bef4-780a-4451-ae04-02108902326b", "redirectURL": "https://idv.preprod.nium.com/preprod/compliance/callback/load?referenceNumber=71abe935-f3d9-4dc3-8ae1-ce9b2904a2fd", "firstName": "SHELDON", "middleName": "PATTERSON", "lastName": "COOPER", } ``` ### 400 response In case of any basic validation failures, Nium returns an HTTP 400 Bad Request response status code to the Onboard Corporate Customer API. You need to look at the errors field and resubmit with the correct customer details. ```JSON { "status": "BAD_REQUEST", "message": "Unable to create customer v1: Validation failed for input provided", "errors": [ "[\"The maximum length of email is 60 characters\"]" ] } ``` All corporate customers are required to have a unique business name and business registration number. Bad request example with a non-unique name: ```JSON { "status": "BAD_REQUEST", "message": "Unable to create customer v1: Corporate customer already exist with customerHashId 88464f2d-8caa-4cd4-a1db-346d9defde05", "errors": [ "[\"Corporate customer already exist with customerHashId 88464f2d-8caa-4cd4-a1db-346d9defde05\"]" ] } ``` #### `errorDetails` object In addition to the above basic errors, more detailed errors are presented in the below format with code and description. For details on the different error codes, see [Onboarding error codes](/docs/onboarding/corporate-customers/onboarding-error-codes). ```JSON { "status": "BAD_REQUEST", "code": "unable to initiate CaaS Corporate Onboarding", "message": "{\"errors\":[{\"code\":\"E100\",\"description\":\"Tax Details is Missing for Business Entity MONEYWISE PARTNERS324905\"},{\"code\":\"E100\",\"description\":\"Tax Country is Missing for Business Entity MONEYWISE PARTNERS324905\"},{\"code\":\"E100\",\"description\":\"Registered Address Line 1 is Missing for Business Entity MONEYWISE PARTNERS324905\"},{\"code\":\"E100\",\"description\":\"Address Registered Country is Missing for Business Entity MONEYWISE PARTNERS324905\"},{\"code\":\"E100\",\"description\":\"Address Post Code is Missing for Business Entity MONEYWISE PARTNERS324905\"},{\"code\":\"E200\",\"description\":\"Share percentage is Missing for Stakeholder Ultimate Beneficial Owner Mila John Jekovar\"}],\"custAdtlInfoNeeded\":false,\"statusCode\":\"400\",\"errorMessage\":\"Compliance Request Validation Failed with Errors - Tax Details is Missing , Tax Country is Missing , Tax Number is Missing , Registered Address Line 1 is Missing , Address Registered Country is Missing , Address Post Code is Missing for Business entity MONEYWISE PARTNERS324905. \\n Share percentage is Missing for stakeholder Ultimate Beneficial Owner Mila John Jekovar. \\n Please provide the required information.\",\"isCustAdtlInfoNeeded\":false}", "errorDetails": [ { "code": "E100", "description": "Tax Details is Missing for Business Entity MONEYWISE PARTNERS324905" }, { "code": "E100", "description": "Tax Country is Missing for Business Entity MONEYWISE PARTNERS324905" }, { "code": "E100", "description": "Address Registered Country is Missing for Business Entity MONEYWISE PARTNERS324905" }, { "code": "E100", "description": "Address Post Code is Missing for Business Entity MONEYWISE PARTNERS324905" }, { "code": "E200", "description": "Share percentage is Missing for Stakeholder Ultimate Beneficial Owner Mila John Jekovar" } ] } ``` ## Webhooks After receiving the response from the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API, for all cases where `status = IN_PROGRESS`, Nium sends a webhook event to the configured client URL, under Notification Webhook. You need to look for the corresponding template within the webhook event's response `CARD_CLIENT_KYB_STATUS_WEBHOOK` in the [Client-KYB Status](/docs/developers/notifications-and-webhooks/platform-events/client-kyb-status) event. To learn more about webhooks, see [Notifications and Webhooks](/docs/developers/notifications-and-webhooks). ### `complianceStatus` field In the webhook response, the `complianceStatus` field can have one of the following values. | complianceStatus | Description | | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ACTION _REQUIRED` | Wait for the next state while your compliance agent is reviewing the application. | | `COMPLETED` | This is not a terminal state. RFIs can be raised even after this state. Transactions are not allowed yet. Look at `status` field for confirmation of approval. | | `REJECT` | The corporate customer needs to resubmit the application to restart the process along with `clientId` and `customerHashId`. This is not a terminal state. | | `RFI_REQUESTED` | If the compliance agent finds insufficient information in the application, they raise a request for information (RFI) to you to collect the missing information from the corporate customer. | | `RFI_RESPONDED` | After you gather the missing information, send it via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. After the missing information is received, you receive this webhook event. Once compliance status changes to `RFI_REQUESTED`, a compliance officer will work on the application only after it reaches `RFI_RESPONDED`. The client has to make sure that all the RFIs are responded to and compliance status has reached `RFI_RESPONDED` | `complianceStatus` only details the progress of the application but doesn't confirm the approval. RFIs can be raised after any `complianceStatus` and it is advisable to keep the RFI process open in any state. #### Resubmission When `complianceStatus`=`Reject` and `status`=`Failed`, you can resubmit an application.To resubmit an application, include `customerhashid` as provided below in the Onboard Corproate Customer API. Once successful, `complianceStatus`='IN\_PROGRESS' or `ACTION_REQUIRED` or `COMPLETED`. You will receive an error if resubmission is not allowed for any reason. ```json { "region": "EU", "customerHashId":"745b3570-f6b2-46b5-9389-c7925a26139c", "businessDetails": { "businessName": "Channels BusinessName Blacklist", "businessRegistrationNumber": "3121s2aw8293", "businessType": "PRIVATE_COMPANY", "tradeName": "John Electric", "website": "www.JohnPower.com", } } ``` Resubmission is not allowed if the customer's application is rejected due to high risk or non-compliance. Please reach out to your Nium account manager or [Nium Support](mailto:support@Nium.com) for more details. When an application is rejected due to high risk or non-compliance reasons, resubmitting the application returns error **R800**. Use the R800 error to identify applications that were rejected due to non-compliance reasons and can't be resubmitted. ```json { "status": "BAD_REQUEST", "code": "unable to initiate CaaS Corporate Onboarding", "message": "{\"errors\":[{\"code\":\"R800\",\"description\":\"Application cannot be resubmit as it was rejected for high risk."}],\"isCustAdtlInfoNeeded\":false}", "errorDetails": [ { "code": "R800", "description": "Application cannot be resubmit as it was rejected for high risk." } } ``` ### `status` field This field can have the following values. | Status | Description | | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Pending` | This state indicates that the application is under review. This is not a terminal state. | | `Clear` | This is a terminal state and is the confirmation of approval. Client can communicate the approval to customers and transactions are allowed only in this state. In rare scenarios of post-approval due diligence, RFIs can be raised even after this state, which can be inferred from the change in `complianceStatus` | | `Failed` | The corporate customer needs to resubmit the application to restart the process along with `clientId` and `customerHashId`. This is a terminal state and Compliance agent might not entertain the resubmission. | The same status can also be found in Customer Details API. ## Resubmitting a customer When ## RFI process While the application status is `ACTION_REQUIRED`, the compliance agent may request additional information by raising an RFI request, which sets the `complianceStatus` as `RFI_REQUESTED` in the webhook response. Then, you need to call the [Fetch Corporate Customer RFI Details](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/rfi) API to fetch the RFI templates requested by using the `clientID` and `caseID` parameters or by using only the `customerHashId`. There can be multiple RFI templates in the response. The [Respond to RFI for Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate/rfi) API should be used to respond to all required fields for each RFI template raised. The required fields are different for each RFI template but are a subset of the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. For the complete list of RFI templates and required fields or documents by region, see the [RFI templates](/docs/onboarding/corporate-customers/requests-for-information-rfis/rfi-templates) page. After an RFI template is responded, the `status` of the template changes to `RFI_RESPONDED` in the [Fetch Corporate Customer RFI Details](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/rfi) API. Once all the RFI templates are responded, the status of the application changes from `RFI_REQUESTED` to `RFI_RESPONDED` and you will receive a webhook with `complianceStatus`=`RFI_RESPONDED` After the application, the `complianceStatus` can again become `RFI_REQUESTED` or one of the terminal states becomes `COMPLETED` or `REJECTED`. ## Terms and Conditions Terms and Conditions ## Regenerate KYC URL API \[Will be deprecated] Expiry on the E\_DOC\_VERIFY URL is removed and hence this API is redundant and will be deprecated. Clients that already integrated this API will receive a dummy expiry to support their flows. ## Update Corporate Customer API After the onboarding is complete and the customer is approved, the [Update Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate) API allows you to perform the following actions on a corporate customer: - Update business details and risk details of a corporate customer. - Add new stakeholders and update information for existing stakeholders. - Replace and update existing applicant information. - Add new documents for business details, stakeholder details, and applicant details. This API can be called only if the compliance status is `COMPLETED`; any other status results in a validation error. All the fields in the request body of the Update Corporate Customer API are the same as the Onboard Corporate customer API except `authenticationCode`. Clients of EU and UK must pass the authentication code submitted by the end customer. This is a regulatory requirement in the UK and US. Please note: - You do not need to pass the entire request body. Send only the fields that need to be updated. If any field is not passed in the request body, it will remain unchanged. - Any parameter which is an array will be entirely replaced by the input values passed in the API, such as the `tax_details` and `professionalDetails` arrays. - You can either add a new stakeholder or update and existing stakeholder. To add a new stakeholder, you needn't send a `referenceId`; or if you do, you need to send a new `referenceId`. When updating details of an existing stakeholder, you need to pass the `referenceId` of the existing stakeholder. - You can either replace the applicant or update the existing applicant. To replace the applicant, you needn't send a `referenceId`; or if you do, you need to send a new `referenceId`. When updating details of an existing applicant, you need to pass the `referenceId` of the existing applicant. - After the Update Corporate Customer API is called, the status of the application changes to `ACTION_REQUIRED` and the application goes to manual review. After Nium's compliance team completes verification, the status changes to `COMPLETED` and the data is updated in the database. RFIs may be raised by our compliance officer to complete the verification. Once the Update Corporate Customer API the `complianceStatus` changes to `ACTION_REQUIRED`, the customer `status` remains `CLEAR` which will allow the customer to transact. ## Ongoing Due Diligence (ODD) Corporate customers approved more than one year ago are subject to **Ongoing Due Diligence (ODD)**. ODD is a periodic review process that applies to active customers based on their risk profile and transaction history. During this review, a compliance officer may issue one or more [Requests for Information (RFIs)](/docs/onboarding/corporate-customers/requests-for-information). You are expected to respond promptly to any RFIs to help complete the review. Failure to respond may result in temporary account suspension. If you have any questions please contact your Nium Account Manager or [Nium Support](mailto:support@nium.com) for more information. #### Completing ODD When going through Ongoing Due Diligence (ODD): - The `status` field remains **Clear** during the Ongoing Due Diligence (ODD) process. Customers can continue to process transactions as usual. - If an RFI is raised, the `complianceStatus` will change to **RFI\_REQUESTED**, similar to the onboarding flow. It can also transition to the following states: **ACTION\_REQUIRED**, **RFI\_RESPONDED**, and **COMPLETED**. - Use the same onboarding requests from manage RFIs: - [Fetch RFI Details](/api#tag/customer-account---individual/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) - [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) - Expired documents will be requested via RFI. This may include the latest **BUSINESS\_REGISTRATION\_DOC** or other relevant documents. - If new stakeholders are identified, you may be asked to provide their details and verification documents. - You may also be asked to provide an updated ownership structure if any changes in shareholding are detected. To track changes in ODD status, subscribe to the **CUSTOMER\_ODD\_STATUS\_WEBHOOK** event. For more information, see [Customer ODD Status](/docs/developers/notifications-and-webhooks/platform-events/customer-odd-status). The `oddStatus` field in the event can return the following values: | `oddStatus` | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------ | | `odd_due` | The customer is due for Ongoing Due Diligence (ODD). A compliance officer will initiate the review shortly. | | `odd_initiated` | The ODD process has been initiated by a compliance officer. You may receive one or more Requests for Information (RFIs). | | `odd_completed` | The ODD process is complete. No further action is required until the next review is due. | ### Event example: ODD status event ```json { "clientHashId": "86ce8d7b-f3fa-46d5-8d1c-53212aade5b5", "customerHashId":"857dc08e-dffa-4e9a-ad96-79041c8a7025", "oddStatus":"odd_due", "template": "CUSTOMER_ODD_STATUS_WEBHOOK", "customerType":"corporate" } ``` ## Region `businessType` matrix | `businessType` | `AU` | `EU` | `SG` | `UK` | `US` | | :------------------------------ | :--- | :--- | :--- | :--- | :--- | | `ASSOCIATION` | Yes | Yes | Yes | Yes | No | | `CORPORATION` | No | No | No | No | Yes | | `ESTATE` | No | No | No | No | Yes | | `GENERAL_PARTNERSHIP` | No | No | No | No | Yes | | `GOVERNMENT_ENTITY` | Yes | Yes | Yes | Yes | No | | `LIMITED_LIABILITY_COMPANY` | No | No | No | No | Yes | | `LIMITED_LIABILITY_PARTNERSHIP` | No | Yes | No | Yes | Yes | | `OTHERS` | No | No | Yes | Yes | No | | `PARTNERSHIP` | Yes | No | Yes | No | No | | `PRIVATE_COMPANY` | Yes | Yes | Yes | Yes | No | | `PUBLIC_COMPANY` | Yes | Yes | Yes | Yes | Yes | | `REGULATED_TRUST` | Yes | No | No | No | No | | `SOLE_TRADER` | Yes | No | Yes | Yes | Yes | | `TRUST` | No | Yes | Yes | Yes | Yes | | `UNICORP_ASSOCIATION` | No | No | No | No | Yes | | `UNICORP_PARTNERSHIP` | No | No | No | Yes | No | | `UNREGULATED_TRUST` | Yes | No | No | No | No | --- # Onboarding Forms URL: https://docs.nium.com/docs/onboarding/corporate-customers/onboarding-forms You can onboard corporate customers with Nium in two ways, depending on your needs and resources: - **Custom API integration**: Leverage Nium's Customer Account - Corporate APIs to create a fully customized onboarding journey. This is ideal for clients needing a highly tailored experience. For more information, see [Corporate Customers](/docs/onboarding/corporate-customers#implementation). - **Onboarding forms**: Choose Nium’s pre-built onboarding forms for a faster, lower-effort setup, ideal for clients onboarding a smaller number of corporate customers with limited engineering resources. Nium's onboarding forms allow you to customize specific elements of the customer onboarding experience, including: - **Brand name**: Display your brand name at key touchpoints. - **Brand logo**: Showcase your logo on the *OTP (one-time password)* email, welcome page, and drop-off page. **Note**: Color and font customization is not available at this time. This form is helpful for clients that want: - **Faster deployment**: Nium’s pre-built forms streamline onboarding, significantly reducing the engineering effort required for custom API integrations. - **Optimized user experience**: Nium’s onboarding forms are designed with regional nuances in mind, improving the customer experience. - **Comprehensive security and compliance**: Built to comply with regional data privacy laws, Nium’s onboarding forms incorporate robust security features to meet the approval of various global compliance teams. ### Key features - **Branding**: Customize the form by adding your brand name and logo at key customer touchpoints, such as the welcome page, OTP email, and drop-off page. - **Secure URL expiration**: The form’s URL automatically expires after 24 hours, enhancing security. - **Email-based OTP authentication**: A one-time password (OTP) is emailed to applicants for identity verification. - **Data validation and pre-population**: Business registration numbers are validated, and existing customer data is pre-populated using trusted vendors. - **Save draft feature**: Users can save their progress and return later to complete the form. - **Review page**: Corporate customers can review and correct any information included in the form before submission. - **Acceptance of terms**: Includes built-in acceptance policies as well as terms and conditions. - **Inbuilt integrations**: The form supports live-document OCR, Singpass authentication, and database-based E-KYC for verifying corporate customers’ applicants and stakeholders. - **Advanced security features**: Includes session timeouts, rate limiting, data retention policies, data privacy measures, and encryption. - **Application tracking**: Clients can track the progress of an onboarding form, including completed sections, submission errors, and approval status. We're actively working on expanding the capability of Onboarding forms. Future additions include: - **Integrated RFI process**: Simplifies requests for information (RFI), removing the need for time-consuming email exchanges. - **Nium portal support**: Nium portal enables clients to create applications and regenerate onboarding form URLs, eliminating the need for a custom API integration. - **Multi-factor authentication (MFA)**: Clients can enable MFA for added security, with the option to disable it if not required. - **Enhanced customization**: Future updates will include options for color and font customizations. Alternatively, you can build a fully custom onboarding flow using a custom API integration. For more information, see [Corporate Customers](/docs/onboarding/corporate-customers#implementation). ## Supported browsers Nium's onboarding forms support the following browsers (minimum required versions): - Google Chrome version 14 and above. - Safari version 13 and above. - Microsoft Edge version 115 and above. Please note that onboarding forms may not be fully compatible with all mobile browsers. ## Creating an Onboarding Form The following shows the steps clients follow to onboard corporate customers using Nium’s pre-built Onboarding Form. Sign up - Onboarding forms are currently only available for Singapore (SG) clients. - Customers with a `registeredCountry` of either SG or non-SG can be onboarded through the SG region. For more details, please contact your Nium account manager or [Nium Support](mailto:support@nium).com. To configure onboarding forms for your account, provide the following details to your Nium sales or account representative. Contact [Nium support](mailto:support@nium.com) if you are unsure of who your sales representative or account manager is: - **Brand name**: The name your customers recognize your products by. - **Brand logo**: Enhance your customers’ onboarding experience by including your logo. - **Minimum size**: - 35x35 pixels, - **Maximum size**: - 5 MB. - **Acceptable formats**: - PNG - JPEG - SVG - **Technical support email**: The email address your customers can use to contact your entity for technical issues or queries. - **Operations email**: The email address to receive communications regarding requests for information (RFIs). ### Step 1: Create an application 1. Submit a [Create Application for Onboarding Form](/api#tag/onboarding-forms---corporate/POST/api/v1/client/{clientHashId}/applications) request and include the required parameters to create an onboarding form application. 2. Nium's API will return a form URL. Share this URL with the customer you're onboarding. You can then either: - Include our custom JavaScript component in your HTML. For more details on this Javascript component, see [Using Javascript for onboarding forms](#using-javascript-for-onboarding-forms) - Embed the form URL in an iframe on your customer facing dashboard. For details on embedding the form URL, see [Using iframes for onboarding forms](#using-iframes-for-onboarding-forms).). - Send it directly to customers via email. #### Request parameters | Parameter | Description | Required | | :---------------- | :------------------------------------------------------------- | :------- | | `region` | Regulatory region under which you want to onboard the customer | Required | | `applicationType` | Only valid value is `corporate` | Required | | `corporate` | Object to pass the basic details of the customer | | ##### `corporate` object | Parameter | Description | Required | | :--------------------------- | :---------------------------------------------------------------------------------------------------------------- | :------- | | `businessName` | The name of the corporate customer. Maximum length: 80 characters. | Yes | | `businessRegistrationNumber` | The business registration number of the corporate customer. Maximum length: 30 alphanumeric characters or spaces. | Yes | | `applicantEmail` | The applicant’s email address where the OTP will be sent. Maximum length: 60 characters. | Yes | | `registeredCountry` | The registered country of the corporate customer. | Optional | ```json { "region": "SG", "corporate": { "businessName": "ABC Capital-01-16", "businessRegistrationNumber": "BRNBCAAN3336", "applicantEmail": "applicant.email@cusdomain.com", "registeredCountry": "SG" }, "applicationType": "corporate" } ``` #### Response | Parameter | Description | Required | | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `applicationId` | A unique identifier for the application used in subsequent requests. | Yes | | `url` | The URL to access the onboarding form. Share this with the customer via an iframe or offline channels like email. | Yes | | `expiry` | The expiration time of the URL in `epoch` format. Use the [Regenerate Onboarding Form URL](/api#tag/onboarding-forms---corporate/GET/api/v1/client/{clientHashId}/applications/{applicationId}/regenerateURL) request if the URL expires. | Yes | ##### Response example ```json { "applicationId": "APP1713860447006QUG", "url": "https://onboard.nium.com/corporate/APP1713860447006QUG?linkId=7653cf6e-957a-4491-b41b-c44f7e96f414", "expiry": "1713359070614" } ``` #### Troubleshooting - **Duplicate values**: The `businessRegistrationNumber` and `businessName` must be unique when creating an application. Submitting duplicate values returns a `BAD_REQUEST` error. - **Multiple applications**: Multiple `applicationId`s can be created for the same applicant but for different corporate customers using the [Create Application for Onboarding Form](/api#tag/onboarding-forms---corporate/POST/api/v1/client/{clientHashId}/applications) request. - **Existing customer**: If a customer already exists with the same `businessName` or `businessRegistrationNumber`, Nium’s API will return an error. Bad request error if an application already exists with the samebusinessName or businessRegistrationNumber ```json { "errors": [ { "code": "application_already_exists", "description": "application already exists with the businessName Kub, Rogahn 1028 and businessRegistrationNumber: 113061158" } ] } ``` Bad request error if a customer already exists with the same businessName or businessRegistrationNumber ```json { "errors": [ { "code": "customer_already_exists", "description": "customer already exists with the businessName Wolff - Borera2011" } ] } ``` ### Step 2: Authenticate the customer Nium sends an OTP to the customer's email, which they enter into the onboarding form to authenticate their account. See [Onboarding forms walkthrough](#onboarding-forms-walkthrough) for screenshots showing where customers enter the OTP. ### Step 3: Complete and submit the form To complete the onboarding form, the corporate customer must provide key business and personal information within the form. The corporate customer applicant must complete the following actions: 1. **Confirm business information**: Applicants review and confirm the corporate customer's business name and registration number, as provided by the client. 2. **Verify business details**: Nium auto-fills the form with business and stakeholder information. Applicants confirm these details and upload any necessary documents. 3. **Enter stakeholder information**: The applicant must complete the details for Ultimate Beneficial Owners (UBOs), shareholders, directors, and other key stakeholders (such as signatories), as listed in the business registration document. The applicant must also upload any required supporting documents. 4. **Provide applicant information**: If the applicant is not one of the previously mentioned stakeholders, they must add their personal information to the form. 5. **Review and accept terms**: The applicant reviews the entered details, accepts the terms and conditions, and submits the form. For more information, see our [Terms & Conditions and Privacy Policy](#terms-and-conditions-and-privacy-policy). 6. **Complete applicant verification**: The applicant verifies their identity via Singpass or by uploading documents through Onfido, our verification partner. In certain regions, verification is automatically performed via database verification, with no further action required from the applicant. 7. **Submission confirmation**: After submitting all required data and documents, and completing the verification process, the applicant will see an "application is under review" message on the form. ### Step 4: Complete compliance review Our compliance team will review the corporate customer's submitted application. Progress is communicated via webhooks. Nium's compliance team may issue a Request for Information (RFI), which will trigger an email from Nium's API detailing the required data. You need to collect the requested data or documents from the corporate customer and submit them back to our compliance team by responding to the RFI email. The review process is complete once the `status` updates to `Clear`. After this, the customer can start initiating transactions. ### Webhooks Integrate with the [Client-KYB Status](/docs/developers/notifications-and-webhooks/platform-events/client-kyb-status) event to track status updates for the application. Use the `applicationId` returned in step 1 to listen for status changes.. Track the `complianceStatus` and `status` fields to determine the next steps. The following table breaks down important `complianceStatus` and `status` updates and the subsequent actions you need to take. You can ignore any other state transitions. | `complianceStatus` | `status` | Description | Action required from the client | | :----------------- | :-------- | :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | | `ACTION_REQUIRED` | `PENDING` | Application is under review by our compliance team. | None | | `RFI_REQUESTED` | `PENDING` | Compliance team raised an RFI. Client will receive an RFI email. | Collect the requested information from the customer and reply to the RFI email. | | `RFI_RESPONDED` | `Pending` | Compliance team has received your RFI response and verifying the details provided. | None | | `COMPLETED` | `Clear` | Application is approved by our compliance team. | Customer can start processing transactions. | | `REJECTED` | `FAILED` | Application is rejected by our compliance team. | Reach out to your Nium account manager for next steps. | ## Additional tools ### Regenerating expired URLs URLs returned in the Create Application for Onboarding Form response expire after 24 hours. When an onboarding form URL expires, customers encounter a **The link you clicked on has broken.** page in their browser and customers must contact the client's support team for a new URL. Sign up The client and their team can fetch a new URL using the [Regenerate Onboarding Form URL](/api#tag/onboarding-forms---corporate/GET/api/v1/client/{clientHashId}/applications/{applicationId}/regenerateURL) request. Customers who have already started filling out the onboarding form will not encounter the **The link you clicked on has broken.** page unless they leave the form and try to access the expired URL again. ### Terms & Conditions The client configures the terms & conditions, which will be shown to the customer. Use the [Terms and Conditions](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions) request to view the terms and conditions configured for your onboarding form. #### Privacy Policy You can review our [Privacy Policy](https://www.nium.com/privacy/privacy-policy) which is also shown to customers. ### JavaScript To integrate our onboarding forms into your platform, you can use our custom JavaScript component. See the following HTML example that shows how to include the onboarding form by passing the form URL as a parameter: ```javascript Custom Component ``` #### Component Paths - Preprod path to access the JavaScript component: ``` https://onboarding-form-frontend.preprod.niumops.com/corporate/resources/niumOnboardingForms.js ``` - Production path to access the JavaScript component: ``` https://onboarding-form.nium.com/corporate/resources/niumOnboardingForms.js ``` #### Best practices To ensure a seamless experience when using the Javascript component, follow these best practices: **Page Layout**: - Use a full-page layout to display onboarding forms for the best visual experience. - If additional elements are required on the same page, make sure scrolling is enabled and verify the form renders correctly. **CSS Customization**: - Keep your CSS minimal to avoid conflicts with the form's default styles. - If you encounter issues with CSS interference, contact your account manager for assistance. **Browser Behavior**: - Avoid refreshing the browser during the onboarding process. Refreshing the page will restart the form from the beginning. - Verify the browser's back button navigates to the previous page of your website. Navigation within the form itself is managed by the "Back" and "Next" buttons provided in the form. **Permissions and Requirements**: - The onboarding forms do not require permissions for camera, microphone, or geolocation. - Document uploads are mandatory for completing the onboarding process. **Authentication**: - By default, onboarding forms request customer authentication immediately after the welcome page. Following these guidelines will help ensure a smooth and reliable onboarding experience for your customers. ### iframes The onboarding form can also be embedded as an iframe onto your customer-facing dashboard or portal. - We advise clients to avoid refreshing their browser while completing the onboarding form, as this can cause the form to reload from the beginning. - Make sure the browser’s back button works as expected. The browser back button should lead users to the previous webpage. Navigation within the form is enabled by *back* and *next* buttons. - Make sure scrolling is enabled so users can navigate through the entire form. - Onboarding form views best in a full page. Make sure to provide sufficient width. - Camera, microphone, geo location permissions are not required. Document upload is required. - By default, onboarding forms request customer authentication after the welcome page. Please note, Singpass currently does not support iframe integrations. Applicants must upload documents using Onfido or another third-party eDocument verification provider. ## Walkthrough The following provides a breakdown of the different pages in Nium's onboarding forms. A GIF is also available to help you better understand how the onboarding form looks, and what customers will run into as they complete the form. Onboarding forms GIF walkthrough Sign up #### Page 1: Welcome Page Sign up #### Page 2: Customer Authentication Sign up #### Page 3: OTP email Sign up #### Page 4: Uploading Data and Documents Sign up #### Page 5: Review and Submit Sign up #### Page 6: Terms & Conditions and Privacy Policy Sign up #### Page 7: Applicant verification Sign up #### Page 8: Onboarding form under review Sign up #### Page 9: RFI email Sign up ## Next steps To ensure a smooth onboarding process for your corporate customers, please reach out to your Nium account manager or contact [Nium support](mailto:support@nium.com) to confirm if any additional information or steps are required. Once everything is confirmed, the Nium team will help you configure your payment experience and finalizing the setup to process transactions for your customers. --- # Onboarding Error Codes URL: https://docs.nium.com/docs/onboarding/corporate-customers/onboarding-error-codes You can use the errorDetails object in all of the APIs related to Onboarding. In this object, code can be used to classify messages and to handle different error codes. You can use the `errorDetails` object in all of the APIs related to Onboarding. In this object, `code` can be used to classify messages and to handle different error codes. Example: - You can direct an applicant to the business details page when receiving error `E100` or `F100`. - You can change the error message and appropriately guide your customer when receiving error `R601`. The error codes on this page are composed of a letter and a 3-digit number. ## `Cxxx` – RFI | Error Code | Error source | | :--------- | :-------------------------------------------------------------------------------------------------------------------------- | | `C101` | Reference ID is required to process the responded RFI for Template . (only for clients who have not integrated RFI HashId) | | `C102` | Either **rfiHashId** or **rfiTemplateId** is required for one of the RFIs | | `C301` | Reference ID is incorrect for the responded RFI for Template . | | `C302` | Invalid RFI template ID(s) . | | `C303` | No matching template found for **uniqueId** with the given **rfiHashId** | | `C304` | No matching template found for the given rfiHashId | | `C305` | rfiHashId is required to resolve multiple open templates with the same templateId e47fbae2-aee2-43d4-9524-c8fcf6513616 | | `C306` | Invalid UniqueId | | `C401` | Provided Information or document is incorrect for the responded RFI for Template . | | `C402` | The RFI has already been responded for template ID . | | | | ## `Exxx` – Missing field in request | Error Code | Error source | | :--------- | :-------------------------------------------- | | `E100` | Business information | | `E200` | Stakeholder details | | `E300` | Applicant details | | `E400` | Risk assessment info info, Nature Of Business | | `E500` | Additional info Expected Account Usage | | `E600` | RFI | | `E800` | Region | | `E900` | Bank details (HK) | ## `Fxxx` – Invalid field in request | Error Code | Error source | | :--------- | :-------------------------------------------- | | `F100` | Business information | | `F200` | Stakeholder details | | `F300` | Applicant details | | `F400` | Risk assessment info info, Nature Of Business | | `F500` | Additional info Expected Account Usage | | `F600` | RFI | | `F800` | Region | | `F900` | Bank details (HK) | ## `Ixxx` – Errors from partners | Error Code | Error source | | :--------- | :----------------------------------------------------------- | | `I000` | KYC is approved. | | `I100` | Fetching data from the partner is not complete. | | `I300` | The application is being reviewed by our compliance agent. | | `I400` | Validation error at one of our partners | | `I500` | An internal service is down. | | `I601` | The status change request is from an invalid status. | | `I602` | The status change request is from an unauthorized personnel. | | `I603` | The link expired. | ## `Pxxx` and `Qxxx` – Parameters are invalid | Error Code | Error source | | :--------- | :-------------------------------------------------------- | | `P100` | Parameters are missing. | | | –– Q –– | | `Q100` | Parameters are invalid. | | `Q101` | Combination of parameters could not be used to find data. | | `Q102` | `clientHashId` cannot be found. | | `Q103` | `customerHashId` cannot be found. | ## `Rxxx` and `Zxxx` – Other errors | Error Code | Error source | | :--------- | :------------------------------------------------------------------------------------------------------------------------ | | `R400` | Bad request – anything that can't be categorized above. | | `R401` | KYC was already completed. | | `R403` | The document was already uploaded. | | `R408` | The link already expired. | | `R500` | Any internal service, vendor, or underlying service is down. | | `R601` | Status change request from an invalid status. | | `R602` | Link regeneration failed - while customer applicant KYC is submitted. | | `R603` | Link regeneration failed - while customer applicant KYC is in `ERROR` state. | | `R604` | Link regeneration failed - link regeneration can't be initiated for this compliance status. | | `R605` | Link regeneration failed - link regeneration can't be initiated for the applicant's current KYC status. | | `R606` | That functionality isn't available in the current status. | | `R607` | The customer can't be created in the current status. | | `R608` | The customer can't use functionalities like the Get Application Details API until after the applicant's KYC is submitted. | | `R609` | An invalid request structure was provided in the stakeholders object. | | `R700` | Too many requests. | | `R800` | Resubmission is blocked because the application was rejected due to high risk. | | `Z100` | Any error that isn't classified in the above scenarios. | In some cases, the `errorDetails` field may not be available where the previous version of `errors` field is in use. --- # Corporate Constants URL: https://docs.nium.com/docs/onboarding/corporate-customers/corporate-constants The Fetch Corporate Constants request returns acceptable values of various fields that need to be passed via the Onboard Corporate Customer request. The [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request returns acceptable values of various fields that need to be passed via the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request. ## Constants endpoint Some of the enumerated fields have values that change often as they're added or removed, such as `intendedUseOfAccount` or `industrySector`. Integrating this request helps you cater to these changes without the need for any further development on your end. Keeping enumerated values up to date is beneficial to the customers as it improves the application approval rates and reduces the turnaround time for approvals. You need to integrate this API as part of your onboarding process. You need to also display its output to your customers as a dropdown list while they complete your onboarding form. Use this API for all the fields listed below. ## `fieldName` to `category` Pass the `fieldName` as the `category` listed in the table below. The following are the categories in [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API. | Fetch Corporate Constants API `category` | Onboard Corporate Customer API `fieldName` | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `annualTurnover` | `riskAssessmentInfo.annualTurnover` | | `averageTransactionValue` | `expectedAccountUsage.debit.averageTransactionValue` `expectedAccountUsage.credit.averageTransactionValue` | | `businessType` | `businessDetails.businessType` `businessDetails.stakeholders.businessPartner.businessType` | | `capitalContribution` | `businessDetails.stakeholders.stakeholderDetails.professionalDetails.capitalContribution` `businessDetails.stakeholders.businessPartner.capitalContribution` `businessDetails.applicantDetails.professionalDetails.capitalContribution` | | `countryName` | `businessDetails.addresses.businessAddress.country` `businessDetails.addresses.registeredAddress.country` `businessDetails.applicantDetails.address.country` `businessDetails.applicantDetails.documentDetails.documentIssuanceCountry` `businessDetails.applicantDetails.taxDetails.country` `businessDetails.businessPartner.addresses.registeredAddress.country` `businessDetails.businessPartner.legalDetails.registeredCountry` `businessDetails.documentDetails.documentIssuanceCountry` `businessDetails.legalDetails.registeredCountry` `businessDetails.partnershipDetails.partnerCountry` `businessDetails.stakeholders.stakeholderDetails.address.country` `businessDetails.stakeholders.stakeholderDetails.documentDetails.documentIssuanceCountry` `businessDetails.taxDetails.country` `riskAssessmentInfo.countryOfOperation` `riskAssessmentInfo.transactionCountries` `businessDetails.applicantDetails.nationality` `expectedAccountUsage.debit.topTransactionCountries``expectedAccountUsage.credit.topTransactionCountries` | | `countryOfOperation` | `riskAssessmentInfo.countryOfOperation` `riskAssessmentInfo.transactionCountries` | | `documentType` | `businessDetails.documentType` `businessDetails.stakeholders.stakeholderDetails.documentType` `businessDetails.applicantDetails.documentType` | | `intendedUseOfAccount` | `riskAssessmentInfo.intendedUseOfAccount` `expectedAccountUsage.intendedUses` | | `industrySector` | `riskAssessmentInfo.industrySector` | | `listedExchange` | `businessDetails.legalDetails.listedExchange` | | `monthlyTransactionVolume` | `expectedAccountUsage.debit.monthlyTransactionVolume` `expectedAccountUsage.credit.monthlyTransactionVolume` | | `monthlyTransactions` | `expectedAccountUsage.debit.monthlyTransactions` `expectedAccountUsage.credit.monthlyTransactions` | | `position` | `businessDetails.stakeholders.stakeholderDetails.position` `businessDetails.stakeholders.businessPartner.businessEntityType` `businessDetails.applicantDetails.position` | | `regulatedTrustType` | `businessDetails.regulatoryDetails.regulatedTrustType` \\\* Valid only for AU | | `restrictedCountries` | `riskAssessmentInfo.restrictedCountries` \\\* Required for the UK | | `state` | `businessDetails.addresses.registeredAddress.state` `businessDetails.addresses.businessAddress.state` `businessDetails.stakeholders.stakeholderDetails.address.state ` `businessDetails.addresses.applicantDetails.address.state` \\\* Valid only for US, AU, NZ addresses. | | `streetType` | `businessDetails.stakeholders.stakeholderDetails.address.state ` `businessDetails.addresses.applicantDetails.address.state` \\\* Valid only for AU, NZ addresses. | | `totalEmployees` | `riskAssessmentInfo.totalEmployees` | | `trustBeneficiaryClass` | `businessDetails.stakeholders.stakeholderDetails.professionalDetails.trustBeneficiaryClass` \\\* Valid only for NZ | | `unregulatedTrustType` | `businessDetails.regulatoryDetails.unregulatedTrustType` | | `votingRights` | `businessDetails.stakeholders.stakeholderDetails.professionalDetails.votingRights` | | `rfiTemplates` | This can be used to find the templateId to template name mapping for RFI templates of different regions. | ## Response The API response contains an array of code-description pairs that are valid for the given field. | Response field | Usage | | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | The valid values that need to be used in the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request for the given field. | | `description` | A description of the category code which can be shown to the applicant as a dropdown list. | --- # Using the Sandbox URL: https://docs.nium.com/docs/onboarding/corporate-customers/using-the-sandbox As part of onboarding, you need to submit data and documents for your business, your business stakeholders, and your applicants via the Onboard Corporate Customer API. After you receive a response with status='INPROGRESS', your customer needs to check for any additional required documents in the remarks field, such as a redirect URL for applicant KYC. After all required data and documents are submitted, Nium initiates verification, and the application status changes to ACTIONREQUIRED, COMPLETED, or REJECTED which is communicated via webhook, detailed in Onboard API response. As part of onboarding, you need to submit data and documents for your business, your business stakeholders, and your applicants via the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. After you receive a response with `status='IN_PROGRESS'`, your customer needs to check for any additional required documents in the `remarks` field, such as a redirect URL for applicant KYC. After all required data and documents are submitted, Nium initiates verification, and the application status changes to `ACTION_REQUIRED`, `COMPLETED`, or `REJECTED` which is communicated via webhook, detailed in [Onboard API response](/docs/onboarding/corporate-customers#onboard-api-response). Nium’s sandbox allows you to simulate the below scenarios for onboarding a corporate customer by using the appropriate `businessRegistrationNumber` and Request examples. | Scenario | Description | | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Auto-approval | All documents and information required for completing the verification process are provided in the Onboard Corporate Customer API. The application is approved in real-time (within a few minutes) and then you receive a webhook with `status='COMPLETED'`. This is applicable only for the eKYB flow. | | Action required | All documents and information required are provided in the Onboard Corporate Customer API, but the application was not auto-approved and needs to be manually reviewed by Nium's compliance team. You receive a webhook with `status='ACTION_REQUIRED'` . Once received, wait for the next webhook which will be sent after the compliance agent completes the manual review. | | In Progress with documents required | All information required for completing the verification process is provided in the Onboard Corporate Customer API, however some of the required documents are not submitted. The customer is expected to submit all the required documents after which Nium initiates the verification. In this case, you need to receive the documents required in the `remarks` field. | | In Progress with redirection link | All information required for completing the verification process is provided in the Onboard Corporate Customer API, however the applicant is required to complete the KYC using the redirect URL received using the Onboard Corporate Customer API. You can direct the applicant to the redirect URL so the applicant can complete KYC on the vendor's portal. | ## Simulate various scenarios - [Example requests - AU](/docs/onboarding/corporate-customers/au-onboarding/example-requests) - [Example requests - CA](/docs/onboarding/corporate-customers/ca-onboarding/example-requests) - [Example requests - EU](/docs/onboarding/corporate-customers/eu-onboarding/example-requests) - [Example requests - HK](/docs/onboarding/corporate-customers/hk-onboarding/example-requests) - [Example requests - SG](/docs/onboarding/corporate-customers/sg-onboarding/example-requests) - [Example requests - UK](/docs/onboarding/corporate-customers/uk-onboarding/example-requests) - [Example requests - US](/docs/onboarding/corporate-customers/us-onboarding/example-requests) ## Response examples for Exhaustive Corporate Details API The Nium sandbox allows you to fetch multiple responses in the [Exhaustive Corporate Details using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) API by providing different business registration numbers. For details, see your region's example response. - [Response example for EU](/docs/onboarding/corporate-customers/eu-onboarding/example-requests) - [Response example for SG](/docs/onboarding/corporate-customers/sg-onboarding/example-requests) - [Response example for UK](/docs/onboarding/corporate-customers/uk-onboarding/example-requests) --- # Letter of Authorization URL: https://docs.nium.com/docs/onboarding/corporate-customers/letter-of-authorization A Letter of Authorization (LOA) or Power of Attorney (POWER_OF_ATTORNEY) is a document signed by a business signatory that authorizes an applicant to conduct financial transactions and related activities on behalf of the business. This document is critical because it verifies the applicant’s authority to represent the business. A **Letter of Authorization (LOA)** or **Power of Attorney (POWER\_OF\_ATTORNEY)** is a document signed by a business signatory that authorizes an applicant to conduct financial transactions and related activities on behalf of the business. This document is critical because it verifies the applicant’s authority to represent the business. *Live-authorization* is a digital process where a signatory authorizes the applicant without requiring physical documents or signatures. ## Regional requirements **APAC/UK** For customers in AU, NZ, SG, HK, UK, CA, and JP: If the applicant is not a *DIRECTOR*, *UBO* (Ultimate Beneficial Owner), or an equivalent role, they must submit a Letter of Authorization (`documentType` = **LOA**). - In the UK, use `POWER_OF_ATTORNEY`. - If the LOA is missing or incorrect, a compliance agent will raise an RFI (Request for Information) with the template `applicantAuthorizationLetter`. For more details about RFI templates, see [RFI Templates](/docs/onboarding/corporate-customers/requests-for-information). - The LOA must be issued and signed by directors or other authorized signatories. **US** For customers in the US: - If the applicant is not an officer, an LOA can be submitted. - If not submitted, the LOA will be requested via an RFI. **EU** For customers in the EU: - If the applicant is not a *DIRECTOR*, they must submit a `POWER_OF_ATTORNEY`. - If issued in a non-EEA country, the Power of Attorney must be certified by an apostille. - Alternatively, the applicant can nominate a director to provide live-authorization. - A live-authorization does not require an apostille, regardless of where it is issued. ## LOA template Applicants can use the following application, have it signed by directors or authorized signatories (or officers in the US): [Letter of Authorization (LOA)](https://github.com/nium-global/nium-assets/raw/014de0b57ef62158e8dd8aa7213e6f7d39631105/Letter%20of%20Authorizations%20\(LOA\)/LOA-letter-of-authorizatio.pdf) ## Live-authorization Live-authorization is an alternative to submitting a Power of Attorney. Applicants can nominate a director (or other signatory with equivalent powers) to provide digital authorization. Benefits of live-authorization include: - Removing the need for physical documents. - In the EU, avoids the requirement for a Power of Attorney certified by an apostille. Currently, live-authorization is available only in the EU but we're on brining this capability to more regions. ### Process 1. Applicant nominates a director as the Live-Authorizer and skips submitting a Power of Attorney. 2. Applicant completes biometric verification using a link (Onfido). 3. The nominated director receives a separate link (shared by the client), reviews applicant and authorization details, provides consent, and completes biometric verification. 4. This process creates a legally enforceable authorization equivalent to a signed LOA or Power of Attorney. Authorization page ## Implementation notes - If the applicant is not a Director, your UI should allow them to either: - Submit a Power of Attorney, or - Nominate a director for Live-authorization. - For the nominated director: - Pass `stakeholderDetails.isLiveAuthorizer` as **true** and `kycMode` as **E\_DOC\_VERIFY**. - You receive an additional `redirectURL` in the Onboard Corporate Customer response. Share this link with the nominated director. - Do not submit a Power of Attorney for this applicant. - Once all required documents and biometric checks are completed (by the applicant, director, and others), the `complianceStatus` updates to `ACTION_REQUIRED` and Nium reviews the application. - If Live-authorization fails, operations may request re-authorization or a Power of Attorney via RFI. ## Validations - Only one stakeholder can be nominated for live-authorization. - The position field must contain **DIRECTOR** if `isLiveAuthorizer` is set to **true**. - Currently, only directors are eligible for live-authorization. - `kycMode` **E\_DOC\_VERIFY** must be used when `isLiveAuthorizer = true`. --- # Requests for Information (RFIs) URL: https://docs.nium.com/docs/onboarding/corporate-customers/requests-for-information After submission, the status in the Onboard Corporate Customer response is IN_PROGRESS. The applicant needs to complete both the Applicant KYC (if applicable) and Upload documents steps to proceed further. Once done, Nium initiates verification and sends the response via a webhook. After submission, the status in the Onboard Corporate Customer response is `IN_PROGRESS`. The applicant needs to complete both the Applicant KYC (if applicable) and Upload documents steps to proceed further. Once done, Nium initiates verification and sends the response via a webhook. The application might be approved at this stage; and if it isn't approved, the application goes through a manual review. Any changes in the status is again communicated via a webhook. If the agent requires more information to approve the application, he raises an RFI. This will trigger a webhook (`CARD_CLIENT_KYB_STATUS_WEBHOOK`) with the status `RFI_REQUESTED`. Client has to perform the following steps: - [Step 1: Fetch Corporate Customer RFI Details](#step-1) - [Step 2: Respond to RFI Details](#step-2) ## Step 1: Fetch Corporate Customer RFI Details Call the [Fetch Corporate Customer RFI Details](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/rfi) API with either `caseID` or `clientID` or `customerHashId` in the query parameter. ### Response of Fetch Corporate Customer RFI details The `rfiTemplates` ios an array of objects that contains the RFI templates that are requested for the business or stakeholder. Use the `rfiHashId` to fetch a specific RFI. Please note, while `rfiHashId` will always be unique, two RFIs can share the same values for the following: - `templateId` - `referenceId` - `status` For example. if a `stakeholderAddress` RFI is raised for two stakeholders, the RFIs will have the same `templateId` with different `referenceId`. #### `rfiTemplates` object | Parameter | Type | Description | | :--------------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `rfiHashId` | string | Unique identifier for the individual RFI | | `referenceID` | string | This is the `referenceId` of the entity for which the RFI is raised. This field is available to applicants and stakeholders. When this value available, you need to pass the same `referenceId` in the Respond to RFI API. If you don't already have, use the Customer Details API to fetch the `referenceId` for each stakeholder and applicant. | | `remarks` | string | This field returns any remarks entered by the compliance agent. | | `status` | enum | The status of this particular template is either `RFI_REQUESTED` or `RFI_RESPONDED`. This field changes to `RFI_RESPONDED` when an RFI is responded to. | | `templateId` | string | The RFI template ID. This is not a unique value for the RFI. There is a one-to-one mapping for `templateId` and `template.name`. **Note:** There can be two RFIs with the same `templateId` and `referenceId` and `status` but with different `rfiHashId`. | | [template](#template-object) | object | This object contains information about the template. | #### `template` object This object is within the `rfiTemplates` array of objects and contains information about the template. | Parameter | Type | Description | | :-------------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `documentType` | enum | This is the type of the document expected from the customer: Valid values: `POA` (Proof of Address)`POI` (Proof of Identity)`LOA` (Letter of Authorization)`POWER_OF_ATTORNEY``document` (for any other kind of document) | | `name` | string | The name of the template. For example: `stakeholderAddress` and `stakeholderIdentity`. | | [requiredFields](#requiredfields-array) | array of objects | This object contains metadata and can be used to directly display the required fields to the customer. **Note:** This object can be ignored if you are displaying the required fields yourself. | | `rfiType` | enum | Valid values are: `corporate` for `businessDetails` related or `riskAssessmentInfo` related RFIs`applicant` for applicant related RFIs`stakeholder` for individual and corporate related RFIs | | `type` | enum | The determines the type of template. Valid values are: `data``document` | #### `requiredFields` array This array of objects is within the `rfiTemplates.template` object and contains metadata as well as can be used to directly display the required fields to the customer. **NOTE:** This object can be ignored if you are constructing the set of required fields yourself. | Parameter | Type | Description | | :----------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fieldLabel` | string | This text can be directly displayed on the form to the customer as a label. | | `fieldValue` | string | This indicates into which onboarding API field the value is sent. Valid values are: `documentType``documentNumber``documentExpiryDate``document``intendedUseOfAccount``businessName``transactionCountries` **Note:** The value `document` refers to the `document` object that contains the `fileName`, `fileType`, and `document` base-64 fields.`documentExpiryDate` may not be available for all `documentType` values. This can be treated as optional and can be sent for `DRIVER_LICENSE` or `PASSPORT`. | | `type` | enum | Use this to configure the UI element. Valid values are: `data``document` | ## Step 2: Respond to RFI Details Pick the templates where `status = RFI_REQUESTED` and call the [Respond to RFI Details](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate/rfi) API. | Parameter | Type | Description | | :---------------------------------------------------------------- | :--------------- | :----------------------------------------------------------------------------------------------------------------- | | `region` | enum | Valid values are: `AU``EU``HK``SG``UK``US` | | `
  • `clientId`
  • `caseId`
  • `customerHashId`
    • ` | string | Any one of these three values is required. | | [rfiResponseRequest](#rfiresponserequest-array) | array of objects | This contains an array of objects each of which is a response to an RFI template present in Fetch RFI Details API. | ### `rfiResponseRequest` array This contains an array of objects each of which is a response to an RFI template present in Fetch RFI Details API. | Parameter | Type | Description | | :------------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rfiHashId` | string | Unique identifier for the individual RFI reecived in the Fetch RFI Details API response. | | `rfiTemplateId` | string | The ID corresponding to each template name. This field is in the process of being depreciated. This is optional for clients integrating using `rfiHashId`. If you hvae any questions about moving away from this field, please reach out to your Nium account manager or [Nium support](mailto:support@nium.com). | | `businessDetails` | object | This object is similar to the `businessDetails` object in the Onboard Corporate Customer API but requires only the required fields of the RFI. Note: API reference section for [Respond to RFI Details](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate/rfi) mentions `businessInfo` instead of `businessDetails`. We accept both values to ensure backward compatibility | | `riskAssessmentInfo` | object | This object is similar to the `riskAssessmentInfo` object in the Onboard Corporate Customer API but contains only the required fields. | The fields and structure of the Respond to RFI API are the same as that of the Onboard Corporate Customer API You need to send only the required fields for the RFI and not the entire onboard request again. For examples of how to send each RFI, see [RFI examples](/docs/onboarding/corporate-customers/requests-for-information-rfis/rfi-examples). You can choose to add the `documentType` field within the `documentDetails` object. Use the following values for `documentType` - `BUSINESS_REGISTRATION_DOCUMENT` - `INVOICE` - `LICENSE` - `OTHER` - `PARTNERSHIP_DEED` - `PROOF_OF_ADDRESS` - `PROOF_OF_IDENTITY` - `SELFIE` - `TRUST_DEED` - `LOA` - `POWER_OF_ATTORNEY` The `documentDetails` element--not an array--is an object for the Fetch Corporate Constants API of all applicant, corporate, and stakeholder `rfiType` values. Its behavior is different from the Onboard Corporate API because different RFIs will be raised for each document required. However, if you want to send multiple files for the same document--for example, the front and back of a passport--you can make use of the document object which is an array of objects with fields `fileName`, `fileType`, and `document`. To enable backward compatibility this API supports both `businessInfo` object and `businessDetails` object. ### Responding to multiple RFI templates You can respond to multiple RFI templates in the same request. Make sure you have different objects for each `rfiHashId`. Once all the RFI templates are responded, the status of the application changes from `RFI_REQUESTED` to `RFI_RESPONDED` and you will receive a webhook with `complianceStatus`=`RFI_RESPONDED` After the application, the `complianceStatus` can again become `RFI_REQUESTED` or one of the terminal states becomes `COMPLETED` or `REJECTED`. Though rare, compliance agent can raise an RFI even after the `complianceStatus` is `COMPLETED`. Make sure to provision such cases. ### Troubleshooting errors | **Error** | **Description** | | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `No matching template found for referenceId with the given rfiHashId` or `No matching template found for the given rfiHashId` | The `templateId` is optional. If provided, it must match the `templateId` returned when using the `rfiHashId` to [fetch RFI details](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/rfi). | | `rfiHashId is required to resolve multiple open templates with the same templateId XXXXX` | If multiple RFIs have been raised with the same `templateId`, you must provide the `rfiHashId`. If you haven't integrated `rfiHashId`, contact [Nium support](mailto:support@nium.com). | | `Either rfiHashId or rfiTemplateId is required` | You must provide either the `rfiHashId` or the `templateId`. | | `RFI template ID is invalid` | There is no RFI raised for the customer associated with this template. | | `Invalid UniqueId` | (For clients who have not integrated `rfiHashId`) Either the `referenceId` does not match the `templateId`, or the required `referenceId` is missing. | | `RFI is already responded` | An agent has already responded to this RFI by collecting information from other sources. To prevent this, use the \[Fetch RFI Details]\([fetch RFI details](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/rfi)) request when the customer is ready to respond, and only display templates with the status `RFI_REQUESTED`. | | `Reference ID is required to process the responded RFI` | The `referenceId` field is required for all applicant-related and stakeholder-related RFIs. | --- # RFI Templates URL: https://docs.nium.com/docs/onboarding/corporate-customers/requests-for-information-rfis/rfi-templates This page contains all the possible Request For Information (RFI) templates for corporate customers. For the RFI template and response examples, see [RFI examples](/docs/onboarding/corporate-customers/requests-for-information-rfis/rfi-examples). Use [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/rfi) request with `category` set to **rfiTemplates** to fetch `templateId` to template `name` mapping for RFI templates of different regions. For a mapping of RFI `templateId` to RFI `template.name`, use `category = rfiTemplates` in the Fetch Corporate Constants API. **Note:** The `templateId` in sandbox can only be used for integration in sandbox; and `templateId` in production can only be used for integration in production.. The below Request parameters refer to the response object of the [Fetch Corporate Customer RFI Details](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/rfi) API where: - RFI name: `rfiTemplates.template.name` - RFI field name: `rfiTemples.template.requiredFields.fieldValue` ## RFI templates for applicant details ### Templates where RFI type is documents The **RFI field name** fields are within the `businessInfo.applicantDetails.documentDetails` object | RFI name | RFI description | RFI field name | Region | | :----------------------------- | :----------------------------------------------------- | :------------------------------------------------------------------ | :--------------------------- | | `applicantAddress` | Valid applicant's proof of address document | `.documentType` `.document` | `AU EU HK SG UK US CA NZ JP` | | `applicantAuthorizationLetter` | Valid applicant's letter of authorization | `.document` | `AU __ HK SG UK US CA NZ JP` | | `applicantIdentity` | Valid applicant's proof of identity document | `.documentType` `.documentNumber` `.documentExpiryDate` `.document` | `AU EU HK SG UK US CA NZ JP` | | `powerOfAttorney` | Valid applicant's power of attorney document | `.document` | `AU EU HK SG UK US CA NZ JP` | | `applicantreKyc\*` | Live selfie and document verification of the applicant | `.document` | `EU UK` | The `applicantreKyc` RFI includes the link to complete selfie verification in the `remarks` section. The applicant clicks on this link to complete selfie verification. Once completed, the RFI closes automatically. The client won't need to respond to the RFI with any additional data. ## RFI templates for stakeholder details ### Templates where RFI type is documents The **RFI field name** fields are within the `businessInfo.stakeholders.stakeholderDetails.documentDetails` object and the `businessInfo.stakeholders.businessPartner.documentDetails` object. | RFI name | RFI description | RFI field name | Region | | :-------------------- | :------------------------------------------------------- | :------------------------------------------------------------------ | :--------------------------- | | `stakeholderAddress` | Valid stakeholder proof of address document | `.documentType` `.document` | `AU EU HK SG UK US CA NZ JP` | | `stakeholderIdentity` | Valid stakeholder proof of identity document | `.documentType` `.documentNumber` `.documentExpiryDate` `.document` | `AU EU HK SG UK US CA NZ JP` | | `stakeholderreKYC\*` | Live selfie and document verification of the stakeholder | `.document` | `EU UK SG` | The stakeholderreKYC RFI similar to the applicantreKyc RFI includes the link to complete selfie verification in the remarks section. The link should be distributed to the respective stakholder for completing KYC. Once completed, the RFI closes automatically. The client won't need to respond to the RFI with any additional data. ## RFI Templates for business details ### Templates where RFI type is data The **RFI field name** fields are within the `businessInfo` object. | RFI name | RFI description | RFI field name | Region | | :------------- | :-------------------------------------------------------------------------------------- | :------------------------- | :--------------------------- | | `businessName` | The corporate customer's registered business name. | `.businessName` | `AU EU HK SG UK US CA NZ JP` | | `otherData` | To collect any other information about the customer or its stakeholders and applicants. | `additionalInfo.otherData` | `AU EU HK SG UK US CA NZ JP` | ### Templates where RFI type is documents The **RFI field name** fields are within the `businessInfo.documentDetails` object. | RFI name | RFI description | RFI field name | Region | | :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- | :---------------------------- | | `acra` | The Singapore government issues the Accounting and Corporate Regulatory Authority (ACRA) report to Singapore companies confirming their registration, activity, and most of their recent stakeholders' list. | `.document` | `__ __ __ SG __ __` | | `asic` | The Australian government issues the Australian Securities and Investments Commission (ASIC) report to Australian companies confirming their registration, activity, and most of their recent stakeholders' list. | `.document` | `AU __ __ __ __ __ _ NZ _ JP` | | `businessRegistrationDocument` | The business registration document of the corporate customer. | `.document` | `AU EU HK SG UK US CA NZ JP` | | `directorsRegister` | The register of directors of the corporate customer. | `.document` | `__ EU __ __ __ US` | | `corporateAddressProof` | The proof of a current address for the company. The document can be a bank statement, utility bill, or letter from the government. | `.document` `.documentType` | `AU EU HK SG UK US CA NZ JP` | | `invoice` | The invoice for the corporate customer. | `.document` | `AU EU HK SG UK US CA NZ JP` | | `license` | The business license of the corporate customer. e.g. if you sell alcohol you must have a liquor license | `.document` | `AU EU HK SG UK US CA NZ JP` | | `otherDocument` | An addditional supporting document for the corporate customer. | `.document` | `AU EU HK SG UK US CA NZ JP` | | `partnershipDeed` | The partnership deed of the corporate customer. | `.document` | `AU EU HK SG UK US CA NZ JP` | | `shareholdersRegister` | The register of shareholders of the corporate customer. | `.document` | `__ EU __ __ __ US` | | `trustDeed` | The trust deed of the corporate customer. | `.document` | `AU EU HK SG UK US CA NZ JP` | | `uniqueTaxpayerNumber` | A company’s unique taxpayer number is a 10-digit reference number assigned by the HM Revenue and Customs (HMRC) department in the United Kingdom to identify a limited company for tax purposes. | `.document` | `__ __ __ __ UK __` | ## RFI templates for risk assessment information ### Templates where RFI type is data The **RFI field name**fields are within the `riskAssessmentInfo` object. | RFI name | RFI description | RFI field name | Region | | :--------------------- | :------------------------------------------------------------ | :---------------------- | :--------------------------- | | `transactionCountries` | The primary countries where the corporate customer transacts. | `.transactionCountries` | `AU EU HK SG UK US CA NZ JP` | | `intendedUseOfAccount` | The primary use of the corporate customer's account. | `.intendedUseOfAccount` | `AU EU HK SG UK US CA NZ JP` | --- # RFI Examples URL: https://docs.nium.com/docs/onboarding/corporate-customers/requests-for-information-rfis/rfi-examples Thew following details the different responses you can expect to receive when using the Fetch RFI Template Details request to understand how to respond to Requests for Information (RFIs). The response you receive when using the Fetch RFI Template Details request details what details you'll need to include in your response to the RFI. You specifically use the Respond to RFI request and include the details returned in the Fetch RFI Template Details request. For a list of RFI templates and definitions, see [RFI templates](/docs/onboarding/corporate-customers/requests-for-information-rfis/rfi-templates). Please note, both `rfiHashId` and `rfiTemplateId` are both currently supported when responding to RFIs. However, `rfiTemplateId` will be deprecated in the coming months. We recommend using `rfiHashId` in in all new implementations. If you have any questions, please contact your Nium account manager or [Nium Support](mailto:support@nium.com). ## Applicant details Templates that appear under `applicantDetails` includes: | Template | Description | | :---------------------------------------------------------------- | :------------------------------------------------------------------------------- | | [`applicantAddress`](#applicant-address) | Proof of address for the applicant, such as a utility bill or bank statement. | | [`applicantIdentity`](#applicant-identity) | Government-issued identity document for the applicant. | | [`applicantAuthorizationLetter`](#applicant-authorization-letter) | Letter authorizing the applicant to act on behalf of an entity. | | [`applicantPersonalImage`](#applicant-personal-image) | Recent photo or selfie of the applicant for identity verification. | | [`applicantreKyc`](#applicant-rekyc) | Data for re-verifying the applicant’s identity, typically via third-party tools. | ### Applicant address `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "b93bac45-4661-4217-944a-081bf7b91b2b", "templateId": "7cddffb5-e076-4965-8433-2e995de7c8f1", "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "template": { "name": "applicantAddress", "documentType": "POA", "type": "document", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Proof of Address Document Type", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Proof of Address Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Require Applicant Adddress Doc for verification (not older than 3 months)", "status": "RFI_REQUESTED" } ``` > Respond to RFI request Note: API reference section for [Respond to RFI Details](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate/rfi) mentions `businessInfo` instead of `businessDetails`. We accept both values to ensure backward compatibility ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "b93bac45-4661-4217-944a-081bf7b91b2b", "businessDetails": { "applicantDetails":{ "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "documentDetails": { "documentType":"Bank Statement", "document": [{ "document": "", "fileName": "ProofOfAddress.png", "fileType": "image/png" } ] } } } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "7cddffb5-e076-4965-8433-2e995de7c8f1", "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "template": { "name": "applicantAddress", "documentType": "POA", "type": "document", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Proof of Address Document Type", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Proof of Address Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Require Applicant Adddress Doc for verification (not older than 3 months)", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "7cddffb5-e076-4965-8433-2e995de7c8f1", "businessDetails": { "applicantDetails":{ "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "documentDetails": { "documentType":"Bank Statement", "document": [{ "document": "", "fileName": "ProofOfAddress.png", "fileType": "image/png" } ] } } } } ] } ``` ### Applicant identity `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "2a6010c8-2684-4294-bc1f-bc67bb92fceb", "templateId": "9ef0ddd3-2070-4024-8edd-dcc1b2f2414b", "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "template": { "name": "applicantIdentity", "documentType": "POI", "type": "document", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Identity Document Type", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Identity Document Number", "fieldValue": "documentNumber", "type": "data" }, { "fieldLabel": "Identity Document Expiry Date", "fieldValue": "documentExpiryDate", "type": "data" }, { "fieldLabel": "Identity Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Require Applicant Identity Doc for verification", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "2a6010c8-2684-4294-bc1f-bc67bb92fceb", "businessDetails": { "applicantDetails":{ "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "documentDetails": { "documentType":"PASSPORT", "documentNumber":"123456", "documentExpiryDate":"2024-11-11", "documentIssuanceCountry": "UK", "document": [{ "document": "", "fileName": "IdentityProof.png", "fileType": "image/png" } ] } } } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "9ef0ddd3-2070-4024-8edd-dcc1b2f2414b", "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "template": { "name": "applicantIdentity", "documentType": "POI", "type": "document", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Identity Document Type", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Identity Document Number", "fieldValue": "documentNumber", "type": "data" }, { "fieldLabel": "Identity Document Expiry Date", "fieldValue": "documentExpiryDate", "type": "data" }, { "fieldLabel": "Identity Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Require Applicant Identity Doc for verification", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "9ef0ddd3-2070-4024-8edd-dcc1b2f2414b", "businessDetails": { "applicantDetails":{ "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "documentDetails": { "documentType":"PASSPORT", "documentNumber":"123456", "documentExpiryDate":"2024-11-11", "documentIssuanceCountry": "UK", "document": [{ "document": "", "fileName": "IdentityProof.png", "fileType": "image/png" } ] } } } } ] } ``` ### Applicant authorization letter `rfiHashId` > Fetch RFI Details response Template for `powerOfAttorney` is similar to `applicantAuthorizationLetter` . ```json { "rfiHashId": "79b549ec-4f0b-4592-9efd-c8a718973004", "templateId": "f48ad926-6b3c-4fb8-ba09-36a73c646fe3", "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "template": { "name": "applicantAuthorizationLetter", "documentType": "LOA", "type": "document", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Identity Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Require Letter of Authorisation for Applicant", "status": "RFI_REQUESTED" } ``` > Respond to RFI request Template for `powerOfAttorney` is similar to `applicantAuthorizationLetter` . ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "79b549ec-4f0b-4592-9efd-c8a718973004", "businessDetails": { "applicantDetails":{ "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "documentDetails": { "documentType":"LOA", "document": [{ "document": "", "fileName": "LOA.png", "fileType": "image/png" } ] } } } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "f48ad926-6b3c-4fb8-ba09-36a73c646fe3", "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "template": { "name": "applicantAuthorizationLetter", "documentType": "LOA", "type": "document", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Identity Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Require Letter of Authorisation for Applicant", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "f48ad926-6b3c-4fb8-ba09-36a73c646fe3", "businessDetails": { "applicantDetails":{ "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "documentDetails": { "documentType":"LOA", "document": [{ "document": "", "fileName": "LOA.png", "fileType": "image/png" } ] } } } } ] } ``` ### Applicant personal image `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "14f65e1e-449e-40d3-81a6-d2b132f150a2", "templateId": "fad8ddcf-34a0-4951-a09b-a678bb8a18cc", "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "template": { "name": "applicantPersonalImage", "documentType": "POI", "type": "document", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Selfie Image", "fieldValue": "document", "type": "document" } ] }, "remarks": "Require latest photograph of the applicant ", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "14f65e1e-449e-40d3-81a6-d2b132f150a2", "businessDetails": { "applicantDetails":{ "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "documentDetails": { "documentType":"Selfie", "document": [{ "document": "", "fileName": "Selfie.png", "fileType": "image/png" } ] } } } } ] } ``` `rfiTemplateId` > Fetch Details response ```json { "templateId": "fad8ddcf-34a0-4951-a09b-a678bb8a18cc", "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "template": { "name": "applicantPersonalImage", "documentType": "POI", "type": "document", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Selfie Image", "fieldValue": "document", "type": "document" } ] }, "remarks": "Require latest photograph of the applicant ", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "fad8ddcf-34a0-4951-a09b-a678bb8a18cc", "businessDetails": { "applicantDetails":{ "referenceId": "86cc20d6-86d2-4da6-87d1-3d7c1f4cf7b8", "documentDetails": { "documentType":"Selfie", "document": [{ "document": "", "fileName": "Selfie.png", "fileType": "image/png" } ] } } } } ] } ``` ### Applicant reKyc `rfiHashId` > Fetch RFI Details response ``` { "rfiHashId": "a7b86b3e-809e-4c9b-9ac4-e0a632ade2b8", "templateId": "758f8e8d-f589-468c-9509-268ce67b3075", "referenceId": "5ff7c5a9-e7ed-4a7b-a655-0a83eb246e3a", "template": { "name": "applicantreKYC", "type": "data", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Other Data", "fieldValue": "otherData", "type": "data" } ] }, "remarks": "Please complete the onfido verification: https://integrationspreprod.partners.instarem.com/preprod/compliance/callback/load?referenceNumber=3997dbbf-7f28-4928-9a10-4394b85d5807&token=eyJhQ", "status": "RFI_REQUESTED" } ``` `rfiTemplateId` > Fetch RFI Details response ``` { "templateId": "758f8e8d-f589-468c-9509-268ce67b3075", "referenceId": "5ff7c5a9-e7ed-4a7b-a655-0a83eb246e3a", "template": { "name": "applicantreKYC", "type": "data", "rfiType": "applicant", "requiredFields": [ { "fieldLabel": "Other Data", "fieldValue": "otherData", "type": "data" } ] }, "remarks": "Please complete the onfido verification: https://integrationspreprod.partners.instarem.com/preprod/compliance/callback/load?referenceNumber=3997dbbf-7f28-4928-9a10-4394b85d5807&token=eyJhQ", "status": "RFI_REQUESTED" } ``` ## Business details Templates that appear under `businessDetails` includes: | Template | | :------------------------------------------------------------------------------------------------------ | | [`businessName`](#businessname-response-fetch-rfi-details-api) | | [`otherData`](#otherdata-template-response-fetch-rfi-details-api) | | [`businessRegistrationDocument`](#businessregistrationdocument-template-response-fetch-rfi-details-api) | | [`otherDocument`](#otherdocument-template-response-fetch-rfi-details-api) | ### Business name `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "619691ef-6c2a-4552-8148-9fd978a65143", "templateId": "ccb58d50-5dad-4bff-a418-3c2d5426e4c2", "template": { "name": "businessName", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Business Name", "fieldValue": "businessName", "type": "data" } ] }, "remarks": "Please submit the name of the business without special charaters", "status": "RFI_REQUESTED" }, ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "619691ef-6c2a-4552-8148-9fd978a65143", "businessDetails": { "businessName":"Bradsons Electronics28 revised" } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "ccb58d50-5dad-4bff-a418-3c2d5426e4c2", "template": { "name": "businessName", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Business Name", "fieldValue": "businessName", "type": "data" } ] }, "remarks": "Please submit the name of the business without special charaters", "status": "RFI_REQUESTED" }, ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "ccb58d50-5dad-4bff-a418-3c2d5426e4c2", "businessDetails": { "businessName":"Bradsons Electronics28 revised" } } ] } ``` ### Other data The `otherData` template is a very useful RFI since agents often use it to fetch any information that doesn't have a template defined. Compliance agent can request multiple otherData templates together with different comments. Make sure to add the right rfiHashId when responding. `rfiHashId` > Fetch RFI Details response ```json { "rfiTemplates": [ { "rfiHashId": "42261455-0f66-414c-9866-5bfb9281420e", "templateId": "838c752a-2a3c-42f3-84e9-95a8ab8e9ea2", "template": { "name": "otherData", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Other Data", "fieldValue": "otherData", "type": "data" } ] }, "remarks": "Please provide detailed nature of business", "status": "RFI_REQUESTED" }, { "rfiHashId": "0bb4eead-3166-452d-8aaa-4377e1f69c0c", "templateId": "838c752a-2a3c-42f3-84e9-95a8ab8e9ea2", "template": { "name": "otherData", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Other Data", "fieldValue": "otherData", "type": "data" } ] }, "remarks": "Clarify if applicant Jake Jacob and stakeholder Jake J Tarter are one and the same.", "status": "RFI_REQUESTED" } ] } ``` > Respond to RFI request ```json { "region": "SG", "clientId": "NIM1693472104978", "rfiResponseRequest": [ { "rfiHashId": "42261455-0f66-414c-9866-5bfb9281420e", "businessDetails": { "additionalInfo": { "otherData": "My Detailed Nature of business is to sell Oranges online to customers that are in different countries." } } }, { "rfiHashId": "0bb4eead-3166-452d-8aaa-4377e1f69c0c", "businessDetails": { "additionalInfo": { "otherData": "Yes they are one and the same, after marriage Jake changed her last name." } } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "rfiTemplates": [ { "templateId": "838c752a-2a3c-42f3-84e9-95a8ab8e9ea2", "template": { "name": "otherData", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Other Data", "fieldValue": "otherData", "type": "data" } ] }, "remarks": "Please provide detailed nature of business", "status": "RFI_REQUESTED" } ] } ``` > Respond to RFI request ```json { "region": "SG", "clientId": "NIM1693472104978", "rfiResponseRequest": [ { "rfiTemplateId": "838c752a-2a3c-42f3-84e9-95a8ab8e9ea2", "businessDetails": { "additionalInfo": { "otherData": "My Detailed Nature of business is to sell Oranges online to customers that are in different countries." } } } ] } ``` ### Business registration document The following RFIs are similar: - `acra` - `asic` - `directorsRegister` - `incorporationForm` - `invoice` - `license` - `otherDocument` - `partnershipDeed` - `shareholdersRegister` - `trustDeed` - `uniqueTaxpayerNumber` - `corporateAddressProof` (**Note:** `documentType` is an additional value in the `requiredFields`) `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "0cb888d9-1d3c-4197-b99b-1c8f96a4678f", "templateId": "cee213af-b9a2-4d35-ae4a-31fdf9ef446b", "template": { "name": "businessRegistrationDocument", "documentType": "document", "type": "document", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Business Registration Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Please submit the latest Registration Document", "status": "RFI_REQUESTED" },{ "rfiHashId": "afcf82d2-e3f1-4031-a115-5530dabcbc59", "templateId": "76796bf6-ca02-4867-b13f-3661a2594180", "template": { "name": "corporateAddressProof", "documentType": "document", "type": "document", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Address Proof Document Type for Business", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Address Proof for Business", "fieldValue": "document", "type": "document" } ] }, "remarks": "Please submit the latest Registration Document", "status": "RFI_REQUESTED" } ``` > `businessRegistrationDocument` and `corporateAddressProof` request body for the Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "0cb888d9-1d3c-4197-b99b-1c8f96a4678f", "businessDetails": { "documentDetails": { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "document": "", "fileName": "BRD.png", "fileType": "image/png" } ] } } }, { "rfiHashId": "afcf82d2-e3f1-4031-a115-5530dabcbc59", "businessDetails": { "documentDetails": { "documentType": "Utility Bill", "document": [ { "document": "", "fileName": "utility.png", "fileType": "image/png" } ] } } } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "cee213af-b9a2-4d35-ae4a-31fdf9ef446b", "template": { "name": "businessRegistrationDocument", "documentType": "document", "type": "document", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Business Registration Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Please submit the latest Registration Document", "status": "RFI_REQUESTED" },{ "templateId": "76796bf6-ca02-4867-b13f-3661a2594180", "template": { "name": "corporateAddressProof", "documentType": "document", "type": "document", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Address Proof Document Type for Business", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Address Proof for Business", "fieldValue": "document", "type": "document" } ] }, "remarks": "Please submit the latest Registration Document", "status": "RFI_REQUESTED" } ``` > `businessRegistrationDocument` and `corporateAddressProof` request body for the Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "cee213af-b9a2-4d35-ae4a-31fdf9ef446b", "businessDetails": { "documentDetails": { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "document": "", "fileName": "BRD.png", "fileType": "image/png" } ] } } }, { "rfiTemplateId": "76796bf6-ca02-4867-b13f-3661a2594180", "businessDetails": { "documentDetails": { "documentType": "Utility Bill", "document": [ { "document": "", "fileName": "utility.png", "fileType": "image/png" } ] } } } ``` ### Other document Compliance agents can request multiple documents in the `otherDocument` RFI. Make sure to enable uploading of multiple documents for this RFI template and send it in the `document` field as an array of objects as shown in the example. `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "b93bac45-4661-4217-944a-081bf7b91b2b", "templateId": "76796bf6-ca02-4867-b13f-3661a2594180", "template": { "name": "otherDocument", "documentType": "document", "type": "document", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Other Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "1. Please submit taxes filed in 2022 and 2023, 2. Please submit Memorandum of Association.", "status": "RFI_REQUESTED" }, { "rfiHashId": "7df27efd-b5e6-4081-a00c-4b42cb895a79", "templateId": "76796bf6-ca02-4867-b13f-3661a2594180", "template": { "name": "otherDocument", "documentType": "document", "type": "document", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Other Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "Please provide No UBO declaration signed by a director.", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "rfiHashId": "b93bac45-4661-4217-944a-081bf7b91b2b", "businessDetails": { "documentDetails": { "documentType": "Utility Bill", "document": [ { "document": "", "fileName": "tax2023.png", "fileType": "image/png" }, { "document": "", "fileName": "tax2022.png", "fileType": "image/png" }, { "document": "", "fileName": "memorandum.png", "fileType": "image/png" } ] } } }, { "rfiHashId": "b93bac45-4661-4217-944a-081bf7b91b2b", "businessDetails": { "documentDetails": { "documentType": "UBO Declaration", "document": [ { "document": "", "fileName": "noUBODeclaratn.png", "fileType": "image/png" } } } } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "76796bf6-ca02-4867-b13f-3661a2594180", "template": { "name": "otherDocument", "documentType": "document", "type": "document", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Other Document", "fieldValue": "document", "type": "document" } ] }, "remarks": "1. Please submit taxes filed in 2022 and 2023, 2. Please submit Memorandum of Association.", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "rfiTemplateId": "76796bf6-ca02-4867-b13f-3661a2594180", "businessDetails": { "documentDetails": { "documentType": "Utility Bill", "document": [ { "document": "", "fileName": "tax2023.png", "fileType": "image/png" }, { "document": "", "fileName": "tax2022.png", "fileType": "image/png" }, { "document": "", "fileName": "memorandum.png", "fileType": "image/png" } ] } } } ``` ## Risk assessment Templates that appear under `riskAssessment` includes: | Template in the response of the Fetch RFI Details API | | :------------------------------------------------------------------------------------ | | [intendedUseOfAccount](#intendeduseofaccount-template-response-fetch-rfi-details-api) | | [transactionCountries](#transactioncountries-template-response-fetch-rfi-details-api) | ### Intended use of account `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "a188dafc-82c7-49fd-a9c7-367b50e61a38", "templateId": "5c68d9e0-6f23-46f5-86d0-02d6cb81d48b", "template": { "name": "intendedUseOfAccount", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Intended Use Of Account", "fieldValue": "intendedUseOfAccount", "type": "data" } ] }, "remarks": "What do you intend to use this account for?", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "a188dafc-82c7-49fd-a9c7-367b50e61a38", "riskAssessmentInfo": { "intendedUseOfAccount": "IU001" } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "5c68d9e0-6f23-46f5-86d0-02d6cb81d48b", "template": { "name": "intendedUseOfAccount", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Intended Use Of Account", "fieldValue": "intendedUseOfAccount", "type": "data" } ] }, "remarks": "What do you intend to use this account for?", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "5c68d9e0-6f23-46f5-86d0-02d6cb81d48b", "riskAssessmentInfo": { "intendedUseOfAccount": "IU001" } } ] } ``` ### Transaction countries `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "9144447e-e63f-4ded-ab17-88c99ed35da2", "templateId": "177b0715-7b64-45b0-ae7e-1c23c812063a", "template": { "name": "transacationCountries", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Payment Corridors", "fieldValue": "transactionCountries", "type": "data" } ] }, "remarks": "List all the countries you are going to transact", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "9144447e-e63f-4ded-ab17-88c99ed35da2", "riskAssessmentInfo": { "transactionCountries": ["US","IN","HK"] } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "177b0715-7b64-45b0-ae7e-1c23c812063a", "template": { "name": "transacationCountries", "type": "data", "rfiType": "corporate", "requiredFields": [ { "fieldLabel": "Payment Corridors", "fieldValue": "transactionCountries", "type": "data" } ] }, "remarks": "List all the countries you are going to transact", "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "177b0715-7b64-45b0-ae7e-1c23c812063a", "riskAssessmentInfo": { "transactionCountries": ["US","IN","HK"] } } ] } ``` ## Stakeholders Templates that appear under `stakeholders` includes: | Templates | | :---------------------------------------------------------------------------------- | | [stakeholderAddress](#stakeholderaddress-template-response-fetch-rfi-details-api) | | [stakeholderIdentity](#stakeholderidentity-template-response-fetch-rfi-details-api) | | [stakeholderreKyc](#stakeholder-rekyc) | ### Stakeholder address `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "1fd4babc-ddd4-4634-bfbc-0444bd74a9da", "templateId": "4e63476f-a704-461a-865e-253cf905bb60", "referenceId": "be4e20fd-2a28-4753-b493-dc49f014a473", "template": { "name": "stakeholderAddress", "documentType": "POA", "type": "document", "rfiType": "stakeholder", "requiredFields": [ { "fieldLabel": "Proof of Address Document Type", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Proof of Address", "fieldValue": "document", "type": "document" } ] }, "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "1fd4babc-ddd4-4634-bfbc-0444bd74a9da", "businessDetails": { "stakeholders": [ { "referenceId": "40262cf7-bda3-4b19-bed3-03cfbb3a2ad3", "stakeholderDetails": { "documentDetails": { "documentType": "Bank Statement", "document": [ { "document": "", "fileName": "STPOA.png", "fileType": "image/png" } ] } } } ] } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "4e63476f-a704-461a-865e-253cf905bb60", "referenceId": "be4e20fd-2a28-4753-b493-dc49f014a473", "template": { "name": "stakeholderAddress", "documentType": "POA", "type": "document", "rfiType": "stakeholder", "requiredFields": [ { "fieldLabel": "Proof of Address Document Type", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Proof of Address", "fieldValue": "document", "type": "document" } ] }, "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "4e63476f-a704-461a-865e-253cf905bb60", "businessDetails": { "stakeholders": [ { "referenceId": "40262cf7-bda3-4b19-bed3-03cfbb3a2ad3", "stakeholderDetails": { "documentDetails": { "documentType": "Bank Statement", "document": [ { "document": "", "fileName": "STPOA.png", "fileType": "image/png" } ] } } } ] } } ] } ``` ### Stakeholder identity `rfiHashId` > Fetch RFI Details response ```json { "rfiHashId": "32efd125-4013-49d8-9303-18e04106fdbc", "templateId": "478b6c22-8fa7-45eb-8498-26e021914121", "referenceId": "904200f4-b192-40c2-8a46-b4ec1c748b7b", "remarks":"Need POI for stakeholder" "template": { "name": "stakeholderIdentity", "documentType": "POI", "type": "document", "rfiType": "stakeholder", "requiredFields": [ { "fieldLabel": "Identity Document Type", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Identity Document Number", "fieldValue": "documentNumber", "type": "data" }, { "fieldLabel": "Identity Document Expiry Date", "fieldValue": "documentExpiryDate", "type": "data" }, { "fieldLabel": "Identity Document", "fieldValue": "document", "type": "document" } ] }, "status": "RFI_REQUESTED" } ``` > Respond to RFI request If the `referenceId` belongs to a corporate stakeholder, use the `businessPartner` object in place of the `stakeholderDetails` object. The remaining part of the body is the same. ```json { "region": "UK", "clientId": "NIM1688219482719", "rfiResponseRequest": [ { "rfiHashId": "32efd125-4013-49d8-9303-18e04106fdbc", "businessDetails": { "stakeholders": [ { "referenceId": "40262cf7-bda3-4b19-bed3-03cfbb3a2ad3", "stakeholderDetails": { "documentDetails": { "documentType": "PASSPORT", "documentNumber": "12345678", "documentExpiryDate": "2024-11-10", "documentIssuanceCountry":"UK", "document": [ { "document": "", "fileName": "STPOI.png", "fileType": "image/png" } ] } } } ] } } ] } ``` `rfiTemplateId` > Fetch RFI Details response ```json { "templateId": "478b6c22-8fa7-45eb-8498-26e021914121", "referenceId": "904200f4-b192-40c2-8a46-b4ec1c748b7b", "remarks":"Need POI for stakeholder" "template": { "name": "stakeholderIdentity", "documentType": "POI", "type": "document", "rfiType": "stakeholder", "requiredFields": [ { "fieldLabel": "Identity Document Type", "fieldValue": "documentType", "type": "data" }, { "fieldLabel": "Identity Document Number", "fieldValue": "documentNumber", "type": "data" }, { "fieldLabel": "Identity Document Expiry Date", "fieldValue": "documentExpiryDate", "type": "data" }, { "fieldLabel": "Identity Document", "fieldValue": "document", "type": "document" } ] }, "status": "RFI_REQUESTED" } ``` > Respond to RFI request ```json { "region": "UK", "clientId": "NIM1688219482719", "caseId": "b8eccc6c-dab2-45ac-9386-ca432e4ae75d", "rfiResponseRequest": [ { "rfiTemplateId": "478b6c22-8fa7-45eb-8498-26e021914121", "businessDetails": { "stakeholders": [ { "referenceId": "40262cf7-bda3-4b19-bed3-03cfbb3a2ad3", "stakeholderDetails": { "documentDetails": { "documentType": "PASSPORT", "documentNumber": "12345678", "documentExpiryDate": "2024-11-10", "documentIssuanceCountry":"UK", "document": [ { "document": "", "fileName": "STPOI.png", "fileType": "image/png" } ] } } } ] } } ] } ``` ### Stakeholder reKyc `rfiHashId` > Fetch RFI Details response ``` { "rfiHashId": "a7b86b3e-809e-4c9b-9ac4-e0a632ade2b8", "templateId": "758f8e8d-f589-468c-9509-268ce67b3075", "referenceId": "5ff7c5a9-e7ed-4a7b-a655-0a83eb246e3a", "template": { "name": "stakeholderreKYC", "type": "data", "rfiType": "stakeholder", "requiredFields": [ { "fieldLabel": "Other Data", "fieldValue": "otherData", "type": "data" } ] }, "remarks": "Please complete the onfido verification: https://integrationspreprod.partners.instarem.com/preprod/compliance/callback/load?referenceNumber=3997dbbf-7f28-4928-9a10-4394b85d5807&token=eyJhQ", "status": "RFI_REQUESTED" } ``` `rfiTemplateId` > Fetch RFI Details response ``` { "templateId": "758f8e8d-f589-468c-9509-268ce67b3075", "referenceId": "5ff7c5a9-e7ed-4a7b-a655-0a83eb246e3a", "template": { "name": "stakeholderreKYC", "type": "data", "rfiType": "stakeholder", "requiredFields": [ { "fieldLabel": "Other Data", "fieldValue": "otherData", "type": "data" } ] }, "remarks": "Please complete the onfido verification: https://integrationspreprod.partners.instarem.com/preprod/compliance/callback/load?referenceNumber=3997dbbf-7f28-4928-9a10-4394b85d5807&token=eyJhQ", "status": "RFI_REQUESTED" } ``` --- # AU Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/au-onboarding - This page contains details about the Australia Know Your Business (KYB) flows and links to the following sub-pages for a quick reference: | Page name | Description | | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | **[AU required parameters](/docs/onboarding/corporate-customers/au-onboarding/required-parameters)** | This page lists the required API parameters of each entity type. | | **[AU required documents](/docs/onboarding/corporate-customers/au-onboarding/required-documents)** | This page contains tables listing the required documents for verification of the business entity, stakeholders, and applicants. | | **[AU position mapping](/docs/onboarding/corporate-customers/au-onboarding/position-mapping)** | This page gives a quick glance at the required positions of each entity type. | | **[AU request examples](/docs/onboarding/corporate-customers/au-onboarding/example-requests)** | This page contains API request examples for AU entities. | Nium offers eKYB and Manual KYB flows for customers in Australia. The eKYB flow is fully automated, allowing corporate customers to be approved within a few minutes of submitting their application, making it the preferred mode for all customers. Reach out to Nium's sales team to configure the eKYB flow for your account. ## eKYB flow The following steps are required to complete the eKYB application. AU Onboarding ### Step 1. Get Public Corporate Details Using Business ID API To start the eKYB process, collect the basic details about the corporate customer from the applicant through an onboarding form, including the `businessRegistrationNumber` and `countryCode`. For a list of valid country codes, see [Currency and country codes](/docs/getting-started/currency-and-country-codes). Then call Nium's [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API. This API returns publicly available information about the corporate customer, which you then display to the customer so they can select and confirm the `businessName` and `businessRegistrationNumber` along with any other optional details. This step is optional and is intended to help the applicant select the right details. This API returns multiple results for a given `businessRegistrationNumber` which you display to your customer and let them select the correct result. If no results are returned, call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API with a full request body. Such applications go through manual review, making the eKYB process not applicable. ### Step 2. Get Onboard Corporate Customer API You need to collect all the details required to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API through an onboarding form and call it with the full request body. #### Applicant KYC Australia supports all three KYC flows, (`E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC`). You need to pass the following parameter in the `businessDetails.applicantDetails.kycMode` object: - `E_KYC` for Australian residents - `E_DOC_VERIFY` for non-Australian residents If required, you can use `Manual_KYC` for non-Australian residents, but those applications go through manual review and cannot be verified in real time. Uploading of documents is mandatory for `MANUAL_KYC` which needs to be sent in the `businessDetails.applicantDetails.documentDetails` object. For details, see [AU required documents for applicants](#applicant-kyc). Upon submission, the `status` in the response of the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API is `IN_PROGRESS`. If any documents are required, the applicant needs to upload them to proceed further. Once done, Nium initiates real-time verification and sends the response via a webhook. The application can be approved at this stage. If it can't be approved, it goes through manual review. Any changes in the`status` is communicated via a webhook. For the next steps based on the response of a webhook, see [Webhooks](/docs/onboarding/corporate-customers#webhooks). #### Applicant E\_DOC\_VERIFY As a response to the Onboard Corp Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirectURL. The applicant then lands on the KYC vendor's page, where he can complete the KYC verification by uploading his proof of identity and proof of address documents with a live selfie. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium. Redirection can result in the following scenarios, based on the below parameters. - `errorCode` - `errorMessage` - `isSuccess` – This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. | Scenario | Expected action | Query parameters in the redirection | | :------------------------------------------------------------- | :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ | | The applicant completes the required steps in the vendor’s UI. | Client needs to wait for the webhook. | `errorCode`: N/A `errorMessage`: N/A `isSuccess`: TRUE | | The document is submitted in the vendor's UI. | KYC Process is complete. Client needs to wait for the webhook. | `errorCode`: R403 `errorMessage`: documentAlreadySubmitted `isSuccess`: FALSE | | The customer provides incorrect data in the vendor's UI. | You ask customer to submit correct data on the vendor's page. | `errorCode`: I400 `errorMessage`: vendorValidationError `isSuccess`: FALSE | | Verification fails at the vendor. | The application goes to manual review. The client needs to wait for webhook. | `errorCode`: R401 `errorMessage`: vendorVerificationFailure `isSuccess`: FALSE | | An internal server error occurs at Nium. | Try after some time or reach out to Nium's support. | `errorCode`: R500 `errorMessage`: internalServerError `isSuccess`: FALSE | | Any unexpected error occurs from the vendor. | Try after some time or reach out to Nium's support. | `errorCode`: I500 `errorMessage`: unexpectedError `isSuccess`: FALSE | | Validation is complete and customer retries the same link. | KYC Process is completed. The client needs to wait for the webhook. | `errorCode`: R606 `errorMessage`: verificationAlreadyCompleted `isSuccess`: FALSE | Based on the scenario, you can implement the next steps as provided in the table above. **Example of a redirect to the client in a successful case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11- f95c315ce83c&isSuccess=true&errorCode=&errorMessage= ``` **Example of a redirect to the client in a failed case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11- f95c315ce83c&errorCode=R408&errorMessage=redirectURLExpired&isSuccess=false ``` For applicants where the `businessDetails.applicantDetails.address.country` is `US`, the applicant's address' `state` needs to be a valid 2 letter state code. Use [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API for acceptable values. When the applicant's `businessDetails.applicantDetails.address.country` is `GB`, the applicant's `postcode` needs to be in the `SW4 6EH` format. #### Stakeholder KYC The `E_KYC` and `MANUAL_KYC` modes are offered for KYC of Individual stakeholders in the eKYB flow in Australia. For stakeholders, you pass `E_KYC` (for AU residents) or `MANUAL_KYC` (for non-AU residents) in `businessDetails.stakeholders.stakeholderDetails.kycMode`. Applications with `MANUAL_KYC` go through manual review and cannot be verified in real-time. The uploading of documents is mandatory for `MANUAL_KYC` which has to be sent in `businessDetails.stakeholders.stakeholderDetails`. See [AU required documents](/docs/onboarding/corporate-customers/au-onboarding/required-documents) for details. #### Upload documents If no results are returned as part of the [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API for the particular `businessRegistrationNumber`, you need to upload documents since Nium doesn't retrieve certain required information from some of its sources. If the [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API returns a match, you generally don't need to upload documents. However, even in this flow, there might be a particular scenario that requires the applicant to provide some documents. Documents can be submitted either of two ways: - As part of the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API - Via the [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) API The [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request is preferred since it uploads one document at a time, which reduces the loading time. This API can be called only while the application is in the `IN_PROGRESS` state. You can use the `remarks` field to list which documents Nium is expecting, in the response of both APIs. The API gateway has a limit of 10 MB for any API request. This makes Upload Document API the preferred way to upload documents since you can upload one document at a time. For the entire list of required documents for manual KYB and eKYB flows, see [AU required documents](/docs/onboarding/corporate-customers/au-onboarding/required-documents). #### Terms and Conditions You must show customers the Nium terms and conditions configured for your `client` resource. You can fetch these specific terms and conditions using our [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions). Customers can only submit the onboarding form once they accept the terms and conditions. To fetch the [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions): 1. Wait for the Onboarding API to return a `customerHashId`. 2. Once returned, call our [Accept Terms and Conditions API](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) and include the `customerHashId`. 3. Show the customer the returned terms and conditions and record their acceptance before allowing them to transact. For more details, see [Terms and Conditions](/docs/onboarding/corporate-customers#terms-and-conditions). ### Wait for webhook response After submission, the `status` in the Onboard Corporate Customer response is `IN_PROGRESS`. The applicant needs to complete both the [Applicant KYC](#applicant-kyc) and [Upload documents](#upload-documents) steps to proceed further. Once done, Nium initiates real-time verification and sends the response via a webhook. The application might be approved at this stage; and if it isn't approved, the application goes through a manual review. Any changes in the `status` is again communicated via a webhook. For the next steps based on the response of the webhook, see [Webhooks](/docs/onboarding/corporate-customers#webhooks). ## Manual KYB flow The `MANUAL_KYB` process is similar to eKYB with one exception, documents are mandatory in all cases. AU Onboarding 1. The manual KYB flow requires the submission of business documents. You can send them via the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API or using the [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request under the `businessDetails.documentDetails` section. Nium doesn't initiate verification until all required documents are submitted.\ The [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) API is preferred since it can upload one document at a time, which reduces loading times. 2. The applicant KYC is the same as the eKYB flow. For details on implementing `E_DOC_VERIFY`, see [Applicant E\_DOC\_VERIFY](#applicant-e-doc-verify). 3. Only the `MANUAL_KYC` process is offered for individual stakeholders. You need to pass `MANUAL_KYC` in the `businessDetails.applicantDetails.kycMode` object. You need to upload your documents. Send the information in the `businessDetails.stakeholders.stakeholderDetails.documentDetails\` object.\ For details, see [AU required documents](/docs/onboarding/corporate-customers/au-onboarding/required-documents#stakeholders). 4. Terms and Conditions flow is same as mentioned in the eKYB flow. Once the API is submitted, the next steps are the same as those in the eKYB process, except that all applications are required to go through the manual review. For the next steps to take to onboard your customer, see the response returned in the [webhook](/docs/onboarding/corporate-customers#webhooks). --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/au-onboarding/required-parameters The API fields shown on this page are relevant to Australia only. To see the full payload, refer to the Onboard Corporate Customer API Reference. The API fields shown on this page are relevant to Australia only. To see the full payload, refer to the [Onboard Corporate Customer API Reference](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). All fields have a maximum limit of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `region` | The country or geographic region where the corporate end customer is located and is onboarded. e.g. To onboard a US-based customer, use the `US` value. | Yes | | [businessDetails](#businessdetails-object) | An object that accepts business details about the corporate customer. | Yes | | [riskAssessmentInfo](#riskassessmentinfo-object) | An object that contains the risk assessment information. | Yes | | [deviceDetails](#devicedetails-object) | An object that contains information about the customer's device and IP address. | Yes | | [`expectedAccountUsage`](#expectedAccountUsage) | Describes how the customer expects to use the account. | Yes | | [`natureOfBusiness`](#natureOfBusiness) | Contains information about the nature of the business, such as the `industrySector`. | Yes | | [tags](#tags-object) | An object that contains the tags. | No | | `clientId` | The Nium client ID of the customer. Returned in the response to the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request. This field is required to restart onboarding and the KYB process. | Yes | | `customerHashId` | This field accepts the unique customer identifier generated at the time of customer creation. It's received in the response to the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes | ## Request parameters The below Request parameters refer to the `businessType` fields page: | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :-------------------------------------------- | :------------------------------------------------- | :------------------------------------ | | `ASSOCIATION` `PRIVATE_COMPANY` `SOLE_TRADER` | `GOVERNMENT_ENTITY` `PARTNERSHIP` `PUBLIC_COMPANY` | `REGULATED_TRUST` `UNREGULATED_TRUST` | ## `businessDetails` object An object that contains business details about the corporate customer. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :-------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `referenceId` | The universally unique identifier (UUID) of the business entity that Nium uses to identify the `businessDetails` entity. If it's not provided, Nium generates one. The UUID is used to respond to a request for information (RFI) or to upload required documents for the business entity. | Optional | Optional | Optional | | `businessName` | The name a corporate customer is registered under. | Required | Required | Required | | `businessRegistrationNumber` | The business registration number. This fields accepts only nine digits when `businessType` is `PRIVATE_COMPANY` or `PUBLIC_COMPANY` and only 11 digits for any other `businessType`. | Required | Required | Required | | `tradeName` | Another name that the corporate customer uses to do business under, which is different than their licensed business name. | Optional | Optional | Optional | | `website` | The corporate customer's website. | Optional | Optional | Optional | | `businessType` | The legal entity type of the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `trusteeName` | The full name of the trustee. | N/A | N/A | Optional | | `settlorName` | The full name of the trust settlor. **Note:** This field is optional for, `UNREGULATED_TRUST` and not applicable for `REGULATED_TRUST`. | N/A | N/A | Optional \* | | [partnershipDetails](#partnershipdetails-object) | An object that contains the partnership details. **Note:** This field is optional for a `PARTNERSHIP` and not required for other business types. | N/A | Optional \* | N/A | | [associationDetails](#associationdetails-object) | An object that contains the association details. **Note:** This field is required for an `ASSOCIATION`. | Required \* | N/A | N/A | | [legalDetails](#businessdetailslegaldetails-object) | An object that contains the legal details. | Required | Required | Required | | [regulatoryDetails](#regulatorydetails-object) | The regulatory details about the corporate customer. | N/A | N/A | Required | | [addresses](#addresses-object) | An object that contains the registered and business addresses of the corporate customer. | Required | Required | Required | | [documentDetails](#documentdetails-object) | An array of objects that contains the business documents. **Note:** This is required for Manual KYB and for eKYB when the `businessDetails.businessType` is one of the following: `ASSOCIATION` `PARTNERSHIP` `REGULATED_TRUST` `UNREGULATED_TRUST`. | Required \* | Required \* | Required | | [stakeholders](#stakeholders-array) | An array of objects that contains the individual and corporate stakeholders of the corporate customer. | Required \* | Required \* | Required \* | | [applicantDetails](#applicantdetails-object) | An object that contains the applicant's details. | Required | Required | Required | | [additionalInfo](#riskassessmentinfo-object) | An object that contains additional information about the business. | Required | Required | Required | ### `partnershipDetails` object An object within the `businessDetails` object that contains the partnership details. - This object is required if `businessDetails.businessType = PARTNERSHIP`. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | ---------------- | ------------------------------------------------- | --------------------------------- | ------------------------------- | ---------------------------------- | | `partnerName` | The complete name of the partner. | N/A | Optional \* | N/A | | `partnerCountry` | The country where the partnership is established. | N/A | Optional \* | N/A | | `partnerState` | The state where the partnership is established. | N/A | Optional \* | N/A | ### `associationDetails` object An object within the `businessDetails` object that contains the association details. - This object is required if `businessDetails.businessType = ASSOCIATION`. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | ------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ---------------------------------- | | `associationName` | The complete name of the association. | Required\* | N/A | N/A | | `associationNumber` | The association number as issued by the applicable state or territory. Should be alphanumeric. | Required\* | N/A | N/A | | `associationChairPerson` | The full name of the association chair, secretary, or treasurer. | Required\* | N/A | N/A | ### `businessDetails.legalDetails` object An object within the `businessDetails` object that contains the corporate customer's legal details. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `registeredDate` | The date the business is registered entered in the `YYYY-MM-DD` format. Registered date cannot be a past date. | Required | Required | Required | | `registeredCountry` | The country where the business is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `listedExchange` | The exchange where the business is publicly listed. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. **Note:** This field is required for a `PUBLIC_COMPANY`. | N/A | Required \* | N/A | | `legislationName` | The name under which the entity is formed. **Note:** This field is optional if `businessDetails.businessType` is `GOVERNMENT_ENTITY` and not applicable to others. | N/A | Optional \* | N/A | | `legislationType` | The legislation type under which the government entity is formed. **Note:** This field is optional if `businessDetails.businessType` is `GOVERNMENT_ENTITY` and not applicable to others. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | N/A | Optional \* | N/A | ### `regulatoryDetails` object An object within the `businessDetails` object that contains the regulatory details about the corporate customer. This object is required if `businessDetails.businessType` is `REGULATED_TRUST` or `UNREGULATED_TRUST`. | Property | Description | Regulated trust | Unregulated trust | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------: | :---------------: | | `regulatedTrustType` | The regulated trust type detail. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. This field is an array | Required | N/A | | `unregulatedTrustType` | The unregulated trust type detail. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. This field is an array. | N/A | Required | ### `addresses` object An object within the `businessDetails` object that contains one or more business addresses. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | [registeredAddress](#registeredaddress-object) | An object that contains the address where the business is registered. | Required | Required | Required | | [businessAddress](#businessaddress-object) | An object that contains the address where the business is mainly conducted, if different than the registered address. **Note:** This is required if `isSameBusinessAddress = No` | Required \* | Required \* | Required \* | #### `registeredAddress` object An object within the `businessDetails.addresses` object that contains the address details where the corporate customer is registered. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ---------------------------------- | | `addressLine1` | The first address line of the registered business. | Required | Required | Required | | `addressLine2` | The second address line of the registered business. | Optional | Optional | Optional | | `city` | The city where the corporate customer is registered. | Required | Required | Required | | `state` | The state where the corporate customer is registered. | Required | Required | Required | | `country` | The country where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `postcode` | The postal code where the corporate customer is registered. | Required | Required | Required | #### `businessAddress` object An object within the `businessDetails.addresses` object that contains the address details about the principal place of business only when the registered address is different. - This object is required if `businessDetails.additionalInfo.isSameBusinessAddress = No`. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `addressLine1` | The first address line of the registered business. | Required | Required | Required | | `addressLine2` | The second address line of the registered business. | Optional | Optional | Optional | | `city` | The city where the corporate customer is registered. | Required | Required | Required | | `state` | The state where the corporate customer is registered. | Required | Required | Required | | `country` | The country where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `postcode` | The postal code where the corporate customer is registered. | Required | Required | Required | ### `documentDetails` object An array of objects within the `businessDetails` object that contains one or more business documents. - This object is required if either is true: - Manual KYB is used. - eKYB is used and `businessDetails.businessType` is one of the following: - `ASSOCIATION` - `PARTNERSHIP` - `REGULATED_TRUST` - `UNREGULATED_TRUST` | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `documentType` | The type of business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required | | [document](#document-object) | An array of objects that contains a copy of the document. | Required \* | Required \* | Required | #### `document` object An array of objects within the `businessDetails.documentDetails` object. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------- | :------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `fileName` | The name of the file. | Required \* | Required \* | Required | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \* | Required \* | Required | | `document` | The file as a base64 encoded string. | Required \* | Required \* | Required | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `isSameBusinessAddress` | This field accepts `Yes` or `No` to indicate if the principal place of business is the same or different from the registered business entity address. | Optional | Optional | Optional | ### `stakeholders` array An array of objects within the `businessDetails` object that contains information about one or many stakeholders. For every stakeholder object, you need to send either the `stakeholderDetails` or the `businessPartner` parameters. | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | | :--------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- | :-------------------------------- | ----------- | | `referenceId` | The UUID associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | Optional | Optional | Optional | | [stakeholderDetails](#businessdetails-stakeholders-stakeholderdetails) | An object that contains the details about the individual stakeholders. | Required \* | Required \* | Required \* | | [businessPartner](#businessdetails-stakeholders-businesspartner) | An object that contains the details about the corporate stakeholders, if available. **Note:** This is required only if a business partner exists. | Required \* | Required \* | Required \* | #### `stakeholderDetails` object An object within the `stakeholders` object that contains the details about an individual stakeholder. - This object is required if individual stakeholder for the following scenarios: - The Nium client is configured for Manual KYB.˙ - The Nium client is configured for eKYB and `businessDetails.businessType` is one of the following:˙ - `ASSOCIATION`˙ - `PARTNERSHIP`˙ - `SOLE_TRADER`˙ - `UNREGULATED_TRUST` and `REGULATED_TRUST`˙ | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `kycMode` | The KYC mode for verifying the individual stakeholder. Valid values are `E_KYC` and `MANUAL_KYC`. | Required | Required | Required | | `firstName` | The given name of the individual stakeholder. | Required \* | Required \* | Required \* | | `middleName` | The middle name of the individual stakeholder. | Optional | Optional | Optional | | `lastName` | The last name of the individual stakeholder. | Required \* | Required \* | Required \* | | `nationality` | The nationality of the individual stakeholder. | Required \* | Required \* | Required \* | | `dateOfBirth` | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. | Required \* | Required \* | Required \* | | [professionalDetails](#professionaldetails-array) | An array of objects that contains the individual stakeholder's professional details. | Required \* | Required \* | Required \* | | [address](#address-object) | An object that contains the residential address of the individual stakeholder. | Required \* | Required \* | Required \* | | [documentDetails](#documentdetails-object-1) | An array of objects that contains the document details about the individual stakeholder. **Note:** This is required if `kycMode = MANUAL_KYC`. | Required \* | Required \* | Required \* | ##### `stakeholderDetails.professionalDetails` array An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's professional details. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `position` | The position of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | ##### `applicantDetails.address` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------ | :---------------------------- | :-------------------------------- | | `addressLine1` | The first address line of the individual stakeholder's residential address. If `kycMode = E_KYC` then the following needs to be passed in this field as comma-separated values: unit number (if available) street number street name | Required \* | Required \* | Required \* | | `addressLine2` | The second address line of the individual stakeholder's residential address. **Note:** If `kycMode = E_KYC` then `streetType` needs to be passed in this field. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | | `city` | The city or suburb of the individual stakeholder. If `kycMode = E_KYC` then suburb needs to be passed in this. | Required \* | Required \* | Required \* | | `state` | The state of the individual stakeholder's residential address. | Required \* | Required \* | Required \* | | `country` | The country of the individual stakeholder's residential address. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | | `postcode` | The postal code of the individual stakeholder's residential address. | Required \* | Required \* | Required \* | ##### `stakeholderDetails.documentDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's document details. \* Required if the `kycMode` **MANUAL\_KYC**. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | | `documentNumber` | The ID number for the given document type. | Required \* | Required \* | Required \* | | `documentIssuanceCountry` | The country that issued the business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. Date of expiry cannot be a past date. | Required \* | Required \* | Required \* | | [document](#document-object-1) | A copy of the document. | Required \* | Required \* | Required \* | ##### `document` An array of object within the `businessDetails.stakeholders.stakeholderDetails.documentDetails` object that contains a copy of the document. - Required if the `kycMode` **MANUAL\_KYC**. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------ | :---------------------------- | :-------------------------------- | | `fileName` | The name of the file. | Required \* | Required \* | Required \* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \* | Required \* | Required \* | | `document` | The document saved as a base64 encoded string. | Required \* | Required \* | Required \* | #### `businessPartner` An object within the `businessDetails.stakeholders` object that contains the business details about the corporate stakeholder. \* This object is required if a corporate stakeholder exists for any `businessType` for both Manual KYB and eKYB. | Property | Description | Association | Government Partnership Public | Regulated trust Unregulated trust | | :-------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- | :---------------------------- | :-------------------------------- | | `businessName` | The registered business name of the corporate stakeholder. | Required \* | Required \* | Required \* | | `businessRegistrationNumber` | The business registration number. | Required \* | Required \* | Required \* | | `businessType` | The legal entity type of the business. **Note:** For Manual KYB, this field is not applicable; for eKYB this field is required for `UNREGULATED_TRUST` and `REGULATED_TRUST` Valid values are only: `PUBLIC_COMPANY` `PRIVATE_COMPANY` `GOVERNMENT_ENTITY` | N/A | N/A | Required \* | | `businessEntityType` | The position of the corporate stakeholder in the company. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | | [legalDetails](#businessdetailslegaldetails-object) | The corporate stakeholder's legal details. | Required \* | Required \* | Required \* | ##### `businessPartner.legalDetails` object An object within the `businessDetails.stakeholders.businessPartner` object that contains the corporate stakeholder's legal details. | Property | Description | Association Sole trader Trust | Government Private Public | LLP | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- | :------------------------ | :---------- | | `registeredCountry` | The country where the corporate stakeholder is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | ### `applicantDetails` object An object within the `businessDetails` object that contains details about the applicant. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------ | :---------------------------- | :-------------------------------- | | `referenceId` | The UUID associated with the applicant and the applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents. | Optional | Optional | Optional | | `kycMode` | The KYC mode for verifying the identity of the applicant. Valid values are `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC`. | Required | Required | Required | | `firstName` | The first name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Required | Required | Required | | `middleName` | The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Optional | Optional | Optional | | `lastName` | The last name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Required | Required | Required | | `nationality` | The nationality of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `dateOfBirth` | The date on which the applicant was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. Applicant cannot be below 18 years of age. | Required | Required | Required | | [professionalDetails](#professionaldetails-array-1) | An array of objects that contains the applicant's professional details. | Required | Required | Required | | [address](#address-object-1) | An object that contains the applicant's residential address. | Required | Required | Required | | [contactDetails](#contactdetails-object) | The contact details of the applicant. | Required | Required | Required | | [documentDetails](#document-object-1) | An array of objects that contains the applicant's document details. **Note:** This object is required only for `E_DOC_VERIFY` and `MANUAL_KYC`. In `E_KYC`, `LOA` is required if the applicant isn't a `DIRECTOR`/ `UBO`. | Required \* | Required \* | Required \* | #### `applicantDetails.professionalDetails` array An array of objects within the `businessDetails.applicantDetails` object to contain the professional details about the applicant. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `position` | The position of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | #### `applicantDetails.address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `addressLine1` | The first address line of the applicant. The maximum character length is 40. If `kycMode = E_KYC` then the following needs to be passed in this field as comma-separated values: unit number (if available) street number street name | Required | Required | Required | | `addressLine2` | The second address line of the applicant. The maximum character length is 40. If `kycMode = E_KYC` then `StreetType` needs to be passed in this field. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `city` | The city or suburb of the applicant. The maximum character length is 20. If `kycMode = E_KYC` then suburb needs to be passed in this field. | Required | Required | Required | | `state` | The state of the applicant. The maximum character length is 30. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `country` | The country where the applicant resides. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `postcode` | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. | Required | Required | Required | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object to contain the applicant's contact information. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `email` | The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See [Email regex](/docs/developers/nium-api#regular-expression-for-email). | Required | Required | Required | | `countryCode` | The country code of the applicant's phone number. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `contactNo` | The applicant's phone number. The maximum length is 20 numeric characters. | Required | Required | Required | #### `usinessDetails.applicantDetails.documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. \* This object is required if `kycMode` is `MANUAL_KYC` or `E_DOC_VERIFY`. In `E_KYC`, `LOA` is required if the applicant isn't a `DIRECTOR`/ `UBO`. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | | `documentNumber` | The ID number for the given document type. | Required \* | Required \* | Required \* | | `documentIssuanceCountry` | The country that issued the business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \* | Required \* | Required \* | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. Date of expiry cannot be a past date. | Required \* | Required \* | Required \* | | [document](#document-object) | An array of objects that contains a copy of the document. **Note:** This object is required only for `MANUAL_KYC`. In `E_KYC` or `E_DOC_VERIFY`, `LOA` is required if the applicant isn't a `DIRECTOR`/ `UBO`. | Required \* | Required \* | Required \* | ##### `documentDetails.document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains the document copy. \* Required if the `kycMode` **MANUAL\_KYC**. In `E_KYC` or `E_DOC_VERIFY`, `LOA` is required if the applicant isn't a `DIRECTOR`/ `UBO`. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------ | :---------------------------- | :-------------------------------- | | `fileName` | The name of the file. | Required \* | Required \* | Required \* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \* | Required \* | Required \* | | `document` | The document saved as a base64 encoded string. The maximum size is 5 MB. | Required \* | Required \* | Required \* | ## `riskAssessmentInfo` object An object that contains the following details that are required to determine a corporate customer's risk profile. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------- | :-------------------------------- | | `totalEmployees` | The corporate customer's total number of employees. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `annualTurnover` | The corporate customer’s annual turnover. If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `industrySector` | The corporate customer's industry sector. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `countryOfOperation` | An array of countries the corporate customer operates in. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `transactionCountries` | An array of countries where the transactions occur. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `intendedUseOfAccount` | The customer's intended use of the account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | ## `deviceDetails` object This object contains the information about the customer's device and IP address where the onboarding request originated. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ---------------------------------- | | `countryIP` | Country of the IP address e.g. `US`. Use [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) for valid values. | Required | Required | Required | | `deviceInfo` | Information of the device e.g. `Mac OS`. | Required | Required | Required | | `ipAddress` | IP address of the device e.g. `45.48.241.198`. | Required | Required | Required | | `sessionId` | A unique identifier for the session, generated by your application. | Required | Required | Required | ## `tags` object This object contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | :------- | :------------------------------------------------------------------------------ | :------------------------------ | :---------------------------- | :-------------------------------- | | `key` | The name of the tag. The maximum character length is 128. Key should be unique. | Optional | Optional | Optional | | `value` | The value of the tag. The maximum character length is 256. | Optional | Optional | Optional | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/corporate-customers/au-onboarding/required-documents This page outlines the documents required for stakeholders, applicants, and various business types to onboard a corporate customer registered in Australia. ## Business details The following documents are required as part of the Know Your Business (KYB) identification and verification process. | `businessType` | Manual KYB | eKYB | | :------------------------------------------------------------------- | :-------------------------- | :----------------- | | `GOVERNMENT_ENTITY` `PRIVATE_COMPANY` `PUBLIC_COMPANY` `SOLE_TRADER` | `BUSINESS_REGISTRATION_DOC` | N/A | | `ASSOCIATION` | `ASSOCIATION_DEED` | `ASSOCIATION_DEED` | | `PARTNERSHIP` | `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | | `REGULATED_TRUST` `UNREGULATED_TRUST` | `TRUST_DEED` | `TRUST_DEED` | ## Stakeholders AU resident individual stakeholders need to use the `kycMode`= `E_KYC`. `kycMode`=`MANUAL_KYC` should be passed for non-residents. ### Manual KYC When `kycMode = MANUAL_KYC` the following documents need to be submitted. > ⚠️ IMPORTANT > > If the document doesn't contain an address, you need to submit an [Acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) which can verify the address with `documentType = PROOF_OF_ADDRESS`. > > If this additional document is not submitted, the compliance agent will raise an RFI for `stakeholderAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | Field name | Passport | National Id | Driver's license | Additional Document if the first document doesn't contain an address | | :------------------------ | :-------------------- | :------------ | :--------------- | :------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVER_LICENCE` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | | `documentExpiryDate` | Yes | Yes | Yes | No | | `document.fileName` | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | Yes | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. See [Letter Of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for suggested format of LOA in case you do not have one. **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport, Medicare Cards, or Driver's License. ## Applicants Nium offers `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC` modes for applicant KYC in Australia. - `E_KYC` is applicable for AU residents. No documents are required if the applicant is a director. Letter of Authorization is required to be uploaded if the applicant isn't a director. - `E_DOC_VERIFY` is applicable for non-AU residents. Applicant needs to complete KYC using the redirect URL. Document details need to be passed for `E_DOC_VERIFY` and upload of document files isn't required. - `MANUAL_KYC` required document details along with upload of document files. ### Manual KYC Every individual applicant needs to submit one of the following information when `kycMode = MANUAL_KYC`. > ⚠️ IMPORTANT > > If the document doesn't contain an address, you need to submit an [Acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) which can verify the address with `documentType = PROOF_OF_ADDRESS`. > > If this additional document is not submitted, the compliance agent will raise an RFI for `applicantAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | Field name | Passport | National Id | Drivers license | Letter Of Authorization, if applicant is not a `DIRECTOR` or `UBO` | Additional document if the first document doesn't contain an address | | :------------------------ | :-------------------- | :------------ | :--------------- | :------------------------------------------------------------------ | :------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVER_LICENCE` | `LOA` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | No | | `documentExpiryDate` | Yes | Yes | Yes | No | No | | `document.fileName` | Yes | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | Yes | | `document.document` | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | Every individual applicant needs to submit one of the following information when `kycMode = E_DOC_VERIFY` | Field name | Passport | National Id | Drivers license | Letter Of Authorization, if applicant is not a `DIRECTOR` or `UBO` | | :------------------------ | :-------------------- | :------------ | :--------------- | :------------------------------------------------------------------ | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVER_LICENCE` | `LOA` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | | `documentExpiryDate` | Yes | Yes | Yes | No | | `document.fileName` | No | No | No | Yes | | `document.fileType` | No | No | No | Yes | | `document.document` | No | No | No | Yes | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. See [Letter Of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for the suggested format of `LOA` in case you do not have one. **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport, National Id, or Driver's License. ## Acceptable documents for `PROOF_OF_ADDRESS` | Individual stakeholder or applicant | Business details | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | | Utility bills (gas, electric, internet, phone) Financial records (bank statement, mortgage statement) Life, health, or other insurance statement (auto, home, boat) Medical records (doctor, hospital, or clinical) Pay-slip Government-issued letter | Utility bills (gas, electric, internet, phone) Financial records (bank or mortgage statement) Government-issued letter | **NOTE**: The above documents are in addition to the standard documents mentioned in Business, Stakeholder, or Applicant section. These can be passed under the `documentType` `PROOF_OF_ADDRESS`. The above documents cannot be more than 90 days old when submitting. --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/au-onboarding/position-mapping | Business entity type | DIRECTOR | MEMBERS | PARTNER | REPRESENTATIVE | SETTOR | TRUSTEE | UBO | SHAREHOLDER | SIGNATORY | EXECUTOR | PROTECTOR | | Business entity type | `DIRECTOR` | `MEMBERS` | `PARTNER` | `REPRESENTATIVE` | `SETTOR` | `TRUSTEE` | `UBO` | `SHAREHOLDER` | `SIGNATORY` | `EXECUTOR` | `PROTECTOR` | | -------------------- | :--------: | :-------: | :-------: | :--------------: | :------: | :-------: | :---: | :------------ | :---------- | :--------- | :---------- | | `ASSOCIATION` | | Yes | | Yes | | | Yes | Yes | Yes | | | | `GOVERNMENT_ENTITY` | Yes | | | Yes | | | Yes | Yes | Yes | | | | `PARTNERSHIP` | Yes | | Yes | | | | Yes | Yes | Yes | | | | `PRIVATE_COMPANY` | Yes | | | Yes | | | Yes | Yes | Yes | | | | `PUBLIC_COMPANY` | Yes | | | Yes | | | Yes | Yes | Yes | | | | `REGULATED_TRUST` | | | | | Yes | Yes | Yes | Yes | Yes | | | | `SOLE_TRADER` | Yes | | | Yes | | | Yes | Yes | Yes | | | | `UNREGULATED_TRUST` | | | | | Yes | Yes | Yes | Yes | Yes | Yes | Yes | A **Yes** value means that position can be passed for that `businessType`. A blank table cell means that position is not applicable for that `businessType`. - Use `REPRESENTATIVE` as a position for chair, secretary, treasurer of an Association. - Some `PARTNERSHIP`s have a board of directors, `DIRECTOR` can be added as a position in such cases - Sometimes `PRIVATE` and `PUBLIC` companies do not have an identifiable `UBO`, in such cases `SHAREHOLDER` can be passed as position along with share% Multiple positions in the `professionalDetails` array object as shown below: ```json "professionalDetails": [ { "position": "REPRESENTATIVE" }, { "position": "UBO", "sharePercentage": "50%" }, { "position": "SIGNATORY" } ``` --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/au-onboarding/example-requests To onboard your entity, you can call the Onboard Corporate Customer API. For an example call that you can customize with your information, see: To onboard your entity, you can call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. For an example call that you can customize with your information, see: - [Private companies](#private) - [Unregulated trusts](#unregulated-trust) - [Public companies](#public) - [Simulate scenarios in the eKYB flow](#simulate-scenarios-ekyb-flow) ## Private companies The following is an API request example call where `businessType = PRIVATE_COMPANY`. ```json { "region": "AU", "businessDetails": { "businessName": "Stocast Pvt. Ltd.", "businessType": "PRIVATE_COMPANY", "businessRegistrationNumber": "113400250", "website": "www.stocast.com", "legalDetails": { "registeredCountry": "AU", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "302, 78, Woodlands Avenue", "addressLine2": "AVE", "city": "Parramatta", "state": "NSW", "country": "AU", "postcode": "2150" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD.png", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Arijit", "lastName": "Singh aab", "dateOfBirth": "1947-02-15", "nationality": "AU", "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "AU", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "123456009", "document": [ { "fileName": "nationalidfront", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessType": "REGULATED_TRUST", "businessEntityType": "EXECUTOR", "businessName": "Ace Group aab", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "AU", "registrationType": "ABN", "registeredDate": "2019-08-10" }, "regulatoryDetails": { "regulatedTrustType": [ "TT009" ] } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Sachin", "lastName": "Ten aab", "dateOfBirth": "1992-08-09", "nationality": "AU", "professionalDetails": [ { "position": "SETTLOR" } ], "contactDetails": { "countryCode": "AU", "contactNo": "733722664", "email": "jomooo014_9@rairfl.com" }, "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "postcode": "3207", "country": "AU" }, "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "A1111111", "documentIssuanceCountry": "AU" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN", "US" ], "totalEmployees": "EM009", "annualTurnover": "AU011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "transactionCountries":[ "IN", "US", "CA" ] } } ``` ## Unregulated trusts The following is an API request example call where `businessType = UNREGULATED_TRUST`. ```json { "region": "AU", "businessDetails": { "businessName": "COPEN CHARITABLE TRUST23", "businessType": "UNREGULATED_TRUST", "businessRegistrationNumber": "11100000342", "website": "www.copen.com", "trusteeName": "KATIE PATTERSON", "settlorName": "MICHAEL PATTERSON", "legalDetails": { "registeredCountry": "AU", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "302, 78, Woodlands Avenue", "addressLine2": "AVE", "city": "Parramatta", "state": "NSW", "country": "AU", "postcode": "2150" } }, "regulatoryDetails": { "unregulatedTrustType": [ "TT002", "TT005" ] }, "documentDetails": [ { "documentType": "TRUST_DEED", "document": [ { "fileName": "TrustDeed.png", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "MAXWELL", "lastName": "PLANCK", "dateOfBirth": "1947-02-15", "nationality": "AU", "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "AU", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "321456009", "document": [ { "fileName": "nationalid", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessType": "REGULATED_TRUST", "businessEntityType": "DIRECTOR", "businessName": "Plushie Corp", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "AU", "registrationType": "ABN", "registeredDate": "2019-08-10" }, "regulatoryDetails": { "regulatedTrustType": [ "TT009" ] } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "KATHERINE", "lastName": "JOHANSON", "dateOfBirth": "1992-08-09", "nationality": "AU", "professionalDetails": [ { "position": "REPRESENTATIVE" } ], "contactDetails": { "countryCode": "AU", "contactNo": "733722664", "email": "katherine@copen.com" }, "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "postcode": "3207", "country": "AU" }, "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "329847234", "documentIssuanceCountry": "AU" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN", "US" ], "totalEmployees": "EM009", "annualTurnover": "AU011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "transactionCountries":[ "IN", "US", "CA" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Public companies The following is an API request example call where `businessType = PUBLIC_COMPANY`. ```json { "region": "AU", "businessDetails": { "businessName": "Hell's Kitchen Chain4 of Restaurants", "businessType": "PUBLIC_COMPANY", "businessRegistrationNumber": "120000350", "website": "www.hellskitchen.com", "legalDetails": { "registeredCountry": "AU", "registeredDate": "2021-08-10", "listedExchange": "EX098" }, "addresses": { "registeredAddress": { "addressLine1": "302, 78, Woodlands Avenue", "addressLine2": "AVE", "city": "Parramatta", "state": "NSW", "country": "AU", "postcode": "2150" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD.png", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "MAX", "lastName": "COOK", "dateOfBirth": "1947-02-15", "nationality": "AU", "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "AU", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "123456009", "document": [ { "fileName": "medicare_card", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessType": "REGULATED_TRUST", "businessEntityType": "DIRECTOR", "businessName": "Ace Group", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "AU", "registrationType": "ABN", "registeredDate": "2019-08-10" }, "regulatoryDetails": { "regulatedTrustType": [ "TT009" ] } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "JONATHAN", "lastName": "PLANCK", "dateOfBirth": "1992-08-09", "nationality": "AU", "professionalDetails": [ { "position": "REPRESENTATIVE" } ], "contactDetails": { "countryCode": "AU", "contactNo": "733722664", "email": "jonathan@hellskitchen.com" }, "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "postcode": "3207", "country": "AU" }, "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "329847234", "documentIssuanceCountry": "AU" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN", "US" ], "totalEmployees": "EM009", "annualTurnover": "AU011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "transactionCountries":[ "IN", "US", "CA" ] } } ``` ## Simulate scenarios in the eKYB flow If you are using eKYB flow for the AU region, you can generate the following scenarios by using the below steps with the example `businessRegistrationNumber` (BRN) in the following table. | Simulated scenario | Condition | Example BRN | | :---------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | | [Auto-approval](#request-example-auto-approval) | BRN Contains `101` and `applicantDetails.contactDetails.contactNo` starts with `91` | `101324536`, `234101456`, `12101B325` `contactNo`: `91092345`, `913332134` | | [Action required](#request-example-action-required) | Contains `103` | `102324536`, `234102456`, `12102B325` | | [Completing applicant E\_DOC\_VERIFY](#completing-applicant-edocverify) | Pattern on `applicantDetails.contactDetails.contactNo` | | **Step 1:** Call the [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API using the Business Registration Number and Region according to the scenario you want to test. You receive multiple businesses in the response. Pick the one with with matching `businessRegistrationNumber`. In this response, the `businessName` is always returned as `EBL Disability Services Inc.` for any of the `businessRegistrationNumber` mentioned in the table. This behavior is only in the sandbox; the accurate name appears in production. **Step 2:** Use the example requests in the table and call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. ### Request example: auto approval For the description of this scenario, see [Auto Approval Scenario](/docs/onboarding/corporate-customers/using-the-sandbox) ```json { "region": "AU", "businessDetails": { "businessName": "Stocast Pvt. Ltd.", "businessType": "PRIVATE_COMPANY", "businessRegistrationNumber": "101340025", "website": "www.stocast.com", "legalDetails": { "registeredCountry": "AU", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "302, 78, Woodlands Avenue", "addressLine2": "AVE", "city": "Parramatta", "state": "NSW", "country": "AU", "postcode": "2150" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD.png", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Arijit", "lastName": "Singh aab", "dateOfBirth": "1947-02-15", "nationality": "AU", "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "AU", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO" } ] } }, { "businessPartner": { "businessType": "REGULATED_TRUST", "businessEntityType": "EXECUTOR", "businessName": "Ace Group aab", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "AU", "registrationType": "ABN", "registeredDate": "2019-08-10" }, "regulatoryDetails": { "regulatedTrustType": [ "TT009" ] } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Sachin", "lastName": "Ten aab", "dateOfBirth": "1992-08-09", "nationality": "AU", "professionalDetails": [ { "position": "SETTLOR" } ], "contactDetails": { "countryCode": "AU", "contactNo": "913722664", "email": "jomooo014_9@rairfl.com" }, "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "postcode": "3207", "country": "AU" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN", "US" ], "totalEmployees": "EM009", "annualTurnover": "AU011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "transactionCountries":[ "IN", "US", "CA" ] } } ``` ### Request example: action required For the description of this scenario, see [Action required scenario](/docs/onboarding/corporate-customers/using-the-sandbox#action-required) ```json { "region": "AU", "businessDetails": { "businessName": "Stocast Pvt. Ltd.", "businessType": "PRIVATE_COMPANY", "businessRegistrationNumber": "110321340", "website": "www.stocast.com", "legalDetails": { "registeredCountry": "AU", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "302, 78, Woodlands Avenue", "addressLine2": "AVE", "city": "Parramatta", "state": "NSW", "country": "AU", "postcode": "2150" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD.png", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Arijit", "lastName": "Singh aab", "dateOfBirth": "1947-02-15", "nationality": "AU", "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "AU", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO" } ] } }, { "businessPartner": { "businessType": "REGULATED_TRUST", "businessEntityType": "EXECUTOR", "businessName": "Ace Group aab", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "AU", "registrationType": "ABN", "registeredDate": "2019-08-10" }, "regulatoryDetails": { "regulatedTrustType": [ "TT009" ] } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Sachin", "lastName": "Ten aab", "dateOfBirth": "1992-08-09", "nationality": "AU", "professionalDetails": [ { "position": "SETTLOR" } ], "contactDetails": { "countryCode": "AU", "contactNo": "913722664", "email": "jomooo014_9@rairfl.com" }, "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "postcode": "3207", "country": "AU" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN", "US" ], "totalEmployees": "EM009", "annualTurnover": "AU011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "transactionCountries":[ "IN", "US", "CA" ] } ``` ### Completing applicant E\_DOC\_VERIFY For non-Australian residents, the applicant eDocVerify is done via the third-party vendor Onfido. Applicant KYC via Onfido takes place for the Singapore region when the KYC mode is `E_DOC_VERIFY`. To simulate different success and error responses of the eDocVerify flow, use the following conditions on the applicant's phone number. In all cases, the applicant needs to open the redirect URL in their browser. You either land on the vendor’s page or receive a success/failure redirection back to your KYC redirect URL without any actions needed on the UI. The redirectURL has `isSuccess`, `errorCode`, and `errorMessage` parameters as described in [Applicant KYC](/docs/onboarding/corporate-customers/au-onboarding#applicant-kyc). Based on `businessDetails.applicantDetails.contactDetail.contactNumber`, there are two outcomes: | First two digits of `contactNumber` | Resulting situation | | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Doesn't contain any of the simulated patterns | Onfido's sandbox page is opened and the applicant needs to complete the simulated authentication on the UI. This can be used for end-to-end testing. | | Does contain any of the simulated patterns | The customer's browser redirects to your KYC redirect URL without the need of any actions on the UI. Redirection will contain the following [Redirection parameters](#redirection-parameters) | #### Redirection parameters | Return code | Query parameters in the redirection | | :---------- | :---------------------------------------------------------------------------------- | | 91 | `isSuccess`=`true`; `errorCode`=;`erroressage`= | | 41 | `isSuccess = false` ; `errorCode = R403`; `errorMessage = documentAlreadySubmitted` | | 51 | `isSuccess = false` ; `errorCode = I500`; `errorMessage = unexpectedError` | | 61 | `isSuccess = false` ; `errorCode = R408`; `errorMessage = redirectUrlExpired` | You can test the `verificationAlreadyCompleted` message by clicking on the `redirectURL` after completing verification. --- # CA Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/ca-onboarding - This page contains details of the Canada (CA) KYB flows with the following sub-pages for quick reference: | Page name | Description | | :--------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | | **[CA required parameters](/docs/onboarding/corporate-customers/ca-onboarding/required-parameters)** | This page lists the required API fields of each entity type for an eKYB verification. | | **[CA required documents](/docs/onboarding/corporate-customers/ca-onboarding/required-documents)** | This page contains tables listing the required documents to verify the business entity, stakeholders, and applicants. | | **[CA position mapping](/docs/onboarding/corporate-customers/ca-onboarding/position-mapping)** | This page gives a quick glance at the required positions of each entity type. | | **[CA request examples](/docs/onboarding/corporate-customers/ca-onboarding/example-requests)** | This page contains API request examples for CA entities. | Nium offers Manual KYB flows for customers in Canada. Please note that businesses registered in Quebec cannot be onboarded on Nium platform to comply with fintech requirements ## Manual KYB Flow The following steps need to be performed for completing an application via Manual KYB. CA Onboarding For Manual KYB, you need to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API directly. In this flow, the entire request body needs to be passed in the Onboard Corporate Customer API. ### Onboard Corporate Customer API You need to collect all the details required to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API through an onboarding form and call the API with the full request body. #### Applicant KYC The `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC` are supported for applicants for eKYB flow in Canada. For applicants, you pass `E_KYC` (for CA residents) or `E_DOC_VERIFY` (for non-CA residents) in `businessDetails.applicantDetails.kycMode`. If required, the client can make use of the`MANUAL_KYC` for non-CA residents; however, uploading of documents is required for Manual KYC which needs to be sent in `businessDetails.applicantDetails.documentDetails`. For details, see HK required documents for applicants. The uploading of documents is mandatory for `MANUAL_KYC` which has to be sent in `businessDetails.applicantDetails.documentDetails`. See [CA required documents](/docs/onboarding/corporate-customers/ca-onboarding/required-documents) for details. **Applicant eDocVerify** As a response to the Onboard Corp Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirect URL. The applicant then lands on the KYC vendor's page, where he can complete the KYC verification by uploading his proof of identity and proof of address documents with a live selfie. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium. Redirection can result in the following scenarios, based on the below parameters. - `errorCode` - `errorMessage` - `isSuccess` – This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. | Scenario | Expected action from client | Query parameters in the redirection | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | The applicant completed the required steps in the vendor’s UI. | Wait for webhook. | `errorCode`: N/A `errorMessage`: N/A `isSuccess`: TRUE | | The document has already been submitted in the vendor's UI. | KYC Process is completed. Client needs to wait for webhook. | `errorCode`: R403 `errorMessage`: documentAlreadySubmitted `isSuccess`: FALSE | | The customer has provided incorrect data in the vendor's UI. | Ask customer to submit correct data in the vendors page. | `errorCode`: I400 `errorMessage`: vendorValidationError `isSuccess`: FALSE | | Verification failure at the vendor. | The application goes to manual review. The client needs to wait for webhook. | `errorCode`: R401 `errorMessage`: vendorVerificationFailure `isSuccess`: FALSE | | Internal Server error at Nium. | Try after some time or reach out to Nium's support. | `errorCode`: R500 `errorMessage`: internalServerError `isSuccess`: FALSE | | Any unexpected error from the vendor. | Try after some time or reach out to Nium's support. | `errorCode`: I500 `errorMessage`: unexpectedError `isSuccess`: FALSE | | Validation already completed and customer retries the same link. | KYC Process is completed. The client need to wait for webhook. | `errorCode`: R606 `errorMessage`: verificationAlreadyCompleted `isSuccess`: FALSE | Based on the scenario, you can implement the next steps as provided in the table above. **Example of a redirect to the client in a successful case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11- f95c315ce83c&isSuccess=true&errorCode=&errorMessage= ``` **Example of a redirect to the client in a failed case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11- f95c315ce83c&errorCode=R408&errorMessage=redirectURLExpired&isSuccess=false ``` When the applicant's `businessDetails.applicantDetails.address.country` is `US`, the applicant's address' `state` needs to be a valid 2 letter state code. Use the [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API for acceptable values. When the applicant's `businessDetails.applicantDetails.address.country` is `GB`, the applicant's `postcode` needs to be in the `SW4 6EH` format. #### Upload documents Document upload is required for Business and for the applicant if the `kycMode` is `MANUAL_KYC` Documents can be submitted either of two ways: - As part of the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request - Using the [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request The [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) API is preferred since it uploads one document at a time, which reduces the loading time. This API can be called only while the application is in the `IN_PROGRESS` state. You can use the `remarks` field to list which documents Nium is expecting, in the response of both APIs. The API gateway has a limit of 10 MB for any API request. This makes Upload Document API the preferred way to upload documents since you can upload one document at a time. For the entire list of required documents for manual KYB and eKYB flows, see [CA required documents](/docs/onboarding/corporate-customers/ca-onboarding/required-documents). #### Applicant Declaration CA applicant declaration must happen in the following way. While building the form, you should ensure that the applicant declaration is a checkbox that is collected on a separate page after the applicant has already filled in the Stakeholder information. This page should show the list of all stakeholders in view mode. The applicant declaration text should imply the following statements objectively: - The List of UBOs and their details provided are true and verified by the applicant - The List of directors and their details provided are true and verified by the applicant - All the other information provided by the applicant is true and verified. > I certify that I am the authorized representative of the customer; all information provided and documents submitted are complete and correct. I confirm that I have provided all the UBOs and directors or equivalent positions available. I have read and accepted the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). You can accept this through a clickwrap and send Nium the confirmation by passing `businessDetails.applicantDetails.additionalInfo.applicantDeclaration='Yes'`. This is a mandatory field, and passing any other value would result in a validation error. You can show the below text while accepting the clickwrap. #### Stakeholder KYC Stakeholder KYC is not required in Canada. You can ignore the `businessDetails.stakeholders.stakeholderDetails.kycMode` field. After submission and completion of applicant KYC in case of E\_DOC\_VERIFY, and submission of required documents, the `status` in the response of the Onboard Corporate customer is `IN_PROGRESS`. Nium initiates real-time verification and sends the response via webhook. The application can get approved at this stage; and if it isn't approved, the application goes through manual review. Any changes in `status` is again communicated via webhook. For the next steps to take to onboard your customer, see the response returned in the [webhook](/docs/onboarding/corporate-customers#webhooks). #### Terms and Conditions You must show customers the Nium terms and conditions configured for your `client` resource. You can fetch these specific terms and conditions using our [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions). Customers can only submit the onboarding form once they accept the terms and conditions. To fetch the [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions): 1. Wait for the Onboarding API to return a `customerHashId`. 2. Once returned, call our [Accept Terms and Conditions API](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) and include the `customerHashId`. 3. Show the customer the returned terms and conditions and record their acceptance before allowing them to transact. For more details, see [Terms and Conditions](/docs/onboarding/corporate-customers#terms-and-conditions). --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/ca-onboarding/required-parameters - The API fields shown on this page are relevant to Canada only. To see the full payload, refer to the [Onboard Corporate Customer API Reference](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). All fields have a maximum limit of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `region` | The country or geographic region where the corporate end customer is located and is onboarded. To onboard a Canada -based customer, use the `CA` value. | Yes | | [businessDetails](#businessDetails) | An object that accepts business details about the corporate customer. | Yes | | [riskAssessmentInfo](#riskAssessmentInfo) | An object that contains the risk assessment information. | Yes | | [deviceDetails](#deviceDetails) | An object that contains information about the customer's device and IP address. | Yes | | [tags](#tags) | An object that contains the tags. | No | | `clientId` | This field accepts the Nium client ID of the customer. It's received in the response to the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | | `customerHashId` | This field accepts the unique customer identifier generated at the time of customer creation. It's received in the response to the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | ## Table header API fields The below table headers refer to the `businessType` fields: | Public | Trust | Other entity | | :--------------- | :------------------------- | :------------------------------------------------------ | | `PUBLIC_COMPANY` | `TRUST``WIDELY_HELD_TRUST` | `PRIVATE_COMPANY` `CHARITY` `PARTNERSHIP` `SOLE_TRADER` | ## `businessDetails` object An object that accepts business details about the corporate customer. | Property | Description | Public | Trust | Other entity | | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- | :---------- | :----------- | | `referenceId` | The universally unique identifier (UUID) of the business entity that Nium uses to identify the `businessDetails` entity. If it's not provided, Nium generates one. The UUID is used to respond to a request for information (RFI) or to upload required documents for the business entity. | Optional | Optional | Optional | | `businessName` | The name a corporate customer is registered under. | Required | Required | Required | | `businessRegistrationNumber` | The business registration number. For US customers, pass only the employer identification number (TIN). This field accepts only 9 digits. | Required | Required | Required | | `tradeName` | Another name that the corporate customer uses to do business under, which is different than their licensed business name. | Optional | Optional | Optional | | `website` | A company's set of related web pages located under a single domain name. | Optional | Optional | Optional | | `businessType` | The legal entity type of the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | | `description` | A brief overview of the business. Max character length is 65535. | Required | Required | Required | | `stockSymbol` | The publicly traded stock or ticker symbol of the business. | Optional | N/A | N/A | | [taxDetails](#businessDetails-taxDetails) | An array of objects for Tax identification number of the entity | Optional | Optional | Optional | | [legalDetails](#businessDetails-legalDetails) | An object that contains the legal details. | Required | Required | Required | | [addresses](#businessDetails-addresses) | An object that contains the registered address and the business address of the corporate customer. | Required | Required | Required | | [documentDetails](#businessdetails-documentdetails) | An array of object that contains the business documents. **Note:** This object is required for `MANUAL_KYB`. | Required \* | Required \* | Required \* | | [stakeholders](#businessdetails-stakeholders) | An array of object that contains the individual and corporate stakeholders of the corporate customer. | Required | Required | Required | | [applicantDetails](#businessdetails-applicantdetails) | An object that contains the applicant's details. | Required | Required | Required | | [additionalInfo](#businessDetails-additionalInfo) | An object that contains additional information about the business. | Optional | Optional | Optional | ### taxDetails array An array of objects within the `businessDetails` object that contains multiple values of taxation details of the corporate customer. | Property | Description | Required | | :---------- | :--------------------------------------------------------- | :------- | | `country` | This field will be CA | Required | | `taxNumber` | The tax ID number of the business as found in tax filings. | Required | ### `legalDetails` object An object within the `businessDetails` object that accepts legal details. | Property | Description | Required | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------: | | `registeredDate` | The date the business is registered entered in the `YYYY-MM-DD` format. Registered date cannot be future date. | Required \| Optional for Charity | | `registeredCountry` | The country where the business is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required \| Optional for Charity | | `listedExchange` | The exchange where the business is publicly listed. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required for Public Company | ### `addresses` object An object within the `businessDetails` object that accepts registered and business addresses. | Property | Description | Required | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------: | | [registeredAddress](#businessdetails-address-registeredaddress) | An object that contains the address where the business is registered. | Required | | [businessAddress](#businessdetails-address-businessaddress) | An object that contains the address where the business correspondence can be conducted, if different than the registered address. This will also be the communication address. **Note:** This is required if `isSameBusinessAddress=No` | Required \* | #### `registeredAddress` object An object within the `businessDetails.address` object that accepts the address details where the corporate customer is registered. | Property | Description | Required | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the registered business. | Required | | `addressLine2` | The second address line of the registered business. | Optional | | `city` | The city where the corporate customer is registered. | Required | | `state` | The state where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `country` | The country where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `postcode` | The postal code where the corporate customer is registered. `postcode` is alphanumeric and follows the format 'A1A 1A1' e.g. , K1A 0T6 | Required | #### `businessAddress` object An object within the `businessDetails.address` object that accepts the address details where the business correspondence can be conducted, if different than the registered address \* This object is required if `isSameBusinessAddress = No`. | Property | Description | Required | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: | | `addressLine1` | The first address line of the principal place of business if different than the registered business. | Required \* | | `addressLine2` | The second address line of the principal place of business if different than the registered business. | Optional | | `city` | The city of the principal place of business if different than the registered address. | Required \* | | `state` | The state of the principal place of business if different than the registered address. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required \* | | `country` | The country where the principal place of business occurs if different than the registered country. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required \* | | `postcode` | The postal code where the principal place of business occurs if different than the registered address. `postcode` is alphanumeric and follows the format 'A1A 1A1' e.g. , K1A 0T6 | Required \* | ### `documentDetails` array An array of objects within the `businessDetails` object that accepts one or more business documents. | Property | Description | Required | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: | | `documentType` | The type of business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required \* | | [document](#businessdetails-documentdetails-document) | An object that contains a document copy. | Required \* | #### `document` array An array of objects within the `businessDetails.documentDetails` object. | Property | Description | Required | | ---------- | --------------------------------------------------------------------------------------------------------------------------- | :---------: | | `fileName` | The name of the file. | Required \* | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \* | | `document` | The file as a base64 encoded string. | Required \* | ### `stakeholders` object An array of objects within the `businessDetails` object that accepts one or many stakeholders' information. For every stakeholder object, send either the `stakeholderDetails` or the `businessPartner` parameters. | Property | Description | Required | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `referenceId` | The UUID associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | Optional | | [stakeholderDetails](#businessdetails-stakeholders-stakeholderdetails) | An object that contains the details about the individual stakeholder. | Required | | [businessPartner](#businessdetails-stakeholders-businesspartner) | An object that contains the details of the corporate stakeholder, if available. | Required | #### `stakeholderDetails` object An object within the `stakeholders` object that contains the details of about an individual stakeholder. | Property | Description | Required | | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | :-------------------------------: | | `kycMode` | The KYC mode for verifying the individual stakeholder. You can ignore this field as stakeholder KYC is not required. | Optional | | `firstName` | The first name of the individual stakeholder. | Required | | `middleName` | The middle name of the individual stakeholder. | Optional | | `lastName` | The last name of the individual stakeholder. | Required | | `nationality` | The nationality of the individual stakeholder. | Required | | `dateOfBirth` | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. | Required if the position is `UBO` | | [professionalDetails](#businessdetails-stakeholders-stakeholderdetails-professionaldetails) | The professional details of the individual stakeholder. This field is an array. | Required | | [address](#businessdetails-stakeholders-stakeholderdetails-address) | An object that contains the residential address of the individual stakeholder. | Required if the position is `UBO` | | \[contactDetails] | An object that contains the contact details of the individual stakeholder | Optional | ##### `professionalDetails` object An array of object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's professional details. | Property | Description | Required | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------: | | `position` | The position of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `sharePercentage` | The share percentage of the individual stakeholder in the company. | Required when Position is `UBO` | ##### `addresses` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the individual stakeholder. | Required | | `addressLine2` | The second address line of the individual stakeholder. | Optional | | `city` | The city or suburb of the individual stakeholder. | Required | | `state` | The state of the individual stakeholder. | Required | | `country` | The country where the individual stakeholder resides, specified in [ISO 3166 format](https://www.iban.com/country-codes). | Required | | `postcode` | The postal code of the individual stakeholder. | Required | ##### `contactDetails` object An optional object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's contact information. | Property | Description | Public | Trust | Other entity | | ----------- | ------------------------------------------------------- | :------: | :------: | :----------: | | `email` | The individual stakeholder's email address. | Optional | Optional | Optional | | `contactNo` | The contact phone number of the individual stakeholder. | Optional | Optional | Optional | #### `businessPartner` An object within the `businessDetails.stakeholders` object with the business details of the corporate stakeholder. \* This object is required if there's a corporate stakeholder. | Property | Description | Required | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: | | `businessName` | The registered business name of the corporate stakeholder. | Required | | `businessRegistrationNumber` | The business registration number. | Required | | `businessEntityType` | The position of the corporate stakeholder in the company. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `sharePercentage` | The share percentage of the corporate stakeholder in the company. **Note:** If the corporate stakeholder’s position is `UBO`, then the share percentage is a required input parameter. | Required \* | | [legalDetails](#businessdetails-stakeholders-businesspartner-legaldetails) | An object that contains the legal details of the corporate stakeholder. | Required | ##### `legalDetails` object An object within the `businessDetails.stakeholders.businessPartner` object that contains the corporate stakeholder's legal details. | Property | Description | Public | Trust | Other entity | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | :------: | :----------: | | `registeredCountry` | The country where the corporate stakeholder is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | ### `applicantDetails` object An object within the `businessDetails` object that contains details about the applicant. | Property | Description | Required | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------: | | `referenceId` | The universally unique identifier (UUID) associated with the applicant and applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents. | Optional | | `kycMode` | The KYC mode for verifying the identity of the applicant. Valid values are `E_KYC` , `E_DOC_VERIFY`, and `MANUAL_KYC`. | Required | | `firstName` | The first name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Required | | `middleName` | The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Optional | | `lastName` | The last name or the applicant. The maximum length is 40 alphabetic characters or spaces. | Required | | `nationality` | The nationality of the applicant. | Required | | `dateOfBirth` | The date when the applicant is born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. Applicant cannot be less than 18 yrs of age. | Required | | `occupation` | Occupation of applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | [professionalDetails](#businessdetails-applicantdetails-professionaldetails) | An array of objects that contains the professional details of the applicant. | Required | | [address](#businessdetails-applicantdetails-address) | An object that contains the address of the applicant. | Required | | [contactDetails](#businessdetails-applicantdetails-contactdetails) | An object that contains the contact details of the applicant. | Required | | [documentDetails](#businessdetails-applicantdetails-contactdetails) | An array of objects that contains the document details of the applicant. | Required if `kycMode` is `MANUAL_KYC` | | [additionalInfo](#businessDetails-applicantDetails-additionalInfo) | An object that contains additional information about the applicant. | Required | #### `professionalDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the professional details of the applicant. | Property | Description | Required | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | | `position` | The position of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `sharePercentage` | The share percentage of the applicant in the company. **Note:** This field is a required input parameter if the applicant's position is `UBO`. | Required when `position`is `UBO` or `PARTNER` | #### `address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | Property | Description | Public | Trust | Other entity | | -------------- | --------------------------------------------------------------------------------------------------------------------------- | :------: | :------: | :----------: | | `addressLine1` | The first address line of the applicant. The maximum character length is 40. | Required | Required | Required | | `addressLine2` | The second address line of the applicant. The maximum character length is 40. | Optional | Optional | Optional | | `city` | The city of the applicant. The maximum character length is 20. | Required | Required | Required | | `state` | The state of the applicant. The Maximum character length is 30. | Required | Required | Required | | `country` | The country where the applicant resides, specified in [ISO 3166 format](https://www.iban.com/country-codes). | Required | Required | Required | | `postcode` | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. | Required | Required | Required | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object that contains the applicant's contact information. | Property | Description | Public | Trust | Other entity | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | :------: | :----------: | | `email` | The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See [Email regex](/docs//15-Developers/04-FAQs/06-Regex-and-Accepted-Values.md). | Required | Required | Required | | `countryCode`. | The country code of the applicant's phone number. | Required | Required | Required | | `contactNo` | The applicant's phone number. The maximum length is 20 numeric characters. | Required | Required | Required | #### `documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. | Property | Description | Required | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `documentNumber` | The ID number for the given document type. | Required | | `documentIssuanceCountry` | The country that issued the business document, specified in the [ISO 3166 format](https://www.iban.com/country-codes). | Required | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. **Note:** This field is required if `documentType = PASSPORT or DRIVER_LICENCE`. Expiry date cannot be a past date. | Required \* | | [document](#businessdetails-applicantdetails-documentdetails-document) | An array of objects that contains the copy of the document. **Note:** This field is required for `MANUAL_KYC`. | Required \* | ##### `document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains the document copy. \* This object is required for `MANUAL_KYC`. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :---------: | | `fileName` | The name of the file. | Required \* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \* | | `document` | The document saved as a base64 encoded string. | Required \* | #### `additionalInfo` object An object within the `businessDetails.applicantDetails` object that contains additional information about the applicant. While building the form, you should ensure that the applicant declaration is a checkbox that is collected on a separate page after the applicant has already filled the Stakeholder information. This page should show the list of all stakeholders in view mode. The applicant declaration text should imply the following statements objectively: - The List of UBOs and their details provided are complete and verified by the applicant - The List of directors and their details provided are complete and verified by the applicant - All the other information provided by the applicant is complete and verified. | Property | Description | Required | | ---------------------- | ------------------------------------------------------------------------------------- | :------: | | `applicantDeclaration` | This field accepts the declaration from the Applicant. The only valid value is `Yes`. | Required | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Public | Trust | Other entity | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | :------: | :----------: | | `isSameBusinessAddress` | This field accepts `Yes` or `No` to indicate if the principal place of business is the same or different from the registered business entity address. **Note:** This field is required if `Yes`; optional if `No`. | Optional | Optional | Optional | ## `riskAssessmentInfo` object An object that contains the following details that are required to determine a corporate customer's risk profile. | Property | Description | Required | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `totalEmployees` | The corporate customer's total number of employees. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `annualTurnover` | The corporate customer’s annual turnover. If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `industrySector` | The corporate customer's industry sector. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `countryOfOperation` | An array of countries the corporate customer operates in. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `transactionCountries` | An array of countries where the transactions occur. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | | `intendedUseOfAccount` | The customer's intended use of the account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | ## `deviceDetails` object This object contains the information about the customer's device and IP address where the onboarding request originated. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ---------------------------------- | | `countryIP` | Country of the IP address e.g. `US`. Use [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) for valid values. | Required | Required | Required | | `deviceInfo` | Information of the device e.g. `Mac OS`. | Required | Required | Required | | `ipAddress` | IP address of the device e.g. `45.48.241.198`. | Required | Required | Required | | `sessionId` | A unique identifier for the session, generated by your application. | Required | Required | Required | ## `tags` object This object contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15. | Property | Description | Required | | -------- | ------------------------------------------------------------------------------- | :------: | | `key` | The name of the tag. The maximum character length is 128. Key should be unique. | Optional | | `value` | The value of the tag. The maximum character length is 256. | Optional | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/corporate-customers/ca-onboarding/required-documents This page outlines the documents required for stakeholders, applicants, and various business types to onboard a corporate customer registered in Canada. ## Business details The following documents are required as part of the Know Your Business (KYB) identification and verification process. | Entity type | Document Type (enum) | Documents required | | :------------------ | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PRIVATE\_COMPANY | `BUSINESS_REGISTRATION_DOCUMENT` | `Articles of incorporation` (optional) `Certificate of corporate Status` (optional) If Article of incorporation does not contain shareholder details: `Shareholder registry` | | PUBLIC\_COMPANY | `BUSINESS_REGISTRATION_DOCUMENT` | Certificate of incumbency, the articles of incorporation, or the bylaws of the corporation or subsequent board resolutions that set out the officers duly authorized to sign on behalf of the corporation | | TRUST | `TRUST_DEED` | Deed of trust | | CHARITY | | N/A | | PARTNERSHIP | `PARTNERSHIP_AGREEMENT` | Partnership Agreement | | WIDELY\_HELD\_TRUST | `TRUST_DEED` | Deed of trust | | SOLE\_TRADER | | N/A | ## Stakeholders No documents and `documentDetails` are required for stakeholders. ## Applicants Nium offers `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC` modes for applicant KYC in the US. - `E_KYC` is applicable for CA residents. No document details are required for this mode. - `E_DOC_VERIFY` is applicable for non-CA residents. Applicant needs to complete KYC using the redirect URL. Document details need to be passed for `E_DOC_VERIFY` and upload of document files isn't required. - `MANUAL_KYC` required document details along with upload of document files. ### Manual KYC Every individual applicant needs to submit one of the following information when `kycMode = MANUAL_KYC`. | Document Type | Document Accepted | Document type Enum | | :---------------- | :---------------- | :----------------------- | | POI | Passport | `PASSPORT` | | | Driver’s License | `DRIVER_LICENSE` | | | Residence Card | `NATIONAL_ID` | | | Citizenship Card | `NATIONAL_ID` | | POA (optional) | Listed below | `PROOF_OF_ADDRESS` | | LOA (conditional) | | `LETTER_OF_AUTHORISATON` | | Residence Card | Passport | Residence Card | Citizenship Card | Driver license | Additional document if the first document doesn't contain an address | Additional document if the applicant is not a UBO/ DIRECTOR/ TRUSTEE/ PARTNER | | :------------------------ | :-------------------- | :------------- | :--------------- | :--------------- | :------------------------------------------------------------------- | :---------------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `NATIONAL_ID` | `DRIVER_LICENSE` | `PROOF_OF_ADDRESS` | `LOA` | | `documentNumber` | Yes (Passport number) | Yes | Yes | Yes | No | No | | `documentIssuanceCountry` | Yes | Yes | Yes | Yes | No | No | | `documentExpiryDate` | Yes | No | No | Yes | No | No | | `document.fileName` | Yes | Yes | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | Yes | Yes | | `document.document` | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | Yes | **Note:** Additionally Letter of Authorization is required for the Applicant who is not a UBO or director (or equivalent positions) of the company. **Note:** Proof of Address is required for the applicant if the Passport/National ID is used as Proof of identity and the passport does not contain the applicant’s address. **`PROOF_OF_ADDRESS`documents applicable for Applicant** Proof of address is needed when address is not stated on National ID/Passport - Utility Bill, dated within the previous 60 days (gas, electric, telephone, cable) - Major Credit Card Bills, dated within the previous 60 days (VISA, MasterCard, American Express, Discover) - Bank or brokerage account statement dated within the previous 60 days ### eDocVerify Every individual applicant needs to submit one of the following information when `kycMode = E_DOC_VERIFY` | Field name | Passport | National ID | Driver license | | :------------------------ | :-------------------- | :------------ | :--------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVER_LICENSE` | | `documentNumber` | Yes (Passport number) | Yes | Yes | | `documentIssuanceCountry` | Yes | Yes | Yes | | `documentExpiryDate` | Yes | No | Yes | | `document.fileName` | No | No | No | | `document.fileType` | No | No | No | | `document.document` | No | No | No | --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/ca-onboarding/position-mapping | businessType | SIGNATORY | DIRECTOR | EXECUTOR | PARTNER | PROTECTOR | SETTLOR | SHAREHOLDER | TRUSTEE | UBO | | `businessType` | `SIGNATORY` | `DIRECTOR` | `EXECUTOR` | `PARTNER` | `PROTECTOR` | `SETTLOR` | `SHAREHOLDER` | `TRUSTEE` | `UBO` | | ------------------- | :---------- | :--------: | :--------: | :-------: | :---------: | :-------: | :-----------: | :-------: | :---: | | `PRIVATE_COMPANY` | Yes | Yes | | | | | Yes | | Yes | | `PUBLIC_COMPANY` | Yes | Yes | | | | | Yes | | Yes | | `TRUST` | Yes | Yes | Yes | Yes | Yes | | Yes | Yes | Yes | | `CHARITY` | Yes | Yes | Yes | | Yes | Yes | | | | | `PARTNERSHIP` | Yes | Yes | | Yes | | | | | | | `WIDELY_HELD_TRUST` | Yes | Yes | Yes | Yes | Yes | | Yes | Yes | Yes | | `SOLE_TRADER` | Yes | | | | | | | | Yes | A **Yes** value means that position can be passed for that `businessType`. A blank table cell means that position is not applicable for that `businessType`. --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/ca-onboarding/example-requests To onboard your entity, you can call the Onboard Corporate Customer API. For an example call that you can customize with your information, see: To onboard your entity, you can call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. For an example call that you can customize with your information, see: - [Private companies](#private) - [Public companies](#public) ## Private companies The following is an API request example call where `businessType = PRIVATE_COMPANY`. ```json { "region": "CA", "businessDetails": { "businessName": "Soylent Caals", "businessRegistrationNumber": "1014999d8", "businessType": "PRIVATE_COMPANY", "description": "Corporation in US to facilitate payments to business", "tradeName": "Soylent Corp", "legalDetails": { "registeredCountry": "CA", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "999 Park Street", "addressLine2": "Near Airport", "city": "Toronto", "state": "Ontario", "country": "CA", "postcode": "A1A1A1" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD", "fileType": "application/pdf", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "firstName": "AAMICHAEL", "lastName": "JONES", "nationality": "CA", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "UBO", "sharePercentage": "50" } ], "address": { "addressLine1": "Park Street", "city": "Toronto", "state": "Ontario", "country": "CA", "postcode": "07071" } } }, { "businessPartner": { "businessName": "Vehement Capital Partners", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "E_KYC", "occupation": "OC9510", "firstName": "AATom", "lastName": "Arch", "nationality": "CA", "dateOfBirth": "1982-07-10", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "CA", "contactNo": "9974922222", "email": "tom@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "Toronto", "state": "Ontario", "postcode": "06110", "country": "US" }, "additionalInfo": { "applicantDeclaration": "Yes" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "CA011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "US", "SG", "HK", "AU" ], "transactionCountries": [ "SG", "AU", "EU" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Public Company The following is an API request example call where `businessType = TRUST`. ```json { "region": "CA", "businessDetails": { "businessName": "Soylent Chemidls", "businessRegistrationNumber": "101qd8", "businessType": "PUBLIC_COMPANY", "description": "Corporation in US to facilitate payments to business", "tradeName": "Soylent Corp", "legalDetails": { "registeredCountry": "CA", "registeredDate": "2021-08-10", "listedExchange": "EX103" }, "addresses": { "registeredAddress": { "addressLine1": "999 Park Street", "addressLine2": "Near Airport", "city": "Toronto", "state": "Ontario", "country": "CA", "postcode": "A1A1A1" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD", "fileType": "application/pdf", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "firstName": "AAMICHAEL", "lastName": "JONES", "nationality": "CA", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "UBO", "sharePercentage": "50" } ], "address": { "addressLine1": "Park Street", "city": "Toronto", "state": "Ontario", "country": "CA", "postcode": "07071" } } }, { "businessPartner": { "businessName": "Vehement Capital Partners", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "CA" } } } ], "applicantDetails": { "kycMode": "E_KYC", "occupation": "OC9510", "firstName": "AATom", "lastName": "Arch", "nationality": "CA", "dateOfBirth": "1982-07-10", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "CA", "contactNo": "9974922222", "email": "tom@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "Toronto", "state": "Ontario", "postcode": "06110", "country": "US" }, "additionalInfo": { "applicantDeclaration": "Yes" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "CA011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "US", "SG", "HK", "AU" ], "transactionCountries": [ "SG", "AU", "EU" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Other entities The following is an API request example call where `businessType = CORPORATION`. Examples for other entity types listed below are similar. - Corporations - Estates - General partnerships - Limited liability company - Limited liability partnership firms - Limited partnerships - Sole traders - Unincorporated associations ```json { "region": "US", "businessDetails": { "businessName": "Soylent Corporation68s", "businessRegistrationNumber": "529403988", "businessType": "CORPORATION", "description": "Corporation in US to facilitate payments to business", "tradeName": "Soylent Corp", "legalDetails": { "registeredCountry": "CA", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "999 Park Street", "addressLine2": "Near Airport", "city": "Toronto", "state": "Ontario", "country": "US", "postcode": "07071" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD", "fileType": "application/pdf", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "MICHAEL", "lastName": "JONES", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "Park Street", "city": "Toronto", "state": "Ontario", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US", "document": [ { "fileName": "POI.png", "fileType": "images/png", "document": "gtudfsdfgegetg" } ] } ] } }, { "businessPartner": { "businessName": "Vehement Capital Partners", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "CA" } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Tom", "lastName": "Arch", "nationality": "US", "dateOfBirth": "1982-07-10", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "CA", "contactNo": "9974922222", "email": "tom@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "Toronto", "state": "Ontario", "postcode": "06110", "country": "US" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "123456789", "documentIssuanceCountry": "CA" } ], "additionalInfo": { "applicantDeclaration": "Yes" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "CA011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "US", "SG", "HK", "AU" ], "transactionCountries": [ "SG", "AU", "EU" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` --- # EU Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/eu-onboarding This page provides an overview of Know Your Business (KYB) flows for the European Union and includes links to related resources for quick reference. | Page | Description | | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | | [EU Required Parameters](/docs/onboarding/corporate-customers/eu-onboarding/required-parameters) | Lists the required API fields for each entity type. | | [EU Required Documents](/docs/onboarding/corporate-customers/eu-onboarding/required-documents) | Lists the required documents to verify businesses, stakeholders, and applicants. | | [EU Position Mapping](/docs/onboarding/corporate-customers/eu-onboarding/position-mapping) | Describes the required roles for each entity type. | | [EU Request Examples](/docs/onboarding/corporate-customers/eu-onboarding/example-requests) | Provides sample requests for EU entities. | - Nium supports both electronic KYB (eKYB) and manual KYB flows for businesses in the European Union. - eKYB pre-fills applications and helps reduce the number of documents required to submit. It improves your customers experience by reducing drop-offs and speeding up approvals. [Contact Nium](https://www.nium.com/contact-us) for information on how to enable eKYB for your account. ## eKYB flow Follow these steps to complete the eKYB application process. EU Onboarding ### Step 1: Fetch public corporate details Collect the basic details about the applying corporate customer through an onboarding form (eKYB onboarding). This includes the `businessRegistrationNumber` and `countryCode`. See [currency and country codes](/docs/getting-started/currency-and-country-codes) for valid values. Call the [Fetch Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) request. This request returns publicly available corporate details. Return them to your customer to confirm. Store the returned `searchReferenceId`. You’ll need it in the next step. If no results are returned, submit a full request using the [Onboard Corporate Customer](/api#tag/customer-account-corporate/post/api/v1/client/{clientHashId}/corporate) request to proceed with manual KYB onboarding. ### Step 2: Get exhaustive corporate details Call the [Fetch Exhaustive Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) request with the `searchReferenceId`. Save the returned `searchId`; this will be required in later steps. This is a chargeable API. Use it only once per customer. Contact your Nium account manager or [Nium Support](mailto:support@nium.com) for more details. ### Step 3: Display details to the applicant Display the returned details to the applicant for review. Collect any missing required information. ### Step 4: Submit corporate details Call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request with the complete details, including **searchId**. If **searchId** is not included, the application is processed as a `MANUAL_KYB` onboarding attempt and goes through manual review. #### Applicant KYC After receiving a response from the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate), save the `redirect` URL and send the applicant to this `redirectURL`. The applicant then completes KYC on Nium's verification partner's side (Onfido) by uploading a proof of identity, and a live selfie. You must include **E\_DOC\_VERIFY** for `businessDetails.applicantDetails.kycMode` for every application. You must pass with **E\_DOC\_VERIFY** set **`businessDetails.applicantDetails.kycMode`**. Once KYC is completed, the browser is Redirected to the clients configured E\_KYC redirect URL with the following query paramneters: - `isSuccess` - This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. - `errorCode` - `errorMessage` - `referennceId` (used to identify the individual for whom redirection happened.) | Scenario | Action | Query Parameters | | :------------------------- | :-------------------------- | :--------------------- | | Steps completed | Wait for webhook | `isSuccess` = **true** | | Document already submitted | Wait for webhook | `errorCode` = **R403** | | Incorrect data | Ask applicant to correct it | `errorCode` = **I400** | | Vendor verification failed | Wait for manual review | `errorCode` = **R401** | | Internal server error | Retry or contact support | `errorCode` = **R500** | | Unexpected error | Retry or contact support | `errorCode=` **I500** | | Already verified | Wait for webhook | `errorCode` = **R606** | #### Example - success redirect: ``` *https://www.clientRedirectURL.com/?clientId=...&caseId=4ff53849-3d30-45c8-af11-f95c315ce83c&isSuccess=true&errorCode=&errorMessage=&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX* ``` #### Example - Successful Redirect: ** #### Example - Failed Redirect: ``` *https://www.clientRedirectURL.com/?clientId=...&errorCode=R403&isSuccess=false&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX* ``` - For **US** addresses, use a valid two-letter `state` code. - For **GB** addresses, use the **SW4 6EH** postcode format. Use the [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request for permitted values. #### Stakeholder KYC For the following values: - **UBO** - **TRUSTEE** - **PARTNER** - **REPRESENTATIVE** - **SIGNATORY** Use **E\_DOC\_VERIFY** or **MANUAL\_KYC** as `kycMode` based on stakeholder preference. `E_DOC_VERIFY` will require live-selfie and hence should be used only when stakeholder is accessible. For `MANUAL_KYC` include required documents in `businessDetails.stakeholders.stakeholderDetails.documentDetails`. Steps to implement stakeholder `E_DOC_VERIFY` `redirectURL` are similar to that of applicant mentioned above. For details on implementation, see **[Onboard API Response - 200 response](/docs/onboarding/corporate-customers#onboard-api-response)** The `referenceId` shown in the browser redirection matches the one submitted in the onboarding request for that stakeholder. If multiple stakeholders have a `redirectURL`, use the `referenceId` to identify each stakeholder and direct them to the correct page. Ignore `businessDetails.stakeholders.stakeholderDetails.kycMode` for other positions. See [Required documents](/docs/onboarding/corporate-customers/eu-onboarding) for details. #### Upload documents Note, if **searchId** is not passed, document uploads are required. Additionally, even with **searchId**, additional documents may be needed. Use one of these APIs: - [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) – Recommended. - [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). Add remarks in the `remarks` field to indicate missing documents. The API gateway limits requests to 10 MB. Use the [Upload Document request](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/uploadDocuments) for large files. See [EU Required Documents](/docs/onboarding/corporate-customers/eu-onboarding/required-documents). #### Terms and Conditions Fetch and display terms using the [Terms and Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions). To accept: 1. Wait for **customerHashId** in onboarding response. 2. Call [Accept Terms and Conditions API](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions). 3. Show terms and record acceptance. See [Terms and Conditions](/docs/onboarding/corporate-customers#terms-and-conditions). ### Step 5: Wait for webhook After submission, status is **IN\_PROGRESS**. The applicant must complete KYC of himself and wait for KYC of all the stakeholders to be completed and upload required documents. Nium then verifies the details and returns a response via webhook. See [Webhooks](/docs/onboarding/corporate-customers#webhooks) for next steps. ## Manual KYB flow Manual KYB Call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request with a full request body. - Submit all required documents first. - Use **E\_DOC\_VERIFY** for applicant KYC. - Use **E\_DOC\_VERIFY** or **MANUAL\_KYC** based on stakeholder preference. - `E_DOC_VERIFY` will require live-selfie and hence should be used when stakeholder is accessible. - include required documents in `businessDetails.stakeholders.stakeholderDetails.documentDetails` for `MANUAL_KYC`. - `kycMode` is required for the following roles: - **UBO** - **TRUSTEE** - **PARTNER** - **REPRESENTATIVE** - **SIGNATORY** Status is **IN\_PROGRESS** after submission. When complete, Nium sends the verification result via webhook. See [Webhooks](/docs/onboarding/corporate-customers#webhooks) for more information. --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/eu-onboarding/required-parameters The page list the fields that apply to customers onboarded under the EU region. To view the complete request payload, see the Onboard Corporate Customer request. The page list the `fields` that apply to customers onboarded under the `EU` region. To view the complete request payload, see the [Onboard Corporate Customer request](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). All fields have a maximum length of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `region` | The regulatory region under which the corporate customer is being onboarded. To onboard under the EU region, use the `EU` value. | Yes | | [`businessDetails`](#businessDetails) | Contains information about the business, including the applicant and stakeholders. | Yes | | [`riskAssessmentInfo`](#riskAssessmentInfo) | Provides additional business profile information, such as total number of employees and annual turnover. | Yes | | [`deviceDetails`](#deviceDetails) | Includes the device and IP address from which the onboarding request originated. | Yes | | [`expectedAccountUsage`](#expectedAccountUsage) | Describes how the customer expects to use the account. | Yes | | [`natureOfBusiness`](#natureOfBusiness) | Contains information about the nature of the business, such as the `industrySector`. | Yes | | [`tags`](#tags) | Contains user-defined key-value pairs submitted by the client. | No | | `customerHashId` | A unique identifier returned in the response to the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request. *Note:*\* Required only when reinitiating KYB after a rejection. | Yes \* | ## Note Only customers registered in EEA are eligible to be onboarded under EU region. Please contact your account manager, in case you need to onboard customers registered outside of EEA. For more information, see [Regulatory region](/docs/onboarding/corporate-customers#regulatory-region). All the fields listed below are applicable for all entity types: - Associations - Government Body - Limited Liability Partnership - Public Company - Private Limited Company - Sole Trader - Trust ## `businessDetails` object Contains information about the corporate customer, including the applicant and stakeholders. | Property | Description | Required | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `referenceId` | A unique identifier for the business entity. If not provided, Nium generates one. Used to respond to RFIs or upload documents. | No | | `businessName` | The registered name of the business. | Yes | | `businessRegistrationNumber` | The official registration number of the business. | Yes | | `tradeName` | The name the business operates under. If the business doesn't use a trade name, set `tradeName` : **`businessName`**. | Yes | | `website` | The business’s website. If not available, submit a social media profile (such as Instagram or Facebook). If neither is available, upload a document with `documentType` : **PROOF\_OF\_BUSINESS**. | No | | `businessType` | The legal entity type, such as a private or public company. Use the [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` : **businessType**. | Yes | | [`legalDetails`](#legaldetails-object) | Registration and legal information for the business. | Yes | | [`taxDetails`](#taxdetails-array) | Tax identification details. | No | | [`addresses`](#addresses-object) | Registered and operating addresses. | Yes | | [`documentDetails`](#documentdetails-object) | Business documents. For details, see [EU Required Documents](/docs/onboarding/corporate-customers/corporate-constants). | Yes \* | | [`stakeholders`](#stakeholders-object) | Information about the business’s stakeholders, such as directors or UBOs. | Yes | | [`applicantDetails`](#applicantdetails-object) | Information about the individual submitting the application. | Yes | | [`additionalInfo`](#additionalinfo-object) | Optional details related to the application. | No | [](/docs/onboarding/corporate-customers/eu-onboarding) ### `legalDetails` object Contains registration and legal information for the business. | Property | Description | Required | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `registeredDate` | The date the business was registered entered in the `YYYY-MM-DD` format. Registered date cannot be a future date. | Yes | | `registeredCountry` | The country where the business is registered. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category`=`countryName` for a valid set of values. | Yes | [](/docs/onboarding/corporate-customers/eu-onboarding) ### `taxDetails` array An array of objects within the `businessDetails` object that contains multiple values of taxation details of the corporate customer. | Property | Description | Required | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `country` | The country in which the corporate customer is paying taxes. This will be the same as the registered country, unless the customer is paying taxes in other countries as well. **Note:** If the customer is a subsidiary or a part of a group of companies, the customer needs to provide countries where taxes are paid for its own legal entity and not for the entire group of companies. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with category=countryName. | No | | `taxNumber` | The tax ID number for this country. Max character length is 64 characters | No | ### `addresses` object An object within the `businessDetails` object that contain registered and business addresses. | Property | Description | Required | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | [registeredAddress](#businessdetails-address-registeredaddress) | An object that contains the address where the business is registered. | Yes | | [businessAddress](#businessdetails-address-businessaddress) | An object that contains the address where the business is mainly conducted, if different than the registered address. **Note**: This is not required if `isSameBusinessAddress`= `Yes` is passed under businessDetails.additionalInfo. | Yes \* | #### `registeredAddress` object An object within the `businessDetails.address` object that contains the address details where the corporate customer is registered. | Property | Description | Required | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `addressLine1` | The first address line of the registered address. | Yes | | `addressLine2` | The second address line of the registered address. | No | | `city` | The city of the registered address. | Yes | | `state` | The state or province of the registered address. If the address doesn't contain state, city can be repeated as state. | Yes | | `country` | The country of the registered address. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`= `countryName` for a valid set of values. | Yes | | `postcode` | The postal code where the corporate customer is registered. | Yes | #### `businessAddress` object An object within the `businessDetails.address` object that contains the address details of the principal place of business only when the registered address is different. \* This object is not required if `businessDetails.additionalInfo.isSameBusinessAddress = Yes`. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `addressLine1` | The first address line of the business address. | Yes \* | | `addressLine2` | The second address line of the business address. | No | | `city` | The city of the business address. | Yes \* | | `state` | The state or province of the business address. If the address doesn't contain state, city can be repeated as state. | Yes \* | | `country` | The country of the business address. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`countryName` for a valid set of values. | Yes \* | | `postcode` | The postal code where the business address. | Yes \* | ### `documentDetails` object An array of objects within the `businessDetails` object that contains one or more business documents. \* For a complete list of required documents, see [EU required documents](/docs/onboarding/corporate-customers/corporate-constants#business-documents). | Property | Description | Required | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `documentType` | The type of business document such as Business Registration Document or Association Deed. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`= `documentType` for a valid set of values. | Yes \* | | [document](#businessdetails-documentdetails-document) | An array of objects that contains a copy of the document. | Yes \* | #### `document` object An array object within the `businessDetails.documentDetails` object. You can add multiple files under the same document object such as multiple pages of the Business Registration Document or addendum. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | | `fileName` | The name of the file. | Yes \* | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes \* | | `document` | The file as a base64 encoded string. | Yes \* | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Required | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `isSameBusinessAddress` | This field accepts `Yes` or `No` to indicate if the principal place of business is the same or different from the registered business entity address. **Note:** Business address can be skipped if this field is `Yes` | No | | `searchId` | This field is required for eKYB and is returned in the response of the [Exhaustive Corporate Details using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) API. Required documents for business will be dependent on this field. | No | ### `stakeholders` object An array of objects within the `businessDetails` object that contains the stakeholders of the corporate customers such as Directors or UBOs. Stakeholder can be a business entity or a natural person. For every stakeholder object, you need to send either the `stakeholderDetails` or the `businessPartner` parameters. | Property | Description | Required | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `referenceId` | The universal unique identifier (UUID) associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | No | | [stakeholderDetails](#businessdetails-stakeholders-stakeholderdetails) | An object that contains the details of the individual stakeholder. | Yes | | [businessPartner](#businessdetails-stakeholders-businesspartner) | An object that contains the details of the corporate stakeholder, if available. | Yes \* | #### `stakeholderDetails` object An object within the `stakeholders` object that contains the details about an individual stakeholder (natural person). All the Signatories, Directors, UBOs, Trustees, Settlor, Partners as available in the Business registration document, or Register of Directors or Register of Shareholders have to be included in the application for all business Types. ##### How to add positions: - **Directors**: All the management directors need to be added as stakeholders. Board of directors are not required. - **UBO**: All shareholders owning more than 25% of share (directly or indirectly) should be tagged as UBOs. In case, no individual owns 25% of share (directly or indirectly) then the most senior director as per their position should be declared as UBO. In case no UBO is submitted, Nium’s team will identify the UBO. For sole traders, the owner should be declared as the UBO. - **Signatory/Representative**: Individual(s) that will conduct transactions or add additional users should be declared as a Signatory/ Representative. Applicant is considered as Representative by default and should be added as such and will be eligible for conducting transactions. Any other users can be added as representatives as well. It is recommended to send all the users as part of the application. These users can be added later as well by sending an email to . KYC of such users should be completed as directed. - **Others**: Other positions such as Partner/ Trustee / Settlor should be provided as applicable as per the [Position mapping](/docs/onboarding/corporate-customers/eu-onboarding/position-mapping) | Property | Description | Required | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `kycMode` | The KYC mode for the individual stakeholder. Note: When positions include `SIGNATORY`, `REPRESENTATIVE`, `UBO`, `TRUSTEE`, `PARTNER`, this field is required to be one of `E_DOC_VERIFY` or `MANUAL_KYC` based on stakeholder preference. Else ignore this field. | Yes\* | | `isLiveAuthorizer` | Boolean. Set this as `true` to nominate this stakeholder as Live-Authorizer. Follow the process, implementation notes and validations listed under [Live-Authorization](/docs/onboarding/corporate-customers/letter-of-authorization#live-authorization) | No | | `firstName` | The first name of the individual stakeholder. | Yes | | `middleName` | The middle name of the individual stakeholder. | No | | `lastName` | The surname of the individual stakeholder. | Yes | | `nationality` | The nationality of the individual stakeholder. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` = `countryName` for a valid set of values. | Yes | | `dateOfBirth` | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. | Yes | | `birthCountry` | The country of birth. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` = `countryName` for a valid set of values. Required if position contains `UBO`,`TRUSTEE` or `PARTNER`. | Yes \* | | [taxDetails](#businessDetails-stakeholders-stakeholderDetails-taxDetails) | The taxation details of the individual stakeholder. **Note:** This field is required if the position is `UBO`, `TRUSTEE`, or `PARTNER`. | Yes \* | | [professionalDetails](#businessdetails-stakeholders-stakeholderdetails-professionaldetails) | An array of objects to accept the positions held by the stakeholder in the business of the corporate customer and details related to the positions held. | Yes | | [address](#businessdetails-stakeholders-stakeholderdetails-address) | An object that contains the residential address of the individual stakeholder. | Yes | | [contactDetails](#businessdetails-stakeholders-stakeholderdetails-contactdetails) | An object that contains the contact details of the individual stakeholder. | No | | [documentDetails](#businessdetails-stakeholders-stakeholderdetails-documentdetails) | An object that contains the document details of the individual stakeholder. **Note:** This field is required if `kycMode`=`MANUAL_KYC`. Additionally, documentDetails are required for `DIRECTOR` | Yes \* | | [additionalInfo](#businessdetails-stakeholders-stakeholderdetails-additionalInfo) | An object that contains additional information required about the individual stakeholder such as `isPEP`. | Yes | ##### `taxDetails` array An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's tax details of one or more countries. \* This object is required if the position includes `UBO` or `TRUSTEE`, or `PARTNER`. | Property | Description | Required | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `country` | The country where the stakeholder is paying taxes. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`countryName` for a valid set of values. | Yes \* | | `taxNumber` | The tax ID number for the corresponding country. Maximum 64 characters. | Yes \* | ##### `professionalDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's professional details. Very often an individual can hold more that one position such as DIRECTOR/ UBO and all applicable positions must be selected. | Property | Description | Required | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `position` | The position of the individual stakeholder such as UBO, DIRECTOR, SIGNATORY. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`position` | Yes | | `sharePercentage` | The share percentage of the individual stakeholder in the company. Sharepercentage should be a number between 0 and 100. Eg. 23.4 **Note:** This field is required if position is `UBO` or `SHAREHOLDER`. Else ignore. | Yes \* | | `positionStartDate` | The date the individual stakeholder started the position of `UBO`. **Note:** This field is required if the position is `UBO` or `TRUSTEE` or `PARTNER`. Position start date cannot be a future date. | Yes \* | ##### `address` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `addressLine1` | The first address line of the individual stakeholder. | Yes | | `addressLine2` | The second address line of the individual stakeholder. | No | | `city` | The city or suburb of the individual stakeholder. | Yes | | `state` | The state or province of the individual stakeholder. City can be passed as state if state is unavailable. | Yes | | `country` | The country where the individual stakeholder resides. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` = `countryName` for a valid set of values. | Yes | | `postcode` | The postal code of the individual stakeholder. | Yes | ##### `contactDetails` object An optional object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the stakeholder's contact information. | Property | Description | Required | | ----------- | ------------------------------------------------------- | -------- | | `email` | The individual stakeholder's email address. | No | | `contactNo` | The contact phone number of the individual stakeholder. | No | ##### `documentDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's document details. Please note: - If kycMode is MANUAL\_KYC, system will validate for required documents. As a result, stakeholders whose positions include `SIGNATORY`, `REPRESENTATIVE`, `UBO`, `TRUSTEE`, `PARTNER` will require `docuemntDetails` and `documents` objects. - If position is `DIRECTOR`, we will require the document number which means `documentDetails` object (that will include `documentNumber` , `documentIssuanceCountry`, `documentExpiryDate`) needs to be mandatorily provided. Document file (`documentDetails.document` object) is not required for the `DIRECTOR` position. - `documentDetails` is not required in case `kycMode` is `E_DOC_VERIFY` - Additionally, if `additionalInfo.isPEP` is `Yes` then `SOURCE_OF_WEALTH` should be submitted as a document. \* **Note:** Check [EU required Documents](/docs/onboarding/corporate-customers/corporate-constants#stakeholder-documents) for list of acceptable documents, their definitions and properties. | Property | Description | Required | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `documentType` | The type of document. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`documentType` for a valid set of values. | Yes \* | | `documentNumber` | The identification number for the document. | Yes \* | | `documentIssuanceCountry` | The country that issued the document. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`countryName` for a valid set of values. | Yes \* | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. **Note:** This is required only if `documentType = PASSPORT`. Expiry date cannot be a past date. | Yes \* | | [document](#businessDetails-stakeholders-stakeholderDetails-document) | An array of objects that contains a copy of a document. Document is required only if `kycMode`=`MANUAL_KYC` or for sending additional documents such as `SOURCE_OF_WEALTH` . | Yes \* | ###### `document` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails.documentDetails` object that contains a copy of the individual stakeholder's document. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | | `fileName` | The name of the file. | Yes \* | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes \* | | `document` | The file as a base64 encoded string. | Yes \* | ##### `additionalInfo` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains additional information about the individual stakeholder. | Property | Description | Required | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `isPep` | This field accepts `Yes` or `No` to indicate if the individual stakeholder is a politically exposed person. If this field is Yes, it is recommended to submit `SOURCE_OF_WEALTH` as a document as this will, otherwise be requested via RFI. | Yes | A PEP (Politically Exposed Person) is someone who holds a prominent public position or has held one in the recent past and, as a result, may be more vulnerable to being involved in bribery, corruption, or money laundering. #### `businessPartner` An object within the `businessDetails.stakeholders` object that contains the business details of the corporate stakeholder. - If the customer is a multilayered company with another corporate owning more than 25% of share directly or indirectly then all such corporate stakeholders should be declared in the application. - Refer [Multi-layered ownership structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6) to understand if the customer is a multi-layered company. - Additionally, Corporate Structure (or ownership structure) should be submitted to validate the structure under `businessDetails.documentType` = `CORPORATE_STRUCTURE`. Refer to [EU Required documents](/docs/onboarding/corporate-customers/corporate-constants#additional-business-documents). | Property | Description | Required | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `businessName` | The registered business name of the corporate stakeholder. | Yes | | `businessRegistrationNumber` | The business registration number. | Yes | | `businessEntityType` | The primary position of the corporate stakeholder in the business of the company. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` = `position` for a valid set of values. Corporate stakeholders can typically hold positions such as UBO, SHAREHOLDER, PARTNER, TRUSTEE. Sometimes, corporate stakeholder can be a DIRECTOR as well. | Yes | | `sharePercentage` | The share percentage of the corporate stakeholder in the company. **Note:** This field is required if the stakeholder’s position is `UBO` or `SHAREHOLDER`. Else ignore. Sharepercentage should be a number between 0 and 100. Eg. 23.4 | Yes \* | | [legalDetails](#businessdetails-stakeholders-businesspartner-legaldetails) | An object that contains the registration and legal details of the corporate stakeholder. | Yes | ##### `legalDetails` object Contains registration and legal information for the business. | Property | Description | Required | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | registeredCountry | The country where the corporate stakeholder is registered. Use Fetch corporate constants API with category = countryName for a valid selection. | Yes | ### `applicantDetails` object Contains details about the individual applicant representing the corporate customer. | Property | Description | Required | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `referenceId` | A UUID associated with the applicant. | No | | `kycMode` | The KYC mode for verifying the identity of the applicant. Set `kycMode` : **E\_DOC\_VERIFY**. | Yes | | `firstName` | The applicant’s first name. Maximum: 40 alphabetic characters or spaces. | Yes | | `middleName` | The applicant’s middle name. Maximum: 40 alphabetic characters or spaces. | No | | `lastName` | The applicant’s last name. Maximum: 40 alphabetic characters or spaces. | Yes | | `nationality` | The applicant’s nationality (e.g., `US`, `IN`). Use the [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) request with `category` : **countryName**. | Yes | | `dateOfBirth` | The applicant’s date of birth. Format: `YYYY-MM-DD`. Cannot be a future date. Must be at least 18 years old. | Yes | | `birthCountry` | The applicant’s country of birth. . Use the [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) request with `category` : **countryName**. | Yes | | [`professionalDetails`](#businessdetails-applicantdetails-professionaldetails) | Array of objects that describe the applicant’s roles in the business. | Yes | | [`taxDetails`](#businessDetails-applicantDetails-taxDetails) | The applicant’s tax identification details. **Required** if position is `UBO`, `TRUSTEE`, or `PARTNER`. | Yes \* | | [`address`](#businessdetails-applicantdetails-address) | The applicant’s residential address. | Yes | | [`contactDetails`](#businessdetails-applicantdetails-contactdetails) | Contact details for the applicant. | Yes | | [`documentDetails`](#businessdetails-applicantdetails-contactdetails) | Optional. An array of additional documents for the applicant (e.g., `POWER_OF_ATTORNEY`, `SOURCE_OF_WEALTH`). | Yes \* | | [`additionalInfo`](#businessDetails-applicantDetails-additionalInfo) | Additional applicant information, such as `isPEP`. | Yes | #### `professionalDetails` object Describes the roles held by the applicant in the corporate customer’s business. | Property | Description | Required | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `position` | The position of the applicant. Use Fetch corporate constants API for a valid set of values. An applicant is a REPRESENTATIVE by default. In addition, all applicable positions like UBO or DIRECTOR should be added. | Yes | | `sharePercentage` | The share percentage of the applicant in the company. Number between 0 and 100 **Note:** This field is required if the position is UBO/ SHAREHOLDER | Yes \* | | `positionStartDate` | The date the applicant started the position at the corporate customer. Position start date cannot be a future date. This field is required for UBO/ TRUSTEE/ PARTNER. | Yes \* | #### `taxDetails` array An array of objects within the `businessDetails.applicantDetails.` object that contains the applicant's tax details of one or more countries. \* This object is required if the position includes `UBO` or `TRUSTEE`, or `PARTNER`. | Property | Description | Required | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `country` | The country of the applicant's tax paying country. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`countryName` for a valid set of values. | Yes \* | | `taxNumber` | The tax ID number for the corresponding country. Maximum 64 characters. | Yes \* | #### `address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | Property | Description | Required | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `addressLine1` | The first address line of the applicant. The maximum character length is 40. | Yes | | `addressLine2` | The second address line of the applicant. The maximum character length is 40. | No | | `city` | The city of the applicant. The maximum character length is 20. | Yes | | `state` | The state or province of the applicant. City can be passed as state if state is unavailable. The maximum character length is 30. | Yes | | `country` | The country where the applicant residence. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for `category`=`countryName` for a valid set of values. | Yes | | `postcode` | The postal code of the applicant. The minimum length is 3 and the maximum is 10 alphanumeric characters or spaces. | Yes | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object that contains the applicant's contact information. | Property | Description | Required | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `email` | The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See [Email regex](/docs//15-Developers/04-FAQs/06-Regex-and-Accepted-Values.md). | Yes | | `countryCode` | The country code of the applicant's phone number. | Yes | | `contactNo` | The applicant's phone number. The maximum length is 20 numeric characters. | Yes | #### `documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. `documentType` and the `document` object are required for applicant in the below conditions: - If positions does not include `DIRECTOR` / `UBO` / `PARTNER` / `TRUSTEE` then `POWER_OF_ATTORNEY` is required. - If `isPEP`=`Yes` then `SOURCE_OF_WEALTH` is required. \* Check [EU required Documents](/docs/onboarding/corporate-customers/eu-onboarding/required-documents) for list of acceptable documents, their definitions and properties. | Property | Description | Required | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `documentType` | The type of document. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | [document](#businessDetails-applicantDetails-documentDetails-document) | The copy of the document. **Note:** This is required for `POWER_OF_ATTORNEY`. This field is an array. | Yes \* | ##### `document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains a copy of the document. \* This object is required for `POWER_OF_ATTORNEY` or `SOURCE_OF_WEALTH`. > Applicant can nominate one of the directors to Live-Authorize and skip submitting Power of Attorney. See [Live-Authorization](/docs/onboarding/corporate-customers/letter-of-authorization#live-authorization) for details. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | | `fileName` | The name of the file. | Yes \* | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes \* | | `document` | The copy of the document. | Yes \* | #### `additionalInfo` object An object within the `businessDetails.applicantDetails` object that contains additional information about the applicant. | Property | Description | Required | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `isPep` | This field accepts `Yes` or `No` to indicate if the applicant is a politically exposed person. If this field is Yes, it is recommended to submit `SOURCE_OF_WEALTH` as a document as this will, otherwise be requested via RFI. | Yes | See [PEP definition](#businessDetails-pep-definition) ## `expectedAccountUsage` object This object contains the details regarding the expected usage of the account | Property | Description | Required | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | [debit](#expectedAccountUsageDebit) | Object containing expected account usage of all outward transactions. | Yes | | [credit](#expectedAccountUsageCredit) | Object containing expected account usage of all inward transactions. | Yes | | `intendedUses` | Array of intended uses of the account. Send all applicable values. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with category = `intendedUses` for valid values. | Yes | | `intendedUsesDescription` | Text field description of the intended use of the account of the corporate customer if `other` is passed in the `intendedUses` field. Min 20 characters. | Yes\* | ### `debit`object This object containing expected account usage of all outward transactions | Property | Description | Required | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `monthlyTransactionVolume` | Estimated total monthly payout transaction amount converted to `EUR`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`monthlyTransactionVolume` for a valid set of values. | Yes | | `monthlyTransactions` | Estimated count of payout transactions per month for the corporate customer. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`monthlyTransactions` for a valid set of values. | Yes | | `averageTransactionValue` | Estimated average transaction value per payout for the corporate customer converted to `EUR`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`averageTransactionValue` for a valid set of values. | Yes | | `topTransactionCountries` | Array of top payout countries. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`= `countryName` for a valid set of values. | Yes | | `topBeneficiaries` | Array of expected primary beneficiaries. Can be specific companies or types of entities (e.g., Ryan Air, Ketan Meheta, Employees of corporate). | Yes | ### `credit`object This object containing expected account usage of all inward transactions. \* In case the customer is not enabled for payins, the client is expected to send the minimum bracket within the allowed ranges for `monthlyTransactionVolume`, `monthlyTransactions`, `averageTransactionValue`. The entire credit object is not applicable if the client is a Payroll client and/ or have requested Nium to switch off third party funding. | Property | Description | Required | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `monthlyTransactionVolume` | Estimated total monthly payin transaction amount converted to `EUR`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`monthlyTransactionVolume` for a valid set of values. | Yes | | `monthlyTransactions` | Estimated count of payin transactions per month for the corporate customer. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`monthlyTransactions` for a valid set of values. | Yes | | `averageTransactionValue` | Estimated average transaction value per payin for the corporate customer converted to `EUR`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) `category`=`averageTransactionValue` for a valid set of values. | Yes | | `topTransactionCountries` | Array of top payin countries. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`= `countryName` for a valid set of values. | Yes | | `topRemitters` | Array of expected primary remitters. Can be specific companies or types of entities (e.g., Ryan Air, Ketan Meheta, Employees of corporate). | Yes | ## `natureOfBusiness` object An object within the `businessDetails.natureOfBusiness` object to provide the nature of business such as industrySector. \* If the industrySector contains any prohibited industries, additional documentation might be requested and can affect the overall approval TAT. Refer to [Prohibited and Restricted Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories) | Property | Description | Required | | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `industryCodes` | An array of industry sector codes that apply for the corporate customer's business. Send all applicable values. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values using `industrySector` category | Yes | | `industryDescription` | Text field explaining the business of the corporate customer in 2-3 sentences. Max Character limit: 300. Min 20 characters. | Yes | ## `riskAssessmentInfo` object An object that contains the details related to the business profile of the corporate customers. | Property | Description | Required | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `totalEmployees` | The corporate customer's total number of employees. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`=`totalEmployees` for a valid set of values. | Yes | | `annualTurnover` | The corporate customer’s annual turnover.If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with category = `annualTurnover` for a valid set of values. | Yes | | `countryOfOperation` | An array of all the countries the corporate customer has presence and does business. List all the countries you have branches, operations, factories etc… Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. This field is an array. Ex: `["IN", "FR", "LT"]` | Yes | ## `deviceDetails` object This object contains the information about the customer's device and IP address where the onboarding request originated. | Property | Description | Required | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `countryIP` | Country of the IP address e.g. US. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` = `countryName` for valid values. | Yes | | `deviceInfo` | Information of the device e.g. Mac OS. | Yes | | `ipAddress` | IP address of the device e.g. 45.48.241.198 | Yes | | `sessionId` | A unique identifier for the session, generated by your application. | Yes | ## `tags` object This object contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15. | Property | Description | Required | | -------- | ------------------------------------------------------------------------------- | -------- | | `key` | The name of the tag. The maximum character length is 128. Key should be unique. | No | | `value` | The value of the tag. The maximum character length is 256. | No | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/corporate-customers/eu-onboarding/required-documents This page outlines the documents required for stakeholders, applicants, and various business types to onboard a corporate customer registered in Europe. ## Business Documents The following table lists the required document types for both manual KYB and eKYB for all business entity types. | `businessType` | Manual KYB | eKYB (`searchId` is present) | | :---------------------------------- | :------------------------------------------------------------------------------------ | :--------------------------- | | `ASSOCIATION` | `ASSOCIATION_DEED` | `ASSOCIATION_DEED` | | `GOVERNMENT_ENTITY` | `BUSINESS_REGISTRATION_DOC` | N/A | | `LIMITED_LIABILITY_PARTNERSHIP` | `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | | `PUBLIC_COMPANY`/ `PRIVATE_COMPANY` | `BUSINESS_REGISTRATION_DOC` `REGISTER_OF_DIRECTORS` \* `REGISTER_OF_SHAREHOLDERS`\* | N/A | | `SOLE_TRADER` | `BUSINESS_REGISTRATION_DOC` | N/A | | `TRUST` | `TRUST_DEED` | `TRUST_DEED` | Business Registration Document or any equivalent documents are preferred to be notarized. If non-notarized document is submitted, Nium tries to fetch the document from source, delaying approvals. ### Additional business documents - **REGISTER\_OF\_DIRECTORS and REGISTER\_OF\_SHAREHOLDERS**: This document is required in case the Business Registration Document does not contain the list of directors or shareholders. Submit notarized documents for faster approvals. When using eKYB, the `REGISTER_OF_DIRECTORS` and `REGISTER_OF_SHAREHOLDERS` fields are required when the customer is adding a new shareholder or director who is not available in the list of stakeholders returned in the Exhaustive Details API. If these documents aren't provided, compliance will request them via RFI. - **PROOF\_OF\_BUSINESS**: This document has to be submitted in case website is not provided. Any document that will help us validate the business of the customer. Proof of Business can be any one of the following documents: - Any document depicting the product catalogue such as company brochures or marketing material or detailed business plan. **\[Preferred]** - Contracts or business agreements or vendor agreements. - Photo of store, in case of brick and mortar store. - Invoice containing clear description of business operations (issued within 1 year) **\[Not preferred]**. - **Corporate structure (Ownership Structure)** This document should be provided if the customer is a multi-layered company. Refer [Multi-layered ownership structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6) to understand if the customer is a multi-layered company. Corporate structure can be drafted by the customer and contains the names of the shareholders, along with the percent of shares held which will help us to establish the ultimate beneficial owner. See below for an example. You can use a similar template, if you don't have one. Use `documentType` = `CORPORATE_STRUCTURE` to add the corporate structure document. Ownership Chart For a complete list of business document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category) API with `fieldName` as `documentType`. ## Stakeholder Documents Stakeholder with positions including `SIGNATORY`, `REPRESENTATIVE`, `UBO`, `TRUSTEE`, `PARTNER` require KYC have 2 choices: E-Document verification flow or Manual KYC. ### `E_DOC_VERIFY` | Documents to be uploaded in Onfido form | Documents to be submitted via API | | :--------------------------------------------------------------------------------------------------------- | :----------------------------------- | | Live Selfie with Passport/National ID submitted in the form presented by Onfido (eDoc verification vendor) | If isPEP= true then Source of wealth | ### `MANUAL_KYC` All the stakeholders with `kycMode` = `MANUAL_KYC` will require to submit documents (`documentDetails` and `documentDetails.document`). Nium accepts Passport or National ID for non-LT stakeholders and only National ID for LT stakeholders for Manual KYC. Additionally, `SOURCE_OF_WEALTH` should be submitted in case the stakeholder is a PEP. If, not submitted, `SOURCE_OF_WEALTH` will be requested via RFI. - National ID should be submitted for Lithuanian stakeholders (nationality is **LT**) and 11 digits Personal Identification Number should be submitted as `documentNumber`. - Any Passport/ National ID that's submitted will go through fraud checks at Nium. In case, the document, doesn't meet our standards, notarized documents will be requested by a RFI. Photocopies or scanned documents in black-and-white are not accepted The following table lists the fields required for each document type. | Field name | For Non-LT stakeholders (nationality is not LT) | Lithuanian stakeholders (nationality=LT) | Additionally if `isPEP`=`Yes` | | :------------------------ | :---------------------------------------------- | :--------------------------------------------- | ----------------------------- | | `documentType` | `PASSPORT` or `NATIONAL_ID` | `NATIONAL_ID` | `SOURCE_OF_WEALTH` | | `documentNumber` | Yes | Yes (11 digits Personal Identification Number) | No | | `documentIssuanceCountry` | Yes | Yes | No | | `documentExpiryDate` | Yes for Passport | No | No | | `document.fileName` | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category) API with `fieldName` as `documentType`. ### `DIRECTOR` `documentDetails` are required when the position is `DIRECTOR` for both eKYB and Manual KYB: - Document files and `documentDetails.document` are not required. - `kycMode`can be ignored for this position. - `documentType` required based on nationality: | Field name | Non-Lithuanian stakeholders (nationality=LT) | Lithuanian stakeholders (nationality=LT) | Additionally, if `isPEP`=`Yes` | | :------------------------ | :-------------------------------------------- | :--------------------------------------------- | ------------------------------ | | `documentType` | `PASSPORT` or `NATIONAL_ID` | `NATIONAL_ID` | `SOURCE_OF_WEALTH` | | `documentNumber` | Yes | Yes (11 digits Personal Identification Number) | No | | `documentIssuanceCountry` | Yes | Yes | No | | `documentExpiryDate` | Yes for Passport | No | No | | `document.fileName` | No | No | Yes | | `document.fileType` | No | No | Yes | | `document.document` | No | No | Yes | For a complete list of personal document types, see the enums listed in [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category) API with `fieldName` set to `documentType`. ### Additional stakeholder documents - **Source Of wealth**: If any of the shareholders is a Politically exposed person (`isPEP` = `Yes`) then `SOURCE_OF_WEALTH` should be submitted as a document for that shareholder. Source of wealth is any document that helps us understand the origin and means of wealth, reflecting the overall accumulated net worth of entity/individual, used to establish and operate a company. A written explanation, accompanied by supporting documentation, must be collected to confirm the legitimacy of the customer’s wealth for conducting business. Examples of supporting documentation for Source of Wealth. - Personal or joint savings, collected in form of bank statements - Employment income, including salaries, bonuses, and pension - Loan agreements - Contract agreements - Sale of assets (real estate, shares) - Inheritances, including family wealth transfer - Compensation from legal settlements - Profits from legitimate business activities or investments - Ownership of businesses or investments, including returns - Other documents, related to customer’s funds or wealth ## Applicant Documents Applicants are always required to complete the E-Document verification flow for both Manual KYB and eKYB. | Uploaded in Onfido form (eDoc vendor) | Submitted via API | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Live selfie with Passport or National ID (captured in the Onfido form) | Power of Attorney (if the role is not DIRECTOR, UBO, PARTNER, or TRUSTEE)Source of Wealth (required if `isPEP = true`) | The following table lists the fields required for each document type. | Field name | If position does not include DIRECTOR / UBO / PARTNER / TRUSTEE | If isPEP=Yes | | :------------------------ | --------------------------------------------------------------- | ------------------ | | `documentType` | `POWER_OF_ATTORNEY` | `SOURCE_OF_WEALTH` | | `documentNumber` | No | No | | `documentIssuanceCountry` | No | No | | `documentExpiryDate` | No | No | | `document.fileName` | Yes | Yes | | `document.fileType` | Yes | Yes | | `document.document` | Yes | Yes | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. ### Additional applicant documents - **Power of Attorney**: In case the applicant is not a **DIRECTOR**, **UBO**, **PARTNER**, **TRUSTEE**, a `POWER_OF_ATTORNEY` is required. This document has to be certified by an apostille in case it is not issued in a EEA country. - See [Letter of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for the Power Of Attorney requirements. - Alternatively an applicant can nominate a director to provide Live-Authorization and avoid physical documents and/or the apostille processes. See [Live-Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for more details. - **Source Of wealth**: See [Additional stakeholder documents> Source of Wealth](#additional-stakeholder-documents) for more details. --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/eu-onboarding/position-mapping Positions required for each business type in the EU: | `businessType` | `DIRECTOR` | `PARTNER` | `REPRESENTATIVE` | `SETTLOR` | `SHAREHOLDER` | `SIGNATORY` | `TRUSTEE` | `UBO` | | ------------------------------- | :--------: | :-------: | :--------------: | :-------: | :-----------: | :---------: | :-------: | :---: | | `ASSOCIATION` | Yes | | Yes | | Yes | Yes | | | | `LIMITED_LIABILITY_PARTNERSHIP` | | Yes | Yes | | | Yes | | Yes | | `GOVERNMENT_ENTITY` | | | Yes | | | Yes | | | | `PRIVATE_COMPANY` | Yes | | Yes | | Yes | Yes | | Yes | | `PUBLIC_COMPANY` | Yes | | Yes | | Yes | Yes | | Yes | | `SOLE_TRADER` | | | Yes | | | Yes | | Yes | | `TRUST` | | | Yes | Yes | | Yes | Yes | Yes | #### Response example Multiple positions in the `professionalDetails` array object as shown below: ```json "professionalDetails": [ { "position": "REPRESENTATIVE" }, { "position": "UBO", "sharePercentage": "50.2", "positionStartDate":"2022-11-30" }, { "position": "SIGNATORY" } ``` --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/eu-onboarding/example-requests To onboard your entity, you can call the Onboard Corporate Customer API. For an example call that you can customize with your information, see: To onboard your entity, you can call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. For an example call that you can customize with your information, see: - [Private companies](#private) - [Trusts](#trust) - [Limited liability partnerships](#llp) - [Live-Authorization](#live-authorization) - [Simulate various scenarios](#simulate-various-scenarios) ## Private companies The following is an API request example call where `businessType = PRIVATE_COMPANY`. ```json { "region": "EU", "businessDetails": { "businessName": "JOHNS ELECTRIC COMPANY", "businessRegistrationNumber": "3121s2aw8293", "businessType": "PRIVATE_COMPANY", "tradeName": "John Electric", "website": "www.JohnPower.com", "legalDetails": { "registeredCountry": "DE", "registeredDate": "2018-11-12" }, "addresses": { "registeredAddress": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" } }, "taxDetails": [ { "country": "DE", "taxNumber": "12223423" } ], "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD", "fileType": "image/png", "document": "" } ] }, { "documentType": "REGISTER_OF_DIRECTORS", "document": [ { "fileName": "RegisterOfDirectors", "fileType": "image/png", "document": "" } ] }, { "documentType": "REGISTER_OF_SHAREHOLDERS", "document": [ { "fileName": "RegisterOfShareholders", "fileType": "image/png", "document": "" } ] }, { "documentType": "CORPORATE_STRUCTURE", "document": [ { "fileName": "Ownership chart", "fileType": "image/png", "document": "" } ] } ], "stakeholders": [ { "referenceId": "29aeb27f-4168-4125-a3b0-fa786f425a7c", "businessPartner": { "businessName": "NEWVILE INC.", "businessRegistrationNumber": "900843822", "businessEntityType": "SHAREHOLDER", "addresses": { "registeredAddress": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" } }, "legalDetails": { "registeredCountry": "DE" }, "sharePercentage": "05.00" } }, { "stakeholderDetails": { "firstName": "JOHN", "kycMode": "MANUAL_KYC", "middleName": "DAVID", "lastName": "SMITH", "nationality": "GB", "birthCountry": "GB", "dateOfBirth": "1981-06-15", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "city": "Eastleigh", "state": "London", "country": "GB", "postcode": "SO53 2FW" }, "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO", "sharePercentage": "10.3", "positionStartDate": "2021-09-23" } ], "taxDetails": [ { "country": "DE", "taxNumber": "12223423" } ], "additionalInfo": { "isPep": "No" }, "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "Z3367529", "documentIssuanceCountry": "GB", "documentExpiryDate": "2029-09-10", "document": [ { "fileName": "Passport", "fileType": "image/png", "document": "" } ] } ] } }, { "referenceId":"08e66e6f-e5b1-4a7e-a807-d9ac907d4213", "stakeholderDetails": { "firstName": "Brad", "kycMode": "E_DOC_VERIFY", "middleName": "P", "lastName": "Pitter", "nationality": "FR", "birthCountry": "FR", "dateOfBirth": "1981-06-15", "address": { "addressLine1": "3 Rue Frédéric Chopin", "city": "Vesoul", "state": "Franche-Comté", "country": "FR", "postcode": "70000" }, "professionalDetails": [ { "position": "UBO", "sharePercentage": "51", "positionStartDate": "2021-09-23" } ], "taxDetails": [ { "country": "FR", "taxNumber": "FR123ASE" } ], "additionalInfo": { "isPep": "No" } } } ], "applicantDetails": { "firstName": "SHELDON", "middleName": "PATTERSON", "lastName": "COOPER", "nationality": "DE", "dateOfBirth": "1981-06-15", "address": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" }, "contactDetails": { "contactNo": "8897681220", "email": "sheldon@garage.com", "countryCode": "DE" }, "professionalDetails": [ { "position": "REPRESENTATIVE" } ], "kycMode": "E_DOC_VERIFY", "birthCountry": "DE", "additionalInfo": { "isPep": "No" } }, "additionalInfo": { "searchId": "e23e8883-a58c-4003-adb3-41e31bc57282", "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "EU011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVEU02", "topTransactionCountries": [ "GB", "FR" ], "topBeneficiaries": [ "Green Corp", "Roberts inc", "Acme" ] }, "credit": { "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVEU02", "topTransactionCountries": [ "IN" ], "topRemitters": [ "Individual contractors", "part time employees" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ], "industryDescription": "Trader of Seeds and fertilizers based in UK." }, "tags": [ { "key": "Tag 1", "value": "Tag value 1" }, { "key": "Tag 2", "value": "Tag value 2" } ] } ``` ## Simulate eKYB If you are using eKYB flow for the EU region, you can generate the following scenarios by using the below steps with the example `businessRegistrationNumber` (BRN) in the following table. | Simulated scenario | Condition on BRN | Example BRN | | | :------------------------------------------------------------------------------------------ | :----------------------------------------------------- | :------------------------------------ | - | | [Action required](#response-conditions-for-the-exhaustive-corporate-details-api) | Contains `C02` | `C02324536`, `234C02456`, `12A02B325` | | | [In progress with documents required](#request-example-in-progress-with-documents-required) | Contains `C03` | `C03324536`, `234C03456`, `12C03B325` | | | [Completing applicant eDocVerify](#completing-applicant-or-stakeholder-edocverify) | Pattern on `applicantDetails.contactDetails.contactNo` | | | **Step 1:** Call the [Public Corporate Details (Lookup)](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) request using the **Business Registration Number** and **Region** that match your test scenario. This request returns the basic company details for the specified business.\ From the response, copy the value of `searchReferenceId` — you’ll need it for the next step. In this response, the `businessName` is always returned as `STAR FINANCE PRIVATE LIMITED` appended by your `businessRegistrationNumber` and doesn't match with what is returned in Step 2. This behavior is only in the sandbox; the accurate name appears in production. **Step 2:** Call the [Exhaustive Corporate Details using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) API using the `searchReferenceId` received in Step 1 for the particular scenario. This returns detailed information about the corporate customer including `searchId`. **Step 3:** Use the example requests in the table and call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Step 4:** Use the redirect URL and complete the **Applicant KYC** section on the Onfido page (or use the simulated scenarios for KYC mentioned below) and wait for the webhook. Verification can be completed with dummy credentials if using Onfido's sandbox. Regardless, you need to open the redirect URL in your browser. ### Response conditions You can generate responses for different `businessType` by following the table below. This can be used for testing the pre-population flow after calling the Exhaustive Corporate Details Using Business ID API. | `businessType` | Condition on `businessRegistrationNumber` | | :------------------------------ | :---------------------------------------- | | `PRIVATE_LIMITED_COMPANY` | Contains `C01` or `C02` or `C03` | | `PUBLIC_COMPANY` | Contains `C11` or `C12` or `C13` | | `SOLE_TRADER` | Contains `C21` or `C22` or `C23` | | `GOVERNMENT_BODY` | Contains `C31` or `C32` or `C33` | | `TRUST` | Contains `C41` or `C42` or `C43` | | `LIMITED_LIABILITY_PARTNERSHIP` | Contains `C51` or `C52` or `C53` | | `ASSOCIATION` | Contains `C61` or `C62` or `C63` | ```json { "region": "EU", "businessDetails": { "businessName": "JOHNS ELECTRIC COMPANY", "businessRegistrationNumber": "C019843274", "businessType": "PRIVATE_COMPANY", "tradeName": "JOHN COMPANY", "legalDetails": { "registeredCountry": "BE", "registeredDate": "2015-07-27" }, "taxDetails": [ { "country": "BE", "taxNumber": "C12431234" } ], "addresses": { "registeredAddress": { "addressLine1": "PUTSTRAAT 457", "addressLine2": "KELBY AVENUE", "city": "SINT TRUIDEN", "state": "BELGIUM", "country": "BE", "postcode": "3800" } }, "stakeholders": [ { "entityType": "CORPORATE", "stakeholderDetails": null, "businessPartner": { "businessName": "TRANQUIL PVT. LTD.", "businessRegistrationNumber": "P652246623", "businessEntityType": "Ultimate Beneficial Owner", "sharePercentage": "4.00", "addresses": { "registeredAddress": null, "businessAddress": null }, "legalDetails": { "registeredCountry": "LT" } } }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "ROB", "middleName": null, "lastName": "DEWULF knmpg", "nationality": "BE", "kycMode": "MANUAL_KYC", "dateOfBirth": "1982-10-10", "birthCountry": "BE", "taxDetails": [ { "country": "BE", "taxNumber": "C1234245" } ], "address": { "addressLine1": "RUE DE BOUILLON 93", "addressLine2": "GROBBENDONK", "city": "GROBBENDONK", "state": "GROBBENDONK", "country": "BE", "postcode": "2078" }, "contactDetails": { "email": "rob@yopmail.com", "contactNo": "41442341111", "countryCode": "BE" }, "professionalDetails": [ { "position": "Shareholder", "sharePercentage": "27.00", "positionStartDate": "2021-10-10" } ], "documentDetails": null, "additionalDetails": { "isPep": "No" } }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "STEVE", "middleName": null, "lastName": "MARTENS gityu", "nationality": "BE", "kycMode": "MANUAL_KYC", "dateOfBirth": "1982-10-10", "birthCountry": "BE", "taxDetails": [ { "country": "BE", "taxNumber": "C1234245" } ], "address": { "addressLine1": "RUE DE BOUILLON 93", "addressLine2": "GROBBENDONK", "city": "GROBBENDONK", "state": "GROBBENDONK", "country": "BE", "postcode": "2078" }, "contactDetails": { "email": "steve@yopmail.com", "contactNo": "41442341111", "countryCode": null }, "professionalDetails": [ { "position": "Director", "sharePercentage": null } ], "documentDetails": null, "additionalDetails": { "isPep": "No" } }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "JARNO", "middleName": null, "lastName": "DESTOMBES otcdx", "nationality": "BE", "kycMode": "MANUAL_KYC", "dateOfBirth": "1982-10-10", "birthCountry": "BE", "taxDetails": [ { "country": "BE", "taxNumber": "C1234245" } ], "address": { "addressLine1": "RUE DES TAILLIS 429", "addressLine2": "GIJZENZELE", "city": "GIJZENZELE", "state": "GIJZENZELE", "country": "BE", "postcode": "2098" }, "contactDetails": { "email": "jarno@yopmail.com", "contactNo": "41442341111", "countryCode": null }, "professionalDetails": [ { "position": "Director", "sharePercentage": null } ], "documentDetails": null, "additionalDetails": { "isPep": "No" } }, "businessPartner": null } ], "additionalInfo": { "searchId": "e0fa4d91-ed80-40be-84c3-d0b493eecdbf", "isSameBusinessAddress": "Yes" }, "applicantDetails": { "firstName": "JARNO", "middleName": null, "lastName": "DESTOMBES kdassq", "nationality": "BE", "kycMode": "E_DOC_VERIFY", "dateOfBirth": "1982-10-10", "birthCountry": "BE", "address": { "addressLine1": "RUE DES TAILLIS 429", "addressLine2": "GIJZENZELE", "city": "GIJZENZELE", "state": "GIJZENZELE", "country": "BE", "postcode": "2098" }, "contactDetails": { "email": "jarno@yopmail.com", "contactNo": "41442341111", "countryCode": "BE" }, "professionalDetails": [ { "position": "Director", "sharePercentage": null, "positionStartDate": "2021-10-10" } ], "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "32874293874", "documentIssuanceCountry": "BE", "documentExpiryDate": "2025-10-10" } ], "additionalDetails": { "isPep": "No" } } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "EU011", "industrySector": "IS144", "countryOfOperation": [ "GB", "US", "SG" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVEU02", "topTransactionCountries": [ "EU", "FR" ], "topBeneficiaries": [ "John Electric", "Acme", "Green way" ] }, "credit": { "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVEU02", "topTransactionCountries": [ "IN" ], "topRemitters": [ "Individual contractors", "part time employees" ] }, "intendedUses": [ "IU002", "IU002" ], "intendedUsesDescription":"Send money to vendors for export settlement" }, "natureOfBusiness":{ "industryCodes":["IS002","IS003" ], "industryDescription": "Trader of Seeds and fertilizers based in UK." } } ``` ### Completing application The applicant or stakeholder eDocVerify is done via the third-party vendor Onfido. Applicant/ stakeholder KYC via Onfido takes place for the EU region when the KYC mode is `E_DOC_VERIFY`. To simulate different success and error responses of the eDocVerify flow, use the following conditions on the applicant's phone number. In all cases, the applicant needs to open the redirect URL in their browser. You either land on the vendor’s page or receive a success/failure redirection back to your KYC redirect URL without any actions needed on the UI. The redirectURL has `isSuccess`, `errorCode`, and `errorMessage` parameters as described in [Applicant KYC](/docs/onboarding/corporate-customers/eu-onboarding#applicant-kyc). Based on `businessDetails.applicantDetails.contactDetails.contactNumber`,`businessDetails.stakeholderDetails.contactDetail.contactNumber` there are two outcomes: | First two digits of `contactNumber` | Resulting situation | | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Doesn't contain any of the simulated patterns | Onfido's sandbox page is opened and the applicant needs to complete the simulated authentication on the UI. This can be used for end-to-end testing. | | Does contain any of the simulated patterns | The customer's browser redirects to your KYC redirect URL without the need of any actions on the UI. Redirection will contain the following [Redirection parameters](#redirection-parameters) | #### Redirection parameters | Return code | Query parameters in the redirection | | :---------- | :---------------------------------------------------------------------------------- | | 91 | `isSuccess`=`true` ; `errorCode`=;`errorMessage`= | | 41 | `isSuccess = false` ; `errorCode = R403`; `errorMessage = documentAlreadySubmitted` | | 51 | `isSuccess = false` ; `errorCode = I500`; `errorMessage = unexpectedError` | ## Simulate - Manual KYB flow You might want to test transactions without going through the onboarding flow. To enable this, Nium provides simulated requests which get auto-approved in the manual KYB flow. You can generate auto-approval scenarios for manual KYB only in the sandbox environment. In production, every application is reviewed by Nium's compliance analysts before approval. | Simulated scenario | Condition on BRN | Example BRN | | :---------------------------------------------- | :--------------- | :------------------------------------ | | [Auto-approval](#request-example-auto-approval) | Contains `M01` | `M01324536`, `234M01456`, `12M01B325` | Call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API with the following example request. ### Request example: auto-approval ```json { "region": "EU", "businessDetails": { "businessName": "KOLBE ELECTRIC COMPANY 1", "businessRegistrationNumber": "320000M01283", "businessType": "PRIVATE_COMPANY", "tradeName": "Johns Electric", "website": "www.johnselectric.com", "legalDetails": { "registeredCountry": "DE", "registeredDate": "2018-11-12" }, "addresses": { "registeredAddress": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" } }, "taxDetails": [ { "country": "DE", "taxNumber": "12223423" } ], "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD", "fileType": "application/pdf", "document": "" } ] }, { "documentType": "REGISTER_OF_DIRECTORS", "document": [ { "fileName": "RegisterOfDirectors", "fileType": "application/pdf", "document": "" } ] }, { "documentType": "REGISTER_OF_SHAREHOLDERS", "document": [ { "fileName": "RegisterOfShareholders", "fileType": "application/pdf", "document": "" } ] } ], "stakeholders": [ { "referenceId": "29aeb27f-4168-4125-a3b0-fa786f425a7c", "businessPartner": { "businessName": "NEWVILE INC.", "businessRegistrationNumber": "900843822", "businessEntityType": "SHAREHOLDER", "addresses": { "registeredAddress": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" } }, "legalDetails": { "registeredCountry": "DE" }, "sharePercentage": "05.00" } }, { "stakeholderDetails": { "firstName": "KATIE", "middleName": "ATIKINSON", "lastName": "RONTAK", "nationality": "GB", "kycMode": "MANUAL_KYC", "dateOfBirth": "1981-06-15", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "city": "Eastleigh", "state": "London", "country": "GB", "postcode": "SO53 2FW" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "taxDetails": [ { "country": "DE", "taxNumber": "12223423" } ], "additionalInfo": { "isPep": "No" }, "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "Z3367529", "documentIssuanceCountry": "GB", "documentExpiryDate": "2026-01-04" } ] } } ], "applicantDetails": { "firstName": "SHELDON", "middleName": "PATTERSON", "lastName": "COOPER", "nationality": "DE", "dateOfBirth": "1981-06-15", "address": { "addressLine1": "Güntzelstrasse 99", "city": "Mehring", "state": "Freistaat Bayern", "country": "DE", "postcode": "84561" }, "contactDetails": { "contactNo": "8897681220", "email": "sheldon@garage.com", "countryCode": "DE" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "kycMode": "E_DOC_VERIFY", "birthCountry": "DE", "additionalInfo": { "isPep": "No" }, "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "Z3367659", "documentIssuanceCountry": "EU", "documentExpiryDate": "2026-01-04" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM005", "annualTurnover": "EU001", "industrySector": "IS053", "countryOfOperation": [ "DE" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVEU02", "topTransactionCountries": [ "EU", "FR" ], "topBeneficiaries": [ "Ryan Air", "Radisson", "London Bus Company" ] }, "credit": { "monthlyTransactionVolume": "MVEU01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVEU02", "topTransactionCountries": [ "IN" ], "topRemitters": [ "Individual contractors", "part time employees" ] }, "intendedUses": [ "IU002", "IU004" ], "intendedUsesDescription":"Send money to vendors for export settlement" }, "natureOfBusiness":{ "industryCodes":["IS002","IS003" ], "industryDescription": "Trader of Seeds and fertilizers based in UK." }, "tags": [ { "key": "Tag 1", "value": "Tag value 1" }, { "key": "Tag 2", "value": "Tag value 2" } ] } ``` --- # HK Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/hk-onboarding This page contains details about the Hong Kong (HK) Know Your Business (KYB) flows and links to the following sub-pages for a quick reference: | Page name | Description | | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | **[HK required parameters](/docs/onboarding/corporate-customers/hk-onboarding/required-parameters)** | This page lists the required API fields of each entity type. | | **[HK required documents](/docs/onboarding/corporate-customers/hk-onboarding/required-documents)** | This page contains tables listing the required documents for verification of the business entity, stakeholders, and applicants. | | **[HK position mapping](/docs/onboarding/corporate-customers/au-onboarding/position-mapping)** | This page gives a quick glance at the required positions of each entity type. | | **[HK request examples](/docs/onboarding/corporate-customers/hk-onboarding/example-requests)** | This page contains API request examples for HK entities. | Nium offers Manual KYB flows for customers in Hong Kong. ## Manual KYB Flow The following steps need to be performed for completing an application via Manual KYB. HK Onboarding For Manual KYB, you need to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API directly. In this flow, the entire request body needs to be passed in the Onboard Corporate Customer API. ### Applicant KYC `E_DOC_VERIFY` and `MANUAL_KYC` are supported for applicants in HK. `E_DOC_VERIFY` is the preferred mode of KYC since it reduces the turnaround time. If required, you can use `Manual_KYC`, however uploading of documents is required for Manual KYC which needs to be sent in `businessDetails.applicantDetails.documentDetails`. For details, see [HK required documents for applicants](/docs/onboarding/corporate-customers/hk-onboarding/required-documents#applicants). The API gateway has a limit of 10 MB for any API request. This makes Upload Document API the preferred way to upload documents since you can upload one document at a time. #### E\_DOC\_VERIFY As a response to the Onboard Corp Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirectURL. The applicant then lands on the KYC vendor's page, where he can complete the KYC verification by uploading his proof of identity and proof of address documents with a live selfie. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium. Redirection can result in the following scenarios, based on the below parameters. - `errorCode` - `errorMessage` - `isSuccess` – This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. | Scenario | Expected action from client | Query parameters in the redirection | | ---------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | The applicant completed the required steps... | Wait for webhook. | `errorCode`: N/A `errorMessage`: N/A `isSuccess`: TRUE | | The document has already been submitted in... | KYC Process is completed. Client needs to wait for webhook. | `errorCode`: R403 `errorMessage`: documentAlreadySubmitted `isSuccess`: FALSE | | The customer has provided incorrect data in... | Ask customer to submit correct data in the vendors page. | `errorCode`: I400 `errorMessage`: vendorValidationError `isSuccess`: FALSE | | Verification failure at the vendor. | The application goes to manual review. The client needs to wait for webhook. | `errorCode`: R401 `errorMessage`: vendorVerificationFailure `isSuccess`: FALSE | | Internal Server error at Nium. | Try after some time or reach out to Nium's support. | `errorCode`: R500 `errorMessage`: internalServerError `isSuccess`: FALSE | | Any unexpected error from the vendor. | Try after some time or reach out to Nium's support. | `errorCode`: I500 `errorMessage`: unexpectedError `isSuccess`: FALSE | | Validation already completed and customer... | KYC Process is completed. The client needs to wait for webhook. | `errorCode`: R606 `errorMessage`: verificationAlreadyCompleted `isSuccess`: FALSE | Based on the scenario, you can implement the next steps as provided in the table above. #### Example - Successful Redirect: ``` https://www.clientRedirectURL.com/?clientId=...&caseId=4ff53849-3d30-45c8-af11-f95c315ce83c&isSuccess=true&errorCode=&errorMessage=f95c315ce83c&isSuccess=true&errorCode=&errorMessage= ``` #### Example - failed redirect: ``` https://www.clientRedirectURL.com/?clientId=...&caseId=4ff53849-3d30-45c8-af11-f95c315ce83c&isSuccess=true&errorCode=&errorMessage= ``` For applicants where the `businessDetails.applicantDetails.address.country` is US, the applicant's address' `state` needs to be a valid 2 letter state code. Use the [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API for a set of valid values. ### Stakeholder KYC Only `MANUAL_KYC` is offered for KYC of Individual stakeholders in Hong Kong. Uploading of documents is required for Manual KYC which needs to be sent in `businessDetails.stakeholders.stakeholderDetails.documentDetails`. For details, see [HK required documents for stakeholders](/docs/onboarding/corporate-customers/hk-onboarding/required-documents#stakeholders). ### Bank Account Details Applicants must submit Bank Account Details of the corporate customer in the `businessDetails.bankAccountDetails` object . This is required per regulations to enable auto-sweep. After submission, the `status` in the response of the Onboard Corporate Customer API is `IN_PROGRESS`. Nium initiates manual verification and sends the response via webhook. The application can get approved at this stage. Any changes in `status` is again communicated via webhook. For the next steps based on the response of the webhook, see [Webhooks](/docs/onboarding/corporate-customers#webhooks). ### Terms and Conditions You must show customers the Nium terms and conditions configured for your `client` resource. You can fetch these specific terms and conditions using our [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions). Customers can only submit the onboarding form once they accept the terms and conditions. To fetch the [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions): 1. Wait for the Onboarding API to return a `customerHashId`. 2. Once returned, call our [Accept Terms and Conditions API](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) and include the `customerHashId`. 3. Show the customer the returned terms and conditions and record their acceptance before allowing them to transact. For more details, see [Terms and Conditions](/docs/onboarding/corporate-customers#terms-and-conditions). --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/hk-onboarding/required-parameters The API fields shown on this page are relevant to Hong Kong (HK) only. To see the full payload, refer to the Onboard Corporate Customer API Reference. The API fields shown on this page are relevant to Hong Kong (HK) only. To see the full payload, refer to the [Onboard Corporate Customer API Reference](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). All fields have a maximum limit of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `region` | The country or geographic region where the corporate end customer is located and is onboarded. To onboard an HK-based customer, use the `HK` value. | Yes | | [businessDetails](#businessDetails) | An object that contains business details about the corporate customer. | Yes | | [riskAssessmentInfo](#riskAssessmentInfo) | An object that contains the risk assessment information. | Yes | | [deviceDetails](#deviceDetails) | An object that contains information about the customer's device and IP address. | Yes | | [tags](#tags) | An object that contains the tags. | No | | `clientId` | This field contains the Nium client ID about the customer. It's received in the response to the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | | `customerHashId` | This field contains the unique customer identifier generated at the time of the customer creation. It's received in the response to the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | ## Table entity API fields The below object table columns apply to the following entity types: - `FOREIGN_COMPANY_OFFICE` - `GENERAL_PARTNERSHIP` - `LIMITED_PARTNERSHIP` - `PRIVATE_COMPANY` - `PUBLIC_COMPANY` - `SOLE_TRADER` ## `businessDetails` object An object that contains business details about the corporate customer. | Property | Description | Required | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `referenceId` | The universally unique identifier (UUID) of the business entity that Nium uses to identify the `businessDetails` entity. If it's not provided, Nium generates one. The UUID is used to respond to a request for information (RFI) or to upload required documents for the business entity. | No | | `businessName` | The name a corporate customer is registered under. | Yes | | `businessRegistrationNumber` | The business registration number. | Yes | | `tradeName` | In case the corporate customer is doing business under a different name than their licensed business name. | Yes | | `website` | The corporate customer's website. | No | | `businessType` | The legal entity type of the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | [legalDetails](#businessDetails-legalDetails) | An object that contains the legal details. | Yes | | [addresses](#businessdetails-addresses) | An object that contains the registered and business addresses of the corporate customer. | Yes | | [bankAccountDetails](#businessDetails-bankAccountDetails) | An object that contains the bank account details of the corporate customer. **Note:** This is required if a client is configured for auto sweep. | Yes \* | | [documentDetails](#businessdetails-documentdetails) | An array of objects that contains the business documents. **Note:** This is required per [HK required documents](/docs/onboarding/corporate-customers/hk-onboarding/required-documents). | Yes | | [stakeholders](#businessdetails-stakeholders) | An array of objects that contains the individual and corporate stakeholders about the corporate customer. | Yes | | [applicantDetails](#businessdetails-applicantdetails) | An object that contains the applicant's details. | Yes | | [additionalInfo](#businessDetails-additionalInfo) | An object that contains additional information about the business. | No | ### `legalDetails` object An object within the `businessDetails` object that contains legal details. | Property | Description | Required | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `registeredDate` | The date the business was registered entered in the `YYYY-MM-DD` format. Registered date cannot be a future date. | Yes | | `registeredCountry` | The country where the business is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | ### `addresses` object An object within the `businessDetails` object that contains registered and business addresses. | Property | Description | Required | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | [registeredAddress](#businessdetails-address-registeredaddress) | An object that contains the address where the business is registered. | Yes | | [businessAddress](#businessdetails-address-businessaddress) | An object that contains the address where the business is mainly conducted, if different than the registered address. **Note:** This is required if `isSameBusinessAddress=No` | Yes \* | #### `registeredAddress` object An object within the `businessDetails.address` object that contains the address details where the corporate customer is registered. | Property | Description | Required | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the registered business. | Yes | | `addressLine2` | The second address line of the registered business. | No | | `city` | The city where the corporate customer is registered. | Yes | | `state` | The state where the corporate customer is registered. | Yes | | `country` | The country where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `postcode` | The postal code where the corporate customer is registered. Pass `0000` for postcode in HK. | Yes | #### `businessAddress` object An object within the `businessDetails.address` object that contains the address details about the principal place of business only when the registered address is different. | Property | Description | Required | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the principal place of business if different than the registered business. \* **Note:** This is required if `isSameBusinessAddress = No`. | Yes \* | | `addressLine2` | The second address line of the principal place of business if different than the registered business. | No | | `city` | The city of the principal place of business if different than the registered address. \* **Note:** This is required if `isSameBusinessAddress = No`. | Yes \* | | `state` | The state of the principal place of business if different than the registered address. \* **Note:** This is required if `isSameBusinessAddress = No`. | Yes \* | | `country` | The country where the principal place of business occurs if different than the registered country. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. \* This is required if `isSameBusinessAddress = No`. | Yes \* | | `postcode` | The postal code where the principal place of business occurs if different than the registered address. \* **Note:** This is required if `isSameBusinessAddress = No`. Pass `0000` for postcode in HK. | Yes \* | ### `bankAccountDetails` object An object within the `businessDetails` object that contains the bank account details of the corporate customer. This is required if a client is configured for auto sweep and for refunds. | Property | Description | Required | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------- | | `accountName` | The name of the beneficiary for the bank account. This field can contain alphanumeric characters and the following special characters: `& . , ( ) _ ' / -`. The maximum length is 140 characters. | Yes | | `bankName` | The name of the bank. The maximum length is 255 characters. | Yes | | `accountNumber` | Account number. This field can contain alphanumeric characters for a maximum length of 35 characters. | Yes | | `currency` | The currency in which the auto sweep has to occur. Allowed currencies are `HKD` and `USD`. | Yes | | `routingType` | Routing type of the bank account. The only valid value is `SWIFT` if currency is `USD` and `SWIFT` or `BANK CODE` if currency is `HKD`. | Yes | | `routingValue` | Routing value for the provided routing type. This field can contain alphanumeric characters. The valid length is either eight or ten characters. | Yes | ### `documentDetails` array An array of objects within the `businessDetails` object that contains one or more business documents. | Property | Description | Required | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | [document](#businessdetails-documentdetails-document) | An array of object that contains a copy of the document. | Yes | #### `document` object An array of objects within the `businessDetails.documentDetails` object such as Business Registration Document or Partnership Deed. You can add multiple files under the same document object such as multiple pages of the Business Registration Document or addendum. | Property | Description | Required | | ---------- | --------------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes | | `document` | The file as a base64 encoded string. | Yes | ### `stakeholders` object An array of objects within the `businessDetails` object that contains information about one or many stakeholders. \* For every stakeholder object, you need to send either the `stakeholderDetails` or the `businessPartner` parameters. | Property | Description | Required | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `referenceId` | The universal unique identifier (UUID) associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | No | | [stakeholderDetails](#businessdetails-stakeholders-stakeholderdetails) | An object that contains the details of the individual stakeholder. | Yes \* | | [businessPartner](#businessdetails-stakeholders-businesspartner) | An object that contains the details of the corporate stakeholder. Required if a corporate stakeholder exists. | Yes \* | #### `stakeholderDetails` object An object within the `stakeholders` object that contains the details of an individual stakeholder. | Property | Description | Required | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | :------: | | `kycMode` | The KYC mode for verifying the individual stakeholder. Valid value is `MANUAL_KYC`. | Yes | | `firstName` | The first name of the individual stakeholder. | Yes | | `middleName` | The middle name of the individual stakeholder. | No | | `lastName` | The last name of the individual stakeholder. | Yes | | `nationality` | The nationality of the individual stakeholder. | Yes | | `dateOfBirth` | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. | Yes | | [professionalDetails](#businessdetails-stakeholders-stakeholderdetails-professionaldetails) | The professional details of the individual stakeholder. This is an array. | Yes | | [address](#businessdetails-stakeholders-stakeholderdetails-address) | An object that contains the residential address of the individual stakeholder. | Yes | | [contactDetails](#businessdetails-stakeholders-stakeholderdetails-contactdetails) | An object that contains the contact details of the individual stakeholder. | No | | [documentDetails](#businessdetails-stakeholders-stakeholderdetails-documentdetails) | An object that contains the document details of the individual stakeholder. This is an array. | Yes | ##### `professionalDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's professional details. | Property | Description | Business entity type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------: | | `position` | The position of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `sharePercentage` | The share percentage of the individual stakeholder in the company. **Note:** If the stakeholder’s position is `UBO`, then the share percentage is a required input parameter. | Yes \* | ##### `applicantDetails.address` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `addressLine1` | The first address line of the individual stakeholder. | Yes | | `addressLine2` | The second address line of the individual stakeholder. | No | | `city` | The city or suburb of the individual stakeholder. | Yes | | `state` | The state of the individual stakeholder. | Yes | | `country` | The country where the individual stakeholder resides. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `postcode` | The postal code of the individual stakeholder. Pass `0000` for postcode in HK. | Yes | ##### `contactDetails` object An optional object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the stakeholder's contact information. | Property | Description | Required | | ----------- | ------------------------------------------------------- | :------: | | `email` | The individual stakeholder's email address. | No | | `contactNo` | The contact phone number of the individual stakeholder. | No | ##### `stakeholderDetails.documentDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's document details. | Property | Description | Required | | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentNumber` | The ID number for the given document type. | Yes | | `documentIssuanceCountry` | The country that issued the business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. This is required if `documentType` is `PASSPORT`. Expiry date cannot be a past date. | Yes \* | | [document](#businessdetails-stakeholders.stakeholderDetails-documentDetails-document) | An array of object that contains the document copy. | Yes | ##### `documentDetails.document` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails.documentDetails` object that contains a copy of the individual stakeholder's document. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes | | `document` | The document saved as a base64 encoded string. | Yes | #### `businessPartner` An object within the `businessDetails.stakeholders` object that contains the business details about the corporate stakeholder. \* This object is required if a corporate stakeholder exists. | Property | Description | Required | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `businessName` | The registered business name of the corporate stakeholder. | Yes | | `businessRegistrationNumber` | The business registration number. | Yes | | `businessEntityType` | The position of the corporate stakeholder in the company. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `sharePercentage` | The share percentage of the corporate stakeholder in the company. **Note:** If the stakeholder’s position is `UBO`, then the share percentage is a required input parameter. | Yes \* | | [legalDetails](#businessdetails-stakeholders-businesspartner-legaldetails) | An object that contains the legal details of the corporate stakeholder. | Yes | ##### `businessPartner.legalDetails` object An object within the `businessDetails.stakeholders.businessPartner` object that contains the corporate stakeholder's legal details. | Property | Description | Required | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `registeredCountry` | The country where the corporate stakeholder is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | ### `applicantDetails` object An object within the `businessDetails` object that contains details about the applicant. | Property | Description | Required | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `referenceId` | The universally unique identifier (UUID) associated with the applicant and applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents. | No | | `kycMode` | The KYC mode for verifying the identity of the applicant. The valid values are `E_DOC_VERIFY` and `MANUAL_KYC` | Yes | | `firstName` | The first name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Yes | | `middleName` | The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces. | No | | `lastName` | The last name or the applicant. The maximum length is 40 alphabetic characters or spaces. | Yes | | `nationality` | Nationality of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Yes | | `dateOfBirth` | The date on which the applicant was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. Applicant age cannot be less than 18 yrs. | Yes | | [professionalDetails](#businessdetails-applicantdetails-professionaldetails) | An array of object that contains the professional details of the applicant. | Yes | | [address](#businessdetails-applicantdetails-address) | An object that contains the address of the applicant. | Yes | | [contactDetails](#businessdetails-applicantdetails-contactdetails) | An object that contains the contact details of the applicant. | Yes | | [documentDetails](#businessdetails-applicantdetails-contactdetails) | An array of object that contains the document details of the applicant. | Yes | #### `professionalDetails` object An array of object within the `businessDetails.applicantDetails` object that contains the professional details about the applicant. | Property | Description | Required | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `position` | The position of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `sharePercentage` | The share percentage of the applicant in the company. **Note:** If the applicant's position is `UBO`, then the share percentage is a required input parameter. | Yes \* | #### `applicantDetails.address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | Property | Description | Required | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the applicant. The maximum character length is 40. | Yes | | `addressLine2` | The second address line of the applicant. The maximum character length is 40. | No | | `city` | The city of the applicant. The maximum character length is 20. | Yes | | `state` | The state of the applicant. The maximum character length is 30. | Yes | | `country` | The country where the applicant resides. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `postcode` | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. Pass `0000` for postcode in HK. | Yes | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object that contains the applicant's contact information. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `email` | The applicant's email address. The maximum length is 40 and needs to be a valid email address. See [Email regex](/docs/developers/nium-api#regular-expression-for-email). | Yes | | `countryCode`. | The country code of the applicant's phone number. | Yes | | `contactNo` | The applicant's phone number. The maximum length is 20 numeric characters. | Yes | #### `usinessDetails.applicantDetails.documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. | Property | Description | Required | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentNumber` | The ID number for the given document type. | Yes | | `documentIssuanceCountry` | The country that issued the business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. This is required if `documentType` is `PASSPORT`. Expiry date cannot be a past date. | Yes \* | | [document](#businessdetails-applicantdetails-documentdetails-document) | An object that contains a copy of the document | Yes \* | ##### `documentDetails.document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains the document copy. \* This is required for `MANUAL_KYC` or if `documentType` is `LOA`. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes \* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes \* | | `document` | The document saved as a base64 encoded string. | Yes \* | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Required | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `isSameBusinessAddress` | This field accepts `Yes` or `No` to indicate if the principal place of business is the same or different from the registered business entity address. **Note:** This is required if `Yes`; it's optional if `No`. | Yes \* | ## `riskAssessmentInfo` object An object that contains the following details which are required to determine a corporate customer's risk profile. | Property | Description | Required | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `totalEmployees` | The corporate customer's total number of employees. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `annualTurnover` | The corporate customer’s annual turnover. If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `industrySector` | The corporate customer's industry sector. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `countryOfOperation` | An array of countries the corporate customer operates in. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `transactionCountries` | An array of countries where the transactions occur. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `intendedUseOfAccount` | The customer's intended use of the account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | ## `deviceDetails` object This object contains the information about the customer's device and IP address where the onboarding request originated. | Property | Description | Association Sole trader Trust | Government Private Public | LLP | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------- | -------- | | `countryIP` | Country of the IP address e.g. US. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `deviceInfo` | Information of the device e.g. Mac OS. | Required | Required | Required | | `ipAddress` | IP address of the device e.g. 45.48.241.198 | Required | Required | Required | | `sessionId` | A unique identifier for the session, generated by your application. | Required | Required | Required | ## `tags` object An optional object that contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15. | Property | Description | Required | | -------- | ------------------------------------------------------------------------------- | :------: | | `key` | The name of the tag. The maximum character length is 128. Key should be unique. | No | | `value` | The value of the tag. The maximum character length is 256. | No | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/corporate-customers/hk-onboarding/required-documents This page outlines the documents required for stakeholders, applicants, and various business types to onboard a corporate customer registered in Hong Kong (HK). ## Business details The following table lists the required document types for both verification types for all business entity types. | `businessType` | Manual KYB | | :----------------------- | :-------------------------------------------------------- | | `FOREIGN_COMPANY_OFFICE` | Any of the most recently lodged `NAR1` or `NNC1` or `NN3` | | `GENERAL_PARTNERSHIP` | `BUSINESS_REGISTRATION_DOC` `PARTNERSHIP_DEED` | | `LIMITED_PARTNERSHIP` | `BUSINESS_REGISTRATION_DOC` `PARTNERSHIP_DEED` | | `OTHER` | Either of the most recently lodged `NAR1` or `NNC1` | | `PRIVATE_COMPANY` | Either of the most recently lodged `NAR1` or `NNC1` | | `PUBLIC_COMPANY` | Either of the most recently lodged `NAR1` or `NNC1` | | `SOLE_TRADER` | `BUSINESS_REGISTRATION_DOC` | For a complete list of business document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category) API with `fieldName` as `documentType`. ## Stakeholders Both residents and non-residents of HK need to use the KYC mode `MANUAL_KYC` ### Manual KYC Every individual stakeholder needs to submit the following information when `kycMode = MANUAL_KYC`. > ⚠️ IMPORTANT > > If the document doesn't contain an address, you need to submit an [Acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) which can verify the address with `documentType = PROOF_OF_ADDRESS`. > > If this additional document is not submitted, the compliance agent will raise an RFI for `stakeholderAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | Field name | Passport | National ID | Additional document if the first document doesn't contain an address | | :------------------------ | :-------------------- | :------------------------------- | :------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes (Use HK ID for HK residents) | No | | `documentIssuanceCountry` | Yes | Yes | No | | `documentExpiryDate` | Yes | No | No | | `document.fileName` | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport or National ID. See [Letter Of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for suggested format of LOA in case you do not have one. ## Applicants `E_DOC_VERIFY` and `MANUAL_KYC` methods are supported for applicants. - In `E_DOC_VERIFY`, applicants need to complete KYC using the redirect URL. Document details need to be passed for `E_DOC_VERIFY` and uploading of document files isn't required. - In `MANUAL_KYC`, applicants need to upload document files along with document details. - `LOA` (Letter of Authorization) is always required for any `kycMode` if the applicant is not a `DIRECTOR` or `UBO` or `PARTNER`. ### `E_DOC_VERIFY` Applicants need to submit one of the following information when `kycMode = E_DOC_VERIFY`. | Field name | Passport | National ID | LOA (if applicant is not a `DIRECTOR` / `UBO` / `PARTNER`) | | :------------------------ | :-------------------- | :------------------------------- | :--------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `LOA` | | `documentNumber` | Yes (Passport number) | Yes (Use HK ID for HK residents) | No | | `documentIssuanceCountry` | Yes | Yes | No | | `documentExpiryDate` | Yes | No | No | | `document.fileName` | No | No | Yes | | `document.fileType` | No | No | Yes | | `document.document` | No | No | Yes | ### `MANUAL_KYC` Applicants need to submit one of the following information when `kycMode = MANUAL_KYC`. > ⚠️ IMPORTANT > > If the document doesn't contain an address, you need to submit an [Acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) which can verify the address with `documentType = PROOF_OF_ADDRESS`. > > If this additional document is not submitted, the compliance agent will raise an RFI for `applicantAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | Field name | Passport | National ID | LOA, if applicant is not a `DIRECTOR`/`UBO`/`PARTNER` | Additional document if the first document doesn't contain an address | | :------------------------ | :-------------------- | :------------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `LOA` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes (Use HK ID for HK residents) | No | No | | `documentIssuanceCountry` | Yes | Yes | No | No | | `documentExpiryDate` | Yes | No | No | No | | `document.fileName` | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | Yes | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport or National ID. ## Acceptable documents for `PROOF_OF_ADDRESS` | Individual stakeholder or applicant | Business details | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | | Utility bills (gas, electric, internet, phone) Financial records (bank statement, mortgage statement) Life, health, or other insurance statement (auto, home, boat) Medical records (doctor, hospital, or clinical) Pay-slip Government-issued letter | Utility bills (gas, electric, internet, phone) Financial records (bank or mortgage statement) Government-issued letter | **NOTE**: The above documents are in addition to the standard documents mentioned in Business, Stakeholder, or Applicant section. These can be passed under the `documentType` `PROOF_OF_ADDRESS`. The above documents cannot be more than 90 days old when submitting. --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/hk-onboarding/position-mapping | businessType | DIRECTOR | PARTNER | REPRESENTATIVE | SHAREHOLDER | SIGNATORY | UBO | | `businessType` | `DIRECTOR` | `PARTNER` | `REPRESENTATIVE` | `SHAREHOLDER` | `SIGNATORY` | `UBO` | | :------------------------ | :--------- | :-------- | :--------------- | :------------ | :---------- | :---- | | `FOREIGN_COMPANY_OFFICE` | Yes | | Yes | Yes | Yes | Yes | | `GENERAL_PARTNERSHIP` | | Yes | Yes | | Yes | | | `LIMITED_PARTNERSHIP` | | Yes | Yes | | Yes | | | `OTHERS` | Yes | | Yes | Yes | Yes | Yes | | `PRIVATE_LIMITED_COMPANY` | Yes | | Yes | Yes | Yes | Yes | | `PUBLIC_COMPANY` | Yes | | Yes | Yes | Yes | Yes | | `SOLE_TRADER` | | | Yes | | Yes | | A **Yes** value means that position can be passed for that `businessType`. A blank table cell means that position is not applicable for that `businessType`. Multiple positions in the `professionalDetails` array object as shown below: ```json "professionalDetails": [ { "position": "REPRESENTATIVE" }, { "position": "UBO", "sharePercentage": "50%" }, { "position": "SIGNATORY" } ``` --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/hk-onboarding/example-requests To onboard your entity, you can call the Onboard Corporate Customer API. For an example call that you can customize with your information, see: To onboard your entity, you can call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. For an example call that you can customize with your information, see: - [Sole traders](#sole-trader) - [Private companies](#private-company) - [Limited partnerships](#limited-partnership) - [Simulate scenarios in the manual KYB flow](#simulate-scenarios-in-the-manual-kyb-flow) ## Sole traders ```JSON { "region": "HK", "businessDetails": { "businessName": "Acme HK", "businessRegistrationNumber": "92238740598", "businessType": "SOLE_TRADER", "tradeName": "Acme", "website": "www.acmehk.com", "legalDetails": { "registeredCountry": "HK", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2055" } }, "bankAccountDetails": { "accountName": "Hong Kong Company", "bankName": "DBS", "accountNumber": "123456", "currency": "HKD", "routingType": "SWIFT", "routingValue": "DHBKHKHH" }, "documentDetails": [ { "documentType": "LOA", "documentNumber": "N118668(E)", "document": [ { "fileName": "LOA", "fileType": "png", "document": "" } ] }, { "documentType": "BUSINESS_REGISTRATION_DOC", "documentNumber": "2348729383", "document": [ { "fileName": "BRD001.pdf", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "John", "middleName": "J", "lastName": "Smith", "dateOfBirth": "1947-02-15", "nationality": "HK", "address": { "addressLine1": "221 Sai Yeung", "addressLine2": "Choi St N", "city": "Sham Shui Po District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "HKId", "fileType": "png", "document": " " } ] } ] } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "Jake", "middleName": "J", "lastName": "Roberts", "dateOfBirth": "1967-02-15", "nationality": "HK", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Causeway Rd", "addressLine2": "Causeway Bay", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "HK686634A", "documentIssuanceCountry": "HK", "document": [ { "fileName": "HKId", "fileType": "png", "document": " " } ] } ], "contactDetails": { "countryCode": "HK", "contactNo": "303351617013", "email": "jack@acmehk.com" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "totalEmployees": "EM009", "annualTurnover": "HK011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "transactionCountries":[ "HK", "US", "CA" ] }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` ## Private companies ```JSON { "region": "HK", "businessDetails": { "businessName": "Acme Incorporation", "businessRegistrationNumber": "123358360598", "businessType": "PRIVATE_COMPANY", "tradeName": "Acme Inc.", "website": "www.acme.com", "legalDetails": { "registeredCountry": "HK", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2055" } }, "bankAccountDetails": { "accountName": "Hong Kong Company", "bankName": "DBS", "accountNumber": "123456", "currency": "HKD", "routingType": "SWIFT", "routingValue": "DHBKHKHH" }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mark", "middleName": "J", "lastName": "Cary", "dateOfBirth": "1947-02-15", "nationality": "HK", "address": { "addressLine1": "221 Sai Yeung", "addressLine2": "Choi St N", "city": "Sham Shui Po District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "HKId", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessEntityType": "UBO", "businessName": "TeleHK LTD", "sharePercentage": "60.00", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "HK" } } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "John", "middleName": "F", "lastName": "Roberts", "dateOfBirth": "1967-02-15", "nationality": "HK", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Causeway Rd", "addressLine2": "Causeway Bay", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "contactDetails": { "countryCode": "HK", "contactNo": "303351617013", "email": "john@acme.com" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "H23424214", "documentIssuanceCountry": "HK" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "HK", "US", "CA" ], "totalEmployees": "EM009", "annualTurnover": "HK011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` ## Limited partnerships ```JSON { "region": "HK", "businessDetails": { "businessName": "Acme Partnership", "businessRegistrationNumber": "19238740598", "businessType": "LIMITED_PARTNERSHIP", "tradeName": "Acme Partners", "website": "www.acmepartners.com", "legalDetails": { "registeredCountry": "HK", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2055" } }, "bankAccountDetails": { "accountName": "Hong Kong Company", "bankName": "DBS", "accountNumber": "123456", "currency": "HKD", "routingType": "SWIFT", "routingValue": "DHBKHKHH" }, "documentDetails": [ { "documentType": "NAR1", "documentNumber": "N118668(E)", "document": [ { "fileName": "NAR1", "fileType": "png", "document": "" } ] }, { "documentType": "LOA", "documentNumber": "N118668(E)", "document": [ { "fileName": "LOA", "fileType": "png", "document": "" } ] }, { "documentType": "PARTNERSHIP_DEED", "documentNumber": "2348729383", "document": [ { "fileName": "PD001", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mary", "middleName": "J", "lastName": "Campbell", "dateOfBirth": "1947-02-15", "nationality": "HK", "address": { "addressLine1": "221 Sai Yeung", "addressLine2": "Choi St N", "city": "Sham Shui Po District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "HKId", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessEntityType": "UBO", "businessName": "Kitchens of Hongkong", "sharePercentage": "60", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "HK" } } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "Jack", "middleName": "J", "lastName": "Smith", "dateOfBirth": "1967-02-15", "nationality": "HK", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Causeway Rd", "addressLine2": "Causeway Bay", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "contactDetails": { "countryCode": "HK", "contactNo": "303351617013", "email": "jack@acme.com" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "H23424214", "documentIssuanceCountry": "HK" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "HK", "US", "CA" ], "totalEmployees": "EM009", "annualTurnover": "HK011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` ## Simulate scenarios in the manual KYB flow You can generate different scenarios for manual KYB only in the sandbox environment. You might want to test transactions without going through the onboarding flow. To enable this, Nium provides simulated requests which get auto-approved in the manual KYB flow. You can generate auto-approval scenarios for manual KYB only in the sandbox environment. In production, every application is reviewed by Nium's compliance analysts before approval. | Simulated scenario | Condition on BRN | Example BRN | | :----------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- | | [Auto-approval](#request-example-auto-approval) | BRN contains `M01` and `stakeholderDetails.firstName` starts with `AA` for all individual stakeholders | BRN: `M01324536`, `234M01456`, `12M01B325` Stakeholder firstName: `AAshutosh`, `AAnthony` | | [Action required](#request-example-action-required) | does not contain `M01` | | | [In progress with documents required](#request-example-in-progress-with-document-required) | | | | [In progress with redirectURL](#request-example-in-progress-with-redirect-url) | Pattern on `applicantDetails.contactDetails.contactNo` | | Call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API with the following example request. ### Request example: auto-approval ```json { "region": "HK", "businessDetails": { "businessName": "Acme", "businessRegistrationNumber": "m01ty6eer8", "businessType": "PRIVATE_COMPANY", "tradeName": "Acme Inc.", "website": "www.acme.com", "legalDetails": { "registeredCountry": "HK", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2055" } }, "bankAccountDetails": { "accountName": "Hong Kong Company", "bankName": "DBS", "accountNumber": "123456", "currency": "HKD", "routingType": "SWIFT", "routingValue": "DHBKHKHH" }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mark", "middleName": "J", "lastName": "Cary", "dateOfBirth": "1947-02-15", "nationality": "HK", "address": { "addressLine1": "221 Sai Yeung", "addressLine2": "Choi St N", "city": "Sham Shui Po District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "HKId", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessEntityType": "UBO", "businessName": "TeleHK LTD", "sharePercentage": "60.00", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "HK" } } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "Mark", "middleName": "L", "lastName": "Johnson", "dateOfBirth": "1995-10-14", "nationality": "IN", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Buldhana Road", "addressLine2": "Taluka Malkapur", "city": "Malkapur", "state": "Maharashtra", "country": "IN", "postcode": "443101" }, "contactDetails": { "countryCode": "HK", "contactNo": "913351617013", "email": "john@hachiko.com" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "682634114855", "documentIssuanceCountry": "IN" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "HK", "US", "CA" ], "totalEmployees": "EM009", "annualTurnover": "HK011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` ### Request example: action required ```json { "region": "HK", "businessDetails": { "businessName": "Acme", "businessRegistrationNumber": "P1201ty6eer8", "businessType": "PRIVATE_COMPANY", "tradeName": "Acme Inc.", "website": "www.acme.com", "legalDetails": { "registeredCountry": "HK", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2055" } }, "bankAccountDetails": { "accountName": "Hong Kong Company", "bankName": "DBS", "accountNumber": "123456", "currency": "HKD", "routingType": "SWIFT", "routingValue": "DHBKHKHH" }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mark", "middleName": "J", "lastName": "Cary", "dateOfBirth": "1947-02-15", "nationality": "HK", "address": { "addressLine1": "221 Sai Yeung", "addressLine2": "Choi St N", "city": "Sham Shui Po District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "HKId", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessEntityType": "UBO", "businessName": "TeleHK LTD", "sharePercentage": "60.00", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "HK" } } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "Mark", "middleName": "L", "lastName": "Johnson", "dateOfBirth": "1995-10-14", "nationality": "IN", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Buldhana Road", "addressLine2": "Taluka Malkapur", "city": "Malkapur", "state": "Maharashtra", "country": "IN", "postcode": "443101" }, "contactDetails": { "countryCode": "HK", "contactNo": "913351617013", "email": "john@hachiko.com" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "682634114855", "documentIssuanceCountry": "IN" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "HK", "US", "CA" ], "totalEmployees": "EM009", "annualTurnover": "HK011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` ### Completing applicant eDocVerify The applicant eDocVerify is done via the third-party vendor Jumio. Applicant KYC via Jumio takes place for the EU region when the KYC mode is `E_DOC_VERIFY`. To simulate different success and error responses of the eDocVerify flow, use the following conditions on the applicant's phone number. In all cases, the applicant needs to open the redirect URL in their browser. You either land on the vendor’s page or receive a success/failure redirection back to your KYC redirect URL without any actions needed on the UI. The redirectURL has `isSuccess`, `errorCode`, and `errorMessage` parameters as described in [Applicant KYC](/docs/onboarding/corporate-customers/hk-onboarding#applicant-kyc). Based on `businessDetails.applicantDetails.contactDetail.contactNumber`, there are two outcomes: | First two digits of `contactNumber` | Resulting situation | | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Doesn't contain any of the simulated patterns | Jumio's sandbox page is opened and the applicant needs to complete the simulated authentication on the UI. This can be used for end-to-end testing. | | Does contain any of the simulated patterns | The customer's browser redirects to your KYC redirect URL without the need of any actions on the UI. Redirection will contain the following [Redirection parameters](#redirection-parameters) | #### Redirection parameters | Return code | Query parameters in the redirection | | :---------- | :---------------------------------------------------------------------------------- | | 91 | `isSuccess`=`true` ; `errorCode`=;`errorMessage`= | | 41 | `isSuccess = false` ; `errorCode = R403`; `errorMessage = documentAlreadySubmitted` | | 51 | `isSuccess = false` ; `errorCode = I500`; `errorMessage = unexpectedError` | | 61 | `isSuccess = false` ; `errorCode = R408`; `errorMessage = redirectUrlExpired` | ### Request example: in progress with redirect URL ```json { "region": "HK", "businessDetails": { "businessName": "Acme", "businessRegistrationNumber": "P1201ty6eer8", "businessType": "PRIVATE_COMPANY", "tradeName": "Acme Inc.", "website": "www.acme.com", "legalDetails": { "registeredCountry": "HK", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2055" } }, "bankAccountDetails": { "accountName": "Hong Kong Company", "bankName": "DBS", "accountNumber": "123456", "currency": "HKD", "routingType": "SWIFT", "routingValue": "DHBKHKHH" }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mark", "middleName": "J", "lastName": "Cary", "dateOfBirth": "1947-02-15", "nationality": "HK", "address": { "addressLine1": "221 Sai Yeung", "addressLine2": "Choi St N", "city": "Sham Shui Po District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "HKId", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessEntityType": "UBO", "businessName": "TeleHK LTD", "sharePercentage": "60.00", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "HK" } } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "John", "middleName": "L", "lastName": "Frank", "dateOfBirth": "1995-10-14", "nationality": "IN", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Buldhana Road", "addressLine2": "Taluka Malkapur", "city": "Malkapur", "state": "Maharashtra", "country": "IN", "postcode": "443101" }, "contactDetails": { "countryCode": "HK", "contactNo": "913351617013", "email": "john@hachiko.com" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "HK", "US", "CA" ], "totalEmployees": "EM009", "annualTurnover": "HK011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` ### Request example: in progress with document required ```json { "region": "HK", "businessDetails": { "businessName": "Acme", "businessRegistrationNumber": "m01ty6eer8", "businessType": "PRIVATE_COMPANY", "tradeName": "Acme Inc.", "website": "www.acme.com", "legalDetails": { "registeredCountry": "HK", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "Wan Chai District", "state": "Hong Kong", "country": "HK", "postcode": "2055" } }, "bankAccountDetails": { "accountName": "Hong Kong Company", "bankName": "DBS", "accountNumber": "123456", "currency": "HKD", "routingType": "SWIFT", "routingValue": "DHBKHKHH" }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mark", "middleName": "J", "lastName": "Cary", "dateOfBirth": "1947-02-15", "nationality": "HK", "address": { "addressLine1": "221 Sai Yeung", "addressLine2": "Choi St N", "city": "Sham Shui Po District", "state": "Hong Kong", "country": "HK", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "HKId", "fileType": "png", "document": "" } ] } ] } }, { "businessPartner": { "businessEntityType": "UBO", "businessName": "TeleHK LTD", "sharePercentage": "60.00", "businessRegistrationNumber": "987600001", "legalDetails": { "registeredCountry": "HK" } } } ], "applicantDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mark", "middleName": "L", "lastName": "Roberts", "dateOfBirth": "1995-10-14", "nationality": "IN", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Buldhana Road", "addressLine2": "Taluka Malkapur", "city": "Malkapur", "state": "Maharashtra", "country": "IN", "postcode": "443101" }, "contactDetails": { "countryCode": "HK", "contactNo": "913351617013", "email": "john@hachiko.com" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "682634114855", "documentIssuanceCountry": "IN" } ] }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "HK", "US", "CA" ], "totalEmployees": "EM009", "annualTurnover": "HK011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` --- # JP Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/jp-onboarding This page contains details about the Japan (JP) Know Your Business (KYB) flows and links to the following sub-pages for a quick reference: | Page name | Description | | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | **[JP Required Parameters](/docs/onboarding/corporate-customers/jp-onboarding/required-parameters)** | This page lists the required API fields of each entity type. | | **[JP Required Documents](/docs/onboarding/corporate-customers/jp-onboarding/required-documents)** | This page contains tables listing the required documents for verification of the business entity, stakeholders, and applicants. | | **[JP Position Mapping](/docs/onboarding/corporate-customers/jp-onboarding/position-mapping)** | This page gives a quick glance at the required positions of each entity type. | | **[JP Request Examples](/docs/onboarding/corporate-customers/jp-onboarding/example-requests)** | This page contains API request examples for HK entities. | Nium offers Manual KYB flows for customers in Japan. ## Manual KYB flow The following steps must be performed to complete an application via Manual KYB. JP Onboarding For Manual KYB, you need to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API directly. In this flow, the entire request body needs to be passed in the Onboard Corporate Customer API. ### Applicant KYC `MANUAL_KYC` are supported for applicants in JP. Uploading of documents is required for Manual KYC which needs to be sent in `businessDetails.applicantDetails.documentDetails`. For details, see [JP required documents for applicants](/docs/onboarding/corporate-customers/jp-onboarding/required-documents#applicant). The API gateway has a limit of 10 MB for any API request. This makes Upload Document API the preferred way to upload documents since you can upload one document at a time. ### Stakeholder KYC Only `MANUAL_KYC` is offered for KYC of Individual stakeholders in Hong Kong. Uploading of documents is required for Manual KYC which needs to be sent in `businessDetails.stakeholders.stakeholderDetails.documentDetails`. For details, see [HK required documents for stakeholders](/docs/onboarding/corporate-customers/jp-onboarding/required-documents#stakeholder). ### Bank account details Applicants must submit Bank Account Details of the corporate customer in the `businessDetails.bankAccountDetails` object. This is required per regulations to enable auto-sweep. After submission, the `status` in the response of the Onboard Corporate Customer API is `IN_PROGRESS`. Nium initiates manual verification and sends the response via webhook. The application can get approved at this stage. Any changes in `status` is again communicated via webhook. For the next steps based on the response of the webhook, see [Webhooks](/docs/developers/notifications-and-webhooks). ### Terms and conditions You must show customers the Nium terms and conditions configured for your `client` resource. You can fetch these specific terms and conditions using our [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions). Customers can only submit the onboarding form once they accept the terms and conditions. To fetch the [Terms And Conditions](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions): 1. Wait for the Onboarding API to return a `customerHashId`. 2. Once returned, call our [Accept Terms and Conditions API](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) and include the `customerHashId`. 3. Show the customer the returned terms and conditions and record their acceptance before allowing them to transact. For more details, see [Terms and Conditions](/docs/onboarding/corporate-customers#terms-and-conditions). --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/jp-onboarding/required-parameters The API fields shown on this page are relevant to Japan (JP) only. To see the full payload, see the Onboard Corporate Customer request. The API fields shown on this page are relevant to Japan (JP) only. To see the full payload, see the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request. All fields have a maximum limit of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `region` | The country or geographic region where the corporate end customer is located and is onboarded. To onboard an JP-based customer, use the `JP` value. | Yes | | [businessDetails](#businessDetails) | An object that contains business details about the corporate customer. | Yes | | [riskAssessmentInfo](#riskAssessmentInfo) | An object that contains the risk assessment information. | Yes | | [deviceDetails](#deviceDetails) | An object that contains information about the customer's device and IP address. | Yes | | [expectedAccountUsage](#expectedAccountUsage) | An object that contains the expected usage of the account | Yes | | [tags](#tags) | An object that contains the tags. | No | | `clientId` | This field contains the Nium client ID about the customer. It's received in the response to the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | | `customerHashId` | This field contains the unique customer identifier generated at the time of the customer creation. It's received in the response to the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | ## Table entity API fields The below object table columns apply to the following entity types: - `PRIVATE_COMPANY` - `PUBLIC_COMPANY` ## `businessDetails` object An object that contains business details about the corporate customer. | Property | Description | Required | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `referenceId` | The universally unique identifier (UUID) of the business entity that Nium uses to identify the `businessDetails` entity. If it's not provided, Nium generates one. The UUID is used to respond to a request for information (RFI) or to upload required documents for the business entity. | No | | `businessName` | The name a corporate customer is registered under. | Yes | | `businessName_local` | The name a corporate customer is registered under in Kanji Language | Yes | | `businessRegistrationNumber` | The business registration number. | Yes | | `tradeName` | In case the corporate customer is doing business under a different name than their licensed business name. | Yes | | `website` | The corporate customer's website. | No | | `businessType` | The legal entity type of the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | [legalDetails](#businessDetails-legalDetails) | An object that contains the legal details. | Yes | | [addresses](#businessdetails-addresses) | An object that contains the registered and business addresses of the corporate customer. | Yes | | [bankAccountDetails](#businessDetails-bankAccountDetails) | An object that contains the bank account details of the corporate customer. **Note:** This is required if a client is configured for auto sweep and refunds. | Yes \* | | [documentDetails](#businessdetails-documentdetails) | An array of objects that contains the business documents. **Note:** This is required per [JP required documents](/docs/onboarding/corporate-customers/jp-onboarding/required-documents). | Yes | | [stakeholders](#businessdetails-stakeholders) | An array of objects that contains the individual and corporate stakeholders about the corporate customer. | Yes | | [applicantDetails](#businessdetails-applicantdetails) | An object that contains the applicant's details. | Yes | | [additionalInfo](#businessDetails-additionalInfo) | An object that contains additional information about the business. | No | ### `legalDetails` object An object within the `businessDetails` object that contains legal details. | Property | Description | Required | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `registeredDate` | The date the business was registered entered in the `YYYY-MM-DD` format. Registered date cannot be a future date. | Yes | | `registeredCountry` | The country where the business is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | ### `addresses` object An object within the `businessDetails` object that contains registered and business addresses. | Property | Description | Required | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | [registeredAddress](#businessdetails-address-registeredaddress) | An object that contains the address where the business is registered. | Yes | | [businessAddress](#businessdetails-address-businessaddress) | An object that contains the address where the business is mainly conducted, if different than the registered address. **Note:** This is required if `isSameBusinessAddress=No` | Yes | #### `registeredAddress` object An object within the `businessDetails.address` object that contains the address details where the corporate customer is registered. | Property | Description | Required | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the registered business. | Yes | | `addressLine2` | The second address line of the registered business. | No | | `city` | The city where the corporate customer is registered. | Yes | | `state` | The state where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `country` | The country where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `postcode` | The postal code where the corporate customer is registered. | Yes | #### `businessAddress` object An object within the `businessDetails.address` object that contains the address details about the principal place of business only when the registered address is different. | Property | Description | Required | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the principal place of business if different than the registered business. \* **Note:** This is required if `isSameBusinessAddress = No`. | Yes \* | | `addressLine2` | The second address line of the principal place of business if different than the registered business. | No | | `city` | The city of the principal place of business if different than the registered address. \* **Note:** This is required if `isSameBusinessAddress = No`. | Yes \* | | `state` | The state of the principal place of business if different than the registered address. \* **Note:** This is required if `isSameBusinessAddress = No`. | Yes \* | | `country` | The country where the principal place of business occurs if different than the registered country. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. \* This is required if `isSameBusinessAddress = No`. | Yes \* | | `postcode` | The postal code where the principal place of business occurs if different than the registered address. \* **Note:** This is required if `isSameBusinessAddress = No` | Yes \* | ### `bankAccountDetails` object An object within the `businessDetails` object that contains the bank account details of the corporate customer. This will be used for refunds. | Property | Description | Required | | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `accountName` | The name of the beneficiary for the bank account. The account name should be in **Katakana** and match bank records. Supported special characters include: `& . , ( ) _ ' / -`. The maximum length is 140 characters. | Yes  | | `bankName` | The name of the bank in English. The maximum length is 255 characters. | Yes  | | `accountNumber` | Account number. This field can contain alphanumeric characters for a maximum length of 35 characters. | Yes  | | `bankAccountType` | Bank Account type as per the Add Beneficiary API | Yes | | `currency` | The primary currency of the bank account. Supported value is `JPY`. | Yes  | | `routingType` | Routing type of the bank account. Only supported value is `BANK CODE` | Yes | | `routingValue` | Routing value of the bank account for the provided routing type. Supports alphanumeric characters. | Yes | | `routingType2` | Additional routing type of the bank account. Only supported value is `BRANCH CODE` | Yes | | `routingValue2` | Routing value of the additional routing type. Supports alphanumeric characters. | Yes | ### `documentDetails` array An array of objects within the `businessDetails` object that contains one or more business documents. | Property | Description | Required | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | [`document`](#businessdetails-documentdetails-document) | An array of object that contains a copy of the document. | Yes | #### `document` object An array of objects within the `businessDetails.documentDetails` object. | Property | Description | Required | | ---------- | --------------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes | | `document` | The file as a base64 encoded string. | Yes | ### `stakeholders` object An array of objects within the `businessDetails` object that contains information about one or many stakeholders. \* For every stakeholder object, you need to send either the `stakeholderDetails` or the `businessPartner` parameters. | Property | Description | Required | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `referenceId` | The universal unique identifier (UUID) associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | No | | [stakeholderDetails](#businessdetails-stakeholders-stakeholderdetails) | An object that contains the details of the individual stakeholder. | Yes \* | | [businessPartner](#businessdetails-stakeholders-businesspartner) | An object that contains the details of the corporate stakeholder. Required if a corporate stakeholder exists. | Yes \* | #### `stakeholderDetails` object An object within the `stakeholders` object that contains the details of an individual stakeholder. | Property | Description | Required | | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `kycMode` | The KYC mode for verifying the individual stakeholder. Valid value is `MANUAL_KYC`. | Yes | | `firstName` | The first name of the individual stakeholder. | Yes | | `firstName_local` | The first name of the individual stakeholder in Kanji Characters. | Yes\* | | `middleName` | The middle name of the individual stakeholder. | No | | `lastName` | The last name of the individual stakeholder. | Yes | | `lastName_local` | The first name of the individual stakeholder in Kanji Characters. | Yes\* | | `nationality` | The nationality of the individual stakeholder. | Yes | | `occupation` | Occupation of the Stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. Required if position is `UBO` or `SIGNATORY` | Yes\* | | `dateOfBirth` | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. | Yes | | [professionalDetails](#businessdetails-stakeholders-stakeholderdetails-professionaldetails) | The professional details of the individual stakeholder. This is an array. | Yes | | [address](#businessdetails-stakeholders-stakeholderdetails-address) | An object that contains the residential address of the individual stakeholder. | Yes | | [contactDetails](#businessdetails-stakeholders-stakeholderdetails-contactdetails) | An object that contains the contact details of the individual stakeholder. | No | | [documentDetails](#businessdetails-stakeholders-stakeholderdetails-documentdetails) | An object that contains the document details of the individual stakeholder. This is an array. | Yes | \* Required fields for Stakeholder Position UBO or Authorised Signatory only and if the nationality is `JP`. ##### `professionalDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's professional details. | Property | Description | Required | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `position` | The position of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `sharePercentage` | The share percentage of the individual stakeholder in the company. | No | ##### `applicantDetails.address` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `addressLine1` | The first address line of the individual stakeholder. | Yes | | `addressLine2` | The second address line of the individual stakeholder. | No | | `city` | The city or suburb of the individual stakeholder. | Yes | | `state` | The state of the individual stakeholder. | Yes | | `country` | The country where the individual stakeholder resides. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `postcode` | The postal code of the individual stakeholder. | Yes | ##### `contactDetails` object An optional object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the stakeholder's contact information. | Property | Description | Required | | ----------- | ------------------------------------------------------- | :------: | | `email` | The individual stakeholder's email address. | No | | `contactNo` | The contact phone number of the individual stakeholder. | No | ##### `stakeholderDetails.documentDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's document details. | Property | Description | Required | | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentNumber` | The ID number for the given document type. | Yes | | `documentIssuanceCountry` | The country that issued the business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. This is required if `documentType` is `PASSPORT` or `DRIVER_LICENSE`. Expiry date cannot be a past date. | Yes | | [document](#businessdetails-stakeholders.stakeholderDetails-documentDetails-document) | An array of object that contains the document copy. | Yes | ##### `documentDetails.document` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails.documentDetails` object that contains a copy of the individual stakeholder's document. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes | | `document` | The document saved as a base64 encoded string. | Yes | #### `businessPartner` An object within the `businessDetails.stakeholders` object that contains the business details about the corporate stakeholder. This object is optional in Japan. | Property | Description | Required | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `businessName` | The registered business name of the corporate stakeholder. | Yes | | `businessRegistrationNumber` | The business registration number. | Yes | | `businessEntityType` | The position of the corporate stakeholder in the company. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `sharePercentage` | The share percentage of the corporate stakeholder in the company. | No | | [legalDetails](#businessdetails-stakeholders-businesspartner-legaldetails) | An object that contains the legal details of the corporate stakeholder. | Yes | ##### `businessPartner.legalDetails` object An object within the `businessDetails.stakeholders.businessPartner` object that contains the corporate stakeholder's legal details. | Property | Description | Required | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `registeredCountry` | The country where the corporate stakeholder is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | ### `applicantDetails` object An object within the `businessDetails` object that contains details about the applicant. | Property | Description | Required | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `referenceId` | The universally unique identifier (UUID) associated with the applicant and applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents. | No | | `kycMode` | The KYC mode for verifying the identity of the applicant. The valid values is `MANUAL_KYC` | Yes | | `firstName` | The first name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Yes | | `firstName_local` | The first name of the applicant in Kanji characters. The maximum length is 40 alphabetic characters or spaces. Required if nationality is `JP` | Yes \* | | `middleName` | The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces. | No | | `lastName` | The last name or the applicant. The maximum length is 40 alphabetic characters or spaces. | Yes | | `lastName_local` | The last name or the applicant in Kanji characters. The maximum length is 40 alphabetic characters or spaces. Required if nationality is `JP` | Yes \* | | `nationality` | Nationality of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Yes | | `dateOfBirth` | The date on which the applicant was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. Applicant age cannot be less than 18 yrs. | Yes | | `occupation` | Occupation of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. Required if position is `UBO` or `SIGNATORY` | Yes\* | | [professionalDetails](#businessdetails-applicantdetails-professionaldetails) | An array of object that contains the professional details of the applicant. | Yes | | [address](#businessdetails-applicantdetails-address) | An object that contains the address of the applicant. | Yes | | [contactDetails](#businessdetails-applicantdetails-contactdetails) | An object that contains the contact details of the applicant. | Yes | | [documentDetails](#businessdetails-applicantdetails-contactdetails) | An array of object that contains the document details of the applicant. | Yes | #### `professionalDetails` object An array of object within the `businessDetails.applicantDetails` object that contains the professional details about the applicant. | Property | Description | Required | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `position` | The position of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `sharePercentage` | The share percentage of the applicant in the company. | No | #### `applicantDetails.address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | Property | Description | Required | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the applicant. The maximum character length is 40. | Yes | | `addressLine2` | The second address line of the applicant. The maximum character length is 40. | No | | `city` | The city of the applicant. The maximum character length is 20. | Yes | | `state` | The state of the applicant. The maximum character length is 30. | Yes | | `country` | The country where the applicant resides. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `postcode` | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. | Yes | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object that contains the applicant's contact information. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `email` | The applicant's email address. The maximum length is 40 and needs to be a valid email address. See [Email regex](/docs/developers/nium-api#regular-expression-for-email) | Yes | | `countryCode`. | The country code of the applicant's phone number. | Yes | | `contactNo` | The applicant's phone number. The maximum length is 20 numeric characters. | Yes | #### `usinessDetails.applicantDetails.documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. | Property | Description | Required | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentNumber` | The ID number for the given document type. | Yes | | `documentIssuanceCountry` | The country that issued the business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. This is required if `documentType` is `PASSPORT` or `DRIVER_LICENSE`. Expiry date cannot be a past date. | Yes \* | | [document](#businessdetails-applicantdetails-documentdetails-document) | An object that contains a copy of the document | Yes \* | ##### `documentDetails.document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains the document copy. \* This is required for `MANUAL_KYC` or if `documentType` is `LOA`. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes \* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes \* | | `document` | The document saved as a base64 encoded string. | Yes \* | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Required | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `isSameBusinessAddress` | This field accepts `Yes` or `No` to indicate if the principal place of business is the same or different from the registered business entity address. **Note:** This is required if `Yes`; it's optional if `No`. | Yes \* | ## `expectedAccountUsage` object This object contains the details regarding the expected usage of the account | Property | Description | Required | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `intendedUses` | Array of Intended uses of the account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | ## `riskAssessmentInfo` object An object that contains the following details which are required to determine a corporate customer's risk profile. | Property | Description | Required | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `totalEmployees` | The corporate customer's total number of employees. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `annualTurnover` | The corporate customer’s annual turnover. If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `industrySector` | The corporate customer's industry sector. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `countryOfOperation` | An array of countries the corporate customer operates in. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `transactionCountries` | An array of countries where the transactions occur. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | ## `deviceDetails` object This object contains the information about the customer's device and IP address where the onboarding request originated. | Property | Description | Required | | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `countryIP` | Country of the IP address e.g. `US`. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Yes | | `deviceInfo` | Information of the device e.g. Mac OS. | Yes | | `ipAddress` | IP address of the device e.g. 45.48.241.198 | Yes | | `sessionId` | A unique identifier for the session, generated by your application. | Yes | ## `tags` object An optional object that contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15. | Property | Description | Required | | -------- | ------------------------------------------------------------------------------- | :------: | | `key` | The name of the tag. The maximum character length is 128. Key should be unique. | No | | `value` | The value of the tag. The maximum character length is 256. | No | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/corporate-customers/jp-onboarding/required-documents This page lists the required documents for stakeholders, applicants, and business types to onboard a corporate customer registered in Japan (JP). ## Business details The table below lists the document types required for Manual KYB verification for all available business entity types. | `businessType` | Manual KYB | | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | | `PRIVATE_COMPANY` | A copy of the corporate registry (登記事項証明書, Tokijiko Shomeisho) is required. This document must be issued within 6 months of submission. | | `PUBLIC_COMPANY` | A copy of the corporate registry (登記事項証明書, Tokijiko Shomeisho) is required. This document must be issued within 6 months of submission. | For a complete list of business document types, see the values listed in the [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category) request using `fieldName` as the `documentType`. ## Stakeholders Each individual stakeholder must submit the following information when `kycMode = MANUAL_KYC`. For each stakeholder, at least one of the following documents must be submitted: - Passport - National ID - Driver's License > ⚠️ IMPORTANT > > If the document does not include an address, you must submit an [acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) to verify the address with `documentType` set to **PROOF\_OF\_ADDRESS**. > > If this additional document is not provided, a compliance agent will issue an RFI (Request for Information) for the `stakeholderAddress`. You can submit the additional document using the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) request. | Field name | Passport | National ID | Driver's License | Additional document required if the first document does not include an address | | :------------------------ | :-------------------- | :------------ | :---------------- | :----------------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVERS_LICENSE` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | | `documentExpiryDate` | Yes | No | Yes | No | | `document.fileName` | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | Yes | **Note:** Photocopies or scanned documents in black-and-white are not accepted. ## Applicants `MANUAL_KYC` methods is supported for applicants. - In `MANUAL_KYC`, applicants need to upload document files along with document details. - `LOA` (Letter of Authorization) is always required. See [Letter of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for suggested format of LOA in case you do not have one. Applicant needs to submit one of these three document (Passport, National ID, Driver's License) along with the LOA. > ⚠️ IMPORTANT > > If the document does not include an address, you must submit an [acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) to verify an address with `documentType` set to **PROOF\_OF\_ADDRESS**. > > If this additional document is not provided, a compliance agent will issue an RFI (Request for Information) for the `stakeholderAddress`. You can submit the additional document using the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) request | Field name | Passport | National ID | Driver's License | LOA when the applicant is *not* a DIRECTOR or UBO | Additional document required if the first document does not include an address | | :------------------------ | :-------------------- | :------------ | :---------------- | :------------------------------------------------ | :----------------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVERS_LICENSE` | `LOA` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | No | | `documentExpiryDate` | Yes | No | Yes | No | No | | `document.fileName` | Yes | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | Yes | Yes | For a complete list of personal document types, see the values listed in the [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category) request with `fieldName` as `documentType`. **Note:** Photocopies or scanned documents in black-and-white are not accepted for Passports or National IDs. ## Proof of Address The following table breaks down the document types that are accepted for `PROOF_OF_ADDRESS`. Please note, the following documents are required in addition to the standard documents mentioned above for [Business details](#business-details), [Stakeholders](#stakeholders), and [Applicants](#applicants). These documents can be submitted with `documentType` as `PROOF_OF_ADDRESS`. | Individual Stakeholder or Applicant | Business Details | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------- | | Utility bills (gas, electric, internet, phone) Financial records (bank statement, mortgage statement) Insurance statements (life, health, auto, home, boat) Medical records (doctor, hospital, or clinic) Pay-slip Government-issued letter | Utility bills (gas, electric, internet, phone) Financial records (bank or mortgage statement) Government-issued letter | **Note**: Documents must be no older than 90 days at the time of submission. --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/jp-onboarding/position-mapping | businessType | DIRECTOR | SHAREHOLDER | SIGNATORY | UBO | | `businessType` | `DIRECTOR` | `SHAREHOLDER` | `SIGNATORY` | `UBO` | | :------------------------ | :--------- | :------------ | :---------- | :---- | | `PRIVATE_LIMITED_COMPANY` | Yes | Yes | Yes | Yes | | `PUBLIC_COMPANY` | Yes | Yes | Yes | Yes | - **Yes** indicates the position is available for the specified `businessType`. - A blank cell indicates the position is not applicable for the specified `businessType`. You can pass multiple positions in the `professionalDetails` array as shown below: ```json "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO", "sharePercentage": "50%" }, { "position": "SIGNATORY" } ] ``` --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/jp-onboarding/example-requests Use the Onboard Corporate Customer request to onboard an entity. Below are examples you can use and update with your entity's information: Use the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request to onboard an entity. Below are examples you can use and update with your entity's information: - [Private companies](#private-companies) - [Public companies](#public-company) ## Private companies Here is an example Onboard Corporate Customer request where `businessType` is **PRIVATE\_COMPANY**. ```json { "region": "JP", "businessDetails": { "businessName": "Sora Co.", "businessName_local": "そらしゃ", "businessRegistrationNumber": "922387405989", "businessType": "PRIVATE_COMPANY", "tradeName": "Sora Co.", "website": "www.soraco.com", "legalDetails": { "registeredCountry": "JP", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "TOKYO", "state": "TY", "country": "JP", "postcode": "2055" } }, "bankAccountDetails": { "accountName":"そらしゃ", "bankName": "Bank of Shanghai (Hong Kong) Limited", "accountNumber": "77989", "currency": "JPY", "bankAccountType": "Saving", "routingType": "SWIFT", "routingValue": "RAKTJPJT", "routingType2": "BRANCH CODE", "routingValue2": "051" }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "documentNumber": "2348729383", "document": [ { "fileName": "BRD001.pdf", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mark", "firstName_local": "标记", "middleName": "J", "lastName": "Roberts", "lastName_local": "罗伯茨", "occupation": "OC0001", "dateOfBirth": "1947-02-15", "nationality": "JP", "address": { "addressLine1": "Shirakawa-Cho-Hirono-493", "addressLine2": "Kamo-Gun", "city": "Gifu", "state": "AI", "country": "JP", "postcode": "509-1108" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "JPId", "fileType": "png", "document": "" } ] } ] } }, { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Jake", "firstName_local": "陳", "middleName": "J", "lastName": "Roberts", "lastName_local": "龍", "occupation": "OC0001", "dateOfBirth": "1947-02-15", "nationality": "JP", "address": { "addressLine1": "Shirakawa-Cho-Hirono-493", "addressLine2": "Kamo-Gun", "city": "Gifu", "state": "AI", "country": "JP", "postcode": "509-1108" }, "professionalDetails": [ { "position": "UBO", "sharePercentage": "5" } ], "documentDetails": [ { "documentType": "DRIVER_LICENCE", "documentNumber": "DL21355", "documentIssuanceCountry": "JP", "documentExpiryDate": "2029-10-01", "document": [ { "fileName": "HKId", "fileType": "png", "document": "" } ] } ] } } ], "applicantDetails": { "kycMode": "MANUAL_KYC", "firstName": "John", "firstName_local": "譲仁", "middleName": "J", "lastName": "Roberts", "lastName_local": "英国", "dateOfBirth": "1967-02-15", "occupation": "OC0001", "nationality": "JP", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Shirakawa-Cho-Hirono-493", "addressLine2": "Kamo-Gun", "city": "Gifu", "state": "AI", "country": "JP", "postcode": "509-1108" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "JP686634A", "documentIssuanceCountry": "JP", "document": [ { "fileName": "JPId", "fileType": "png", "document": "" } ] }, { "documentType": "LOA", "document": [ { "fileName": "LOA", "fileType": "png", "document": "" } ] } ], "contactDetails": { "countryCode": "JP", "contactNo": "303351617013", "email": "jack@soraco.com" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "totalEmployees": "EM009", "annualTurnover": "JP002", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "transactionCountries": [ "HK", "US", "CA" ] }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` ## Public company Here is an example Onboard Corporate Customer request where `businessType` is **PUBLIC\_COMPANY**. ```json { "region": "JP", "businessDetails": { "businessName": "Sora Co.", "businessName_local": "そらしゃ", "businessRegistrationNumber": "922387405989", "businessType": "PUBLIC_COMPANY", "tradeName": "Sora Co.", "website": "www.soraco.com", "legalDetails": { "registeredCountry": "JP", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Rm 1301 13/F", "addressLine2": "Cre Building 303", "city": "TOKYO", "state": "TY", "country": "JP", "postcode": "2055" } }, "bankAccountDetails": { "accountName":"そらしゃ", "bankName": "Bank of Shanghai (Hong Kong) Limited", "accountNumber": "77989", "currency": "JPY", "bankAccountType": "Saving", "routingType": "SWIFT", "routingValue": "RAKTJPJT", "routingType2": "BRANCH CODE", "routingValue2": "051" }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "documentNumber": "2348729383", "document": [ { "fileName": "BRD001.pdf", "fileType": "png", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Mark", "firstName_local": "标记", "middleName": "J", "lastName": "Roberts", "lastName_local": "罗伯茨", "occupation": "OC0001", "dateOfBirth": "1947-02-15", "nationality": "JP", "address": { "addressLine1": "Shirakawa-Cho-Hirono-493", "addressLine2": "Kamo-Gun", "city": "Gifu", "state": "AI", "country": "JP", "postcode": "509-1108" }, "professionalDetails": [ { "position": "DIRECTOR" } ], "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "C668668E", "documentIssuanceCountry": "HK", "document": [ { "fileName": "JPId", "fileType": "png", "document": "" } ] } ] } }, { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "John", "firstName_local": "史密斯", "middleName": "K", "lastName": "Smith", "lastName_local": "史", "occupation": "OC0001", "dateOfBirth": "1947-02-15", "nationality": "JP", "address": { "addressLine1": "Shirakawa-Cho-Hirono-493", "addressLine2": "Kamo-Gun", "city": "Gifu", "state": "AI", "country": "JP", "postcode": "509-1108" }, "professionalDetails": [ { "position": "UBO", "sharePercentage": "5" } ], "documentDetails": [ { "documentType": "DRIVER_LICENCE", "documentNumber": "DL21355", "documentIssuanceCountry": "JP", "documentExpiryDate": "2029-10-01", "document": [ { "fileName": "HKId", "fileType": "png", "document": "" } ] } ] } } ], "applicantDetails": { "kycMode": "MANUAL_KYC", "firstName": "Jack", "firstName_local": "约翰", "middleName": "J", "lastName": "Frost", "lastName_local": "霜", "dateOfBirth": "1967-02-15", "occupation": "OC0001", "nationality": "JP", "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Shirakawa-Cho-Hirono-493", "addressLine2": "Kamo-Gun", "city": "Gifu", "state": "AI", "country": "JP", "postcode": "509-1108" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "JP686634A", "documentIssuanceCountry": "JP", "document": [ { "fileName": "JPId", "fileType": "png", "document": "" } ] }, { "documentType": "LOA", "document": [ { "fileName": "LOA", "fileType": "png", "document": "" } ] } ], "contactDetails": { "countryCode": "JP", "contactNo": "303351617013", "email": "jack@soraco.com" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "totalEmployees": "EM009", "annualTurnover": "JP002", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "transactionCountries": [ "HK", "US", "CA" ] }, "tags": [ { "key": "Tag 1", "value": "Tag 1 HK" }, { "key": "Tag 2", "value": "Tag 2 HK" } ] } ``` --- # NZ Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/nz-onboarding This page contains details about the New Zealand Know Your Business (KYB) flows and links to the following sub-pages for a quick reference: | Page name | Description | | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | **[NZ Required Parameters](/docs/onboarding/corporate-customers/nz-onboarding/required-parameters)** | This page lists the required API parameters of each entity type. | | **[NZ Required Documents](/docs/onboarding/corporate-customers/nz-onboarding/required-documents)** | This page contains tables listing the required documents for verification of the business entity, stakeholders, and applicants. | | **[NZ Position Mapping](/docs/onboarding/corporate-customers/nz-onboarding/position-mapping)** | This page gives a quick glance at the required positions of each entity type. | | **[NZ Request Examples](/docs/onboarding/corporate-customers/nz-onboarding/example-requests)** | This page contains API request examples for NZ entities. | Nium offers eKYB and Manual KYB flows for customers in New Zealand. The eKYB flow is fully automated, allowing corporate customers to be approved within a few minutes of submitting their application, making it the preferred mode for all customers. Onboarded customers in New Zealand can’t use their wallet until it’s first funded from their own bank account. The bank must be one of the approved banks. Make sure your customers know this requirement—wallets remain inactive until the condition is met. ## eKYB flow The following steps are required to complete the eKYB application. NZ Onboarding ## Onboarding Corporate Customers You need to collect all the details required to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API through an onboarding form and call it with the full request body. ### Applicant KYC New Zealand supports all three KYC flows, (`E_KYC`,`E_DOC_VERIFY` and `MANUAL_KYC`). You need to pass the following parameter in the `businessDetails.applicantDetails.kycMode` object: - `E_KYC` for New Zealand residents - `E_DOC_VERIFY` for non-New Zealand residents If required, you can use `Manual_KYC` for non-New Zealander residents, but those applications go through manual review and cannot be verified in real time. Document details are mandatory for all KYC modes but uploading documents is mandatory only for`MANUAL_KYC` mode which needs to be sent in the `businessDetails.applicantDetails.documentDetails` object. For details, see [NZ Required Documents](/docs/onboarding/corporate-customers/nz-onboarding/required-documents#applicants). Upon submission, the `status` in the response of the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API is `IN_PROGRESS`. If any documents are required, the applicant needs to upload them to proceed further. Once done, Nium initiates real-time verification and sends the response via a webhook. The application can be approved at this stage. If it can't be approved, it goes through manual review. Any changes in the`status` is communicated via a webhook. For the next steps based on the response of a webhook, see [Webhooks](/docs/developers/notifications-and-webhooks). ### Applicant E\_DOC\_VERIFY As a response to the Onboard Corp Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirectURL. The applicant then lands on the KYC vendor's page, where he can complete the KYC verification by uploading his proof of identity and proof of address documents with a live selfie. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium. Redirection can result in the following scenarios, based on the below parameters. - `errorCode` - `errorMessage` - `isSuccess` – This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. | Scenario | Expected action | Query parameters in the redirection | | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | The applicant completes the required steps in the vendor’s UI. | Client needs to wait for the webhook. | `errorCode`: N/A `errorMessage`: N/A `isSuccess`: TRUE | | The document is submitted in the vendor's UI. | KYC Process is complete. Client needs to wait for the webhook. | `errorCode`: R403 `errorMessage`: documentAlreadySubmitted `isSuccess`: FALSE | | The customer provides incorrect data in the vendor's UI. | You ask customer to submit correct data on the vendor's page. | `errorCode`: I400 `errorMessage`: vendorValidationError `isSuccess`: FALSE | | Verification fails at the vendor. | The application goes to manual review. The client needs to wait for webhook. | `errorCode`: R401 `errorMessage`: vendorVerificationFailure `isSuccess`: FALSE | | An internal server error occurs at Nium. | Try after some time or reach out to Nium's support. | `errorCode`: R500 `errorMessage`: internalServerError `isSuccess`: FALSE | | Any unexpected error occurs from the vendor. | Try after some time or reach out to Nium's support. | `errorCode`: I500 `errorMessage`: unexpectedError `isSuccess`: FALSE | | Validation is complete and customer retries the same link. | KYC Process is completed. The client needs to wait for the webhook. | `errorCode`: R606 `errorMessage`: verificationAlreadyCompleted `isSuccess`: FALSE | Based on the scenario, you can implement the next steps as provided in the table above. **Example of a redirect to the client in a successful case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11-f95c315ce83c&isSuccess=true&errorCode=&errorMessage= ``` #### Example - Successful Redirect ``` https://www.clientRedirectURL.com/?clientId=...&caseId=4ff53849-3d30-45c8-af11-f95c315ce83c&isSuccess=true&errorCode=&errorMessage= ``` For applicants where the `businessDetails.applicantDetails.address.country` is `US`, the applicant's address' `state` needs to be a valid 2 letter state code. Use [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API for acceptable values. If the applicant’s `businessDetails.applicantDetails.address.country` is set to **GB**, the value of the applicant's postcode must follow the `SW4 6EH` format. ### Stakeholder KYC The `E_KYC` and `MANUAL_KYC` modes are offered for KYC of Individual stakeholders in the eKYB flow in New Zealanders. For stakeholders, you pass `E_KYC` (for NZ residents) or `MANUAL_KYC` (for non-NZ residents) in `businessDetails.stakeholders.stakeholderDetails.kycMode`. Applications with `MANUAL_KYC` go through manual review and cannot be verified in real-time. Document details are mandatory for all KYC modes but uploading of documents is mandatory only for `MANUAL_KYC` which has to be sent in `businessDetails.stakeholders.stakeholderDetails`. See [NZ required documents](/docs/onboarding/corporate-customers/nz-onboarding/required-documents#stakeholders-and-applicants) for details. ### Uploading documents If no results are returned as part of the [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API for the particular `businessRegistrationNumber`, you need to upload documents since Nium doesn't retrieve certain required information from some of its sources. If the [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) request returns a match, you generally don't need to upload documents. However, even in this flow, there might be a particular scenario that requires the applicant to provide some documents. Documents can be submitted either of two ways: - As part of the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API - Using the [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request The [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) API is preferred since it uploads one document at a time, which reduces the loading time. This API can be called only while the application is in the `IN_PROGRESS` state. You can use the `remarks` field to list which documents Nium is expecting, in the response of both APIs. The API gateway has a limit of 10 MB for any API request. This makes Upload Document API the preferred way to upload documents since you can upload one document at a time. For the entire list of required documents for manual KYB and eKYB flows, see [NZ required documents](/docs/onboarding/corporate-customers/nz-onboarding/required-documents). #### Terms and Conditions You must show customers the Nium terms and conditions configured for your `client` resource. You can fetch these specific terms and conditions using our [Terms And Conditions](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions) endpoint. Customers can only submit the onboarding form once they accept the terms and conditions. To fetch [Terms And Conditions](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions): 1. Wait for the Onboarding API to return a `customerHashId`. 2. Once returned, call our [Accept Terms and Conditions API](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) and include the `customerHashId`. 3. Show the customer the returned terms and conditions and record their acceptance before allowing them to transact. For more details, see [Terms and Conditions](/docs/onboarding/corporate-customers#terms-and-conditions). ### Webhook response After submission, the `status` in the Onboard Corporate Customer response is `IN_PROGRESS`. The applicant needs to complete both the [Applicant KYC](#applicant-kyc) and [Upload documents](#upload-documents) steps to proceed further. Once done, Nium initiates real-time verification and sends the response via a webhook. The application might be approved at this stage; and if it isn't approved, the application goes through a manual review. Any changes in the `status` is again communicated via a webhook. For the next steps based on the response of the webhook, see [Webhooks](/docs/onboarding#webhooks). ## Manual KYB flow The `MANUAL_KYB` process is similar to eKYB. The one exception is that documents are mandatory in all cases. NZ Onboarding - Manual KYB 1. The manual KYB flow requires the submission of business documents. You can send them using the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request or with the [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request under the `businessDetails.documentDetails` section. Nium doesn't initiate verification until all required documents are submitted.\ The [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request is preferred since it can upload one document at a time, which reduces loading times. 2. The applicant KYC is the same as the eKYB flow. For details on implementing `E_DOC_VERIFY`, see [Applicant `E_DOC_VERIFY`](#applicant-e_doc_verify). 3. Only the `MANUAL_KYC` process is offered for individual stakeholders. You need to pass `MANUAL_KYC` in the `businessDetails.applicantDetails.kycMode` object. You need to upload your documents. Send the information in the `businessDetails.stakeholders.stakeholderDetails.documentDetails\` object.\ For details, see [NZ Required Documents](/docs/onboarding/corporate-customers/nz-onboarding/required-documents). 4. Terms and Conditions flow is same as mentioned in the eKYB flow. Once the request is submitted, the next steps are the same as those in the eKYB process, except that all applications are required to go through the manual review. For the next steps, see [Corporate Customer](/docs/onboarding). --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/nz-onboarding/required-parameters The API fields shown on this page are relevant to New Zealand only. To see the full payload, refer to the Onboard Corporate Customer API Reference. The API fields shown on this page are relevant to New Zealand only. To see the full payload, refer to the [Onboard Corporate Customer API Reference](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). All fields have a maximum limit of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `region` | The country or geographic region where the corporate end customer is located and is onboarded. To onboard an NZ-based customer, use the `NZ` value. | Yes | | [businessDetails](#businessDetails) | An object that contains business details about the corporate customer. | Yes | | [riskAssessmentInfo](#riskAssessmentInfo) | An object that contains the risk assessment information. | Yes | | [expectedAccountUsage](#expectedAccountUsage) | An object that contains the expected usage of the account | Yes | | [tags](#tags) | An object that contains the tags. | No | | [deviceDetails](#deviceDetails) | An object that contains information about the customer's device and IP address. | Yes | | `clientId` | This field contains the Nium client ID of the customer. It's received in the response of the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | | `customerHashId` | This field contains the unique customer identifier generated at the time of the customer creation. It's received in the response of the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | ## Request parameters The below Request parameters refer to the `businessType` fields page: | Association Private Sole trader | Government Partnership Public | Trust | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------- | | `CLUB_ASSOCIATION` `PRIVATE_COMPANY` `SOLE_TRADER` `CO_OPERATIVE` | `GOVERNMENT_ENTITY` `GENERAL_PARTNERSHIP` `LIMITED_PARTNERSHIP` `PUBLIC_COMPANY` | `TRUST` | ## `businessDetails` object An object that contains business details about the corporate customer. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------- | ------------- | | `referenceId` | The universally unique identifier (UUID) of the business entity that Nium uses to identify the `businessDetails` entity. If it's not provided, Nium generates one. The UUID is used to respond to a request for information (RFI) or to upload required documents for the business entity. | Optional | Optional | Optional | | `businessName` | The name a corporate customer is registered under. | Required | Required | Required | | `businessRegistrationNumber` | The business registration number. This field accepts only 13-digit BRN. | Required | Required | Required | | `tradeName` | Another name that the corporate customer uses to do business under, which is different than their licensed business name. | Optional | Optional | Optional | | `hasNominee` | Boolean value stating if the entity has nominee stakeholders. | Required | Required | Required | | `isCashIntensiveBusiness` | Boolean value stating if the entity is cash-intensive. Following question should be asked to the customer as is: "Do you deal in physical cash in your business or collect cash deposits? Example: Casino, Supermarket, Foreign exchange Store". | Required | Required | Required | | `website` | The corporate customer's website. | Optional | Optional | Optional | | `businessType` | The legal entity type of the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | [legalDetails](#businessDetails-legalDetails) | An object that contains the legal details. | Required | Required | Required | | [regulatoryDetails](#businessDetails-regulatoryDetails) | The regulatory details about the corporate customer. | N/A | N/A | Required | | [addresses](#businessdetails-addresses) | An object that contains the registered and business addresses of the corporate customer. | Required | Required | Required | | [documentDetails](#businessdetails-documentdetails) | An array of objects that contains the business documents. Required when the `businessDetails.businessType` is one of the following: `GENERAL_PARTNERSHIP` `LIMITED_PARTNERSHIP` `TRUST` | Optional | Required \\\* | Required | | [bankAccountDetails](#businessDetails-bankAccountDetails) | An object that contains the bank account details of the corporate customer. | Required | Required | Required | | [stakeholders](#businessdetails-stakeholders) | An array of objects that contains the individual and corporate stakeholders of the corporate customer. | Required \\\* | Required \\\* | Required \\\* | | [applicantDetails](#businessdetails-applicantdetails) | An object that contains the applicant's details. | Required | Required | Required | | [additionalInfo](#businessDetails-additionalInfo) | An object that contains additional information about the business. | Optional | Optional | Optional | ### `legalDetails` object An object within the `businessDetails` object that contains the corporate customer's legal details. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | -------- | | `registeredDate` | The date the business is registered entered in the `YYYY-MM-DD` format. Registered date cannot be a past date. | Required | Required | Required | | `registeredCountry` | The country where the business is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `isRegistered` | Boolean value if the club, association, or co-operative is registered. Required only for `CLUB_ASSOCIATION`, `CO_OPERATIVE`. | Required \\\* | N/A | N/A | | `listedExchange` | The exchange where the business is publicly listed. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. **Note:** This field is required for a `PUBLIC_COMPANY`. | N/A | Required \\\* | N/A | ### `regulatoryDetails` object An object within the `businessDetails` object that contains the regulatory details about the corporate customer. This object is required if `businessDetails.businessType` is `TRUST`. | Property | Description | Trust | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `unregulatedTrustType` | The unregulated trust type detail. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. This field is an array. | Required | ### `associationDetails` object An object within the `businessDetails` object that contains the association details. - Required if `isRegistered` = `true` - Optional if `businessDetails.businessType = CLUB_ASSOCIATION` or `CO_OPERATIVE`. | Property | Description | Association Private Sole trader | Government Partnership Public | Regulated trust Unregulated trust | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ---------------------------------- | | `associationName` | The complete name of the association. Applicable for `CLUB_ASSOCIATION`. Required if `isRegistered` = `true`, optional for `false`. | Required \* | N/A | N/A | | `associationNumber` | The association number issued by the applicable state or territory. This value must be a number. Required for `CLUB_ASSOCIATION` when `isRegistered` is `true`; optional when `false`. | Required \* | N/A | N/A | | `associationChairPerson` | The full name of the association chair, secretary, or treasurer. Applicable for `CLUB_ASSOCIATION`. Required if `isRegistered` = `true`, optional for `false`. | Required \* | N/A | N/A | ### `addresses` object An object within the `businessDetails` object that contains one or more business addresses. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ------------- | | [registeredAddress](#businessdetails-address-registeredaddress) | An object that contains the address where the business is registered. | Required | Required | Required | | [businessAddress](#businessdetails-address-businessaddress) | An object that contains the address where the business is mainly conducted, if different than the registered address. **Note:** This is required if `isSameBusinessAddress = No`. | Required \\\* | Required \\\* | Required \\\* | #### `registeredAddress` object An object within the `businessDetails.addresses` object that contains the address details where the corporate customer is registered. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | -------- | | `addressLine1` | The first address line of the registered business. | Required | Required | Required | | `addressLine2` | The second address line of the registered business. | Optional | Optional | Optional | | `city` | The city where the corporate customer is registered. | Required | Required | Required | | `state` | The state where the corporate customer is registered. | Required | Required | Required | | `country` | The country where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `postcode` | The postal code where the corporate customer is registered. | Required | Required | Required | #### `businessAddress` object An object within the `businessDetails.addresses` object that contains the address details about the principal place of business only when the registered address is different. \* This object is required if `businessDetails.additionalInfo.isSameBusinessAddress = No`. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------- | ------------- | | `addressLine1` | The first address line of the principal place of business if different than the registered business. | Required \\\* | Required \\\* | Required \\\* | | `addressLine2` | The second address line of the principal place of business if different than the registered business. | Optional | Optional | Optional | | `city` | The city of the principal place of business if different than the registered address. | Required \\\* | Required \\\* | Required \\\* | | `state` | The state of the principal place of business if different than the registered address. | Required \\\* | Required \\\* | Required \\\* | | `country` | The country where the principal place of business occurs if different than the registered country. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \\\* | Required \\\* | Required \\\* | | `postcode` | The postal code where the principal place of business occurs if different than the registered address. | Required \\\* | Required \\\* | Required \\\* | ### `documentDetails` object An array of objects within the `businessDetails` object that contains one or more business documents. Mandatory if `businessDetails.businessType` is one of the following: - `LIMITED_PARTNERSHIP` - `GENERAL_PARTNERHIP` - `TRUST` | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | -------- | | `documentType` | The type of business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \\\* | Required \\\* | Required | | [document](#businessdetails-documentdetails-document) | An array of objects that contains a copy of the document. | Required \\\* | Required \\\* | Required | #### `document` object An array of objects within the `businessDetails.documentDetails` object. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ---------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | -------- | | `fileName` | The name of the file. | Required \\\* | Required \\\* | Required | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \\\* | Required \\\* | Required | | `document` | The file as a base64 encoded string. | Required \\\* | Required \\\* | Required | ### `bankAccountDetails` object An object within the `businessDetails` object that contains the bank account details of the corporate customer. This will be used for refunds. | Property | Description | Required | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `accountName` | The name of the beneficiary of the bank account. Supports alphanumeric characters and the following special characters: `& . , ( ) _ ' / -`. The maximum length is 140 characters. | Yes | | `bankName` | The name of the bank. Maximum length is 255 characters. | Yes | | `accountNumber` | The bank account number, which can include letters and numbers. Use the format XXYYYY999999999, where:XX: 2-digit bank codeYYYY: 4-digit branch code999999999: 9- or 10-digit account number | Yes | | `currency` | Currency of the banZk account. Only supported value is `NZD` | Yes | | `routingType` | Routing type of the bank account. Only supported value is `SWIFT`. | No | | `routingValue` | Routing value of the bank account. Supports alphanumeric characters. Accepted length is either eight or ten characters. | No | | `routingType2` | Additional routing type of the bank account. Only supported value is `BRANCH CODE`. | No | | `routingValue2` | Routing value for the additional routing type of the bank account. | No | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | -------- | | `isSameBusinessAddress` | This field accepts `Yes` or `No` to indicate if the principal place of business is the same or different from the registered business entity address. | Optional | Optional | Optional | ### `stakeholders` array An array of objects within the `businessDetails` object that contains information about one or many stakeholders. For every stakeholder object, you need to send either the `stakeholderDetails` or the `businessPartner` parameters. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ------------- | | `referenceId` | The UUID associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | Optional | Optional | Optional | | [stakeholderDetails](#businessdetails-stakeholders-stakeholderdetails) | An object that contains the details about the individual stakeholders. | Required \\\* | Optional | Required \\\* | | [businessPartner](#businessdetails-stakeholders-businesspartner) | An object that contains the details about the corporate stakeholders, if available. **Note:** This is required only if a business partner exists. | Required \\\* | Optional | Required \\\* | #### `stakeholderDetails` object An object within the `stakeholders` object that contains the details about an individual stakeholder. This object is required if individual stakeholder. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | -------- | | `kycMode` | The KYC mode for verifying the individual stakeholder. Valid values are `E_KYC` and `MANUAL_KYC`. | Required | Required | Required | | `firstName` | The given name of the individual stakeholder. | Required | Required | Required | | `middleName` | The middle name of the individual stakeholder. | Optional | Optional | Optional | | `lastName` | The last name of the individual stakeholder. | Required | Required | Required | | `nationality` | The nationality of the individual stakeholder. | Required | Required | Required | | `dateOfBirth` | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. | Required | Required | Required | | [professionalDetails](#businessdetails-stakeholders-stakeholderdetails-professionaldetails) | An array of objects that contains the individual stakeholder's professional details. | Required | Required | Required | | [address](#businessdetails-stakeholders-stakeholderdetails-address) | An object that contains the residential address of the individual stakeholder. | Required | Required | Required | | [documentDetails](#businessdetails-stakeholders-stakeholderdetails-documentdetails) | An array of objects that contains the document details about the individual stakeholder. | Required | Required | Required | ##### `stakeholderDetails.professionalDetails` array An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's professional details. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ------------ | | `position` | The position of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `capitalContribution` | The capital contribution of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values using `capitalContribution` as the category. Required for `UBO`, `SHAREHOLDER`, `TRUSTEE` and `PARTNER`. | Required\\\* | Required\\\* | Required\\\* | | `hasDistributionRight` | Boolean value stating if the stakeholder has distribution rights. Required for `UBO`, `SHAREHOLDER` and `PARTNER`. | Required\\\* | Required\\\* | Required\\\* | | `interestPercentage` | Number between 0-100 stating the interest percentage of the stakeholder. Trust beneficiary interest percentage to be collected for trust beneficiary position. Partner interest percentage to be collected for partner position. | N/A | Required\\\* | Required\\\* | | `trustBeneficiaryClass` | Class of trust beneficiary. Applicable only if the stakeholder position is a trust beneficiary. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | N/A | N/A | Required\\\* | | `votingRights` | Array of voting rights of the stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. Required for `UBO`s, `SHAREHOLDER`, `PARTNER`. | Required\\\* | Required\\\* | Required\\\* | | `sharePercentage` | Number between 0-100 stating the percentage of shares owned by the stakeholder. Required only for `UBO`, `SHAREHOLDER`, `TRUSTEE` and `PARTNER`. | Required\\\* | Required\\\* | Required\\\* | ##### `applicantDetails.address` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ------------- | | `addressLine1` | The first address line of the individual stakeholder's residential address. If `kycMode = E_KYC` then the following needs to be passed in this field as comma-separated values: unit number (if available) street number street name | Required \\\* | Required \\\* | Required \\\* | | `addressLine2` | The second address line of the individual stakeholder's residential address. **Note:** If `kycMode = E_KYC` then `streetType` needs to be passed in this field. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \\\* | Required \\\* | Required \\\* | | `city` | The city or suburb of the individual stakeholder. If `kycMode = E_KYC` then suburb needs to be passed in this. | Required \\\* | Required \\\* | Required \\\* | | `state` | The state of the individual stakeholder's residential address. If `country` is **NZ** use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \\\* | Required \\\* | Required \\\* | | `country` | The country of the individual stakeholder's residential address. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \\\* | Required \\\* | Required \\\* | | `postcode` | The postal code of the individual stakeholder's residential address. | Required \\\* | Required \\\* | Required \\\* | ##### `stakeholderDetails.documentDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's document details. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ------------- | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `documentNumber` | The ID number for the given document type. | Required | Required | Required | | `documentIssuanceCountry` | The country that issued the business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `documentReferenceNumber` | Required for Driver's License when kycMode is `E_KYC`. `driversLicenceVersionNumber` must be passed in this field. Alphanumeric with a length of 3. | Required \\\* | Required \\\* | Required \\\* | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. Date of expiry cannot be a past date. Required only for Passport or Drivers License. | Required \\\* | Required \\\* | Required \\\* | | [`document`](#businessDetails-stakeholders-stakeholderDetails-documentDetails-document) | A copy of the document. | Required \\\* | Required \\\* | Required \\\* | ##### `document` An array of object within the `businessDetails.stakeholders.stakeholderDetails.documentDetails` object that contains a copy of the document. \* Required if the `kycMode` **MANUAL\_KYC**. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ---------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ------------- | | `fileName` | The name of the file. | Required \\\* | Required \\\* | Required \\\* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \\\* | Required \\\* | Required \\\* | | `document` | The document saved as a base64 encoded string. | Required \\\* | Required \\\* | Required \\\* | #### `businessPartner` An object within the `businessDetails.stakeholders` object that contains the business details about the corporate stakeholder. \* This object is required if a corporate stakeholder is trustee of a trust. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ------------- | | `businessName` | The registered business name of the corporate stakeholder. | Required \\\* | Required \\\* | Required \\\* | | `businessRegistrationNumber` | The business registration number. Should be 13 digit numeric in case registeredCountry = `NZ`. | Required \\\* | Required \\\* | Required \\\* | | `businessType` | The legal entity type of the business. | Required \\\* | Required \\\* | Required \\\* | | `businessEntityType` | The position of the corporate stakeholder in the company. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \\\* | Required \\\* | Required \\\* | | `capitalContribution` | The capital contribution of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values using `capitalContribution` as the key. Required for Trustees. | Optional | Optional | Required \\\* | | [legalDetails](#businessDetails-stakeholders-businessPartner-legalDetails) | The corporate stakeholder's legal details. | Required \\\* | Required \\\* | Required \\\* | | `sharePercentage` | Number between 0-100 stating the percentage of Shares owned by the stakeholder. Required only for trustee entity type. | Optional | Optional | Required \\\* | ##### `businessPartner.legalDetails` object An object within the `businessDetails.stakeholders.businessPartner` object that contains the corporate stakeholder's legal details. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | ------------- | | `registeredCountry` | The country where the corporate stakeholder is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required \\\* | Required \\\* | Required \\\* | ### `applicantDetails` object An object within the `businessDetails` object that contains details about the applicant. | Property | Description | Association Private Sole trader | Government Partnership Public | Trust | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | -------- | | `referenceId` | The UUID associated with the applicant and the applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents. | Optional | Optional | Optional | | `kycMode` | The KYC mode for verifying the identity of the applicant. Valid values are `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC`. | Required | Required | Required | | `firstName` | The first name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Required | Required | Required | | `middleName` | The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Optional | Optional | Optional | | `lastName` | The last name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Required | Required | Required | | `nationality` | The nationality of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `dateOfBirth` | The date on which the applicant was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. Applicant cannot be below 18 years of age. | Required | Required | Required | | [professionalDetails](#businessdetails-applicantdetails-professionaldetails) | An array of objects that contains the applicant's professional details. | Required | Required | Required | | [address](#businessdetails-applicantdetails-address) | An object that contains the applicant's residential address. | Required | Required | Required | | [contactDetails](#businessDetails-applicantDetails-contactDetails) | The contact details of the applicant. | Required | Required | Required | | [documentDetails](#businessdetails-applicantdetails-contactdetails) | An array of objects that contains the applicant's document details. | Required | Required | Required | #### `applicantDetails.professionalDetails` array An array of objects within the `businessDetails.applicantDetails` object to contain the professional details about the applicant. | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- | ---------- | | `position` | The position of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `capitalContribution` | The capital contribution of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values using `capitalContribution` as the key. Required for UBOs, Shareholders, Trustees, and Partners. | Required\* | Required\* | Required\* | | `hasDistributionRight` | Boolean value stating if the stakeholder has distribution rights. Required for UBOs, Shareholders, and Partners. | Required\* | Required\* | Required\* | | `interestPercentage` | Number between 0-100 stating the interest percentage of the stakeholder. Trust beneficiary interest percentage to be collected for trust beneficiary position. Partner interest percentage to be collected for partner position. | N/A | Required\* | Required\* | | `trustBenefeciaryClass` | Class of trust beneficiary. Applicable only if the stakeholder position is a trust beneficiary. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | N/A | N/A | Required\* | | `votingRights` | Array of voting rights of the stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. Required for UBOs, Shareholders, and Partners. | Required\* | Required\* | Required\* | | `sharePercentage` | Number between 0-100 stating the percentage of shares owned by the stakeholder. Required only for UBOs, Shareholders, Trustees, and Partners. | Required\* | Required\* | Required\* | #### `applicantDetails.address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------- | --------- | | `addressLine1` | The first address line of the applicant. The maximum character length is 40. If `kycMode = E_KYC`, then the following needs to be passed in this field as comma-separated values: unit number (if available)street numberstreet name | Required | Required | Required | | `addressLine2` | The second address line of the applicant. The maximum character length is 40. If `kycMode = E_KYC`, then `StreetType` needs to be passed in this field. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `city` | The city or suburb of the applicant. The maximum character length is 20. If `kycMode = E_KYC`, then the suburb needs to be passed in this field. | Required | Required | Required | | `state` | The state of the applicant. The maximum character length is 30. If country=`NZ`, use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `country` | The country where the applicant resides. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `postcode` | The postal code of the applicant. The minimum length is 3, and the maximum length is 10 alphanumeric characters or spaces. | Required | Required | Required | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object to contain the applicant's contact information. | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- | --------- | | `email` | The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See [Regex and Accepted Values](/docs/developers/faqs/regex-and-accepted-values) | Required | Required | Required | | `countryCode` | The country code of the applicant's phone number. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `contactNo` | The applicant's phone number. The maximum length is 20 numeric characters. | Required | Required | Required | #### `usinessDetails.applicantDetails.documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- | ---------- | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `documentNumber` | The ID number for the given document type. | Required | Required | Required | | `documentIssuanceCountry` | The country that issued the business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. The expiry date cannot be a past date. Required for Passport or Driver's License. | Required\* | Required\* | Required\* | | `documentReferenceNumber` | Required for Driver's License when kycMode is `E_KYC`. `driversLicenceVersionNumber` must be passed in this field. Alphanumeric with a length of 3. | Required\* | Required\* | Required\* | | [`document`](#businessdetails-applicantdetails-documentdetails-document) | An array of objects that contains a copy of the document. **Note:** This object is required only for `MANUAL_KYC`. In `E_KYC` or `E_DOC_VERIFY`, `LOA` is required if the applicant isn't a `DIRECTOR`/`UBO`. | Required\* | Required\* | Required\* | ##### `documentDetails.document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains the document copy. This object is required only for `MANUAL_KYC`. `LOA` is required if the applicant isn't a `DIRECTOR`/ `UBO` even for `E_KYC` and `E_DOC_VERIFY` | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | ------------ | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- | ---------- | | `fileName` | The name of the file. | Required\* | Required\* | Required\* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required\* | Required\* | Required\* | | `document` | The document saved as a base64 encoded string. The maximum size is 5 MB. | Required\* | Required\* | Required\* | ## `riskAssessmentInfo` object An object that contains the following details that are required to determine a corporate customer's risk profile. | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- | --------- | | `totalEmployees` | The corporate customer's total number of employees. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `annualTurnover` | The corporate customer’s annual turnover. If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `industrySector` | The corporate customer's industry sector. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `countryOfOperation` | An array of countries the corporate customer operates in. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `transactionCountries` | An array of countries where the transactions occur. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | ## `expectedAccountUsage` object This object contains the details regarding the expected usage of the account | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- | --------- | | `intendedUses` | Array of intended uses of the account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | ## `deviceDetails` object This object contains the information about the customer's device and IP address where the onboarding request originated. | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------- | --------- | | `countryIP` | Country of the IP address, e.g., `US`. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `deviceInfo` | Information of the device, e.g., `Mac OS`. | Required | Required | Required | | `ipAddress` | IP address of the device, e.g., `45.48.241.198`. | Required | Required | Required | | `sessionId` | A unique identifier for the session, generated by your application. | Required | Required | Required | ## `tags` object This object contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15. | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | ------------ | ------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- | --------- | | `key` | The name of the tag. The maximum character length is 128. Key should be unique. | Optional | Optional | Optional | | `value` | The value of the tag. The maximum character length is 256. | Optional | Optional | Optional | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/corporate-customers/nz-onboarding/required-documents This page outlines the documents required for stakeholders, applicants, and various business types to onboard a corporate customer registered in New Zealand. ## Business details The following documents are required as part of the Know Your Business (KYB) identification and verification process. | `businessType` | Required Document for eKYB | Required Document for Manual KYB | | :---------------------------------------------------------------------------------------------------- | :------------------------- | :------------------------------- | | `GOVERNMENT_ENTITY` `PRIVATE_COMPANY` `PUBLIC_COMPANY` `SOLE_TRADER` `CLUB_ASSOCIATION``CO_OPERATIVE` | N/A | `BUSINESS_REGISTRATION_DOCUMENT` | | `GENERAL_PARTNERSHIP``LIMITED_PARTNERSHIP` | `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | | `TRUST` | `TRUST_DEED` | `TRUST_DEED` | ## Stakeholders NZ resident individual stakeholders need to use the `kycMode`= `E_KYC`. `kycMode`=`MANUAL_KYC` should be passed for non-residents. ### eKYC In E KYC mode, no document file is needed. However, details of at lease one of the following document is needed. In case of Driver's License documents, the drivers license version number should be passed in the `documentReferenceNumber` field. | Field name | Passport | Driver's license | Nominee Agreement (if stakeholder is a Nominee) | | :------------------------ | :-------------------- | :--------------- | :---------------------------------------------- | | `documentType` | `PASSPORT` | `DRIVER_LICENSE` | `NOMINEE_AGREEMENT` | | `documentNumber` | Yes (Passport number) | Yes | No | | `documentReferenceNumber` | No | Yes | No | | `documentIssuanceCountry` | Yes | Yes | No | | `documentExpiryDate` | Yes | Yes | No | | `document.fileName` | No | No | Yes | | `document.fileType` | No | No | Yes | | `document.document` | No | No | Yes | ### Manual KYC When `kycMode = MANUAL_KYC` the following documents need to be submitted. | Field name | Passport | Driver's license | National Id | Nominee Agreement (if stakeholder is a Nominee) | | :------------------------ | :-------------------- | :--------------- | :------------ | :---------------------------------------------- | | `documentType` | `PASSPORT` | `DRIVER_LICENSE` | `NATIONAL_ID` | `NOMINEE_AGREEMENT` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | | `documentReferenceNumber` | No | No | No | No | | `documentExpiryDate` | Yes | Yes | No | No | | `document.fileName` | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | Yes | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. A Stakeholder is considered a Nominee if they holds any of the following positions: - `NOMINEE_DIRECTOR` - `NOMINEE_SHAREHOLDER` - `NOMINEE_SETTLOR` - `NOMINEE_GENERAL_PARTNER` **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport, Medicare Cards, or Driver's License. ## Applicants Nium offers `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC` modes for applicant KYC in New Zealand. - `E_KYC` is applicable for NZ residents.ID document details are needed for E\_KYC mode. Additionally, Letter of Authorization is required to be uploaded if the applicant isn't a director or UBO - `E_DOC_VERIFY` is applicable for non-AU residents. Applicant needs to complete KYC using the redirect URL. Document details need to be passed for `E_DOC_VERIFY` and upload of document files isn't required. - `MANUAL_KYC` required document details along with upload of document files. ### eKYC and eDoc Verify | Field name | Passport | Driver's license | Nominee Agreement or Letter Of Authorization (as applicable\*) | | :------------------------ | :-------------------- | :--------------- | :------------------------------------------------------------- | | `documentType` | `PASSPORT` | `DRIVER_LICENSE` | `NOMINEE_AGREEMENT` / `LOA` | | `documentNumber` | Yes (Passport number) | Yes | No | | `documentReferenceNumber` | No | Yes | No | | `documentIssuanceCountry` | Yes | Yes | No | | `documentExpiryDate` | Yes | No | No | | `document.fileName` | No | No | Yes | | `document.fileType` | No | No | Yes | | `document.document` | No | No | Yes | See [applicant nominee agreement conditions](#applicant-nominee-agreement-condition) to understand where Nominee Agreement or Letter of Authorization is required. ### Manual KYC Every individual applicant needs to submit one of the following information when `kycMode = MANUAL_KYC`. | Field name | Passport | Drivers license | National Id | Nominee Agreement or Letter Of Authorization (as applicable) | | :------------------------ | :-------------------- | :--------------- | :------------ | :----------------------------------------------------------- | | `documentType` | `PASSPORT` | `DRIVER_LICENSE` | `NATIONAL_ID` | `NOMINEE_AGREEMENT`/ `LOA` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | | `documentExpiryDate` | Yes | Yes | No | No | | `document.fileName` | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | | `document.document` | **Yes** | **Yes** | Yes | **Yes** | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. #### Applicant Nominee Agreement or Letter of Authorization Conditions One of Nominee Agreement or Letter of Authorization may be required for applicant as described below. - If the applicant is a nominee stakeholder having one of `NOMINEE_DIRECTOR` or `NOMINEE_SHAREHOLDER` or `NOMINEE_SETTLOR` or `NOMINEE_GENERAL_PARTNER` as positions then Nominee agreement is required. - If the applicant is not a nominee stakeholder and applicant has one of `DIRECTOR` or `UBO` as positions then no document is required. - If the applicant is not a nominee stakeholder and applicant is not `DIRECTOR` or `UBO` then Letter of Authorization is required. See [Letter Of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for the suggested format of `LOA` in case you do not have one. **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport, Medicare Cards, or Driver's License. --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/nz-onboarding/position-mapping | Business entity type | DIRECTOR | NOMINEEDIRECTOR | MEMBERS | PARTNER | NOMINEEGENERALPARTNER | TRUSTBENEFICIARY | SETTELOR | NOMINEESETTLOR | TRUSTEE | UBO | SHAREHOLDER | NOMINEESHAREHOLDER | PROTECTOR | REPRESENTATIVE | | Business entity type | `DIRECTOR` | `NOMINEE_DIRECTOR` | `MEMBERS` | `PARTNER` | `NOMINEE_GENERAL_PARTNER` | `TRUST_BENEFICIARY` | `SETTELOR` | `NOMINEE_SETTLOR` | `TRUSTEE` | `UBO` | `SHAREHOLDER` | `NOMINEE_SHAREHOLDER` | `PROTECTOR` | `REPRESENTATIVE` | | --------------------- | :--------: | :----------------- | :-------: | :-------: | :------------------------ | :-----------------: | :--------: | :---------------- | :-------: | :---: | :------------ | :-------------------- | :---------- | :--------------- | | `CLUB_ASSOCIATION` | Yes | Yes | Yes | | | | Yes | Yes | | Yes | Yes | Yes | | Yes | | `GOVERNMENT_ENTITY` | Yes | | | | | | | | | | | | | Yes | | `LIMITED_PARTNERSHIP` | | | | Yes | Yes | | | | | Yes | Yes | Yes | | Yes | | `GENERAL_PARTNERSHIP` | | | | Yes | Yes | | | | | | | | | Yes | | `PRIVATE_COMPANY` | Yes | Yes | | | | | | | | Yes | Yes | Yes | | Yes | | `PUBLIC_COMPANY` | Yes | Yes | | | | | | | | Yes | Yes | Yes | | Yes | | `TRUST` | Yes | Yes | Yes | | | Yes | Yes | | Yes | Yes | Yes | Yes | Yes | Yes | | `SOLE_TRADER` | | | | | | | | | | Yes | Yes | Yes | | Yes | | `CO_OPERATIVE` | Yes | Yes | Yes | | | | | | | Yes | Yes | Yes | Yes | Yes | A **Yes** value means that position can be passed for that `businessType`. A blank table cell means that position is not applicable for that `businessType`. ### ProfessionalDetails - Position mapping Different professional details parameters are required based on the position of the stakeholder. Mapping of the required parameters based on the position of the stakeholder. | Details\Positions | `UBO` | `SHAREHOLDER` | `DIRECTOR` | `TRUSTEE` | `SETTLOR` | `TRUST_BENEFICIARY` | `MEMBERS` | `PROTECTOR` | `PARTNER` | `REPRESENTATIVE` | `NOMINEE_DIRECTOR` | `NOMINEE_SHAREHOLDER` | `NOMINEE_SETTLOR` | `NOMINEE_GENERAL_PARTNER` | | ----------------------- | ----- | ------------- | ---------- | --------- | --------- | ------------------- | --------- | ----------- | --------- | ---------------- | ------------------ | --------------------- | ----------------- | ------------------------- | | `votingRights` | Yes | Yes | | | | | | | Yes | | | | | | | `interestPercentage` | | | | | | Yes | | | Yes | | | | | | | `trustBeneficiaryClass` | | | | | | Yes | | | | | | | | | | `hasDistributionRight` | Yes | Yes | | | | | | | Yes | | | | | | | `sharePercentage` | Yes | Yes | | Yes | | | | | Yes | | | | | | | `capitalContribution` | Yes | Yes | | Yes | | | | | Yes | | | | | | Multiple positions in the `professionalDetails` array object can be passed if required as shown below: ```json "professionalDetails": [ { "position": "REPRESENTATIVE" }, { "position": "UBO", "sharePercentage": "34.5", "capitalContribution": "NZ008", "hasDistributionRight": true, "votingRights": [ "VTR01" ] }, { "position": "NOMINEE_SHAREHOLDER" } ] ``` --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/nz-onboarding/example-requests To onboard your entity, you can call the Onboard Corporate Customer request. For an example call that you can customize with your information, see: To onboard your entity, you can call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request. For an example call that you can customize with your information, see: - [Private companies](#private) - [Trusts](#trust) - [Sole trader](#sole-trader) - [Limited partnership](#limited-partnership) ## Private companies The following is an API request example call where `businessType = PRIVATE_COMPANY`. ```json { "region": "NZ", "businessDetails": { "businessName": "ABCD Corp 123", "businessType": "PRIVATE_COMPANY", "businessRegistrationNumber": "8150775678762", "tradeName": "AB Company", "hasNominee": true, "isCashIntensiveBusiness": true, "bankAccountDetails": { "accountName": "Mohenjadaro Consulting Limited", "bankName": "Bank of New Zealand (BNZ)", "accountNumber": "123243999999999", "currency": "NZD" }, "website": "www.abcdxyz.com", "legalDetails": { "registeredCountry": "NZ", "registeredDate": "2000-01-02" }, "addresses": { "registeredAddress": { "addressLine1": "1,1, abcabc", "addressLine2": "Avenue,NIRIMBA", "city": "Wellington", "state": "QLD", "country": "NZ", "postcode": "5016" }, "businessAddress": { "addressLine1": "1,1, abcabc", "addressLine2": "Avenue,NIRIMBA", "city": "Wellington", "state": "QLD", "country": "NZ", "postcode": "5016" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "John", "middleName": "Conner", "lastName": "Smith", "dateOfBirth": "1947-02-15", "nationality": "SG", "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "125710929", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20", "document": [ { "document": "", "fileName": "john_passport", "fileType": "application/pdf" } ] } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "AU", "postcode": "2002" }, "professionalDetails": [ { "position": "UBO", "sharePercentage": "34.5", "capitalContribution": "NZ008", "hasDistributionRight": true, "votingRights": [ "VTR01" ] } ] } }, { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Jane", "middleName": "M", "lastName": "Doe", "dateOfBirth": "1972-02-15", "nationality": "NZ", "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV", "documentIssuanceCountry": "NZ", "documentExpiryDate": "2031-05-20" } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "WELLINGTON", "state": "Arrowtown", "country": "NZ", "postcode": "2002" }, "professionalDetails": [ { "position": "DIRECTOR" } ] } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Terrance", "middleName": "M", "lastName": "Smith", "dateOfBirth": "1972-02-15", "nationality": "NZ", "professionalDetails": [ { "position": "NOMINEE_SHAREHOLDER" }, { "position": "REPRESENTATIVE" } ], "contactDetails": { "countryCode": "NZ", "contactNo": "471822328", "email": "AUcust02_8@fit.com" }, "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV", "documentIssuanceCountry": "SG", "documentExpiryDate":"2031-05-20" } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "NZ", "postcode": "2002" } } }, "expectedAccountUsage": { "intendedUses": [ "IU005", "IU004" ] }, "riskAssessmentInfo": { "totalEmployees": "EM009", "industrySector": "IS144", "annualTurnover": "NZ008", "countryOfOperation": [ "IN", "GB" ], "transactionCountries": [ "GB", "US", "SG" ] } } ``` ## Trusts The following is an API request example call where `businessType = TRUST`. ```json { "region": "NZ", "businessDetails": { "businessName": "Good Children Trust", "businessType": "TRUST", "businessRegistrationNumber": "8050695628781", "tradeName": "Aspire Trust", "hasNominee": false, "isCashIntensiveBusiness": false, "documentDetails": [ { "documentType": "TRUST_DEED", "document": [ { "fileName": "TrustDeed.png", "fileType": "png", "document": "" } ] } ], "bankAccountDetails": { "accountName": "Mohenjadaro Consulting Limited", "bankName": "Bank of New Zealand (BNZ)", "accountNumber": "123243999999999", "currency": "NZD" }, "regulatoryDetails": { "unregulatedTrustType": [ "NZTT2" ] }, "legalDetails": { "registeredCountry": "NZ", "registeredDate": "2002-01-02" }, "addresses": { "registeredAddress": { "addressLine1": "1,1, abcabc", "addressLine2": "Avenue,NIRIMBA", "city": "Wellington", "state": "Arrowtown", "country": "NZ", "postcode": "5016" }, "businessAddress": { "addressLine1": "1,1, abcabc", "addressLine2": "Avenue,NIRIMBA", "city": "Wellington", "state": "Arrowtown", "country": "NZ", "postcode": "5016" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "John", "middleName": "Conner", "lastName": "Smith", "dateOfBirth": "1947-02-15", "nationality": "SG", "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "125710929", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20", "document": [ { "document": "", "fileName": "john_passport", "fileType": "application/pdf" } ] } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "AU", "postcode": "2002" }, "professionalDetails": [ { "position": "TRUSTEE", "capitalContribution": "NZ008", "sharePercentage":"5" } ] } }, { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Jane", "middleName": "M", "lastName": "Doe", "dateOfBirth": "1972-02-15", "nationality": "NZ", "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20" } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "NZ", "postcode": "2002" }, "professionalDetails": [ { "position": "SETTLOR" } ] }, "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Jacqulien", "middleName": "M", "lastName": "John", "dateOfBirth": "1945-02-15", "nationality": "NZ", "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV 2334", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20" } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "NZ", "postcode": "2002" }, "professionalDetails": [ { "position": "TRUST_BENEFICIARY", "interestPercentage":"6", "trustBeneficiaryClass":"C" } ] } }, { "businessPartner": { "businessType": "PRIVATE_COMPANY", "businessRegistrationNumber": "1234567890123", "businessEntityType": "TRUSTEE", "businessName": "Ace Group aab", "capitalContribution": "NZ008", "sharePercentage": "5", "legalDetails": { "registeredCountry": "NZ", "registeredDate": "2019-08-10" } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Terrance", "middleName": "M", "lastName": "Smith", "dateOfBirth": "1972-02-15", "nationality": "NZ", "professionalDetails": [ { "position": "DIRECTOR" } ], "contactDetails": { "countryCode": "NZ", "contactNo": "471822328", "email": "AUcust02_8@fit.com" }, "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20" } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Wellington", "state": "Arrowtown", "country": "NZ", "postcode": "2002" } } }, "expectedAccountUsage": { "intendedUses": [ "IU005", "IU004" ] }, "riskAssessmentInfo": { "totalEmployees": "EM009", "industrySector": "IS144", "annualTurnover": "NZ008", "countryOfOperation": [ "IN", "GB" ], "transactionCountries": [ "GB", "US", "SG" ] } } ``` ## Sole trader The following is an API request example call where `businessType = SOLE_TRADER`. ```json { "region": "NZ", "businessDetails": { "businessName": "Jack Enterprises 23", "businessType": "SOLE_TRADER", "businessRegistrationNumber": "8023675678761", "hasNominee": false, "isCashIntensiveBusiness": true, "bankAccountDetails": { "accountName": "Mohenjadaro Consulting Limited", "bankName": "Bank of New Zealand (BNZ)", "accountNumber": "123243999999999", "currency": "NZD" }, "legalDetails": { "registeredCountry": "NZ", "registeredDate": "2002-01-02" }, "addresses": { "registeredAddress": { "addressLine1": "1,1, abcabc", "addressLine2": "Avenue,NIRIMBA", "city": "Wellington", "state": "QLD", "country": "NZ", "postcode": "5016" }, "businessAddress": { "addressLine1": "1,1, abcabc", "addressLine2": "Avenue,NIRIMBA", "city": "Wellington", "state": "QLD", "country": "NZ", "postcode": "5016" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Jack", "middleName": "M", "lastName": "Smith", "dateOfBirth": "1972-02-15", "nationality": "NZ", "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20" } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "NZ", "postcode": "2002" }, "professionalDetails": [ { "position": "UBO", "capitalContribution": "NZ008", "sharePercentage":"5.3", "hasDistributionRight": true, "votingRights": [ "VTR07" ] } ] } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Jane", "middleName": "M", "lastName": "Doe", "dateOfBirth": "1942-02-15", "nationality": "NZ", "professionalDetails": [ { "position": "REPRESENTATIVE" } ], "contactDetails": { "countryCode": "NZ", "contactNo": "471822328", "email": "AUcust02_8@fit.com" }, "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20" }, {"documentType": "LOA", "document": [ { "document": "", "fileName": "john_passport", "fileType": "application/pdf" } ] } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Willington", "state": "Arrowtown", "country": "NZ", "postcode": "2002" } } }, "expectedAccountUsage": { "intendedUses": [ "IU005", "IU003" ] }, "riskAssessmentInfo": { "totalEmployees": "EM009", "industrySector": "IS144", "annualTurnover": "NZ008", "countryOfOperation": [ "IN", "ES" ], "transactionCountries": [ "GB", "US", "SG" ] } } ``` ## Limited partnership The following is an API request example call where `businessType = LIMITED_PARTNERSHIP`. ```json { "region": "NZ", "businessDetails": { "businessName": "Jack & Jill Partnership", "businessType": "LIMITED_PARTNERSHIP", "businessRegistrationNumber": "8064575678761", "hasNominee": false, "isCashIntensiveBusiness": true, "bankAccountDetails": { "accountName": "Mohenjadaro Consulting Limited", "bankName": "Bank of New Zealand (BNZ)", "accountNumber": "123243999999999", "currency": "NZD" }, "legalDetails": { "registeredCountry": "NZ", "registeredDate": "2002-01-02" }, "addresses": { "registeredAddress": { "addressLine1": "1,1, abcabc", "addressLine2": "Avenue,NIRIMBA", "city": "Wellington", "state": "QLD", "country": "NZ", "postcode": "5016" }, "businessAddress": { "addressLine1": "1,1, abcabc", "addressLine2": "Avenue,NIRIMBA", "city": "Wellington", "state": "QLD", "country": "NZ", "postcode": "5016" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Jack", "middleName": "M", "lastName": "Smith", "dateOfBirth": "1972-02-15", "nationality": "NZ", "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20" } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "NZ", "postcode": "2002" }, "professionalDetails": [ { "position": "UBO", "capitalContribution": "NZ008", "sharePercentage":"5.3", "hasDistributionRight": true, "votingRights": [ "VTR07" ] } ] } }, { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Humpty", "middleName": "M", "lastName": "Dumpty", "dateOfBirth": "1986-02-15", "nationality": "NZ", "documentDetails": [ { "documentType": "PASSPORT", "documentNumber": "125710 929", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20" } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Sydney", "state": "QLD", "country": "NZ", "postcode": "2002" }, "professionalDetails": [ { "position": "PARTNER", "capitalContribution": "NZ008", "interestPercentage":"4.2", "sharePercentage":"5.3", "hasDistributionRight": true, "votingRights": [ "VTR01","VTR02" ] } ] } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Jane", "middleName": "M", "lastName": "Doe", "dateOfBirth": "1942-02-15", "nationality": "NZ", "professionalDetails": [ { "position": "REPRESENTATIVE" } ], "contactDetails": { "countryCode": "NZ", "contactNo": "471822328", "email": "AUcust02_8@fit.com" }, "documentDetails": [ { "documentType": "DRIVER_LICENSE", "documentNumber": "125710929", "documentReferenceNumber": "ACV", "documentIssuanceCountry": "SG", "documentExpiryDate": "2031-05-20" }, {"documentType": "LOA", "document": [ { "document": "", "fileName": "john_passport", "fileType": "application/pdf" } ] } ], "address": { "addressLine1": "192, 101, High Street", "addressLine2": "ST", "city": "Willington", "state": "Arrowtown", "country": "NZ", "postcode": "2002" } } }, "expectedAccountUsage": { "intendedUses": [ "IU005", "IU003" ] }, "riskAssessmentInfo": { "totalEmployees": "EM009", "industrySector": "IS144", "annualTurnover": "NZ008", "countryOfOperation": [ "IN", "ES" ], "transactionCountries": [ "GB", "US", "SG" ] } } ``` --- # Allowed Banks for Wallet Activation URL: https://docs.nium.com/docs/onboarding/corporate-customers/nz-onboarding/allowed-banks To meet regulatory requirements in New Zealand, a wallet can only be activated after it receives its first funding transaction from the customer’s own bank account. That bank must be one of the approved banks listed below. # Allowed Banks To meet regulatory requirements in New Zealand, a wallet can only be activated after it receives its **first funding transaction** from the customer’s **own bank account**. That bank must be one of the **approved banks** listed below. Let your customers know: only the first funding must meet this requirement. After activation, they can fund the wallet from other banks or sources. *** ## List of Allowed New Zealand Banks - ANZ Bank New Zealand Ltd - ASB Bank Limited - Australia and New Zealand Banking Group Limited - Bank of Baroda (New Zealand) Limited - Bank of China Limited - Bank of China (New Zealand) Limited - Bank of India (New Zealand) Limited - China Construction Bank Corporation - China Construction Bank (New Zealand) Limited - Citibank N A - Commonwealth Bank of Australia - Heartland Bank Limited - Industrial and Commercial Bank of China (New Zealand) Limited - Industrial and Commercial Bank of China Limited - JPMorgan Chase Bank NA - Kiwibank Limited - Kookmin Bank - MUFG Bank, Ltd - Coöperatieve Rabobank U.A. trading as Rabobank Nederland - Rabobank New Zealand Limited - Southland Building Society - The Co-operative Bank Limited - The Hongkong and Shanghai Banking Corporation Limited - TSB Bank Limited - Westpac Banking Corporation - Westpac New Zealand Limited *** If you have questions or need clarification on this requirement, please reach out to your Nium account manager or [Nium Support](mailto:support@nium.com). --- # SG Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/sg-onboarding This page contains details about the Singapore Know Your Business (KYB) flows and links to the following sub-pages for a quick reference: | Page name | Description | | :------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | **[SG required fields](/docs/onboarding/corporate-customers/sg-onboarding/required-parameters)** | This page lists the required API fields of each entity type. | | **[SG required documents](/docs/onboarding/corporate-customers/sg-onboarding/required-documents)** | This page contains tables listing the required documents for verification of the business entity, stakeholders, and applicants. | | **[SG position mapping](/docs/onboarding/corporate-customers/sg-onboarding/position-mapping)** | This page gives a quick glance at the required positions of each entity type. | | **[SG request examples](/docs/onboarding/corporate-customers/sg-onboarding/example-requests)** | This page contains API request examples for SG entities. | Nium offers eKYB and Manual KYB flows for customers in Singapore. The eKYB flow is fully automated, allowing corporate customers to be approved within a few minutes of submitting their application, making it the preferred mode for all customers. Reach out to Nium's sales team to configure the eKYB flow for your account.git diff --name-only --diff-filter=U ## eKYB flow The following steps are required to complete the eKYB application. SG Onboarding ### Step 1. Get Public Corporate Details Using Business ID API To start the eKYB process, collect the basic details about the corporate customer from the applicant through an onboarding form, including the `businessRegistrationNumber` and `countryCode`. For a list of valid country codes, see [Currency and country codes](/docs/getting-started/currency-and-country-codes). Then call Nium's [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API. This API returns publicly available information about the corporate customer, which you then display to the customer so they can select and confirm the `businessName` and `businessRegistrationNumber` along with any other optional details. You need to store the `searchReferenceId` that's returned in this response since it's required in subsequent steps. This API may return multiple results for a given `businessRegistrationNumber`. When there's more than one, display all the results to let the customer select the right one. When no results are returned, you should call the Onboard Corporate Customer API with a full request body. Such applications go through manual review, making the eKYB process not applicable in this case. ### 2. Get Exhaustive Corporate Details Using Business ID API Call the [Exhaustive Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) endpoint using the `searchReferenceId` stored in [Step 1](#step-1-get-public-corporate-details-using-business-id-api) as the parameter. This returns the public and non-public information about the corporate customer. You need to store the `searchId` that's returned in this response since it's required in the subsequent steps. This is a chargeable API. Work with your Nium representative before using it. It's best to use this API only once per customer. ### Step 3. Display the information to the applicant You need to display the above-received information to the applicant for their confirmation, edits, or additions. Then, submit the form. All the fields required to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API are collected in this step. Any additional fields that are required, and not returned in the above step, are to be added by the applicant. ### Step 4. Post Onboard Corporate Customer API You then call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API with the full request body, including the `searchId` you stored in Step 2. If the `searchId` parameter isn't passed, the application is treated as `MANUAL_KYB` and goes through a manual review. #### Applicant KYC In Singapore, the supported applicant methods for the eKYB flow are `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC`. - You need to use `E_KYC` for Singaporean residents and `E_DOC_VERIFY` for non-Singaporean residents and pass that value in `businessDetails.applicantDetails.kycMode`. - If required, you can use `MANUAL_KYC` for non-Singaporean residents, but those applications go through manual review and cannot be verified in real time. - The uploading of documents is required for `MANUAL_KYC` which has to be sent in the `businessDetails.applicantDetails.documentDetails` object. For details, see [SG required documents](/docs/onboarding/corporate-customers/sg-onboarding/required-documents). **`E_KYC`** As a response to the Onboard Corporate Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirectURL. The applicant then lands on the KYC vendor's page, where he can complete the KYC verification using Singpass authentication. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium. Redirection can result in the following scenarios, based on the below parameters. - `errorCode` - `errorMessage` - `isSuccess` – This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. - `referennceId` (used to identify the individual for whom redirection happened.) | Scenario | Expected action from client | Query parameters in the redirection | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | | The applicant completed the required steps in the vendor’s UI. | Wait for webhook. | `errorCode`: N/A `errorMessage`: N/A `isSuccess`: TRUE | | The customer has provided incorrect data in the vendor's UI. (customer didn't click accept in the vendor's page) | Ask customer to submit correct data in the vendors page. | `errorCode`: I400 `errorMessage`: vendorValidationError `isSuccess`: FALSE | | Any unexpected error from the vendor. | Try after some time or reach out to Nium's support. | `errorCode`: I500 `errorMessage`: unexpectedError `isSuccess`: FALSE | Based on the scenario, you can implement the next steps as provided in the table above. **Example of a redirect to the client in a successful case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11- f95c315ce83c&isSuccess=true&errorCode=&errorMessage=&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX ``` **Example of a redirect to the client in a failed case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11- f95c315ce83c&errorCode=I400&errorMessage=vendorValidationError&isSuccess=false&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX ``` **Applicant E\_DOC\_VERIFY** As a response to the Onboard Corp Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirectURL. Applicant then lands on our KYC vendor's page, where he can complete the KYC verification by uploading his proof of identity and proof of address documents with a live selfie. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium. Redirection can result in the following scenarios, based on the below parameters. - `errorCode` - `errorMessage` - `isSuccess` - This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. - `referennceId` (used to identify the individual for whom redirection happened.) | Scenario | Expected action from client | Query parameters in the redirection | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | The applicant completed the required steps in the vendor’s UI. | Wait for webhook. | `errorCode`: N/A `errorMessage`: N/A `isSuccess`: TRUE | | The document has already been submitted in the vendor's UI. | KYC Process is completed. Client needs to wait for webhook. | `errorCode`: R403 `errorMessage`: documentAlreadySubmitted `isSuccess`: FALSE | | The customer has provided incorrect data in the vendor's UI. | Ask customer to submit correct data in the vendors page. | `errorCode`: I400 `errorMessage`: vendorValidationError `isSuccess`: FALSE | | Verification failure at the vendor. | The application goes to manual review. The client needs to wait for webhook. | `errorCode`: R401 `errorMessage`: vendorVerificationFailure `isSuccess`: FALSE | | Internal Server error at Nium. | Try after some time or reach out to Nium's support. | `errorCode`: R500 `errorMessage`: internalServerError `isSuccess`: FALSE | | Any unexpected error from the vendor. | Try after some time or reach out to Nium's support. | `errorCode`: I500 `errorMessage`: unexpectedError `isSuccess`: FALSE | | Validation already completed and customer retries the same link. | KYC Process is completed. The client need to wait for webhook. | `errorCode`: R606 `errorMessage`: verificationAlreadyCompleted `isSuccess`: FALSE | Based on the scenario, you can implement the next steps as provided in the table above. **Example of a redirect to the client in a successful case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11- f95c315ce83c&isSuccess=true&errorCode=&errorMessage=&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX ``` **Example of a redirect to the client in a failed case** ``` https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11- f95c315ce83c&errorCode=R408&errorMessage=redirectURLExpired&isSuccess=false&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX ``` When the applicant's `businessDetails.applicantDetails.address.country` is `US`, the applicant's address' `state` needs to be a valid 2 letter state code. Use the [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API for acceptable values. When the applicant's `businessDetails.applicantDetails.address.country` is `GB`, the applicant's `postcode` needs to be in the `SW4 6EH` format. #### Stakeholder KYC For the eKYB flow, Nium offers `E_KYC`, `E_DOC_VERIFY` and `MANUAL_KYC` for stakeholder verification. - For resident stakeholders (`address.country`=`SG`), set `E_KYC` or `MANUAL_KYC` as `kycMode` based on stakeholder preference. - For non-resident stakeholders set `kycMode` as `E_DOC_VERIFY` or `MANUAL_KYC` based on stakeholder preference. - `E_DOC_VERIFY` will require live-selfie and hence should be used only when stakeholder is accessible, similarly `E_KYC` will require singpass authentication. For `MANUAL_KYC` include required documents in `businessDetails.stakeholders.stakeholderDetails.documentDetails`. Steps to implement stakeholder `E_DOC_VERIFY` or `E_KYC` `redirectURL` are similar to that of applicant mentioned above. For details on implementation, see **[Onboard API Response - 200 response](/docs/onboarding/corporate-customers#onboard-api-response)** The `referenceId` available in the browser redirection is the same as the one submited in the Onboard API request for the stakeholder. In case, multiple stakeholders have redirectURL, you can use the referenceId to identify them and land them to the appropriate page as required. #### Upload documents If `searchId` isn't passed, a document upload is required. Even if `searchId` is passed, some documents might be required in certain scenarios. Nium doesn't initiate verification until all required documents are submitted. All required documents can be submitted in two ways: - [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request. - [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API The [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) API is preferred since it uploads one document at a time, which reduces the loading time. This API can be called only while the application is in the `IN_PROGRESS` state. You can use the `remarks` field to list which documents Nium expects in the response of both APIs. The API gateway has a limit of 10 MB for any API request. This makes Upload Document API the preferred way to upload documents since you can upload one document at a time. For the entire list of required documents for manual and eKYB flows, see [SG required documents](/docs/onboarding/corporate-customers/sg-onboarding/required-documents). #### Terms and Conditions You must show customers the Nium terms and conditions configured for your `client` resource. You can fetch these specific terms and conditions using our [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions). Customers can only submit the onboarding form once they accept the terms and conditions. To fetch the [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions): 1. Wait for the Onboarding API to return a `customerHashId`. 2. Once returned, call our [Accept Terms and Conditions API](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) and include the `customerHashId`. 3. Show the customer the returned terms and conditions and record their acceptance before allowing them to transact. For more details, see [Terms and Conditions](/docs/onboarding/corporate-customers#terms-and-conditions). ### Step 5. Wait for webhook response After submission, the `status` in the Onboard Corporate Customer response is `IN_PROGRESS`. The applicant needs to complete both the [Applicant KYC](#applicant-kyc) and [Upload documents](#upload-documents) steps to proceed further. Once done, Nium initiates real-time verification and sends the response via a webhook. The application might be approved at this stage; and if it isn't approved, the application goes through a manual review. Any changes in the `status` is again communicated via a webhook. For the next steps based on the response of the webhook, see [Webhooks](/docs/onboarding/corporate-customers#webhooks). ## Manual KYB flow SG Onboarding For manual KYB, you need to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API directly. In this flow, the entire request body needs to be passed in the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. Important points to keep in mind: - Nium doesn't initiate verification until all required documents are submitted. - Use `E_KYC`, `MANUAL_KYC` for resident applicants and `E_DOC_VERIFY` or `MANUAL_KYC` for non-residents. - Use `E_KYC`, `MANUAL_KYC` for resident stakeholders and `E_DOC_VERIFY` or `MANUAL_KYC` for non-residents based on stakeholder preference. - `E_DOC_VERIFY` will require live-selfie and hence should be used when stakeholder is accessible. Similarly E\_KYC will require Singpass authentication. - Include required documents in `businessDetails.stakeholders.stakeholderDetails.documentDetails` for `MANUAL_KYC`. - Terms and Conditions flow is same mentioned in the eKYB flow. After submission, the `status` in the response of the Onboard Corporate Customer API is `IN_PROGRESS`. Once documents are uploaded and the KYC completes, Nium initiates manual verification and sends the response via a webhook. For the next steps to take to onboard your customer, see the response returned in the [webhook](/docs/onboarding/corporate-customers#webhooks). --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/sg-onboarding/required-parameters The API fields shown on this page are relevant to Singapore only. To see the full payload, refer to the Onboard Corporate Customer API Reference. The API fields shown on this page are relevant to Singapore only. To see the full payload, refer to the [Onboard Corporate Customer API Reference](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). All fields have a maximum limit of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `region` | The country or geographic region where the corporate end customer is located and is onboarded. To onboard a Singapore-based customer, use the `SG` value. | Yes | | [businessDetails](#businessDetails) | An object that contains business details about the corporate customer. | Yes | | [riskAssessmentInfo](#riskAssessmentInfo) | An object that contains the risk assessment information. | Yes | | [deviceDetails](#deviceDetails) | An object that contains information about the customer's device and IP address. | Yes | | [expectedAccountUsage](#expectedAccountUsage) | An object that contains the expected usage of the account | Yes | | [tags](#tags) | An object that contains the tags. | No | | `clientId` | This field contains the Nium client ID of the customer. It's received in the response of the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | | `customerHashId` | This field contins the unique customer identifier generated at the time of the customer creation. It's received in the response of the previously executed [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Note:** This field is required to reinitiate the KYB process. | Yes \* | ## Request parameters The below Request parameters refer to the `businessType` fields: | Government/Private/Sole trader | Public | Association/Partner/Trust | | --------------------------------------------------- | ---------------- | ----------------------------------- | | `GOVERNMENT_ENTITY` `PRIVATE_COMPANY` `SOLE_TRADER` | `PUBLIC_COMPANY` | `ASSOCIATION` `PARTNERSHIP` `TRUST` | ## `businessDetails` object An object that contains business details about the corporate customer. | Property | Description | Government Private Sole trader | Public | Association Partner Trust | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ----------- | --------------------------- | | `referenceId` | The universally unique identifier (UUID) of the business entity that Nium uses to identify the `businessDetails` entity. If it's not provided, Nium generates one. The UUID is used to respond to a request for information (RFI) or to upload required documents for the business entity. | Optional | Optional | Optional | | `businessName` | The name a corporate customer is registered under. | Required | Required | Required | | `businessRegistrationNumber` | The business registration number. | Required | Required | Required | | `tradeName` | Another name that the corporate customer uses to do business under, which is different than their licensed business name. | Optional | Optional | Optional | | `formerName` | In case the corporate customer did business under a different name than their licensed business name. | Optional | Optional | Optional | | `website` | The corporate customer's website. | Optional | Optional | Optional | | `businessType` | The legal entity type of the business. Use [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) for a valid set of values. | Required | Required | Required | | [associationDetails](#businessDetails-associationDetails) | An object that contains the association details. **Note:** Required only for `ASSOCIATION`. | N/A | N/A | Required \* | | [legalDetails](#businessDetails-legalDetails) | An object that contains the legal details. | Required | Required | Required | | [regulatoryDetails](#businessDetails-regulatoryDetails) | An object that contains the client's regulatory status. **Note:** This field is required only for `TRUST`. | N/A | N/A | Required \* | | [taxDetails](#businessDetails-taxDetails) | An array of objects that contains the tax details of the customer. **Note:** Required for customers with `registeredCountry`=`BR`. | Optional \* | Optional \* | Optional \* | | [addresses](#businessdetails-addresses) | An object that contains the registered and business addresses of the corporate customer. | Required | Required | Required | | [documentDetails](#businessdetails-documentdetails) | An array of objects that contains the business documents. **Note:** This field is required if specified in [SG required documents](/docs/onboarding/corporate-customers/sg-onboarding/required-documents). | Required \* | Required \* | Required \* | | [stakeholders](#businessdetails-stakeholders) | An array of objects that contains the individual and corporate stakeholders of the corporate customer. | Required | Required | Required | | [applicantDetails](#businessdetails-applicantdetails) | An object that contains the applicant's details. | Required | Required | Required | | [additionalInfo](#businessDetails-additionalInfo) | An object that contains additional information about the business. | Optional | Optional | Optional | ### `associationDetails` object An object within the `businessDetails` object that contains the association details. This is required if `businessType = ASSOCIATION`. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ------ | ------------------------- | | associationName | The complete name of the association. **Note:** This field is required only for `ASSOCIATION`. | N/A | N/A | Required \* | | associationNumber | The number of the association that an applicable state or territory issues. **Note:** This field is required only for `ASSOCIATION`. | N/A | N/A | Required \* | | associationChairPerson | The complete name of an association chairperson, secretary, or treasurer. **Note:** This field is required only for `ASSOCIATION`. | N/A | N/A | Required \* | ### `legalDetails` object An object within the `businessDetails` object that contains legal details. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | registeredDate | The date the business was registered entered in the `YYYY-MM-DD` format. Registered date cannot be future date. | Required | Required | Required | | registeredCountry | The country where the business is registered, specified in the [ISO 3166 format](https://www.iban.com/country-codes). | Required | Required | Required | | listedExchange | The exchange where the business is publicly listed. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | N/A | Required | N/A | ### `regulatoryDetails` array An array of objects within the `businessDetails` object that contains the regulatory status of the corporate customer. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | -------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------ | ------ | ------------------------- | | unregulatedTrustType | Unregulated trust type details. **Note:** This field is required only for `TRUST`. This field is an array. | N/A | N/A | Required \* | ### `taxDetails` array An array of objects within the `businessDetails` object that contains multiple values of taxation details of the corporate customer. - Required if `registeredCountry`=`BR` | Property | Description | Government Private Sole trader | Public | Association Partner Trust | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ---------- | --------------------------- | | `country` | The country in which the corporate customer is paying taxes. This will be the same as the registered country, unless the customer is paying taxes in other countries as well. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. Atleast one tax country should be `BR` if `registeredCountry`=`BR` | Required \* | Required\* | Required\* | | `taxNumber` | The tax ID number for this country. Send CNPJ (Cadastro Nacional da Pessoa Jurídica) for Brazilian Tax Number.Max 18 character. Numeric and special characters of ./- are allowed. Ex: "40.828.622/0001-27" | Required \* | Required\* | Required\* | ### `addresses` object An object within the `businessDetails` object that contains registered and business addresses. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------- | ------------------------- | | registeredAddress | An object that contains the address where the business is registered. | Required | Required | Required | | businessAddress | An object that contains the address where the business is mainly conducted, if different than the registered address. **Note:** This is required if `isSameBusinessAddress = No` | Required \* | Required \* | Required \* | #### `registeredAddress` object An object within the `businessDetails.address` object that contains the address details where the corporate customer is registered. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ------------ | ----------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | addressLine1 | The first address line of the registered business. | Required | Required | Required | | addressLine2 | The second address line of the registered business. | Optional | Optional | Optional | | city | The city where the corporate customer is registered. | Optional | Optional | Optional | | state | The state where the corporate customer is registered. | Optional | Optional | Optional | | country | The country where the corporate customer is registered, specified in the ISO 3166 format. | Required | Required | Required | | postcode | The postal code where the corporate customer is registered. | Required | Required | Required | #### `businessAddress` object An object within the `businessDetails.address` object that contains the address details about the principal place of business only when the registered address is different. - Use these fields only if the principal place of business is different than the registered address. - These fields are required only if `isSameBusinessAddress = No`. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ---------- | ------------------------- | | addressLine1 | The first address line of the principal place of business if different than the registered business. | Required\* | Required\* | Required\* | | addressLine2 | The second address line of the principal place of business if different than the registered business. | Optional | Optional | Optional | | city | The city of the principal place of business if different than the registered address. | Optional | Optional | Optional | | state | The state of the principal place of business if different than the registered address. | Optional | Optional | Optional | | country | The country where the principal place of business occurs if different than the registered country, specified in the ISO 3166 format. | Required\* | Required\* | Required\* | | postcode | The postal code where the principal place of business occurs if different than the registered address. | Required\* | Required\* | Required\* | ### `documentDetails` object An array of object within the `businessDetails` object that contains one or more business documents. For a complete list of required documents, see [SG required documents](/docs/onboarding/corporate-customers/sg-onboarding/required-documents). | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------- | ------------------------- | | documentType | The type of business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required \* | Required \* | Required \* | | document | An array of objects that contains a copy of the document. | Required \* | Required \* | Required \* | #### `document` object An array of object within the `businessDetails.documentDetails` object. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | -------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------- | ------------------------- | | fileName | The name of the file. | Required \* | Required \* | Required | | fileType | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \* | Required \* | Required | | document | The file as a base64 encoded string. | Required \* | Required \* | Required | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------- | ------------------------- | | isSameBusinessAddress | This field accepts `Yes` or `No` to indicate if the principal place of business is the same or different from the registered business entity address. | Optional | Optional | Optional | | searchId | This field is required for eKYB and is returned in the response of the Exhaustive Corporate Details using Business ID API. | Conditional | Conditional | Conditional | ### `stakeholders` object An array of object within the `businessDetails` object that contains information about one or many stakeholders. For every stakeholder object, you need to send either the `stakeholderDetails` or the `businessPartner` parameters. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | referenceId | The UUID associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | Optional | Optional | Optional | | stakeholderDetails | An object that contains the details about the individual stakeholder. Required only if an individual stakeholder exists. | Required | Required | Required | | businessPartner | An object that contains the details about the corporate stakeholder, if available. Required only if a business partner exists. | Required | Required | Required | #### `stakeholderDetails` object An object within the `stakeholders` object that contains the details about an individual stakeholder. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------- | ------------------------- | | kycMode | The KYC mode for the individual stakeholder. **Note:** This field is required to be `E_KYC`, `E_DOC_VERIFY`,`MANUAL_KYC` are acceptable values. For details, see **[Stakeholder KYC](/docs/onboarding/corporate-customers/sg-onboarding#stakeholder-kyc)** | Required | Required | Required | | firstName | The first name of the individual stakeholder. | Required | Required | Required | | middleName | The middle name of the individual stakeholder. | Optional | Optional | Optional | | lastName | The last name of the individual stakeholder. | Required | Required | Required | | nationality | The nationality of the individual stakeholder. | Required | Required | Required | | dateOfBirth | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be future date. | Optional | Optional | Optional | | professionalDetails | The array of professional details about the individual stakeholder. | Required | Required | Required | | address | An object that contains the residential address of the individual stakeholder. This field is required only if `position = DIRECTOR, UBO`. | Required \* | Required \* | Required \* | | contactDetails | An object that contains the contact details about the individual stakeholder. | Optional | Optional | Optional | | documentDetails | An array of object that contains the document details about the individual stakeholder. **Note:** This field is required only if `MANUAL_KYC`. | Required \* | Required \* | Required \* | ##### `professionalDetails` object An array of object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's professional details. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | position | The position of the individual stakeholder. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | | sharePercentage | The share percentage of the individual stakeholder in the company. | Optional | Optional | Optional | ##### `applicantDetails.address` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. This object is required only if `position = DIRECTOR, UBO`. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------- | ------------------------- | | addressLine1 | The first address line of the individual stakeholder. | Required \\\* | Required \\\* | Required \\\* | | addressLine2 | The second address line of the individual stakeholder. | Optional | Optional | Optional | | city | The city or suburb of the individual stakeholder. | Optional | Optional | Optional | | state | The state of the individual stakeholder. | Optional | Optional | Optional | | country | The country where the individual stakeholder resides, specified in the [ISO 3166 format](https://www.iban.com/country-codes). | Required \\\* | Required \\\* | Required \\\* | | postcode | The postal code of the individual stakeholder. | Required \\\* | Required \\\* | Required \\\* | ##### `contactDetails` object An optional object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the stakeholder's contact information. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | --------- | ------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | email | The individual stakeholder's email address. | Optional | Optional | Optional | | contactNo | The contact phone number of the individual stakeholder. | Optional | Optional | Optional | ##### `stakeholderDetails.documentDetails` object An array of object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's document details. This object is required only if `kycMode = MANUAL_KYC`. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | documentType | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required \* | Required | Required | | documentNumber | The ID number for the given document type. | Required \* | Required | Required | | documentIssuanceCountry | The country that issued the business document, specified in the [ISO 3166 format](https://www.iban.com/country-codes). This field is required for `NATIONAL_ID` and `PASSPORT`. | Required \* | Required | Required | | documentExpiryDate | The date the document will expire in `YYYY-MM-DD` format. Note: This field is required for `PASSPORT`. Expiry date cannot be a past date. | Required \* | Required | Required | | document | An array of objects that contains a copy of the document. | Required \* | Required | Required | ###### `documentDetails.document` object An array of object within the `businessDetails.stakeholders.stakeholderDetails.documentDetails` object. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | -------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | fileName | The name of the file. | Required \* | Required | Required | | fileType | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \* | Required | Required | | document | The file as a base64 encoded string. | Required \* | Required | Required | #### `businessPartner` An object within the `businessDetails.stakeholders` object with the business details about the corporate stakeholder. This object is required if a business partner exists. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | businessName | The registered business name of the corporate stakeholder. | Required | Required | Required | | businessRegistrationNumber | The business registration number. | Required | Required | Required | | businessEntityType | The position of the corporate stakeholder in the company. Use Fetch corporate constants API for a valid set of values. | Required | Required | Required | | sharePercentage | The share percentage of the corporate stakeholder in the company. | Optional | Optional | Optional | | legalDetails | An object that contains the legal details about the corporate stakeholder. | Required | Required | Required | ##### `businessPartner.legalDetails` object An object within the `businessDetails.stakeholders.businessPartner` object that contains the corporate stakeholder's legal details. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | registeredCountry | The country where the corporate stakeholder is registered, specified in the [ISO 3166 format](https://www.iban.com/country-codes). | Required | Required | Required | ### `applicantDetails` object An object within the `businessDetails` object that contains details about the applicant. | Property | Description | Government Private Sole trader | Public | Association Partner Trust | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------- | --------------------------- | | `referenceId` | The universally unique identifier (UUID) associated with the applicant and applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents. | Optional | Optional | Optional | | `kycMode` | The KYC mode for verifying the identity of the applicant. Applicable values are `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC`. For details, see [SG Applicant KYC](/docs/onboarding/corporate-customers/sg-onboarding#applicant-kyc) | Required | Required | Required | | `firstName` | The first name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Required | Required | Required | | `middleName` | The middle name of the applicant. Maximum length is 40 alphabetic characters or spaces. | Optional | Optional | Optional | | `lastName` | The last name or the applicant. The maximum length is 40 alphabetic characters or spaces. | Required | Required | Required | | `nationality` | Nationality of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `dateOfBirth` | The date on which the applicant was born in `YYYY-MM-DD` format. Date of birth cannot be future date. Applicant age should be less than 18 yrs. | Required | Required | Required | | [professionalDetails](#businessdetails-applicantdetails-professionaldetails) | An array of objects that contains the professional details about the applicant. | Required | Required | Required | | [address](#businessdetails-applicantdetails-address) | An object that contains the address of the applicant.. | Required | Required | Required | | [contactDetails](#businessdetails-applicantdetails-contactdetails) | An object that contains the contact details about the applicant. | Required | Required | Required | | [documentDetails](#businessdetails-applicantdetails-contactdetails) | An object that contains the document details about the applicant. **Note:** This field is required if `kycMode = MANUAL_KYC` or to submit `LOA`. | Required \* | Required \* | Required \* | #### `professionalDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the professional details about the applicant. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | position | The position of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | | sharePercentage | The share percentage of the applicant in the company. | Optional | Optional | Optional | #### `applicantDetails.address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | addressLine1 | The first address line of the applicant. The maximum character length is 40. | Required | Required | Required | | addressLine2 | The second address line of the applicant. The maximum character length is 40. | Optional | Optional | Optional | | city | The city of the applicant. Maximum character length is 20. | Required | Required | Required | | state | The state of the applicant. Maximum character length is 30. | Optional | Optional | Optional | | country | The country where the applicant resides, specified in the [ISO 3166 format](https://www.iban.com/country-codes). | Required | Required | Required | | postcode | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. | Required | Required | Required | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object that contains the applicant's contact information. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | email | The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See [Email regex](/docs/developers/nium-api#regular-expression-for-email). | Required | Required | Required | | countryCode | The country code of the applicant's phone number. | Required | Required | Required | | contactNo | The applicant's phone number. The maximum length is 20 numeric characters. | Required | Required | Required | #### `usinessDetails.applicantDetails.documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. This object is required if `kycMode = MANUAL_KYC` or to submit `LOA`. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ---------- | ------------------------- | | documentType | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required \* | Required\* | Required \* | | documentNumber | The ID number for the given document type. | Required \* | Required\* | Required \* | | documentIssuanceCountry | The country that issued the business document, specified in the [ISO 3166 format](https://www.iban.com/country-codes). This is required only if `documentType = NATIONAL_ID, PASSPORT`. | Required \* | Required\* | Required \* | | documentExpiryDate | The date the document expires in the`YYYY-MM-DD` format. This is required only if \`documentType = **PASSPORT**. Expiry date should not be past date. | Required \* | Required\* | Required \* | | document | An array of objects that contains the copy of the document. For details, see [SG required documents](/docs/onboarding/corporate-customers/sg-onboarding/required-documents). | Required \* | Required\* | Required \* | ##### `documentDetails.document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains the document copy. For details, see [SG required documents](/docs/onboarding/corporate-customers/sg-onboarding/required-documents). | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | -------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ---------- | ------------------------- | | fileName | The name of the file. | Required \* | Required\* | Required \* | | fileType | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Required \* | Required\* | Required \* | | document | The document saved as a base64 encoded string. | Required \* | Required\* | Required \* | ## `riskAssessmentInfo` object An object that contains the following details that are required to determine a corporate customer's risk profile. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | totalEmployees | The corporate customer's total number of employees. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | | annualTurnover | The corporate customer’s annual turnover. If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | | industrySector | The corporate customer's industry sector. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | | countryOfOperation | An array of countries the corporate customer operates in, specified in the [ISO 3166 format](https://www.iban.com/country-codes). | Required | Required | Required | | transactionCountries | An array of countries where the transactions occur, specified in the [ISO 3166 format](https://www.iban.com/country-codes). | Required | Required | Required | | intendedUseOfAccount | The customer's intended use of the account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | ## `deviceDetails` object This object contains the information about the customer's device and IP address where the onboarding request originated. | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------- | --------- | | `countryIP` | Country of the IP address, e.g., `US`. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Required | Required | Required | | `deviceInfo` | Information of the device, e.g., `Mac OS`. | Required | Required | Required | | `ipAddress` | IP address of the device, e.g., `45.48.241.198`. | Required | Required | Required | | `sessionId` | A unique identifier for the session, generated by your application. | Required | Required | Required | ## `expectedAccountUsage` object This object contains the details regarding the expected usage of the account | **Property** | **Description** | **Association** **Private** **Sole trader** | **Government** **Partnership** **Public** | **Trust** | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- | --------- | | `intendedUses` | Array of intended uses of the account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Required | Required | Required | ## `tags` object This object contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15. | Property | Description | Government/Private/Sole trader | Public | Association/Partner/Trust | | -------- | ------------------------------------------------------------------------------- | ------------------------------ | -------- | ------------------------- | | key | The name of the tag. The maximum character length is 128. Key should be unique. | Optional | Optional | Optional | | value | The value of the tag. The maximum character length is 256. | Optional | Optional | Optional | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/corporate-customers/sg-onboarding/required-documents This page outlines the documents required for stakeholders, applicants, and various business types to onboard a corporate customer registered in Singapore. ## Business details The following table lists the required document types for both verification types for all business entity types. | `businessType` | Manual KYB | eKYB | | :------------------ | :-------------------------- | :----------------- | | `ASSOCIATION` | `ASSOCIATION_DEED` | `ASSOCIATION_DEED` | | `GOVERNMENT_ENTITY` | `BUSINESS_REGISTRATION_DOC` | N/A | | `PARTNERSHIP` | `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | | `PRIVATE_COMPANY` | `BUSINESS_REGISTRATION_DOC` | N/A | | `PUBLIC_COMPANY` | `BUSINESS_REGISTRATION_DOC` | N/A | | `SOLE_TRADER` | `BUSINESS_REGISTRATION_DOC` | N/A | | `TRUST` | `TRUST_DEED` | `TRUST_DEED` | For a complete list of business document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. ## Stakeholders Nium offers `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC` modes for applicant KYC in Singapore. - For SG residents (based on address country) set the `kycMode` as `E_KYC` or `MANUAL_KYC` based on stakeholder preference. - For non-residents set `kycMode` as `E_DOC_VERIFY` or `MANUAL_KYC` based on the stakeholder preference. ### `E_KYC` or `E_DOC_VERIFY` | E\_DOC\_VERIFY (Documents to be uploaded in Onfido form) | E\_KYC | | :----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | Live Selfie with Passport/National ID/Driver's License and Proof of Address to be submitted in the form presented by Onfido (eDoc verification vendor) | No documents are required, only Singpass authentication | ### Manual KYC Every individual stakeholder needs to submit one of the following information when `kycMode = MANUAL_KYC`. | Field name | Passport | National ID | Driver license | | :------------------------ | :-------------------- | :------------ | :--------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVER_LICENSE` | | `documentNumber` | Yes (Passport number) | Yes | Yes | | `documentIssuanceCountry` | Yes | Yes | Yes | | `documentExpiryDate` | Yes | - | Yes | | `document.fileName` | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. > ⚠️ IMPORTANT > > If the document doesn't contain an address, you need to submit an [Acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) which can verify the address with `documentType = PROOF_OF_ADDRESS`. > > If this additional document is not submitted, the compliance agent will raise an RFI for `stakeholderAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport, Medicare Cards, or Driver's License. ## Applicants Nium offers `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC` modes for applicant KYC in Singapore. - `E_KYC` is applicable for SG residents via Myinfo verification. - `E_DOC_VERIFY` is applicable for non-SG residents. Applicant needs to complete KYC using the redirect URL. Document details need to be passed for `E_DOC_VERIFY` and upload of document files isn't required. - `MANUAL_KYC` required document details along with upload of document files. - Additionally, `LOA` is required for all KYC Modes when applicant is not a Director/ UBO ### `E_KYC` or `E_DOC_VERIFY` | E\_DOC\_VERIFY (Documents to be uploaded in Onfido form) | E\_KYC (Myinfo authentication) | API documents for both E\_DOC\_VERIFY, E\_KYC | | :----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Live Selfie with Passport/National ID/Driver's License and Proof of Address to be submitted in the form presented by Onfido (eDoc verification vendor) | No documents are required in Myinfo, only Singpass authentication | `LOA` will be required for all KYC modes when applicant is not a Director/ UBO and should be submitted via API. | ### Manual KYC Every individual applicant needs to submit one of the following information when `kycMode = MANUAL_KYC`. > ⚠️ IMPORTANT > > If the document doesn't contain an address, you need to submit an [Acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) which can verify the address with `documentType = PROOF_OF_ADDRESS`. > > If this additional document is not submitted, the compliance agent will raise an RFI for `applicantAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | Field name | Passport | National ID | Driver license | Letter Of Authorization when applicant isn't a `DIRECTOR` or `UBO` | Additional document if the first document doesn't contain an address | | :------------------------ | :-------------------- | :------------ | :--------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVER_LICENSE` | `LOA` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | No | | `documentExpiryDate` | Yes | No | Yes | No | No | | `document.fileName` | Yes | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | Yes | | `document.document` | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. See [Letter Of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for suggested format of LOA in case you do not have one. **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport, Medicare Cards, or Driver's License. ## Acceptable documents for `PROOF_OF_ADDRESS` | Individual stakeholder or applicant | Business details | | :----------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | | Bank statement Government-issued letter Utility bill (gas, electricity, internet, phone, water) | Bank statement Government-issued letter Utility bill (gas, electricity, internet, phone, water) | **NOTE**: The above documents are in addition to the standard documents mentioned in Business, Stakeholder, or Applicant section. These can be passed under the `documentType` `PROOF_OF_ADDRESS`. The above documents cannot be more than 90 days old when submitting. --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/sg-onboarding/position-mapping | businessType | DIRECTOR | EXECUTOR | MEMBERS | PARTNER | PROTECTOR | REPRESENTATIVE | SETTLOR | TRUSTEE | UBO | SHAREHOLDER | SIGNATORY | | `businessType` | `DIRECTOR` | `EXECUTOR` | `MEMBERS` | `PARTNER` | `PROTECTOR` | `REPRESENTATIVE` | `SETTLOR` | `TRUSTEE` | `UBO` | `SHAREHOLDER` | `SIGNATORY` | | ----------------- | :--------: | :--------: | :-------: | :-------: | :---------: | :--------------: | :-------: | :-------: | :---: | :------------ | :---------- | | Association | | | Yes | | | | | | | Yes | Yes | | Government entity | Yes | | | | | Yes | | | | Yes | Yes | | Partnership | Yes | | | Yes | | | | | | Yes | Yes | | Private company | Yes | | | | | Yes | | | Yes | Yes | Yes | | Public company | Yes | | | | | Yes | | | | Yes | Yes | | Sole trader | Yes | | | | | Yes | | | Yes | Yes | Yes | | Trust | | Yes | | | Yes | | Yes | Yes | Yes | Yes | Yes | A **Yes** value means that position can be passed for that `businessType`. A blank table cell means that position is not applicable for that `businessType`. Multiple positions in the `professionalDetails` array object as shown below: ```json "professionalDetails": [ { "position": "REPRESENTATIVE" }, { "position": "UBO", "sharePercentage": "50%" }, { "position": "SIGNATORY" } ``` --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/sg-onboarding/example-requests To onboard your entity, you can call the Onboard Corporate Customer API. For an example call that you can customize with your information, see: To onboard your entity, you can call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. For an example call that you can customize with your information, see: - [Private companies](#private) - [Public companies](#public) - [Partnerships](#partnership) - [Brazil Customer](#brazil-customer) - [Simulate scenarios in the eKYB flow](#simulate-scenarios-ekyb-flow) - [Simulate scenarios in the manual KYB flow](#simulate-scenarios-manual-kyb-flow) ## Private companies The following is an API request example call where `businessType = PRIVATE_COMPANY`. ```json { "region": "SG", "businessDetails": { "referenceId": "6913aac9-cbd9-4783-8fd6-07ea9655dfec", "businessName": "Singapor2e23 Electronics", "businessRegistrationNumber": "9223287324", "website":"www.singaporeelectronics.com", "businessType": "PRIVATE_COMPANY", "legalDetails": { "registeredCountry": "SG", "registeredDate": "2000-01-02" }, "addresses": { "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "document": "", "fileName": "BRD.pdf", "fileType": "application/pdf" } ] } ], "stakeholders": [ { "referenceId": "d25c5c6f-d4b0-47a5-986e-7b50641b65fc", "stakeholderDetails": { "firstName": "Narendra", "middleName": "C", "lastName": "Bhargav", "nationality": "IN", "kycMode": "MANUAL_KYC", "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO", "sharePercentage": "23" } ], "address": { "addressLine1": "MG road,25", "addressLine2": "Gandhinagar", "city": "Mumbai", "country": "IN", "postcode": "300012" }, "documentDetails": [ { "documentType": "PASSPORT", "documentExpiryDate": "2029-09-10", "documentIssuanceCountry": "IN", "documentNumber": "098734524", "document": [ { "document": "", "fileName": "Passport.pdf", "fileType": "application/pdf" } ] } ] } }, { "referenceId": "s36c5c6f-d4b0-47a5-986e-7b50641b66rf", "stakeholderDetails": { "firstName": "Narayana", "middleName": "R", "lastName": "Pandit", "nationality": "IN", "kycMode": "E_DOC_VERIFY", "professionalDetails": [ { "position": "DIRECTOR" } ], "address": { "addressLine1": "7 Koil street", "addressLine2": "64 No.01-01", "city": "Chennai", "country": "IN", "postcode": "600032" } } }, { "referenceId": "f45c5c6f-d4b0-47a5-986e-7b50641b67tf", "stakeholderDetails": { "firstName": "Rama", "middleName": "R", "lastName": "Krishna", "nationality": "IN", "kycMode": "E_KYC", "professionalDetails": [ { "position": "DIRECTOR" } ], "address": { "addressLine1": "7 Koil street", "addressLine2": "64 No.01-01", "city": "Chennai", "country": "IN", "postcode": "600032" } } }, { "referenceId": "006ebeeb-3ede-4f49-8381-1e382334131c", "businessPartner": { "legalDetails": { "registeredCountry": "FR" }, "businessEntityType": "SHAREHOLDER", "businessName": "Farto AgriTECH LIMITED", "businessRegistrationNumber": "822843822" } } ], "applicantDetails": { "referenceId": "0c61376b-70c3-4d45-9193-0a6ddece4e0e", "firstName": "Hardik", "middleName": "Kumar", "lastName": "Roshan", "dateOfBirth": "1982-07-17", "nationality": "SG", "kycMode": "E_KYC", "contactDetails": { "contactNo": "222268870", "countryCode": "SG", "email": "hardik@singel.com" }, "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "additionalInfo": { "isSameBusinessAddress": "Yes", "searchId": "6nf3aac9-cbd9-423k-8fd6-07ea9345dfec" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "GB", "AU", "FR" ], "totalEmployees": "EM009", "annualTurnover": "SG011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Public companies The following is an API request example call where `businessType = PUBLIC_COMPANY`. ```json { "region": "SG", "businessDetails": { "referenceId": "6913aac9-cbd9-4783-8fd6-07ea9655dfec", "businessName": "Singapore Special Appliances", "businessRegistrationNumber": "903280424", "website":"www.singaporeappliances.com", "businessType": "PUBLIC_COMPANY", "legalDetails": { "registeredCountry": "SG", "registeredDate": "2000-01-02", "listedExchange": "EX080" }, "addresses": { "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "document": "", "fileName": "BRD.pdf", "fileType": "application/pdf" } ] } ], "stakeholders": [ { "referenceId": "d25c5c6f-d4b0-47a5-986e-7b50641b65fc", "stakeholderDetails": { "firstName": "John", "middleName": "C", "lastName": "Grisham", "nationality": "IN", "kycMode": "MANUAL_KYC", "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO", "sharePercentage": "60" } ], "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "country": "SG", "postcode": "28046" }, "documentDetails": [ { "documentType": "PASSPORT", "documentExpiryDate": "2029-09-10", "documentIssuanceCountry": "IN", "documentNumber": "098734524", "document": [ { "document": "", "fileName": "Passport.pdf", "fileType": "application/pdf" } ] } ] } }, { "referenceId": "006ebeeb-3ede-4f49-8381-1e382334131c", "businessPartner": { "legalDetails": { "registeredCountry": "FR" }, "businessEntityType": "SHAREHOLDER", "businessName": "Fiago AgriTECH LIMITED", "businessRegistrationNumber": "822843822" } } ], "applicantDetails": { "referenceId": "0c61376b-70c3-4d45-9193-0a6ddece4e0e", "firstName": "Mitchell", "middleName": "", "lastName": "Johnson", "dateOfBirth": "1982-07-17", "nationality": "SG", "kycMode": "E_KYC", "contactDetails": { "contactNo": "222268870", "countryCode": "SG", "email": "hardik@singel.com" }, "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "additionalInfo": { "isSameBusinessAddress": "Yes", "searchId": "6nf3aac9-cbd9-423k-8fd6-07ea9345dfec" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "GB", "AU", "FR" ], "totalEmployees": "EM009", "annualTurnover": "SG011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Partnerships The following is an API request example call where `businessType = PARTNERSHIP`. ```json { "region": "SG", "businessDetails": { "referenceId": "6913aac9-cbd9-4783-8fd6-07ea9655dfec", "businessName": "S&K Partners", "businessRegistrationNumber": "903272424", "website":"www.snkpartners.com", "businessType": "PARTNERSHIP", "legalDetails": { "registeredCountry": "SG", "registeredDate": "2000-01-02" }, "addresses": { "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "documentDetails": [ { "documentType": "PARTNERSHIP_DEED", "document": [ { "document": "", "fileName": "PARTNERSHIPDeed.pdf", "fileType": "application/pdf" } ] } ], "stakeholders": [ { "referenceId": "d25c5c6f-d4b0-47a5-986e-7b50641b65fc", "stakeholderDetails": { "firstName": "Samuel", "middleName": "C", "lastName": "Dickenson", "nationality": "US", "kycMode": "MANUAL_KYC", "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO" } ], "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "country": "SG", "postcode": "28046" }, "documentDetails": [ { "documentType": "PASSPORT", "documentExpiryDate": "2029-09-10", "documentIssuanceCountry": "SG", "documentNumber": "098734524", "document": [ { "document": "", "fileName": "Passport.pdf", "fileType": "application/pdf" } ] } ] } }, { "referenceId": "006ebeeb-3ede-4f49-8381-1e382334131c", "businessPartner": { "legalDetails": { "registeredCountry": "FR" }, "businessEntityType": "SHAREHOLDER", "businessName": "Soso FINTECH LIMITED", "businessRegistrationNumber": "FL22843822" } } ], "applicantDetails": { "referenceId": "0c61376b-70c3-4d45-9193-0a6ddece4e0e", "firstName": "Katrina", "middleName": "", "lastName": "Kaif", "dateOfBirth": "1982-07-17", "nationality": "SG", "kycMode": "E_KYC", "contactDetails": { "contactNo": "222268870", "countryCode": "SG", "email": "katkaif@snkpartners.com" }, "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "additionalInfo": { "isSameBusinessAddress": "Yes", "searchId": "6nf3aac9-cbd9-423k-8fd6-07ea9345dfec" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "GB", "AU", "FR" ], "totalEmployees": "EM009", "annualTurnover": "SG011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` The following is an API request to onboard a customer from Brazil. ```json { "region": "SG", "businessDetails": { "businessName": "Brazil Consumer E231l1ectronics", "businessRegistrationNumber": "229223287324", "businessType":"PRIVATE_COMPANY", "legalDetails": { "registeredCountry": "BR", "registeredDate": "2000-01-02" }, "taxDetails": [ { "country": "BR", "taxNumber": "40.828.622/0001-27" } ], "addresses": { "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "stakeholders": [ { "referenceId": "d25c5c6f-d4b0-47a5-986e-7b50641b65fc", "stakeholderDetails": { "firstName": "Narendra", "middleName": "C", "lastName": "Bhargav", "nationality": "IN", "kycMode": "MANUAL_KYC", "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO" } ], "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "country": "SG", "postcode": "28046" }, "documentDetails": [ { "documentType": "PASSPORT", "documentExpiryDate": "2029-09-10", "documentIssuanceCountry": "IN", "documentNumber": "098734524", "document": [ { "document": "", "fileName": "Passport.pdf", "fileType": "application/pdf" } ] } ] } }, { "referenceId": "006ebeeb-3ede-4f49-8381-1e382334131c", "businessPartner": { "legalDetails": { "registeredCountry": "FR" }, "businessEntityType": "SHAREHOLDER", "businessName": "Farto AgriTECH LIMITED", "businessRegistrationNumber": "822843822" } } ], "applicantDetails": { "referenceId": "0c61376b-70c3-4d45-9193-0a6ddece4e0e", "firstName": "Hardik", "middleName": "Kumar", "lastName": "Roshan", "dateOfBirth": "1982-07-17", "nationality": "BR", "kycMode": "E_DOC_VERIFY", "contactDetails": { "contactNo": "222268870", "countryCode": "BR", "email": "hardik@singel.com" }, "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "Rua Santo Antônio 1235", "addressLine2": "Resende", "city": "Rio de Janeiro", "country": "BR", "postcode": "27536-010" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN" ], "transactionCountries": [ "GB", "AU", "FR" ], "totalEmployees": "EM009", "annualTurnover": "SG011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Simulate scenarios in the eKYB flow If you are using eKYB flow for the Singapore region, you can generate the following scenarios by using the below steps with the example `businessRegistrationNumber` (BRN) in the following table. | Simulated scenario | Condition on BRN | Example BRN | | :------------------------------------------------------------------------------------- | :----------------------------------------------------- | :------------------------------------ | | [Auto-approval](#request-example-auto-approval) | Contains `M01` | `M01324536`, `234M01456`, `12M01B325` | | [Action required](#request-example-action-required) | Contains `A02` | `A02324536`, `234A02456`, `12A02B325` | | [In progress with documents required](#request-example-in-progress-documents-required) | Contains `A03` | `A03324536`, `234A03456`, `12A03B325` | | [Completing applicant eKYC](#completing-applicant-ekyc) | Pattern on `applicantDetails.contactDetails.contactNo` | | | [Completing applicant eDocVerify](#completing-applicant-edocverify) | Pattern on `applicantDetails.contactDetails.contactNo` | | **Step 1:** Call the [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API using the Business Registration Number and Region according to the scenario you want to test. You receive multiple businesses in the response. Pick the one with with matching `businessRegistrationNumber` and copy the `searchReferenceId`. In this response, the `businessName` is always returned as `STAR FINANCE PRIVATE LIMITED` appended by your `businessRegistrationNumber` and doesn't match with what is returned in Step 2. This behavior is only in the sandbox; the accurate name appears in production. **Step 2:** Call the [Exhaustive Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) API using the `searchReferenceId` received in Step 1 for the particular scenario. This returns detailed information about the corporate customer including `searchId`. **Step 3:** Use the example requests in the table and call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. **Step 4:** Use the redirect URL and complete the **Applicant KYC** section on the MyInfo page (or use the simulated scenarios for KYC mentioned below) and wait for the webhook. Verification can be completed with dummy credentials if using Myinfo's sandbox. Regardless, you need to open the redirect URL in your browser. ### Response conditions for the Exhaustive Corporate Details API You can generate responses for different `businessType` by following the table below. This can be used for testing the pre-population flow after calling the Exhaustive Corporate Details Using Business ID API. | `businessType` | Condition on `businessRegistrationNumber` | | :---------------- | :---------------------------------------- | | `PUBLIC_COMPANY` | Contains `A01` or `A02` or `A03` | | `PRIVATE_COMPANY` | Contains `A11` or `A12` or `A13` | | `SOLE_TRADER` | Contains `A21` or `A22` or `A23` | | `PARTNERSHIP` | Contains `A31` or `A32` or `A33` | ### Request example: auto-approval For the description of this scenario, see [Auto-approval scenario](/docs/onboarding/corporate-customers/using-the-sandbox#auto-approval) ```json { "region": "SG", "businessDetails": { "businessName": "ACME COMPANY PTE. LTD. PWUIMRBF", "businessRegistrationNumber": "A11232393", "businessType": "PUBLIC_COMPANY", "legalDetails": { "registeredCountry": "SG", "registeredDate": "2021-07-13", "listedExchange": "EX056" }, "addresses": { "registeredAddress": { "addressLine1": "22 CIRCULAR ROAD , 02 - 01", "addressLine2": "-", "city": "SINGAPORE", "state": "SINGAPORE", "country": "SG", "postcode": "049422" } }, "stakeholders": [ { "stakeholderDetails": { "firstName": "MANISHA", "middleName": null, "lastName": "XUCCH", "nationality": "IN", "dateOfBirth": null, "kycMode": "E_KYC", "address": { "addressLine1": "A - 2/5, CHANDER PRIYA APARTMENT, SECTOR -9, NEAR GANESH MRI", "addressLine2": "ROHINI, NORTH WEST DELHI", "city": "ROHINI", "state": "NEW DELHI", "country": "IN", "postcode": "110085" }, "contactDetails": null, "professionalDetails": [ { "position": "UBO", "sharePercentage": "27" }, { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "businessPartner": null }, { "stakeholderDetails": { "firstName": "TANISHA", "middleName": null, "lastName": "FLEZY", "nationality": "IN", "dateOfBirth": null, "kycMode": "E_KYC", "address": { "addressLine1": "A - 2/5, CHANDER PRIYA APARTMENT, SECTOR -9, NEAR GANESH MRI", "addressLine2": "ROHINI, NORTH WEST DELHI", "city": "ROHINI", "state": "NEW DELHI", "country": "IN", "postcode": "110085" }, "contactDetails": null, "professionalDetails": [ { "position": "SHAREHOLDER", "sharePercentage": "5" } ], "documentDetails": null }, "businessPartner": null }, { "stakeholderDetails": { "firstName": "TANYA", "middleName": null, "lastName": "SHKZREB", "nationality": "SG", "dateOfBirth": null, "address": { "addressLine1": "39 ROBINSON ROAD", "addressLine2": "11-01,ROBINSON POINT", "city": "SINGAPORE", "state": "SINGAPORE", "country": "SG", "postcode": "068911" }, "contactDetails": null, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "businessPartner": null } ], "applicantDetails": { "firstName": "TEO", "middleName": null, "lastName": "SHfOCCF", "nationality": "SG", "dateOfBirth": "1989-10-10", "kycMode": "E_KYC", "address": { "addressLine1": "15 ST. GEORGE'S ROAD", "addressLine2": "05-166", "city": "SINGAPORE", "state": "SINGAPORE", "country": "SG", "postcode": "32015" }, "contactDetails": { "contactNo": "32423411", "countryCode": "SG", "email": "teo.sg@yopmail.com" }, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "additionalInfo": { "searchId": "2ea658b7-6ce3-4f2b-b22d-dab0b1ea0abb", "companyStatus": "LIVE COMPANY", "isSameBusinessAddress": "yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "SG011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "SG", "US", "GB" ], "transactionCountry": [ "DE", "JP", "IN" ] } } ``` ### Request example: action required For the description of this scenario, see [Action required scenario](/docs/onboarding/corporate-customers/using-the-sandbox#action-required) ```json { "region": "SG", "businessDetails": { "businessName": "ACME COMPANY PTE. LTD. PWUIMRBF", "businessRegistrationNumber": "A11232393", "businessType": "PUBLIC_COMPANY", "legalDetails": { "registeredCountry": "SG", "registeredDate": "2021-07-13", "listedExchange": "EX056" }, "addresses": { "registeredAddress": { "addressLine1": "22 CIRCULAR ROAD , 02 - 01", "addressLine2": "-", "city": "SINGAPORE", "state": "SINGAPORE", "country": "SG", "postcode": "049422" } }, "stakeholders": [ { "stakeholderDetails": { "firstName": "MANISHA", "middleName": null, "lastName": "XUCCH", "nationality": "IN", "dateOfBirth": null, "kycMode": "E_KYC", "address": { "addressLine1": "A - 2/5, CHANDER PRIYA APARTMENT, SECTOR -9, NEAR GANESH MRI", "addressLine2": "ROHINI, NORTH WEST DELHI", "city": "ROHINI", "state": "NEW DELHI", "country": "IN", "postcode": "110085" }, "contactDetails": null, "professionalDetails": [ { "position": "UBO", "sharePercentage": "27" }, { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "businessPartner": null }, { "stakeholderDetails": { "firstName": "TANISHA", "middleName": null, "lastName": "FLEZY", "nationality": "IN", "dateOfBirth": null, "kycMode": "E_KYC", "address": { "addressLine1": "A - 2/5, CHANDER PRIYA APARTMENT, SECTOR -9, NEAR GANESH MRI", "addressLine2": "ROHINI, NORTH WEST DELHI", "city": "ROHINI", "state": "NEW DELHI", "country": "IN", "postcode": "110085" }, "contactDetails": null, "professionalDetails": [ { "position": "SHAREHOLDER", "sharePercentage": "5" } ], "documentDetails": null }, "businessPartner": null }, { "stakeholderDetails": { "firstName": "TANYA", "middleName": null, "lastName": "SHKZREB", "nationality": "SG", "dateOfBirth": null, "address": { "addressLine1": "39 ROBINSON ROAD", "addressLine2": "11-01,ROBINSON POINT", "city": "SINGAPORE", "state": "SINGAPORE", "country": "SG", "postcode": "068911" }, "contactDetails": null, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "businessPartner": null } ], "applicantDetails": { "firstName": "TEO", "middleName": null, "lastName": "SHfOCCF", "nationality": "SG", "dateOfBirth": "1989-10-10", "kycMode": "MANUAL_KYC", "address": { "addressLine1": "15 ST. GEORGE'S ROAD", "addressLine2": "05-166", "city": "SINGAPORE", "state": "SINGAPORE", "country": "SG", "postcode": "32015" }, "contactDetails": { "contactNo": "32423411", "countryCode": "SG", "email": "teo.sg@yopmail.com" }, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "additionalInfo": { "searchId": "2ea658b7-6ce3-4f2b-b22d-dab0b1ea0abb", "isSameBusinessAddress": "yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "SG011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "SG", "US", "GB" ], "transactionCountry": [ "DE", "JP", "IN" ] } } ``` ### Request example: in progress with documents required For the description of this scenario, see [In progress scenario](/docs/onboarding/corporate-customers/using-the-sandbox#in-progress) ```json { "region": "SG", "businessDetails": { "businessName": "ACME COMPANY PTE. LTD. 8083", "businessRegistrationNumber": "A0183473323", "businessType": "PRIVATE_COMPANY", "legalDetails": { "registeredCountry": "SG", "registeredDate": "2017-07-08" }, "addresses": { "registeredAddress": { "addressLine1": "67 HIGH STREET, 06-08", "addressLine2": "SATNAM HOUSE", "city": "SINGAPORE", "state": "SINGAPORE", "country": "SG", "postcode": "179431" } }, "stakeholders": [ { "entityType": "CORPORATE", "stakeholderDetails": null, "businessPartner": { "businessName": "TANYA SH VKP", "businessRegistrationNumber": "E6554322", "businessEntityType": "Shareholder", "addresses": { "registeredAddress": { "addressLine1": "2 PANDAN VALLEY", "addressLine2": "02-212, ACACIA COURT", "city": "SINGAPORE", "state": "SINGAPORE", "country": "SG", "postcode": "079903" } }, "legalDetails": { "registeredCountry": "SG" } } }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "ROBERT", "middleName": "SH", "lastName": "UWW", "nationality": "VG", "dateOfBirth": null, "address": { "addressLine1": "85 JLN DEDAP 7 TAMAN JAYA", "addressLine2": "JOHOR BAHRU, JOHOR", "city": "MALAYSIA", "state": "MALAYSIA", "country": "MY", "postcode": "81100" }, "contactDetails": null, "professionalDetails": [ { "position": "UBO", "sharePercentage": "52.4" } ], "documentDetails": null }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "PETER", "middleName": null, "lastName": "TQ", "nationality": "MN", "dateOfBirth": null, "address": { "addressLine1": "85 JLN DEDAP 7 TAMAN JAYA", "addressLine2": "JOHOR BAHRU, JOHOR", "city": "MALAYSIA", "state": "MALAYSIA", "country": "MY", "postcode": "81100" }, "contactDetails": null, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "TEO", "middleName": null, "lastName": "GI", "nationality": "SG", "dateOfBirth": null, "address": { "addressLine1": "15 ST. GEORGE'S ROAD", "addressLine2": "05-166", "city": null, "state": null, "country": "SG", "postcode": "32015" }, "contactDetails": null, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "businessPartner": null } ], "applicantDetails": { "firstName": "TEO", "middleName": null, "kycMode": "MANUAL_KYC", "lastName": "jksdhf", "nationality": "GB", "dateOfBirth": "1989-10-10", "address": { "addressLine1": "15 ST. GEORGE'S ROAD", "addressLine2": "05-166", "city": "LONDON", "state": "LONDON", "country": "GB", "postcode": "32015" }, "contactDetails": { "contactNo": "32423411", "countryCode": "SG", "email": "teo.sg@yopmail.com" }, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "additionalInfo": { "searchId": "c0be4204-698b-4c76-b17b-48d977304286", "isSameBusinessAddress": "yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "SG011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "SG", "US", "GB" ], "transactionCountry": [ "DE", "JP", "IN" ] } } ``` ### Completing applicant eKYC For Singapore residents, the applicant eKYC is done via MyInfo. To simulate different success and error responses of the eKYC flow, use the following conditions on the applicant's phone number. In all cases, the applicant needs to open the redirectURL in their browser. You either land on the vendor’s page or receive a success/failure redirection back to your client KYC redirect URL without any actions needed on the UI. The redirectURL has `isSuccess`, `errorCode`, and `errorMessage` parameters as described in [Applicant KYC](/docs/onboarding/corporate-customers/sg-onboarding#applicant-kyc). Based on `businessDetails.applicantDetails.contactDetail.contactNumber`, there are two outcomes: | First two digits of `contactNumber` | Resulting situation | | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Doesn't contain any of the simulated patterns | Myinfo’s sandbox page is opened and the applicant needs to complete the simulated authentication on the UI. This can be used for end-to-end testing. | | Does contain any of the simulated patterns | The customer's browser redirects to your KYC redirect URL without the need of any actions on the UI. Redirection will contain the following [Redirection parameters](#redirection-parameters) | #### Redirection parameters | Return code | Query parameters in the redirection | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 21 | `isSuccess = false`; `errorCode = R500`; `errorMessage = internalServerError` | | 71 | `isSuccess = false` ; `errorCode = I400`; `errorMessage = vendorValidationError` | | 91 | `isSuccess = true` ; `errorCode =`; `errorMessage =` Opening the redirect URL twice will generate the verification already completed scenario: `isSuccess = false` ; `errorCode =`; `errorMessage=verificationAlreadyCompleted` | ### Completing applicant eDocVerify For non-Singapore residents, the applicant eDocVerify is done via the third-party vendor Onfido. Applicant KYC via Onfido takes place for the Singapore region when the KYC mode is `E_DOC_VERIFY`. To simulate different success and error responses of the eDocVerify flow, use the following conditions on the applicant's phone number. In all cases, the applicant needs to open the redirect URL in their browser. You either land on the vendor’s page or receive a success/failure redirection back to your KYC redirect URL without any actions needed on the UI. The redirectURL has `isSuccess`, `errorCode`, and `errorMessage` parameters as described in [Applicant KYC](/docs/onboarding/corporate-customers/sg-onboarding#applicant-kyc). Based on `businessDetails.applicantDetails.contactDetail.contactNumber`, there are two outcomes: | First two digits of `contactNumber` | Resulting situation | | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Doesn't contain any of the simulated patterns | Onfido's sandbox page is opened and the applicant needs to complete the simulated authentication on the UI. This can be used for end-to-end testing. | | Does contain any of the simulated patterns | The customer's browser redirects to your KYC redirect URL without the need of any actions on the UI. Redirection will contain the following [Redirection parameters](#redirection-parameters) | #### Redirection parameters | Return code | Query parameters in the redirection | | :---------- | :---------------------------------------------------------------------------------- | | 91 | `isSuccess`=`true`; `errorCode`=;`erroressage`= | | 41 | `isSuccess = false` ; `errorCode = R403`; `errorMessage = documentAlreadySubmitted` | | 51 | `isSuccess = false` ; `errorCode = I500`; `errorMessage = unexpectedError` | | 61 | `isSuccess = false` ; `errorCode = R408`; `errorMessage = redirectUrlExpired` | Note: You can test the `verificationAlreadyCompleted` message by clicking on the `redirectURL` after completing verification. ## Simulate scenarios in the manual KYB flow You might want to test transactions without going through the onboarding flow. To enable this, Nium provides simulated requests which get auto-approved in the manual KYB flow. You can generate auto-approval scenarios for manual KYB only in the sandbox environment. In production, every application is reviewed by Nium's compliance analysts before approval. | Simulated scenario | Condition on BRN | Example BRN | | :---------------------------------------------- | :--------------- | :------------------------------------ | | [Auto-approval](#request-example-auto-approval) | Contains `M01` | `M01324536`, `234M01456`, `12M01B325` | Call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API with the following example request. ### Request example: auto-approval ```json { "region": "SG", "businessDetails": { "referenceId": "6913aac9-cbd9-4783-8fd6-07ea9655dfec", "businessName": "Singapore Electronics 27779", "businessRegistrationNumber": "903287424M01233", "website":"www.singaporeelectronics.com", "businessType": "PRIVATE_COMPANY", "legalDetails": { "registeredCountry": "SG", "registeredDate": "2000-01-02" }, "addresses": { "registeredAddress": { "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "document": "", "fileName": "BRD.pdf", "fileType": "application/pdf" } ] } ], "stakeholders": [ { "referenceId": "d25c5c6f-d4b0-47a5-986e-7b50641b65fc", "stakeholderDetails": { "firstName": "Narendra", "middleName": "C", "lastName": "Bhargav", "dateOfBirth": "1982-07-17", "nationality": "IN", "kycMode": "MANUAL_KYC", "professionalDetails": [ { "position": "DIRECTOR" }, { "position": "UBO", "sharePercentage": "60" } ], "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "country": "SG", "postcode": "28046" }, "documentDetails": [ { "documentType": "PASSPORT", "documentExpiryDate": "2029-09-10", "documentIssuanceCountry": "IN", "documentNumber": "098734524", "document": [ { "document": "", "fileName": "Passport.pdf", "fileType": "application/pdf" } ] } ] } }, { "referenceId": "006ebeeb-3ede-4f49-8381-1e382334131c", "businessPartner": { "legalDetails": { "registeredCountry": "FR" }, "businessEntityType": "SHAREHOLDER", "businessName": "Farto AgriTECH LIMITED", "businessRegistrationNumber": "822843822" } } ], "applicantDetails": { "referenceId": "0c61376b-70c3-4d45-9193-0a6ddece4e0e", "firstName": "Hardik", "middleName": "", "lastName": "Roshan", "dateOfBirth": "1982-07-17", "nationality": "SG", "kycMode": "E_KYC", "contactDetails": { "contactNo": "222268870", "countryCode": "SG", "email": "hardik@singel.com" }, "professionalDetails": [ { "position": "SIGNATORY" } ], "address": { "addressLine1": "7 Ang Mo Kio Street", "addressLine2": "64 No.01-01", "city": "Singapore", "country": "SG", "postcode": "28046" } }, "additionalInfo": { "isSameBusinessAddress": "Yes", "searchId": "6nf3aac9-cbd9-423k-8fd6-07ea9345dfec" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "SG011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "SG", "US", "GB" ], "transactionCountry": [ "DE", "JP", "IN" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` --- # UK Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/uk-onboarding This page contains details about the United Kingdom Know Your Business (KYB) flows and links to the following sub-pages for a quick reference: | Page name | Description | | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | **[UK required parameters](/docs/onboarding/corporate-customers/uk-onboarding/required-parameters)** | This page lists the required API fields of each entity type. | | **[UK required documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents)** | This page contains tables listing the required documents for verification of the business entity, stakeholders, and applicants. | | **[UK position mapping](/docs/onboarding/corporate-customers/au-onboarding/position-mapping)** | This page gives a quick glance at the required positions of each entity type. | | **[UK request examples](/docs/onboarding/corporate-customers/uk-onboarding/example-requests)** | This page contains API request examples for UK entities. | Nium offers eKYB and Manual KYB flows for customers in the United Kingdom. The eKYB flow is fully automated, allowing corporate customers to be approved within a few minutes of submitting their application, making it the preferred mode for all customers. Reach out to Nium's sales team to configure the eKYB flow for your account. ## eKYB flow The following steps are required to complete the eKYB application. UK Onboarding ### Step 1. Get Public Corporate Details Using Business ID API To start the eKYB process, collect the basic details about the corporate customer from the applicant through an onboarding form, including the `businessRegistrationNumber` and `countryCode`. For a list of valid country codes, see [Currency and country codes](/docs/getting-started/currency-and-country-codes). Then, call Nium's [Public Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v1/client/{clientHashId}/corporate/lookup) API. This API returns publicly available information about the corporate customer, which you then display to the customer so they can select and confirm the `businessName` and `businessRegistrationNumber` along with any other optional details. You need to store the `searchReferenceId` that's returned in this response since it's required in subsequent steps. This API may return multiple results for a given `businessRegistrationNumber`. When there's more than one, display the results to let the customer select the correct one. When no results are returned, call the Onboard Corporate Customer API with a full request body. Such applications go through manual review, making the eKYB process not applicable in this case. ### Step 2. Get Exhaustive Corporate Details Using Business ID API Call the [Exhaustive Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) API using the `searchReferenceId` stored in [Step 1](#step-1-get-public-corporate-details-using-business-id-api) as the parameter. This returns the public and non-public information about the corporate customer. You need to store the `searchId` that's returned in this response since it's required in the subsequent steps. This is a chargeable API. Work with your Nium representative before using it. It's best to use this API only once per customer. ### Step 3. Display the information to the applicant You need to display the above-received information to the applicant for their confirmation, edits, or additions. Then, submit the form. All the fields required to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API are collected in this step. Any additional fields that are required, and not returned in the above step, are to be added by the applicant. ### Step 4. Post Onboard Corporate Customer API You then call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API with the full request body, including the `searchId` you stored in Step 2. If the `searchId` parameter isn't passed, the application is treated as `MANUAL_KYB` and goes through a manual review. #### Applicant KYC As a response to the Onboard Corporate Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirectURL. The applicant then lands on the KYC vendor's page, where he can complete the KYC verification by uploading his proof of identity and proof of address documents with a live selfie. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium. You need to show the success or failure message to the applicant once redirected back. You need to pass `E_DOC_VERIFY` as `businessDetails.applicantDetails.kycMode` for all applications. Once the flow is compelted on the vendor's page, applicant is redirected to client's E\_KYC redirect URL. The following parameters available in redirection can have different values based on the following scenarios. - `errorCode` - `errorMessage` - `isSuccess` – This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. - `referenceId` (used to identify the individual for whom redirection happened.) | Scenario | Expected action from client | Query parameters in the redirection | | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | The applicant completed the required steps in the vendor’s UI. | Wait for webhook. | `errorCode`: N/A `errorMessage`: N/A `isSuccess`: TRUE | | The document has already been submitted in the vendor's UI. | KYC Process is completed. Client needs to wait for webhook. | `errorCode`: R403 `errorMessage`: documentAlreadySubmitted `isSuccess`: FALSE | | The customer has provided incorrect data in the vendor's UI. (customer didn't click accept in the vendor's page) | Ask customer to submit correct data in the vendors page. | `errorCode`: I400 `errorMessage`: vendorValidationError `isSuccess`: FALSE | | Verification failure at the vendor. | The application goes to manual review. The client needs to wait for webhook. | `errorCode`: R401 `errorMessage`: vendorVerificationFailure `isSuccess`: FALSE | | Internal Server error at Nium. | Try after some time or reach out to Nium's support. | `errorCode`: R500 `errorMessage`: internalServerError `isSuccess`: FALSE | | Any unexpected error from the vendor. | Try after some time or reach out to Nium's support. | `errorCode`: I500 `errorMessage`: unexpectedError `isSuccess`: FALSE | | Validation already completed and customer retries the same link. | KYC Process is completed. The client need to wait for webhook. | `errorCode`: R606 `errorMessage`: verificationAlreadyCompleted `isSuccess`: FALSE | Based on the scenario, you can implement the next steps as provided in the table above. Example success redirect: ``` https://www.clientRedirectURL.com/?clientId=...&caseId=4ff53849-3d30-45c8-af11-f95c315ce83c&isSuccess=true&errorCode=&errorMessage=f95c315ce83c&isSuccess=true&errorCode=&errorMessage=&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX ``` Example failure redirect: ``` https://www.clientRedirectURL.com/?clientId=...&errorCode=R403&isSuccess=false ``` - For **US** addresses, use a valid two-letter `state` code. - For **GB** addresses, use the **SW4 6EH** postcode format. #### Stakeholder KYC For the eKYB flow, `E_KYC`, `E_DOC_VERIFY` and `MANUAL_KYC` modes are offered for KYC of individual stakeholders. - You're required to pass `E_KYC` for UK residents. - For non-UK residents `E_DOC_VERIFY` or `MANUAL_KYC` can be passed in `businessDetails.applicantDetails.kycMode` based on stakeholder preference. - `E_DOC_VERIFY` will require live-selfie and hence should be used only when stakeholder is accessible. For details on implementation, see **[Onboard API Response - 200 response](/docs/onboarding/corporate-customers#onboard-api-response)** The `referenceId` available in the browser redirection is the same as the one submited in the Onboard API request for the stakeholder. In case, multiple stakeholders have redirectURL, you can use the referenceId to identify them and land them to the appropriate page as required. The `kycMode` is required only when the position of the individual stakeholder is `UBO`, `DIRECTOR`, `TRUSTEE`, `PARTNER`, or `MEMBER`, `REPRESENTATIVE`, \`\` and can be ignored for other positions. Applications with `MANUAL_KYC` go through manual review and cannot be verified in real-time. Uploading of documents is mandatory for `MANUAL_KYC`, which needs to be sent in `businessDetails.applicantDetails.documentDetails`. For details, see [UK required documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents). #### Upload documents If `searchId` isn't passed, a document upload is required. Even if `searchId` is passed, some documents might be required in certain scenarios. Nium doesn't initiate verification until all required documents are submitted. All required documents can be submitted in two ways: - [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request - [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request The [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) API is preferred since it uploads one document at a time, which reduces the loading time. This API can be called only while the application is in the `IN_PROGRESS` state. You can use the `remarks` field to list which documents Nium is expects in the response of both APIs. The API gateway has a limit of 10 MB for any API request. This makes Upload Document API the preferred way to upload documents since you can upload one document at a time. For the entire list of required documents for manual and eKYB flows, see [UK required documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents). #### Terms and Conditions You must show customers the Nium terms and conditions configured for your `client` resource. You can fetch these specific terms and conditions using our [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions). Customers can only submit the onboarding form once they accept the terms and conditions. To fetch the [Terms And Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/{clientHashId}/termsAndConditions): 1. Wait for the Onboarding API to return a `customerHashId`. 2. Once returned, call our [Accept Terms and Conditions API](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) and include the `customerHashId`. 3. Show the customer the returned terms and conditions and record their acceptance before allowing them to transact. For more details, see [Terms and Conditions](/docs/onboarding/corporate-customers#terms-and-conditions). ### Step 5. Wait for webhook response After submission, the `status` in the Onboard Corporate Customer response is `IN_PROGRESS`. The applicant needs to complete both the [Applicant KYC](#applicant-kyc) and [Upload documents](#upload-documents) steps to proceed further. Once done, Nium initiates real-time verification and sends the response via a webhook. The application might be approved at this stage; and if it isn't approved, the application goes through a manual review. Any changes in the `status` is again communicated via a webhook. For the next steps based on the response of the webhook, see [Webhooks](/docs/onboarding/corporate-customers#webhooks). ## Manual KYB flow UK Manual KYB For manual KYB, you need to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API directly. In this flow, the entire request body needs to be passed in the Onboard Corporate Customer API. Important points to keep in mind: - Nium doesn't initiate verification until all required documents are submitted. - You need to pass `E_DOC_VERIFY` as `businessDetails.applicantDetails.kycMode` for all applications. For details on implementing `E_DOC_VERIFY`, see [Applicant KYC](#applicant-kyc). - The applicant is required to complete the KYC process using the redirect link via Nium's vendor Onfido. - Use `E_DOC_VERIFY` or `MANUAL_KYC` based on stakeholder preference and include required documents in `businessDetails.stakeholders.stakeholderDetails.documentDetails` for `MANUAL_KYC`. `E_DOC_VERIFY` will require live-selfie and hence should be used when stakeholder is accessible. - `kycMode` is required only when the position of the individual stakeholder is `UBO`/ `DIRECTOR`/ `TRUSTEE`/ `PARTNER`/ `MEMBER`/ `REPRESENTATIVE`/ `SIGNATORY`. Uploading of documents is required for manual KYC, which needs to be sent in `businessDetails.stakeholder.stakeholderDetails.documentDetails`. For details, see [Stakeholder documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents#stakeholders) - Terms and Conditions flow is same mentioned in the eKYB flow. After the submission, the `status` in the response of the Onboard Corporate Customer API is `IN_PROGRESS`. Once documents are uploaded and the KYC process completes, Nium initiates manual verification and sends the response via a webhook. For the next steps based on the response of the webhook, see [Notifications and Webhooks](/docs/developers/notifications-and-webhooks). --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/uk-onboarding/required-parameters The API fields shown on this page are relevant to the United Kingdom only. To see the full payload, refer to the Onboard Corporate Customer API Reference. The API fields shown on this page are relevant to the United Kingdom only. To see the full payload, refer to the [Onboard Corporate Customer API Reference](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). All fields have a maximum limit of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `region` | The regulatory region where the corporate customer is being onboarded. Use `UK` to onboard a customer based in the United Kingdom. | Yes | | [businessDetails](#businessDetails) | Details about the business, including information about the applicant and stakeholders. | Yes | | [riskAssessmentInfo](#riskAssessmentInfo) | Business profile details, such as total employees and annual turnover. | Yes | | [deviceDetails](#deviceDetails) | Information about the device and IP address used to submit the onboarding request. | Yes | | [expectedAccountUsage](#expectedAccountUsage) | Details about how the customer intends to use the account. | Yes | | [natureOfBusiness](#natureOfBusiness) | Information about the company’s industry and type of business activity. | Yes | | [tags](#tags) | Optional metadata tags you can use to identify customer accounts. | No | | `customerHashId` | The unique customer identifier generated when creating the customer record. Returned in the response to the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request. *Required to reinitiate the KYB process.* | | Only customers registered in GB, CH, MC are eligible to be onboarded under UK region. Please contact your account manager, in case you need to onboard customers registered outside of these countries. See [Regulatory region](/docs/onboarding/corporate-customers#regulatory-region) for details. ## Table entity API fields ## Table entity API fields The below object table columns apply to the following entity types: - `ASSOCIATION` - `GOVERNMENT_ENTITY` - `LIMITED_LIABILITY_PARTNERSHIP` - `PRIVATE_COMPANY` - `PUBLIC_COMPANY` - `SOLE_TRADER` - `TRUST` - `UNINCORP_PARTNERSHIP` - `OTHERS` ## `businessDetails` object An object that contains business details about the corporate customer. | Property | Description | Required | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `referenceId` | The universally unique identifier (UUID) that Nium uses to identify the `businessDetails` entity. If not provided, Nium generates one. Used when responding to an RFI or uploading documents for the business entity. | No | | `businessName` | The registered legal name of the business. | Yes | | `businessRegistrationNumber` | The official registration number issued to the business. | Yes | | `tradeName` | The name the business operates under. If unavailable, set `tradeName` to the same value as `businessName`. | Yes | | `website` | The business’s website. If unavailable, provide a social media profile (for example, Instagram or Facebook). If neither is available, upload a document with `documentType` **PROOF\_OF\_BUSINESS**. | No | | `businessType` | The legal entity type of the business, such as Private or Public Company. Use the [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category`: `businessType`. | Yes | | [legalDetails](#businessDetails-legalDetails) | Legal and registration details for the business. | Yes | | [addresses](#businessdetails-addresses) | The registered and operating business addresses. | Yes | | [documentDetails](#businessdetails-documentdetails) | An array of business documents. *Required for [UK required documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents).* | Yes\* | | [stakeholders](#businessdetails-stakeholders) | Details about the business’s stakeholders, such as directors or ultimate beneficial owners (UBOs). | Yes | | [applicantDetails](#businessdetails-applicantdetails) | Information about the applicant associated with the business. | Yes | | [additionalInfo](#businessDetails-additionalInfo) | Optional supplementary information related to the application. | No | ### `legalDetails` object An object within the `businessDetails` object that contains legal details. | Property | Description | Required | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `registeredDate` | The date the business was registered entered in the `YYYY-MM-DD` format. Registered date cannot be future date. | Yes | | `registeredCountry` | The country where the business is registered. Use [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request with `category` set to **countryName**. | Yes | ### `addresses` object An object within the `businessDetails` object that contains registered and business addresses. | Property | Description | Required | | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | [registeredAddress](#businessdetails-address-registeredaddress) | The address where the business is registered. | Yes | | [businessAddress](#businessdetails-address-businessaddress) | The address where the business is mainly conducted, if different than the registered address. *Not required if `isSameBusinessAddress` is **Yes** and passed under `businessDetails.additionalInfo`.* | Yes | #### `registeredAddress` object An object within the `businessDetails.address` object that contains the address details where the corporate customer is registered. | Property | Description | Required | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the registered address. | Yes | | `addressLine2` | The second address line of the registered address. | No | | `city` | The city or suburb of the registered address. | No | | `state` | The state or province of the registered address. | No | | `country` | The country where the corporate customer is registered. Use [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category`=`countryName`. | Yes | | `postcode` | The postal code where the corporate customer is registered. | Yes | #### `businessAddress` object An object within the `businessDetails.address` object that contains the address details about the principal place of business only when the registered address is different. Optional if `isSameBusinessAddress` is **Yes** under `businessDetails.additionalInfo`. | Property | Description | Required | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the business address. | Yes | | `addressLine2` | The second address line of the business address. | No | | `city` | The city or suburb of the business address. | No | | `state` | The state or province of the business address. | No | | `country` | The country of the business address. Use the [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request with `category`=`countryName`. | Yes | | `postcode` | The postal code of the business address. | Yes | ### `documentDetails` array An array of objects within the `businessDetails` object that contains one or more business documents. \* This object is required if either of the following are true: - Manual KYB is used. - `searchId` is nor passed. - eKYB is used and `businessDetails.businessType` is one of the following: - `LIMITED_LIABILITY_PARTNERSHIP` - `TRUST` - `UNINCORP_PARTNERSHIP` For a complete list of required documents, see [UK Required Documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents). | Property | Description | Required | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of business document. Use [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) for a valid set of values. | Yes | | [document](#businessdetails-documentdetails-document) | An array of object that contains a copy of the document. | Yes | #### `document` object An array of objects within the `businessDetails.documentDetails` object. | Property | Description | Required | | ---------- | --------------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes | | `document` | The file as a base64 encoded string. | Yes | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Required | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `isSameBusinessAddress` | Indicates whether the principal place of business is the same as the registered business address. Accepts `Yes` or `No`. If set to **Yes**, the business address can be skipped. | No | | `searchId` | Used for eKYB. Returned in the response from the [Exhaustive Corporate Details using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) request. The required business documents depend on this value. | No | ### `stakeholders` object An array of objects within the `businessDetails` object that contains information about one or many stakeholders including Directors and UBOs. For every stakeholder object, you need to send either the `stakeholderDetails` or the `businessPartner` parameters. | Property | Description | Required | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `referenceId` | The universal unique identifier (UUID) associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | No | | [stakeholderDetails](#businessdetails-stakeholders-stakeholderdetails) | An object that contains the details of the individual stakeholder. | Yes | | [businessPartner](#businessdetails-stakeholders-businesspartner) | An object that contains the details of the corporate stakeholder. Required if a corporate stakeholder exists. | Yes | #### `stakeholderDetails` object Each item in the `stakeholders` object represents an individual stakeholder (natural person). Include all **Signatories**, **Directors**, **Ultimate Beneficial Owners (UBOs)**, **Trustees**, **Settlors**, and **Partners** listed in the **Business Registration Document**, **Register of Directors**, or **Register of Shareholders** for all business types. To add positions: - **Directors**: Include all active management directors as stakeholders. Board members who do not participate in daily operations are not required. - **Ultimate Beneficial Owners (UBOs)**: Add all individuals who own **more than 25%** of the business (directly or indirectly). - For sole traders, the business owner is considered the UBO. - For high-risk businesses, Nium may request via RFI that all individuals owning **more than 10%** of shares be declared as UBOs. - **Control Person**:\ If no individual owns 25% or more of the business, identify and submit a Control Person along with the Control Person Declaration.\ See [UK Required Documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents) for details. - **Signatory or Representative**:\ Add individuals authorized to conduct transactions or manage user access. - The applicant is considered a Representative by default and must be included. - You can add other users as Representatives in the application or later by emailing . Each Representative must complete KYC as instructed. - **Other Roles**:\ Include other applicable roles—such as **Partner**, **Trustee**, or **Settlor**—according to position mapping requirements. | Property | Description | Required | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `kycMode` | The KYC mode for verifying the individual stakeholder. Valid values are `E_KYC` , `E_DOC_VERIFY`, `MANUAL_KYC`. The `kycMode` is required only when the position of the individual stakeholder is `UBO`, `TRUSTEE`, `PARTNER`, or `MEMBER` or `REPRESENTATIVE` or `SIGNATORY` and can be ignored for other positions. For details, see **[Stakeholder KYC](/docs/onboarding/corporate-customers/uk-onboarding#stakeholder-kyc)** | Yes | | `firstName` | The first name of the individual stakeholder. | Yes | | `middleName` | The middle name of the individual stakeholder. | No | | `lastName` | The last name of the individual stakeholder. | Yes | | `nationality` | The nationality of the individual stakeholder. Use [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category`=`countryName`. | Yes | | `dateOfBirth` | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. | Yes | | [professionalDetails](#businessdetails-stakeholders-stakeholderdetails-professionaldetails) | An array of objects to accept the positions held by the stakeholder in the business of the corporate customer and details related to the positions held. | Yes | | [address](#businessdetails-stakeholders-stakeholderdetails-address) | An object that contains the residential address of the individual stakeholder. | Yes | | [contactDetails](#businessdetails-stakeholders-stakeholderdetails-contactdetails) | An object that contains the contact details of the individual stakeholder. | No | | [documentDetails](#businessdetails-stakeholders-stakeholderdetails-documentdetails) | An object that contains the document details of the individual stakeholder. **Note:** This is required if `kycMode = MANUAL_KYC`. | Yes \* | | [additionalInfo](#businessdetails-stakeholders-stakeholderdetails-additionalInfo) | An object that contains additional information required about the individual stakeholder such as `isPEP`. | Yes | ##### `professionalDetails` object An array of objects within `businessDetails.stakeholders.stakeholderDetails` that defines each stakeholder’s professional details. A stakeholder can hold multiple positions (for example, **Director** and **UBO**). Select all applicable positions for each individual. | Property | Description | Required | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `position` | The position of the individual stakeholder such as UBO, DIRECTOR, REPRESENATTIVE, SIGANTORY . Use the [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request with `category`set to **position** for a valid set of values. | Yes | | `sharePercentage` | The share percentage of the individual stakeholder in the company. *Required if stakeholder’s position contains `UBO` or `SHAREHOLDER`. Else ignore.* Sharepercentage should be a number between 0 and 100. Eg. 23.4 | Yes | ##### `stakeholderDetails.address` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the individual stakeholder. | Yes | | `addressLine2` | The second address line of the individual stakeholder. | No | | `city` | The city or suburb of the individual stakeholder. | No | | `state` | The state or province of the individual stakeholder. | No | | `country` | The country where the individual stakeholder resides. Use [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category`=`countryName`. | Yes | | `postcode` | The postal code of the individual stakeholder. | Yes | ##### `contactDetails` object An optional object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the stakeholder's contact information. | Property | Description | Required | | ----------- | ------------------------------------------------------- | :------: | | `email` | The individual stakeholder's email address. | No | | `contactNo` | The contact phone number of the individual stakeholder. | No | ##### `stakeholderDetails.documentDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's document details. Required for **MANUAL\_KYC**. See [UK required documents for stakeholders](/docs/onboarding/corporate-customers/uk-onboarding/required-documents#stakeholders) for more information. | Property | Description | Required | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of document. Use the [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request with `category`set to **documentType**. | Yes \* | | `documentNumber` | The ID number for the given document type. | Yes \* | | `documentIssuanceCountry` | The country that issued the business document. This field is required if `documentType` = `PASSPORT` or `DRIVER_LICENSE` or `NATIONAL_ID`. Use [Fetch corporate constants API](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) with `category`=`countryName` | Yes \* | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. This is required if `documentType` is `PASSPORT` or `DRIVER_LICENSE`.Expiry date cannot be a past date. | Yes \* | | [document](#businessdetails-stakeholders.stakeholderDetails-documentDetails-document) | An object that contains the document copy. | Yes \* | ##### `documentDetails.document` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails.documentDetails` object that contains a copy of the individual stakeholder's document. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes | | `document` | The document saved as a base64 encoded string. | Yes | #### `stakeholderDetails.additionalInfo` object An object under `businessDetails.stakeholders.stakeholderDetails` that provides additional information about an individual stakeholder, such as if they are a politically exposed person (PEP). | Property | Description | Required | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `isPep` | Indicates if the stakeholder is a politically exposed person. Accepts `Yes` or `No`. If set to **Yes**, include a `SOURCE_OF_WEALTH` document; otherwise, it may be requested later via a RFI. | Yes | A **Politically Exposed Person (PEP)** is someone who currently holds or has recently held a prominent public position and may therefore present a higher risk of involvement in bribery, corruption, or money laundering. #### `businessPartner` An object within the `businessDetails.stakeholders` object that contains the business details about the corporate stakeholder. - If the customer is a multi-layered company where another corporate entity owns more than 25% of shares (directly or indirectly), declare all such corporate stakeholders in the application. - See [Multi-layered Ownership Structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-uk#heading-7) for guidance on identifying multi-layered companies. - Submit the corporate or ownership structure document to verify ownership under `businessDetails.documentType` set to **CORPORATE\_STRUCTURE**. For more information, see [UK Required Documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents). | Property | Description | Required | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `businessName` | The registered business name of the corporate stakeholder. | Yes | | `businessRegistrationNumber` | The official registration number of the corporate stakeholder. | Yes | | `businessEntityType` | The primary role of the corporate stakeholder within the company. Use the [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request with `category` set to **position** for valid values. Corporate stakeholders can typically hold positions such as **UBO**, **Shareholder**, **Partner**, or **Trustee**. In some cases, a corporate stakeholder may also act as a **Director**. | Yes | | `sharePercentage` | The ownership percentage of the corporate stakeholder in the company. **Note:** Required if the stakeholder’s position is **UBO** or **Shareholder**. Otherwise, omit. The value must be a number between 0 and 100 (for example, `23.4`). | Yes | | [legalDetails](#businessdetails-stakeholders-businesspartner-legaldetails) | The registration and legal details of the corporate stakeholder. | Yes | ##### `businessPartner.legalDetails` object An object within the `businessDetails.stakeholders.businessPartner` object that contains the corporate stakeholder's legal details. | Property | Description | Required | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `registeredCountry` | The country where the corporate stakeholder is registered. Use the [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request `category` set to **countryName**. | Yes | ### `applicantDetails` object An object within the `businessDetails` object that contains details about the applicant. | Property | Description | Required | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `referenceId` | The universally unique identifier (UUID) associated with the applicant and applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents. | No | | `kycMode` | The KYC mode for verifying the identity of the applicant. The only valid value is `E_DOC_VERIFY`. | Yes | | `firstName` | The first name of the applicant. The maximum length is 40 characters or spaces. | Yes | | `middleName` | The middle name of the applicant. The maximum length is 40 characters or spaces. | No | | `lastName` | The last name or the applicant. The maximum length is 40 characters or spaces. | Yes | | `nationality` | Nationality of the applicant. Use the [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants) request with `category` set to **countryName** for valid values. | Yes | | `dateOfBirth` | The date on which the applicant was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. Applicant age should be less than 18 yrs. | Yes | | [professionalDetails](#businessdetails-applicantdetails-professionaldetails) | An array of object that contains the professional details of the applicant. | Yes | | [address](#businessdetails-applicantdetails-address) | The residential address of the applicant. | Yes | | [contactDetails](#businessdetails-applicantdetails-contactdetails) | The contact details of the applicant. | Yes | | [documentDetails](#businessdetails-applicantdetails-documentdetails) | The document details of the applicant. Required only for **POWER\_OF\_ATTORNEY** or **SOURCE\_OF\_WEALTH**. | Yes \* | | [additionalInfo](#applicantdetails-object) | Additional applicant information, such as `isPEP`. | Yes | #### `professionalDetails` object Describes the roles held by the applicant in the corporate customer’s business. | Property | Description | Required | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `position` | The position of the applicant. Use the [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants) request with `category` set to **countryName** for valid values. An applicant is a **REPRESENTATIVE** by default. Additionally, all applicable positions like **UBO** or **DIRECTOR** should be added. | Yes | | `sharePercentage` | The share percentage of the applicant in the company. If the applicant's position is **UBO** or **SHAREHOLDER**, then the share percentage is a required input parameter. Else ignore. `sharePercentage` should be a number between 0 and 100. Eg. 23.4 | Yes | #### `applicantDetails.address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | Property | Description | Required | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the applicant. The maximum character length is 40. | Yes | | `addressLine2` | The second address line of the applicant. The maximum character length is 40. | No | | `city` | The city or suburb of the applicant. The maximum character length is 20. | Yes | | `state` | The state or province of the applicant. The maximum character length is 30. | No | | `country` | The country of the applicant address. Use the [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants) request with `category` set to **countryName** for valid values. | Yes | | `postcode` | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. For UK postcodes, use the `SW4 6EH` format. | Yes | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object that contains the applicant's contact information. | Property | Description | Required | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `email` | The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See [Email regex](/docs/developers/nium-api#regular-expression-for-email). | Yes | | `countryCode`. | The country code of the applicant's phone number. | Yes | | `contactNo` | The applicant's phone number. The maximum length is 20 numeric characters. | Yes | #### `businessDetails.applicantDetails.documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. - If positions does not include DIRECTOR / UBO / PARTNER / TRUSTEE/ MEMBER then **POWER\_OF\_ATTORNEY** is required. - If `isPEP` is **Yes** then **SOURCE\_OF\_WEALTH** is required. | Property | Description | Required | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of document. Use the [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) request for a valid set of values. | Yes \* | | [document](#businessdetails-applicantdetails-documentdetails-document) | An array of objects that contains a copy of the document. Required for **POWER\_OF\_ATTORNEY** or **SOURCE\_OF\_WEALTH**. See [UK Required Documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents) for required fields. | Yes | ##### `documentDetails.document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains the document copy. - Required for **POWER\_OF\_ATTORNEY** or **SOURCE\_OF\_WEALTH**. See [UK Required Documents](/docs/onboarding/corporate-customers/uk-onboarding/required-documents) for the valid set of required fields. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes | | `document` | The document saved as a base64 encoded string. | Yes | #### `applicantDetails.additionalInfo` object An object within `businessDetails.applicantDetails` that provides additional information about the applicant, such as whether they are a politically exposed person (PEP). | Property | Description | Required | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `isPep` | Indicates whether the applicant is a politically exposed person. Accepts `Yes` or `No`. If set to **Yes**, include a `SOURCE_OF_WEALTH` document; otherwise, it may be requested later via RFI. | Yes | A **Politically Exposed Person (PEP)** is someone who currently holds or has recently held a prominent public position and may therefore present a higher risk of involvement in bribery, corruption, or money laundering. ## `expectedAccountUsage` object Contains information about how the corporate customer expects to use their account. | Property | Description | Required | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | [debit](#expectedAccountUsageDebit) | Expected usage for all outward (debit) transactions. | Yes | | [credit](#expectedAccountUsageCredit) | Expected usage for all inward (credit) transactions. | Yes | | `intendedUses` | Array of intended account uses. Include all applicable values. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` = `intendedUses` for valid options. | Yes | | `intendedUsesDescription` | Description of the intended account use if `other` is selected in `intendedUses`. Minimum 20 characters. | Yes\* | ### `debit` object Describes the expected usage for all outward (debit) transactions. | Property | Description | Required | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `monthlyTransactionVolume` | Estimated total monthly payout volume, converted to `GBP`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **monthlyTransactionVolume** for valid options. | Yes | | `monthlyTransactions` | Estimated number of monthly payout transactions. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **monthlyTransactions** for valid options. | Yes | | `averageTransactionValue` | Estimated average payout transaction value, converted to `GBP`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **averageTransactionValue** for valid options. | Yes | | `topTransactionCountries` | Array of top payout destination countries. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **countryName** for valid options. | Yes | ### `credit` object Describes the expected usage for all inward (credit) transactions. - If the customer is not enabled for pay-ins, provide the lowest valid bracket for `monthlyTransactionVolume`, `monthlyTransactions`, and `averageTransactionValue`. - This object is not applicable to Payroll clients or clients who have disabled third-party funding. | Property | Description | Required | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `monthlyTransactionVolume` | Estimated total monthly pay-in volume, converted to `GBP`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **monthlyTransactionVolume** for valid options. | Yes | | `monthlyTransactions` | Estimated number of monthly pay-in transactions. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **monthlyTransactions** for valid options. | Yes | | `averageTransactionValue` | Estimated average pay-in transaction value, converted to `EUR`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **averageTransactionValue** for valid options. | Yes | | `topTransactionCountries` | Array of top pay-in source countries. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **countryName** for valid options. | Yes | ## `natureOfBusiness` object Contains information about the business’s nature and industry. - If the `industrySector` includes any restricted or prohibited industries, Nium may request additional documentation, which can affect approval timelines.\ See [Prohibited and Restricted Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories) for more details. | Property | Description | Required | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `industryCodes` | Array of industry sector codes applicable to the business. Include all relevant values. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **industrySector** for valid options. | Yes | | `industryDescription` | Brief description (2–3 sentences) of the business. Maximum 300 characters; minimum 20 characters. | No | ## `riskAssessmentInfo` object Contains information about the business’s operational and financial profile. | Property | Description | Required | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `totalEmployees` | Total number of employees. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **totalEmployees** for valid options. | Yes | | `annualTurnover` | Annual turnover. If the business is less than one year old, provide the expected turnover; otherwise, use the previous year’s turnover. “Turnover” refers to total annual revenue. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **annualTurnover** for valid options. | Yes | | `countryOfOperation` | Array of countries where the business operates or maintains a presence. Include all countries where the company has offices, factories, or operations. Example: `["IN", "FR", "LT"]`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for valid country codes. | Yes | | `travelRestrictedCountry` | Indicates whether the customer (for example, an Online Travel Agency) facilitates travel to any travel-restricted countries. Accepts `Yes` or `No`. Applicable when JPMC Virtual Account is enabled. | Yes\* | | `restrictedCountries` | Array of restricted countries to which the OTA facilitates travel. Required if `travelRestrictedCountry` = `Yes`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for valid country codes. | Yes\* | | `ofacLicencePresent` | Indicates whether the OTA holds an OFAC license. Accepts `Yes` or `No`. Required if `travelRestrictedCountry` = `Yes`. | Yes\* | ## `deviceDetails` object Contains information about the customer’s device and IP address used during onboarding. | Property | Description | Required | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `countryIP` | Country associated with the device’s IP address (for example, `US`). Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` set to **countryName** for valid country codes. | Yes | | `deviceInfo` | Device information (for example, `macOS`). | Yes | | `ipAddress` | Device IP address (for example, `45.48.241.198`). | Yes | | `sessionId` | Unique session identifier generated by the client application. | Yes | ## `tags` object An optional object containing up to 15 user-defined key-value pairs provided by the client. | Property | Description | Required | | -------- | ----------------------------------------------------------------- | :------: | | `key` | Name of the tag. Maximum 128 characters. Each key must be unique. | No | | `value` | Value of the tag. Maximum 256 characters. | No | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/corporate-customers/uk-onboarding/required-documents This page outlines the documents required for stakeholders, applicants, and various business types to onboard a corporate customer registered in the United Kingdom. ## Business details The following table lists the required document types for both verification types for all business entity types. | `businessType` | Manual KYB | eKYB | | :------------------------------ | :-------------------------- | :----------------- | | `ASSOCIATION` | `ASSOCIATION_DEED` | - | | `GOVERNMENT_ENTITY` | `BUSINESS_REGISTRATION_DOC` | - | | `LIMITED_LIABILITY_PARTNERSHIP` | `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | | `PRIVATE_COMPANY` | `BUSINESS_REGISTRATION_DOC` | - | | `PUBLIC_COMPANY` | `BUSINESS_REGISTRATION_DOC` | - | | `SOLE_TRADER` | `BUSINESS_REGISTRATION_DOC` | - | | `TRUST` | `TRUST_DEED` | `TRUST_DEED` | | `UNINCORP_PARTNERSHIP` | `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | ### Additional Business Documents - **PROOF\_OF\_BUSINESS**: Required if the business does not have a website. Submit any document that helps validate the customer’s business operations. Acceptable documents include: - Product catalogues, company brochures, marketing materials, or a detailed business plan. *Preferred* - Contracts, business agreements, or vendor agreements. - Photos of the physical store (for brick-and-mortar businesses). - Invoices clearly describing business activities, issued within the past year. *Not preferred* - **Corporate Structure (Ownership Structure)**: Required if the customer is a multi-layered company. See [Multi-layered Ownership Structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6) for details on identifying multi-layered entities. The corporate structure document can be prepared by the customer and must list all shareholders with their respective ownership percentages to help identify the ultimate beneficial owner (UBO). - You can use your own format or a similar template. - Use `documentType` **CORPORATE\_STRUCTURE** when submitting an ownership structure. Ownership Chart Ownership Chart For a complete list of business document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. ## Stakeholders Stakeholder with positions including **SIGNATORY**, **REPRESENTATIVE**, **UBO**, **TRUSTEE**, **PARTNER**,**MEMBER** require KYC have the following choices: - UK residents need to use the KYC mode **E\_KYC**. - For non-residents pass `kycMode` as **E\_DOC\_VERIFY** or **MANUAL\_KYC** based on the stakeholder's preference. ### `E_KYC` No documents are required for E\_KYC. ### `E_DOC_VERIFY` | Documents to be uploaded in Onfido form | Documents to be supported via Nium's API | | :----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Live Selfie with Passport/National ID/Driver's License and Proof of Address to be submitted in the form presented by Onfido (eDoc verification vendor) | **SOURCE\_OF\_WEALTH** in case stakeholder is a politically exposed person (PEP). | ### `MANUAL_KYC` Every individual stakeholder needs to submit proof of address and proof of identity when `kycMode` = `MANUAL_KYC`. The following information needs to be submitted for proof of identity. - Even if the document used for proof of identity contains an address , you need to submit an additional proof of address. [Acceptable document for `PROOF_OF_ADDRESS`](#acceptable-documents-proof-of-address) which can verify the address with `documentType` **PROOF\_OF\_ADDRESS**. - If this additional document is not submitted, Nium, will raise an RFI for `stakeholderAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) request. | Field name | Passport | National ID | Driver license | Proof of Address | | :------------------------ | :-------------------- | :------------ | :--------------- | :----------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `DRIVER_LICENSE` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes | Yes | No | | `documentIssuanceCountry` | Yes | Yes | Yes | No | | `documentExpiryDate` | Yes | No | Yes | No | | `document.fileName` | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | Yes | **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport, National ID, or Driver's License. ### Additional Stakeholder Documents Additional stakeholder documents may be requested as part of the onboarding process. #### Source of wealth If any shareholder is a Politically Exposed Person (`isPEP` = **Yes**), a **SOURCE\_OF\_WEALTH** document must be submitted for that individual. A Source of Wealth document helps verify the origin and means of a person’s accumulated wealth used to establish and operate a business.\ Provide a written explanation supported by documentation that confirms the legitimacy of the customer’s funds. Acceptable documents include: - Personal or joint savings (bank statements) - Employment income (salaries, bonuses, pensions) - Loan or contract agreements - Sale of assets (for example, real estate or shares) - Inheritances or family wealth transfers - Compensation from legal settlements - Profits from legitimate business or investments - Ownership of businesses or investment returns - Other documents evidencing the customer’s funds or wealth #### Control person declaration Submit a **CONTROL\_PERSON\_DECLARATION** if no individual owns 25% or more of the business (directly or indirectly). To submit a **CONTROL\_PERSON\_DECLARATION**, Identify the control person and provide a signed declaration. See the [Control Person Declaration Template](https://www.nium.com/corporate-onboarding/verifying-your-business-in-uk#heading-9) for reference. #### Proof of address A **PROOF\_OF\_ADDRESS** document may also be submitted.\ Acceptable documents differ for individual stakeholders/applicants and businesses. | Individual Stakeholder or Applicant | Business Details | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Utility bills (gas, electric, internet, phone)Financial records (bank or mortgage statement)Insurance statements (life, health, auto, home, boat)Medical records (doctor, hospital, or clinic)Pay slipsGovernment-issued lettersDriver’s license (if not used as proof of identity) | Utility bills (gas, electric, internet, phone)Financial records (bank or mortgage statement)Government-issued letters | All Proof of Address documents must be issued within the last 90 days at the time of submission. ## Applicant The following table lists the required documents submitted either electronically or manually. | API Documents\*\* | Onfido Documents | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | | Power of Attorney if the applicant is not a **DIRECTOR**, **UBO**, **PARTNER**, **TRUSTEE**, or **MEMBER**. Also include **SOURCE\_OF\_WEALTH** if the applicant is a PEP. | Live selfie with passport, national ID, or driver’s license, submitted through Onfido (e-document verification vendor). | The following table lists the fields required for each document type to complete the **E\_DOC\_VERIFY** process. | Field Name\*\* | **Power of Attorney (if applicant is not a DIRECTOR, UBO, PARTNER, TRUSTEE, or MEMBER)** | **Source of Wealth** | | :------------------ | :--------------------------------------------------------------------------------------- | :--------------------: | | `documentType` | **POWER\_OF\_ATTORNEY** | **SOURCE\_OF\_WEALTH** | | `document.document` | Yes | Yes | ### Additional applicant documents - **Power of Attorney**: Required if the applicant is not a **DIRECTOR**, **UBO**, **PARTNER**, or **TRUSTEE**. - See [Letter of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization) for Power of Attorney requirements. - Alternatively, the applicant can nominate a director to complete **Live Authorization** and avoid physical documentation or apostille requirements. See [Live Authorization](/docs/onboarding/corporate-customers/letter-of-authorization#live-authorization) for more information. - **Source of Wealth**: See [Additional Stakeholder Documents - Source of Wealth](#additional-stakeholder-documents) for more information. For a complete list of personal document types, use the [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category) request with `fieldName` set to **documentType**. --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/uk-onboarding/position-mapping | BusinessType | DIRECTOR | MEMBERS | PARTNER | REPRESENTATIVE | SETTLOR | SHAREHOLDER | SIGNATORY | TRUSTEE | UBO | CONTROL_PERSON | | `BusinessType` | `DIRECTOR` | `MEMBERS` | `PARTNER` | `REPRESENTATIVE` | `SETTLOR` | `SHAREHOLDER` | `SIGNATORY` | `TRUSTEE` | `UBO` | `CONTROL_PERSON` | | ------------------------------- | :--------: | :-------: | :-------: | :--------------: | :-------: | :-----------: | :---------: | :-------: | :---: | :--------------: | | `ASSOCIATION` | | Yes | | Yes | | | Yes | | | Yes | | `GOVERNMENT_ENTITY` | | | | Yes | | | Yes | | | Yes | | `LIMITED_LIABILITY_PARTNERSHIP` | | | Yes | Yes | | | Yes | | | Yes | | `PRIVATE_COMPANY` | Yes | | | Yes | | Yes | Yes | | Yes | Yes | | `PUBLIC_COMPANY` | Yes | | | Yes | | Yes | Yes | | Yes | Yes | | `SOLE_TRADER` | | | | Yes | | | Yes | | | Yes | | `TRUST` | | | | Yes | Yes | | Yes | Yes | | Yes | | `UNINCORP_PARTNERSHIP` | | | Yes | Yes | | | Yes | | | Yes | A **Yes** means that position can be passed for that `businessType`. A blank table cell means that position is not applicable for that `businessType`. Multiple positions in the `professionalDetails` array object as shown below: ```json "professionalDetails": [ { "position": "REPRESENTATIVE" }, { "position": "UBO", "sharePercentage": "50%" }, { "position": "SIGNATORY" } ``` --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/uk-onboarding/example-requests To onboard your entity, you can call the Onboard Corporate Customer API. For an example call that you can customize with your information, see: To onboard your entity, you can call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. For an example call that you can customize with your information, see: - [Private companies](#private) - [Simulate scenarios in the eKYB flow](#simulate-scenarios-ekyb-flow) ## Private companies The following is an API request example call where `businessType = PRIVATE_COMPANY`. ```json { "region": "UK", "businessDetails": { "businessName": "Bradsonsas electronics 92", "businessRegistrationNumber": "995M010990117", "businessType": "PRIVATE_COMPANY", "tradeName":"Bradsons Elesdctrics", "website":"www.brandsonelectronics98.co.uk", "addresses": { "registeredAddress": { "addressLine1": "1 ANGEL COURT, 23RD AVENUE", "city": "LONDON", "country": "GB", "postcode": "EC2R 7AG" } }, "legalDetails": { "registeredCountry": "GB", "registeredDate": "1999-01-02" }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "document": "", "fileName": "BRD.pdf", "fileType": "application/pdf" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Piyush", "middleName": "J", "lastName": "Chan", "dateOfBirth": "1980-01-17", "nationality": "GB", "professionalDetails": [ { "position": "UBO", "sharePercentage": "5" } ], "address": { "addressLine1": "High Street 303, 24th Street", "addressLine2": "Bradford Avenue", "city": "London", "country": "GB", "postcode": "28046" }, "contactDetails": { "contactNo": "691668879", "countryCode": "GB", "email": "peter@azmotor.com" }, "additionalInfo": { "isPep": "Yes"}, "documentDetails": [ { "documentExpiryDate": "2029-09-10", "documentIssuanceCountry": "GB", "documentNumber": "123456009", "documentType": "PASSPORT", "document": [ { "document": "", "fileName": "passport.pdf", "fileType": "application/pdf" } ] } ] } } , { "stakeholderDetails": { "firstName": "Piyush", "lastName": "PITT", "middleName": "C", "nationality": "GB", "dateOfBirth": "1985-03-15", "professionalDetails": [ { "position": "DIRECTOR" } ], "address": { "addressLine1": "High Street 202", "addressLine2": "56th Avenue", "city": "London", "country": "GB", "postcode": "L1 8JQ" }, "contactDetails": { "contactNo": "500668880", "countryCode": "GB", "email": "brad@azmotor.com" }, "additionalInfo": { "isPep": "Yes"} } }, { "referenceId": "006ebeeb-3ede-4f49-8381-1e382334131c", "businessPartner": { "legalDetails": { "registeredCountry": "FR" }, "businessEntityType": "SHAREHOLDER", "businessName": "JumaTECH LIMITED", "businessRegistrationNumber": "JM22843822" } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "BRAD", "lastName": "LEONG", "middleName": "C", "nationality": "GB", "dateOfBirth": "1985-03-15", "professionalDetails": [ { "position": "DIRECTOR" } ], "address": { "addressLine1": "High Street 202", "addressLine2": "56th Avenue", "city": "London", "country": "GB", "postcode": "L1 8JQ" }, "contactDetails": { "contactNo": "910668880", "countryCode": "GB", "email": "brad@belec.com" }, "additionalInfo": { "isPep": "No"} }, "additionalInfo": { "isSameBusinessAddress": "Yes", "searchId":"c654b49e-6cee-11ee-b962-0242ac120002" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN", "US" ], "transactionCountries": [ "GB", "AU", "FR" ], "totalEmployees": "EM009", "annualTurnover": "GB011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Test eKYB flow If you are using the eKYB flow for the UK region, you can test the following scenarios by following these steps with the example `businessRegistrationNumber` (BRN) in the following table. ### Response conditions for the Exhaustive Corporate Details request You can generate responses for different `businessType` entities by following the table below. This can be used for testing the pre-population flow after calling the [Exhaustive Corporate Details Using Business ID](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/corporate/lookup) request. | `businessType` | `businessRegistrationNumber` condition | | :------------------------------ | :------------------------------------- | | `PRIVATE_LIMITED_COMPANY` | Contains `B01` or `B02` or `B03` | | `PUBLIC_COMPANY` | Contains `B11` or `B12` or `B13` | | `SOLE_TRADER` | Contains `B21` or `B22` or `B23` | | `GOVERNMENT_BODY` | Contains `B31` or `B32` or `B33` | | `TRUST` | Contains `B41` or `B42` or `B43` | | `LIMITED_LIABILITY_PARTNERSHIP` | Contains `B51` or `B52` or `B53` | | `ASSOCIATION` | Contains `B61` or `B62` or `B63` | ### Request example: auto-approval In this scenario, all documents and information required for completing the verification process are provided in the Onboard Corporate Customer API. The application is approved in real-time (within a few minutes) and then you receive a webhook with `status='COMPLETED'`. This is applicable only for the eKYB flow. ```json { "region": "UK", "businessDetails": { "businessName": "Bradsonsas electronics 91", "businessRegistrationNumber": "995M010990116", "businessType": "PRIVATE_COMPANY", "tradeName":"Bradsons Elesdctrics", "website":"www.brandsonelectronics98.co.uk", "addresses": { "registeredAddress": { "addressLine1": "1 ANGEL COURT, 23RD AVENUE", "city": "LONDON", "country": "GB", "postcode": "EC2R 7AG" } }, "legalDetails": { "registeredCountry": "GB", "registeredDate": "1999-01-02" }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "document": "", "fileName": "BRD.pdf", "fileType": "application/pdf" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "Piyush", "middleName": "J", "lastName": "Chan", "dateOfBirth": "1980-01-17", "nationality": "GB", "professionalDetails": [ { "position": "UBO", "sharePercentage": "5" } ], "address": { "addressLine1": "High Street 303, 24th Street", "addressLine2": "Bradford Avenue", "city": "London", "country": "GB", "postcode": "28046" }, "contactDetails": { "contactNo": "691668879", "countryCode": "GB", "email": "peter@azmotor.com" }, "additionalInfo": { "isPep": "Yes"}, "documentDetails": [ { "documentExpiryDate": "2029-09-10", "documentIssuanceCountry": "GB", "documentNumber": "123456009", "documentType": "PASSPORT", "document": [ { "document": "", "fileName": "passport.pdf", "fileType": "application/pdf" } ] } ] } } , { "stakeholderDetails": { "firstName": "Piyush", "lastName": "PITT", "middleName": "C", "nationality": "GB", "dateOfBirth": "1985-03-15", "professionalDetails": [ { "position": "DIRECTOR" } ], "address": { "addressLine1": "High Street 202", "addressLine2": "56th Avenue", "city": "London", "country": "GB", "postcode": "L1 8JQ" }, "contactDetails": { "contactNo": "500668880", "countryCode": "GB", "email": "brad@azmotor.com" } } }, { "referenceId": "006ebeeb-3ede-4f49-8381-1e382334131c", "businessPartner": { "legalDetails": { "registeredCountry": "FR" }, "businessEntityType": "SHAREHOLDER", "businessName": "JumaTECH LIMITED", "businessRegistrationNumber": "JM22843822" } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "BRAD", "lastName": "LEONG", "middleName": "C", "nationality": "GB", "dateOfBirth": "1985-03-15", "professionalDetails": [ { "position": "DIRECTOR" } ], "address": { "addressLine1": "High Street 202", "addressLine2": "56th Avenue", "city": "London", "country": "GB", "postcode": "L1 8JQ" }, "contactDetails": { "contactNo": "910668880", "countryCode": "GB", "email": "brad@belec.com" } }, "additionalInfo": { "isSameBusinessAddress": "Yes", "searchId":"c654b49e-6cee-11ee-b962-0242ac120002" } }, "riskAssessmentInfo": { "countryOfOperation": [ "HK", "IN", "US" ], "transactionCountries": [ "GB", "AU", "FR" ], "totalEmployees": "EM009", "annualTurnover": "GB011", "industrySector": "IS144", "intendedUseOfAccount": "IU003" }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ### Request example: action required In this scenario, all the documents and information required are provided in the Onboard Corporate Customer API, but the application was not auto-approved and needs to be manually reviewed by Nium's compliance team. You receive a webhook with `status='ACTION_REQUIRED'` . Once received, wait for the next webhook which will be sent once the compliance agent completes the manual review. ```json { "region": "UK", "businessDetails": { "businessName": "HEATHER COMPANY waoek 45", "businessRegistrationNumber": "GBB02834745", "tradename":"Heather Trades", "website": null, "tradeName": "HEATHER COMPANY", "businessType": "PRIVATE_COMPANY", "legalDetails": { "registeredCountry": "GB", "registeredDate": "2016-01-17" }, "addresses": { "registeredAddress": { "addressLine1": "44-137 BRADFORD STREET", "addressLine2": "CONVENT GARDEN", "city": "LONDON", "state": null, "country": "GB", "postcode": "SO53 2FW" } }, "stakeholders": [ { "entityType": "CORPORATE", "stakeholderDetails": null, "businessPartner": { "businessName": "ACME PVT. LTD.", "businessRegistrationNumber": "P652246613", "businessEntityType": "UBO", "sharePercentage": "4.00", "addresses": { "registeredAddress": null, "businessAddress": null }, "legalDetails": { "registeredCountry": "GB", "registeredDate": "2016-01-17" } } }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "MARTHA", "middleName": null, "lastName": "ROGERS dqhfj", "kycMode": "E_KYC", "nationality": "GB", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "addressLine2": null, "city": "Vilnius", "state": null, "country": "LT", "postcode": "LT-8098" }, "contactDetails": { "email": "sh3@yopmail.com", "contactNo": "442020757588", "countryCode": null }, "professionalDetails": [ { "position": "SHAREHOLDER", "sharePercentage": "27.00" } ], "additionalInfo": { "isPep": "Yes"}, "documentDetails": null }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "ARTHUR", "middleName": null, "lastName": "ROGERS bamqe", "nationality": "GB", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "addressLine2": null, "city": "Vilnius", "state": null, "country": "LT", "postcode": "LT-8098" }, "contactDetails": { "email": "sh2@yopmail.com", "contactNo": "442020757588", "countryCode": null }, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "additionalInfo": { "isPep": "Yes"}, "documentDetails": null }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "MARY", "middleName": null, "lastName": "ROGERS vmikg", "nationality": "GB", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "123 High Street", "addressLine2": null, "city": "London", "state": "London", "country": "GB", "postcode": "SW1A 1AA" }, "contactDetails": { "email": "sh4@yopmail.com", "contactNo": "912020757588", "countryCode": null }, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "additionalInfo": { "isPep": "No"}, "documentDetails": null }, "businessPartner": null } ], "additionalInfo": { "searchId": "1970b00a-229f-49bf-8c68-f45f600b98b0", "isSameBusinessAddress": "Yes" }, "applicantDetails": { "firstName": "MARY", "middleName": null, "lastName": "ROGERS ktsdwe", "kycMode": "E_DOC_VERIFY", "nationality": "GB", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "123 High Street", "addressLine2": null, "city": "London", "state": "London", "country": "GB", "postcode": "SW1A 1AA" }, "contactDetails": { "email": "sh4@yopmail.com", "contactNo": "912020757588", "countryCode": "GB" }, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "additionalInfo": { "isPep": "No"}, "documentDetails": null } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "GB011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVGB01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVGB02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVGB01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVGB02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ], "industryDescription": "Trader of Seeds and fertilizers based in UK." } } ``` ### Request example: In Progress with documents required In this scenario, all information required for completing the verification process is provided in the Onboard Corporate Customer API, however some of the required documents are not submitted. The customer is expected to submit all the required documents after which Nium initiates the verification. In this case, you need to receive the documents required in the `remarks` field. ```json { "region": "UK", "businessDetails": { "businessName": "Bradsons Electronics23343", "businessRegistrationNumber": "239854510000442", "businessType": "PRIVATE_COMPANY", "tradeName": "Bradsons Electronics", "website": "www.brandsonelectronics.co.uk", "addresses": { "registeredAddress": { "addressLine1": "1 ANGEL COURT, 23RD AVENUE", "city": "LONDON", "country": "GB", "postcode": "EC2R 7AG" } }, "legalDetails": { "registeredCountry": "GB", "registeredDate": "1999-01-02" }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "document": "", "fileName": "BRD.pdf", "fileType": "application/pdf" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "Bradson", "middleName": "J", "lastName": "Chan", "dateOfBirth": "1980-01-17", "nationality": "GB", "professionalDetails": [ { "position": "UBO", "sharePercentage": "5" } ], "address": { "addressLine1": "High Street 303, 24th Street", "addressLine2": "Bradford Avenue", "city": "London", "country": "GB", "postcode": "28046" }, "contactDetails": { "contactNo": "691668879", "countryCode": "GB", "email": "peter@azmotor.com" }, "additionalInfo": { "isPep": "Yes" } } }, { "referenceId": "128ebeeb-3ede-4f49-8381-1e382334154d", "stakeholderDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "BRAD", "lastName": "PITT", "middleName": "C", "nationality": "GB", "dateOfBirth": "1985-03-15", "professionalDetails": [ { "position": "DIRECTOR" } ], "address": { "addressLine1": "High Street 202", "addressLine2": "56th Avenue", "city": "Vesoul", "state": "Franche-Comte", "country": "FR", "postcode": "70000" }, "additionalInfo": { "isPep": "Yes" } } }, { "referenceId": "006ebeeb-3ede-4f49-8381-1e382334131c", "businessPartner": { "legalDetails": { "registeredCountry": "FR" }, "businessEntityType": "SHAREHOLDER", "businessName": "JumaTECH LIMITED", "businessRegistrationNumber": "JM22843822" } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "BRAD", "lastName": "LEONG", "middleName": "C", "nationality": "GB", "dateOfBirth": "1985-03-15", "professionalDetails": [ { "position": "DIRECTOR" } ], "address": { "addressLine1": "High Street 202", "addressLine2": "56th Avenue", "city": "London", "country": "GB", "postcode": "L1 8JQ" }, "contactDetails": { "contactNo": "500668880", "countryCode": "GB", "email": "brad@belec.com" }, "additionalInfo": { "isPep": "Yes" } }, "additionalInfo": { "isSameBusinessAddress": "Yes", "searchId": "d902e6cc-4b72-4b48-b814-725352c4768d" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "GB011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVGB01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVGB02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVGB01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVGB02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ], "industryDescription": "Trader of Seeds and fertilizers based in UK." }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ### Completing applicant or stakeholder eDocVerify The applicant or stakeholder eDocVerify is done via the third-party vendor Onfido. Applicant/ stakeholder KYC via Onfido takes place for the EU region when the KYC mode is `E_DOC_VERIFY`. To simulate different success and error responses of the eDocVerify flow, use the following conditions on the applicant's phone number. In all cases, the applicant needs to open the redirect URL in their browser. You either land on the vendor’s page or receive a success/failure redirection back to your KYC redirect URL without any actions needed on the UI. The redirectURL has `isSuccess`, `errorCode`, and `errorMessage` parameters as described in [Applicant KYC](/docs/onboarding/corporate-customers/uk-onboarding#applicant-kyc). Based on `businessDetails.applicantDetails.contactDetail.contactNumber` or `businessDetails.stakeholders.stakeholderDetails.contactDetail.contactNumber`, there are two outcomes: | First two digits of `contactNumber` | Resulting situation | | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Doesn't contain any of the simulated patterns | Onfido's sandbox page is opened and the applicant needs to complete the simulated authentication on the UI. This can be used for end-to-end testing. | | Does contain any of the simulated patterns | The customer's browser redirects to your KYC redirect URL without the need of any actions on the UI. Redirection will contain the following [Redirection parameters](#redirection-parameters) | #### Redirection parameters | Return code | Query parameters in the redirection | | :---------- | :---------------------------------------------------------------------------------- | | 91 | `isSuccess`=`true` ; `errorCode`=;`errorMessage`= | | 41 | `isSuccess = false` ; `errorCode = R403`; `errorMessage = documentAlreadySubmitted` | | 51 | `isSuccess = false` ; `errorCode = I500`; `errorMessage = unexpectedError` | | 61 | `isSuccess = false` ; `errorCode = R408`; `errorMessage = redirectUrlExpired` | ## Simulate scenarios in the manual KYB flow You might want to test transactions without going through the onboarding flow. To enable this, Nium provides simulated requests which get auto-approved in the manual KYB flow. You can generate auto-approval scenarios for manual KYB only in the sandbox environment. In production, every application is reviewed by Nium's compliance analysts before approval. | Simulated scenario | Condition on BRN | Example BRN | | :---------------------------------------------- | :--------------- | :------------------------------------ | | [Auto-approval](#request-example-auto-approval) | Contains `M01` | `M01324536`, `234M01456`, `12M01B325` | Call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API with the following example request. ```json { "region": "UK", "businessDetails": { "businessName": "HEATHER COMPANY xdmbl", "businessRegistrationNumber": "B0183473323", "website": null, "tradeName": "HEATHER COMPANY", "businessType": "PRIVATE_COMPANY", "legalDetails": { "registeredCountry": "GB", "registeredDate": "2016-01-17" }, "addresses": { "registeredAddress": { "addressLine1": "44-137 BRADFORD STREET", "addressLine2": "CONVENT GARDEN", "city": "LONDON", "state": null, "country": "GB", "postcode": "SO53 2FW" } }, "stakeholders": [ { "entityType": "CORPORATE", "stakeholderDetails": null, "businessPartner": { "businessName": "ACME PVT. LTD.", "businessRegistrationNumber": "P652246613", "businessEntityType": "UBO", "sharePercentage": "4.00", "addresses": { "registeredAddress": null, "businessAddress": null }, "legalDetails": { "registeredCountry": "GB", "registeredDate": "2016-01-17" } } }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "MARTHA", "middleName": null, "lastName": "ROGERS vsvrn", "kycMode": "E_KYC", "nationality": "GB", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "addressLine2": null, "city": "Vilnius", "state": null, "country": "LT", "postcode": "LT-8098" }, "contactDetails": { "email": "sh3@yopmail.com", "contactNo": "442020757588", "countryCode": null }, "professionalDetails": [ { "position": "SHAREHOLDER", "sharePercentage": "27.00" } ], "documentDetails": null }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "MD", "middleName": null, "lastName": "AKRAM HOSSAIN ckocb", "kycMode": "E_KYC", "nationality": "BD", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "addressLine2": null, "city": "Vilnius", "state": null, "country": "LT", "postcode": "LT-8098" }, "contactDetails": { "email": "sh1@yopmail.com", "contactNo": "442020757588", "countryCode": null }, "professionalDetails": [ { "position": "UBO", "sharePercentage": "27.00" } ], "documentDetails": null }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "ARTHUR", "middleName": null, "lastName": "ROGERS odkox", "kycMode": "E_KYC", "nationality": "GB", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "addressLine2": null, "city": "Vilnius", "state": null, "country": "LT", "postcode": "LT-8098" }, "contactDetails": { "email": "sh2@yopmail.com", "contactNo": "442020757588", "countryCode": null }, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "businessPartner": null }, { "entityType": "INDIVIDUAL", "stakeholderDetails": { "firstName": "MARY", "middleName": null, "lastName": "ROGERS ixiup", "kycMode": "E_KYC", "nationality": "GB", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "addressLine2": null, "city": "Vilnius", "state": null, "country": "LT", "postcode": "LT-8098" }, "contactDetails": { "email": "sh4@yopmail.com", "contactNo": "442020757588", "countryCode": null }, "professionalDetails": [ { "position": "DIRECTOR", "sharePercentage": null } ], "documentDetails": null }, "businessPartner": null } ], "additionalInfo": { "isSameBusinessAddress": "Yes" }, "applicantDetails": { "firstName": "MARY", "middleName": null, "lastName": "ROGERS ktbcwe", "kycMode": "E_DOC_VERIFY", "nationality": "GB", "dateOfBirth": "1992-10-10", "address": { "addressLine1": "13 Hursley Road Chandlers Ford", "addressLine2": null, "city": "Vilnius", "state": null, "country": "LT", "postcode": "LT-8098" }, "contactDetails": { "email": "sh4@yopmail.com", "contactNo": "442020757588", "countryCode": "GB" }, "professionalDetails": [ { "position": "REPRESENTATIVE", "sharePercentage": null } ], "documentDetails": null } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "GB011", "industrySector": "IS144", "intendedUseOfAccount": "IU003", "countryOfOperation": [ "GB" ], "travelRestrictedCountry": "Yes", "transactionCountries": [ "GB" ], "restrictedCountries": [ "SG" ], "ofacLicencePresent": "Yes" } } ``` --- # US Onboarding URL: https://docs.nium.com/docs/onboarding/corporate-customers/us-onboarding This page outlines the US Know Your Business (KYB) flows and links to reference pages: | **Page name** | **Description** | | :--------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | | **[US required parameters](/docs/onboarding/corporate-customers/us-onboarding/required-parameters)** | Lists the required request fields for each entity type used in eKYB. | | **[US required documents](/docs/onboarding/corporate-customers/us-onboarding/required-documents)** | Tables of required documents for the business entity, stakeholders, and applicants. | | **[US position mapping](/docs/onboarding/corporate-customers/us-onboarding/postion-mapping)** | Required positions for each entity type at a glance. | | **[US request examples](/docs/onboarding/corporate-customers/us-onboarding/example-requests)** | Example requests for US entities. | Nium supports both **eKYB** and **Manual KYB** for customers in the United States. - **eKYB** is fully automated and can approve eligible customers within minutes of submission.\ Contact your Nium Sales representative to enable eKYB for your account. ## eKYB flow Follow these steps to complete an eKYB application in the US. US Onboarding ### Onboard corporate customers Collect the required data in your onboarding form and call **[Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/%7BclientHashId%7D/corporate)** with the full request body. #### Applicant KYC Supported applicant KYC modes for eKYB in the US: - `E_KYC` (recommended for US residents) - `E_DOC_VERIFY` (recommended for non-US residents) - `MANUAL_KYC` (available if needed for non-US residents; goes to manual review and is not real-time) Set the mode in `businessDetails.applicantDetails.kycMode`. - **Documents are required** for `MANUAL_KYC` and must be sent in `businessDetails.applicantDetails.documentDetails`.\ See **[US required documents](/docs/onboarding/corporate-customers/us-onboarding/required-documents)**. #### Applicant eDocVerify When you use the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request, Nium returns a **redirect URL**.\ Your app must store this URL and redirect the applicant to the KYC vendor’s page to complete identity checks (POI/POA + liveness). After completion, the applicant is redirected back to your configured client KYC redirect URL. **Redirection outcomes** are indicated by the following query parameters: - `errorCode` - `errorMessage` - `isSuccess` — Indicates whether the applicant completed the steps in the vendor UI (not the final KYC result). | **Scenario** | **Expected client action** | **Redirect query parameters** | | :------------------------------------------------------- | :------------------------------------------------------- | :------------------------------------------------------------------------------- | | Applicant completed the required steps in the vendor UI. | Wait for the webhook. | `isSuccess=true`, `errorCode`=N/A, `errorMessage`=N/A | | Document already submitted at the vendor. | KYC processing will continue. Wait for the webhook. | `isSuccess=false`, `errorCode=R403`, `errorMessage=documentAlreadySubmitted` | | Customer provided incorrect data at the vendor. | Ask the customer to correct the data on the vendor page. | `isSuccess=false`, `errorCode=I400`, `errorMessage=vendorValidationError` | | Vendor verification failed. | Application goes to manual review. Wait for the webhook. | `isSuccess=false`, `errorCode=R401`, `errorMessage=vendorVerificationFailure` | | Internal server error at Nium. | Retry later or contact Nium Support. | `isSuccess=false`, `errorCode=R500`, `errorMessage=internalServerError` | | Unexpected vendor error. | Retry later or contact Nium Support. | `isSuccess=false`, `errorCode=I500`, `errorMessage=unexpectedError` | | Validation already completed and link reused. | KYC is completed. Wait for the webhook. | `isSuccess=false`, `errorCode=R606`, `errorMessage=verificationAlreadyCompleted` | **Examples** - Successful redirect:\ `https://www.clientRedirectURL.com/?clientId=...&caseId=4ff53849-3d30-45c8-af11-f95c315ce83c&isSuccess=true&errorCode=&errorMessage=` - Failed redirect (expired):\ `https://www.clientRedirectURL.com/?clientId=...&caseId=4ff53849-3d30-45c8-af11-` **Address formatting rules** - If `businessDetails.applicantDetails.address.country = US`, `state` must be a valid 2-letter state code. - Use **[Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/%7BclientHashId%7D/onboarding/constants)**. - If `country = GB`, `postcode` must be in `SW4 6EH` format. #### Stakeholder KYC Supported KYC modes for **individual stakeholders** in the US eKYB flow: - `E_KYC` (US residents) - `MANUAL_KYC` (non-US residents; manual review required) Set the mode in `businessDetails.stakeholders.stakeholderDetails.kycMode`. - **Documents are required** for `MANUAL_KYC` and must be sent in `businessDetails.stakeholders.stakeholderDetails.documentDetails`.\ See **[US required documents](/docs/onboarding/corporate-customers/us-onboarding/required-documents)**. #### Upload documents Documents may be required if any applicant or stakeholder uses `MANUAL_KYC`. **How to submit documents** - With [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) (preferred: one document per call for faster UX). - With [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request (bulk upload in the same request). - Use the `remarks` field (in responses) to see which documents Nium expects. The API gateway limits request payloads to **10 MB**.\ Prefer **Upload Document** to send files one at a time. For a complete list of required documents for eKYB and Manual KYB, see **[US required documents](/docs/onboarding/corporate-customers/us-onboarding/required-documents)**. #### Applicant declaration US applicants must accept the following declaration: > I certify that I am the authorized representative of the customer; all information provided and documents submitted are complete and correct. I confirm that I have provided all the UBOs present. I have read and accepted the [Nium Terms and Conditions](https://www.nium.com/legal/end-customer-terms). Implementation notes: - Capture acceptance via clickwrap. - Send confirmation by passing `Yes` in `businessDetails.applicantDetails.additionalInfo.applicantDeclaration` and include a timestamp. - This field is **mandatory**. Any value other than `Yes` results in a validation error. - Display the declaration text where you collect consent. #### Terms and conditions - Customers must be shown the **Nium Terms and Conditions** configured for your `client` resource. - Fetch them with **[Terms and Conditions API](/api#tag/customer-terms-and-conditions/GET/api/v1/client/%7BclientHashId%7D/termsAndConditions)**. Do not allow submission until the customer accepts the terms. #### Integration flow 1. Call [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) and obtain a `customerHashId`. 2. Call **[Accept Terms and Conditions](/api#tag/customer-terms-and-conditions/POST/api/v1/client/%7BclientHashId%7D/customer/%7BcustomerHashId%7D/termsAndConditions)** with `customerHashId`. 3. Display the returned T\&Cs and record acceptance before enabling transactions. For more details, see **[Terms and Conditions](/docs/onboarding#terms-and-conditions)**. ### Webhook response After submission and applicant KYC completion, the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) response shows `status = IN_PROGRESS`.\ Nium performs real-time verification and sends results via webhook. The application may be **approved** at this stage; otherwise, it proceeds to **manual review**. Any further `status` changes are also sent via webhook. - For next steps, follow the guidance in the **[relevant webhook](/docs/onboarding#webhooks)** response. ## Manual KYB flow Manual KYB follows the eKYB sequence, with one key difference: **documents are always required**. US Manual KYB ## Submitting documents - You may include documents in Onboard Corporate Customer, but using [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) is preferred (one file per call, faster UX). - Use the `remarks` field in either API’s response to see which documents Nium expects. ## Processing - After documents are uploaded, Nium initiates verification. - You’ll be notified of all `status` changes via webhook. - For the full list of required documents (eKYB and Manual KYB), see **[US required documents](/docs/onboarding/corporate-customers/us-onboarding/required-documents)**. ## Constraints - **Upload Document** can be called only while the application is in `IN_PROGRESS`. ## Implementation checklist 1. **Business documents** are mandatory for `MANUAL_KYB`. Send them using the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request or the preferred [Upload Document](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate/documents) request under `businessDetails.documentDetails`.\ Nium will not start verification until all required documents are submitted. 2. **Applicant KYC** is the same as eKYB. See **[Applicant KYC](#applicant-kyc)**. 3. **Stakeholder KYC** in Manual KYB supports only `MANUAL_KYC` for individual stakeholders. - Set `businessDetails.stakeholders.stakeholderDetails.kycMode = MANUAL_KYC`. - Upload documents in `businessDetails.stakeholders.stakeholderDetails.documentDetails`. - See **[US required documents](/docs/onboarding/corporate-customers/us-onboarding/required-documents)**. 4. **Applicant declaration** is required (same as eKYB). 5. **Terms and Conditions** flow is the same as in eKYB. After submission and document upload, Nium performs a manual review. - For next steps, refer to the webhook event. - See **[Notifications and Webhooks](/docs/developers/notifications-and-webhooks)**. --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/corporate-customers/us-onboarding/required-parameters The API fields shown on this page are relevant to the United States only. To see the full payload, refer to the Onboard Corporate Customer API Reference. The API fields shown on this page are relevant to the United States only. To see the full payload, refer to the [Onboard Corporate Customer API Reference](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate). All fields have a maximum limit of 255 characters unless stated otherwise. ## Request parameters | Property | Description | Required | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `region` | The regulatory region under which the corporate customer is being onboarded. To onboard under the US region, use the US value. | Yes | | [businessDetails](#businessDetails) | Contains information about the business, including the applicant and stakeholders. | Yes | | [riskAssessmentInfo](#riskAssessmentInfo) | Provides additional business profile information, such as total number of employees and annual turnover. | Yes | | [expectedAccountUsage](#expectedaccountusage-object) | Provides additional business profile information, such as total number of employees and annual turnover. | Yes | | [natureOfBusiness](#riskAssessmentInfonatureOfBusiness) | Provides additional business profile information, such as total number of employees and annual turnover. | Yes | | [deviceDetails](#deviceDetails) | Includes the device and IP address from which the onboarding request originated. | Yes | | [tags](#tags) | Contains user-defined key-value pairs submitted by the client. | No | | `customerHashId` | A unique identifier returned in the response to the Onboard Corporate Customer request.Note:\* Required only when reinitiating KYB after a rejection. | Yes \* | ## Request parameters The below Request parameters refer to the `businessType` fields: | Public | Trust | Other entity | | :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PUBLIC_COMPANY` | `TRUST` | `CORPORATION` `LIMITED_LIABILITY_COMPANY``ESTATE` `GENERAL_PARTNERSHIP` `LIMITED_LIABILITY_PARTNERSHIP` `SOLE_TRADER``UNICORP_ASSOCIATION``LIMITED_PARTNERSHIP` | ## `businessDetails` object Contains information about the corporate customer, including the applicant and stakeholders. | Property | Description | Public | Trust | Other entity | | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- | :---------- | :----------- | | `referenceId` | A unique identifier for the business entity. If not provided, Nium generates one. Used to respond to RFIs or upload documents. | Optional | Optional | Optional | | `businessName` | The registered name of the business. | Required | Required | Required | | `businessRegistrationNumber` | The business registration number. For US customers, pass only the employer identification number (EIN). This field accepts only 9 digits. Sole traders can submit TIN/ SSN in case EIN is not avialable | Required | Required | Required | | `tradeName` | The name the business operates under. If the business doesn't use a trade name, set businessName as tradeName | Required | Required | Required | | `website` | The business’s website. If not available, submit a social media profile (such as Instagram or Facebook). If neither is available, upload a document with documentType : PROOF\_OF\_BUSINESS. | Optional | Optional | Optional | | `businessType` | The legal entity type, such as a private or public company. Use the [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` : `businessType`. | Required | Required | Required | | `description` | A brief overview of the business. Max character length allowed is 65535. | Required | Required | Required | | `stockSymbol` | The publicly traded stock or ticker symbol of the business. | Required | N/A | N/A | | [legalDetails](#businessDetails-legalDetails) | Registration and legal information for the business. | Required | Required | Required | | [regulatoryDetails](#businessDetails-regulatoryDetails) | An object that contains the regulatory details. | N/A | Required | N/A | | [addresses](#businessDetails-addresses) | An object that contains the registered address and the business address of the corporate customer. | Required | Required | Required | | [documentDetails](#businessdetails-documentdetails) | Business documents. For details, see [US Required Documents](/docs/onboarding/corporate-customers/us-onboarding/required-documents). | Required \* | Required \* | Required \* | | [stakeholders](#businessdetails-stakeholders) | An array of object that contains the individual and corporate stakeholders of the corporate customer. | Required | Required | Required | | [applicantDetails](#businessdetails-applicantdetails) | An object that contains the applicant's details. | Required | Required | Required | | [additionalInfo](#businessDetails-additionalInfo) | An object that contains additional information about the business. | Optional | Optional | Optional | ### `legalDetails` object An object within the `businessDetails` object that accepts legal details. | Property | Description | Public | Trust | Other entity | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | :------: | :----------: | | `registeredDate` | The date the business is registered entered in the `YYYY-MM-DD` format. Registered date cannot be a future date. | Required | Required | Required | | `registeredCountry` | The country where the business is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`countryName`. | Required | Required | Required | | `listedExchange` | The exchange where the business is publicly listed. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`listedExchange`. | Required | N/A | N/A | ### `regulatoryDetails` object An object within the `businessDetails` object that accepts the regulatory status of the client. | Property | Description | Public | Trust | Other entity | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----: | :------: | :----------: | | `unregulatedTrustType` | The array of one or more unregulated trust types. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`unregulatedTrustType`. This field is an array. | N/A | Required | N/A | ### `addresses` object An object within the `businessDetails` object that accepts registered and business addresses. | Property | Description | Public | Trust | Other entity | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: | :---------: | :----------: | | [registeredAddress](#businessdetails-address-registeredaddress) | An object that contains the address where the business is registered. | Required | Required | Required | | [businessAddress](#businessdetails-address-businessaddress) | An object that contains the address where the business is mainly conducted, if different than the registered address. Note: This is not required if isSameBusinessAddress= Yes is passed under businessDetails.additionalInfo. | Required \* | Required \* | Required \* | #### `registeredAddress` object An object within the `businessDetails.address` object that accepts the address details where the corporate customer is registered. | Property | Description | Required | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the registered business. | Yes | | `addressLine2` | The second address line of the registered business. | No | | `city` | The city where the corporate customer is registered. | Yes | | `state` | The state where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`state`. | Yes | | `country` | The country where the corporate customer is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`countryName`. | Yes | | `postcode` | The postal code where the corporate customer is registered. | Yes | #### `businessAddress` object An object within the `businessDetails.address` object that accepts the address details of the principal place of business only when the registered address is different. \* This object is not required if businessDetails.additionalInfo.isSameBusinessAddress = Yes. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the business address. | Yes \* | | `addressLine2` | The second address line of the business address. | No | | `city` | The city of the business address. | Yes \* | | `state` | The state of the business address. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`state`. | Yes \* | | `country` | The country of the business address. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`countryName`. | Yes \* | | `postcode` | The postal code of the business address. | Yes \* | ### `documentDetails` object An array of objects within the `businessDetails` object that accepts one or more business documents. \* This object is always required for `MANUAL_KYB` and required for eKYB in few businessTypes. For both manual KYB and eKYB, the `CERTIFICATE_OF_GOOD_STANDING` document is required when the `address.registeredAddress.state` field is `DE` or `NJ`. | Property | Description | Required | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of business document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`documentType`. | Yes \* | | [document](#businessdetails-documentdetails-document) | An object that contains a document copy. | Yes \* | #### `document` object An array of objects within the `businessDetails.documentDetails` object such as Business Registration Document or Partnership Deed. You can add multiple files under the same document object such as multiple pages of the Business Registration Document or addendum. | Property | Description | Required | | ---------- | --------------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes \* | | `fileType` | The type of the file. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes \* | | `document` | The file as a base64 encoded string. | Yes \* | ### `additionalInfo` object An object within the `businessDetails` object that contains additional information about the business. | Property | Description | Required | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `isSameBusinessAddress` | This field accepts `Yes` or `No` to indicate if the principal place of business is the same or different from the registered business entity address. **Note:** This field is required if `Yes`; optional if `No`. | Yes \* | ### `stakeholders` object An array of objects within the businessDetails object that contains the stakeholders of the corporate customers such as Directors or UBOs. Stakeholder can be a business entity or a natural person. For every stakeholder object, you need to send either the stakeholderDetails or the businessPartner parameters. | Property | Description | Required | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `referenceId` | The UUID associated with the stakeholder and stakeholder object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload the required documents. | No | | [stakeholderDetails](#businessdetails-stakeholders-stakeholderdetails) | An object that contains the details about the individual stakeholder. | Yes | | [businessPartner](#businessdetails-stakeholders-businesspartner) | An object that contains the details of the corporate stakeholder, if available. | Yes | #### `stakeholderDetails` object An object within the stakeholders object that contains the details about an individual stakeholder (natural person). All the Signatories, Directors, UBOs, Trustees, Settlor, Partners as available in the registration documents or SOS filings should be added as stakeholders. - **Directors**: All the officers declared during registration need to be added as Directors. Other Board of Directors should also be added as directors. - **UBO**: All shareholders owning more than 25% of share (directly or indirectly) should be tagged as UBOs. In case no UBO is submitted, Nium’s team will identify the UBO. For sole traders, the owner should be declared as the UBO. - **CONTROL PRONG**: Individuals with significant responsibility to control, manage, or direct the legal entity. This includes: CEO, CFO, COO, Managing Member, General Partner, President, etc. At least one Control Prong should be identified while submitting the application. - **Signatory**: Individual(s) that will conduct transactions or add additional users should be declared as a Signatory. Applicant is considered as Signatory by default and should be added as such and will be eligible for conducting transactions. Any other users can be added as representatives as well. It is recommended to send all the users as part of the application. These users can be added later as well by sending an email to . KYC of such users should be completed as directed. - **Others**: Other positions such as Partner/ Trustee / Settlor should be provided as applicable as per the Position mapping | Property | Description | Required | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `kycMode` | The KYC mode for verifying the individual stakeholder. The valid values are `E_KYC` and `MANUAL_KYC`. | Yes | | `firstName` | The first name of the individual stakeholder. | Yes | | `middleName` | The middle name of the individual stakeholder. | No | | `lastName` | The last name of the individual stakeholder. | Yes | | `nationality` | The nationality of the individual stakeholder (e.g., US, IN). Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests for a valid set of values with `category`=`countryName` | Yes | | `dateOfBirth` | The date the individual stakeholder was born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. | Yes | | [professionalDetails](#businessdetails-stakeholders-stakeholderdetails-professionaldetails) | An array of objects to accept the positions held by the stakeholder in the business of the corporate customer and details related to the positions held. | Yes | | [address](#businessdetails-stakeholders-stakeholderdetails-address) | An object that contains the residential address of the individual stakeholder. | Yes | | [contactDetails](#businessdetails-stakeholders-stakeholderdetails-contactdetails) | An object that contains the contact details of the individual stakeholder. | No | | [documentDetails](#businessdetails-stakeholders-stakeholderdetails-documentdetails) | An array of object that contains the document details of the individual stakeholder. | Yes | ##### `professionalDetails` object An array of object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's professional details. Very often an individual can hold more that one position such as DIRECTOR/ UBO and all applicable positions must be selected. | Property | Description | Required | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `position` | The position of the individual stakeholder such as UBO, DIRECTOR, SIGNATORY. At least one of the individual stakeholders should have a position as `CONTROL_PRONG`. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`position`. | Yes | | `sharePercentage` | The share percentage of the individual stakeholder in the company. Sharepercentage should be a number between 0 and 100. Eg. 23.4 Note: This field is required if position is UBO or SHAREHOLDER. Else ignore. | Yes \* | ##### `addresses` object An object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's residential address. | Property | Description | Required | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | | `addressLine1` | The first address line of the individual stakeholder. | Yes | | `addressLine2` | The second address line of the individual stakeholder. | No | | `city` | The city or suburb of the individual stakeholder. | Yes | | `state` | The state or province of the individual stakeholder. | Yes | | `country` | The country where the individual stakeholder resides, specified in [ISO 3166 format](https://www.iban.com/country-codes) with `category`=`countryName` | Yes | | `postcode` | The postal code of the individual stakeholder. | Yes | ##### `contactDetails` object An optional object within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's contact information. | Property | Description | Required | | ----------- | ------------------------------------------------------- | :------: | | `email` | The individual stakeholder's email address. | No | | `contactNo` | The contact phone number of the individual stakeholder. | No | ##### `stakeholderDetails.documentDetails` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails` object that contains the individual stakeholder's document details. | Property | Description | Required | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `documentType` | The type of document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`documentType`. | Yes | | `documentNumber` | The identification number of the document. | Yes | | `documentIssuanceCountry` | The country that issued the document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values. | Yes | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. **Note:** This field is required if `documentType = PASSPORT` or `DRIVER_LICENCE`. Expiry date cannot be a past date. | Yes \* | | [document](#businessdetails-stakeholders.stakeholderdetails-documentdetails-document) | A copy of the document. **Note:** This field is required for `MANUAL_KYC`. This field is an array. | Yes \* | ##### `documentDetails.document` object An array of objects within the `businessDetails.stakeholders.stakeholderDetails.documentDetails` object that contains the document copy. You can pass front and back of a passport etc.. as in array under the same documentDetails object. \* This object is required for `MANUAL_KYC`. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes \* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes \* | | `document` | The document saved as a base64 encoded string. | Yes \* | #### `businessPartner` An object within the businessDetails.stakeholders object that contains the business details of the corporate stakeholder. If the customer is a multilayered company with another corporate owning more than 25% of share directly or indirectly then all such corporate stakeholders should be declared in the application. Refer [Multi-layered ownership structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-us#heading-8) to understand if the customer is a multi-layered company. Additionally, Ownership chart document should be submitted to validate the structure under businessDetails.documentType = OWNERSHIP\_CHART. Refer to [US Required documents](/docs/onboarding/corporate-customers/us-onboarding/required-documents). | Property | Description | Required | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `businessName` | The registered business name of the corporate stakeholder. | Yes | | `businessRegistrationNumber` | The business registration number. | Yes | | `businessEntityType` | The primary position of the corporate stakeholder in the business of the company. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` = `position` for a valid set of values. Corporate stakeholders can typically hold positions such as UBO, SHAREHOLDER, PARTNER, TRUSTEE. Sometimes, corporate stakeholder can be a DIRECTOR as well. | Yes | | `sharePercentage` | The share percentage of the corporate stakeholder in the company. Note: This field is required if the stakeholder’s position is UBO or SHAREHOLDER. Else ignore. Sharepercentage should be a number between 0 and 100. Eg. 23.4 | Yes \* | | [legalDetails](#businessdetails-stakeholders-businesspartner-legaldetails) | An object that contains the registration and legal details of the corporate stakeholder. | Yes | ##### `businessPartner.legalDetails` object An object within the `businessDetails.stakeholders.businessPartner` object that contains the corporate stakeholder's legal details. | Property | Description | Required | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `registeredCountry` | The country where the corporate stakeholder is registered. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`countryName`. | Yes | ### `applicantDetails` object Contains details about the individual applicant representing the corporate customer. | Property | Description | Required | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `referenceId` | The universally unique identifier (UUID) associated with the applicant and applicant object. If the UUID isn't provided, Nium generates one. The UUID can be used to respond to an RFI or to upload required documents. | No | | `kycMode` | The KYC mode for verifying the identity of the applicant. Valid values are `E_KYC` , `E_DOC_VERIFY`, and `MANUAL_KYC`. | Yes | | `firstName` | The first name of the applicant. The maximum length is 40 alphabetic characters or spaces. | Yes | | `middleName` | The middle name of the applicant. The maximum length is 40 alphabetic characters or spaces. | No | | `lastName` | The last name or the applicant. The maximum length is 40 alphabetic characters or spaces. | Yes | | `nationality` | The nationality of the applicant (e.g., US, IN). Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values with `category`=`countryName`. | Yes | | `dateOfBirth` | The date when the applicant is born in the `YYYY-MM-DD` format. Date of birth cannot be a future date. Applicant age cannot cannot be less than 18 yrs. | Yes | | [professionalDetails](#businessdetails-applicantdetails-professionaldetails) | An array of objects that contains the professional details of the applicant. | Yes | | [address](#businessdetails-applicantdetails-address) | An object that contains the address of the applicant. | Yes | | [contactDetails](#businessdetails-applicantdetails-contactdetails) | An object that contains the contact details of the applicant. | Yes | | [documentDetails](#businessdetails-applicantdetails-contactdetails) | An array of objects that contains the document details of the applicant. | Yes | | [additionalInfo](#businessDetails-applicantDetails-additionalInfo) | An object that contains additional information about the applicant such as applicant declaration. | Yes | #### `professionalDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the professional details of the applicant. | Property | Description | Required | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `position` | The position of the applicant. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`position`. An applicant is a REPRESENTATIVE by default. In addition, all applicable positions like UBO or DIRECTOR should be added. | Yes | | `sharePercentage` | The share percentage of the applicant in the company. Number between 0 and 100. Eg., `23.4` Note: This field is required if the position is UBO/ SHAREHOLDER. | Yes \* | #### `applicantDetails.address` object An object within the `businessDetails.applicantDetails` object that contains the applicant's residential address. | Property | Description | Required | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `addressLine1` | The first address line of the applicant. The maximum character length is 40. | Yes | | `addressLine2` | The second address line of the applicant. The maximum character length is 40. | No | | `city` | The city of the applicant. The maximum character length is 20. | Yes | | `state` | The state or province of the applicant. The Maximum character length is 30. | Yes | | `country` | The country where the applicant resides. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values with `category`=`countryName`. | Yes | | `postcode` | The postal code of the applicant. The minimum length is 3 and the maximum length is 10 alphanumeric characters or spaces. | Yes | #### `contactDetails` object An object within the `businessDetails.applicantDetails` object that contains the applicant's contact information. | Property | Description | Required | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `email` | The applicant's email address. The maximum character length is 40 and needs to be a valid email address. See [Email regex](/docs/developers/nium-api). | Yes | | `countryCode`. | The country code of the applicant's phone number. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values with `category`=`countryName`. | Yes | | `contactNo` | The applicant's phone number. The maximum length is 20 numeric characters. | Yes | #### `usinessDetails.applicantDetails.documentDetails` object An array of objects within the `businessDetails.applicantDetails` object that contains the applicant's document information. For - E\_KYC, documentDetails are required. Document is required only for submitting an LOA. - For E\_DOC\_VERIFY, documentDetails and documents are not required,unless for submitting an LOA. - For Manual KYC, both are required. | Property | Description | E\_DOC\_VERIFY | E\_KYC | MANUAL\_KYC | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------: | :----: | :---------: | | `documentType` | The type of the document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`documentType`. | Yes \* | Yes | Yes | | `documentNumber` | Identification number of the document. | No | Yes | Yes | | `documentIssuanceCountry` | The country that issued the document. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values with `category`=`documentType` | No | Yes | Yes | | `documentExpiryDate` | The date the document expires in the `YYYY-MM-DD` format. **Note:** This field is required if `documentType = PASSPORT or DRIVER_LICENCE`. Expiry date cannot be past date. | No | Yes\* | Yes \* | | [document](#businessdetails-applicantdetails-documentdetails-document) | An array of objects that contains the copy of the document. **Note:** This field is required for `MANUAL_KYC` or for submitting `LOA`. | Yes \* | Yes\* | Yes | ##### `documentDetails.document` object An array of objects within the `businessDetails.applicantDetails.documentDetails` object that contains the document copy. You can pass front and back of passport etc.. as an array under the same documentDetails object. \* This object is required for `MANUAL_KYC` or for submitting `LOA`. | Property | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------- | :------: | | `fileName` | The name of the file. | Yes \* | | `fileType` | The file type. Valid types are `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `jpeg`, `jpg`, and `png`. | Yes \* | | `document` | The document saved as a base64 encoded string. | Yes \* | #### `additionalInfo` object An object within the `businessDetails.applicantDetails` object that contains additional information about the applicant. See [Applicant Declaration](/docs/onboarding/corporate-customers/us-onboarding#applicant-declaration) for details | Property | Description | Required | | ------------------------------- | --------------------------------------------------------------------------------------------------------- | :------: | | `applicantDeclaration` | This field accepts the declaration from the Applicant. The only valid value is `Yes`. | Yes | | `applicantDeclarationTimestamp` | The timestamp at which applicant accpeted the declaration in `YYYY-MM-DD HH:MM:SS` format in UTC timezone | Yes | ## `expectedAccountUsage` object This object contains the details regarding the expected usage of the account | Property | Description | Required | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | [debit](#expectedAccountUsageDebit) | Object containing expected account usage of all outward transactions. | Yes | | [credit](#expectedAccountUsageCredit) | Object containing expected account usage of all inward transactions. | Yes | | `intendedUses` | Array of intended uses of the account. Send all applicable values. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` = `intendedUses` for valid values. | Yes | | `intendedUsesDescription` | Text field description of the intended use of the account of the corporate customer. Min 20 characters. | No | ### `debit`object This object containing expected account usage of all outward transactions | Property | Description | Required | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `monthlyTransactionVolume` | Estimated total monthly payout transaction amount converted to `USD`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` is **monthlyTransactionVolume** for a valid set of values. | Yes | | `monthlyTransactions` | Estimated count of payout transactions per month for the corporate customer. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` is **monthlyTransactions** for a valid set of values. | Yes | | `averageTransactionValue` | Estimated average transaction value per payout for the corporate customer converted to `USD`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` is **averageTransactionValue** for a valid set of values. | Yes | | `topTransactionCountries` | Array of top payout countries. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`= `countryName` for a valid set of values. | Yes | ### `credit`object This object containing expected account usage of all inward transactions. - In case the customer is not enabled for payins, the client is expected to send the minimum bracket within the allowed ranges for `monthlyTransactionVolume`, `monthlyTransactions`, `averageTransactionValue`. - The entire credit object is not applicable if the client is a Payroll client and/ or have requested Nium to switch off third party funding. | Property | Description | Required | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `monthlyTransactionVolume` | Estimated total monthly payin transaction amount converted to `USD`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` is **monthlyTransactionVolume** for a valid set of values. | Yes | | `monthlyTransactions` | Estimated count of payin transactions per month for the corporate customer. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category` is **monthlyTransactions** for a valid set of values. | Yes | | `averageTransactionValue` | Estimated average transaction value per payin for the corporate customer converted to `USD`. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) `category` is **averageTransactionValue** for a valid set of values. | Yes | | `topTransactionCountries` | Array of top payin countries. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests with `category`= `countryName` for a valid set of values. | Yes | ## `natureOfBusiness` object An object within the `businessDetails.natureOfBusiness` object to provide the nature of business such as industrySector. \* If the industrySector contains any prohibited industries, additional documentation might be requested and can affect the overall approval TAT. Refer to [Prohibited and Restricted Business Categories](https://www.nium.com/regulatory-disclosures/prohibited-business-categories) | Property | Description | Required | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `industryCodes` | An array of industry sector codes that apply for the corporate customer's business. Send all applicable values. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) for a valid set of values using `industrySector` category | Yes | ## `riskAssessmentInfo` object An object that contains the following details that are required to determine a corporate customer's risk profile. | Property | Description | Required | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | `totalEmployees` | The corporate customer's total number of employees. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) requests for a valid set of values with `category`=`totalEmployees`. | Yes | | `annualTurnover` | The corporate customer’s annual turnover.If the company is less than one year old, provide the expected turnover; otherwise, provide the turnover from the previous year. Turnover refers to the total revenue generated by the business. Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category` = `annualTurnover` for a valid set of values. | Yes | | `countryOfOperation` | An array of all the countries the corporate customer has presence and does business. List all the countries you have branches, operations, factories etc… Use [Fetch Corporate Constants](/docs/onboarding/corporate-customers/corporate-constants) with `category`=`countryName` for a valid set of values. This field is an array. Ex: \["IN", "FR", "LT"] | Yes | ## `deviceDetails` object This object contains the information about the customer's device and IP address where the onboarding request originated. | Property | Description | Required | | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `countryIP` | Country of the IP address e.g. US. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values with `category`=`countryName`. | Yes | | `deviceInfo` | Information of the device e.g. Mac OS. | Yes | | `ipAddress` | IP address of the device in IPV4 format e.g. 45.48.241.198 | Yes | | `sessionId` | A unique identifier for the session, generated by your system. | Yes | ## `tags` object This object contains the user-defined key-value pairs that the client provides. The maximum number of tags is 15. | Property | Description | Required | | -------- | ------------------------------------------------------------------------------- | :------: | | `key` | The name of the tag. The maximum character length is 128. Key should be unique. | No | | `value` | The value of the tag. The maximum character length is 256. | No | --- # Required Documents - US URL: https://docs.nium.com/docs/onboarding/corporate-customers/us-onboarding/required-documents This page outlines the documents required for stakeholders, applicants, and various business types to onboard a corporate customer registered in the United States. ## Business details The following documents are required as part of the Know Your Business (KYB) identification and verification process. | Entity type | Manual KYB | eKYB | | :---------------------------------------------------------- | :-------------------------------------------------- | :----------------------------------------------- | | Corporations Limited liability companies (LLC) | `BUSINESS_REGISTRATION_DOC` | N/A | | Public company | `PROOF_OF_EXISTENCE` | N/A | | Unincorporated associations | `BUSINESS_REGISTRATION_DOC` | `BUSINESS_REGISTRATION_DOC` | | Sole traders | `BUSINESS_REGISTRATION_DOC` or `IRS_CERTIFICATE` | `BUSINESS_REGISTRATION_DOC` or `IRS_CERTIFICATE` | | Estate | `LOA` | `LOA` | | General partnership Limited liability partnership firms | `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | | Limited partnership | `BUSINESS_REGISTRATION_DOCUMENT` `PARTNERSHIP_DEED` | `PARTNERSHIP_DEED` | | Trust | `TRUST_DEED` | `TRUST_DEED` | Any required document not submitted in eKYB flow will be requested via auto-RFI. ### Additional business documents - **CERTIFICATE\_OF\_GOOD\_STANDING**: This document is required when the `address.registeredAddress.state` field is `DE` or `NJ` for both Manual KYB and eKYB. - **PROOF\_OF\_BUSINESS**: This document has to be submitted in case website is not provided. Any document that will help us validate the business of the customer. Proof of Business can be any one of the following documents: - Any document depicting the product catalogue such as company brochures or marketing material or detailed business plan. **\[Preferred]** - Contracts or business agreements or vendor agreements. - Photo of store, in case of brick and mortar store. - Invoice containing clear description of business operations (issued within 1 year) **\[Not preferred]** - **Ownership Chart** This document should be provided if the customer is a multi-layered company. Refer [Multi-layered ownership structure](https://www.nium.com/corporate-onboarding/verifying-your-business-in-eu#heading-6) to understand if the customer is a multi-layered company. Corporate structure can be drafted by the customer and contains the names of the shareholders, along with the percent of shares held which will help us to establish the ultimate beneficial owner. See below for an example. You can use a similar template, if you don't have one. Set `documentType` to **OWNERSHIP\_CHART** to add the corporate structure document. Ownership Chart Ownership Chart - **BUSINESS\_REGISTRATION\_DOCUMENT**: Any of the following could be submitted as business registration document. See [Verifying Ownership](https://www.nium.com/corporate-onboarding/verifying-your-business-in-us#heading-2) to understand the documents that can be obtained for different businessTypes. - Articles of Incorporation - Certificate of Formation - Company Bylaws - Board resolutions - Any Operating Agreement - **CERTIFICATE\_OF\_GOOD\_STANDING**: State issued Certificate of Good standing ## Stakeholders The following documents are required as part of the Know Your Business (KYB) identification and verification process for stakeholders. Only individual stakeholders, not corporate stakeholders, require documents. Based on the address country of the stakeholder, client should pass either `E_KYC` or `MANUAL_KYC`. | Method | Document (`documentType`) | | :------------------------------------- | :------------------------------------------------------------------------------------------ | | eKYC (address.country=US) | The last 4 digits of or the entire SSN to be passed as `documentNumber` (`NATIONAL_ID`) | | Manual KYC (address.country is not US) | Passport details (`PASSPORT`) Driver License (`DRIVER_LICENSE`) National ID (`NATIONAL_ID`) | Also see [Acceptable documents for `PROOF_OF_ADDRESS`](#additional-applicant-documents) ### US residents US residents need to use the KYC mode `E_KYC` with their national ID for verification. | Fields name | National ID | | :------------------------ | :------------------------------------------- | | `documentType` | `NATIONAL_ID` | | `documentNumber` | Yes (The last 4 digits of or the entire SSN) | | `documentIssuanceCountry` | Yes (valid value is `US` for `E_KYC`) | | `documentExpiryDate` | N/A | | `document.fileName` | N/A | | `document.fileType` | N/A | | `document.document` | N/A | ### Non-US residents Every non-US resident need to pass `kycMode`=`MANUAL_KYC` and submit one of the following information. If the document doesn't contain an address, you need to submit an [Acceptable document for `PROOF_OF_ADDRESS`](#additional-applicant-documents) which can verify the address with `documentType = PROOF_OF_ADDRESS`. If this additional document is not submitted, the compliance agent will raise an RFI for `stakeholderAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | Field name | Passport | National ID | Additional document if the first document doesn't contain an address | | :------------------------ | :-------------------- | :------------ | :------------------------------------------------------------------- | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `PROOF_OF_ADDRESS` | | `documentNumber` | Yes (Passport number) | Yes | No | | `documentIssuanceCountry` | Yes | Yes | No | | `documentExpiryDate` | Yes | No | No | | `document.fileName` | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | | `document.document` | Yes | Yes | Yes | For a complete list of business document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. Photocopies or scanned documents in black-and-white are not accepted for Passport, National ID, or Driver's License. ## Applicants Nium offers `E_KYC`, `E_DOC_VERIFY`, and `MANUAL_KYC` modes for applicant KYC in the US. - `E_KYC` is applicable for US residents. Only document details are required for eKYC and upload of document files isn't required. - `E_DOC_VERIFY` is applicable for non-US residents. Applicant needs to complete KYC using the redirect URL. - `MANUAL_KYC` required document details along with upload of document files. ### E\_KYC US residents need to use the KYC mode `E_KYC` with their national ID for verification. | Fields name | National ID | If applicant is not an officer | | :------------------------ | :------------------------------------------- | ------------------------------ | | `documentType` | `NATIONAL_ID` | `LOA` | | `documentNumber` | Yes (The last 4 digits of or the entire SSN) | N/A | | `documentIssuanceCountry` | Yes (valid value is `US` for `E_KYC`) | N/A | | `documentExpiryDate` | N/A | N/A | | `document.fileName` | N/A | Yes | | `document.fileType` | N/A | Yes | | `document.document` | N/A | Yes | ### eDocVerify Every individual applicant needs to submit one of the following information when `kycMode = E_DOC_VERIFY` | Documents to be uploaded in Onfido form | API documents | | :------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Live Selfie with Passport/National ID submitted in the form presented by Onfido (eDoc verification vendor)Proof of address as presented by Onfido | In case applicant is not an officer LOA should be submitted in the API | ### E\_KYC US residents need to use the KYC mode `E_KYC` with their national ID for verification. | Fields name | National ID | If applicant is not an officer | | :------------------------ | :------------------------------------------- | ------------------------------ | | `documentType` | `NATIONAL_ID` | `LOA` | | `documentNumber` | Yes (The last 4 digits of or the entire SSN) | N/A | | `documentIssuanceCountry` | Yes (valid value is `US` for `E_KYC`) | N/A | | `documentExpiryDate` | N/A | N/A | | `document.fileName` | N/A | Yes | | `document.fileType` | N/A | Yes | | `document.document` | N/A | Yes | ### eDocVerify Every individual applicant needs to submit one of the following information when `kycMode = E_DOC_VERIFY` | Documents to be uploaded in Onfido form | API documents | | :------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Live Selfie with Passport/National ID submitted in the form presented by Onfido (eDoc verification vendor)Proof of address as presented by Onfido | In case applicant is not an officer LOA should be submitted in the API | ### E\_KYC US residents need to use the KYC mode `E_KYC` with their national ID for verification. | Fields name | National ID | If applicant is not an officer | | :------------------------ | :------------------------------------------- | ------------------------------ | | `documentType` | `NATIONAL_ID` | `LOA` | | `documentNumber` | Yes (The last 4 digits of or the entire SSN) | N/A | | `documentIssuanceCountry` | Yes (valid value is `US` for `E_KYC`) | N/A | | `documentExpiryDate` | N/A | N/A | | `document.fileName` | N/A | Yes | | `document.fileType` | N/A | Yes | | `document.document` | N/A | Yes | ### eDocVerify Every individual applicant needs to submit one of the following information when `kycMode = E_DOC_VERIFY` | Documents to be uploaded in Onfido form | API documents | | :------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Live Selfie with Passport/National ID submitted in the form presented by Onfido (eDoc verification vendor)Proof of address as presented by Onfido | In case applicant is not an officer LOA should be submitted in the API | ### Manual KYC Every individual applicant needs to submit one of the following information when `kycMode = MANUAL_KYC`. - If the document doesn't contain an address, you need to submit an [Acceptable document for `PROOF_OF_ADDRESS`](#additional-applicant-documents) which can verify the address with `documentType = PROOF_OF_ADDRESS`. - If this additional document is not submitted, the compliance agent will raise an RFI for `applicantAddress` to which you can submit the additional document via the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | Field name | Passport | National ID | Additional document if the first document doesn't contain an address | If applicant is not an officer | | :------------------------ | :-------------------- | :------------ | :------------------------------------------------------------------- | ------------------------------ | | `documentType` | `PASSPORT` | `NATIONAL_ID` | `PROOF_OF_ADDRESS` | `LOA` | | `documentNumber` | Yes (Passport number) | Yes | No | No | | `documentIssuanceCountry` | Yes | Yes | No | No | | `documentExpiryDate` | Yes | No | No | No | | `document.fileName` | Yes | Yes | Yes | Yes | | `document.fileType` | Yes | Yes | Yes | Yes | | `document.document` | **Yes** | **Yes** | **Yes** | Yes | For a complete list of personal document types, see the values obtained from [Fetch corporate constants](/docs/onboarding/corporate-customers/corporate-constants#fieldname-to-category)API with `fieldName` as `documentType`. **NOTE:** Photocopies or scanned documents in black-and-white are not accepted for Passport, National ID, or Driver's License. ### Additional applicant documents - **Letter of Authorization**: In case applicant is not an officer, `LOA` is required. You can upload it during application submission or Nium will request it in RFI. - **Proof of address**: In case the POI document doesn't contain address, POA should be uploaded as a separate document with `documentType`=`PROOF_OF_ADDRESS`. Proof of address should be issued not more than 60 days old while submitting. Acceptable documents for Proof of address are: - Utility bills (gas, electric, internet, phone) - Financial records (bank statement, mortgage statement) - Life, health, or other insurance statement (auto, home, boat) - Medical records (doctor, hospital, or clinical) - Pay-slip - Government-issued letter --- # Position Mapping URL: https://docs.nium.com/docs/onboarding/corporate-customers/us-onboarding/postion-mapping | businessType | CONTROL_PRONG | DIRECTOR | EXECUTOR | MEMBERS | PARTNER | PROTECTOR | SETTLOR | SHAREHOLDER | SIGNATORY | TRUSTEE | UBO | | `businessType` | `CONTROL_PRONG` | `DIRECTOR` | `EXECUTOR` | `MEMBERS` | `PARTNER` | `PROTECTOR` | `SETTLOR` | `SHAREHOLDER` | `SIGNATORY` | `TRUSTEE` | `UBO` | | ------------------------------- | :-------------: | :--------: | :--------: | :-------: | :-------: | :---------: | :-------: | :-----------: | :---------: | :-------: | :---: | | `CORPORATION` | Yes | Yes | | | | | | | Yes | | Yes | | `ESTATE` | Yes | | Yes | | | | | | Yes | | | | `GENERAL_PARTNERSHIP` | Yes | Yes | | | Yes | | | | Yes | | Yes | | `LIMITED_LIABILITY_COMPANY` | Yes | Yes | | | | | | | Yes | | Yes | | `LIMITED_LIABILITY_PARTNERSHIP` | Yes | Yes | | | Yes | | | | Yes | | Yes | | `LIMITED_PARTNERSHIP` | Yes | Yes | | | Yes | | | | Yes | | Yes | | `PUBLIC_COMPANY` | Yes | Yes | | | | | | | Yes | | Yes | | `TRUST` | Yes | | Yes | | | Yes | Yes | Yes | Yes | Yes | Yes | | `UNINCORP_ASSOCIATION` | Yes | | | Yes | | | | | Yes | | Yes | A **Yes** value means that position can be passed for that `businessType`. A blank table cell means that position is not applicable for that `businessType`. Multiple positions in the `professionalDetails` array object as shown below: ```json "professionalDetails": [ { "position": "REPRESENTATIVE" }, { "position": "UBO", "sharePercentage": "50%" }, { "position": "SIGNATORY" } ``` --- # Example Requests URL: https://docs.nium.com/docs/onboarding/corporate-customers/us-onboarding/example-requests To onboard your entity, you can call the Onboard Corporate Customer API. For an example call that you can customize with your information, see: To onboard your entity, you can call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. For an example call that you can customize with your information, see: - [Public companies](#public) - [Trusts](#trust) - [All other entities](#other) - [Simulate various scenarios](#simulate-various-scenarios) ## Public companies The following is an API request example call where `businessType = PUBLIC_COMPANY`. ```json { "region": "US", "businessDetails": { "businessName": "Jubliant Public Corporations10", "businessRegistrationNumber": "52940398934", "businessType": "PUBLIC_COMPANY", "description": "Public company in US to facilitate agro payments", "legalDetails": { "registeredCountry": "US", "registeredDate": "2021-08-10", "listedExchange": "EX103" }, "stockSymbol": "MLFP", "addresses": { "registeredAddress": { "addressLine1": "999 Park Street", "addressLine2": "Near Airport", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" } }, "documentDetails": [ { "documentType": "PROOF_OF_EXISTENCE", "document": [ { "fileName": "POE", "fileType": "application/pdf", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "MARTHA", "lastName": "JONES", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "Park Street", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US", "document": [ { "fileName": "POI.png", "fileType": "images/png", "document": "gtudfsdfgegetg" } ] } ] } }, { "businessPartner": { "businessName": "Lightsaber Fintech Venture", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "John", "lastName": "Arch", "nationality": "US", "dateOfBirth": "1982-07-10", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "US", "contactNo": "9974922222", "email": "tom@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "West Hartford", "state": "Connecticut", "postcode": "06110", "country": "US" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "123456789", "documentIssuanceCountry": "US" } ], "additionalInfo": { "applicantDeclaration": "Yes", "applicantDeclarationTimestamp": "2025-09-02 14:03:45" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "US011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Trusts The following is an API request example call where `businessType = TRUST`. ```json { "region": "US", "businessDetails": { "businessName": "Farhampton Children Trust25", "businessRegistrationNumber": "52940397834", "businessType": "TRUST", "description": "Trust in US to support specially abled children", "legalDetails": { "registeredCountry": "US", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "999 Park Street", "addressLine2": "Near Airport", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" } }, "regulatoryDetails": { "unregulatedTrustType": [ "TT002" ] }, "documentDetails": [ { "documentType": "TRUST_DEED", "document": [ { "fileName": "TRUSTDEED", "fileType": "application/pdf", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "KATIE", "lastName": "WINCELET", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "Park Street", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US", "document": [ { "fileName": "POI.png", "fileType": "images/png", "document": "gtudfsdfgegetg" } ] } ] } }, { "businessPartner": { "businessName": "Amanda Corp", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Tom", "lastName": "Cruise", "nationality": "US", "dateOfBirth": "1982-07-10", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "US", "contactNo": "9974922222", "email": "tom@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "West Hartford", "state": "Connecticut", "postcode": "06110", "country": "US" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "123456789", "documentIssuanceCountry": "US" } ], "additionalInfo": { "applicantDeclaration": "Yes", "applicantDeclarationTimestamp": "2025-09-02 14:03:45" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "US011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Other entities The following is an API request example call where `businessType = CORPORATION`. Examples for other entity types listed below are similar. - Corporations - Estates - General partnerships - Limited liability company - Limited liability partnership firms - Limited partnerships - Sole traders - Unincorporated associations ```json { "region": "US", "businessDetails": { "businessName": "Soylent Corporation68s", "businessRegistrationNumber": "529403988", "businessType": "CORPORATION", "description": "Corporation in US to facilitate payments to business", "tradeName": "Soylent Corp", "legalDetails": { "registeredCountry": "US", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "999 Park Street", "addressLine2": "Near Airport", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" } }, "documentDetails": [ { "documentType": "BUSINESS_REGISTRATION_DOC", "document": [ { "fileName": "BRD", "fileType": "application/pdf", "document": "" } ] } ], "stakeholders": [ { "stakeholderDetails": { "kycMode": "MANUAL_KYC", "firstName": "MICHAEL", "lastName": "JONES", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "Park Street", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US", "document": [ { "fileName": "POI.png", "fileType": "images/png", "document": "gtudfsdfgegetg" } ] } ] } }, { "businessPartner": { "businessName": "Vehement Capital Partners", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "Tom", "lastName": "Arch", "nationality": "US", "dateOfBirth": "1982-07-10", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "US", "contactNo": "9974922222", "email": "tom@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "West Hartford", "state": "Connecticut", "postcode": "06110", "country": "US" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "123456789", "documentIssuanceCountry": "US" } ], "additionalInfo": { "applicantDeclaration": "Yes", "applicantDeclarationTimestamp": "2025-09-02 14:03:45" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "US011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ## Simulate various scenarios You can generate the following scenarios by using the below example requests to call the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) API. | Simulated Scenario | condition on BRN | Example | | :-------------------------------------------------- | :----------------------------------------------------- | :-------- | | [Auto-approval](#auto-approval) | Starts with `101` | 101567889 | | [Action required](#action-required) | Starts with `102` | 102567898 | | [In progress with documents required](#in-progress) | Any BRN | 101789123 | | [In progress with redirectURL](#redirectURL) | Pattern on `applicantDetails.contactDetails.contactNo` | | > It may take 5 to 10 minutes for you to get the next webhook after submission in sandbox. ### Request example: auto-approval ```json { "region": "US", "businessDetails": { "businessName": "TESSERACT LLC WFWEF15", "businessRegistrationNumber": "101401556", "businessType": "LIMITED_LIABILITY_COMPANY", "description": "Limited liability company in US for IT services", "legalDetails": { "registeredCountry": "US", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "223, Grand St.", "addressLine2": "", "city": "New York", "state": "NY", "country": "US", "postcode": "10013" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "MARTHA", "lastName": "ENGLISH REBORN", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "UBO", "sharePercentage": "52.3" } ], "address": { "addressLine1": "Park Street", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US" } ] } }, { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "MARCUS", "lastName": "STYLUS", "nationality": "US", "dateOfBirth": "1956-04-15", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "111, White Avenue", "city": "New York", "state": "NY", "country": "US", "postcode": "11123" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "666456789", "documentIssuanceCountry": "US" } ] } }, { "businessPartner": { "businessName": "CUZEK PRIVATE VENTURES", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "MARTHA", "lastName": "ENGLISH REBORN", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "US", "contactNo": "9974922222", "email": "tony@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "West Hartford", "state": "Connecticut", "postcode": "06110", "country": "US" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US" } ], "additionalInfo": { "applicantDeclaration": "Yes", "applicantDeclarationTimestamp": "2025-09-02 14:03:45" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "US011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ### Request example: action required ```json { "region": "US", "businessDetails": { "businessName": "TESSERACT LLC WFRRF", "businessRegistrationNumber": "102404336", "businessType": "LIMITED_LIABILITY_COMPANY", "description": "Limited liability company in US for IT services", "legalDetails": { "registeredCountry": "US", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "Random Address", "addressLine2": "", "city": "Gotham City", "state": "NY", "country": "US", "postcode": "10013" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "MARTHA WAS", "lastName": "ENGLISH IS", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "Park Street", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US" } ] } }, { "businessPartner": { "businessName": "CUZEK PRIVATE VENTURES", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "E_KYC", "firstName": "MARTHA IS", "lastName": "ENGLISH WAS", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "US", "contactNo": "9974922222", "email": "tony@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "West Hartford", "state": "Connecticut", "postcode": "06110", "country": "US" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US" } ], "additionalInfo": { "applicantDeclaration": "Yes", "applicantDeclarationTimestamp": "2025-09-02 14:03:45" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "US011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ### Request example: in progress with documents required ```json { "region": "US", "businessDetails": { "businessName": "TESSERACT LLC WFWEF", "businessRegistrationNumber": "101402356", "businessType": "LIMITED_LIABILITY_COMPANY", "description": "Limited liability company in US for IT services", "legalDetails": { "registeredCountry": "US", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "223, Grand St.", "addressLine2": "", "city": "New York", "state": "NY", "country": "US", "postcode": "10013" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "MARTHA", "lastName": "ENGLISH REBORN", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "Park Street", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US" } ] } }, { "businessPartner": { "businessName": "CUZEK PRIVATE VENTURES", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "MANUAL_KYC", "firstName": "MARTHA", "lastName": "ENGLISH REBORN", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "US", "contactNo": "9974922222", "email": "tony@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "West Hartford", "state": "Connecticut", "postcode": "06110", "country": "US" }, "additionalInfo": { "applicantDeclaration": "Yes", "applicantDeclarationTimestamp": "2025-09-02 14:03:45" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "US011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` ### Completing applicant eDocVerify The applicant eDocVerify is done via the third-party vendor Onfido. Applicant KYC via Onfido takes place for the EU region when the KYC mode is `E_DOC_VERIFY`. To simulate different success and error responses of the eDocVerify flow, use the following conditions on the applicant's phone number. In all cases, the applicant needs to open the redirect URL in their browser. You either land on the vendor’s page or receive a success/failure redirection back to your KYC redirect URL without any actions needed on the UI. The redirectURL has `isSuccess`, `errorCode`, and `errorMessage` parameters as described in [Applicant KYC](/docs/onboarding/corporate-customers/us-onboarding#applicant-kyc). Based on `businessDetails.applicantDetails.contactDetail.contactNumber`, there are two outcomes: | First two digits of `contactNumber` | Resulting situation | | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Doesn't contain any of the simulated patterns | Onfido's sandbox page is opened and the applicant needs to complete the simulated authentication on the UI. This can be used for end-to-end testing. | | Does contain any of the simulated patterns | The customer's browser redirects to your KYC redirect URL without the need of any actions on the UI. Redirection will contain the following [Redirection parameters](#redirection-parameters) | #### Redirection parameters | Return code | Query parameters in the redirection | | :---------- | :---------------------------------------------------------------------------------- | | 91 | `isSuccess`=`true` ; `errorCode`=;`errorMessage`= | | 41 | `isSuccess = false` ; `errorCode = R403`; `errorMessage = documentAlreadySubmitted` | | 51 | `isSuccess = false` ; `errorCode = I500`; `errorMessage = unexpectedError` | | 61 | `isSuccess = false` ; `errorCode = R408`; `errorMessage = redirectUrlExpired` | ### Request example: in progress with redirectURL ```json { "region": "US", "businessDetails": { "businessName": "TESSERACT LLC WFWEF", "businessRegistrationNumber": "101402356", "businessType": "LIMITED_LIABILITY_COMPANY", "description": "Limited liability company in US for IT services", "legalDetails": { "registeredCountry": "US", "registeredDate": "2021-08-10" }, "addresses": { "registeredAddress": { "addressLine1": "223, Grand St.", "addressLine2": "", "city": "New York", "state": "NY", "country": "US", "postcode": "10013" } }, "stakeholders": [ { "stakeholderDetails": { "kycMode": "E_KYC", "firstName": "MARTHA", "lastName": "ENGLISH REBORN", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "CONTROL_PRONG" } ], "address": { "addressLine1": "Park Street", "city": "Newark", "state": "New Jersey", "country": "US", "postcode": "07071" }, "documentDetails": [ { "documentType": "NATIONAL_ID", "documentNumber": "555456789", "documentIssuanceCountry": "US" } ] } }, { "businessPartner": { "businessName": "CUZEK PRIVATE VENTURES", "businessRegistrationNumber": "987609384", "businessEntityType": "UBO", "sharePercentage": "15", "legalDetails": { "registeredCountry": "US" } } } ], "applicantDetails": { "kycMode": "E_DOC_VERIFY", "firstName": "MARTHA", "lastName": "ENGLISH REBORN", "nationality": "US", "dateOfBirth": "1961-08-11", "professionalDetails": [ { "position": "SIGNATORY" } ], "contactDetails": { "countryCode": "US", "contactNo": "91974922222", "email": "tony@xyz.com" }, "address": { "addressLine1": "Apt X 99, Green Avenue", "city": "West Hartford", "state": "Connecticut", "postcode": "06110", "country": "US" }, "additionalInfo": { "applicantDeclaration": "Yes", "applicantDeclarationTimestamp": "2025-09-02 14:03:45" } }, "additionalInfo": { "isSameBusinessAddress": "Yes" } }, "riskAssessmentInfo": { "totalEmployees": "EM009", "annualTurnover": "US011", "countryOfOperation": [ "DE", "IN" ] }, "expectedAccountUsage": { "debit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "GB", "FR" ] }, "credit": { "monthlyTransactionVolume": "MVUS01", "monthlyTransactions": "ATC01", "averageTransactionValue": "ATVUS02", "topTransactionCountries": [ "IN" ] }, "intendedUses": [ "IU002", "IU003" ], "intendedUsesDescription": "Send money to vendors for export settlement" }, "natureOfBusiness": { "industryCodes": [ "IS002", "IS003" ] }, "tags": [ { "key": "tag1", "value": "tag1value" }, { "key": "tag2", "value": "tag2value" } ] } ``` --- # Individual Customers URL: https://docs.nium.com/docs/onboarding/individual-customers This page describes an older version of corporate customer onboarding that is no longer supported. Visit the Customer Onboarding page for the latest v5 onboarding guide. This page describes an older version of corporate customer onboarding that is no longer supported. Visit the [Customer Onboarding](/docs/onboarding/customer-onboarding) page for the latest v5 onboarding guide. An individual customer is an end-user who holds the balance. In a corporate travel-and-expense (T\&E) use case, this would be a staff member who receives a T\&E card. In a consumer-funded use case, this would be a retail end-customer who has an account. Depending on the nature of the product or program, the know-your-customer (KYC) and the onboarding process differ. Work with your Nium representative to determine the right approach. ## KYC Overview The [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API is used for adding individual customers in the following flow. Individual Customer Onboarding Overview ## Region-Specific KYC Offerings Nium supports automated KYC for most of the regions. | Regulatory region | KYC offerings        | Description | | :---------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | AU | `E_KYC` `MANUAL_KYC` | Automated KYC by the Australian eKYC vendor. Requires manual submission of documents and review by Nium compliance. | | EU | `E_DOC_VERIFY` | Automated document verification by eDocument verification vendor. | | SG | `E_KYC` `E_DOC_VERIFY` `MANUAL_KYC` | Automated KYC for Singapore residents by eKYC vendor. Automated document verification by an eDocument verification vendor. Requires manual submission of documents and review by Nium compliance. | | UK | `E_DOC_VERIFY` | Automated document verification by an eDocument verification vendor. | | US | `E_KYC` | Automated KYC for US nationals by eKYC vendor. | ## Onboarding Customers The following are the steps of the Nium customer onboarding process: - [KYC Overview](#kyc-overview) - [Region-Specific KYC Offerings](#region-specific-kyc-offerings) - [Onboarding Customers](#onboarding-customers) - [Step 1: Create a Customer Account](#step-1-create-a-customer-account) - [Step 2: Submit Account for Compliance Checks](#step-2-submit-account-for-compliance-checks) - [Step 3: Complete Compliance Checks](#step-3-complete-compliance-checks) - [Step 4: Complete RFI Items](#step-4-complete-rfi-items) - [Resubmit Customer Applications](#resubmit-customer-applications) - [Upload Documents](#upload-documents) - [Use Case](#use-case) - [Spend Management](#spend-management) ### Step 1: Create a Customer Account You can create the customer account by providing customer details through the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API. The customer details include the customer’s personal, contact, and KYC details. Some of the details are optional, depending on the defined KYC option. Once you create the customer account, the compliance process begins automatically. ### Step 2: Submit Account for Compliance Checks The customer compliance check involves customer verification, screening, and the KYC process. | Step | Description | | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Screening | Checks whether the customer is part of any of the regulatory blacklists and if Nium can legally do business with the customer. | | KYC | Verifies whether the customer details are accurate. It includes authenticating the customer's identity and address using proof of identity (PoI) and proof of address (PoA). | ### Step 3: Complete Compliance Checks The following table describes the `states` customer accounts go through as they're reviewed by Nium's compliance team and go through the compliance check process. | Compliance status | Description | | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INITIATED` | Compliance is initiated, and the customer needs to take a few more steps to complete the KYC process, such as adding the required information. This status is applicable only for eKYC. | | `IN PROGRESS` | The KYC compliance process is in progress, and the customer has some pending action, such as uploading a document. | | `ACTION REQUIRED` | The customer uploads documents and waits for verification from the compliance team. | | `RFI REQUESTED` | The Nium compliance team raises a request-for-information (RFI) and the customer responds to the RFI through the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | | `COMPLETED` | The compliance process is complete. | | `ERROR` | No action is taken. The customer application fails due to an error. Contact Nium customer support for assistance. | | `EXPIRED` | The submitted document's date expires. The Nium team may raise an RFI. | | `REJECT` | If the compliance team rejects the KYC process, the status changes to `REJECT`. The reinitiate-KYC process is available in this case. | Each action depends upon separate `kycStatus` and `complianceStatus` as detailed in this table: | KYC status | Compliance status | Your next action | APIs involved | Remarks | | ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Pending` | `INITIATED` | Wait for the compliance status callback. | [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | eKYC is initiated. The system updates the status according to the KYC vendor and our screening results. | | `Failed` | `REJECT` | Reinitiate eKYC by providing the same `customerHashId`. | [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) | Check the remarks or the compliance remarks. | | `Pending` | `ERROR` | Email Nium. | [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | Nium's compliance team might need to check the errors manually. | | `Pending` | `ACTION_REQUIRED` | Wait for the next compliance status update. | [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | Nium's compliance team requires a manual check on this request. | | `Pending` | `RFI_REQUESTED` | Check the `rfiDetails` array and provide the requested information through the [Respond To RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. | [Fetch Individual Customer RFI Details](/api#tag/customer-account---individual/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) [Respond To RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) | Nium's compliance team requires additional information to verify the customer. | | `Pending` | `RFI_RESPONDED` | Wait for the next compliance status update. | [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | Nium's compliance team verifies the information in your [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API. Usually, the system updates the compliance status to `ACTION_REQUIRED`. | | `Clear` | `COMPLETED` | Continue your user journey, for example, Add card. | [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | eKYC is successful and the customer is onboarded. | Nium calls the compliance status callback URL to inform you of any change in the compliance status. Then, you need to call the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API to retrieve the detailed information. Within the `complianceStatus`: - `INITIATED` is the first status. - `COMPLETED` is the final status. ### Step 4: Complete RFI Items Refer to [RFI process for individual customers](/docs/onboarding/individual-customers/requests-for-information-rfis). ## Resubmit Customer Applications The onboarding process can be reinitiated if the compliance status is `ERROR` or `REJECTED`. However, applications rejected due to high risk or non-compliance will be blocked from being resubmitted to Nium. Resubmission is still allowed for reasons unrelated to compliance, such as incomplete applications, typos, wrong addresses, etc. For reinitiation, call the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API with the previously generated `customerHashId`. ## Upload Documents When onboarding is initiated with `kycMode = MANUAL_KYC`, then the proof of identity documents are required to be submitted to initiate the KYC process. In addition to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API, Nium offers the [Upload Document](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/uploadDocuments) API which can accept the additional documents in multiple steps. ## Use Case ### Spend Management This is applicable for the use cases where the business expenses made by the employees are funded by a corporation, i.e., their employer. The employees are required to be onboarded in Nium along with their corporate customers. While onboarding employees for spend management use cases, the same [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API is used with minimal information for their identity verification. An *employer letter* alone is sufficient to onboard an employee in Nium. For more information, see [Configure the corporate customer and employee relationship](/docs/getting-started/parent-child-hierarchy#configure-the-corporate-customer-and-employee-relationship). --- # Adding Customers URL: https://docs.nium.com/docs/onboarding/individual-customers/adding-customers The Unified Add Customer API creates a customer with the manual Know Your Customer (KYC) option where most of the parameters are applicable. For other KYC options, fewer parameters are applicable. The [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API creates a customer with the manual Know Your Customer (KYC) option where most of the parameters are applicable. For other KYC options, fewer parameters are applicable. 1. To see an example request, go to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API page. 2. Select an example by clicking anywhere on the word **EXAMPLES** to open the drop-down list of available examples: - Sample for Manual KYC - Sample for Screening only - Sample for e-KYC Adding Customers 3. To make a sample request, go to the [Getting started](/docs/01-Getting%20Started/index.mdx) page. ## Enum values ### `estimatedMonthlyFunding` The `estimatedMonthlyFunding` enum values are as follows: | Code | Description | | :------ | :------------ | | `MF001` | < 1000 | | `MF002` | 1000 – 5000 | | `MF003` | 5000 – 10000 | | `MF004` | 10000 – 20000 | | `MF005` | > 20000 | ### `intendedUseOfAccount` The `intendedUseOfAccount` enum values are as follows: | Code | Description | | :------ | :-------------------------------------------- | | `IU100` | Receiving from/Transfers to accounts I own | | `IU101` | Receiving from/Transfers to friends or family | | `IU102` | Property, goods or services payments | | `IU103` | Education-related payment | | `IU104` | Investments | | `IU105` | Receive or send donations | | `IU106` | Day-to-day spending | | `IU107` | Receiving a salary | | `IU108` | Travel related spending | | `IU109` | Saving | ### `occupation` The `occupation`enum is only applicable for onboarding in Canada. The enum values are as follows: | Code | Description | | :------- | :-------------------------------------------------------------------------------------------------------------- | | `OC0001` | Legislators and senior management | | `OC1001` | Administrative services managers | | `OC1002` | Managers in financial and business services | | `OC1003` | Managers in communication (except broadcasting) | | `OC1110` | Auditors, accountants and investment professionals | | `OC1120` | Human resources and business service professionals | | `OC1201` | Administrative and financial supervisors | | `OC1210` | Administrative and regulatory occupations | | `OC1211` | Court reporters, transcriptionists, records management technicians and statistical officers | | `OC1220` | Accounting, insurance and related business administrative occupations | | `OC1310` | Administrative, property and payroll officers | | `OC1311` | Office administrative assistants - general, legal and medical | | `OC1320` | Transportation and production logistics coordinators and customs and related broker occupations | | `OC1410` | Office support and court services occupations | | `OC1411` | Survey, statistical and data entry occupations | | `OC1420` | Financial, insurance and related administrative support workers | | `OC1430` | Library, correspondence and other clerks | | `OC1440` | Supply chain logistics, tracking and scheduling coordination occupations | | `OC2001` | Managers in engineering, architecture, science and information systems | | `OC2110` | Physical science professionals | | `OC2111` | Life science professionals | | `OC2112` | Public and environmental health and safety professionals | | `OC2120` | Architects, urban planners and land surveyors | | `OC2121` | Mathematicians, statisticians, actuaries and data scientists | | `OC2122` | Computer and information systems professionals | | `OC2123` | Computer, software and Web designers and developers | | `OC2130` | Civil and mechanical engineers | | `OC2131` | Electrical, electronics and computer engineers | | `OC2132` | Manufacturing and processing engineers | | `OC2133` | Natural resources engineers | | `OC2139` | Other engineers | | `OC2210` | Technical occupations in physical sciences | | `OC2211` | Technical occupations in life sciences | | `OC2221` | Technical occupations in architecture, drafting, surveying, geomatics and meteorology | | `OC2222` | Technical occupations in computer and information systems | | `OC2223` | Technical inspectors and regulatory officers | | `OC2230` | Technical occupations in civil, mechanical and industrial engineering | | `OC2231` | Technical occupations in electronics and electrical engineering | | `OC3001` | Managers in health care | | `OC3110` | Physicians and veterinarians | | `OC3111` | Dentists, optometrists and audiologists | | `OC3112` | Pharmacists and dietitians | | `OC3120` | Therapy and assessment professionals | | `OC3130` | Nursing and allied health professionals | | `OC3210` | Technical occupations in therapy and assessment | | `OC3211` | Technical occupations in dental health care | | `OC3212` | Medical technologists and technicians | | `OC3220` | Practitioners of natural healing | | `OC3310` | Assisting occupations in support of health services | | `OC4001` | Managers in public administration | | `OC4002` | Managers in education | | `OC4003` | Managers in social, community and correctional services | | `OC4004` | Managers in public protection services | | `OC4110` | Judges, lawyers and Quebec notaries | | `OC4120` | University professors and post-secondary assistants | | `OC4121` | College and other vocational instructors | | `OC4122` | Secondary, elementary and kindergarten school teachers | | `OC4130` | Social and community service professionals | | `OC4131` | Police investigators and probation officers | | `OC4132` | Educational and employment counsellors | | `OC4140` | Policy and program researchers, consultants and officers | | `OC4210` | Occupations in front-line public protection services | | `OC4220` | Paraprofessional occupations in legal, social, community and education services | | `OC4310` | Assisting occupations in education | | `OC4320` | Assisting occupations in legal and public protection | | `OC4410` | Home care provider occupations | | `OC4420` | Primary combat members of the Canadian Armed Forces | | `OC4510` | Student monitors, crossing guards and related occupations | | `OC5001` | Managers in art, culture, recreation and sport | | `OC5110` | Librarians, archivists, conservators and curators | | `OC5111` | Writing, translating and related communications professionals | | `OC5112` | Creative and performing artists | | `OC5210` | Technical occupations in libraries and public archives | | `OC5211` | Technical occupations in motion pictures, broadcasting and the performing arts | | `OC5212` | Graphic and interior designers | | `OC5310` | Occupations related to museums and art galleries | | `OC5311` | Photographers and support occupations in arts and culture | | `OC5312` | Occupations in creative and performing art | | `OC5320` | Athletes, coaches, referees and related occupations | | `OC5410` | Program leaders and instructors in recreation, sport and fitness | | `OC5510` | Support occupations in art and culture | | `OC6001` | Corporate sales managers | | `OC6002` | Retail and wholesale trade managers | | `OC6003` | Managers in food service and accommodation | | `OC6004` | Managers in customer and personal services | | `OC6201` | Retail sales supervisors | | `OC6202` | Service supervisors | | `OC6210` | Technical sales specialists in wholesale trade and retail and wholesale buyers | | `OC6220` | Specialized occupations in services | | `OC6310` | Insurance, real estate and financial sales occupations | | `OC6320` | Cooks, butchers and bakers | | `OC6321` | Hairstylists and estheticians | | `OC6322` | Shoe repairers, shoemakers and upholsterers | | `OC6410` | Retail salespersons and non-technical wholesale trade sales and account representatives | | `OC6420` | Occupations in personal service | | `OC6430` | Occupations in food and beverage service | | `OC6431` | Occupations in travel and accommodation | | `OC6432` | Tourism and amusement services occupations | | `OC6440` | Customer and information services representatives | | `OC6441` | Security guards and related security service occupations | | `OC6510` | Cashiers and other sales support occupations | | `OC6520` | Food support occupations | | `OC6521` | Support occupations in accommodation, travel, tourism and amusement services | | `OC6522` | Support occupations in personal services | | `OC6531` | Cleaners | | `OC6532` | Service support and related occupations | | `OC7001` | Managers in construction and facility operation and maintenance | | `OC7002` | Managers in transportation and postal and courier services | | `OC7201` | Contractors and supervisors, technical industrial, electrical and construction trades and related workers | | `OC7202` | Contractors and supervisors, technical maintenance trades and heavy equipment and transport operators | | `OC7210` | Machining, metal forming, shaping and erecting trades | | `OC7220` | Technical electrical trades and electrical power line and telecommunications workers | | `OC7230` | Plumbers, pipefitters and gas fitters | | `OC7231` | Carpenters and cabinetmakers | | `OC7232` | Bricklayers and Insulators | | `OC7240` | Machinery and transportation equipment mechanics (except motor vehicles) | | `OC7241` | Automotive service technicians | | `OC7242` | Small engine and equipment mechanics and related repairers (including electrical components) | | `OC7250` | Crane operators and water well drillers | | `OC7260` | Transportation officers and controllers | | `OC7299` | Others technical trades | | `OC7310` | Concrete finishers, tilesetters and plasterers | | `OC7311` | Roofers, glaziers, painters, decorators and floor covering installers | | `OC7320` | Building maintenance installers, servicers and repairers | | `OC7330` | Transport truck and transit drivers | | `OC7331` | Train crew operating occupations | | `OC7340` | Operators, drillers and blasters | | `OC7410` | Mail and message distribution occupations | | `OC7420` | Transport equipment operators, utility maintenance and related maintenance workers | | `OC7510` | Longshore workers and material handlers | | `OC7511` | Trades helpers and labourers | | `OC7520` | Taxi and personal service and delivery service drivers | | `OC7521` | Water and rail transport operators and labourers and related occupations | | `OC8001` | Managers in natural resources production and fishing | | `OC8002` | Managers in agriculture, horticulture and aquaculture | | `OC8201` | Supervisors, logging and forestry | | `OC8202` | Contractors and supervisors, mining, oil and gas | | `OC8203` | Contractors and supervisors, agriculture, horticulture and related operations and services | | `OC8310` | Underground miners, oil and gas drillers and related occupations | | `OC8311` | Logging machinery operators | | `OC8312` | Fishing vessel masters and fishermen/women | | `OC8410` | Mine service workers and operators in oil and gas drilling | | `OC8411` | Logging and forestry workers | | `OC8412` | Workers in agriculture and fishing occupations | | `OC8510` | Agriculture, horticulture and harvesting labourers and related occupations | | `OC8511` | Mine and oil and gas drilling, services and related labourers | | `OC8512` | Logging, forestry, landscaping and other related labourers | | `OC9001` | Managers in manufacturing and utilities | | `OC9201` | Supervisors, processing and manufacturing occupations | | `OC9202` | Supervisors, assembly and fabrication | | `OC9210` | Utilities equipment operators and controllers | | `OC9310` | Central control and process operators in processing and manufacturing | | `OC9320` | Aircraft assemblers and aircraft assembly inspectors | | `OC9410` | Machine operators and related workers in mineral and metal products processing and manufacturing | | `OC9411` | Machine operators and related workers in chemical, plastic and rubber processing | | `OC9412` | Machine operators and related workers in pulp and paper production and wood processing and manufacturing | | `OC9413` | Machine operators and related workers in textile, fabric, fur and leather products processing and manufacturing | | `OC9414` | Machine operators and related workers in food, beverage and associated products processing | | `OC9415` | Printing equipment operators and related occupations | | `OC9420` | Mechanical, electrical and electronics assemblers and inspectors | | `OC9421` | Furniture, wood, plastic and other products assemblers, finishers and inspectors | | `OC9510` | Labourers in processing, manufacturing and utilities | --- # Customer Lifecycle URL: https://docs.nium.com/docs/onboarding/individual-customers/customer-lifecycle This article details the requests and tools clients have available to manage customers. ## Nium API The following table details the requests available to manage customers: | Stage | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Update a customer | The [Customer Update](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/updateCustomer) API can update a customer's information at any time after the onboarding. If `complianceStatus = COMPLETED`, you can update only the customer `email` and `mobile` fields. If `complianceStatus` is any other value, any customer information can be updated. **Note:** Per the Strong Customer Authentication (SCA) requirement, `authenticationCode` needs to be passed in the API within the EU and UK regions. | | Get a customer's details | The [Customer Details](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API gets the detail information of the customer at any time. The `status` field shows the status of the customer in the Nium platform. The `complianceStatus` field shows the status of the compliance check for the customer. | | Get a list of customers | The [Customer List](/api#tag/customer-management/GET/api/v3/client/{clientHashId}/customers) API gets a list of customers under you, which can be further filtered based on query parameters such as email address, mobile number, etc. | | Block/Unblock a customer | The [Block/Unblock Customer](/api#tag/customer-management/PUT/api/v1/client/{clientHashId}/customer/{customerHashId}/block) API enables you to block or unblock a customer's account from processing any further activity. | ## Customer Lifecycle When a customer passes KYC checks and gets approved by Nium, the `customer#status` updates to **Clear**. As your business needs change and customers come and go, you may need to suspend or block customers. Use the [Block/Unblock Customer](/api#tag/customer-management/PUT/api/v1/client/{clientHashId}/customer/{customerHashId}/block) request to help manage customers. As you manage `customers` the `status` updates from **Clear** depending on the action you're performing. The following table details the different `statuses` a `customer` can change to after getting approved in Nium. The different states of customers, as documented in the `status` column, can be reviewed using the [Customer List V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customers) request. | Action | Description | Block/Unblock Customer - `action` | `status` | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------- | | Suspend a customer’s account | Customer accounts can be suspended by you or Nium’s Compliance team at any time. | **TEMPORARY\_BLOCK** | **Suspended** | | Unsuspend a customer’s account | Customer accounts can be unsuspended by you or Nium’s Compliance team at any time. | **UNBLOCK** | **Clear** | | Close a customer’s account | • Customer accounts can be closed by you or Nium’s Compliance team at any time. \n• This is a permanent change and status. Once closed, the customer’s information can be resubmitted to create a new `customer`. \n• A new `customerHashId` will be assigned to the customer. | **PERMANENT\_BLOCK** | **Blocked** | | Terminate a customer's account | • Customer accounts can be terminated by Nium’s Compliance team at any point of time due to fraudulent/ prohibited activities. \n• Account termination is a terminal state and can only be performed by Nium's compliance team. \n• Once terminated, the same customer’s information can't be used to create a `customer` and won't be accepted by Nium. | Not applicable | **Blocked** | ### Suspend Customer Account Call the [Block/Unblock Customer](/api#tag/customer-management/PUT/api/v1/client/{clientHashId}/customer/{customerHashId}/block) API with the `TEMPORARY_BLOCK` parameter, include one of the following in as the `reason`: - `CLIENT_REQUEST` - `CUSTOMER_REQUEST` - `POTENTIAL_SANCTION` - `SUSPICIOUS_ACTIVITY` Example of a failed message response where the provided reason is not included in the above list: ```json { "status": "BAD_REQUEST", "message": "Invalid Reason Provided", "errors": [ "Reason is not valid to Temporarily Block Customer" ] } ``` Example of a successful message response: ```json { "status": "OK", "message": "Customer has been Blocked Temporarily", "errors": [] } ``` ### Close Customer Account Customer accounts can be closed by you or Nium's compliance team at any time. Closing a customer's account is permanent, so if you suspect fraudulent or suspicious activity, [suspend the account](#suspend-customer-account) and contact your Nium account manager or [Nium Support](ailto:support@nium.com) to review the customer's activity and block the account if necessary. If you want to proceed with permanently closing a customer's account, call the [Block/Unblock Customer](/api#tag/customer-management/PUT/api/v1/client/{clientHashId}/customer/{customerHashId}/block) API with the `PERMANENT_BLOCK` parameter and include one of the following in the `reason` parameter: - `UNRESPONSIVE_CUSTOMER` - `CUSTOMER_REQUEST` - `DECEASED` - `DORMANCY` - `OTHER` Any existing balances will be refunded by Nium's operations team. If you have any questions about refunds, please contact your Nium account manager or [Nium Support](ailto:support@nium.com). To reopen a closed account, the customer must go through the onboarding process again and resubmit their information. Customers can resubmit their application and go through the eKYC process again using the: - [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/corporate) request for corporate customers. - [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) request for individual customers. ### Unblock Customer Account A customer can be unblocked, but only in two scenarios: - *You* can unblock only if you request the temporary block. - *Nium* can unblock only if Nium requests the temporary block. When calling the [Block/Unblock Customer](/api#tag/customer-management/PUT/api/v1/client/{clientHashId}/customer/{customerHashId}/block) API with the `UNBLOCK` parameter, include one of the following in the `reason` parameter: - `CLIENT_REQUEST` - `CUSTOMER_REQUEST` ## Tags Nium offers the option to pass customized information via tags in the Unified Add Customer API and the Onboard Corporate Customer API. This feature is applicable for individual and corporate customers, and you can update or delete the tags. For details, see the [Manage Customer Tags](/api#tag/customer-management/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/tags) API. ## Notifications via Callback URL Any change in the compliance lifecycle will be notified to you by a callback URL, configured at your system. For details, see [Callback to receive customer-compliance status](/docs/developers/notifications-and-webhooks/callbacks/customer-compliance-status). ## Rejected Customer Sign up When a customer is rejected, the process is as follows: 1. Continue from any Add customer flow, where `status=PENDING` and `complianceStatus=ACTION_REQUIRED`. 2. Nium compliance sends a callback request for the `complianceStatus` with `customerHashId`. 3. Send a response with the HTTPS status code `200`. 4. Collect and send your customer's details in a `GET` request to the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API with the `customerHashId`. 5. Nium compliance is unable to process the customer onboarding and rejects the customer. Nium compliance updates the compliance status from `ACTION_REQUIRED` to `REJECT` . 6. Nium sends a response with the following: - `kycStatus=FAILED` - `complianceStatus=REJECT` - `remarks` - `complianceRemarks` 7. Tell the customer that the KYC failed and offer an option to reinstate KYC. 8. Send a `POST` request to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API with corrected information and the *existing* `customerHashId`. 9. Nium returns: - `customerDetails` - `complianceStatus=COMPLETED` - `kycStatus=CLEAR` ## Terms and Conditions Sign up --- # Request for Information (RFIs) URL: https://docs.nium.com/docs/onboarding/individual-customers/requests-for-information-rfis When the Nium compliance team finds insufficient information, it takes the following actions: 1. Initiates the RFI and the customer's compliance status becomes `RFI REQUESTED`. 2. The client receives a nudge during the compliance status callback URL; that is, the next time they call the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API, they get the status as `RFI REQUESTED`.\ **NOTE:** The Customer Details API is now the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API. 3. You need to call the [Fetch Individual Customer RFI Details](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/updateCustomer) API to fetch the RFI information requested. There can be multiple RFI templates in the response. 4. You call the [Respond To RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API and provides the requested information. 5. The compliance status changes to `RFI RESPONDED`. 6. The compliance team reviews the information and takes the necessary action. ## RFI requested RFI Requested When an RFI is requested, the process is as follows: 1. This continues from the Add customer process where `status = PENDING` and `complianceStatus = ACTION_REQUIRED`. Nium compliance sends a Request For Information (RFI) and updates the `complianceStatus` from `ACTION_REQUIRED` to `RFI_REQUESTED`. 2. Nium sends a callback request for the change in the`complianceStatus` with the `customerHashId`. 3. Send a response with the HTTPS status code `200`. 4. Send a GET request to the [Fetch Individual Customer RFI Details](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/updateCustomer)API. 5. Nium sends a response with the following: - `rfiDetails` object - `kycStatus=PENDING` - `complianceStatus=RFI_REQUESTED` 6. Request more information from your customer based on the `rfiDetails` array of objects. 7. Send a `POST` request to the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) API with your customer's information. 8. Nium returns a success confirmation upon receipt with the `complianceId` and `complianceStatus=RFI_RESPONDED`. 9. Nium compliance checks the RFI documents, updates the compliance status to `COMPLETED` and sends a callback request for the `complianceStatus` with `customerHashId`. 10. Send a response with the HTTPS status code `200`. 11. Collect and send your customer's details in a `GET` request to the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API with the `customerHashId`. 12. Nium returns: - `customerDetails` - `complianceStatus=COMPLETED` - `kycStatus=CLEAR` --- # Frequently Asked Questions URL: https://docs.nium.com/docs/onboarding/individual-customers/faqs Are customers required to accept Nium's Terms and Conditions before submitting their onboarding request? Yes, it is required before submitting the onboarding request. Can I tag my customers with my business specific information for easy tracking and reporting? Yes, it's possible. Send the information as a key-value pair to tag your customer as detailed Manage customer tags . Can multiple customers be onboarded with the same email ID or mobile number? No. Depending on the configuration during the client set up, the platform accepts customers who have either: A unique email ID and mobile number A unique email ID How to know if my customer has been onboarded successfully and ready to transact? You get a callback from Nium after the compliance check status is `COMPLETED`. Check if the value of the `status` field is `Clear` by making a `GET` request to the Customer Detail V2 API. How to know my next step after receiving the callback from Nium? Refer to The next step for all possible values of compliance `status`. How to make sure no financial transaction is allowed for a former customer? You need to block your customer so that his or her account is deactivated in Nium. Is it possible to onboard individual customers residing in any country? No. Nium doesn’t support onboarding in blacklisted countries as per Nium policy. Please contact your Nium representative for region-specific guidance as per Nium policy. Is it possible to resubmit the onboarding request in case of any error or rejection in the onboarding process? Yes, it is possible to reinitiate the onboarding process with Nium. Call the Unified Add Customer API and include the customerHashId that you received in the API response of your previous request. For details, see Request example for reinitiation. Why am I not receiving any callback from Nium? Check if you have: Configured the callback URL. Updated the callback URL as part of your set up with Nium. Configured your firewall to allow Nium to send to your configured URL. Why was the onboarding request rejected by Nium? We run KYC and screening checks as part of our onboarding process. The possible reasons of rejection could be: The person is found in one of the sanctioned lists. The customer got a high score in risk assessment. The KYC vendor is unable to validate an individual’s identity automatically. Compliance raising an RFI for them, but they are not able to prove their identity. When I get the compliance status ERROR, what should I do? Check the remarks field in the response of the GET call to the Customer Detail V2 API to understand the cause of the error. You can also contact your Nium customer support for more clarification. ### KYC Which KYC models are supported by Nium? Automated KYC models as per our regional guidelines in different geographies. Manual KYC is supported in exceptional cases as a fallback option to the automated KYC verification. In Manual KYC, can I upload the KYC documents later? Such as after calling the onboarding API? Yes, it is possible to upload the KYC documents separately as part of the Upload Document API. What's the difference between compliance status and KYC status? Compliance status indicates various stages of the compliance review process in Nium. KYC status indicates overall status of the KYC and all relevant checks as part of the onboarding process. Use the status field of a GET call to the Customer Detail V2 API to know about the overall KYC status as that is more relevant to you. What's the maximum size of the KYC documents allowed in the API request? 10 MB is the maximum size of the KYC documents allowed in the API request. ### RFI How do I know which information is being requested in an RFI? Refer to the array of objects requiredData in the Fetch Individual Customer RFI Details API. The type field indicates the type of the RFI: data or document. The value field indicates the field to be used while responding to the Respond to RFI API. How does Nium inform clients when an RFI is raised for a customer? You receive a nudge with the customerHashId to the URL configured with Nium for receiving a callback. Check the complianceStatus field in the response of the GET call to the Customer Detail V2 API. The value of complianceStatus is set as RFI\_REQUESTED in this case. How does Nium inform clients when an RFI is completed successfully? You receive a nudge with the customerHashId to the URL configured with Nium for receiving a callback. Check the complianceStatus field in the response of the GET call to the Customer Detail V2 API. The value of complianceStatus is set as COMPLETED in this case. Is it possible to respond to multiple RFIs separately? Yes, if you have received multiple RFIs, then it's possible to respond to multiple RFIs separately by calling the Respond to RFI API multiple times. ## EU and UK ### KYC What actions are expected from the customer in eDocument verification process by Nium? Request your customer to follow the steps as guided by the eDocument verification vendor. Your customers are expected to complete the verification process from their mobile. They are expected to scan and submit the copy of their identity document and complete the biometric verification by uploading a selfie in the form. If their image is blurred, they are requested to rescan or retake the selfie before submission. If the automated verification fails after submission by the customer, what happens? If the automated verification fails, then the onboarding request is reviewed by the Nium Compliance team. Nium's Compliance team may raise an RFI to get more clarification from the Customer. Why am I getting an error post successful verification of my customer? What is the next step? Check if you have configured the *eKYC redirect URL* during the client set up process with Nium. Your customer is redirected back to this URL once the verification process is completed. Why do you need to collect PEP, tax details, and birth country of my EU customers? Customer’s PEP, tax details, and birth country are required for regulatory reporting purposes to the EU regulation authority. As a licensed holder in the EU, Nium is obligated to fulfill the regulatory requirement. Why should I pass the authentication code while updating customer information in the EU and UK? As per the PSD2 SCA guidelines, it's a mandatory requirement to authenticate any update operation on customer information for the EU and UK regulatory regions. As a licensed holder, Nium is obligated to fulfill this regulatory requirement. ### Redirect URL Is there an expiration time for the redirect URL? Yes, the redirect URL remains active for 60 minutes and expires after that. What should I do if the redirect URL is expired? You need to reinitiate the onboarding process so that the redirect URL is regenerated. Why am I getting an error while rendering the redirection URL? What should I do? The redirected URL is expired due to timeout. You need to reinitiate the onboarding process so that the redirect URL is regenerated. --- # AU Onboarding URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-au This page contains details about the Australian Know Your Customer (KYC) flows and links to the following sub-pages for quick reference: | Page name           | Description | | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | | **[AU required parameters](/docs/onboarding/individual-customers/onboarding-au/required-parameters)** | This page lists the required API fields for onboarding an individual customer. | | **[AU required documents](/docs/onboarding/individual-customers/onboarding-au/required-documents)** | This page contains tables listing the required documents for verification of an individual customer. | | **[AU request examples](/docs/onboarding/individual-customers/onboarding-au/example-requests)** | This page contains API request examples for onboarding an individual customer in the AU regulatory region. | ### eKYC – AU When using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API to add a customer in Australia, the customer should undergo `E_KYC` verification. eKYC AU Onboarding In Australia, the add customer eKYC process is: 1. Your new customer signs up for verification. 2. Send a `GET` request to the [Terms and Conditions](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) API. 3. Nium returns the Terms and Conditions (T\&C) description. 4. Display the Terms and Conditions to your customer for them to agree to and accept. You collect all customer information for onboarding. 5. Send a `POST` request to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API as per the AG required parameters. 6. Nium initiates the eKYC process by connecting to GreenID and conducts screening and sanction checks. After completion, Nium updates the compliance status to either `COMPLETED`, `ERROR`, or `REJECT`. 7. Nium sends a callback request for the `complianceStatus` with the `customerHashId`. 8. Send a response with the HTTPS status code `200`. 9. Collect and send your customer's details in a `GET` request to the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API with the `customerHashId`. 10. Nium returns the `customerDetails` object, the `complianceStatus` field, and the `kycStatus` field. ### Manual KYC – AU When using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API with compliance option as `MANUAL_KYC` to add a customer in Australia, the following verification process is performed. Manual KYC --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-au/required-parameters The API fields shown on this page are relevant to the AU regulatory region only. To see the full payload, refer to the Unified Add Customer API Reference. The API fields shown on this page are relevant to the AU regulatory region only. To see the full payload, refer to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API Reference. ## Required Parameters The following table is used for customer onboarding in the AU. | Field Name | Description | Required | | | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | --- | | `firstName` | This field contains the first name of the customer. The maximum character limit is 40. | Yes | | | | `middleName` | This field contains the middle name of the customer. The maximum character limit is 40. | No | | | | `lastName` | This field contains the last name of the customer. The maximum character limit is 40. | Yes | | | | `nationality` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the customer's citizenship. | Yes | | | | `complianceLevel` | This field contains the compliance level for the customer. It is useful when the client has multiple compliance setups. The possible values are `SCREENING` and `SCREENING_KYC`. | No | | | | `countryCode` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country prefix code to the customer's mobile number. | Yes | | | | `mobile` | This field contains the mobile number of the customer without the country prefix code. The maximum character limit is 20 and can contain only numerals. | Yes | | | | `email` | This field contains the email address of the customer which must not already be in the system. The maximum character limit is 60. | Yes | | | | `gender` | This field can accept only one of the following values: `Male`, `Female`, `Others`. | No | | | | `employeeId` | This field accepts the employee ID of the customer in case of spend management use case. | No | | | | `dateOfBirth` | This field contains the customer's date of birth in `YYYY-MM-DD` format. Customers need to be at least 18 years old. For any special use cases, discuss with your Nium account manager. | Yes | | | | `kycMode` | This field can accept `E_KYC` or `MANUAL_KYC` for AU customers. | Yes | | | | `billingAddress1` | This field accepts line 1 of the customer’s billing address. It should match the address on the document being uploaded. The format of this field is \*\*StreetNumber | StreetName | Suburb\*\*. Maximum character limit: 40. | Yes | | `billingAddress2` | This field contains the second line of the customer's billing address. The maximum character limit is 40. | No | | | | `billingCity` | This field contains the city of the customer’s billing address. The maximum character limit is 20. Note: City is mandatory if Apple Pay feature is offered to the Customer. | No | | | | `billingLandmark` | This field contains the landmark for the customer’s billing address. The maximum character limit is 40. | No | | | | `billingState` | This field contains the state of the customer's billing address. The maximum character limit is 30. | Yes | | | | `billingZipCode` | This field contains the ZIP code of the customer’s billing address. The maximum alphanumeric character limit is 10. | Yes | | | | `billingCountry` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country of the customer's billing address. | Yes | | | | `deviceInfo` | This field contains the OS of the device used by the customer for initiating the request. | No | | | | `ipAddress` | This field contains the IP address of the device used by the customer for initiating the request. | No | | | | `countryIP` | This field contains the country IP address for the device by the customer for initiating the request. | No | | | | `sessionId` | This field contains the session ID of the customer's session that is initiating the request. | No | | | | `segment` | This field contains the fee segment associated with a client. The maximum character limit is 64. | No | | | | [identificationDoc](#identificationdoc-object) | This array of objects contains identification documents. The maximum size of this array is 10 MB. | Yes | | | | `additionalInfo` | This field contains additional information. | No | | | | [tags](#tags-object) | This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | No | | | ### `identificationDoc` object This array of objects contains identification documents. | Field name | Description | Required | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `identificationType` | This field accepts the name of the document type being uploaded. This field can accept only one of the following values: \n`PASSPORT`, \n`DRIVING_LICENSE`, \n`MEDICARE_CARD`. | Yes | | `identificationValue` | This field contains the unique document identifier. | Yes | | `identificationDocIssuanceCountry` | This field accepts the country of the issuance for the document being uploaded. | No | | `identificationDocIssuanceState` | This field accepts the issuance state for the document. The acceptable values for states for AU region: \n`ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` \n Note: This field is applicable only if the identificationType is DRIVING\_LICENSE. | No | | `identificationDocReferenceNumber` | This field accepts the reference number for the document being uploaded. It is mandatory for medicare card and driver's license. \nNote: The driver's license card number must be passed only if the identificationType is DRIVING\_LICENSE. | No | | `identificationDocExpiry` | This field accepts the expiry date of the document being uploaded. It is mandatory for passport and medicare card. \nIf the value of identificationDocColor is G, then the acceptable format of expiry date is **YYYY-MM.** \nIf the value of identificationDocColor is B or Y, then the acceptable format of expiry date is **YYYY-MM-DD.** | No | | `identificationDocColor` | This field accepts the color of the medicare card which may be one of three values - G, B, Y. **It is mandatory for medicare card.** | No | | `[identificationDocument](#identificationdocument-object)` | This array accepts objects of the identification document file. **At least one file is mandatory for the Manual KYC mode.** | No | #### `identificationDocument` object This array of objects contains identification documents. This object is needed only if `kycMode` is `MANUAL_KYC` The maximum size of this array is 10 MB. | Field Name | Description | Required | | :--------- | :---------------------------------------------------------------------------------------------------------- | :------- | | document | This field contains the base64 encoded document being uploaded. | Yes | | fileName | This field contains the name of the file being uploaded. | Yes | | fileType | This field contains the type of the file being uploaded. The supported file types are: `JPG`, `PNG`, `PDF` | Yes | ### `tags` object This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | Field name | Description | Required | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `key` | This field contains the name of the tag. The maximum character limit is 128. **Note:** This field is required if the `value` field is provided in the request. | Yes \* | | `value` | This field contains the value of the tag. The maximum character limit is 256. **Note:** This field is required if the `key` field is provided in the request. | Yes \* | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-au/required-documents eKYC ### eKYC The following table lists which information is required for each identification document type, when onboarding customers using eKYC. | Identification document item | PASSPORT | DRIVING\_LICENSE | MEDICARE\_CARD | | :-------------------------------------- | :------- | :--------------- | :------------- | | `identificationValue` | Yes | Yes | Yes | | `identificationDocumentIssuanceCountry` | Yes | | | | `identificationDocumentExpirationDate` | Yes | | Yes | | `identificationDocIssuanceState` | | Yes | | | `identificationDocumentIssuanceDate` | Yes | | Yes | | `identificationDocReferenceNumber` | | Yes | | | `identificationDocColor` | | | Yes | ### Manual KYC In Manual KYC mode, along with the document details mentioned above, the base 64 file of the ID documents should be uploaded using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) request or the [Upload Document](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/uploadDocuments) request. Allowed document types include: - **PASSPORT** - **DRIVING\_LICENSE** - **MEDICARE\_CARD** --- # Example Requests URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-au/example-requests To onboard individual customers, use the Unified Add Customer request. To onboard individual customers, use the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) request. For an example call that you can customize with your information, see: - [Request example for `E_KYC`](#request-example-e-kyc) - [Request example for `MANUAL_KYC`](#request-example-manual-kyc) ## Request example for `E_KYC` The following is an example of a request that uses **E\_KYC** for `kycMode` to onboard a customer. ```json { "nationality": "AU", "kycMode": "E_KYC", "complianceLevel": "SCREENING_KYC", "countryCode": "AU", "addressLine1": "2numbernumbernumbernumber|name", "postcode": "4313", "email": "api_auto_101140554@yopmail.com", "mobile": "107555762", "billingAddress1": "2numbernumbernumbernumber|name", "billingState": "Queensland", "billingZipCode": "4213", "billingCountry": "AU", "billingCity":"asd", "addressCountry":"AU", "city":"city", "state": "Queensland", "dateOfBirth": "1990-12-18", "taxDetails": [ { "countryOfResidence": "FR", "taxIdNumber": "FR123456" } ], "identificationDoc": [ { "identificationType": "PASSPORT", "identificationDocColor": "G", "identificationValue": "0432125561", "identificationDocReferenceNumber": "1", "identificationDocHolderName": "Amin Prayag Uttarkar", "identificationDocExpiry": "2026-08-10", "identificationDocIssuanceCountry": "AU" } ] } ``` ## Request example for `MANUAL_KYC` The following is an example of request that uses **MANUAL\_KYC** for `kycMode` to onboard a customer. ```json { "firstName": "Sam", "lastName": "John", "email": "sam@xyz.com", "nationality": "IN", "countryCode": "SG", "mobile": "12345678", "dateOfBirth": "1995-05-24", "kycMode": "MANUAL_KYC", "billingAddress1": "123 Long Street", "billingAddress2": "Great Lake", "billingCity": "Mumbai", "billingZipCode": "00185", "billingCountry": "IN", "identificationDoc": [ { "identificationType": "PASSPORT", "identificationValue": "P12345", "identificationDocIssuanceCountry": "IN", "identificationDocExpiry": "04/05/2026", "identificationDocument": [ { "fileName": "passport-front.jpg", "fileType": "image/jpeg", "document": "<>" }, { "fileName": "passport-back.jpg", "fileType": "image/jpeg", "document": "<>" } ] } ] } ``` --- # CA Onboarding URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-ca This page contains information and links to guides about onboarding individual Canadian customers and the related Know Your Customer (KYC) flows: | Page name | Description | | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | | **[CA required parameters](/docs/onboarding/individual-customers/onboarding-ca/required-parameters)** | Fields required API fields for onboarding an individual customer. | | **[CA required documents](/docs/onboarding/individual-customers/onboarding-ca/required-documents)** | This page contains tables listing the required documents for verification of an individual customer. | | **[CA request examples](/docs/onboarding/individual-customers/onboarding-ca/example-requests)** | This page contains API request examples for onboarding an individual customer in the CA regulatory region. | Please note, in compliance with regulations from the Financial Transactions and Reports Analysis Centre of Canada (also known as FINTRAC), individuals with a billing address in Quebec cannot be onboarded onto the Nium platform. ## eKYC – CA Use the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) request to add a Candian customer. Be sure to use`E_KYC` to verify the customer. eKYC CA Onboarding To add an individual Candian customer using eKYC process: 1. Have the customer sign up for verification. 2. Send a `GET` request to the [Terms and Conditions](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) API. 3. Nium returns the Terms and Conditions description. 4. Display the Terms and Conditions to your customer to agree and accept. You collect all customer information for onboarding. 5. Send a `POST` request to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API as per [CA required parameters](/docs/onboarding/individual-customers/onboarding-ca/required-parameters) 6. Nium sends a CUSTOMER\_COMPLIANCE\_STATUS webhook with `complianceStatus`. 7. Send a response with the HTTPS status code `200`. --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-ca/required-parameters The page details the fields that are required to onboard individual Canadian customers. To review the request in it's entirety, see the Unified Add Customer request. The page details the fields that are required to onboard individual Canadian customers. To review the request in it's entirety, see the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) request. ## Required Parameters The following table details the fields required to onboard individual customers in Canada. | Field Name | Description | Required | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `firstName` | This field contains the first name of the customer. The maximum character limit is 40. | Yes | | `middleName` | This field contains the middle name of the customer. The maximum character limit is 40. | No | | `lastName` | This field contains the last name of the customer. The maximum character limit is 40. | Yes | | `nationality` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the customer's citizenship. | Yes | | `complianceLevel` | This field contains the compliance level for the customer. It is useful when the client has multiple compliance setups. The possible values are `SCREENING` and `SCREENING_KYC`. | No | | `countryCode` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country prefix code to the customer's mobile number. | Yes | | `mobile` | This field contains the mobile number of the customer without the country prefix code. The maximum character limit is 20 and can contain only numerals. | Yes | | `email` | This field contains the email address of the customer which must not already be in the system. The maximum character limit is 60. | Yes | | `dateOfBirth` | This field contains the customer's date of birth in `YYYY-MM-DD` format. Customers need to be at least 18 years old. For any special use cases, discuss with your Nium account manager. | Yes | | `kycMode` | This field can accept only `E_KYC` for CA customers. | Yes | | `billingAddress1` | This field contains the first line of the customer’s billing address. The maximum character limit is 40. | Yes | | `billingAddress2` | This field contains the second line of the customer's billing address. The maximum character limit is 40. | No | | `billingCity` | This field contains the city of the customer’s billing address. The maximum character limit is 20. | Yes | | `billingLandmark` | This field contains the landmark for the customer’s billing address. The maximum character limit is 40. | No | | `billingState` | This field contains the state of the customer's billing address. The maximum character limit is 30. | Yes | | `billingZipCode` | This field contains the ZIP code of the customer’s billing address. The maximum alphanumeric character limit is 10. | Yes | | `billingCountry` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country of the customer's billing address. | Yes | | `deviceInfo` | This field contains the OS of the device used by the customer for initiating the request. | No | | `occupation` | This field contains the identification type for the document being uploaded for KYC. Use [Fetch Corporate Constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) for valid values. | Yes | | `ipAddress` | This field contains the IP address of the device used by the customer for initiating the request. | No | | `countryIP` | This field contains the country IP address for the device by the customer for initiating the request. | No | | `sessionId` | This field contains the session ID of the customer's session that is initiating the request. | No | | `segment` | This field contains the fee segment associated with a client. The maximum character limit is 64. | No | | [identificationDoc](#identificationdoc-object) | This array of objects contains identification documents. The maximum size of this array is 10 MB. | Yes | | `additionalInfo` | This field contains additional information. | No | | [tags](#tags-object) | This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | No | ### `identificationDoc` object This array of objects contains identification documents. The maximum size of this array is 10 MB. | Field name | Description | Required | | --------------------- | ----------------------------------------------------------------- | -------- | | `identificationType` | This field contains the name of the document type being uploaded. | Yes | | `identificationValue` | This field contains the unique document identifier. | Yes | ### `tags` object This object contains the user-defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | Field name | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `key` | This field contains the name of the tag. The maximum character limit is 128. **Note:** This field is required if the `value` field is provided in the request. | Yes \* | | `value` | This field contains the value of the tag. The maximum character limit is 256. **Note:** This field is required if the `key` field is provided in the request. | Yes \* | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-ca/required-documents Document submission ## Document submission Only Canadian residents are supported as individual customers in the Canadian regulatory region. --- # Example Requests URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-ca/example-requests To onboard your individual customer, you can call the Unified Add Customer API. To onboard your individual customer, you can call the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API. For an example call that you can customize with your information, see below. - [Request example for onboarding](#request-example-onboarding) ## Request example for onboarding The following is an API request example call for customer onboarding for the first time. ```json { "firstName": "Peter", "lastName": "Parker", "email": "peter@xyz.com", "nationality": "FR", "complianceLevel": "SCREENING_KYC", "countryCode": "FR", "mobile": 123456789, "dateOfBirth": "1992-12-18", "kycMode": "E_DOC_VERIFY", "billingAddress1": "Long Street", "billingCity": "Paris", "billingZipCode": "76140", "billingCountry": "FR", "taxDetails":[ { "countryOfResidence":"FR", "taxIdNumber":"FR123456" }, { "countryOfResidence":"ES", "taxIdNumber":"ES267392" } ], "pep":true, "countryOfBirth":"DE", "verificationConsent": true, "intendedUseOfAccount": "Day-to-day spending", "estimatedMonthlyFundingCurrency": "EUR", "estimatedMonthlyFunding": "1000-5000", "internationalPaymentsSupported": true, "expectedCountriesToSendReceiveFrom": [ "SG", "ES" ] } ``` --- # EU Onboarding URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-eu This page contains details about the European Union Know Your Customer (KYC) flows and links to the following sub-pages for quick reference: | Page name           | Description | | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | | **[EU required parameters](/docs/onboarding/individual-customers/onboarding-eu/required-parameters)** | This page lists the required API fields for onboarding an individual customer. | | **[EU required documents](/docs/onboarding/individual-customers/onboarding-eu/required-documents)** | This page contains tables listing the required documents for verification of an individual customer. | | **[EU request examples](/docs/onboarding/individual-customers/onboarding-eu/example-requests)** | This page contains API request examples for onboarding an individual customer in the UK regulatory region. | ## Exception handling for redirection flow As a response to the Unified Add Customer API, Nium returns a redirect URL. You need to redirect the customer to the redirect URL. After the customer completes the KYC verification, they are redirected back to your eKYC redirect URL that was configured with Nium. The following parameters will be returned as part of the eKYC redirect URL to help you to understand the status of the customer’s verification in the vendor’s UI. - `errorCode ` - `errorMessage` - `isSuccess` – This field indicates whether the customer completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. This information helps you to design and implement the next steps in your application, i.e., you may decide to show the success or error message to the customer as per the scenarios listed below. | Scenario | Expected action from client | Query parameters in the redirection | | ---------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | The customer completed the required steps in the vendor’s UI. | You receive a callback from Nium. | `errorCode`: N/A \n \n`errorMessage`: N/A \n \n`isSuccess`: true | | The document has already been submitted in the vendor's UI. | KYC process is complete. You receive a callback from Nium. | `errorCode`: R403 \n \n`errorMessage`: documentAlreadySubmitted \n \n`isSuccess`: FALSE | | The customer has provided incorrect data in the vendor's UI. | Ask your customer to submit correct data in the vendor's page. | `errorCode`: I400 \n \n`errorMessage`: vendorValidationError \n \n`isSuccess`: FALSE | | Verification failure at the vendor. | The application is sent for manual review. | `errorCode`: R401 \n \n`errorMessage`: vendorVerificationFailure \n \n`isSuccess`: FALSE | | Internal server error at Nium. | Ask your customer to try after some time or reach out to Nium support. | `errorCode`: R500 \n \n`errorMessage`: internalServerError \n \n`isSuccess`: FALSE | | Any unexpected error from the vendor. | Ask your customer to try after some time or reach out to Nium support. | `errorCode`: I500 \n \n`errorMessage`: unexpectedError \n \n`isSuccess`: FALSE | | Validation already completed and customer retries the same link. | KYC process is complete. You receive a callback from Nium. | `errorCode`: R606 \n \n`errorMessage`: verificationAlreadyCompleted \n \n`isSuccess`: TRUE | ### Example of a redirect to the client in a successful case `https://www.nium.com/?customerHashId=773bcf1f-7e91-459b-a03a-75c87005145f&errorCode=&errorMessage=&isSuccess=true` ### Example of a redirect to the client in an unsuccessful case `https://www.nium.com/?customerHashId=590ec98a-ab6a-4da1-8dc7-35cc1c98d236&errorCode=R408&errorMessage=redirectURLExpired&isSuccess=false` ## eDocVerify – EU When using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API to add a customer in the European Union, eDocument verification is performed. eDocVerify EU In the EU, the add customer eDocVerify process is as follows: 1. Your new customer signs up for verification. 2. Send a `GET` request to the [Terms and Conditions](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) API. 3. Nium returns the Terms and Conditions description. 4. Display the Terms and Conditions to your customer to agree and accept. You collect all customer information for onboarding. 5. Send a `POST` request to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API as per the [EU required parameters](/docs/onboarding/individual-customers/onboarding-eu/required-parameters) 6. Nium returns the `redirectURL` and other parameters which you inform your customer. 7. Direct your customer for verification and complete the identity verification by uploading the identity document and a live selfie in the form presented. Then wait for a callback from Nium.\ **Caution:** The redirect URL expires in 60 minutes. 8. After the verification process completes, your customer is redirected back to the eKYC redirect URL that is configured during the client setup. 9. Nium sends a CUSTOMER\_COMPLIANCE\_STATUS webhook with `complianceStatus` . 10. Send a response with the HTTPS status code `200`. 11. Customer onboarding can be reinitiated if the compliance status is `IN_PROGRESS`, `REJECT`, or `ERROR`. --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-eu/required-parameters The API fields shown on this page are relevant to the EU regulatory region only. To see the full payload, refer to the Unified Add Customer API Reference. The API fields shown on this page are relevant to the EU regulatory region only. To see the full payload, refer to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API Reference. ## Required Parameters The following table is used for customer onboarding in the EU where the KYC mode is `E_DOC_VERIFY`. | Field name | Description | Required | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `firstName` | This field contains the first name of the customer. The maximum character limit is 40. | Yes | | `middleName` | This field contains the middle name of the customer. The maximum character limit is 40. | No | | `lastName` | This field contains the last name of the customer. The maximum character limit is 40. | Yes | | `nationality` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the customer's citizenship. | Yes | | `complianceLevel` | This field contains the compliance level for the customer. It is useful when the client has multiple compliance setups. The possible values are `SCREENING` and `SCREENING_KYC`. | No | | `countryCode` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country prefix code to the customer's mobile number. | Yes | | `mobile` | This field contains the mobile number of the customer without the country prefix code. The maximum character limit is 20 and can contain only numerals. | Yes | | `email` | This field contains the email address of the customer which must not already be in the system. The maximum character limit is 60. | Yes | | `dateOfBirth` | This field contains the customer's date of birth in `YYYY-MM-DD` format. Customers need to be at least 18 years old. For any special use cases, discuss with your Nium account manager. | Yes | | `kycMode` | This field can accept only `E_DOC_VERIFY` for EU customers. | Yes | | `billingAddress1` | This field contains the first line of the customer’s billing address. The maximum character limit is 40. | Yes | | `billingAddress2` | This field contains the second line of the customer's billing address. The maximum character limit is 40. | No | | `billingCity` | This field contains the city of the customer’s billing address. The maximum character limit is 20. | Yes | | `billingLandmark` | This field contains the landmark for the customer’s billing address. The maximum character limit is 40. | No | | `billingState` | This field contains the state of the customer's billing address. The maximum character limit is 30. | No | | `billingZipCode` | This field contains the postcode of the customer’s billing address. The maximum alphanumeric character limit is 10. | Yes | | `billingCountry` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country of the customer's billing address. | Yes | | `deviceInfo` | This field contains the OS of the device used by the customer for initiating the request. | No | | `ipAddress` | This field contains the IP address of the device used by the customer for initiating the request. | No | | `countryIP` | This field contains the country IP address for the device by the customer for initiating the request. | No | | `sessionId` | This field contains the session ID of the customer's session that is initiating the request. | No | | `segment` | This field contains the fee segment associated with a client. The maximum character limit is 64. | No | | [taxDetails](#taxdetails) | This array accepts the tax details of EU customers. | Yes | | `pep` | This field specifies if the customer is a Politically Exposed Person (PEP) or not. | Yes | | `countryOfBirth` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the customer's country of birth. | Yes | | `verificationConsent` | This field specifies if the electronic verification consent to process customer data for compliance is required or not. | Yes | | [additionalInfo](#additionalInfo-object) | This array of objects contains additional information. | No | | `intendedUseOfAccount` | This field contains the customer’s intended use of their account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Yes | | `estimatedMonthlyFundingCurrency` | This field contains the [3-letter ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) in which estimated monthly funding is expected in the wallet. | Yes | | `estimatedMonthlyFunding` | This field contains the estimated monthly funding amount expected in the wallet. **Note:** This field is required when the `estimatedMonthlyFundingCurrency` field is provided in the request. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Yes | | `internationalPaymentsSupported` | This field specifies if the customer will be doing International send/receive/card payments. The default value is `false`. | Yes | | `expectedCountriesToSendReceiveFrom` | This array contains the 2-letter [ISO Alpha-2 country codes](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) that the client expects their international payment to be spent in, sent to, or received from. **Note:** This field is required when the `internationalPaymentsSupported` field is `true`. | Yes | | [tags](#tags-object) | This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | No | ### `additionalDetails` object This array accepts the additional details of EU customers. The first key-value pair cannot be changed. \* If the customer is a citizen of Lithuania, then this object is required. | Field name | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `key` | This field contains the string `identificationType`. | Yes \* | | `value` | This field contains the string `PersonalIdentificationNumber`. | Yes \* | | `key` | This field contains the string `identificationValue`. | Yes \* | | `value` | If the customer is Lithuanian, this field contains their 11-digit personal identification number. **Note:** This field is used only for Lithuanian citizens. | Yes \* | ### `taxDetails` object This array accepts the tax details of EU customers. | Field name | Description | Required | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `countryOfResidence` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the customer's country of residence. | Yes | | `taxIdNumber` | This field contains the tax ID number of the customer. | Yes | ### `tags` object This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | Field name | Description | Required | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `key` | This field contains the name of the tag. The maximum character limit is 128. **Note:** This field is required if the `value` field is provided in the request. | Yes \* | | `value` | This field contains the value of the tag. The maximum character limit is 256. **Note:** This field is required if the `key` field is provided in the request. | Yes \* | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-eu/required-documents Document submission ## Document submission Nium's eKYC verification process is based on verifying the name, Date of birth, and Address of the individual across various sources such as government records and credit agencies. Hence, for Canadian customers. no document submission is needed. However, `identificationType`, `identificationValue` fields are required when creating Payouts. Since the identity verification is an eDocument verification method, no document submission is required in the API. Live Selfie with Passport or National ID is submitted in the form presented by the eDocument verification vendor. The customer needs to follow the instructions provided by the eDocument verification vendor to complete the identity verification process. For details of the eDocument verification process flow, refer to the [eDocVerify in the EU](/docs/onboarding/individual-customers/onboarding-eu) section. The following table lists the applicable document based on the customer's citizenship. | Type | Non-Lithuanian and non-EU citizens | EU citizens | | :---------------------- | :--------------------------------- | :---------------------- | | Identification document | Passport | National ID or passport | --- # Example Requests URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-eu/example-requests To onboard your individual customer, submit a request to the Unified Add Customer endpoint. To onboard your individual customer, submit a request to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) endpoint. See the following for an example of a Unified Add Customer request that onboards an individual Candian customer. #### Request example ```json { "parentCustomerHashId": "a4bc9c48-2080-49d2-b429-a8baaa73d17a", "firstName": "Piyush", "lastName": "Hatwalne", "email": "piyush@nium.com", "nationality": "CA", "countryCode": "CA", "mobile": 7199982787, "dateOfBirth": "1995-10-14", "kycMode": "E_KYC", "occupation": "OC1210", "countryOfBirth": "DE", "billingCountry": "CA", "billingAddress1": "Unit no 23", "billingCity": "Toronto", "billingZipCode": "m1m1m1", "billingState": "BC", "identificationDoc": [ { "identificationType": "PASSPORT", "identificationValue": "98422222299", "identificationDocExpiry": "2030-11-11" } ] } ``` --- # SG Onboarding URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-sg This page contains details about the different Singapore Know Your Customer (KYC) flows. See the following links for other pages related to onboarding: | Page name           | Description | | :------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | | **[SG required parameters](/docs/onboarding/individual-customers/onboarding-sg/required-parameters)** | This page lists the required API fields for onboarding an individual customer. | | **[SG required documents](/docs/onboarding/individual-customers/onboarding-sg/required-documents)** | This page contains tables listing the required documents for verification of an individual customer. | | **[SG request examples](/docs/onboarding/individual-customers/onboarding-sg/example-requests)** | This page contains API request examples for onboarding an individual customer in the SG regulatory region. | | **[SG PSA Compliance for wallet-based programs](/docs/onboarding/individual-customers/onboarding-sg/wallets-in-sg)** | This page details the SG Payment Services Act (PSA) Compliance on wallet-based programs. | ## eKYC – Singapore (SG) When using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API to add a customer in Singapore, eKYC verification is performed. eKYC - Singapore In Singapore, the add customer eKYC process is as follows: 1. Your new customer signs up for verification. 2. send a `GET` request to the [Terms and Conditions](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) API. 3. Nium returns the Terms and Conditions description. 4. Display the Terms and Conditions to your customer to agree and accept. You collect all customer information for onboarding. 5. Send a `POST` request to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API as per the [SG required parameters](/docs/onboarding/individual-customers/onboarding-sg/required-parameters). 6. Nium returns the redirectURL which you inform your customer. 7. Direct your customer for completing the verification with the vendor. 8. After the verification process completes, your customer is redirected back to the eKYC redirect URL that is configured during the client setup. 9. Nium sends a CUSTOMER\_COMPLIANCE\_STATUS webhook with `complianceStatus` . 10. Send a response with the HTTPS status code `200`. 11. Customer onboarding can be reinitiated if the compliance status is `IN_PROGRESS`, `REJECT`, or `ERROR`. ## eDoc verification - Non-SG When onboarding residents outside of Singapore, use `E_DOC_VERIFY` as the KYC mode. The eDoc Verify flow is similar to the eKYC flow, with the primary difference being the URL returned by Nium originates from our address verification vendor - Onfido. Customers outside of Singapore will need to upload a selfie and a valid identity document during onboarding. After completing these steps, they will be redirected to your callback URL. ### Proof of address verification If proof of address verification is required, the eDoc Verify flow changes based on the customer's country. The onboarding flow changes based on the `billingAddress.country` since our address verification vendor, Onfido, doesn't support all countries. > To ensure the correct templates are set for your account, include a list of countries where you plan to onboard customers during your onboarding with Nium. Based on the country the customer is located in, the eDoc verification flows available include: #### Supported countries If the customer's country appears in the **Singapore - eDoc verification - Supported Countries** list, pass \`kycMode\`\` as **E\_DOC\_VERIFY**. The customer's flow remains the same as the default eDoc verification flow. - The redirect link returned will include an additional step for collecting the address verification document. - The Onfido link will prompt the customer to upload their address verification document. See the following for a full list of countries supported by our address verification vendor: Singapore - eDoc Verification - Supported Countries | Country | Country Code | | ------------------------ | ------------ | | Andorra | AD | | Algeria | DZ | | Argentina | AR | | Australia | AU | | Austria | AT | | Belgium | BE | | Bermuda | BM | | Brazil | BR | | British Virgin Islands | VG | | Bulgaria | BG | | Canada | CA | | Cayman Islands | KY | | Chile | CL | | Colombia | CO | | Costa Rica | CR | | Croatia | HR | | Czech Republic | CZ | | Denmark | DK | | Dominican Republic | DO | | Ecuador | EC | | Estonia | EE | | Ethiopia | ET | | Finland | FI | | France | FR | | Germany | DE | | Ghana | GH | | Gibraltar | GI | | Guatemala | GT | | Hong Kong | HK | | Hungary | HU | | Iceland | IS | | Indonesia | ID | | Ireland | IE | | Isle of Man | IM | | Italy | IT | | Ivory Coast | CI | | Jamaica | JM | | Jersey | JE | | Kenya | KE | | Kuwait | KW | | Latvia | LV | | Liechtenstein | LI | | Lithuania | LT | | Luxembourg | LU | | Malaysia | MY | | Malta | MT | | Mexico | MX | | Monaco | MC | | Netherlands | NL | | New Zealand | NZ | | Nigeria | NG | | Norway | NO | | Panama | PA | | Peru | PE | | Philippines | PH | | Poland | PL | | Portugal | PT | | Romania | RO | | San Marino | SM | | Saudi Arabia | SA | | Senegal | SN | | Serbia | RS | | Singapore | SG | | Slovakia | SK | | Slovenia | SI | | South Africa | ZA | | South Korea | KR | | Spain | ES | | Sweden | SE | | Switzerland | CH | | Taiwan | TW | | Tanzania | TZ | | Turkey | TR | | Uganda | UG | | Ukraine | UA | | United Arab Emirates | AE | | United Kingdom | GB | | United States of America | US | | Vietnam | VN | #### Unsupported countries For countries not supported by our vendor, collect the address verification documents manually. Pass kycMode as **E\_DOC\_VERIFY** - the URL returned by Nium will ask the customer to perform selfie and ID verification, but not address verification. Upload the address document using the `identificationDoc` object in the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer), or the [Upload Document](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/uploadDocuments) request. The application status will remain **in\_progres**s until the document is submitted. Our compliance team will manually verify the document once it is submitted. Please note, Auto-approval of the customer is not possible for customers in unsupported countries. ## Manual KYC – Singapore (SG) When using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API with compliance option as `MANUAL_KYC` to add a customer in Singapore, the following verification process is performed. Manual KYC - SG ## Exception handling As a response to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API with KYC Mode `E_KYC`, Nium returns a redirect URL. You need to redirect the customer to the redirect URL. After the customer completes the KYC verification, they are redirected back to your eKYC redirect URL that was configured with Nium. The following parameters will be returned as part of the eKYC redirect URL to help you to understand the status of the customer’s verification in the vendor’s UI. - `errorCode` - `errorMessage` - `isSuccess` – This field indicates whether the customer completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. This information helps you to design and implement the next steps in your application. For example, you may decide to show the success or error message to the customer as per the scenarios listed below. | Scenario | Expected action | Query parameters in the redirection | | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | The customer completes the required steps in the vendor’s UI. | You receive a callback from Nium. | `errorCode`: N/A \n \n`errorMessage`: N/A \n \n`isSuccess`: `true` | | The customer has provided incorrect data in the vendor's UI and has *not* clicked **Accept** in the vendor's page. | Ask customer to submit correct data in the vendor's page. | `errorCode`: `I400` \n \n`errorMessage`: `vendorValidationError` \n \n`isSuccess`: `false` | | Any unexpected error from the vendor. | Try after some time or reach out to Nium's support. | `errorCode`: `I500` \n \n`errorMessage`: `unexpectedError` \n \n`isSuccess`: `false` | --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-sg/required-parameters The API fields shown on this page are relevant to the SG regulatory region only. To see the full payload, refer to the Unified Add Customer API Reference. The API fields shown on this page are relevant to the SG regulatory region only. To see the full payload, refer to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API Reference. ## Required Parameters The following table list which parameters are required for each KYC mode. | Field Name | Description | eKYC | eDocVerify | Manual KYC | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------- | ------------ | | `firstName` | This field contains the first name of the customer. The maximum limit is 40 characters. | N/A | Required | Required | | `middleName` | This field contains the middle name of the customer. The maximum limit is 40 characters. | N/A | Optional | Optional | | `lastName` | This field contains the last name of the customer. The maximum limit is 40 characters. | N/A | Required | Required | | `nativeLanguageName` | The field contains the customer's name in their native language. If the customer's name is mentioned in their native language in their identity document, then this information should be provided for ease of verification. The maximum limit is 40 characters or 20 double-byte characters. | N/A | Optional | Optional | | `nationality` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the customer's citizenship. | N/A | Required | Required | | `complianceLevel` | This field contains the compliance level for the customer. It is useful when the client has multiple compliance setups. The possible values are `SCREENING` and `SCREENING_KYC`. | Optional | Optional | Optional | | `countryCode` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country prefix code to the customer's mobile number. | Required | Required | Required | | `mobile` | This field contains the mobile number of the customer without the country prefix code. The maximum character limit is 20 and can contain only numerals. | Required | Required | Required | | `email` | This field contains the email address of the customer which must not already be in the system. The maximum character limit is 60. | Required | Required | Required | | `dateOfBirth` | This field contains the customer's date of birth in `YYYY-MM-DD` format. Customers need to be at least 18 years old. For any special use cases, discuss with your Nium account manager. | N/A | Required | Required | | `kycMode` | This field contains the KYC mode used during verification. | `E_KYC` | `E_DOC_VERIFY` | `MANUAL_KYC` | | `billingAddress1` | This field contains the first line of the customer’s billing address. The maximum character limit is 40. | N/A | Required | Required | | `billingAddress2` | This field contains the second line of the customer's billing address. The maximum character limit is 40. | N/A | Optional | Optional | | `billingCity` | This field contains the city of the customer’s billing address. The maximum character limit is 20. | N/A | Required | Required | | `billingLandmark` | This field contains the landmark for the customer’s billing address. The maximum character limit is 40. | N/A | Optional | Optional | | `billingState` | This field contains the state of the customer's billing address. The maximum character limit is 30. | N/A | Optional | Optional | | `billingZipCode` | This field contains the postcode of the customer’s billing address. For UK, specify the postcode value in the following `SW4 6EH` format. The maximum alphanumeric character limit is 10. | N/A | Required | Required | | `billingCountry` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country of the customer's billing address. | N/A | Required | Required | | `deviceInfo` | This field contains the OS of the device used by the customer for initiating the request. | Optional | Optional | Optional | | `ipAddress` | This field contains the IP address of the device used by the customer for initiating the request. | Optional | Optional | Optional | | `countryIP` | This field contains the country IP address for the device by the customer for initiating the request. | Optional | Optional | Optional | | `sessionId` | This field contains the session ID of the customer's session that is initiating the request. | Optional | Optional | Optional | | `segment` | This field contains the fee segment associated with a client. The maximum character limit is 64. | Optional | Optional | Optional | | `identificationDoc` | This field contains an array which contains identification documents. The maximum array size is 10 MB. | N/A | N/A | Required | | `identificationType` | This field contains the identification type for the document being uploaded for KYC. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | N/A | N/A | Required | | `identificationValue` | This field contains the identification value. **Note:** [Required depending on the identification document type](/docs/onboarding/individual-customers/onboarding-sg/required-documents#field-document-requirement-matrix). | N/A | N/A | Required \* | | `identificationIssuingDate` | This field contains the identification document issuing date. **Note:** [Required depending on the identification document type](/docs/onboarding/individual-customers/onboarding-sg/required-documents#field-document-requirement-matrix). | N/A | N/A | Required \* | | `identificationDocExpiry` | This field contains the identification document expiration date. **Note:** [Required depending on the identification document type](/docs/onboarding/individual-customers/onboarding-sg/required-documents#field-document-requirement-matrix). | N/A | N/A | Required \* | | `identificationDocIssuanceCountry` | This field contains the country that issued the identification document. **Note:** [Required depending on the identification document type](/docs/onboarding/individual-customers/onboarding-sg/required-documents#field-document-requirement-matrix). | N/A | N/A | Required \* | | `identificationDocument` | This field contains the document saved as a base64 encoded string. | N/A | N/A | Required | | `fileName` | This field contains the name of the file being uploaded. | N/A | N/A | Required | | `fileType` | This field contains the type of the file being uploaded. The supported file types are: `JPG` `PNG` `PDF`. | N/A | N/A | Required | | `document` | This field contains the base64 encoded document being uploaded. | N/A | N/A | Required | | `verificationConsent` | This field specifies if the electronic verification consent to process customer data for compliance is required or not. | N/A | Required | N/A | | `additionalInfo` | This field contains additional information. | Optional | Optional | Optional | | `tags` | This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | Optional | Optional | Optional | ### `tags` object This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | Field name | Description | Required | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `key` | This field contains the name of the tag. The maximum limit is 128 characters. **Note:** This field is required if the `value` field is provided in the request. | Yes \* | | `value` | This field contains the value of the tag. The maximum limit is 256 characters. **Note:** This field is required if the `key` field is provided in the request. | Yes \* | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-sg/required-documents Document submission ## Document submission ### eKYC (SG residents) For Singapore residents, no document information is required from the customer. ### eDocVerify (Non-SG residents) For non-Singapore residents, a Live Selfie with Passport or National ID needs to be submitted in the form presented by the eDocument verification vendor. ### Manual KYC Both residents and non-residents of Singapore need to present proof-of-identity and proof-of-address documents for the verification process. These can be one of the following: | Proof of identity | Proof of address | | :------------------------------------------------------------------------------------ | :-------------------------------------------------------- | | FIN National ID NRIC Passport The document needs to have the customer's face on it. | National ID Bank statement Government letter Utility bill | ## Field-document requirement matrix The following table lists which information is required for each identification document type. All identification document's front and back are required, except government letters, bank statements, and utility bills. | Identification document item | Bank statement | FIN | Government letter | National ID | NRIC | Passport | Utility bill | | :-------------------------------------- | :------------- | :-- | :---------------- | :---------- | :--- | :------- | :----------- | | `identificationDocumentNumber` | | Yes | | Yes | Yes | Yes | | | `identificationDocumentIssuanceCountry` | Yes | Yes | | Yes | Yes | Yes | | | `identificationDocumentExpirationDate` | | Yes | Yes | | | Yes | | | `identificationDocumentIssuanceDate` | Yes | | Yes | | | | Yes | --- # Example Requests URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-sg/example-requests Use the Unified Add Customer request to onboard an individual customer. Use the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) request to onboard an individual customer. For an example call that you can customize with your information, see the following examples: - [Request example for `E_KYC`](#request-example-e-kyc) - [Request example for `E_DOC_VERIFY`](#request-example-e-doc-verify) - [Request example for `MANUAL_KYC`](#request-example-manual-kyc) - [Request example for `E_DOC_VERIFY` with unsupported countries](#request-example-for-e_doc_verify-with-unsupported-countries) ## Request example for `E_KYC` The following is an example of a request where the KYC mode is `E_KYC`. ```json { "email": "peter.parker@xyz.com", "countryCode": "SG", "mobile": "12345678", "kycMode": "E_KYC" } ``` ## Request example for `E_DOC_VERIFY` The following is an example of a request where the KYC mode is `E_DOC_VERIFY`. ```json { "firstName": "Peter", "lastName": "Parker", "email": "peter.parker@xyz.com", "nationality": "IN", "countryCode": "SG", "mobile": "12345678", "dateOfBirth": "1992-12-18", "kycMode": "E_DOC_VERIFY", "billingAddress1": "123 Long Street", "billingAddress2": "Great Lake", "billingCity": "Mumbai", "billingZipCode": "400011", "billingCountry": "IN", "verificationConsent": true } ``` ## Request example for `MANUAL_KYC` The following is an example of a request where the KYC mode is `MANUAL_KYC`. ```json { "firstName": "Sam", "lastName": "John", "email": "sam@xyz.com", "nationality": "IN", "countryCode": "SG", "mobile": "12345678", "dateOfBirth": "1995-05-24", "kycMode": "MANUAL_KYC", "billingAddress1": "123 Long Street", "billingAddress2": "Great Lake", "billingCity": "Mumbai", "billingZipCode": "00185", "billingCountry": "IN", "identificationDoc": [ { "identificationType": "PASSPORT", "identificationValue": "P12345", "identificationDocIssuanceCountry": "IN", "identificationDocExpiry": "04/05/2026", "identificationDocument": [ { "fileName": "passport-front.jpg", "fileType": "image/jpeg", "document": "<>" }, { "fileName": "passport-back.jpg", "fileType": "image/jpeg", "document": "<>" } ] } ] } ``` ## Request example for `E_DOC_VERIFY` with unsupported countries The following is an example of a request where the KYC mode is `E_DOC_VERIFY`and address verification details must be collected manually. This request is used when the country of residence isn't supported by our adress verification vendor. For more information, see [SG Oboarding](#proof-of-address-verification). ```json { "firstName": "Sam", "lastName": "John", "email": "sam@xyz.com", "nationality": "IN", "countryCode": "SG", "mobile": "12345678", "dateOfBirth": "1995-05-24", "kycMode": "E_DOC_VERIFY", "billingAddress1": "123 Long Street", "billingAddress2": "Great Lake", "billingCity": "Mumbai", "billingZipCode": "00185", "billingCountry": "IN", "identificationDoc": [ { "identificationType": "PASSPORT", "identificationValue": "P12345", "identificationDocIssuanceCountry": "IN", "identificationDocExpiry": "04/05/2026", "identificationDocument": [ { "fileName": "passport-front.jpg", "fileType": "image/jpeg", "document": "<>" }, { "fileName": "passport-back.jpg", "fileType": "image/jpeg", "document": "<>" } ] } ] } ``` --- # Wallets in SG URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-sg/wallets-in-sg Payment Services Act (PSA) scope ## Payment Services Act (PSA) scope ### PSA definition Any wallet-based program, contracted in Singapore, regardless of wallet funding source, as long as it is cardholder entitled – meaning the cardholder has the freedom to choose how the funds residing in the wallet are being spent – is subjected to PSA compliance. The legislation applies to all Singapore Residents: - Singapore Citizen - Singapore Permanent Resident - Holder of a valid Employment Pass issued by the authorities in Singapore If you are unsure whether your e-wallet program is subjected to PSA compliance, reach out to your respective Nium representatives for more information. ## System-level limits In compliance with PSA, Nium implements measures where Nium-issued Singapore-based e-wallets can hold the following maximums: | S$ maximum | Timeframe | Wallets | Referred to as | | :--------- | :------------ | :------------------------- | :----------------------------- | | S$5,000 | At any time | Per wallet | Wallet balance limit Stock cap | | S$30,000 | Calendar year | Total across all e-wallets | Annual load limit Flow cap | These system-level limits apply to all Singapore residents holding a PSA-compliant e-wallet issued by Nium. ## Client-level limits In addition to the system-level *wallet balance limit* and *annual loading limit*, Nium's e-wallet program lets you set any [client-level limits](/docs/fees-and-limits/limits) according to your risk tolerance. ### When lower than system limits If your configured *wallet balance limit* or *annual loading limit* is lower than the system-level limits, then your configured limit or limits apply to *all* of your customers. For example, If your configured *annual loading limit* is S$25,000 (while the system level limit is S$30,000), then the S$25,000 *annual loading limit* takes precedence for all of your customers. ### When higher than system limits If your configured *wallet balance limit* or *annual loading limit* is higher than the system-level limits, then your configured limit or limits apply to only non-Singapore resident e-wallet customers while system-level limits still apply to Singapore Resident e-wallet customers. For example, If your configured *wallet balance limit* is S$8,000 and *annual loading limit* is S$45,000, then these limits apply to non-Singapore Resident e-wallet customers. Singapore Resident e-wallet customers are bound by system-level limits of S$5,000 and S$30,000 respectively. ## Unique Customer ID (UCI) Unique Customer refers to the single individual customer who may hold one or more e-wallets with Nium Singapore. Each unique customer under a PSA-compliant e-wallet program is assigned a Unique Customer ID (UCI). When a customer is onboarded via the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API onto PSA-compliant e-wallet programs, Nium One attempts to match the newly onboarded customer against Nium One’s existing customer base by using the following customer data: - Identification Type (`identificationValue`) - National ID (NRIC) - Foreign Identification Number (FIN) - SingPass ID - Passport Number - Full customer Name - First name (given name) - Middle name - Last Name (family name) - Date of Birth - Nationality If Nium One is able to find a match against an existing customer from another e-wallet program, the newly onboarded customer is assigned the same UCI as the existing customer. Otherwise, a new UCI is assigned to the newly onboarded customer. ### Identifying unique customers To identify unique customers across PSA clients, ensure the `UCI` flag is enabled. Then, when a customer is onboarded via the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API, the following checks are performed: 1. Is `billingAddressCountry = SG`? - If No, onboard the customer without UCI. - If Yes, refer to #2. 2. Does their [identificationValue](#identificationvalue) exist in the system? - If Yes, retrieve the UCI from the existing customer record and assign that UCI to the current onboarded customer. - If No, refer to #3. 3. Does an existing customer record match *all three* of the following characteristics? | Characteristic | | --------------------------------------------------------------------------------------------------------------------------- | | The *First name* and the *Last name* both exist in any of the three name fields: `firstName`, `middleName`, and `LastName`. | | Date of Birth (DOB) | | Nationality | - If yes, retrieve the UCI from the existing customer record and assign that UCI to the current onboarded customer. - If no, generate and assign new UCI to onboarded customer. ### When billing country is updated via RFI When a customer's KYC expires and their billing country is updated through an RFI, the following happens in different scenarios. Scenario 1 – Cardholder moves *out of* Singapore: - Cardholder's residency status updates to non-resident. - Cardholder's UCI value is removed. Scenario 2 – Cardholder moves *into* Singapore - Cardholder's residency status updates to resident. - Cardholder's UCI value is generated as per the current generation logic. ## Limit calculation mechanism ### Default balance limit The default balance limit – legally called *stock cap* – is the maximum total wallet balance that a customer under the same UCI can hold at any point of time. This limit is currently set at SGD5,000 as per the regulation. This means that customer’s maximum total wallet balance at any point of time cannot go beyond SGD5,000. #### Multicurrency wallet handling While calculating the EOD balance limit, balances in multicurrency wallets are included. Balances from non-SGD wallets are included in the balance calculation by converting their value to the SGD equivalent value. However, no physical conversion of currencies between the wallets takes place at that point until the actual refund is carried out. ### Annual loading limit The *annual loading limit* is also called the *flow cap*. The flow cap of S$30,000 legally refers to the cardholder's spending limit. Due to this system limitation, you can only limit the cardholder's funding limit since a cardholder can load only S$30,000 and cannot spend more than S$30,000. The annual loading limit has a starting balance of S$30,000 at the system level or a lower limit at the client level. #### Transactions that reduce annual loading limit The following transactions reduce the annual loading limit, making it closer to 0. When this limit reaches 0, your customer can no longer load any credits to the wallet. | Transaction type | Description | | :------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Cashback_Credit` | Cashback transaction. | | `Customer_Wallet_Credit_Fund_Transfer` | The funds received in the wallet from another customer's wallet of the same client. | | `Fee_Reversal` | Fee reversed in an online reversal. If online reversal is triggered, the corresponding fees applied on transaction are released or reversed. | | `Fee_Waiver` | Fee waiver transaction. | | `Incremental_Auth_Reversal` | Reversal for incremental auth transactions. | | `Original_Credit` | Received incoming Original Credit Transfer (OCT) and credited to the wallet linked to the cardholder's card. | | `Partial_Reversal` | Online partial reversal of a transaction. | | `Reversal` | Online reversal of a transaction. | | `Reversal_Advice` | Reversal initiated when a timeout scenario happens. If Visa or MasterCard time-out the transaction, they generate a *reversal advice* to roll back the transaction. In the case of Wallet Clients, Nium applies the reversal advice and provides the credit back to the customer. In the case of RHA clients, Nium reverses funds on your prefund account and forwards the reversal advice to the RHA client for crediting funds back to the customer. | | `Settlement_Credit` | The difference in amount during transaction and settlement to be credited to the cardholder. The settlement amount is less than transaction amount. | | `Settlement_Direct_Reversal` | Offline reversal unlinked to any original debit transaction. | | `Settlement_Reversal` | Offline reversal of original debit transaction. | | `Wallet_Credit_Mode_Card` | The fund credit to a wallet using a card. | | `Wallet_Credit_Mode_Offline` | The fund credit to a wallet using an offline mode, such as a bank transfer, from the customer's own account. | | `Wallet_Credit_Mode_Offline_Cross_Currency` | The cross-currency fund credit to a wallet using an offline mode, such as a bank transfer, from the customer's own account. | | `Wallet_Credit_Mode_Offline_ThirdParty` | The fund credit to wallet, in the same currency, using an offline mode, such as a bank transfer, from a third party. | | `Wallet_Credit_Mode_Prefund` | The fund credit to a wallet using a client prefund. | | `Wallet_Credit_Mode_Prefund_Cross_Currency` | The cross-currency fund credit to a wallet using a client prefund. | **NOTE:** There is no transaction type that would increase the remaining *available annual inflow*, also called the *annual load limit*. ## Limit configurations ### PSA limit configurations Both the default balance limit and annual limit are not visible on the Nium One Platform and can be changed only by the technical team whenever there’s a change in the regulatory limit. This configuration is internal to Nium and is applied by default for customers under client programs with `assignUniqueCustomerId = true`. ### Client-level limit configurations You may configure different *wallet balance limit* and *annual limit* amounts for their wallet program which are not PSA related. If the client program has `assignUniqueCustomerId = true`, these limits apply to non-SG residents; whereas SG residents are subject to the PSA default balance limit and annual limit amounts, whichever is lower. --- # UK Onboarding URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-uk This page contains details about the United Kingdom Know Your Customer (KYC) flows and links to the following sub-pages for quick reference: | Page name | Description | | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | | **[UK required parameters](/docs/onboarding/individual-customers/onboarding-uk/required-parameters)** | This page lists the required API fields for onboarding an individual customer. | | **[UK required documents](/docs/onboarding/individual-customers/onboarding-uk/required-documents)** | This page contains tables listing the required documents for verification of an individual customer. | | **[UK request examples](/docs/onboarding/individual-customers/onboarding-uk/example-requests)** | This page contains API request examples for onboarding an individual customer in the UK regulatory region. | ## eDocVerify – UK When using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API to add a customer in the United Kingdom, eDocument verification is performed. eDocVerify - UK In the UK, the add customer eDocVerify process is as follows: 1. Your new customer signs up for verification. 2. Send a `GET` request to the [Terms and Conditions](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) API. 3. Nium returns the Terms and Conditions description. 4. Display the Terms and Conditions to your customer to agree and accept. You collect all customer information for onboarding. 5. Send a `POST` request to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API as per the [UK required parameters](/docs/onboarding/individual-customers/onboarding-uk/required-parameters) 6. Nium returns the `redirectURL` and other parameters which you inform your customer. 7. Direct your customer for verification and complete the identity verification by uploading the identity document and a live selfie in the form. Then wait for a callback from Nium.\ **Caution:** The redirect URL expires in 60 minutes. 8. After the verification process completes, your customer is redirected back to the eKYC redirect URL that is configured during the client setup. 9. Nium sends a CUSTOMER\_COMPLIANCE\_STATUS webhook with `complianceStatus` . 10. Send a response with the HTTPS status code `200`. 11. Customer onboarding can be reinitiated if the compliance status is `IN_PROGRESS`, `REJECT`, or `ERROR`. ## Exception handling for redirection flow As a response to the Unified Add Customer API, Nium returns a redirect URL. You need to redirect the customer to the redirect URL. After the customer completes the KYC verification, they are redirected back to your eKYC redirect URL that was configured with Nium. The following parameters will be returned as part of the eKYC redirect URL to help you to understand the status of the customer’s verification in the vendor’s UI. - `errorCode ` - `errorMessage` - `isSuccess` – This field indicates whether the customer completed the required steps in the vendor’s UI. It doesn't mean KYC is successful. This information helps you to design and implement the next steps in your application, i.e., you may decide to show the success or error message to the customer as per the scenarios listed below. | Scenario | Expected action from client | Query parameters in the redirection | | ---------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | The customer completed the required steps in the vendor’s UI. | You receive a callback from Nium. | `errorCode`: N/A \n \n`errorMessage`: N/A \n \n`isSuccess`: true | | The document has already been submitted in the vendor's UI. | KYC process is complete. You receive a callback from Nium. | `errorCode`: R403 \n \n`errorMessage`: documentAlreadySubmitted \n \n`isSuccess`: FALSE | | The customer has provided incorrect data in the vendor's UI. | Ask your customer to submit correct data in the vendor's page. | `errorCode`: I400 \n \n`errorMessage`: vendorValidationError \n \n`isSuccess`: FALSE | | Verification failure at the vendor. | The application is sent for manual review. | `errorCode`: R401 \n \n`errorMessage`: vendorVerificationFailure \n \n`isSuccess`: FALSE | | Internal server error at Nium. | Ask your customer to try after some time or reach out to Nium support. | `errorCode`: R500 \n \n`errorMessage`: internalServerError \n \n`isSuccess`: FALSE | | Any unexpected error from the vendor. | Ask your customer to try after some time or reach out to Nium support. | `errorCode`: I500 \n \n`errorMessage`: unexpectedError \n \n`isSuccess`: FALSE | | Validation already completed and customer retries the same link. | KYC process is complete. You receive a callback from Nium. | `errorCode`: R606 \n \n`errorMessage`: verificationAlreadyCompleted \n \n`isSuccess`: TRUE | ### Example of a redirect to the client in a successful case `https://www.nium.com/?customerHashId=773bcf1f-7e91-459b-a03a-75c87005145f&errorCode=&errorMessage=&isSuccess=true` ### Example of a redirect to the client in an unsuccessful case `https://www.nium.com/?customerHashId=590ec98a-ab6a-4da1-8dc7-35cc1c98d236&errorCode=R408&errorMessage=redirectURLExpired&isSuccess=false` --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-uk/required-parameters The API fields shown on this page are relevant to the UK regulatory region only. To see the full payload, refer to the Unified Add Customer API Reference. The API fields shown on this page are relevant to the UK regulatory region only. To see the full payload, refer to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API Reference. ## Required Parameters The following table is used when `kycMode = E_DOC_VERIFY`. | Field Name | Description | Required | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `firstName` | This field contains the first name of the customer. The maximum limit is 40 characters. | Yes | | `middleName` | This field contains the middle name of the customer. The maximum limit is 40 characters. | No | | `lastName` | This field contains the last name of the customer. The maximum limit is 40 characters. | Yes | | `nationality` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the customer's citizenship. | Yes | | `complianceLevel` | This field contains the compliance level for the customer. It is useful when the client has multiple compliance setups. The possible values are `SCREENING` and `SCREENING_KYC`. | No | | `countryCode` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country prefix code to the customer's mobile number. | Yes | | `mobile` | This field contains the mobile number of the customer without the country prefix code. The maximum limit is 20 numerals. | Yes | | `email` | This field contains the email address of the customer which must not already be in the system. The maximum limit is 60 characters. | Yes | | `dateOfBirth` | This field contains the customer's date of birth in `YYYY-MM-DD` format. Customers need to be at least 18 years old. For any special use cases, discuss with your Nium account manager. | Yes | | `kycMode` | This field can accept only `E_DOC_VERIFY` for UK customers. | Yes | | `billingAddress1` | This field contains the first line of the customer’s billing address. The maximum limit is 40 characters. | Yes | | `billingAddress2` | This field contains the second line of the customer's billing address. The maximum limit is 40 characters. | No | | `billingCity` | This field contains the city of the customer’s billing address. The maximum limit is 20 characters. | Yes | | `billingLandmark` | This field contains the landmark for the customer’s billing address. The maximum limit is 40 characters. | No | | `billingState` | This field contains the state of the customer's billing address. The maximum limit is 30 characters. | No | | `billingZipCode` | This field contains the postcode of the customer’s billing address. For UK, specify the postcode value in the following `SW4 6EH` format. The maximum limit is 10 characters. | Yes | | `billingCountry` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country of the customer's billing address. | Yes | | `deviceInfo` | This field contains the OS of the device used by the customer for initiating the request. | No | | `ipAddress` | This field contains the IP address of the device used by the customer for initiating the request. | No | | `countryIP` | This field contains the country IP address for the device by the customer for initiating the request. | No | | `sessionId` | This field contains the session ID of the customer's session that is initiating the request. | No | | `segment` | This field contains the fee segment associated with a client. The maximum limit is 64 characters. | No | | `verificationConsent` | This field specifies if the electronic verification consent to process customer data for compliance is required or not. | Yes | | `additionalInfo` | This field contains additional information. | No | | `intendedUseOfAccount` | This field contains the customer’s intended use of their account. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Yes | | `estimatedMonthlyFundingCurrency` | This field contains the [3-letter ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) in which estimated monthly funding is expected in the wallet. | Yes | | `estimatedMonthlyFunding` | This field contains the estimated monthly funding amount expected in the wallet. **Note:** This field is required when the `estimatedMonthlyFundingCurrency` field is provided in the request. Use [Fetch corporate constants API](/docs/onboarding/corporate-customers/corporate-constants) for valid values. | Yes \* | | `internationalPaymentsSupported` | This field specifies if the customer will be doing International send/receive/card payments. The default value is `false`. | Yes \* | | `expectedCountriesToSendReceiveFrom` | This array specifies the 2-letter [ISO Alpha-2 country codes](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) that the client expects their international payment to be spent in, sent to, or received from. **Note:** This field is required when the `internationalPaymentsSupported` field is `true`. | Yes \* | | `tags` | This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | No | ### `tags` object This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | Field name | Description | Required | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `key` | This field contains the name of the tag. The maximum limit is 128 characters. **Note:** This field is required if the `value` field is provided in the request. | Yes \* | | `value` | This field contains the value of the tag. The maximum limit is 256 characters. **Note:** This field is required if the `key` field is provided in the request. | Yes \* | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-uk/required-documents Document submission ## Document submission Since the identity verification is an eDocument verification method, no document submission is required in the API. Live Selfie with Passport or National ID or Driver's license is submitted in the form presented by the eDocument verification vendor. The customer needs to follow the instructions provided by the eDocument verification vendor to complete the identity verification process. --- # Example Requests URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-uk/example-requests To onboard your individual customer, you can call the Unified Add Customer API. To onboard your individual customer, you can call the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API. For an example call that you can customize with your information, see below. - [Request example for onboarding](#request-example-onboarding) - [Request example for reinitiation of onboarding](#request-example-reinitiation-onboarding) ## Request example for onboarding The following is an API request example call where the onboarding is initiated for the first time. ```json { "firstName": "Jack", "lastName": "Jill", "email": "jack@xyz.com", "nationality": "GB", "countryCode": "GB", "mobile": 23456789, "dateOfBirth": "1992-12-18", "kycMode": "E_DOC_VERIFY", "billingAddress1": "Long Street", "billingCity": "London", "billingZipCode": "E1 6AN", "billingCountry": "GB", "verificationConsent": true, "intendedUseOfAccount": "Day-to-day spending", "estimatedMonthlyFundingCurrency": "SGD", "estimatedMonthlyFunding": "1000-5000", "internationalPaymentsSupported": true, "expectedCountriesToSendReceiveFrom": [ "SG", "ES" ] } ``` ## Request example for reinitiation of onboarding The following is an API request example call where the onboarding is reinitiated after the first time, including after rejection. ```json { "firstName": "Jack", "lastName": "Brown", "email": "jack@xyz.com", "nationality": "GB", "countryCode": "GB", "mobile": 23456789, "dateOfBirth": "1992-12-18", "kycMode": "E_DOC_VERIFY", "billingAddress1": "Long Street", "billingCity": "London", "billingZipCode": "E1 6AN", "billingCountry": "GB", "verificationConsent": true, "intendedUseOfAccount": "Receiving a salary", "estimatedMonthlyFundingCurrency": "SGD", "estimatedMonthlyFunding": "1000-5000", "internationalPaymentsSupported": true, "expectedCountriesToSendReceiveFrom": [ "SG", "ES" ], "customerHashId": "f1cbcdac-1bb8-4cf9-9f19-702b95bc1c0b" } ``` --- # US Onboarding URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-us This page contains details about the United States Know Your Customer (KYC) flows and links to the following sub-pages for quick reference: | Page name | Description | | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | | **[US required parameters](/docs/onboarding/individual-customers/onboarding-us/required-parameters)** | This page lists the required API fields for onboarding an individual customer. | | **[US required documents](/docs/onboarding/individual-customers/onboarding-us/required-documents)** | This page contains tables listing the required documents for verification of an individual customer. | | **[US request examples](/docs/onboarding/individual-customers/onboarding-us/example-requests)** | This page contains API request examples for onboarding an individual customer in the US regulatory region. | ## eKYC – US When using the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API to add a customer in the United States, customer should undergo `E_KYC` verification. eKYC - US In the US, the add customer eKYC process is as follows: 1. Your new customer signs up for verification. 2. Send a `GET` request to the [Terms and Conditions](/api#tag/customer-terms-and-conditions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/termsAndConditions) API. 3. Nium returns the Terms and Conditions description. 4. Display the Terms and Conditions to your customer to agree and accept. You collect all customer information for onboarding. 5. Send a `POST` request to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API as per [US required parameters](https://developersandbox.nium.com/apis/edit/ic-us-required-parameters) 6. Nium sends a CUSTOMER\_COMPLIANCE\_STATUS webhook with `complianceStatus`. 7. Send a response with the HTTPS status code `200`. --- # Required Parameters URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-us/required-parameters The API fields shown on this page are relevant to the US regulatory region only. To see the full payload, refer to the Unified Add Customer API Reference. The API fields shown on this page are relevant to the US regulatory region only. To see the full payload, refer to the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API Reference. ## Required Parameters The following table is used for customer onboarding in the US. | Field Name | Description | Required | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `firstName` | This field contains the first name of the customer. The maximum character limit is 40. | Yes | | `middleName` | This field contains the middle name of the customer. The maximum character limit is 40. | No | | `lastName` | This field contains the last name of the customer. The maximum character limit is 40. | Yes | | `nationality` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the customer's citizenship. | Yes | | `complianceLevel` | This field contains the compliance level for the customer. It is useful when the client has multiple compliance setups. The possible values are `SCREENING` and `SCREENING_KYC`. | No | | `countryCode` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country prefix code to the customer's mobile number. | Yes | | `mobile` | This field contains the mobile number of the customer without the country prefix code. The maximum character limit is 20 and can contain only numerals. | Yes | | `email` | This field contains the email address of the customer which must not already be in the system. The maximum character limit is 60. | Yes | | `dateOfBirth` | This field contains the customer's date of birth in `YYYY-MM-DD` format. Customers need to be at least 18 years old. For any special use cases, discuss with your Nium account manager. | Yes | | `kycMode` | This field can accept only `E_KYC` for US customers. | Yes | | `billingAddress1` | This field contains the first line of the customer’s billing address. The maximum character limit is 40. | Yes | | `billingAddress2` | This field contains the second line of the customer's billing address. The maximum character limit is 40. | No | | `billingCity` | This field contains the city of the customer’s billing address. The maximum character limit is 20. | Yes | | `billingLandmark` | This field contains the landmark for the customer’s billing address. The maximum character limit is 40. | No | | `billingState` | This field contains the state of the customer's billing address. The maximum character limit is 30. | Yes | | `billingZipCode` | This field contains the ZIP code of the customer’s billing address. The maximum alphanumeric character limit is 10. | Yes | | `billingCountry` | This field contains the 2-letter [ISO Alpha-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) denoting the country of the customer's billing address. | Yes | | `deviceInfo` | This field contains the OS of the device used by the customer for initiating the request. | No | | `ipAddress` | This field contains the IP address of the device used by the customer for initiating the request. | No | | `countryIP` | This field contains the country IP address for the device by the customer for initiating the request. | No | | `sessionId` | This field contains the session ID of the customer's session that is initiating the request. | No | | `segment` | This field contains the fee segment associated with a client. The maximum character limit is 64. | No | | [identificationDoc](#identificationdoc-object) | This array of objects contains identification documents. The maximum size of this array is 10 MB. | Yes | | `additionalInfo` | This field contains additional information. | No | | [tags](#tags-object) | This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | No | ### `identificationDoc` object This array of objects contains identification documents. The maximum size of this array is 10 MB. | Field name | Description | Required | | --------------------- | ----------------------------------------------------------------- | -------- | | `identificationType` | This field contains the name of the document type being uploaded. | Yes | | `identificationValue` | This field contains the unique document identifier. | Yes | ### `tags` object This object contains the user defined key-value pairs provided by the client. The maximum number of tags allowed is 15. | Field name | Description | Required | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `key` | This field contains the name of the tag. The maximum character limit is 128. **Note:** This field is required if the `value` field is provided in the request. | Yes \* | | `value` | This field contains the value of the tag. The maximum character limit is 256. **Note:** This field is required if the `key` field is provided in the request. | Yes \* | --- # Required Documents URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-us/required-documents Document submission ## Document submission Only US residents are supported as individual customers in the US regulatory region. Nium's eKYC verification process is based on the Social Security Number (SSN) of the person to be onboarded, and thus the SSN is required to pass via the API. The following table lists the fields required to be passed within the `identificationDoc` object of the API. | Field name | Value | | :-------------------- | :-------------------------------------------------------------------------- | | `identificationType` | `National Id` | | `identificationValue` | The customer’s 9 digit SSN needs to be provided as an identification value. | --- # Example Requests URL: https://docs.nium.com/docs/onboarding/individual-customers/onboarding-us/example-requests To onboard your individual customer, you can call the Unified Add Customer API. To onboard your individual customer, you can call the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) API. For an example call that you can customize with your information, see below. ## Request example The following is an API request example call for onboarding. ```json {     "firstName": "Peter",     "lastName": "Parker",     "email": "peter.parker@xyz.com",     "nationality": "US",     "countryCode": "US",     "mobile": 123456789,     "dateOfBirth": "1980-01-21",     "kycMode": "E_KYC", "billingAddress1": "101 River Rd", "billingCity": "Philadelphia",     "billingState": "PA",     "billingZipCode": "18013",     "billingCountry": "US",     "identificationDoc": [         {             "identificationType": "National Id",             "identificationValue": "123456789"         }     ] } ``` --- # Verification of Payee URL: https://docs.nium.com/docs/onboarding/vop-guidelines From October 9, 2025, Nium must comply with the EU’s Instant Payments Regulation, which requires clients to perform a Verification of Payee (VoP) on all EUR Local payouts. From *October 9, 2025*, Nium must comply with the EU’s *Instant Payments Regulation*, which requires clients to perform a *Verification of Payee (VoP)* on all *EUR Local payouts*. This guide helps explains: - What changes are happening. - How payouts will change. - How to use *Nium Verify* to improve success rates (optional). ## What’s changing - All EUR local payouts will be required to perform a verification of payee check. - The check validates that the *beneficiary name matches the account holder's name* at the destination bank. - By default, if the names do not match, the payout will be *rejected*. Nium will perform a verification of payee check on every eligible EUR Local payout, regardless of whether you submit a request to the Nium Verify endpoint. ## Client actions ### Override handling - **Default (no action)**: Mismatched payouts will be **rejected**. - **Enable override in Nium Portal**: Mismatched payouts will **proceed**, and your organization accepts liability. To enable the EU override in [Nium Portal](/docs/nium-portal): 1. Log in to [Nium Portal](https://app.nium.com). 2. Click to **Configuration. → Client settings → Verification of Payee Override**. 3. Toggle **Override default**. 4. Review and accept Terms & Conditions. ### Verify beneficiaries To minimize rejections and provide a smoother experience, use the *Nium Verify* endpoint to verify names before creating `payouts`. - [Nium Verify](/api#tag/nium-verify/POST/api/v1/client/{clientHashId}/verifications) - Test your integration in sandbox using the provided [Testing data](#testing-data). Contact [Nium Support](mailto:support@nium.com) to enable access. Example outcomes: - `match`: Safe to proceed with creating the payout. - `partial_match`: Review/correct name or decide on override. - `no_match`: Correct name or enable override if desired. - `invalid`: Review account details. ## Transfer money If you don’t call Verify, Nium still checks during the **Transfer Money** request: | VoP Result | Override Disabled | Override Enabled | | -------------- | ----------------- | ---------------- | | match | Proceed | Proceed | | partial\_match | Reject | Proceed | | no\_match | Reject | Proceed | | invalid | Reject | Proceed | ## Key dates | Date | Milestone | | ------------ | --------------------------- | | Aug 8, 2025 | Initial client notification | | Aug–Sep 2025 | Monthly reminders | | Oct 9, 2025 | Enforcement begins | ## Testing data To help you validate your integration and VoP handling logic, Nium provides **sandbox test IBANs** and account names that simulate different outcomes. | Beneficiary account number | Beneficiary name | Expected response | Notes | | -------------------------- | ---------------- | ------------------------------------- | --------------------------------------------------------- | | `BE84504754703434` | `John Smith` | Transaction Created | IBAN and name match correctly. | | `BE84504754703434` | `J Smith` | `NAME_MISMATCH_NO_OVERRIDE_ALLOWED` | Slight variation triggers partial match. | | `BE84504754703434` | `Jane Doe` | `NAME_MISMATCH_NO_OVERRIDE_ALLOWED` | Name does not match account records. | | `BE48504008294902` | `John smith` | `ACCOUNT_INVALID_NO_OVERRIDE_ALLOWED` | IBAN not valid; verification of payee returns as invalid. | ### Sample responses #### Partial Match Example ```json { "status": "BAD_REQUEST", "message": "Payment validation failed", "errors": [ "beneficiary_name NAME_MISMATCH_NO_OVERRIDE_ALLOWED" ] } ``` #### No Match Example ```json { "status": "BAD_REQUEST", "message": "Payment validation failed", "errors": [ "beneficiary_name NAME_MISMATCH_NO_OVERRIDE_ALLOWED" ] } ``` #### Invalid Account Example ```json { "status": "BAD_REQUEST", "message": "Payment validation failed", "errors": [ "beneficiary_name ACCOUNT_INVALID_NO_OVERRIDE_ALLOWED" ] } ``` Transaction will be successfully created if the override setting is `True`. ## Common questions Q: Is the [Nium Verify](/docs/verify) endpoint mandatory? A: No. Nium performs VoP checks automatically. However, using the [Nium Verify](/docs/verify) endpoint to verify names helps you reduce payment rejections. You can also enable the override toggle in Nium portal to avoid disruptions. Q: Can I still override mismatches? A: Yes, by enabling the override setting in [Nium Portal](/docs/nium-portal). Q: What is the risk of enabling override? A: You accept liability for payouts made despite a name mismatch. Q: What happens if I do nothing? A: From Oct 9, 2025, all EUR Local payouts with mismatched beneficiary names will be rejected. ## Resources - [Nium Verify](/docs/verify) - [Transfer Money](/docs/payouts/transfer-money) - [Support Contact](mailto:support@nium.com) Before October 9, 2025, to avoid disruptions, Nium customers must either: - Use the [Override toggle](#override-handling) in Nium portal. - Integrate with [Nium Verify](/docs/verify). --- # Europe URL: https://docs.nium.com/docs/onboarding/europe As part of Europe’s Instant Payments Regulation, Nium complies with Verification of Payee (VoP) requirements. As part of Europe’s **Instant Payments Regulation**, Nium complies with **Verification of Payee (VoP)** requirements. Local EUR accounts issued via Nium (through SEPA) must be registered with the VoP regulatory authority. This allows the remitter to verify account details before processing a transaction. If a customer chooses to **opt out** of sharing account information with the VoP scheme, the decision can be submitted to Nium using the [Verification of Payee](/api#tag/beneficiary/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/accountVerification) request. Provide: - `uniquePaymentId`: The virtual EUR account number issued via SEPA - `consent`: Opt-out decision For more information, see [Verification of Payee](/docs/onboarding/vop-guidelines) For questions, contact . --- # Wallets URL: https://docs.nium.com/docs/wallets Your customers or account holders get a wallet in multiple currencies. They use a wallet to make payments. You can consider a wallet an account, so you can use the term wallet or account interchangeably. The wallet holds balances in all the currencies that the Nium One program configures. For instance, if your client program is configured to support USD, GBP, and EUR currencies, then a given wallet can store balances in USD, GBP, and EUR. Wallet balances in three currencies. Wallet balances displayed in multiple currencies. Multicurrency wallet virtual account. A virtual account supporting multiple currencies. Nium has integrations with key banking partners to help you obtain and assign virtual bank account numbers (VANs) to meet your product needs. This helps you assign VANs to collect locally or use the Society for Worldwide Interbank Financial Telecommunications (SWIFT) service. You can assign a USD local VAN, for example, so the account holder can collect or fund with US Automated Clearing House (ACH) rails. Similarly, Nium can help you collect GBP using UK Faster Payment Service (FPS) rails by assigning a local GBP-enabled VAN. ## Virtual and physical bank accounts A physical bank account is held in the name of an account holder. A virtual bank account is a feature that a bank offers to help an account holder get multiple account numbers linked to a primary physical bank account. It helps an account holder to receive money using multiple VANs and reconcile effectively. A virtual bank account isn't a separate account but it's a proxy account that's linked to the underlying primary physical bank account. Nium One client structure Nium One client structure The diagram above captures the Nium structure. It shows a client with two client-level prefund accounts in the GBP and USD currencies. The client also has a certain number of account holders. Each account holder has a multicurrency wallet. The multicurrency wallet for account holder **'n'** indicates the wallet has two currencies and each currency has its own VAN. Nium supports assigning VANs at underlying multicurrency wallets and at client prefund accounts, as illustrated in the diagram. As a first step to making use of the VAN feature, you need to work with Nium to configure the client program with the appropriate set of VAN sources. In the image above, the client program is configured with a USD VAN and a GBP VAN, using the right USD VAN source and GBP VAN source. These configuration details about the VAN source are seen in the [Client Details](/api#tag/client-settings/GET/api/v1/client/{clientHashId}) API response. ```shell curl --location --request GET '' \ --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' ``` For brevity, only a section of the API response appears. ```json { ... "paymentIds": [ { "currencyCode": "GBP", "uniquePayerId": null, "uniquePaymentId": "20024397659", "bankName": "JPM_SG" }, { "currencyCode": "USD", "uniquePayerId": null, "uniquePaymentId": "20024397659", "bankName": "JPM_SG" } ], ... } ``` The response suggests that the given client program is configured to use JPMorgan Chase & Co. Singapore or `JPM_SG` as the `bankName` VAN source to issue GBP VAN and USD VAN. The specific bank account number assigned to the client's prefund account—for GPB: 20024397659 and for USD: 20024397659—is the same account number, as this VAN happens to support multiple currencies. The data element `bank_Name` is to be seen as the VAN source. Depending on the configuration you agree with Nium, this VAN source could change. Nium can share the SWIFT code, bank code, or sort code details relevant to the VAN source with you. This *is not* part of the API response. You need to make use of that code, along with the account number, to receive funds through bank rails into the client prefund account. In the above example, for instance, the SWIFT code is CHASSGSG and you need to use it along with account number 20024397659 to receive funds into either one of the client prefund accounts. Nium One supports assigning VANs to the individual currency of the account holder’s multicurrency wallet or account. You see in the diagram that a VAN could be assigned to the USD currency and GBP currency of the wallet. So, every currency within every wallet could be assigned a unique VAN. ### VAN assignment By using the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) API, you can assign the VAN from one of the configured VAN sources. These are configured as part of your client configuration. Before using this API, make sure to configure the list of VAN sources in your configuration. Nium does this configuration for you. To know the list of VAN sources configured in your configuration, use the [Client Details](/api#tag/client-settings/GET/api/v1/client/{clientHashId}) API. You can use the [Virtual Account Details V2](/api#tag/customer-virtual-accounts/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentIds) API to know about the VANs assigned to the account holder’s multicurrency wallet at each currency level. ```shell curl --location --request GET 'https://gateway.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/59796fed-48d3-4d36-8915-0ff1a83d0bd0' \ --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' ``` For brevity, only a section of the API response appears. ```json { ... "paymentIds": [ { "currencyCode": "GBP", "uniquePaymentId": "20024397576", "uniquePayerId": null, "bankName": "JPM_SG" }, { "currencyCode": "USD", "uniquePaymentId": "20024397576", "uniquePayerId": null, "bankName": "JPM_SG" } ], ... } ``` The `uniquePaymentId` is the bank account number. The `bankName` data element indicates the VAN source used. Nium can help you with the appropriate bank code or SWIFT code for the configured banks. In this case, the SWIFT code to be used would be CHASSGSG. So, this particular account holder collects funds into the USD or GBP account by using the SWIFT code CHASSGSG and bank account number 20024397576. ## Multiple wallets Customers and account holders can use multiple wallets to hold their different balances and manage funds from any currency per their business needs. A default wallet is always assigned to customers once they've been successfully onboarded. After they're successfully onboarded, you can configure additional wallets for the customer. These additional wallets can hold balances in a single or multiple currencies, depending on the customer's business needs. - Virtual accounts can also be assigned to any wallet for funding and collection purposes. - Additionally, Payins and Payouts are available to support any wallet for better ledger management. Please note: - Multiple Wallets is currently only supported for the following regions. We're actively working on bringing this feature to more regions. - United States (US) - United Kingdom (UK) - Canada (CA) - Singapore (SG) - Australia (AU) - Hong Kong (HK) - This feature is only available for corporate customers. - Please contact [Nium support](mailto:support@nium.com) to review use case and to configure the maximum number of wallets. ### Requests | API | Description | | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Add Wallet](/api#tag/customer-wallet-balance/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet) | Create and add a wallet for a customer. While creating the wallet, you can specify the currencies the balance should be held in. **Note**: If a currency isn't passed while creating the wallet, the balance will be held in the base currency. Additionally, any other wallets created for the customer will be assigned to the base currency. ii) The `intendedUseOfAccount` field is required when creating any wallet. iii) The fields "name" can be used to identify the wallet, if required. | | [Update Wallet](/api#tag/customer-wallet-balance/PUT/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}) | Update the name, currencies and tags of the wallet. | | [Fetch Wallet](/api#tag/customer-wallet-balance/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet) | Fetch the list of wallets associated with a customer. You can also use this request, with query parameters, to fetch information about a specific wallet. | ### Troubleshooting errors The following is a breakdown of some common errors that can get returned when using the above requests: | API | Description | | :------------------------------------ | :-------------------------------------------- | | `invalid_client_hash_id` | The `clientHashId` provided is invalid. | | `invalid_customer_hash_id` | The `customerHashId` provided is invalid. | | `invalid_wallet_hash_id` | The `walletHashId` provided is invalid. | | `customer_status_not_clear` | Customer's KYC status is not clear. | | `currency_not_configured` | Currency not configured for the client. | | `wallet_creation_limit_exceeds` | Number of wallets exceeds the maximum number. | | `wallet_currency_already_exists` | Currency already exists for the wallet. | | `wallet_currency_removal_not_allowed` | Wallet currency cannot be removed. | --- # Wallet to Wallet Transfers URL: https://docs.nium.com/docs/wallets/wallet-to-wallet-transfers You can allow a Nium onboarded customer to transfer funds from their wallet to another Nium onboarded customer with a suite of Nium One platform fund transfer APIs, which your customer has authorized to do so. The sender and the receiver of the funds can be an individual or a business and can belong to the same or a different client setup based on geographic regions. Global clients have multiple client setups on the platform where customers across the client setups require wallet to wallet transfers. To enable wallet to wallet fund transfers across multiple client setups, contact your Nium representative. Wallet to Wallet Transfers request. > Details how the Wallet to Wallet Transfers request allows you to send money from one wallet to another wallet in the same or a different client setup based on geographic regions. ## Prerequisites - There are no prerequisites to allow wallet to wallet transfers within the same client setup. - There are two requirements to allow wallet to wallet transfers between multiple geographic client setups: - The client of the sender and the receiver customer needs to have the `allowInterClientWalletTransfer` flag set to `true`. - At least one common currency needs to be enabled between the different client setups to enable wallet to wallet fund transfers. ## API server URLs Use the following URLs to separate API calls between different environments. - Sandbox: `https://gateway.nium.com` - Production: `https://api.spend.nium.com` ## API endpoints | HTTP method | API name | Action | | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Wallet to Wallet Transfer](/api#tag/wallet-to-wallet-transfers/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transfers) | This API helps you transfer funds from one Nium onboarded customer wallet to another similar wallet. | | GET | [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) | This API allows you to fetch the transaction details for a customer. | | GET | [Client Transactions](/api#tag/client-transactions) | This API allows you to fetch transaction details at the client level. It also supports query parameters based on filtering to fetch details of the transactions for the customer. | ### Wallet to Wallet Transfer API The [Wallet to Wallet Transfer](/api#tag/wallet-to-wallet-transfers/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transfers) API allows you to transfer funds in the same currency. For example, the source and the destination currency are the same for the sender and the receiver. The operation also lets you transfer funds between different currencies. - The sender can use the [Create Conversion](/api#tag/conversions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions) API to send money from one currency to another in the same wallet. The sender then uses the Wallet to Wallet Transfer API to send the converted currency to the receiver’s wallet. - The sender can use the wallet to wallet transfer request to transfer funds to the receiver’s wallet. The receiver then uses the Create Conversion API to transfer funds from one currency to the desired currency in the same wallet. ## Troubleshooting errors The following are the common error scenarios in sending an API request for a wallet to wallet transfer. | Error | Description | | :------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Either `sourceAmount` or `destinationAmount` isn't provided. | Either provide `sourceAmount` or `destinationAmount`. | | `purposeCode` is invalid. | The transaction isn't permitted due to an invalid `purposeCode`, and the [Purpose of Transfer Code](/docs/payouts/transfer-money/purpose-codes) is provided, such as `IR001`. | | `purposeCode` isn’t provided. | The transaction isn't permitted because the `purposeCode` is required. | | Receiver’s inter-client transfer flag in client configuration is not true. | The receiver’s client program doesn’t have the permission to receive the funds from that client’s customer through Wallet transfer. | | Sender’s inter-client transfer flag in client configuration is not true. | The sender's client program doesn’t have the permission to transfer the funds to that client’s customer through Wallet transfer. | | `sourceCurrencyCode` and `destinationCurrencyCode` don’t match. | Cross-currency transfers are not allowed. The `sourceCurrencyCode` and `destinationCurrencyCode` need to be the same. | --- # Payins URL: https://docs.nium.com/docs/payins Payins enable clients and businesses to collect and fund Nium wallets seamlessly through various payment methods, such as bank transfers, cards, digital wallets, and virtual account numbers (VANs). Whether you are collecting payments from customers or funding your own accounts, payins serves as the bridge to move money into your Nium wallet efficiently and securely. **Payins** enable clients and businesses to collect and fund Nium wallets seamlessly through various payment methods, such as bank transfers, cards, digital wallets, and virtual account numbers (VANs). Whether you are collecting payments from customers or funding your own accounts, payins serves as the bridge to move money into your Nium wallet efficiently and securely. Specifically, payins refers to the process of receiving and funding money into your Nium wallet. Payins supports two primary capabilities: - **Monetary collections:** Collect funds from third parties (e.g., business customers or payers) into your wallet. - *E.G.* A software-as-a-service (SaaS) company collects subscription payments from customers around the world. - **Wallet funding:** Add money to your Nium wallet directly from your own bank account or payment methods. - *E.G.* A corporate client funds their Nium wallet to process payroll or vendor payouts. Payins supports multiple funding channels and payment flows to suit your business needs. With Payins, you can: - **Streamline collecting funds:** Automate the process of collecting funds from customers or third-party sources (e.g., customers, suppliers). - **Simplify wallet funding:** Use multiple funding channels (like bank transfers, prefunding, or card transactions) for flexibility and reliability. - **Improve cash flow management:** Enable real-time or scheduled transfers through virtual account numbers (VANs) or direct debit. Depending on your region, additional verification can be required before creating `payins`. For more details, see [Verification of Payee](/docs/onboarding/vop-guidelines). ## Key features Key features of payins include: - [Fund wallet](#fund-wallet) - [Program, client, and prefund accounts](#program-client-and-prefund-accounts) - [Virtual Account Numbers (VANs)](#virtual-account-numbers-vans) - [Direct Debit](#direct-debit) ### Fund wallet The [Fund Wallet](/docs/payins/fund-wallet) request lets you add money to your Nium wallet. You can use various funding sources, including: - **Prefunding:** Transfer funds upfront for immediate use. - **Bank transfer:** Fund wallets directly from a bank account. - **Card transactions:** Use debit or credit cards to add funds. - **Direct Debit:** Automate recurring transfers from a bank account. Each funding channel is flexible and secure, allowing businesses to maintain control over their cash flow. For more information, see [Fund Wallet](/docs/payins/fund-wallet). ### Program, Client, and Prefund Accounts To help you easily manage funds, Nium organizes funding under structured entities: - **Programs:** Logical groupings of clients, defined by geographic region or bank configurations. - **Clients:** Businesses onboarded onto the Nium platform to issue wallets and cards for their customers. - **Client Prefund:** Add balance to a central account for wallet funding. For more information, see [Program, Client, and Prefund Accounts](/docs/payins/program-client-and-client-prefund-account). ### Virtual Account Numbers (VANs) A **Virtual Account Number (VAN)** is a unique, reusable account number that facilitates bank transfers. VANs enable you or your customers to: - Collect funds from third-party sources (e.g., customer payments). - Add funds to wallets via seamless bank transfers. For details on VAN setup and supported banks, see [Virtual Account Numbers](/docs/payins/virtual-account-number). ### Direct Debit **Direct Debit** enables clients to automate funding from a customer’s bank account into their Nium wallet. This is ideal for recurring payments, such as payroll or subscription collections. Direct Debit is currently supported in multiple regions, including: - AU - EU - SG - UK - US For more information, see [Direct Debit](/docs/payins/direct-debit). ## Europe As part of the Europe's Instant Payments Regulation, Nium is adhering to Verification of Payee (VoP) requirements. The guidelines mandates that the information of Local EUR Accounts issued via Nium is to be provided to VoP regulatory authority. This means, that NIUM will share the account information for the Local EUR Accounts issued with SEPA via Nium, so that the sender can verify account details before processing the transaction. If the customer wants to opt-out i.e, don’t want to share account information with the VoP scheme, the opt-out decision can be provided to Nium using the [Verify a Bank Account](/api#tag/nium-verify/GET/api/v1/client/{clientHashId}/verifications) request. Include the `uniquePaymentId` - The virtual account number for EUR account with SEPA. For more information, see [Verification of Payee guidelines](//docs/02-Onboarding/04-VoP-Guidelines.md) In you have any questions, please don't hesitate to contact . --- # Fund a Wallet URL: https://docs.nium.com/docs/payins/fund-wallet Learn how to fund a Nium wallet using a card, bank transfer, direct debit, or third-party account. Covers funding setup, virtual accounts, and API steps. Use the [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) request to fund a digital wallet through your application. ## Supported funding sources Fund a wallet using any of the following methods: | Method | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Prefunding** | Transfer money to the wallet before a transaction settles or immediately when the financial institution processes funds. Use any source or destination currency. | | **Bank transfer** | Transfer funds to a bank account. | | **Card** | Use a debit or credit card to fund the wallet.Must be enabled by Nium.Source and destination currency must be the same. | | **Direct debit** | Set up automatic transfers from a customer's bank account to their wallet. Must be enabled by Nium. | Wallets can be funded by yourself, third-parties, or your own customers. Contact [Nium Support](mailto:support@nium.com) or your account manager for details on what funding channels are available for you. - For **prefunding**, source and destination currencies can differ. - For **bank transfer** and **card**, both currencies must be the same. ## Funding Wallet Your customers and you can fund your own wallet. Start by creating a Virtual Account Number (VAN). 1. Use the [Fetch Client Details](/api#tag/client-settings/GET/api/v1/client/{clientHashId}) request to confirm which `currencyCode` and `bankName` values are available. 2. Use the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) request to create a `paymentId` for your customer or for your wallet. - The `paymentId` represents your VAN. - Include the `currencyCode` and `bankName` you want the `paymentId` to use. 3. Fetch the VAN details using the [Fetch Virtual Account Details V2](/api#tag/customer-virtual-accounts/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentIds) request. After you've created a VAN: 1. Transfer funds through from your financial institution to your Nium wallet using the VAN details. 2. Nium's financial institution confirms the credit through Inward Credit Confirmation (ICC). An authorization code ( `authCode`) is returned once the transfer begins. 3. Use the `authCode` to fetch the transaction using the Fetch [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) request. When complete: - `status` is **Approved** - `complianceStatus` is **Settled** Diagram showing how to fund a Nium wallet ## Collections Accept wallet funding from a customer, partner, vendor, or other external account. Start by creating a Virtual Account Number (VAN): 1. Use the Fetch [Client Details](/api#tag/client-settings/GET/api/v1/client/{clientHashId}) request to confirm which `currencyCode` and `bankName` values are available. 2. Use the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) request to create a `paymentId`. - The `paymentId` represents your VAN. - Include the desired `currencyCode` and `bankName`. 3. Fetch the VAN using the Fetch [Virtual Account Details V2](/api#tag/customer-virtual-accounts/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentIds) request. After the VAN is shared: 1. The third party sends funds to your wallet using the VAN details. 2. Nium's financial institution confirms the credit through ICC, and an `authCode` is returned. 3. Use the `authCode` with the Fetch [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) request to fetch the status of the transfer. - When complete: - `status` is **Approved** - `complianceStatus` is **Settled** - If webhooks are configured, you also receive the [Wallet Funded webhook](/docs/developers/notifications-and-webhooks/payin-events/wallet-funded) on success. Diagram showing how to fund a Nium wallet from a third-party bank account ## Fund wallet using a card To fund a wallet using a card, after a successfully completing onboarding through Electronic Know Your Customer (eKYC): 1. Use the [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) request using a debit or credit card as the funding method. 2. Nium provides a `returnUrl` to complete 3D Secure One-Time Password (**3DS OTP**) verification. - If 3DS fails, the transaction is restarted. - If successful, you get redirected the customer to your predefined return URL. **URL format:** ```text https:///wallet/fund/{systemReferenceNumber} ``` 3. Use the Fetch [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) request with the `systemReferenceNumber={authCode}` query parameter. Include the `authCode` returned through ICC. - If the `status` is **Approved** or **Declined**, the transaction ends. - If the `status` is **Pending**, wait for the [Wallet Funding](/docs/developers/notifications-and-webhooks/payin-events/wallet-funded) webhook to confirm the transfer. ## Fund wallet using direct debit For details on how to fund a wallet using direct debit, see [Direct Debit](/docs/payins/direct-debit). ## Funding wallets around the world Funding flows around the world can differ depending on the country and local currency. The following highlights important regional requirements for wallet funding. ### Brazil Nium enables clients and corporate customers in Brazil to fund wallets locally in BRL, reducing costs and improving transaction speed. Please note, local funding is only available for **corporate customers** with a valid **CNPJ** (Cadastro Nacional da Pessoa Jurídica). - The CNPJ can be provided during onboarding in the `taxDetails` object using the [Onboard Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate) request. - You can also add CNPJ details to the `customer` at a later time using the [Update Corporate Customer](/api#tag/customer-account-corporate/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/corporate) request. If you're planning to enable BRL funding, make sure your onboarding flow collects this information to avoid any interruptions. Please note, only wallet funding is supported in BRL. Collecting funds from a third party is not supported. #### Supported payment methods No transaction limits are in place for payment methods in Brazil. | Method | Speed | Availability | | ------ | --------- | ----------------- | | PIX | Real-time | 24/7 | | TED | Same day | Cutoff: 15:00 BRT | #### Funding wallets in Brazil Unlike other currencies, BRL funding does not use a [Virtual Account Number (VAN)](/docs/payins/virtual-account-number). Instead, use the static bank details provided by Nium and includes their CNPJ in the payment reference. 1. Share the following BRL bank details with your customer: - **Account name**: NIUM PTE. LTD. - **Account number**: 11504943 - **Bank name**: Banco BS2 S.A. - **Bank code**: 218 - **Branch**: 0001 - **Currency**: BRL 2. The customer initiates a PIX or TED payment, with their financial institution, from their bank account and includes their CNPJ details in the transaction details. 3. Nium matches the CNPJ in the incoming payment with the CNPJ on file for the customer's wallet. 4. Once matched and reconciled, the customer's wallet is credited in BRL. For more on onboarding corporate customers, see [Corporate Customers](/docs/onboarding/corporate-customers). Diagram showing how to fund a Nium wallet in Brazil ### Singapore Use [Fast And Secure Transfers (FAST)](https://www.abs.org.sg/consumer-banking/fast) or [PayNow](https://www.abs.org.sg/consumer-banking/pay-now) to instantly fund a wallet. Diagram showing how to fund a Nium wallet using FAST and PayNow ### Canada - EFT and Interac Nium enables clients in Canada to fund wallets locally in CAD via: - **Interac e-Transfer** - **Electronic Funds Transfer (EFT)** via Canadian bank transfer. These methods allow customers to fund their wallets using local Canadian payment rails. #### Funding wallets in Canada via Interac e-Transfer Nium supports **Interac Autodeposit**, which allows incoming Interac e-Transfers to be credited directly to the CAD Virtual Account (VA) without requiring the payer to answer a security question. Interac e-Transfers to the VA are supported **only when Autodeposit registration has been completed** for the linked Interac email. Interac e-Transfers are processed in **near real-time**: funds are typically credited to the Nium CAD wallet within **minutes** of the payer's bank releasing the transfer. Nium supports two configurations for the Interac email linked to the CAD Virtual Account: - **Client-provided email**: An existing client-owned email address registered for Interac Autodeposit and linked to the CAD Virtual Account. - **Nium-provided email**: An email auto-created by Nium with Interac Autodeposit enabled for CAD funding. Payers use this email as the funding destination for Interac transfers. ##### Client-provided email 1. When requesting the CAD Virtual Account via the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) request, provide: - `uniquePayerId` — the **exact email address** to use for Interac funding (for example, `payments-ca@yourdomain.com`) - `uniquePayerIdType` — `email` - `bankName` — `PATENO_CA` 2. Nium configures the CAD VA, links the email, and sends an **Interac Autodeposit registration email** to the address provided. 3. The registration email contains a link to complete registration in online banking. The customer opens the email and completes **Autodeposit registration**. The link is valid for **up to 7 days**; registration must be completed within this window. The email may land in Spam/Junk depending on the recipient's filters. 4. Once registration is complete, the email is enabled for Autodeposit immediately. Payments can then be initiated to this email from any Canadian bank account via Interac e-Transfer. 5. Nium credits the Nium CAD wallet in real time on receipt of funds. ##### Nium-provided email 1. When requesting the CAD Virtual Account via the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) request, provide `bankName` = `PATENO_CA`. 2. Nium provisions the email and registers it for Interac Autodeposit. Once the email is registered, Nium sends the [Virtual Account Assigned](/docs/developers/notifications-and-webhooks/platform-events/virtual-account-assigned) webhook with the virtual account details. Alternatively, the details can be fetched via the [Virtual Account Details V2](/api#tag/customer-virtual-accounts/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentIds) API. 3. The `virtualAccountNumber` provides the local virtual account details to initiate EFT; the `uniquePayerId` provides the unique email address linked to the `virtualAccountNumber`. 4. Payments can be initiated to this email from any Canadian bank account via Interac e-Transfer. 5. Nium credits the Nium CAD wallet in real time on receipt of funds. - Autodeposit registration must be completed **before** Interac e-Transfers can be received. Transfers sent prior to completion may not be deposited automatically. - Once an Interac e-Transfer is deposited via Autodeposit, the transaction **cannot be reversed**. - Interac e-Transfer is a **domestic-only** rail and works only between Canadian bank accounts. It does not support international transfers. - The registration link sent to a client-provided email is valid for approximately **7 days**. Ensure the email can receive external messages and check Spam/Junk folders. #### Funding wallets in Canada via EFT EFT uses Canadian domestic rails to send CAD directly to the CAD Virtual Account. 1. Request a CAD Virtual Account Number (VAN) via the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) request. For details on what a VAN is and how it works, see [Virtual Account Numbers](/docs/payins/virtual-account-number). 2. Retrieve the VAN details using the [Virtual Account Details V2](/api#tag/customer-virtual-accounts/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentIds) request. a. The `virtualAccountNumber` returned for Canada EFT is a 17-digit string. For details about its structure, see [Currency-specific exceptions](/docs/payins/virtual-account-number#currency-specific-exceptions). 3. The customer logs in to their online or corporate banking portal and initiates an EFT payment to the Nium-provided VAN details. 4. Funds are received by Nium and reconciled. Nium's financial institution confirms the credit via Inward Credit Confirmation (ICC). An `authCode` is returned once the transfer begins - use this with the [Fetch Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) request to track the transaction. 5. Once reconciled, the customer's Nium wallet is credited in CAD. If webhooks are configured, a [Wallet Funded](/docs/developers/notifications-and-webhooks/payin-events/wallet-funded) webhook is triggered upon successful crediting. ### Funding via Wires using MT and PACS This section explains **how your bank should format wire transfers** when you send wires to Nium. Using the correct format helps: - Meet regulatory requirements. - Reduce payment rejections and returns. - Ensure faster and smoother settlement of your funds. Share this section with your bank or payments team. #### Which message type to use When sending funds **from you (the client) to Nium**, your bank must use a **customer credit transfer** message type. **Required for client payments to Nium:** - **SWIFT**: `MT103` - **ISO 20022**: `pacs.008` **Not permitted for client payments:** - **SWIFT**: `MT202` - **ISO 20022**: `pacs.009` Instruct your bank: *"This is a customer payment to Nium. Use MT103 (or pacs.008) and do not use MT202 or pacs.009."* #### Mandatory sender (debtor) information All wire transfers sent to Nium **must** clearly identify you (the sender). Your bank must include: - Your **full legal name** (no abbreviations). - Your **complete physical address**, including: - Street and building number - City - Country - The **correct message type** (MT103 or pacs.008). Providing only a SWIFT BIC or only city/country is **not sufficient**. Incomplete or abbreviated information may cause the payment to be **rejected or delayed** by the receiving bank. #### SWIFT MT103 example ```plaintext :20:TEST123 :23B:CRED :32A:250115USD10000, :50x:/123456789 CLIENT LEGAL NAME LTD 123 MAIN STREET DUBAI AE :57A:LHVEE22 :59:/987654321 NIUM OPERATIONS ``` Key points: - `:20:` — your reference number. - `:23B:` — fixed value `CRED`. - `:50x:` — can be `50K` or `50F`. Contains: - **Account number** (`/123456789`) — the `uniquePaymentId` returned in the Virtual Account Details response. - **Full legal name** (`CLIENT LEGAL NAME LTD`) — the `accountName` returned in the Virtual Account Details response. - **Complete address** (`123 MAIN STREET, DUBAI AE`) — the client's address. - Nium's beneficiary details appear in `:59:` and `:57A:`: - `:57A:` — `routingCodeValue1` or `routingCodeValue2`, depending on `routingCodeType` provided by Nium in the Virtual Account Details response. - `:59:` — `uniquePaymentId` and `accountName` from the Virtual Account Details response. #### ISO 20022 pacs.008 example ```plaintext IntrBkSttlmAmt: USD 10000 Dbtr Nm: PstlAdr StrtNm: 123 Main Street TwnNm: Dubai Ctry: AE DbtrAgt FinInstnId BICFI: MEBLAEAD CdtrAgt FinInstnId BICFI: LHVEE22 Cdtr Nm: NIUM Pvt Ltd CdtrAcct Id Othr Id: ``` Key points: - Message type is **pacs.008** (customer credit transfer). - `Dbtr` (Debtor) includes: - Full legal name — `accountName` from the Virtual Account Details response. - Complete postal address: street, city, and country (for example, `AE`) — the client's address. - `Cdtr` (Creditor) includes: - `Nm` — `accountName` from the Virtual Account Details response. - `CdtrAcct` — `uniquePaymentId` from the Virtual Account Details response. - `CdtrAgt` includes `routingCodeValue1` or `routingCodeValue2`, depending on `routingCodeType` provided by Nium in the Virtual Account Details response. - Debtor and creditor agents are correctly identified with their BICs. #### Common reasons payments are rejected or delayed Your payment to Nium may be **rejected, delayed, or returned** if: - The sender address is **missing or incomplete** (no street, no country, etc.). - Only a **BIC** or bank name is used instead of your full client details. - The **wrong message type** is used (for example, MT202 or pacs.009). - The sender name is **abbreviated** or does **not match your legal name**. #### Pre-send checklist Before sending a wire to Nium, confirm the following with your bank: - [ ] The message type is **MT103** or **pacs.008** (not MT202 or pacs.009). - [ ] Your **full legal name** is included, exactly as provided by Nium in Virtual Account Details (no abbreviations). - [ ] Your **complete physical address** is included (street, city, country). - [ ] You are **not** marked as a financial institution (if you are a corporate client). - [ ] Nium's **beneficiary bank details** and account number are entered exactly as provided by Nium. #### Support If you or your bank are unsure about which message type to use, or how to correctly enter your name and address in the payment message, contact: - Your bank or relationship manager, and/or - Nium Support via the support channels shared with you during onboarding. Reaching out **before sending the payment** helps prevent delays, rejections, or returns. --- # Virtual Accounts URL: https://docs.nium.com/docs/payins/virtual-account-number Virtual account numbers (VANs) are unique account identifiers that enable Nium clients and customers to manage **Virtual account numbers (VANs)** are unique account identifiers that enable Nium clients and customers to manage payments without opening separate bank accounts. You can use VANs to: - **Manage multiple currencies**: Consolidate currency-specific accounts into one platform. - **Automate reconciliation**: Streamline reconciliation through automation at the transaction-level. - **Improve international payment efficiency**: Reduce complexity in cross-border transactions. - **Gain real-time transparency**: Track incoming payments instantly for better visibility and control. ## Understanding virtual accounts A VAN is a unique bank account number associated with a client's or customer's Nium wallet. Customers can use VANs to: - [Self-fund](/docs/payins/fund-wallet#self-fund-wallet): Customers can transfer funds from their own bank accounts ( accounts in their name) directly into their [Nium wallets](/docs/wallets). - [Third Party funding and collections](/docs/payins/fund-wallet#third-party-funds-wallet): Clients and customers can share the virtual account details with third parties to receive the payments directly in their Nium wallets. Each virtual account is unique to: - The wallet currency - The Nium-supported bank associated with that currency For example, a wallet in *SGD* linked with JP Morgan SG will have a different VAN from the same wallet in *AUD* with JP Morgan SG. Virtual account details include: - **Virtual Account Number (VAN):** A unique number linked to your wallet and currency. - **Currency:** The currency of the VAN. - **Account Name:** The name of the account. Can be in the name of the client, customer, or Nium. For more information, see [Virtual account name ](#virtual-account-name). - **Account Type:** Local or Global. For more information, see [Virtual account type](#virtual-account-type). - **Bank Name:** The Nium bank partner receiving the funds. - **Routing Code:** Includes local or global routing codes. For more information, see [Routing details](#routing-details). - **Additional Details:** May include unique payment/payer IDs based on region. ## Virtual account name The **Account Name** helps payers identify the beneficiary of the funds. It's essential for ensuring payment accuracy. When a payment is initiated by a payer, the account name is provided in Beneficiary name. Nium supports VANs with: - **Client’s/Customer’s Name:** Ideal for collections, self-funding and third-party payments. Benefits include: - Enhanced trust and transparency - Easier fund reconciliation - Reduced remittance issues - **Nium's name:** Recommended for self-funding, where the customer or client is initiating the transfer to their own wallet. VAN Account name is dependent on the currency and Nium supported banks. The beneficiary name used in the payment must exactly match the name in the VAN details. Mismatched names can result in payment holds. ## Virtual account type Nium provides two types of VANs, depending on the currency and Nium-supported banks - **Local Account:** Supports payments through local payment methods for faster, cost-effective transfers. - **Global Account:** Supports payments through international wire transfers (SWIFT/WIRES). ## VAN assignment After successful onboarding, clients can request a VAN for a customer wallet using the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) request. - **Immediate Assignment:** VAN is assigned instantly using pre-allocated ranges. - **Delayed Assignment:** VAN status is marked as `INITIALIZED`, and can be assigned within a timeframe (up to 48 hours), depending on the partner bank. A VAN can only be assigned if the customer’s kycStatus is “Clear”. Clients can request the VAN for their own wallet by contacting their Nium account manager or [Nium Support](mailto:support@nium.com) ## VAN details | Payin Country | Account type | Supported Bank | Currency | VAN in name of | Assignment Type | | ------------- | ------------ | ------------------ | --------------------------------------------------------------------- | ----------------------- | --------------- | | AU | Local | `JPM_AU` | AUD | Nium | Immediate | | AU | Local | `Cuscal_AU` | AUD | Customer | Delayed | | AU | Local | `Monoova_AU` | AUD | Customer | Delayed | | AU | Global | `JPM_AU` | USDEURGBPHKD | Nium | Immediate | | AE | Local | `SCB_AE` | AED | | Immediate | | CA | Local | `JPM_CA` | CAD | Nium Canada Corporation | Immediate | | CO | Local | `COBRE_CO` | COP | Nium | Delayed | | DE | Local | `BANKINGCIRCLE_DE` | EUR | Customer | Delayed | | DK | Local | `BANKINGCIRCLE_DK` | DKK | Customer | Delayed | | GB | Local | `CB_GB` | GBP | Customer | Delayed | | HK | Local | `DBS_HK` | HKDUSD | Customer | Delayed | | HK | Global | `DBS_HK` | AUDGBPEURCADCNY | Customer | Delayed | | JP | Local | `GMO_JP` | JPY | Customer | Delayed | | LT | Local | `BOL_LT` | EUR | Customer | Delayed | | MX | Local | `COBRE_MX` | MXN | Customer | Delayed | | PL | Local | `BANKINGCIRCLE_PL` | PLN | Customer | Delayed | | ID | Local | `DBS_ID` | IDR | PT Nium Mitra Indonesia | Immediate | | PH | Local | `NETBANK_PH` | PHP | Customer | Immediate | | SG | Local | `DBS_SG` | SGD | Customer | Immediate | | SG | Local | `JPM_SG` | SGD | Nium PTE LTD CMA | Immediate | | SG | Local | `DIRECTFAST_SG` | SGD | Customer | Delayed | | SG | Global | `DBS_SG` | USD | Customer | Immediate | | SG | Global | `JPM_SG` | USDEURGBPHKDJPYNZDCADSEKDKKNOKAEDCHFCNYTHBPLNHUFILSMXNZARSARCZKAUDTRY | Nium PTE LTD CMA | Immediate | | US | Local | `CFSB_US`\* | USD | Customer | Immediate | | US | Local | `CFSB_USINTL`\*\* | USD | Customer | Immediate | | US | Local | `COLUMN_US` | USD | Customer | Delayed | - \*CFSB\_US VA is provided for customers in US. - \*\*CFSB\_USINTL VA is provided for customers of non-US regions. ### Currency specific exceptions #### United Arab Emirates - AED For AED Local funding via SCB\_AE, an IBAN is required to initiate the transaction. The IBAN is returned in the `uniquePaymentId` field of the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) response. #### Australia - AUD For AUD VAN via `Monoova_AU` or `Cuscal_AU`, a customer can receive a `uniquePaymentId`, such as to initiate the transaction. This information is provided in the `uniquePayerId` field of the [Assign Payment ID](/api#tag/customer-virtual-accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentId) response. #### Brazil - BRL For details on how to fund wallets in Brazil, see [Fund a Wallet - Brazil](/docs/payins/fund-wallet#brazil). #### Canada - CAD For CAD Local EFT Funding and Collections via `PATENO_CA`, the Virtual Account Number (VAN) is a 17-digit string structured as follows: | Segment | Length | Example | Description | | -------------- | -------- | ----------- | ---------------------------------- | | BSB Code | 3 digits | `352` | Bank identifier assigned by Pateno | | Transit Number | 5 digits | `10009` | Branch/transit routing code | | Account Number | 9 digits | `XXXXXXXXX` | Customer virtual account number | **Example:** `352100090000000001` When initiating the EFT transfer, provide the **9-digit Account Number**. ## Routing details Routing information, required to initiate the payment, is accessible via the [Fetch virtual account details](/api#tag/customer-virtual-accounts/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentIds) request using fields like `routingCodeType1`, `routingCodeValue1`, `routingCodeType2` and `routingCodeValue2.`. Below is the list of Routing codes available based on Local and Global account with some examples. | Account Type | Routing Code Type 1 | Routing Code Type 2 | Examples | | ------------ | ------------------- | ------------------------------------ | -------------------------------------------------------------------------- | | Global | SWIFT | | For `JPM_AU`, SWIFT code is CHASAU2X | | Global | SWIFT | Intermediary Bank Code | For JPM\_SG, SWIFT code is CHASSGSG and Intermediary Bank code is CHASGB2L | | Global | SWIFT | Bank code | CITI\_MX – not live for VA | | Global | ACH Code | | doesn’t have value for Column US | | Global | BIC | | only JPM UK | | Local | ABA (ACH) | ABA (Wire) | For CFSB\_US, ACH code is 026073150 and Wire code is 026073008. | | Local | SWIFT | | For DBS\_HK, SWIFT code is DHBKHKHH | | Local | SWIFT | Branch Code | For DBS\_ID, SWIFT code is DBSBIDJA and Branch code is 0307 | | Local | Transit Number | Branch Code | For JPM\_CA, Transit number is 00012 and Branch code is 270 | | Local | Bank Code | Branch or Branch Code or Branch Name | For DBS\_HK, Bank code is 016 and Branch code is 478. | | Local | BIC or BIC Code | | For BOL\_LT, BIC is UAINLT21XXX | | Local | BSB Code | | For `Cuscal_AU`, BSB code is 807125 | | Local | Sort Code | | For CB\_GB, Sort code is 040680 | - **SWIFT Code and BIC:** A SWIFT code or BIC (Bank Identifier Code) is an international identifier used for financial institutions worldwide, typically 8 or 11 characters long, used primarily for international money transfers. Example: BIC code for Citibank in New York, USA is CITIUS33. - **ACH Code:** ACH stands for Automated Clearing House, and the ACH code is used for electronic funds transfers within the United States. It is a 9-digit code used to identify a financial institution in the ACH network. \ Example: The ACH code for Bank of America in New York, USA is 026009593. - **BSB Code:** The Bank State Branch (BSB) code is used in Australia to identify a specific branch of a bank. It is a 6-digit code that is used for direct deposit and other banking transactions. \ Example: The BSB code for Commonwealth Bank in Sydney, Australia is 062-166. - **Bank Code:** A bank code is a unique code assigned to a financial institution by a central bank or regulatory authority. It is used for identifying the bank in banking transactions. \ Example: The bank code for DBS in Hong Kong is 016. - **Transit Number:** The Transit Number is a unique identifier code assigned to each bank branch in Canada by the Canadian Payments Association. It is used for direct deposit and other banking transactions. \ Example: The Transit Number for Royal Bank of Canada in Toronto, Canada is 06400. - **Branch Code:** The Branch Code is a unique identifier code assigned to each bank branch by the financial institution. It is used for identifying the branch location in banking transactions. \ Example: The Branch Code for HSBC Bank in London, UK is 001. --- # Prefund Account URL: https://docs.nium.com/docs/payins/program-client-and-client-prefund-account Program ## Program In the Nium One platform, a program is a logical grouping of clients based on their geographic region or company. Every program can have one or more logo IDs associated with it. Logo IDs specify a region and a bank identification number (BIN), or the first 6 digits on the card. This is a fundamental construct in the platform and has to be mapped with a client at the time of the client creation in the system. Depending on the client use case, BIN, and region requirements, a new program can be defined. If it's not, the existing predefined program is mapped. The client gets access to one or more BIN ranges depending on the associated program. ## Client The client is an enterprise that wants to issue cards for their customers or employees. The client is directly associated with Nium. The customer is the actual cardholder who's onboarded under a particular client. The client entity is created in the system at the time of the client onboarding to manage multiple client-level parameters under this entity. These client-level details are entered into the system based on the program application form filled out by the client as the first step of the client onboarding process. The following configurations are managed at the client level. ### Currencies The platform supports multiple currencies for a customer wallet. These currencies need to be configured at the client level. Based on the client's requirements, these currencies are configured and available for each customer of the client. There would be one base currency or account currency for the wallet. This base currency needs to be configured at the client level, too. ### Virtual accounts A virtual account is a unique reference to an actual Nium bank account generated to send and receive payments. It can be assigned to a client, or to the customers of the client, based on the use case. The client-level configuration for virtual accounts allows the virtual account number generation for clients and their customers. ### Compliance configuration The compliance configuration is specified by the Nium compliance team for clients based on their region, product type, and use case. This configuration is set at the client level and invoked whenever a new customer is onboarded. Based on the configuration, the Know Your Customer (KYC) process is performed. ## APIs Once the client is onboarded completely, and the client-level configuration is completed by the Nium team, then the client can fetch these details using the following API. ### [Client Details](/api#tag/client-settings/GET/api/v1/client/{clientHashId}) API Use your `clientHashId` and `x-api-key` that the Nium team provides you. Example request: ```bash curl -X GET 'https://gateway.nium.com/api/v1/client/{{clientHashId}}' \ -H 'x-api-key: 0mZpIhaLVM1qd8IJhCfgjGJDsY7b5pdr00j' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: client1' ``` You receive the response in the following format: ```json { "name": "Acme Inc", "email": "admin@acme.com", "contactNo": "+6588008100", "markup": 0.5, "clientHashId": "82c68bab-3c04-3451-8d7b-cb38ad713d97", "logoUrl": null, "countryCode": "SG", "clientIdNumber": "", "notificationWebhook": "https://acme-notification.com/webhook", "complianceStatusCallbackUrl": "https://acme-notification.com/callback/compliance?customerHashId=%s", "multiCurrencySupported": false, "deduplicationFlag": false, "customerAuthUrl": null, "prefundName": "Acme Inc", "fundingInstrumentType": "RESTRICTED", "cardTxnRedirectUrl": null, "applePaySupport": false, "googlePaySupport": false, "samsungPaySupport": false, "paymentIds": [ { "currencyCode": "SGD", "uniquePayerId": null, "uniquePaymentId": "8850932057194", "bankName": "DBS_SG" }, { "currencyCode": "HKD", "uniquePayerId": null, "uniquePaymentId": "7770215", "bankName": "DBS_HK" }, { "currencyCode": "SGD", "uniquePayerId": null, "uniquePaymentId": "20024394487", "bankName": "JPM_SG" }, { "currencyCode": "HKD", "uniquePayerId": null, "uniquePaymentId": "20024394487", "bankName": "JPM_SG" }, { "currencyCode": "AUD", "uniquePayerId": null, "uniquePaymentId": "20024394487", "bankName": "JPM_SG" }, { "currencyCode": "USD", "uniquePayerId": null, "uniquePaymentId": "20024394487", "bankName": "JPM_SG" }, { "currencyCode": "EUR", "uniquePayerId": null, "uniquePaymentId": "20024394487", "bankName": "JPM_SG" }, { "currencyCode": "HKD", "uniquePayerId": null, "uniquePaymentId": "800205697", "bankName": "JPM_AU" }, { "currencyCode": "AUD", "uniquePayerId": null, "uniquePaymentId": "800205697", "bankName": "JPM_AU" }, { "currencyCode": "USD", "uniquePayerId": null, "uniquePaymentId": "800205697", "bankName": "JPM_AU" }, { "currencyCode": "EUR", "uniquePayerId": null, "uniquePaymentId": "800205697", "bankName": "JPM_AU" } ], "whitelistedRemitterAccounts": [], "allowThirdPartyFunding": false, "cardTxnProductCode": null, "cardTxnNarrative": null, "complianceCallbackUrl": null, "currencyAuthorizationType": "MULTI", "minimumCustomerAge": 18, "currencies": [ { "currencyCode": "SGD", "decimalUnit": 2, "settlementCurrencyType": "BILLING_CURRENCY", "remittanceAllowed": false, "authorizationOrder": 0 }, { "currencyCode": "AUD", "decimalUnit": 2, "settlementCurrencyType": "BILLING_CURRENCY", "remittanceAllowed": false, "authorizationOrder": 1 }, { "currencyCode": "HKD", "decimalUnit": 2, "settlementCurrencyType": "BILLING_CURRENCY", "remittanceAllowed": false, "authorizationOrder": 2 }, { "currencyCode": "USD", "decimalUnit": 2, "settlementCurrencyType": "BILLING_CURRENCY", "remittanceAllowed": false, "authorizationOrder": 3 }, { "currencyCode": "EUR", "decimalUnit": 2, "settlementCurrencyType": "BILLING_CURRENCY", "remittanceAllowed": false, "authorizationOrder": 4 } ], "accountValidation": false, "regulatoryRegion": "SG", "licenseEntity": "THIRD_PARTY", "ekycRedirectUrl": "https://acme-notification.com/callback/redirect?customerHashId=%s" } ``` ## Client prefund The client prefund process means adding balance to the client account on the platform. This balance can then be used to fund the wallets of customers. The client prefund process involves the following steps. ### 1. Bank transfer You need to transfer money to Nium's bank account—virtual account number—according to the account details provided to the client. After the money transfer, you need to note the *Transfer Reference Number*. ### 2. Initiate prefund request You can do this through the [Client Prefund Request](/api#tag/client-prefund-account/POST/api/v1/client/{clientHashId}/prefund) API. You need to provide all required details, which may include `amount`, `reference number`, `date of transfer`, `currency`, `Nium account number`, `client account number`, and attachments. ### 3. Reconciliation The platform automatically verifies the transaction details and prefund request details. Based on that, it approves the prefund request and the funds are visible in the client prefund account. The following are the client prefund related APIs: #### 3.1 [Client Prefund Request](/api#tag/client-prefund-account/POST/api/v1/client/{clientHashId}/prefund) API This API allows platform clients to raise a prefund request in the system. The client prefund request is initiated after the fund transfer to the provided virtual account number. Example request ```bash curl -X POST "https://gateway.nium.com/api/v1/client/{{clientHashId}}/prefund" \ -H "content-type: application/json" -H "x-api-key: 0mZpIhaLVM1qd8IJhCfgjGJDsY7b5pdr00j" \ -H "x-request-id: 123e4567-e89b-12d3-a456-426655440000" \ -H "x-client-name: client1" -d '{ "bankReferenceNumber": "712347512376", "clientAccountNumber": "615234671328", "comments": "Client Prefund", "currencyCode": "SGD", "dateOfTransfer": "2019-11-24", "niumAccountNumber": "133876812367", "amount": 1000, "requesterId": "8123768123" }' ``` You receive a response in the following format: ```json { "message": "Prefund request added successfully.", "status": "Pending", "amount": 1000, "systemReferenceNumber": "CP8790469553", "uniquePayerId": null, "uniquePaymentId": null } ``` #### 3.2 [Client Prefund Balances](/api#tag/client-prefund-account/GET/api/v1/client/{clientHashId}/balances) API Once the prefund request is approved, you can fetch the information available in the prefund balance using the [Client Prefund Balances](/api#tag/client-prefund-account/GET/api/v1/client/{clientHashId}/balances) API. #### Request example ```bash curl -X GET "https://gateway.nium.com/api/v1/client/{{clientHashId}}/balances" \ -H "x-api-key: 0mZpIhaLVM1qd8IJhCfgjGJDsY7b5pdr00j" \ -H "x-request-id: 123e4567-e89b-12d3-a456-426655440000" \ -H "x-client-name: client1" ``` You receive a response in the following format: ```json [ { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-07-14 05:16:09", "accountType": "CLIENT_POOL", "balance": 0, "currency": "THB", "isDefault": "false" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-07-14 05:16:09", "accountType": "CLIENT_POOL", "balance": 0, "currency": "GBP", "isDefault": "false" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-08-06 04:08:01", "accountType": "CLIENT_POOL", "balance": 4931.185, "currency": "SGD", "isDefault": "true" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-08-06 04:15:01", "accountType": "CLIENT_POOL", "balance": 4981.332, "currency": "USD", "isDefault": "false" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-07-14 05:16:09", "accountType": "CLIENT_POOL", "balance": 0, "currency": "MYR", "isDefault": "false" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-08-06 04:15:01", "accountType": "WALLET_POOL", "balance": 65, "currency": "USD", "isDefault": "false" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-07-14 05:16:09", "accountType": "WALLET_POOL", "balance": 0, "currency": "MYR", "isDefault": "false" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-07-14 05:16:09", "accountType": "WALLET_POOL", "balance": 0, "currency": "THB", "isDefault": "false" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-07-14 05:16:09", "accountType": "WALLET_POOL", "balance": 0, "currency": "GBP", "isDefault": "false" }, { "createdAt": "2020-07-14 05:16:09", "updatedAt": "2020-08-06 04:08:52", "accountType": "WALLET_POOL", "balance": 5, "currency": "SGD", "isDefault": "true" } ] ``` --- # Direct Debit URL: https://docs.nium.com/docs/payins/direct-debit Nium's Direct Debit funding capability helps you add your business customer's bank account to their Nium-issued wallet to help them make payments. ## Prerequisites These are the requirements for this funding mechanism: - Your customer needs to have a bank account and a Nium wallet. - Your customer needs to authorize the Direct Debit mandate to debit from their bank account and accept Nium's terms and conditions (T\&C). - Your customer needs to have enough money in their added bank account to start your transactions. - Your customer needs to be a business, also known as a corporation. - Your customer needs to be onboarded to the Nium One platform. ## Set up To get started with Direct Debit: 1. Accept Nium’s Terms and Conditions. 2. Nium approves requests according to the where Direct Debit is set up. 3. Nium then configures Direct Debit for self-funding to your customer's wallets. 4. Once you complete these steps, you can begin using Direct Debit. Direct Debit is approved on a case by case basis. If you're interested in Direct Debit, reach out to your Nium account manager or [Nium Support](mailto:support@nium.com). ## API server URLs Use the following URLs to separate API calls between different environments. - Sandbox: `https://gateway.nium.com` - Production: `https://api.spend.nium.com` ## Supported countries and currencies The following table shows the supported Direct Debit countries and currencies. For more information, select the Direct Debit page linked in the table for the geography you're interested in. | Country code | Country | Currency code | Currency | | ------------ | ----------------------------------------------------------- | ------------- | :------------------- | | AU | [Australia](/docs/payins/direct-debit/direct-debit-au) | AUD | Australian dollar | | CA | [Canada](/docs/payins/direct-debit/direct-debit-ca) | CAD | Canadian dollar | | EU | [European Union](/docs/payins/direct-debit/direct-debit-eu) | EUR | Euro | | UK | [United Kingdom](/docs/payins/direct-debit/direct-debit-uk) | GBP | Pound sterling | | US | [United States](/docs/payins/direct-debit/direct-debit-us) | USD | United States dollar | | SG | [Singapore](/docs/payins/direct-debit/direct-debit-sg) | SGD | Singapore dollar | ## Direct Debit API endpoints The following APIs support the Direct Debit feature: | HTTP method | API name | Action | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | POST | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Add the funding instrument to your customer's wallet to start a Direct Debit transaction. Use this endpoint to add the payer's physical bank account to the customer's wallet so it can be used for the Direct Debit transaction. Provide the funding instrument's country and currency code. | | GET | [Get Funding Instrument Details](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Get the details of your customer's funding instrument using the `fundingInstrumentId`. This endpoint is optional. The `fundingInstrumentId` is returned as a response in the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | GET | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Get the list of funding instruments registered with your customer. It's optional to use this API. | | POST | [Confirm Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Confirm the funding instrument with one-time password (OTP) authentication. Use this API to communicate the OTP you received from Nium. Nium sends you the OTP during the Add Funding Instrument API call. By confirming the Direct Debit mandate, your customer authorizes Nium to debit payments from their bank account. The debit payments appear on your customer's bank statement as Nium. | | POST | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Fund into your customer's wallet by selecting the funding channel as a `direct_debit` transaction. You also need to provide the `fundingInstrumentId` obtained from the response in the Add Funding Instrument API call. | The following shows the Direct Debit customer wallet flow for all regions. Direct Debit ## Testing Direct Debit You can now test settling funds into a Nium wallet in a sandbox environment almost instantly. This helps you test and integrate Direct Debit flows. Before you begin to test Direct Debit, make sure the following conditions are met: - The client and customer are onboarded to the correct region. - The customer has a wallet set up with the required Direct Debit currency. - The customer has a verified, linked funding instrument available for the correct region and currency. ### Step 1: Start a test Direct Debit Use the [Fund Endpoint](/api#tag/customer-funding/post/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) to pull funds from a verified and linked funding instrument. ```json curl 'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund' \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-Api-Key: YOUR_SECRET_TOKEN' \ --data '{ "amount": 16, "fundingChannel": "DIRECT_DEBIT", "sourceCurrencyCode": "USD", "destinationCurrencyCode": "USD", "fundingInstrumentId": "e18f4c3a-7d9f-4c1d-9a82-58b3d1f6ac91", "statementNarrative": "Simulate Direct Debit settlement" ``` #### Response Example ```json { "destinationAmount": 16, "destinationCurrencyCode": "USD", "paymentMethods": [], "returnUrl": null, "sourceAmount": 16, "sourceCurrencyCode": "USD", "status": "Pending", "systemReferenceNumber": "FW5289214401" } ``` ### Step 2: Testing funds receipt Use the `systemReferenceNumber` from Step 1 to test receiving funds from the linked funding instrument (external bank account). - To test settling funds instantly, set `"coolingOfPeriodInMinutes" to `0`in the`additionalInfo\` object. - This field lets you define a delay (in minutes) before funds are settled. Setting it to `0` bypasses this delay. ```json curl https://gateway.nium.com/api/v1/inward/payment/manual \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-Api-Key: YOUR_SECRET_TOKEN' \ --data '{ "additionalInfo": { "coolingOfPeriodInMinutes": "0" }, "amount": 16, "bankReferenceNumber": "712347512376", "country": "US", "currency": "USD", "payMode": "ACH", "remitterBankName": "CFSB", "transactionId": "FW5289214401", "transactionSource": "ACH", "type": "CREDIT", }' ``` #### Response Example ```json { "message": "ICC request has been processed and published successfully", "success": true } ``` After you complete the steps above, the test Direct Debit transaction will move to **Approved** and the funds will be added to the wallet. This applies to all supported regions and currencies in sandbox environments. ## Use cases You can use the Direct Debit feature for business-to-business (B2B) payments such as employee payroll services or spend management. You can debit your business customer’s bank accounts and load the money into their Nium wallet so you can process their salary and expense payouts. | Use Case | Client type | Example | Funds flow | | :------------------------------------- | :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | | Payroll | Non-financial platform clients | As a payroll platform client, you want to debit a corporate customer's bank account and load money into their Nium wallet. This lets you manage salary and expense payouts. | Corporate customer → Nium → corporate customer’s wallet → corporate customer’s employee | | Spend management and supplier payments | Non-financial platform clients | As a software as a service (SaaS) platform client, you want to debit your customer’s accounts and load money into their wallets. This allows you to process their vendor's invoices and make payments to their vendor. | SaaS platform customer → Nium → SaaS platform customer’s wallet → vendor | | Fintech | Non-financial platform clients | As a fintech platform, you want to direct debit your business customer’s accounts and load money into their wallets. | Fintech business customer → Nium → customer's wallet → spend through a card or payout | The following diagram shows how the Direct Debit transaction flow across different regions. Direct Debit - Overview To learn more about the technical words this guide uses, refer to the [Glossary](/docs/getting-started/glossary). --- # Direct Debit AU URL: https://docs.nium.com/docs/payins/direct-debit/direct-debit-au In Australia, Nium’s platform accepts Direct Debit payments from business customers with an Australian bank account through: - **PayTo** using New Payment Platform (NPP) rails - **Direct Entry (DE)** using \[Bulk Electronic Clearing System (BECS)]\([Bulk Electronics Clearing System (BECS)](https://www.auspaynet.com.au/network/direct-debit-electronic-transfers)) rails Before your customer can use Direct Debit in Australia, the following requirements must be met: - The customer must be a corporate customer. - They must have an Australian bank account with PayTo or BECS Direct Debit enabled and a Nium AUD wallet. - They must authorize the Direct Debit mandate for their bank account and accept [Nium’s terms and conditions (T\&C)](https://www.nium.com/legal). - Their bank account must have sufficient funds to process the transaction. - Only the customer can authorize the Direct Debit mandate for their bank account. For more information, see [Direct Debit](/docs/payins/direct-debit) guide. ## Link and verify bank accounts When customers link their bank account, they are first directed through the PayTo flow. If Nium determines that the customer’s bank account is not enabled for PayTo, the customer is redirected to a fallback flow where they can approve BECS as the payment rail and accept the required BECS terms and conditions. AU Direct Debit For settlement timelines, see [Funding a wallet with Direct Debit](#funding-a-wallet-with-direct-debit). ### Custom payment pages In Australia, customers must complete a Direct Debit Request (DDR) to authorize merchants to debit their bank account through BECS AU, the local Direct Debit scheme. Clients can create their own custom payment pages to collect payment details and the DDR, allowing them to maintain consistent branding. To build a custom payment page: 1. Host your payment pages over HTTPS. 2. Create a page for customers to enter their information. 3. Create a summary and confirmation page. 4. Create a setup success page. 5. Create a page for customers to approve the payment. #### Linking a bank account - PayTo - After onboarding, the customer must link and authorize their external bank account so Nium can pull funds into their wallet. - In your UI, the customer enters their **Account Number** and **BSB Code**, then selects **PayTo** if they know—or are unsure—whether their bank supports PayTo. - The customer must accept the Direct Debit terms and conditions. - Your system captures this by calling the `/addFundingInstrument` endpoint with `channel` **Direct Debit** and `rail` **PayTo**. - Nium checks whether the customer’s bank account is enabled for PayTo. - If PayTo is not supported, you receive a [Funding Instrument Failed](/docs/developers/notifications-and-webhooks/payin-events/funding-instrument-failed) webhook. - When this occurs, prompt the customer to [set up BECS](#linking-a-bank-account---becs) instead and ask them to approve it in your UI. Their existing T\&Cs selection should remain unchanged. - If PayTo is supported, the customer receives a notification from their banking app to approve the PayTo mandate (Payment Agreement). - The customer has **up to 5 days** to approve the mandate. - If they do not approve it within this timeframe, the mandate expires and the bank account setup must be retried. - If they approve it in time, Nium notifies you (using the appropriate webhook) and you should show in your UI that the bank account is approved for PayTo funding. - Because PayTo uses NPP rails, this flow can be completed in near real time once the customer approves the mandate in their banking app. AU Direct Debit #### Linking a bank account — BECS If the customer’s bank does not support PayTo, they can link their account using BECS. Nium sends a BECS mandate email to the customer’s registered contact and approves the bank account after validating the details. Use the BECS linking flow only when PayTo is not supported. AU Direct Debit ##### Example email AU Direct Debit Your UI screens for collecting bank account details and T\&C acceptance for both PayTo and BECS must be approved by Nium. For more information, contact your Nium account manager or [Nium Support](mailto:support@nium.com). ## Funding a wallet with Direct Debit Once a customer’s bank account is linked and authorized, they can initiate a Direct Debit transfer by specifying the AUD amount to deposit into their Nium wallet. To start the transfer, use the [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) request and include the `fundingInstrument` details. Nium automatically determines whether the payment should be processed through PayTo or BECS. You will receive a [Wallet Funded](/docs/developers/notifications-and-webhooks/payin-events/wallet-funded) webhook when the funds are deposited into the customer’s wallet. This webhook includes updated wallet balance details, which you can display in your UI to help customers initiate their next payout. AU Direct Debit AU Direct Debit ### Settlement timelines The time it takes for funds to appear in the customer’s wallet depends on the payment method used—PayTo or BECS: - **PayTo:** Funds typically settle in near real time. - **BECS:** Funds settle within **T+3 days** (three business days after the transaction date). ## Direct Debit requests The following endpoints support Direct Debit: | HTTP method | Request | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | POST | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Adds a funding instrument (the customer’s bank account) to their wallet so Direct Debit payments can be initiated. Provide the country code, currency code, account number, and BSB code. | | GET | [Get Funding Instrument Details](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Retrieves details of a specific funding instrument using the `fundingInstrumentId` (optional). The ID is returned in the response to the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | GET | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Returns a list of funding instruments linked to a customer (optional). | | POST | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Transfers funds into the customer’s wallet using Direct Debit. Provide the `fundingInstrumentId` from the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) response. Debit payments appear on the customer’s bank statement as **Nium**. | ## Mandates You need to get your customer's permission to debit their bank account through a mandate. A mandate is an authorization that the customer provides that gives Nium permission to debit their account. The mandate isn't physically signed by the customer. Once Nium receives an instruction from you via API, it's assumed that your customer has duly agreed to the mandate. After you have that, Nium notifies your customer every time you debit their bank account before each payment. Nium is the service provider to debit the funds from the customer’s bank account. Your customer may cancel a mandate at any time by emailing their bank or financial institution. Canceling a mandate invalidates any future direct debit requests that you issue using this mandate. If you want to accept additional payments from your customer, you need to establish a new mandate with them. ## Chargebacks Customers can ask their bank to reverse a Direct Debit payment for up to *seven years* after the money is added to their Nium wallet. If the bank approves the request, the money is taken out of the customer’s wallet. --- # Direct Debit CA URL: https://docs.nium.com/docs/payins/direct-debit/direct-debit-ca In Canada, Direct Debit transactions are processed using a Pre-Authorized Debit (PAD) scheme. PAD is managed by Payments Canada and operates through the Automated Clearing Settlement System (ACSS). In Canada, Direct Debit transactions are processed using a **Pre-Authorized Debit** (PAD) scheme. PAD is managed by *Payments Canada* and operates through the **Automated Clearing Settlement System** (ACSS). Your business customers in Canada can fund their Nium wallets using PAD. Before they can fund their wallets with Direct Debit transactions in Canadian dollars (CAD), they must first authorize a PAD agreement. This includes: - Providing their: - Bank account number - Transit number - Institution code - Accepting the relevant [Nium terms and conditions](https://www.nium.com/legal/direct-debit-terms). CA Direct Debit ## Requirements To use Direct Debit in Canada, it's required that your customer is onboarded to a **Nium\_CA** entity. Additionally, your underlying customers must meet the following criteria: - Customer must be *corporate customers* (no individual customers). - Underlying customers must have a **presence in Canada** with funds available in a **local bank account**. Once their bank account is linked and the PAD is authorized, your customer can fund their Nium wallet by calling the [/fund endpoint](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) and setting the funding channel to `direct_debit`. ### Settlements Nium’s Direct Debit service is restricted to **self-funding corporate customers only**. This means only an onboarded corporate customer can top up their own wallet to make payouts. This is done by calling the [Fund Wallet](/api#tag/customer-funding/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) request and specifying `Direct_Debit` as the funding channel. There are two options available to settle Direct Debit funds: - [Standard settlement](#standard-settlements): Funds are initiated from the linked bank account and settled into the Nium wallet within **T+4 business days**. For more information, see [Standard settlements](#standard-settlements). - [Faster settlements](#faster-settlements): Available on a **risk-approved basis**, where funds can be settled within the same day. For more information, see [Faster settlements](#faster-settlements). For more information, see [Settlement timelines](#settlement-timelines). ## Transaction limits Direct Debit transactions in Canada are subject to a *$99 million CAD* limit, which is the maximum allowed for this payment rail. However, Nium may apply additional limits based on your business and associated customers. By default, Nium recommends a standard limit of *$250,000 CAD*. - The dollar limit for the overall rail is **$99 million CAD**, though limits may vary by client and customer profile. - Nium recommends standard limits of **$250,000 CAD**, though higher limits can be approved through the [Nium Support](mailto:support@nium.com) team or your Nium Account Manager, based on projected volume. If your projected volumes require higher limits, contact your Nium account manager or [Nium Support](mailto:support@nium.com) team to request an increase. ## Account verification For authorizing and linking bank accounts to initiate Direct Debits, the following methods are available: To initiate Direct Debit in Canada, your customers must first link and authorize their bank account. Nium supports multiple methods for account verification: - [Microdeposit verification](#microdeposit-verification) - [Plaid verification](#plaid-verification) ### Microdeposit verification With Nium’s white-label microdeposit verification method, you can build your own UI to securely link your customer's bank account. 1. The customer enters their bank account details in your UI. 2. Nium sends two small deposits to the customer’s bank account. 3. The customer logs into their online banking and notes the deposit amounts. 4. They enter those amounts in your UI to verify their account. 5. Once verified, Nium sends a webhook notification confirming the account was successfully linked. CA Direct Debit - Microdeposit verification ### Plaid verification Plaid provides an open banking solution for account authorization and linking. 1. The customer invokes the Plaid widget to initiate account verification. 2. The customer selects their bank and logs in for instant authorization. 3. If their bank is unavailable in Plaid’s repository, the customer can opt for the **Plaid Microdeposits** flow: - The customer shares their bank account details and receives a CAD 0.01 deposit with a unique code. - The customer provides this code via the Plaid widget to complete the linkage. ## Settlement timelines For CAD Direct Debits, settlement follows one of two timing options depending on your setup and risk approval. - [Standard settlement](#standard-settlement) - [Faster settlement](#faster-settlement) ### Standard settlements - Timeline: T+4 business days - Cutoff time: 6:30 PM ET - Explanation: T+4 means funds will be available four business days after the transaction is initiated.\ For example, if the transaction starts on a Monday, funds typically settle by Friday (excluding holidays). CA Direct Debit - Standard settlement Once the Direct Debit transactions is initiated, funds are credited to your customer’s wallet within this standard settlement window. ### Faster settlements Faster, same-day settlements are available for eligible customers but **requires prior approval from Nium based on the customer's risk profile**. - To enable faster settlements, contact your Nium Account Manager or [Nium Support](mailto:support@nium.com) to review setup requirements and obtain approval. CA Direct Debit ## Requests To get started, depending on the verification method you choose, use the following requests to verify a customer's account: - [Microdeposits](#microdeposits) - [Plaid](#plaid) *(Instant or Microdeposits)* ### Microdeposits Use the following requests to link a Canadian bank account, verify it with microdeposits, and fund a wallet using Direct Debit. | HTTP Method | API Name | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | [Add Bank Account](/api#tag/accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/bankAccounts) | Submit your customer's bank account details (account number, transit code, and institution number). This starts the microdeposit process—small, random amounts are sent to their bank account for verification. | | `POST` | [Confirm Bank Account](/api#tag/accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/bankAccounts/{bankAccountId}/confirm) | After the microdeposits are received, your customer enters the deposit amounts through this API. If correct, the account is verified. Save the `bankAccountId` returned in the response. | | `POST` | [Set Up Funding Instrument](/api#tag/customer-funding/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Use the `bankAccountId` to create a funding instrument. You’ll get back a `fundingInstrumentId`, which you’ll use for future Direct Debit transactions. | | `GET` | [Fetch Linked Bank Accounts](/api#tag/accounts/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/bankAccounts/{bankAccountId}) | (Optional) Retrieve the list of funding instruments linked to your customer. You can also get details for a specific `fundingInstrumentId` - the `fundingInstrumentId` is returned in the response of the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | `POST` | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Start a Direct Debit transaction by selecting the `"direct_debit"` funding channel and providing the `fundingInstrumentId`. The funds will be pulled from the linked bank account and deposited into your customer’s wallet. On their bank statement, the payment appears as **Nium**. | ### Plaid Customers are redirected to a Plaid-hosted page where they can verify their bank account *(via Instant or Microdeposit verification)*. The `return_URL` is provided in the response of: - For instant verifications, see [**Add funding instrument**](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments). - For microdeposit verification, see [**Confirm Funding Instrument**](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument). After completion, the customer is redirected back to your app or platform based on how the `return_URL` is configured. | HTTP Method | API Name | Action | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | **POST** | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Provide the bank account’s country (CA) and currency (CAD). Ensure `return_URL` is configured. | | **POST** | [Confirm Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) *(Microdeposit only)* | Enter the 3-digit code from the customer’s bank account statement. | | **GET** | [Get Funding Instrument Details](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Retrieve details for a specific funding instrument ID. | | **GET** | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments) | Retrieve the list of registered funding instruments. | | **POST** | [Fund Wallet](/api#tag/customer-funding/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Fund the customer’s wallet by selecting `direct_debit` and providing the `fundingInstrumentId`. | #### Redirect URL After authenticating with Plaid, customers are redirected to your website or app. To keep them updated on their verification status, include the following during Direct Debit setup: - URL to redirect customers to after completing the form - Application URL - Customer host - Port number #### Redirect URL format The following details the format of the URL that'll be generated to redirect customers after they verify their account. ``` URL: GET https://?fundingInstrumentId={fundingInstrumentId}&status={status} ``` It includes the `fundingInstrumentId`, which represents the customer’s linked bank account in Nium, and the verification `status`. ## Testing Direct Debit Before going live, test your Direct Debit integration in your sandbox environment. ### Testing Microdeposits Use the steps below to test microdeposits in your sandbox environment. 1. [Add Bank Account](/api#tag/accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/bankAccounts): Submit valid bank account details to start the microdeposit process. 2. [Simulate Microdeposits](/api#tag/customer/GET/api/v1/simulations/client/{clientHashId}/customer/{customerHashId}/bankAccounts/{bankAccountId}/microDeposits) endpoint: Trigger the deposit of two small, random amounts into the bank account. These simulate real microdeposits from Nium. 3. [Confirm Bank Account](/api#tag/accounts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/bankAccounts/{bankAccountId}/confirm): Enter the microdeposit amounts to verify the account. You’ll receive a `bankAccountId` in the response. 4. [Set Up Funding Instrument](/api#tag/customer-funding/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments): Use the `bankAccountId` to create a funding instrument. You’ll receive a `fundingInstrumentId`. 5. [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund): Use the `fundingInstrumentId` to initiate a Direct Debit transaction. Capture the `systemReferenceNumber` from the response. 6. [Simulate Inward Payment](/api#tag/payin/POST/api/v1/inward/payment/manual) endpoint: Use the `systemReferenceNumber` to simulate the incoming Direct Debit and complete reconciliation. ### Mandates As part of the account verification process, your customer will receive a **Pre-Authorized Debit (PAD)** email. This is a regulatory requirement in Canada. The email serves as formal authorization for Nium to debit funds from the linked bank account. Below is a sample of the PAD authorization email your customer will receive: CA Direct Debit ### Chargebacks Corporate customers have up to **9 business days** to dispute a Direct Debit transaction. If a chargeback request is submitted within this window, Nium will honor the request and return the funds to the customer. --- # Direct Debit EU URL: https://docs.nium.com/docs/payins/direct-debit/direct-debit-eu Nium One platform clients in the European Union can accept Single Euro Payments Area (SEPA) Core Direct Debit payments from business customers with an EU bank account. Nium One platform clients in the European Union can accept [Single Euro Payments Area (SEPA) ](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html#:~:text=Thanks%20to%20the%20Single%20Euro,way%2C%20just%20like%20national%20payments.)Core Direct Debit payments from business customers with an EU bank account. You can use Direct Debit as many times as you want. Direct Debit is a non-real-time payment method from payment creation, to processing, and acknowledgment of its success or failure. Refer to the [Direct Debit](/docs/payins/direct-debit) guide for more information. ## Prerequisites These are the requirements for this funding mechanism: - Your customer needs to have a bank account in the EU with Direct Debit SEPA Core enabled and a Nium EUR wallet. - Your customer needs to authorize the Direct Debit mandate to debit their bank account and accept Nium's terms and conditions (T\&C). - Your customer needs to have enough money in their added bank account to start your transactions. - Your customer is the only person who can authorize the Direct Debit mandate for their bank account. - Your customer needs to be a corporate customer. ## Configuration - Nium approves your Direct Debit mandate setup pages. You can't change these pages without notifying Nium in advance. You need to collect the Direct Debit mandate from your customer, displaying the SEPA customer protection rules to your customer while collecting their bank account details. - During the mandate creation and customer account addition, the customer needs to authenticate themselves with Nium via an email one-time password (OTP) process. - You agree to send advance notifications to your customers three days before initiating the payment request to Nium. ## Direct Debit API endpoints The following APIs support the Direct Debit feature: | HTTP method | API name | Action | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Add the funding instrument to your customer's wallet to start a Direct Debit transaction. Use this API to add the payer's physical bank account to the customer's wallet so that Direct Debit payments can be initiated against it. Provide the funding instrument's country code, currency code, and International Bank Account Number (IBAN). | | GET | [Get Funding Instrument Details](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Get the details of your customer's funding instrument using the `fundingInstrumentId`. This endpoint is optional. The `fundingInstrumentId` is returned as a response in the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | GET | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Get the list of funding instruments registered with your customer. It's optional to use this API. | | POST | [Confirm Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Confirm the funding instrument with OTP authentication. Use this API to communicate the OTP you received from Nium. Nium sends the OTP to the customer through email after the Add Funding Instrument API call. By confirming the Direct Debit mandate, your customer authorizes Nium to debit payments from their bank account. The debit payments appear on your customer's bank statement as Nium. | | POST | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Fund into your customer's wallet by selecting the funding channel as a `direct_debit` transaction. You also need to provide the `fundingInstrumentId` obtained from the response in the Add Funding Instrument API call. The debit payments appear on your customer's bank statement as Nium. | EU Direct Debit > The EU Direct Debit customer experience. ## Payment flow 1. Call the **Add Funding Instrument** API to add your customer’s bank account. 2. Nium sends an email with the OTP to the customer. 3. Call the Confirm Funding Instrument API with the OTP. 4. Nium validates it and returns the `fundingInstrumentId`. 5. Nium sets up the Direct Debit. 6. You and your customer can inquire about the status by calling the Get Funding Instrument Details API. ## Funds flow timeline Direct Debit is a non-real-time payment method and can take 6 days from payment creation to processing, and acknowledgment of its success or failure. EU Funds Flow The EU Direct Debit settlement timing, which takes 6 days. ## Mandates You need to get your customer's permission to debit their bank account through a mandate. A mandate is an authorization that the customer provides, giving Nium permission to debit their account. The mandate isn't physically signed by the customer. Once the customer provides the OTP, which has been verified successfully, they have duly agreed to the mandate. Once you have that, you need to notify your customer every time you debit their bank account at least 3 days before each payment. If you fail to do this, you become liable for any [chargebacks](#chargebacks). Nium is the service provider to debit the funds from the customer’s bank account. It also sends your customer an email with this information 3 days before each payment. Your customer may cancel a mandate at any time by emailing their bank or financial institution. Canceling a mandate invalidates any future direct debit requests that you issue using this mandate. If you want to accept additional payments from your customer, you need to establish a new mandate with them. ## Chargebacks The customer can initiate a dispute with their bank after the funds are credited to their Nium wallet. If their bank agrees, the money is pulled from your customer's Nium wallet as explained below: - 8 months — customers *are not* required to provide any reason - 13 months — customers are required to provide evidence to their bank --- # Direct Debit SG URL: https://docs.nium.com/docs/payins/direct-debit/direct-debit-sg Clients in Singapore can accept eGIRO Direct Debit payments from corporate customers with a Singaporean (SG) bank account. Clients in Singapore can accept [eGIRO](https://www.abs.org.sg/consumer-banking/eGIRO) Direct Debit payments from corporate customers with a Singaporean (SG) bank account. eGIRO Direct Debit is reusable and can be used as many times as needed. Corporate customers that successfully set up eGIRO Direct Debit with their external SG bank account can use it to develop and create recurring direct debit offerings. Please note that direct debits over $200,000 SGD are *non-real-time* and get processed on a delayed timeframe. Notifications for these transactions are not immediate; updates on payment creation, processing, and acknowledgment of success or failure can take some time. For more information, see [Direct Debit](/docs/payins/direct-debit). ## Prerequisites Direct debit is only available for corporate customers. In order to accept and create direct debits, your customer must: - Own a Singaporean (SG) bank account with eGIRO enabled and a Nium SGD wallet. - Verify and authenticate the external bank account that'll be linked to the Nium SGD wallet - Authorize the Direct Debit mandate to debit their bank account and accept Nium's Terms and Conditions (T\&C). - Verify the bank account associated with their Nium wallet has a sufficient balance before the transaction is initiated. ## Verify Bank Account Nium verifies your customer's bank account through eGIRO using instant verification: 1. When you verify a customer's bank account, your customers get redirected to the `return_url` webpage. 2. Here, your customers select the bank account they want to associate with their Nium wallet. 3. Next, the customer verifies ownership by verifying their bank account credentials with the issuing bank to complete verification. The `return_url` is returned in the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) response. ### URL Redirect Setup Once the customer verifies their bank account, they're redirected to your website or application. You receive a webhook event notifying you that the bank account was successfully added to the Nium SGD wallet. Keep your customers up to date on the verification status of their bank account on this website or application page by including the following during Direct Debit setup: - Web page to redirect customers to - Application URL - Customer host - Port The following provides the format of the URL that will be generated to redirect customers. It includes the `fundingInstrumentId` that was created to represent the customer's bank account in Nium and the verification `status`:\ **URL**: GET\ `https://?fundingInstrumentId={fundingInstrumentId}&status={status}` ## Instant Verification To link your customer's bank account to use Direct Debit via instant verification, redirect customers from your website to a page where they can select their bank and get redirected to their bank's website to authorize the connection. Once they authorize the connection with their bank, the customer will need to be redirected back to your website. You'll receive a webhook event notifying you that the account has been successfully added to the wallet. ### Direct Debit - Instant Verification Endpoints The following APIs support Direct Debit instant verification: | HTTP method | API name | Action | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Add the funding instrument to your customer's wallet to start a Direct Debit transaction. Use this API to add the payer's physical bank account to the customer's wallet so that Direct Debit payments can be initiated against it. Provide the funding instrument's country code and currency code. | | GET | [Get Funding Instrument Details](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Get the details of your customer's funding instrument using the `fundingInstrumentId`. This endpoint is optional. The `fundingInstrumentId` is returned as a response in the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | GET | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Get the list of funding instruments registered with your customer. It's optional to use this API. | | POST | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Fund into your customer's wallet by selecting the funding channel as a `direct_debit` transaction. You also need to provide the `fundingInstrumentId` obtained from the response in the Add Funding Instrument API call. | ### Payment Flow 1. Call the Add Funding Instrument API to add your customer’s bank account. 2. The API returns a return URL that lets you redirect the customer to the bank selection page. 3. The customer chooses their bank account and completes the authentication. 4. Nium returns the funding instrument ID. 5. Call the Fund Wallet API to pull funds into the wallet with the correct funding instrument ID. 6. Your customer’s bank account is debited. 7. Nium initiates compliance checks and, after a predetermined time, credits the money to your customer’s wallet. 8. If the customer raises a chargeback, Nium manages the chargeback according to the terms and conditions agreement. SG Direct Debit > The Direct Debit (SG) instant verification flow. ## Funds Flow Timeline The movement of funds depends on the transaction involved: - If the amount of the transaction is under $200,000 SGD, then Nium credits funds in real-time. SG Funds Flow - If the amount is greater than $200,000 SGD, Nium will credit in T+1. SG Funds Flow ## Chargebacks Customers can dispute any transaction with their bank, including eGIRO Direct Debits, **after** funds are credited to their Nium wallet. Please note, for *non-real-time* direct debits, where the transaction is greater than $200,000 SGD, it can take some time (up to 2 days, depending on when direct debit was initiated) for funds to appear in the Nium wallet. --- # Direct Debit UK URL: https://docs.nium.com/docs/payins/direct-debit/direct-debit-uk Nium One platform clients in the United Kingdom can accept Bacs Payment Schemes Limited Direct Debit payments from business customers with a UK bank account using the Bankers' Automated Clearing System (BACS). Nium One platform clients in the United Kingdom can accept Bacs Payment Schemes Limited Direct Debit payments from business customers with a UK bank account using the [Bankers' Automated Clearing System (BACS)](https://www.bacs.co.uk/). You can use Direct Debit as many times as you want. Direct Debit is a non-real-time payment method from payment creation, to processing, and acknowledgment of its success or failure. Refer to the [Direct Debit](/docs/payins/direct-debit) guide for more information. ## Prerequisites These are the requirements for this funding mechanism: - Your customer needs to have a bank account in the UK with BACS Direct Debit enabled and a Nium GBP wallet. - Your customer needs to authorize the Direct Debit mandate to debit from their bank account and accepts Nium's terms and conditions (T\&C). - Your customer needs to have enough money in their added bank account to start your transactions. - Your customer is the only person who can authorize the Direct Debit mandate for their bank account. - Your customer needs to be a corporate customer. ## Configuration - Nium approves your Direct Debit mandate set-up pages. You can't change these pages without notifying Nium in advance. You need to collect the Direct Debit mandate from your customer, displaying the [BACS Direct Debit Guarantee](https://www.bacs.co.uk/media/pu4bmlzs/dd_introduction.pdf) to your customer while collecting their bank account details. - During the mandate creation and customer account addition, the customer needs to authenticate themselves with Nium via an email one-time password (OTP) process. - You agree to send advance notifications to your customers 3 days before initiating the payment request to Nium. ## Direct Debit API endpoints The following APIs support the Direct Debit feature: | HTTP method | API name | Action | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Add the funding instrument ID to your customer's wallet to start a Direct Debit transaction. Use this API to add the payer's funding instrument to the customer's wallet so that Direct Debit payments can be initiated against it. Provide the funding instrument's country code, currency code, account number, and sort code. | | GET | [Get Funding Instrument Details](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Get the details of your customer's funding instrument using the `fundingInstrumentId`. This endpoint is optional. The `fundingInstrumentId` is returned as a response in the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | GET | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Get the list of funding instruments registered with your customer. It's optional to use this API. | | POST | [Confirm Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Confirm the funding instrument with OTP authentication. Use this API to communicate the OTP your customer entered. Nium sends the OTP to the customer through email after the Add Funding Instrument API call. By confirming the Direct Debit mandate, your customer authorizes Nium to debit payments from their bank account. | | POST | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Fund into your customer's wallet by selecting the funding channel as a `direct_debit` transaction. You also need to provide the `fundingInstrumentId` obtained from the response in the Add Funding Instrument API call. The debit payments appear on your customer's bank statement as Nium. | UK Funds Flow > UK Direct Debit flow for customers. ## Payment flow 1. Call the **Add Funding Instrument** API to add your customer’s bank account. 2. Nium sends an email with the OTP to the customer. 3. Call the Confirm Funding Instrument API with the OTP. 4. Nium validates it and returns the `fundingInstrumentId`. 5. Nium sets up the Direct Debit. 6. You and your customer can also inquire about the status by calling the Get Funding Instrument Details API. ## Funds flow timeline Direct Debit is a non-real-time payment method and can take 5 days, from payment creation, to processing, and acknowledgment of its success or failure. UK Funds Flow > The UK Direct Debit settlement timing, which can take 5 days. ## Mandates You need to get your customer's permission to debit their bank account through a mandate. A mandate is an authorization that the customer provides, giving Nium permission to debit their account. The mandate isn't physically signed by the customer. Once the customer provides the OTP, which has been verified successfully, they have duly agreed to the mandate. Once you have that, you need to notify your customer every time you debit their bank account at least 3 days before each payment. If you fail to do this, you become liable for any [chargebacks](#chargebacks). Nium is the service provider to debit the funds from the customer’s bank account. It also sends your customer an email with this information 3 days before each payment. Your customer may cancel a mandate at any time by emailing their bank or financial institution. Canceling a mandate invalidates any future direct debit requests that you issue using this mandate. If you want to accept additional payments from your customer, you need to establish a new mandate with them. ## Chargebacks Your customer can initiate a dispute with their bank after the funds are credited to their Nium wallet for an unlimited time period. If their bank agrees, the money is pulled from the customer's Nium wallet. --- # Direct Debit US URL: https://docs.nium.com/docs/payins/direct-debit/direct-debit-us Nium clients in the United States can accept Automated Clearing House (ACH) Direct Debit payments from business customers with a US bank account. Nium clients in the United States can accept [Automated Clearing House (ACH)](https://www.fiscal.treasury.gov/ach/) Direct Debit payments from business customers with a US bank account. You can use ACH Direct Debit as many times as you want. Direct Debit is a non-real-time payment method from payment creation to processing and acknowledgment of its success or failure. For more information, see [Direct Debit](/docs/payins/direct-debit). ## Prerequisites The prerequisites for Direct Debit include: - Your customer needs to have a bank account in the US with Direct Debit ACH enabled and a Nium USD wallet. - Your customer needs to have sufficient balance in the added bank account before the payment is initiated, for example, when you use the [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) request. - Your customer needs to authorize the Direct Debit mandate to debit their bank account and accept Nium's Terms and Conditions (T\&C). - Your customer's bank account, to be added to the Nium wallet, needs to be verified. - Your customer needs to be a corporate customer. ## Verify and Link External Bank Accounts Before you can directly debit funds, you first need to verify and link the external bank account. There are several ways to authenticate US bank accounts: - [Nium](#nium) - [Micro-deposits](#direct-debit---nium-micro-deposit-verification-endpoints) - [Plaid](#plaid) - [Instant Verification](#plaid---instant-verification) - [Micro-deposits](#plaid---micro-deposits) Micro-deposits through Nium offers more customization compared to Plaid's offering, enabling you to control the entire branding of the customer's experience. > 🚧 NOTE > > Micro-deposits thorugh Nium is currently in early access and subject to further changes. For more information, reach out to you Nium account manager or the [Nium Support Team](mailto:support@nium.com). ### Nium To link your customer’s account with micro-deposits through Nium, first, prompt the customer to enter their bank account details, including the bank account number and routing number. Similar to how Plaid uses micro-deposits to verify bank accounts, your customer should expect to see, within two days, two deposits for random amounts. (less than $1.00) in the bank account they initially entered. The customer's bank account is verified after they provide the exact micro-deposit amounts. Once verified, the bank account is ready to be linked to to customer's Nium Account and initiate Direct Debits. To authenticate a bank account using micro-deposits through Nium: Step 1: Create a Bank Account Verification Create a `bankAccount` resource and include the bank account details provided by the customer. ```curl curl --location --request POST 'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/bankAccounts' \ --header 'x-api-key: X-API-KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "country": "US", "currency": "USD", "accountNumber": "000987654321", "routingCodes": [ { "type": "ach_code", "value": "111000000" } ], "authenticationType": "microdeposit_amounts", "isCustomerAccount": true }' ``` #### Response example ```json { "bankAccountId": "41150875-f86d-462e-b865-ded85fbxxxxx", "accountNumber": "000987654321", "routingCodes": [ { "type": "ach_code", "value": "111000000" } ], "country": "US", "currency": "USD", "verification": "in_progress", "authentication": "in_progress", "authenticationType": "microdeposit_amounts", "isCustomerAccount": true, "createdAt": "2024-04-11T21:45:15Z", "updatedAt": "2024-04-11T21:45:16Z" } ``` The customer can expect to see two micro-deposits within two business days. The `bankAccount` resource includes: - `bankAccount#verification`: Details the status of Nium's attempt to verify the bank account details. - `bankAccount#authentication` Details the status of Nium's attempt to verify account ownership by authenticating the variable micro-deposit amounts. Step 2: Create a Funding Instrument Using the `bankAccountId`, create a `fundingInstrument` for the customer's bank account. The `fundingInstrument` represents the customer's bank account and is used in different requests throughout Nium's API. ```curl curl --location --request POST 'https://gateway.nium.com/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments' \ --header 'x-api-key: X-API-KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "bankAccountId": "{bankAccountId}" }' ``` #### Response example ```json { "fundingInstrumentId": "3041f7a3-3934-411b-835b-e6f4283xxxxx", "bankAccountId": "514db54d-ad3a-47da-9ad4-71558dcxxxxx", "country": "US", "currency": "USD", "maskedAccountNumber": "XXXXXXXX4321", "routingCodes": [ { "type": "ACH_CODE", "value": "111000000" } ], "status": "PENDING", "createdAt": "2024-04-12T13:35:25Z" } ``` Optional: Simulate the Customer Verification Use this request to simulate the customer submitting the amounts of the micro-deposits. ```curl curl --location 'https://gateway.nium.com/api/v1/simulations/client/{clientHashId}/customer/{customerHashId}/bankAccounts/{bankAccountId}/microDeposits' \ --header 'x-api-key: X-API-KEY' ``` #### Response example ```json { "amounts": [0.42, 0.14] } ``` Step 3: Verify Bank Account Authenticate the `amounts` provided by the customer. ```curl curl --location --request POST 'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/bankAccounts/{bankAccountId}/confirm' \ --header 'x-api-key: X-API-KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "amounts": [0.42, 0.14] }' ``` #### Response example ```json { "bankAccountId": "41150875-f86d-462e-b865-ded85fbxxxxx", "accountNumber": "000987654321", "routingCodes": [ { "type": "ach_code", "value": "111000000" } ], "country": "US", "currency": "USD", "verification": "completed", "authentication": "completed", "authenticationType": "microdeposit_amounts", "isCustomerAccount": true, "createdAt": "2024-04-11T21:45:15Z", "updatedAt": "2024-04-12T13:34:13Z" } ``` If the amounts provided are accurate, `bankAccount#authentication` gets updated to **completed** and the `bankAccount` is now verified to initiate Direct Debits. Step 4: Fetch the Funding Instrument If the `fundingInstrument` was created before the `bankAccount#authentication` was **completed**, you'll see `bankAccount#verification` update to **completed** and `fundingInstrument#status` update to **APPROVED** within milliseconds of `bankAccount#authentication` updating to **completed**. Get the `fundingInstrument` details to verify the `status` has updated to **APPROVED** and is ready to use. ```curl curl --location 'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails' \ --header 'x-api-key: X-API-KEY' ``` > Response Example ```json { "bankName": "US Bank", "fundingInstrumentId": "7ac4bc1f-3e81-4766-a908-6231ddd79531", "fundingChannel": "DIRECT_DEBIT", "clientHashId": "94c15268-41fb-4518-8191-a4f7feed17a5", "customerHashId": "8fdc1fd6-3e2c-41f2-9d25-19a7056b60f5", "walletHashId": "fd25a7d3-e8d7-4379-b5a9-e8044d492cae", "saved": true, "status": "APPROVED", "statusDescription": "SUCCESS", "maskedAccountNumber": "XXXXXXXXXXXX1111", "routingType": "ACH CODE", "routingValue": "011401533", "country": "US", "currency": "USD", "createdAt": "2023-01-02 12:21:52", "updatedAt": "2023-01-02 12:27:00" } ``` Based on your business needs, this micro-deposit flow can be altered so bank accounts are verified before the `fundingInstrument` is created. To do so *Verify the Bank Account* before *Creating the Funding Instrument\`*. This ensures `fundingInstruments` are only created for `bankAcounts` with `authentication` **completed**. #### Direct Debit - Nium Micro-deposit Verification Endpoints The following APIs support Direct Debit instant verification: | HTTP method | API name | Action | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Add the funding instrument to your customer's wallet to start a Direct Debit transaction. Use this API to add the payer's physical bank account to the customer's wallet so that Direct Debit payments can be initiated against it. Provide the funding instrument's country code and currency code. | | POST | [Confirm Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Use this API to confirm the payer's physical bank account against your customer's wallet so that Direct Debit payments can be initiated against it. | | GET | [Get Funding Instrument Details](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Get the details of your customer's funding instrument using the `fundingInstrumentId`. This endpoint is optional. The `fundingInstrumentId` is returned as a response in the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | GET | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments) | Get the list of funding instruments registered with your customer. It's optional to use this API. | | POST | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Fund into your customer's wallet by selecting the funding channel as a direct\_debit transaction. You also need to provide the fundingInstrumentId obtained from the response in the Add Funding Instrument API call. | ### Plaid Nium's integration with Plaid is also available for you to verify your customer's bank account. Our integration with Plaid offers **Instant** or **Micro-deposit** verification. When verifying bank accounts with Plaid, your customers get redirected to a web page from Plaid at the `return_url`. On this page, your customers choose how to verify their bank account (**Instant** or **Micro-deposit**) and follow Plaid's experience to complete verification. The `return_url` is available in the response of the following requests: - For **Instant** verification, see [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments). - For **Micro-deposit** verification, see [Confirm Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument). #### Plaid - Instant Verification To link your customer's bank account to use Direct Debit via instant verification, redirect customers from your website to the Plaid website to authorize the connection. To link bank accounts for customers who choose Instant Verification, redirect customers from your website or application to Plaid's website to authorize the connection. Then, on Plaid's website, customers select the bank that holds their account and get redirected to the bank's website to complete authentication and verification. #### Direct Debit - Plaid instant verification requests The following APIs support Direct Debit instant verification: | HTTP method | API name | Action | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Add the funding instrument to your customer's wallet to start a Direct Debit transaction. Use this API to add the payer's physical bank account to the customer's wallet so that Direct Debit payments can be initiated against it. Provide the funding instrument's country code and currency code. | | GET | [Get Funding Instrument Details](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Get the details of your customer's funding instrument using the `fundingInstrumentId`. This endpoint is optional. The `fundingInstrumentId` is returned as a response in the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | GET | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Get the list of funding instruments registered with your customer. It's optional to use this API. | | POST | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Fund into your customer's wallet by selecting the funding channel as a `direct_debit` transaction. You also need to provide the `fundingInstrumentId` obtained from the response in the Add Funding Instrument API call. | 1. Call the Add Funding Instrument API to add your customer’s bank account. 2. The API returns a return URL that lets you redirect the customer to the Plaid page. 3. The customer chooses their bank account to add funds through Plaid and completes the authentication. 4. Nium returns the funding instrument ID. 5. Call the Fund Wallet API to pull funds into the wallet with the correct funding instrument ID. 6. Your customer’s bank account is debited. 7. Nium initiates compliance checks and, after a predetermined time, credits the money to your customer’s wallet. 8. If the customer raises a chargeback, Nium manages the chargeback according to the terms and conditions agreement. US Funds Flow #### Plaid - Micro-deposits To link your customer's bank account to use Direct Debit via micro-deposit verification, they must be redirected from your website to the Plaid website to authorize the connection. Your customer then provides the bank account details to be linked. They then authorize Nium to send a $0.01 micro-deposit to their bank account with a three-letter code that appears in their statement. Your customer authorizes the micro-deposit by entering the code. Micro-deposits are *not* sent in real-time and can take two business days to appear on your customer's bank statement. Details dropdown - Direct Debit - Plaid Micro-deposit Verification Endpoints The following APIs support Direct Debit micro-deposit verification: | HTTP method | API name | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) | Add the funding instrument to your customer's wallet to start a Direct Debit transaction. Use this API to add the payer's physical bank account to the customer's wallet so that Direct Debit payments can be initiated against it. Provide the funding instrument's country code and currency code. | | POST | [Confirm Funding Instrument ID](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Use this API to confirm the payer's physical bank account against your customer's wallet so that Direct Debit payments can be initiated against it. | | GET | [Get Funding Instrument Details](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) | Get the details of your customer's funding instrument using the `fundingInstrumentId`. This endpoint is optional. The `fundingInstrumentId` is returned as a response in the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) request. | | GET | [Get Funding Instrument List](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) | Get the list of funding instruments registered with your customer. It's optional to use this API. | | POST | [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) | Fund into your customer's wallet by selecting the funding channel as a `direct_debit` transaction. You also need to provide the `fundingInstrumentId` obtained from the response in the Add Funding Instrument API call. | > 💁 TIP > > To trigger micro-deposit scenarios in the sandbox environment, use the [Simulate Funding Instrument Status Update (Sandbox Testing)](/api#tag/payouts/POST/api/v1/simulations/transactions/{systemReferenceNumber}/transition) API. Payment flow 1. Call the **Add Funding Instrument** API to add your customer’s bank account. 2. The API returns a return URL that lets you redirect the customer to the Plaid page. 3. If your customer chooses micro-deposit verification, they provide the details of their bank account to be linked, for example, their bank account number, routing code, account name, and account type. Nium then updates the funding instrument status as `Pending` and redirects the customer to the callback URL that you configured during the Direct Debit setup. When your customer receives a micro-deposit, they see a $0.01 deposit. Their account statement shows the sender as Nium and has `ACCTVERFIY` mentioned in the record. They also receive a three-letter code in the `#XYZ` format. 4. You then receive a webhook notification [Direct Debit Micro-Deposit Successful](/docs/developers/notifications-and-webhooks/payin-events/micro-deposit-successful) from Nium once the micro-deposit is sent to the customer account details provided in step 3. 5. After receipt of the webhook, you send a notification to your customer, and you call the Confirm Funding Instrument ID API 6. The API returns a return URL that lets you redirect the customer to the Plaid page again. 7. Your customer enters the three-letter verification code received in their account statement. 8. If the code matches, Nium saves the funding instrument or declines otherwise. 9. Your customer is redirected to your website. 10. Call the Fund Wallet API to pull funds into the wallet with the correct funding instrument ID. 11. Your customer’s bank account is debited. 12. Nium initiates compliance checks and, after a predetermined time, credits the money to your customer’s wallet. 13. If the customer raises a chargeback, Nium manages it according to the T\&C agreement. US DD Funds Flow URL Redirect Setup After your customers complete authentication with Plaid, they're redirected to your website or application. Keep your customers up to date on the verification status of their bank account on this website or application page by including the following during Direct Debit setup: - Web page to redirect customers to - Application URL - Customer host - Port The following provides the format of the URL that'll be generated to redirect customers. It includes the `fundingInstrumentId` that was created to represent the customer's bank account in Nium and the verification `status`:\ **URL**: GET\ `https://?fundingInstrumentId={fundingInstrumentId}&status={status}` ## Funds Flow Timeline The customer's bank has two business days after the day of the debit from their account to reverse the payment. Thus, the cooling-off period takes two business days. The settlement cutoff time for payments is 15:15 EST (19:15 GMT). Payments processed after this time will be processed the next business day. If you have any questions, please contact [Nium support](mailto:support@nium.com). US Funds Flow > The settlement timing for ACH Direct Debit, which takes the standard three days. A faster settlement time option is available to eligible clients after a risk assessment from Nium. Reach out to a Nium sales representative for more information. By creating an ACH Direct Debit mandate, your customer authorizes Nium to debit payments from their bank account. The bank account's last four digits appear on their bank statement as Nium. A faster settlement time option is available to eligible clients after a risk assessment from Nium. Contact [Nium](https://www.nium.com/contact-us) or your Nium account manager representative for more information. ## Chargebacks Your customer can initiate a dispute with their bank within two days for a business bank account after the funds are credited to their wallet. If their bank agrees, the money is pulled from the customer's Nium wallet. --- # Verification of Payee (EU) URL: https://docs.nium.com/docs/payins/verification-of-payee-eu As part of Europe’s Instant Payments Regulation, Nium complies with Verification of Payee (VoP) requirements. As part of Europe’s **Instant Payments Regulation**, Nium complies with **Verification of Payee (VoP)** requirements. Local EUR accounts issued via Nium (through SEPA) must be registered with the VoP regulatory authority. This allows the remitter to verify account details before processing a transaction. If a customer chooses to **opt out** of sharing account information with the VoP scheme, the decision can be submitted to Nium using the [Verification of Payee](/api#tag/beneficiary/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/accountVerification) request. Provide: - `uniquePaymentId`: The virtual EUR account number issued via SEPA - `consent`: Opt-out decision For more information, see [Verification of Payee](/docs/onboarding/vop-guidelines) For questions, contact . --- # Payouts URL: https://docs.nium.com/docs/payouts Nium Payouts lets you send money to over 190 countries and make real-time, on-demand payments in more than 100 countries. Nium Payouts lets you send money to over **190 countries** and make real-time, on-demand payments in more than **100 countries**. With Payouts, funds move instantly from the source to the destination during the transaction. Payments are automatically routed and settled in real time. You can use Payouts to send money to individuals or businesses. Supported transaction types include: - **Individual to Individual (P2P)**: Also called Person-to-Person or Peer-to-Peer. - **Corporate to Individual (B2P)**: Also called Business-to-Person. - **Corporate to Corporate (B2B)**: Also called Business-to-Business. - **Individual to Corporate (P2B)**: Also called Person-to-Business. Payouts can be delivered to a beneficiary’s **bank account, card, digital wallet**, or in some countries, through **cash pickup**. Depending on your region, additional verification can be required before creating `payouts`. For more details, see [Verification of Payee](/docs/onboarding/vop-guidelines). Payouts Overview To explore available payout corridors, visit the [Nium Playbook](https://playbook.nium.com/). You can filter by **country** or **payout method** to see where and how you can send money across the Americas, Europe, the Middle East, Africa, Oceania, and Asia-Pacific. ### Sending Payouts Nium offers several ways to send payouts, depending on your team’s setup. You can use one or a combination of the following: #### API integration Best for: **Technical teams, payroll platforms, and large banks** Integrate directly with Nium’s APIs to automate and scale your payouts. This is ideal for high-volume use cases or extending payout services to your own users. #### Nium Portal Best for: **Small businesses and teams without developers** Use Nium Portal to create single or batch payouts without writing code. The Portal is great for fast onboarding and managing transactions from a browser. #### Nium Connect (SWIFT-Based) Best for: **Banks and financial institutions using SWIFT** Use your existing **MT** or **ISO 20022** message formats to send payments—no API required. Go live faster and route payouts through Nium’s global network. #### Custom integration Best for: **Teams who want flexibility** Combine UI elements, forms, and APIs based on your needs. This option works well if you want to conserve technical resources without losing functionality. ### Payouts overview Payouts Overview TPS limits apply specifically to payout transactions. For request-level rate limits (per second, per day, burst capacity), see [Rate Limits](/docs/15-Developers/01-Nium%20API/05-Usage%20Limits.mdx). If you expect to exceed this TPS limit due to business growth or planned traffic spikes, contact your Nium account manager or [Nium Support](mailto:support@nium.com). ## Local currency wires Nium supports local currency wires to bank accounts in eight countries. This includes: - China - Iceland - India - New Zealand - Saudi Arabia - South Africa - United Arab Emirates - Vietnam For more information, see the [Nium Playbook](https://playbook.nium.com/). ## Foreign exchange For international payouts, our foreign exchange (FX) service automatically converts currencies, streamlining cross-border transfers. For example, a client wants to pay S$5,000 (Singapore dollars) to employees in Singapore from a wallet with $10,000 (United States dollars). Using Payouts on Nium One, you send the money for the payment from your USD wallet with $10K to the SGD wallet that has no money. As part of this transaction, your payment goes through the required foreign exchange (FX) money conversion, which happens during the [Exchange Rate Lock And Hold](/api#tag/quotes-previous-version/GET/api/v1/client/{clientHashId}/exchangeRate) API call before the payout transaction. The FX rate from USD to SGD is $1 USD to $1.33 SGD. So, $5,000 SGD is equivalent to $3,707 USD. Submitting a $3,707 USD payout to an SGD wallet results in a S$5,000 payout. The FX rate used is taken from Reuters® FX service every day of the week, 24/7-including weekends and holiday-with a refresh cycle rate of 15 minutes. The FX rate is based on the currencies used pairs between the source and destination. - The payout fee calculation is done in real-time during the transaction. - Additional configurations are available for Payouts based on the payment methods used. ## Nium Portal You can also use Nium Portal to create a submit payouts. This is helpful for users with less technical expertise that want to avoid the need to build and integration with the Nium API. For more details, see [Nium Portal - Payouts](/docs/nium-portal/batch-payouts). --- # Transfer Money URL: https://docs.nium.com/docs/payouts/transfer-money You can create payouts to transfer funds using one of the following methods: - [Pre-created beneficiary](#pre-created-beneficiary) - [Inline beneficiary details](#inline-beneficiary) - [Batch upload](#batch-upload) - [Batch API](#bulk-api) Select the method based on payout frequency, operational workflow, and automation requirements. ## Payout methods ### Pre-created beneficiary Create a beneficiary once and reuse it across multiple payouts. We recommend pre-creating a beneficiary when you need to create recurring payouts. This reduces payload size, avoids repeated validation, and improves operational consistency. #### Step 1: Create a beneficiary Use the [Create Beneficiary](/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) request. This returns a `beneficiaryHashId` that uniquely identifies the beneficiary. Store the `beneficiaryHashId` for future use. #### Step 2: Create a payout referencing the beneficiary Use the [Create Payout (Remittance)](/api#tag/payouts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) request. Include the stored `beneficiaryHashId` in the request body: ```json { "beneficiary": { "id": "6081219f04fa070017d12e68" }, "payout": { "destinationAmount": 10 }, "purposeCode": "IR005" } ``` Use this method for payroll, vendor payments, marketplace disbursements, and other recurring payouts. ### Inline beneficiary Include beneficiary details directly in the payout request without pre-creating a beneficiary. We recommend creating beneficiaries inline when you need to create one-time payouts. No beneficiary record is stored. Use the [Create Payout (Remittance)](/api#tag/payouts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) request and include all beneficiary details inline: ```json { "beneficiary": { "beneficiary": { "name": "John Doe", "accountType": "CORPORATE" }, "paymentAccount": { "accountNumber": "1234567", "payoutMethod": "LOCAL", "payoutCurrency": "INR", "routingCode": [ { "type": "IFSC CODE", "value": "ICIC0001451" } ] } }, "payout": { "destinationAmount": 10 }, "purposeCode": "IR005" } ``` Use this method for ad-hoc or infrequent transfers when you do not need to reuse a beneficiary. ### Batch upload Submit multiple payouts using a CSV file through Nium Portal. This method is suitable for finance-led workflows and spreadsheet-based processes. - Upload a CSV file in Nium Portal - Validate file rows - Execute the payout batch For more information, see [Batch Payout](/docs/nium-portal/batch-payouts#create-a-batch-payout). ### Batch payout API Submit up to 1,000 payouts in a single API request. We recommend using the Batch Payout request when you need to automate a high volume of payouts. This method is designed for automated platforms, marketplaces, and large-scale payout orchestration. Use the [Create Batch Payout](/api#tag/bulk-payouts) request. Features of the Batch endpoint include: - Per-item status tracking - Bulk-level lifecycle tracking - Webhook notifications - Scheduled execution (`executeAt`) - Idempotency support Each batch can: - Reference a pre-created beneficiary, or - Include inline beneficiary details Use this method when building automated disbursement systems. ## Create quote If currency conversion is required prior to payout, use the [Create Quote](/api#tag/conversions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions) request. Use the returned quote details when creating the payout. ## Upload documents If compliance requires additional documentation, use the [Upload Payout Document](/api#tag/payouts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions/{transactionId}/receipt) request. Documentation requirements vary by corridor and payout type. ## Payout comparison | Requirement | Recommended Method | | ----------------------------- | ----------------------- | | One-time payout | Inline beneficiary | | Recurring payout | Pre-created beneficiary | | Manual spreadsheet workflow | Batch upload | | High-volume automated payouts | Batch endpoint | ## Validation errors If a payout request contains missing or invalid fields, a structured validation error response is returned. This response helps you identify which field caused the error and how to resolve it. ### Error response Validation errors follow the a unified schema: ```json { "code": "field_missing", "description": "Field is missing", "field": "beneficiary.address", "action": "Input the beneficiary address", "regexp": "^.[A-Za-z0-9 -.]{1,255}$" } ``` ### Response body | Field | Description | | ------------- | -------------------------------------------------------------------- | | `code` | Machine-readable error identifier describing the validation failure. | | `description` | Human-readable explanation of the error. | | `field` | The request field that caused the error. | | `action` | Recommended action to resolve the issue. | | `regexp` | Validation pattern required for the field, when applicable. | ### Example response If a payout request is submitted without a beneficiary address, the response can return: ```json { "code": "field_missing", "description": "Field is missing", "field": "beneficiary.address", "action": "Input the beneficiary address", "regexp": "^.[A-Za-z0-9 -.]{1,255}$" } ``` This response indicates that the `beneficiary.address` field was not provided and must be included in the request. ### Legacy schema Newly onboarded customers receive validation errors using the error schema shown above. Some existing integrations may continue to receive validation errors in a previous response format. This does not affect existing integrations. Legacy integrations can adopt the new error schema to use the standardized error structure shown in this section. ### Handling validation errors When building payout integrations, we recommend: - Logging the returned error response - Mapping `code` values to retry or correction logic - Displaying the `description` or `action` message in internal dashboards or operational tools - Validating required fields before submitting payout requests when possible Handling validation errors correctly helps reduce failed payout attempts and improves operational reliability. ## Lifecycle and status tracking After creating a payout: - Retrieve status using the Get Transaction endpoint - Subscribe to webhook events for real-time updates - Handle returned or rejected transactions if applicable - Upload additional documentation if requested See our [Payout Webhooks](/docs/developers/notifications-and-webhooks/payout-events) documentation for event schemas and status transitions. See [Track Payouts](/docs/payouts/track-payouts) for details on how to track payouts. --- # Transaction Lifecycle URL: https://docs.nium.com/docs/payouts/transfer-money/remittance-lifecycle The diagram below outlines the entire journey of a transaction payout (also called a remittance), from its initiation to its completion. See transaction statuses for detailed descriptions of each status a payout goes through. The diagram below outlines the entire journey of a transaction *payout* (also called a *remittance*), from its initiation to its completion. See [transaction statuses](#transaction-statuses) for detailed descriptions of each status a payout goes through. For details on how to create a payout, see [Transfer Money](/docs/payouts/transfer-money). Transaction Lifecycle ## Fetch remittance lifecycle status You can use two fields to fetch transaction statuses: - `systemReferenceNumber` - `externalId` ### System reference number To fetch remittance lifecycle statuses using the `systemReferenceNumber`: 1. Create a payout using the [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) request and note down the `systemReferenceNumber` returned in the response. 2. Fetch the remittance lifecycle status by using the [Fetch remittance lifecycle status](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) request and include the `systemReferenceNumber`. ### Request example ```shell curl 'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit' \ --header 'X-Api-Key: YOUR_SECRET_TOKEN' ``` ### External ID To fetch remittance lifecycle statuses using the `externalId`: 1. Create a payout using the [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) request and include a custom `externalId` - a unique identifier you define to track the transaction for your own reconciliation needs. 2. Fetch the remittance lifecycle status by using the [Fetch Remittance Lifecycle Status](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) request and include the `externalId`. ### Request example ```shell curl 'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit' \ --header 'X-Api-Key: YOUR_SECRET_TOKEN' --header 'externalId: true' ``` ## Payout statuses The following lists all the possible statuses for payout transaction, from initiation to completion, along with their descriptions. | Status | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **AWAITING\_FUNDS** | The transaction is waiting for funding. | | **CANCELLED** | The transaction is cancelled by the customer. For a Payout transaction, typically, this can only be done on scheduled payouts that are not yet initiated. | | **COMPLIANCE\_COMPLETED** | The transaction has cleared compliance review and is ready for further processing. | | **EXPIRED** | The transaction is expired due to insufficient funds or the expiration of the FX rate. | | **IN\_PROGRESS** | The transaction is currently being processed. | | **INITIATED** | The transaction is initiated for processing. | | **PAID** | Money has been sent to the beneficiary bank from Nium's partner bank. | | **PG\_PROCESSING** | Our payment gateway is processing the transaction, and finding the optimal route to process the payment using our partner bank network. | | **REJECTED** | The transaction is rejected by compliance rules. | | **RETURN** | The transaction has been returned by the receiving bank. This status typically applies to a payout transaction when the beneficiary bank returns it for a specific reason. | | **RFI\_REQUESTED** | The transaction has been flagged by compliance rules. Additional information has been requested for this transaction for compliance purposes. | | **RFI\_RESPONDED** | Nium has received the response to the request for additional compliance information requested per RFI. | | **SCHEDULED** | The transaction is scheduled and is going to be processed on the scheduled date. | | **SENT\_TO\_BANK** | The payout instruction has been sent to Nium's partner bank. When the partner bank sends the payment out, the status changes to `PAID`. | ### Substatuses | Status | Substatus | Description | | -------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **PAID** | **PROCESSED\_BY\_CLEARING** | The transaction has been processed by the clearing system and is expected to be credited to the beneficiary. This status typically occurs when Nium does not have full visibility into the transaction’s journey due to clearing or partner limitations. | | **PAID** | **DEEMED\_PAID** | This transaction can be considered **PAID** with a high degree of confidence, as the clearing return window has elapsed without any returns. | | **PAID** | **SENT\_TO\_BENEFICIARY\_BANK** | This suggests that the transaction has reached the beneficiary. If the beneficiary has an active and compliant account then the funds will be credited anytime. | | **PAID** | **SENT\_TO\_BENEFICIARY\_BANK\_ACCOUNT** | This suggests that the funds have reached the beneficiary’s bank account. | --- # Purpose Codes URL: https://docs.nium.com/docs/payouts/transfer-money/purpose-codes Purpose codes are used to identify the purpose of each and every payment. | Purpose Code | Description | | ------------ | ------------------------------------------------------------------------------------------------------- | | IR001 | Transfer to own account | | IR002 | Family Maintenance | | IR003 | Education-related student expenses | | IR004 | Medical Treatment | | IR005 | Hotel Accommodation | | IR006 | Travel | | IR007 | Utility Bills | | IR008 | Repayment of Loans | | IR009 | Tax Payment | | IR010 | Purchase of Residential Property | | IR011 | Payment of Property Rental | | IR012 | Insurance Premium | | IR0012 | Insurance Premium | | IR013 | Product indemnity insurance | | IR0013 | Product indemnity insurance | | IR014 | Insurance Claims Payment | | IR015 | Mutual Fund Investment | | IR016 | Investment in Shares | | IR017 | Donations | | IR01801 | Information Service Charges | | IR01802 | Advertising & Public relations-related expenses | | IR01803 | Royalty fees, trademark fees, patent fees, and copyright fees | | IR01804 | Fees for brokers, front end fee, commitment fee, guarantee fee and custodian fee | | IR01805 | Fees for advisors, technical assistance, and academic knowledge, including remuneration for specialists | | IR01806 | Representative office expenses | | IR01807 | Construction costs/expenses | | IR01808 | Transportation fees for goods | | IR01809 | For payment of exported goods | | IR01810 | Delivery fees for goods | | IR01811 | General Goods Trades - Offline trade | | IR01812 | Logistics (import sea transportation) | | IR01813 | Logistics (export sea transportation) | | IR01814 | Logistics (export air transportation) | | IR01815 | Logistics (import air transportation) | | IR01816 | Logistics (export land transportation) | | IR01817 | Logistics (import land transportation) | | IR020 | Salary | | IR021 | Tax Refund: Commercial / Intermediated | --- # Routing Codes URL: https://docs.nium.com/docs/payouts/transfer-money/routing-codes - SWIFT Code: A SWIFT code is an international bank identifier code used to identify financial institutions worldwide. It is typically 8 or 11 characters long and is used for international money transfers. - **SWIFT Code:** A SWIFT code is an international bank identifier code used to identify financial institutions worldwide. It is typically 8 or 11 characters long and is used for international money transfers.\ Example: BIC code for Citibank in New York, USA is CITIUS33. - **IFSC Code:** The Indian Financial System Code (IFSC) is a unique 11-character code assigned to each bank branch in India by the Reserve Bank of India (RBI). It is used for electronic funds transfer (NEFT, RTGS) in India.\ Example: The IFSC code for HDFC Bank in Mumbai, India is HDFC0000001. - **ACH Code:** ACH stands for Automated Clearing House, and the ACH code is used for electronic funds transfers within the United States. It is a 9-digit code used to identify a financial institution in the ACH network.\ Example: The ACH code for Bank of America in New York, USA is 026009593. - **BSB Code:** The Bank State Branch (BSB) code is used in Australia to identify a specific branch of a bank. It is a 6-digit code that is used for direct deposit and other banking transactions.\ Example: The BSB code for Commonwealth Bank in Sydney, Australia is 062-166. - **SORT Code:** The SORT code is used in the United Kingdom to identify a specific bank branch. It is a 6-digit code used for direct deposit and other banking transactions.\ Example: The SORT code for Barclays Bank in London, UK is 20-65-67. - **Location ID:** The Location ID is a unique identifier code assigned to each bank branch location by the Federal Reserve Bank in the United States. It is used for electronic funds transfer and other banking transactions.\ Example: The Location ID for JPMorgan Chase Bank in New York, USA is 021000021. - **Bank Code:** A bank code is a unique code assigned to a financial institution by a central bank or regulatory authority. It is used for identifying the bank in banking transactions.\ Example: The bank code for Bank of America in the United States is 026009593. - **Transit Number:** The Transit Number is a unique identifier code assigned to each bank branch in Canada by the Canadian Payments Association. It is used for direct deposit and other banking transactions.\ Example: The Transit Number for Royal Bank of Canada in Toronto, Canada is 06400. - **Branch Code:** The Branch Code is a unique identifier code assigned to each bank branch by the financial institution. It is used for identifying the branch location in banking transactions.\ Example: The Branch Code for HSBC Bank in London, UK is 001. ## Examples of Routing Codes | routing\_code\_type\_1 | routing\_code\_value\_1 | | ---------------------- | ----------------------- | | SWIFT | DBSSSGSG | | IFSC | ICIC0003992 | | ACH CODE | 063103915 | | BSB CODE | 802396 | | SORT CODE | 400000 | | LOCATION ID | 11002495 | | BANK CODE | 8004 | | TRANSIT NUMBER | 00507 | | BRANCH CODE | 001 | --- # Failure Codes URL: https://docs.nium.com/docs/payouts/transfer-money/return-codes Learn why transactions fail with standardized ISO 20022 return codes. Learn how to interpret failure messages, troubleshoot issues, and use Nium's recommended actions to resolve payout errors across currencies and countries. When a transaction fails, Nium returns the relevant *ISO return code* to let you know. The International Organization for Standardization (ISO) standardizes messages sent to clients in the event of transaction failures. This standard ensures consistency across currencies, countries, and payout methods. For return codes, Nium specifically uses ISO 20022. Standardized return codes simplify your integration by reducing the need to translate multiple financial codes and messages. ISO 20022, a globally recognized standard, allows you to pass return codes and descriptions to end customers. This helps users understand why a transaction failed and what to do next—saving time and reducing support requests. ISO details appear in both the response of the [Fetch Remittance Lifecycle Status](/api#tag/payout/GET/api/v1/client/%7BclientHashId%7D/customer/%7BcustomerHashId%7D/wallet/%7BwalletHashId%7D/remittance/%7BsystemReferenceNumber%7D/audit) request and the [Remit Transaction Returned](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-returned) webhook event. In the response: - `errorCode`: The ISO return Code. - `errorReasonCode`: The ISO-defined reason for the failure. - `errorDescription`: Nium's human-readable description of the error. ## ISO terms The following terms commonly appear in ISO definitions and return codes used throughout Nium’s transaction failure messages. | **Term** | **Description** | | ---------------------- | -------------------------------------------------------------------------------------------------------- | | Creditor | The beneficiary of the transaction — the person or entity receiving the funds. | | Debtor | The remitter or sender — the person or entity sending the funds. | | Dormant Account | An account that has been inactive for a specific period. | | Identification Code | A unique number used to identify an account, customer, or institution. | | End Customer | The beneficiary who ultimately receives the funds. | | Clearing System | A financial network that processes, reconciles, and settles transactions between financial institutions. | | Remittance Information | Details about a transaction, such as purpose, amount, and parties involved. | ## Return codes The table below lists common ISO 20022 return codes along with Nium's recommended actions. Use this table to identify why a transaction failed and how to resolve it. You can use these messages in your app or client communications. For more information on the different ISO codes, see [ISO 20022](https://www.iso20022.org/). | ISO Code | ISO Definition | Description | Recommended Action | | -------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AB05 | TimeoutCreditorAgent | Transaction timed out at the creditor's bank. | *Temporary issue* - Check your wallet for a refund. If refunded, reinitiate the transaction. | | AB06 | TimeoutInstructedAgent | The transaction timed out at the instructed agent (typically the intermediary or receiving bank). | *Temporary issue* - Check your wallet for a refund. If the funds were returned, retry the transaction. | | AB08 | OfflineCreditorAgent | The creditor's bank is offline. | *Temporary issue* - Nium couldn’t connect to the beneficiary's bank. Check your wallet for a refund. If refunded, reinitiate the transaction. | | AC01 | IncorrectAccountNumber | The beneficiary's account number format is invalid. | Confirm the correct `beneficiary.accountNumber` with the beneficiary.Use [Nium Verify](/docs/verify) to validate account details before [adding a beneficiary](/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) or [creating a payout](/docs/payouts/transfer-money). | | AC03 | InvalidCreditorAccountNumber | The beneficiary's account number is invalid or missing. | Confirm the correct `beneficiary.accountNumber` with the beneficiary.Use [Nium Verify](/docs/verify) to validate account details before [adding a beneficiary](/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) or [creating a payout](/docs/payouts/transfer-money). | | AC04 | ClosedAccountNumber | The beneficiary's account is closed. | Ask the beneficiary for updated account details. | | AC06 | BlockedAccount | The beneficiary's account is blocked, dormant, or inactive. | Request updated account details from the beneficiary. | | AC08 | InvalidBranchCode | The branch code is invalid or missing. | Confirm the routing code is correct.Use the [Search Routing Code](/api#tag/reference-data/GET/api/v2/client/{clientHashId}/payout/branches) request.If valid but unsupported, contact [Nium support](mailto:support@nium.com). | | AC09 | InvalidAccountCurrency | The account doesn’t support the quoted currency. | Confirm with the beneficiary which currencies the account supports.Use the Nium [Playbook](https://playbook.nium.com/) or [Fetch Supported Corridors](/api#tag/reference-data/GET/api/v3/client/{clientHashId}/supportedCorridors) request to check if Nium supports the currency and available payout methods for the beneficiary's country and currency. | | AC12 | InvalidAccountType | The beneficiary’s account type is invalid. | `beneficiary.accountType` is not supported for the selected payout method. | | AC13 | InvalidDebtorAccountType | The sender’s account type is missing or invalid. | The `remitter.accountType` is not supported for the selected payout method. | | AG01 | TransactionForbidden | The transaction is prohibited due to regulatory restrictions. | Ask the beneficiary for an alternative bank account or payout method. | | AG03 | TransactionNotSupported | The transaction type is not supported on the beneficiary's account. | Ask the beneficiary for an alternative bank account or payout method. | | AM09 | WrongAmount | The received amount differs from the expected amount. | Reinitiate the transaction with the correct amount. | | AM13 | AmountExceedsClearingSystemLimit | The transaction amount exceeds clearing system limits. | Reinitiate the transaction with a lower amount. | | AM21 | LimitExceeded | The transaction amount exceeds the allowed limit. | Use the [Nium Playbook](https://playbook.nium.com/) or [Fetch Supported Corridors](/api#tag/reference-data/GET/api/v3/client/{clientHashId}/supportedCorridors) request to check per-user payout limits.If within limits, ask the beneficiary to check with their bank for any additional restrictions. | | BE07 | MissingDebtorAddress | The sender’s address is missing or incorrect. | Retry the transaction and include all required address details.Use the [Nium Playbook](https://playbook.nium.com/) or [Fetch Supported Corridors](/api#tag/reference-data/GET/api/v3/client/{clientHashId}/supportedCorridors) request to confirm required fields. | | BE10 | InvalidDebtorCountry | The sender’s country code is missing or invalid. | Ensure `remitter.countryCode` or `originatingFICountry` (for on-behalf payouts) is valid. Retry with correct details. | | BE11 | InvalidCreditorCountry | The beneficiary’s country code is missing or invalid. | Ensure `beneficiary.countryCode` is valid.[Update the beneficiary details](/api#tag/beneficiary/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) and retry the transaction. | | BE16 | InvalidDebtorIdentificationCode | The sender’s identification number is missing or invalid. | Retry using the correct `remitter.identificationNumber` format. | | BE17 | InvalidCreditorIdentificationCode | The beneficiary’s identification code is missing or invalid. | Ask the beneficiary for a correct `beneficiaryIdentificationValue`. | | BE18 | InvalidContactDetails | The beneficiary’s contact details are missing or invalid. | Ensure `beneficiaryEmail`, `beneficiaryContactNumber`, or `beneficiaryContactName` are valid.[Update the beneficiary details](/api#tag/beneficiary/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) and retry the transaction. | | CUST | CustomerDecision | Transaction cancelled at the request of the customer. | No action required. The transaction was cancelled by the sender. | | BE23 | AccountProxyInvalid | The phone number, email address, or other proxy used as the account identifier is invalid or unrecognized. | Confirm the correct proxy with the beneficiary, based on the required account number format.Use [Nium Verify](/docs/verify) to validate proxy details before [adding a beneficiary](/api#tag/beneficiary/POST/api/v2/client/%7BclientHashId%7D/customer/%7BcustomerHashId%7D/beneficiaries) or [creating a payout](/docs/payouts/transfer-money). | | DS04 | OrderRejected | The bank rejected the order. | Ask the beneficiary to contact their bank. If rejected in error, retry the transfer. | | DUPL | DuplicatePayment | Duplicate of a previous payment. | If intentional, retry the transfer. | | FF06 | InvalidCategoryPurposeCode | The category purpose code is missing or invalid. | `purposeCode` is unsupported for this payout. Try a different `payoutMethod`. | | FF07 | InvalidPurpose | The transaction purpose is missing or invalid. | `purposeCode` is unsupported for this payout method. Try a different `payoutMethod`. | | FF10 | BankSystemProcessingError | Bank system error prevented transaction processing. | *Temporary issue* – Retry the transfer. Nium automatically retries transactions before returning this error. | | FOCR | FollowingCancellationRequest | Transaction returned as requested. | You requested the return of this transaction. | | MD06 | RefundRequestByEndCustomer | The end customer requested a refund. | Contact the beneficiary to confirm the refund reason. | | MD07 | EndCustomerDeceased | The end customer is deceased. | Return the funds to the original sender. | | MM20 | MismatchCreditorNameAccount | The `beneficiaryName` does not match the name registered with the beneficiary’s account. | Update the `beneficiaryName` to match the account holder’s name, then send the transfer again. | | MS02 | DebtorRefusal | The transaction could not be processed due to internal compliance requirements. | Contact [Nium Support](mailto:support@nium.com) if additional clarification is required. | | MS03 | NotSpecifiedReasonAgentGenerated | No return reason provided by the bank. | Provided when data protection laws restrict specific return codes. | | MS18 | MissingRelatedRemittanceInformation | Required transaction details are missing. | Confirm all required fields and retry the transaction. | | NARR | Narrative | Return reason provided in transaction response. | Check the transaction response for details. | | NOCM | NotCompliant | The beneficiary's account doesn’t meet regulatory requirements (e.g., FICA). | Return the funds to the original sender. | | RC01 | BankIdentifierIncorrect | The bank identifier code format is invalid. | Verify the routing code.Use the [Search Routing Code](/api#tag/reference-data/GET/api/v2/client/{clientHashId}/payout/branches) request.If valid but unsupported, contact [Nium support](mailto:support@nium.com). | | RC02 | InvalidBankIdentifier | The routing code is missing or invalid. | Verify the routing code.Use the [Search Routing Code](/api#tag/reference-data/GET/api/v2/client/{clientHashId}/payout/branches) request.If valid but unsupported, contact [Nium support](mailto:support@nium.com). | | RC07 | IncorrectClearingSystemMemberIdentifier | The routing code or the combination of beneficiary account number and routing code is incorrect. | Verify the routing code and `beneficiary.accountNumber` belong to the same bank.If valid but unsupported, contact [Nium support](mailto:support@nium.com). | | RR03 | MissingCreditorNameOrAddress | The `beneficiaryName` and/or `beneficiaryAddress` is missing or incomplete, as required by regulation. | Verify the `beneficiaryName` and `beneficiaryAddress`, then send the transfer again. | | RR04 | Regulatory Reason | The transaction failed due to regulatory restrictions. | Return the funds to the original sender. | --- # Tracking Wires URL: https://docs.nium.com/docs/payouts/transfer-money/tracking-wires Considering SWIFT cross-border transactions are passed to multiple correspondent banks, these transactions take time to reach the intended beneficiaries. With GPI tracking, you can review the intermediary status details for SWIFT wire transactions. GPI tracking is only available for SWIFT wire transactions. Some of the benefits of using SWIFT GPI include: - **Tracking delayed transfers**: SWIFT GPI can be used as an effective alternative to the **MT103** SWIFT message type to track delayed transfers. - **Increased visibility and transparency**: Use the additional details provided by SWIFT GPI to enhance visibility and transparency, which, in turn, will help reduce the number of queries you receive from your customers. - **More transaction details**: SWIFT GPI provides more details about transactions and how they're being processed. In addition to tracking delayed transfers, you use this additional information to enhance your customer's experience by creating transaction timelines on your platform or by sharing these details directly via texts/emails for those who prefer messages. See the graphic below for an example of a transaction timeline. Get a card widget ## How do I access GPI details? GPI details can be obtained through the `gpi` object in the following request and event: - [Fetch Remittance Lifecycle](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit) request - [Remit Transaction Sent To Bank](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-sent-to-bank) webhook event The Nium One client dashboard also displays GPI details at the transaction level in the **Remittance Transaction Reports** section. ### GPI parameters | Field | Description | | ------------------- | --------------------------------------------------------------------------------------------------- | | `reasonCode` | GPI code shared by the SWIFT partner bank | | `statusDescription` | Description of the GPI reason code | | `timestamp` | Date and time of the last status change | | `forwardBankName` | Name of the next participant bank to which the payment has been forwarded. | | `forwardBankCode` | Bank identification code (BIC) of the next participant bank to which the payment has been forwarded | | `remarks` | Detailed description of the `reasonCode`. This interpretation is provided directly by Nium. | ## GPI reason codes and status descriptions | `status` | `gpi#reasonCode` | `gpi#statusDescription` | `gpi#remarks` | | :------------- | :--------------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SENT_TO_BANK` | G000 | Delivered to the next bank | The payment has been forwarded to the next participant bank in the SWIFT network. It can be either credited to the beneficiary directly or passed to the next bank. | | `SENT_TO_BANK` | G001 | Delivered to the next bank (no tracking) | This often suggests the user may not receive GPI updates beyond this point and will receive a final terminal status. | | `SENT_TO_BANK` | G002 | Pending credit may not be same day. | Often it means that the payment is under manual due diligence in the bank and settlement may take a few hours. | | `SENT_TO_BANK` | G003 | Pending receipt of documentation from the beneficiary. | This often suggests an action on the beneficiary or beneficiary bank. The sender may contact the beneficiary in case of delays or can ensure that the beneficiary details provided are correct. | | `SENT_TO_BANK` | G004 | Pending receipt of funds from the previous bank. | This suggests the forward bank (next SWIFT network bank) has received an instruction to credit the funds to the beneficiary but it has not received the funds yet. Cover payment is missing but it is expected to arrive soon. The funds are expected to reach the beneficiary upon arrival of cover payment. | | `SENT_TO_BANK` | G005 | Delivered to beneficiary bank as GPI. | This suggests that the payment will be credited soon. | | `SENT_TO_BANK` | G006 | Delivered to beneficiary bank as non GPI. | This suggests that the payment will be credited soon. | --- # Estimated Delivery Time URL: https://docs.nium.com/docs/payouts/transfer-money/estimated-delivery-time Nium provides the estimated delivery times for payout transactions using the estimatedDeliveryTime field in the Remit Transaction Initiated webhook event. Nium provides the **estimated delivery times** for payout transactions using the `estimatedDeliveryTime` field in the [Remit Transaction Initiated](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated) webhook event. This lets product, operations, and engineering teams set accurate expectations with end users, track SLA adherence, and act quickly when a payout is delayed. Knowing the an estimated of when funds will be available helps you: - Communicate with customers. - Accurately track SLA. - Proactively handle exceptions or escalations. When a payout is created, Nium triggers a [Remit Transaction Initiated](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated) webhook event (e.g., `REMIT_TRANSACTION_SENT_TO_BANK_WEBHOOK`). The event includes a `estimatedDeliveryTime` field. `estimatedDeliveryTime` is filled with a **UTC timestamp** (ISO 8601 format) indicating when funds are expected to be delivered. The value is calculated based on Nium’s **pre-configured rules for each payout corridor**. Factors include: | Factor | Description | | ------------------------------ | ---------------------------------------------------------------------------- | | **Routing Configuration** | Based on the clearing scheme optimized for the specific transaction. | | **Processing Cut-off Times** | Clearing-specific cut-off timings based on source and destination corridors. | | **Public Holidays & Weekends** | Observed in both the sending and receiving countries. | | **Partner Constraints** | Operating hours, system maintenance windows, and technical limitations. | The delivery estimate reflects how Nium expects the transaction to progress under normal operating conditions. ## Using `estimatedDeliveryTime` To get the most value from this field: 1. **Subscribe to payout webhooks**\ Ensure you’re integrated with Nium’s webhook infrastructure so you receive the `estimatedDeliveryTime` value at transaction initiation. 2. **Parse the timestamp**\ Use the value to: - Display ETA to end users in your transaction UI (**product & ops**) - Trigger alerts for potential SLA breaches (**engineering**) - Compare estimated vs. actual delivery times for SLA reporting (**ops & compliance**) 3. **Handle missing values**\ If the field is omitted or `null`, reach out to your Nium account representative to confirm corridor coverage. ### Example Payload ```json { "template": "REMIT_TRANSACTION_SENT_TO_BANK_WEBHOOK", "systemReferenceNumber": "RT4589947391", "estimatedDeliveryTime": "2025-07-22T23:29:33Z", ... } ``` The `estimatedDeliveryTime` field uses ISO 8601 timestamp format in UTC. If a delivery estimate cannot be calculated for a specific transaction, the field may be omitted or returned as null. ## Service level agreement (SLA) The `estimatedDeliveryTime` field is included in these webhook templates: - `REMIT_TRANSACTION_SENT_TO_BANK_WEBHOOK` - `REMIT_TRANSACTION_PROCESSING_WEBHOOK` (if applicable) ## Common questions Q: Is the delivery time guaranteed? A: No. It reflects Nium’s best estimate based on known routing behavior and partner schedules. Actual delivery may vary depending on external factors. Q: How is this different from payout status updates? A: This SLA is provided at the start of the transaction and reflects how Nium expects the payout to progress. Statuses like `SENT_TO_BANK` or `PAID` indicate actual transaction events. Q: Can I notify end users based on this SLA? A: Yes. Many clients use this field to inform beneficiaries about expected delivery times. However, we recommend pairing it with real-time status updates for confirmation. Q: What if the field is missing in my webhook? A: This feature depends on your setup. If the field is missing, please contact your Nium account representative for support. ## Resources - [Nium Payout Playbook](https://playbook.nium.com) – Corridor-specific SLAs and payout logic. - [Webhook Guide](/docs/developers/notifications-and-webhooks) – Webhooks supported by Nium. - [Transaction Lifecycle](/docs/payouts/transfer-money/remittance-lifecycle) – Understanding payout statuses and transitions. --- # Payout Validator URL: https://docs.nium.com/docs/payouts/transfer-money/payment-validator The Payout Validator request checks whether a payout request will succeed before you debit your customer’s account or call the Transfer Money request. The **Payout Validator** request checks whether a payout request will succeed *before* you debit your customer’s account or call the [Transfer Money](/docs/payouts/transfer-money) request.\ It uses the same request body as the **Transfer Money** request, but instead of creating a transaction, it returns a *validation result* with details on any issues found. ## Business impact The Payout Validator request lets you confirm whether a payout will succeed before debiting your customer’s account or calling the [Transfer Money](/docs/payouts/transfer-money) request. This gives customers upfront visibility into why a transaction might fail—improving their experience and reducing support queries. For example, you can wait to debit a customer’s account until the Payout Validator returns a success response. This prevents unnecessary debit/credit cycles and lowers operational overhead. ## Differentiation Validator responses are grouped into error categories (such as `field_missing`, `incorrect_format`, and `not_allowed`). By handling errors at the category level, your integration stays compatible as new error codes and descriptions are added. This reduces long-term maintenance and ensures consistent validation behavior across requests. ## Scope & control The Validator checks more than field formats. It also validates: - Corridor and rail rules - Source currency configurations - Platform limits (such as remittance thresholds and FX setup) These validations mirror the checks performed by the Transfer Money request, so payouts that pass the validator are far less likely to fail at execution. ## Development Traditional requests often return error codes that change or expand over time. The Validator simplifies this by standardizing responses into categories, such as: - `field_missing`: Required field not provided. - `incorrect_format`: Wrong regex/length/checksum. - `incorrect_value`: Value outside allowed range. - `unsupported_field`: Field not valid for this corridor. - `invalid_combination`: Fields conflict. - `not_allowed`: Client lacks entitlement. By coding once against these categories, applications remain stable even as new error codes are introduced—reducing rework and keeping integrations consistent. ## API request ```http POST /api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/validate Content-Type: application/json Authorization: Bearer ``` ## Responses ### 200 valid ```json { "valid": true, "issues": [] } ``` ### 200 not valid ```json { "valid": false, "issues": [ { "code": "field_missing", "category": "field_missing", "description": "Beneficiary account number is required for USD payouts", "field": "beneficiary.account_number", "action": "Provide a valid account number" }, { "code": "incorrect_format", "category": "incorrect_format", "description": "IBAN must be 22 characters starting with 'DE'", "field": "beneficiary.iban", "regex": "^[A-Z]{2}[0-9]{20}$" } ] } ``` ### 400 ```json { "errors": [ { "code": "invalid_client_hash_id", "description": "The clientHashId provided is invalid" } ] } ``` ## Field definitions | Field | Description | | ------------- | ----------------------------------------------------------------------------- | | `valid` | `true` if no errors.`false` otherwise. | | `issues` | An array of validation findings. | | `code` | Category identifier (`field_missing`,`incorrect_format`). | | `field` | Dot-notation path to the field with the issue (`beneficiary.account_number`). | | `description` | Human-readable explanation of the issue. | | `action` | Recommended fix for the client or developer. | | `regex` | Regex pattern used for validation (optional; for developer use). | ## Error categories The Payout Validator groups errors into **categories** so you can handle them consistently. - **User-fixable errors**: Should be surfaced to the end user, so they can correct inputs and retry. - **Config-only errors**: Internal issues related to client setup or entitlements. These should not be exposed to end users; instead, route internally to support or ops teams. | Category | When it applies | Example Issue | Client Handling | Developer Tip | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **field\_missing** *(User-fixable)* | A required field (including conditional ones) is not provided. | `beneficiary.accountNumber is required for USD payouts.` | Prompt the user to provide the missing field; highlight the input. | Map to your own “required field” validation so users see this inline before submission. | | **incorrect\_format** *(User-fixable)* | A field is present but fails validation for format, length, charset, or checksum. | `beneficiary.accountNumber must be 22 characters starting with 'DE'.` | Validate client-side and display the correct format. | Reuse regex or format hints in your form validation to avoid unnecessary server calls. | | **incorrect\_value** *(User-fixable)* | A field is correctly formatted but violates business rules (range, allowed values, corridor support). | `currency EUR not supported for this route.` | Show allowed values or ranges for correction. | Use [Nium’s Supported Corridors request](/api#tag/payout/GET/api/v3/client/{clientHashId}/supportedCorridors) to fetch corridor and currency lists dynamically instead of hardcoding. | | **unsupported\_field** *(User-fixable)* | A field is provided but not permitted for the corridor or client configuration. | `proxy_identifier not supported in US payouts.` | Hide or remove this field in the client UI for the given context. | Use [Nium’s Supported Corridors request](/api#tag/payout/GET/api/v3/client/{clientHashId}/supportedCorridors) to fetch **mandatory/optional fields** dynamically instead of hardcoding. | | **invalid\_combination** *(User-fixable)* | Fields are valid individually but conflict when used together. | `Provide either bankCode or routingCode, not both.` | Highlight both fields and guide the user to choose one. | Implement combination rules in client validation so users see this inline before submission. | | **not\_allowed** *(Config-only)* | Input is valid in general but blocked by entitlements, role, or client setup. | `KRW payouts not enabled for this account.` | Do **not** show this to the end user; treat as a configuration-only issue. | Flag as a config error so it’s routed to support or ops. Contact Nium Support if the feature must be enabled. | | **validation\_error** *(Config-only)* | Catch-all for issues not covered by other categories (temporary or edge-case errors). | `Transaction object failed validation.` | Show a generic error if needed; escalate to Nium Support if recurring. | Treat as a fallback: log for monitoring, alert ops, and raise to Nium Support if recurring. | ## Integrating Payout Validator ### Step 1: Call the Payout Validator request - Send the payout request to the [Payout Validator](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/validate) endpoint. - Do **not** use the Transfer Money request to debit funds from the sender's account yet. ```pseudo response = call(PayoutValidator, payoutRequest) if response.valid == false: handle(response.issues) stop here ``` ### Step 2: Handle issues by category Group errors by **category** rather than individual error codes. This keeps your integration stable as Nium introduces new error codes. ```pseudo for each issue in response.issues: if issue.category in ["field_missing", "incorrect_format", "incorrect_value", "unsupported_field", "invalid_combination"]: highlightField(issue.field, issue.description) else if issue.category == "not_allowed": flagInternalConfig(issue) else: log("Validator issue", issue) showBanner("error", "We couldn't validate this payout.") ``` ### Step 3: If `valid` is true, debit funds and Transfer Money When `response.valid` is **true**: - Create a payout and debit the customer's account. - Submit the payout using the **Transfer Money** request. ```pseudo if response.valid == true: debit(customerAccount, payout.amount) call(TransferMoney, payoutRequest) ``` ## Best practices - Use the Payout Validator request before debiting funds to prevent reversals. - Log the `code` for easier debugging with Nium Support. - Cache corridor-level details: (for example, supported methods) briefly to reduce repeat validations. - Show messages inline in the UI: for quick correction, and use banners or logs as fallback for system errors. ## Resources - [Transfer Money](/docs/payouts/transfer-money) - [Payout Validator](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/validate) --- # Payout Rail Preference URL: https://docs.nium.com/docs/payouts/transfer-money/payout-rail-preference By default, Nium selects the optimal payout rail for each transaction based on internal routing logic — factoring in cost, coverage, and speed. The Payout Rail Preference feature lets clients override this default and specify how their payments should be routed, per corridor or per payment. By default, Nium selects the optimal payout rail for each transaction based on internal routing logic — factoring in cost, coverage, and speed. The **Payout Rail Preference** feature lets clients override this default and specify *how* their payments should be routed, per corridor or per payment. This is useful when you need to guarantee real-time delivery, optimise for cost, or ensure consistent settlement behaviour across a product line. ## Why It Matters Without rail preference, clients have limited visibility or control over which rail Nium uses. With this feature, you can: - Guarantee **real-time routing** for specific corridors (e.g. always use FPS for GBP, never CHAPS) - Optimise for **cost or speed** depending on your use case - Give your end users a **predictable, consistent payment experience** - Advertise specific SLAs confidently, knowing Nium will not silently downgrade the rail ## How It Works Include the `payoutRail` field in your [Transfer Money](/docs/payouts/transfer-money) request. Nium validates the value against your client configuration and the destination corridor, then routes accordingly. ```json { "preferences": { "payoutRail": ["REALTIME"] } } ``` If no value is passed for `payoutRail`, Nium applies its internal routing logic to select the best rail for your transaction. If the specified rail is unavailable and no fallback partner can honour it, the transaction is **rejected** — Nium does not silently downgrade to a slower or alternate rail. ## Supported Values ### Generic Modes *(Recommended)* Corridor-agnostic values that Nium maps to the best available rail per destination. | Value | Description | Best For | | ---------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `REALTIME` | Near-instant settlement (e.g. FPS, FedNow, Interac) | When settlement speed is the priority | | `SAMEDAY` | Same-day, batch-processed rails where schemes and cut-offs permit | Payroll, batch payouts, end-of-day settlements | | `LOWCOST` | Lowest-cost available rail per corridor | When cost is the priority and SLA allows standard settlement | | `SWIFT` | Settlement via the SWIFT network | Cross-border payouts where local rails are unavailable, or high-value B2B transfers | | `LOCAL` | Standard domestic clearing rails (e.g. ACH, SEPA Credit Transfer) | Non-urgent domestic payouts where rail predictability matters more than speed or cost | ### Explicit Rail IDs *(Advanced)* Specify an exact rail ID for precise control. Only honoured if it matches your client configuration and the destination corridor. Contact your Nium account manager to enable this for your account. ```json { "preferences": { "payoutRail": ["uk_fps"] } } ``` ## Supported Corridors and Rail Mapping ### Generic Mode → Rail Mapping | Currency | `REALTIME` | `SAMEDAY` | `LOWCOST` | `SWIFT` | `LOCAL` | | -------- | --------------- | ------------- | --------- | ------- | ----------------- | | EUR | INSTANT | STANDARD | INSTANT | SWIFT | INSTANT, STANDARD | | GBP | FPS | CHAPS | FPS | SWIFT | FPS, CHAPS | | HKD | FPS, ACT, CHATS | Not supported | FPS, ACT | SWIFT | FPS, ACT, CHATS | | SGD | FPS | SFTP | SFTP | SWIFT | FPS, SFTP | | AUD | NPP | DE | DE | SWIFT | NPP, DE | | CAD | INTERAC | EFT | EFT | SWIFT | EFT | ### Explicit Rail IDs | Currency | Supported Values | | -------- | --------------------------- | | EUR | `eu_instant`, `eu_standard` | | GBP | `uk_fps`, `uk_chaps` | | HKD | `hk_fps`, `hk_chats` | | SGD | `sg_fast`, `sg_sftp` | | AUD | `au_npp`, `au_de` | | CAD | `ca_interac`, `ca_eft` | ## Error Handling Every rail preference is validated against your client configuration and corridor capabilities before the payout is processed. If the requested mode or rail is not supported, the request is rejected with a clear error — there is no silent downgrade or fallback. | HTTP Status | Error Code | Description | Recommended Action | | ----------- | ------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 4XX | `payoutRail` | The requested `payoutRail` value is not supported or does not match your client configuration. | Review the supported rail IDs for the corridor in the Explicit Rail IDs table above. Contact your Nium account manager if you believe your configuration should support this rail. | **Example error response:** ```json { "status": "BAD_REQUEST", "issues": [ { "code": "incorrect_value", "description": "Payout Rail: uk_abc is not supported for currency AUD", "field": null, "action": null, "regex": null } ] } ``` ## Best Practices - Use **generic modes** (`REALTIME`, `LOCAL`) over explicit rail IDs — they are corridor-agnostic and easier to maintain as your payment corridors expand. - Set **corridor-level defaults** during onboarding via your Nium account manager, then use transaction-level `payoutRail` to override for specific payments when needed. - Confirm supported rail IDs per corridor in the tables above before configuring preferences. ## Related Resources - [Transfer Money](/docs/payouts/transfer-money) - [Country and Regional Guides](/docs/payouts/country-and-regional-guides) --- # OFI Screening Guide URL: https://docs.nium.com/docs/payouts/transfer-money/ofi-screening-guide - Transfer Money # To be added - [Transfer Money](/docs/payouts/transfer-money) - [Country and Regional Guides](/docs/payouts/country-and-regional-guides) --- # OFI Screening Guide URL: https://docs.nium.com/docs/payouts/transfer-money/payout-validation-schema - Transfer Money # To be added - [Transfer Money](/docs/payouts/transfer-money) - [Country and Regional Guides](/docs/payouts/country-and-regional-guides) --- # Beneficiaries URL: https://docs.nium.com/docs/payouts/beneficiaries A beneficiary is the individual or business authorized to receive funds from a specific source, such as a bank account or financial transfer. In the context of Nium, a `beneficiary` represents the recipient of a payment or transfer. These details are essential to securely and accurately process transactions. ## Beneficiary resource The `beneficiary` resource represents the entity receiving receiving funds in a payout. It includes essential details about the recipient, such as the entity's name, address, and email. A `beneficiary` can either be a: - Individual - Business Additionally, a `beneficiary` can be associated with one or more payment accounts. The following breaks down the fields and details for individual and business `beneficiaries`. **Note:** Required fields are marked with an asterisk (\*). **Individual beneficiaries** | **Field** | **Description** | | --------------------------------- | ----------------------------------------------------------------------------------------------- | | `beneficiaryName`\* | Full name of the beneficiary. | | `beneficiaryAccountType`\* | Account type: **Individual** or **Corporate**. | | `beneficiaryCountryCode`\* | ISO-2 country code of the beneficiary. | | `destinationCurrency`\* | 3-letter ISO-4217 destination currency code. | | `payoutMethod`\* | Payout method: **LOCAL**, **SWIFT**, **WALLET**, **CARD**, or **PROXY**. | | `beneficiaryEmail` | Email address of the beneficiary. | | `beneficiaryContactCountryCode` | Mobile number country code (without `+`). | | `beneficiaryContactNumber` | Mobile number digits only, without country code. | | `beneficiaryDob` | Date of birth (format: `YYYY-MM-DD`). Applicable only to individual `beneficiaries`. | | `remitterBeneficiaryRelationship` | The relationship between the sender and the receiving entity in the context of the transaction. | **Business beneficiaries** | **Field** | **Description** | | --------------------------------- | ----------------------------------------------------------------------------------------------- | | `beneficiaryName`\* | Full name of the beneficiary. | | `beneficiaryAccountType`\* | Account type: **Individual** or **Corporate**. | | `beneficiaryCountryCode`\* | ISO-2 country code of the beneficiary. | | `destinationCurrency`\* | 3-letter ISO-4217 destination currency code. | | `payoutMethod`\* | Payout method: **LOCAL**, **SWIFT**, **WALLET**, **CARD**, or **PROXY**. | | `beneficiaryEmail` | Email address of the beneficiary. | | `beneficiaryContactName` | Contact person name (for corporate beneficiaries). | | `beneficiaryContactCountryCode` | Mobile number country code (without `+`). | | `beneficiaryContactNumber` | Mobile number digits only, without country code. | | `beneficiaryEntityType` | Entity type of the business (e.g. `partnership`). | | `beneficiaryEstablishmentDate` | Date of establishment (format: `YYYY-MM-DD`). | | `remitterBeneficiaryRelationship` | The relationship between the sender and the receiving entity in the context of the transaction. | When you create a new `beneficiary`, a unique ID (`beneficiaryHashId`) is generated and assigned to the new `beneficiary`. Use this `beneficiaryHashId` and the [beneficiary](https://beneficiary.docs.nium.com/api) endpoint (or Nium Portal) to manage the beneficiary’s details and associated payment accounts. ## Payment account A `payment-account` represents the account details of a `beneficiary`. Specifically, a `payment-account` includes the banking details needed for `beneficiaries` to receive funds from payouts. This includes details like the country, currency, payment method (**LOCAL**, **SWIFT**, **PROXY**, **WALLET**, and \* *CARD*\*), routing code, account number, etc. The details needed to create a `payment-account` vary by payout corridor. The payout corridor is determined by: - Country (`payoutCountry`) - Currency (`payoutCurrency`) - Payment method (`payoutMethod`) The table below lists the most common required fields for setting up a beneficiary’s `payment-account`. For specific corridor or payment method requirements, see the [Add Payment Account](/api#tag/paymentaccounts/POST/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts) request. **Note:** Required fields are marked with an asterisk (\*). | **Field** | **Description** | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `beneficiaryAlias` | A short alias for the beneficiary (5–30 characters). | | `beneficiaryAccountNumber` | Bank account number of the beneficiary. | | `beneficiaryBankName` | Bank name of the beneficiary. | | `beneficiaryBankCode` | Bank identifier code. | | `beneficiaryBankAccountType` | Bank account type: **Current**, **Saving**, **Maestra**, or **Checking**. | | `beneficiaryAddress` | Street address of the beneficiary. | | `beneficiaryCity` | City of the beneficiary. | | `beneficiaryState` | State of the beneficiary. | | `beneficiaryPostcode` | Postal code of the beneficiary. | | `destinationCountry` | 2-letter ISO-2 country code of the destination. | | `routingCodeType1` | Routing code type 1. E.g. `SWIFT`, `IFSC`, `SORT CODE`, `ACH CODE`, `BSB CODE`, `BANK CODE`, `BRANCH CODE`. | | `routingCodeValue1` | Routing code value 1. | | `routingCodeType2` | Routing code type 2. | | `routingCodeValue2` | Routing code value 2. | | `proxyType` | Required when `payoutMethod` is `PROXY`. Values per network: SGD-PayNow: `MOBILE`, `UEN`, `NRIC`, `VPA`; INR-UPI: `VPA`; BRL-PIX: `MOBILE`, `ID`, `EMAIL`, `RANDOM_KEY`; AUD-PayID: `MOBILE`, `EMAIL`, `ABN`, `ORGANISATION_ID`; MYR-DuitNow: `NRIC`, `PASSPORT`, `CORPORATE_REGISTRATION_NUMBER`, `MOBILE`, `ARMY_ID`. | | `proxyValue` | Required when `payoutMethod` is `PROXY`. Mobile number must include country code. | | `encryptedBeneficiaryCardToken` | System-generated card token. Mandatory for non-PCI DSS compliant clients when payout method is `CARD`. | | `beneficiaryCardExpiryDate` | Card expiry date. Required for CARD payout method. | When you create a new `payment-account`, a unique ID (`paymentAccountHashId`) will be assigned to the newly created `payment-account`. Use the `paymentAccountHashId` to manage account details or issue a payout using the [Transfer Money](/docs/payouts/transfer-money) request. ## Managing beneficiaries Clients can manage beneficiaries using: - [The beneficiaries endpoint](https://beneficiary.docs.nium.com/api) - [Nium Portal](/docs/nium-portal#managing-beneficiaries) ### Nium API Use the [beneficiary](https://beneficiary.docs.nium.com/api) endpoint to manage `beneficiaries` and `payment-accounts`. Beneficiary requests | **Request** | **Description** | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | [**Add Beneficiary (V2)**](https://docs.nium.com/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) | Adds a new `beneficiary` and saves their information for future transactions. | | [**Delete Beneficiary (V2)**](https://docs.nium.com/api#tag/beneficiary/DELETE/api/v1/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) | Deletes a `beneficiary` and removes their information from the system. | | [**Get Beneficiaries (V2)**](https://docs.nium.com/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) | Returns a list of `beneficiaries` linked to your account or organization. | | [**Get Beneficiary Details (V2)**](https://docs.nium.com/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) | Fetches detailed information about a specific `beneficiary` using their unique ID. | | [**Get Beneficiary Token (V2)**](https://beneficiary.docs.nium.com/api#tag/beneficiary/POST/api/v3/beneficiary/token) | Retrieves an authentication token to securely interact with the `beneficiary` resource. | | [**Update Beneficiary Details (V2)**](https://docs.nium.com/api#tag/beneficiary/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) | Modifies an existing beneficiary’s details, such as contact information or payment accounts. | Payment Account requests | **Request** | **Description** | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | [\*\*Add Payment Account \*\*](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/POST/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts) | Adds a new `payment-account` under an existing beneficiary. | | [**Get Bank Details**](https://beneficiary.docs.nium.com/api#tag/validations/GET/api/v1/bank-details) | Fetches details about the bank based on the submitted routing code. | | [\*\*Get Payment Account Details \*\*](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/GET/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) | Retrieves detailed information about a specific `payment-account` using its unique identifier. | | [\*\*Get Payments Accounts \*\*](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/GET/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts) | Retrieves a list of all `payment-accounts` associated with a specific beneficiary. | | [\*\*Remove Payment Account \*\*](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/DELETE/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) | Deletes a `payment-account` from a beneficiary's list of accounts. | | [\*\*Update Payment Account Details \*\*](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/PUT/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) | Updates the details of an existing `payment-account`, such as routing codes or account holder information. | #### Creating payment accounts In addition to creating `payment-accounts`, use the [Add Payment Account](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/POST/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts) request to check the required details for a specific payout corridor. Based on the `payoutCountry`, `payoutCurrency`, and `payoutMethod` used, the response to the request will detail the fields that are required to create a corridor specific `payment-account` for your `beneficiary`. The data submitted in the request is validated against field-specific requirements, such as character limits, string length, and special characters. This response helps simplify the process of creating `beneficiaries` and `payment-accounts` by eliminating the need to submit additional requests, like [Fetch Supported Corridors](/api#tag/reference-data/GET/api/v3/client/{clientHashId}/supportedCorridors) or [Beneficiary Validation Schema](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/currency/{currencyCode}/validationSchemas). ### Nium Portal Use the **Beneficiaries** page in Nium Portal to manage the different beneficiaries that have been created for a customer. Managing Beneficiaries For additional details, see [Nium Portal - Overview](/docs/nium-portal#managing-beneficiaries). ## Creating a beneficiary The following examples break down the steps to create a `beneficiary` and a `payment-account`. ### Step 1: Add a beneficiary Use the [Add Beneficiary (V2)](https://docs.nium.com/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) request to add a `beneficiary` for a customer. The required details depend on the `beneficiary` type (`entityType`). After creating a `beneficiary`, a unique `beneficiaryHashId` is assigned. Use this ID to manage the `beneficiary` and its associated `payment-accounts`. When making the request, include: - `clientHashId` – Your unique identifier, generated during onboarding. - `customerHashId` – The unique identifier for the customer, generated when the customer is created. #### Individual beneficiary ```bash curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data-raw '{ "beneficiaryName": "John Singh", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "MY", "destinationCurrency": "PHP", "destinationCountry": "PH", "payoutMethod": "LOCAL", "beneficiaryAccountNumber": "NDIyOTk4MDA2OTk0ODY1MQ==", "beneficiaryAlias": "JohnSingh01", "beneficiaryBankName": "BDO Unibank", "beneficiaryEmail": "john@example.com", "beneficiaryAddress": "123 Tower Bridge", "beneficiaryCity": "Manila", "beneficiaryContactCountryCode": "60", "beneficiaryContactNumber": "9902892467", "routingCodeType1": "BANK CODE", "routingCodeValue1": "010269" }' ``` #### Business beneficiary ```bash curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data-raw '{ "beneficiaryName": "Nium", "beneficiaryAccountType": "Corporate", "beneficiaryCountryCode": "MY", "destinationCurrency": "PHP", "destinationCountry": "PH", "payoutMethod": "LOCAL", "beneficiaryAccountNumber": "NDIyOTk4MDA2OTk0ODY1MQ==", "beneficiaryAlias": "Nium01", "beneficiaryBankName": "BDO Unibank", "beneficiaryEmail": "test@nium.com", "beneficiaryContactName": "Test", "beneficiaryContactCountryCode": "60", "beneficiaryContactNumber": "9902892467", "beneficiaryEntityType": "partnership", "beneficiaryEstablishmentDate": "2000-01-01", "remitterBeneficiaryRelationship": "partner", "routingCodeType1": "BANK CODE", "routingCodeValue1": "010269" }' ``` ### Step 2: Add a payment account Use the [Add Payment Account ](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/POST/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts) request to add a `payment-account` for a `beneficiary`. Before adding a `payment-account`, you must first create a `beneficiary`. The required details vary based on: - **Payout corridor** – Determined by `payout-country` and `payout-currency`. - **Payment method** – Defined by the `payout-method` used. Be sure to include the following in your request: - `beneficiaryHashId` - `clientHashId` - `customerHashId` When you add a new `payment-account`, Nium checks for duplicates to prevent multiple entries of the same account. The following `payment-account` properties are used to determine duplicates: | **Payment Method** | **Properties** | | ---------------------- | -------------------------------------------------------------------------------------------------- | | **LOCAL** or **SWIFT** | `payoutCountry``payoutCurrency``paymentMethod``beneficiaryHashId``bankAccountNumber``routingCodes` | | **PROXY** | `payoutCountry``payoutCurrency``paymentMethod``beneficiaryHashId``proxyType``proxyValue` | | **WALLET** | `payoutCountry``payoutCurrency``paymentMethod``beneficiaryHashId``wallet.provider``wallet` | | **CARD** | `payoutCountry``payoutCurrency``paymentMethod``beneficiaryHashId``card details` or `token` | **Note:** To add another `payment-account` for the same beneficiary, send the relevant request(s) multiple times. #### Sample requests The following example requests show how to create different types of `payment-accounts`. US Local Payment Account - `payout-country`: **US** - `payout-currency`: **USD** - `payment-method`: **LOCAL** ```bash curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "beneficiaryName": "John Singh", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "US", "destinationCurrency": "USD", "destinationCountry": "US", "payoutMethod": "LOCAL", "beneficiaryAccountNumber": "0112345678", "beneficiaryAlias": "test payment account", "beneficiaryAddress": "123 Elm St", "beneficiaryCity": "Anytown", "beneficiaryState": "Anystate", "beneficiaryPostcode": "94536", "routingCodeType1": "ACH CODE", "routingCodeValue1": "114916488" }' ``` HK-GBP SWIFT Payment Account - **`payout-country`**: **HK** - **`payout-currency`**: **GBP** - **`payment-method`**: **SWIFT** ```bash curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "beneficiaryName": "John Singh", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "HK", "destinationCurrency": "GBP", "destinationCountry": "HK", "payoutMethod": "SWIFT", "beneficiaryAccountNumber": "0112345678", "beneficiaryAlias": "test payment account", "beneficiaryBankCode": "402", "beneficiaryBankAccountType": "Checking", "beneficiaryAddress": "123 Elm St", "beneficiaryCity": "Anytown", "beneficiaryState": "Anystate", "beneficiaryPostcode": "94536", "routingCodeType1": "SWIFT", "routingCodeValue1": "ABCHHKHH" }' ``` SG Proxy Payment Account - **`payout-country`**: **SG** - **`payout-currency`**: **SGD** - **`payment-method`**: **PROXY** ```bash curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "beneficiaryName": "John Singh", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "SG", "destinationCurrency": "SGD", "destinationCountry": "SG", "payoutMethod": "PROXY", "beneficiaryAlias": "test payment account", "beneficiaryAddress": "123 Elm St", "beneficiaryCity": "Anytown", "beneficiaryState": "Anystate", "beneficiaryPostcode": "94536", "proxyType": "MOBILE", "proxyValue": "1234567891" }' ``` CN Wallet Payment Account - **`payout-country`**: **CN** - **`payout-currency`**: **CNY** - **`payment-method`**: **WALLET** ```bash curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "beneficiaryName": "John Singh", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "CN", "destinationCurrency": "CNY", "destinationCountry": "CN", "payoutMethod": "WALLET", "beneficiaryAlias": "test payment account", "beneficiaryAddress": "123 Elm St", "beneficiaryCity": "Anytown", "beneficiaryState": "Anystate", "beneficiaryPostcode": "94536" }' ``` CN Card Payment Account - **`payout-country`**: **CN** - **`payout-currency`**: **CNY** - **`payment-method`**: **CARD** ```bash curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "beneficiaryName": "John Singh", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "CN", "destinationCurrency": "CNY", "destinationCountry": "CN", "payoutMethod": "CARD", "beneficiaryAlias": "test payment account", "beneficiaryAddress": "123 Elm St", "beneficiaryCity": "Anytown", "beneficiaryState": "Anystate", "beneficiaryPostcode": "94536", "beneficiaryCardIssuerName": "nium", "beneficiaryCardExpiryDate": "2028-10" }' ``` CN Card-Token Payment Account - **`payout-country`**: **CN** - **`payout-currency`**: **CNY** - **`payment-method`**: **CARD** with a **card-token**. ```bash curl --location 'https://gateway.nium.com/api/v2/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "beneficiaryName": "John Singh", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "CN", "destinationCurrency": "CNY", "destinationCountry": "CN", "payoutMethod": "CARD", "beneficiaryAlias": "test payment account", "beneficiaryAddress": "123 Elm St", "beneficiaryCity": "Anytown", "beneficiaryState": "Anystate", "beneficiaryPostcode": "94536", "beneficiaryCardIssuerName": "nium", "encryptedBeneficiaryCardToken": "", "beneficiaryCardExpiryDate": "2028-10" }' ``` #### Sample response The following is a sample response for creating a `payment-account` with: - `payout-country`: US - `payout-currency`: USD - `payment-method`: LOCAL Sensitive information is masked in the response. ```json { "beneficiaryHashId": "91df5b80-2b48-47a0-b395-a941fca1e0da", "payoutHashId": "16984a1f-df52-4808-948a-49b84967349e", "beneficiaryName": "John Singh", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "US", "beneficiaryAddress": "*****", "beneficiaryCity": "Anytown", "beneficiaryState": "*****", "beneficiaryPostcode": "*****", "beneficiaryEmail": "j*****@example.com", "beneficiaryBankName": "Citizens State Bank of Luling", "beneficiaryBankAccountType": "Checking", "beneficiaryAccountNumber": "******5678", "routingCodeType1": "ACH CODE", "routingCodeValue1": "114916488", "destinationCountry": "US", "destinationCurrency": "USD", "payoutMethod": "LOCAL", "beneficiaryCreatedAt": "2024-12-11", "beneficiaryUpdatedAt": "2024-12-11" } ``` ## Updating a beneficiary The [Update Beneficiary (V2)](https://docs.nium.com/api#tag/beneficiary/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) request enables you to update and modify the details of a beneficiary. All properties of a `beneficiary` can be changed *except*: - `beneficiaryAccountType` - `beneficiaryEmail` - `beneficiaryEntityType` When updating a `beneficiary`, you must include: - `clientHashId` - `customerHashId` - `beneficiaryHashId` ### Updating a payment account The [Update Payment Account ](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/PUT/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) request works similarly to the [Update Beneficiary (V2)](https://docs.nium.com/api#tag/beneficiary/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) request. It updates a beneficiary’s `payment-account` with the details provided in the request body. All properties of a `payment-account` can be modified *except*: - `beneficiaryAccountType` - `beneficiaryEmail` - `beneficiaryEntityType` When updating a `payment-account`, you must include: - `beneficiaryHashId` - `clientHashId` - `customerHashId` - `paymentAccountHashId` When you update a `payment-account`, the system checks for duplicates to prevent multiple entries of the same account. If the updated details match another `payment-account` assigned to the same `beneficiary`, the request is rejected. The following `payment-account` properties are used to determine duplicates: | **Payment Method** | **Properties** | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **LOCAL** or **SWIFT** | `payoutCountry``payoutCurrency``paymentMethod``beneficiaryHashId``paymentAccountHashId``bankAccountNumber``routingCodes` | | **PROXY** | `payoutCountry``payoutCurrency``paymentMethod``beneficiaryHashId``paymentAccountHashId``proxyType``proxyValue` | | **WALLET** | `payoutCountry``payoutCurrency``paymentMethod``beneficiaryHashId``paymentAccountHashId``wallet.provider``wallet` | | **CARD** | `payoutCountry``payoutCurrency``paymentMethod``beneficiaryHashId``paymentAccountHashId``card details` or `token` | ## Deleting a beneficiary Use the [Delete Beneficiary (V2)](https://docs.nium.com/api#tag/beneficiary/DELETE/api/v1/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) request to delete a `beneficiary`. For auditing reasons, the request will soft-delete the `beneficiary`. Deleting a `beneficiary` will also soft-delete all of the associated `payment-accounts`. - Deleted `beneficiaries` won’t be listed in the GET or LIST `beneficiary` requests. - To delete a `beneficiary`, you must include the: - `clientHashId` - `customerHashId` - `beneficiaryHashId` ### Deleting a payment account Use the [Remove Payment Account ](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/DELETE/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) to remove a `payment-account` from a beneficiary. For auditing reasons, the request will soft delete the `payment-account`. - Deleted `payment-accounts` won’t be listed in the GET or LIST `beneficiary` requests. - To delete a `beneficiary` you must include the: - `clientHashId` - `customerHashId` - `beneficiaryHashId` - `paymentAccountHashId` ## Blocking a beneficiary or payment account Use the [Update Beneficiary (V2)](https://docs.nium.com/api#tag/beneficiary/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) and [Update Payment Account ](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/PUT/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) requests to block a `beneficiary` or `payment-account`. By default, `beneficiaries` and `payment-accounts` have a `status` of **active**. Use the [Update Beneficiary (V2)](https://docs.nium.com/api#tag/beneficiary/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) and [Update Payment Account ](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/PUT/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) requests to update the status of `beneficiaries` and `payment-accounts`. Blocking a `beneficiary` or `payment-account` temporarily stops payments in case of an issue. - **To block a `beneficiary`**, use the [Update Beneficiary (V2)](https://docs.nium.com/api#tag/beneficiary/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) request and set the `beneficiary.status` to **blocked**. - Note: Blocking a `beneficiary` also blocks all associated `payment-accounts`. - **To block a `payment-account`**, use the [Update Payment Account ](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/PUT/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) request and set the `payment-account.status` to **inactive**. ## Fetch beneficiary or payment account The [Fetch Beneficiary Details (V2)](https://docs.nium.com/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) and [Fetch Payment Account Details ](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/GET/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) requests allow you to retrieve details of a `beneficiary` or its associated `payment-account`. By default, sensitive information is masked in the response. To retrieve unmasked data, set the `unmaskData` query parameter to **true**. Below is an example of a [Fetch Payment Account Details (V2)](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/GET/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}) response with masked data. ```json { "id": "16984a1f-df52-4808-948a-49b84967349e", "beneficiaryHashId": "91df5b80-2b48-47a0-b395-a941fca1e0da", "owner": { "name": "Nium", "address": { "line1": "*****", "line2": "*****", "city": "Anytown", "state": "*****", "countryCode": "us", "postalCode": "*****" }, "identification": { "type": "type", "value": "*alue" } }, "autoSweep": { "default": false, "enable": false }, "alias": "test payment account", "payoutCountry": "US", "payoutCurrency": "USD", "paymentMethod": "LOCAL", "verificationStatus": { "status": "unverified" }, "status": "active", "bankName": "Citizens State Bank of Luling", "accountType": "checking", "accountNumber": "******5678", "routingCodes": [ { "type": "ach_code", "value": "114916488" } ], "openDate": "2024-12-11", "default": false } ``` ## List beneficiaries or payment accounts The [List Beneficiaries (V2)](https://docs.nium.com/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) and [List Payment Accounts (V2)](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/GET/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts) requests retrieve a list of `beneficiaries` for a customer and `payment-accounts` for a beneficiary. - By default, sensitive information is masked in the response. To retrieve unmasked data, set the `unmaskData` query parameter to **true**. - Items are sorted by `creation-time` and `paymentAccountId`. - The response is paginated and uses cursor-based pagination. Below is a sample response for a [List Beneficiaries (V2)](https://docs.nium.com/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) request. ```json [ { "beneficiaryHashId": "1e3882af-c622-456e-8fbd-c951f3368577", "payoutHashId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "beneficiaryName": "Jeff Grell", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "US", "beneficiaryEmail": "j*****@frontside.net", "destinationCountry": "US", "destinationCurrency": "USD", "payoutMethod": "LOCAL", "beneficiaryAccountNumber": "******5678", "routingCodeType1": "ACH CODE", "routingCodeValue1": "114916488" }, { "beneficiaryHashId": "82bce9d9-f69a-45c7-ab6c-12167a64ed2f", "payoutHashId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "beneficiaryName": "Nium", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "SG", "beneficiaryEmail": "t*****@nium.com", "beneficiaryContactCountryCode": "65", "beneficiaryContactNumber": "*******7890", "destinationCountry": "SG", "destinationCurrency": "SGD", "payoutMethod": "LOCAL", "beneficiaryAccountNumber": "******1234", "remitterBeneficiaryRelationship": "relationship", "beneficiaryDob": "2000-01-01" }, ............. ............., { "beneficiaryHashId": "6fc33e40-f65b-4574-9b4d-3f2ba5491a6d", "payoutHashId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "beneficiaryName": "Nium", "beneficiaryAccountType": "Individual", "beneficiaryCountryCode": "MY", "beneficiaryEmail": "t*****@nium.com", "beneficiaryContactCountryCode": "60", "beneficiaryContactNumber": "*******7890", "destinationCountry": "MY", "destinationCurrency": "MYR", "payoutMethod": "LOCAL", "remitterBeneficiaryRelationship": "relationship", "beneficiaryDob": "2000-01-01" } ] ``` ### SCA Authentication for EU/UK clients To comply with PSD2 regulations, EU/UK clients must include an `authenticationCode` in POST and PUT requests. The `authenticationCode` is a one-time password (OTP) or verification code used as a second authentication factor before calling Nium APIs. ## Transfer money With the changes in [Add Beneficiary (V2)](https://docs.nium.com/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) and [Payment Account ](https://beneficiary.docs.nium.com/api#tag/paymentaccounts/GET/api/v3/clients/{clientHashId}/customers/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts), the [Transfer Money](/docs/payouts/transfer-money) request also accepts the `paymentAccountHashId`. Below are examples of how to transfer money and create a `payout` using the `paymentAccountHashId`. ### Step 1: Add a payment account [After creating a `beneficiary`](/docs/payouts/beneficiaries#creating-a-beneficiary), add a `payment-account` for them. ```bash curl --location 'https://gateway.nium.com/api/v3/clients/42a8224a-09b6-422d-b557-c560354ccb4a/customers/44ca05f5-5fe4-47c1-bc78-af4bb4440bae/beneficiaries/09671eda-68fc-4d05-ba89-8a95174fbdac/payment-accounts' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "authenticationCode": "12345", "payoutCountry": "US", "payoutCurrency": "USD", "paymentMethod": "LOCAL", "alias": "test payment account", "accountType": "checking", "accountNumber": "0112345678", "owner": { "address": { "line1": "123 Elm St", "line2": "Suite 5", "city": "Anytown", "state": "Anystate", "countryCode": "us", "postalCode": "94536" }, "identification": { "type": "type", "value": "value" } }, "routingCodes": [ { "type": "ach_code", "value": "114916488" } ] }' ``` ### Step 2: Transfer funds Create a `remittance` to transfer funds using the `paymentAccountHashId`. ```json curl --location 'https://preprod.spend.nium.com/wallet-service/api/v1/client/20bd3def-49cb-45d6-ab2a-963640322b76/customer/d1218522-4f71-479b-a644-653275e389bf/wallet/aaaedd53-3e8d-4f98-a98e-47cb4f68a7ed/remittance' \ --header 'Content-Type: application/json' \ --header 'csrf_token: ....' \ --header 'Authorization: Bearer .....' \ --data ' { "purposeCode": "IR006", "customerComments": "Family Maintenance", "authenticationCode": "test", "beneficiary": { "paymentAccountId": "e6ee9f20-98c1-4779-814e-014636edd5d8" }, "payout": { "source_amount": 1, "source_currency": "SGD" } }' ``` --- # Schema Preview (Beta) URL: https://docs.nium.com/docs/payouts/beneficiaries/schema-preview Any change to Nium's beneficiary schema like adding a new required field — goes live immediately on the release date as documented in the Nium Changelog. This gives you no time to adapt, which can cause payment failures, unexpected form changes for users, and urgent last-minute fixes. Any change to Nium's [beneficiary schema](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/currency/{currencyCode}/validationSchemas) like adding a new required field — goes live immediately on the release date as documented in the [Nium Changelog](/changelog). This gives you no time to adapt, which can cause payment failures, unexpected form changes for users, and urgent last-minute fixes. We’re beta testing a Schema Preview endpoint that enables you to see and test upcoming schema changes. ## Schema Preview You’ll be able to preview new or updated `beneficiary` fields (including required ones) before release in both sandbox and production environments. With the Schema Preview, you can update your integration ahead of the actual release date to avoid any surprises. No API changes are needed to use the Schema Preview — the preview works with your current integration and requests. You can choose when to opt in or opt out of the Schema Preview (Beta) by contacting [Nium Support](mailto:support@nium.com). ## Using the Schema Preview If the Schema Preview (Beta) is enabled for your account and currency, the `beneficiary` endpoint will return the updated version in advance of release but payments will get impacted only after release. On the release date, the updated schema becomes the default for all clients. This ensures you can transition smoothly, test thoroughly, and reduce payment failures. - No more sudden changes breaking your forms or causing failed payments. - Early visibility into upcoming mandatory fields or validations. - Controlled adoption — you decide when to start using the preview. If you’d like to be part of the Beta Schema Preview for upcoming schema changes, please contact your Nium account manager or [Nium support](mailto:suport@nium.com). --- # Card Widget URL: https://docs.nium.com/docs/payouts/get-a-card-widget This API lets you use Nium’s card widget to tokenize the beneficiary card details. Customers who don't follow the Payment Card Industry Data Security Standard (PCI DSS) need to integrate with this API to get the recipient’s encrypted card token number. ### Card payouts The card widget is a functionality of the Nium Payout service, which lets you make payments in many currencies to multiple parties using the VISA card. This functionality also helps you to make payouts in Chinese Yuan (CNY) using the UnionPay cards. This API supports [Visa Direct](https://developer.visa.com/capabilities/visa_direct/docs#:~:text=Visa%20Direct%20offers%20real%2Dtime,billion%20eligible%20Visa%20card%20accounts.) payouts. Visa Direct is available for Asia-Pacific and European Economic Area(EEA) clients only. UnionPay payouts are only available for the destination country China. In case the transaction currency doesn't match the destination card issuer's currency, the payout amount is converted and credited to the currency of the card issuer. You can use the card widget to make peer-to-peer, business-to-peer, and business-to-business payments. You need to pass the token number in the field `encryptedBeneficiaryCardToken` when you add a beneficiary to make a payout to a card. In case you're PCI-DSS compliant, you can directly pass the card number when you add a beneficiary. Follow these steps to integrate a card widget: ### Step 1: Get a card widget URL. The **[Get card widget](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/widget/token)** request lets you get a card widget URL. You need to pass the style values to make basic style changes to the widget depending on your page color scheme. ### Step 2: Add your widget URL to the client’s page. Use the retrieved card widget URL from **Step 1** and use it as input for **src=**`widgetUrl`. You can use an HTML iFrame tag on your page to add your image details. You can set the height and width of the iFrame tag depending on your page view. ```json { } ``` If you don't have Cascade Style Sheets set up in **Step 1**, then your default widget looks like this image. Transaction Timeline ### Step 3: Add a listener for your message event to get iFrame-validated data. Once you fill in the card details on the widget, the iFrame triggers a **message** event to the parent client page. You have to implement a listener to receive that message which contains the encrypted beneficiary card token and other details. ### Sample event data on success: ```json { "cardDetailsValid": true, "encryptedBeneficiaryCardToken": "eyJhbGciOiJIUzI1NiJ9.eyJlbmNJIjoiZGhoVlFMWW53MjFPY\u2026DQ3fQ.ektooTLFNeCnZSEF5o9iLFHo-JE62qecryM_Hy5cJcM", "maskedCardNumber": "XXXX XXXX XXXX 4242", "billingCurrencyCode": "PHP" } ``` ### Sample event data on failure: ```json { "cardDetailsValid":false } ``` Non-PCI DSS-compliant clients have to use the encrypted beneficiary card token when they add or update a beneficiary for a card payout. The token expires in 30 minutes. --- # Payment Visibility URL: https://docs.nium.com/docs/payouts/recognizing-payments When your business sends payouts through Nium, recipients expect to know two things: - Who sent the money? - What is the payment is for? If recipients can't identify payments on their bank statements, it causes confusion and delays the settlement of funds. To add, variances between regulations and what information is required adds to the difficulty of identifying payments. This guide explains how Nium keeps payments identifiable, how visibility differs by corridor, and how to configure payouts for a better customer experience. ## Visibility Bank statements vary widely by country and clearing system. To maximize visibility, Nium applies the following to every transaction: 1. Custom sender name delivered (when corridors permit): Nium passes your customer’s name as the sender ( `remitter.name`). The recipient sees the ultimate sender. 2. Fixed sender name (add reference text): If the corridor enforces a fixed sender name (e.g., “NIUM Fintech” or “INSTAREM”), Nium forwards your `customerComments` such as customer name and invoice/order ID. - If you don’t provide `customerComments`, Nium auto-populates with **Remitter Name + Nium Transaction ID**. 3. References only (clearing system identifiers): In corridors that don’t display custom sender names or comments, recipients identify payments using system generated clearing references including Unique transaction references ( UTR), bank reference number, transaction reference number, or Nium transaction ID. Your recipient *will always include some identifying details to recognize or trace payments*. ## Corridor categories Corridors generally fall into three categories: #### Sender name and reference both shown - Example: EUR, AUD, SGD - Bank statement: ```yaml CREDIT: ABC Ltd REF: Invoice 1234 ``` #### Fixed sender name — reference text shown - Example: GBP, HKD, MYR - Bank statement: ```yaml CREDIT: NIUM FINTECH REF: ABC Ltd / Invoice 1234 ``` #### Reference only (clearing IDs) - Example: INR, VND, MXN - Bank statement: ```yaml CREDIT: ABC Corp REF: UTR 20250928012345 ``` ## Configuring payouts When creating a payout, you configure two fields: | Field | Purpose | Notes | | ------------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | | `remitter.name` | Sends your customer’s name as the sender. | Some corridors override the `remitter.name` with fixed names (e.g., GBP, HKD, MYR). | | `customerComments` | Free field to include reference details (customer name, invoice ID, order ID). | Length and characters vary. May be shortened or removed by banks. | Think of these as the *Sender Name* and *Payment Reference*. ## Corridor visibility | Currency | Country | Customer Name as Remitter | Remitter Name Visibility | Narrative / Comments Visibility | Other Information | | -------- | -------------- | ------------------------------- | -------------------------------------- | ------------------------------- | --------------------------------- | | AUD | Australia | Yes | Visible | Visible | | | AED | UAE | Yes | Visible | Visible | | | EUR | European Union | Yes | Visible | Visible | | | SGD | Singapore | Yes | Visible | Not visible | Transaction Reference Number | | JPY | Japan | Yes | Visible | Not visible | | | KRW | South Korea | Yes | Visible | Not visible | | | NPR | Nepal | Yes | Visible | Not visible | Bank Transaction Reference Number | | GBP | United Kingdom | No (fixed as NIUM Fintech) | Fixed as NIUM Fintech | Visible | | | MYR | Malaysia | No (fixed as NIUM SDN. BHD.) | Fixed as NIUM SDN. BHD. (FKA Instarem) | Visible | | | BDT | Bangladesh | Limited (clearing restrictions) | Limited by clearing system | Not visible | | | BRL | Brazil | Limited (proxy only) | Proxy transactions only | Not visible | | | CAD | Canada | Bank dependent | Sent to recipient’s bank | Sent to recipient’s bank | | | COP | Colombia | Limited (clearing restrictions) | Limited by clearing system | Not visible | | | HKD | Hong Kong | No (fixed as INSTAREM) | Fixed as INSTAREM | Sent to recipient’s bank | Transaction Reference Number | | IDR | Indonesia | Limited (clearing restrictions) | Limited by clearing system | Not visible | Transaction Reference Number | | INR | India | Limited (proxy only) | Proxy transactions only | Not visible | Bank Reference Number | | LKR | Sri Lanka | Limited (clearing restrictions) | Limited by clearing system | Not visible | | | MXN | Mexico | Limited (clearing restrictions) | Limited by clearing system | Not visible | | | PHP | Philippines | Bank dependent | Sent to recipient’s bank | Sent to recipient’s bank | | | PKR | Pakistan | Bank dependent | Sent to recipient’s bank | Not visible | | | PLN | Poland | Bank dependent | Sent to recipient’s bank | Sent to recipient’s bank | Transaction Reference Number | | THB | Thailand | Limited (clearing restrictions) | Limited by clearing system | Not visible | | | TRY | Turkey | Bank dependent | Sent to recipient’s bank | Not visible | | | USD | United States | Bank dependent | Sent to recipient’s bank | Sent to recipient’s bank | Nium Transaction ID | | VND | Vietnam | Limited (clearing restrictions) | Limited by clearing system | Not visible | Bank Transaction Reference Number | #### Legend - **Yes**: Customer’s name can be sent directly as the remitter. - **Limited**: Supported only in restricted cases (proxy, clearing limits, or dependent on beneficiary bank). Refer to [playbook](https://playbook.nium.com) for more details. - **No**: Corridor enforces a fixed remitter (e.g., NIUM / Instarem). ## Example scenarios #### Sender name shown (EUR) ```json "remitter": {"name": "John Smith"}, "customerComments": "Invoice #1234" ``` ***Bank Statement*** ```yaml CREDIT: JOHN SMITH REF: Invoice #1234 ``` #### Fixed sender name, comments displayed (GBP) ```json "remitter": {"name": "John Smith"}, "customerComments": "Invoice #1234" ``` ***Bank Statement*** ```yaml CREDIT: NIUM FINTECH REF: John Smith / Invoice #1234 ``` #### Fixed sender name, no comments (GBP) ```json "remitter": {"name": "John Smith"} ``` ***Bank Statement*** ```yaml CREDIT: NIUM FINTECH REF: John Smith - Nium Txn 987654321 ``` #### References only (INR) ```json "remitter": {"name": "John Smith"} ``` ***Bank Statement*** ```yaml CREDIT: ABC CORP REF: UTR 20250928012345 ``` ## Identifying payments Recipients rely on a combination of: - **Sender Name**: when allowed by the corridor. - **Reference Text**: custom comments you provide. - **System Identifiers**: UTRs, bank reference numbers, or Nium Transaction IDs. **Best experience**: *Sender name* and *Reference text*. **Fallback**: *Reference text* or *System identifiers*. ## Best practices - Always include your customer’s name in `remitter.name`. - In fixed-remitter corridors, use `customerComments` for *customer name and invoice/order reference*. - Keep text short (less than 30 characters), alphanumeric, and avoid special symbols. - Test visibility in your *key corridors* before going live. Please note: - **Corridor rules**: Some corridors enforce fixed remitter names or block reference details. - **Recipient banks**: Some banks cut short or remove details, even if Nium forwards them. - **Formatting not guaranteed**: The final layout of details always depends on the recipient’s bank. ## Common questions Q: How do I make sure my customer’s name appears? A: Include it in `remitter.name`. If the corridor doesn’t allow a `remitter.name`, add it to `customerComments`. Q: What happens if I don’t pass `customerComments` in fixed-remitter corridors? A: Nium auto-populates `` and `Nium Transaction ID`. Q: How will recipients recognize the transaction? A: Through the sender name, your comments, or system generated reference details references like UTRs. Q: Why does visibility differ across corridors? A: Each clearing system and bank has its own rules for displaying sender and reference details. Q: What if text exceeds corridor limits? A: It may be cut short by the bank. ## Next steps - See [Payouts](/api#tag/Payouts) for details on how to create transactions. - Always send the `remitter.name`. - For corridors with fixed remitter names, include text that'll help you identify the transaction in `customerComments` (e.g. Sender name, Transaction ID, UTR, etc.). - Share these details with your *Ops and Treasury teams* to align how transactions are reconciled. --- # Track Payouts URL: https://docs.nium.com/docs/payouts/track-payouts After you create a payout, the next step is to track its progress. This helps you make sure everything is moving as expected—and take action if needed. Nium lets you track payouts using the following: - **Nium API** - **Nium Portal** - **Nium Connect** - **Webhooks or Callbacks** ### Payout Lifecycle After a payout is created, it moves through a series of statuses that reflect its progress—from initiation to completion. The final (or terminal) statuses are: - `PAID` - `REJECTED` - `RETURN` For a full list of possible statuses and what each one means, see [Transaction Lifecycle](/docs/payouts/transfer-money/remittance-lifecycle#transaction-statuses). ### Statuses Below is a list of all possible payout statuses, from start to finish, along with what each one means. | Status | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `AWAITING_FUNDS` | The transaction is waiting for funds to be added. | | `CANCELLED` | The transaction was canceled by the customer. This usually applies to scheduled payouts that haven’t started yet. | | `COMPLIANCE_COMPLETED` | The transaction passed compliance checks and is ready for the next step. | | `EXPIRED` | The transaction expired—usually due to not being funded in time or an expired Foreign Exchange (FX) rate. | | `FAILED` | The transaction failed. Check for issues (like missing funds) before trying again. | | `IN_PROGRESS` | The transaction is currently being processed. | | `INITIATED` | The transaction has been started and is in the processing flow. | | `PAID` | Funds have been sent to the beneficiary from Nium’s partner bank. | | `PG_PROCESSING` | Nium’s payment gateway is processing the payout and finding the best route through the partner bank network. | | `REJECTED` | The transaction was rejected due to compliance rules. | | `RETURN` | The payout was returned by the processing bank, clearing system, or beneficiary bank. This usually happens when something goes wrong on their end. | | `RFI_REQUESTED` | Compliance flagged the transaction and requested more information (RFI). | | `RFI_RESPONDED` | Nium received a response to the compliance RFI. | | `SCHEDULED` | The transaction is scheduled to be processed on a future date. | | `SENT_TO_BANK` | The payout instructions were sent to Nium’s partner bank. Once the partner bank completes the payout, the status changes to `PAID`. | ### Sub-statuses Sub-statuses provide more detail about a payout that reaches the `PAID` status. They help you understand what stage the transaction is in—whether it’s still with the beneficiary’s bank or has already been credited to the beneficiary’s account. This added transparency is especially useful for tracking how payouts behave in different countries and regions. | Status | Sub-status | Description | | -------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **PAID** | **PROCESSED\_BY\_CLEARING** | The transaction was processed by the clearing system and is expected to be credited to the beneficiary. This status occurs when Nium has limited visibility due to clearing or partner constraints. | | **PAID** | **DEEMED\_PAID** | The transaction is considered **PAID** with high confidence, as the clearing return window has passed without any returns. | | **PAID** | **SENT\_TO\_BENEFICIARY\_BANK** | The transaction has been sent to the beneficiary’s bank. If the account is active and compliant, the funds will be credited shortly. | | **PAID** | **SENT\_TO\_BENEFICIARY\_BANK\_ACCOUNT** | The funds have been credited to the beneficiary’s bank account. | Corridors with additional sub-status: | Currency | Payout Rail | Sub-status | Reason | | -------- | ----------- | ------------------------------------------- | -------------------------- | | NZD | BECS | **PROCESSED\_BY\_CLEARING****DEEMED\_PAID** | Clearing system limitation | | CAD | EFT | **PROCESSED\_BY\_CLEARING****DEEMED\_PAID** | Clearing system limitation | --- # Batch Payouts URL: https://docs.nium.com/docs/payouts/bulk-payouts Send, track, and reconcile high-volume payouts in a single request with asynchronous processing, real-time webhooks, and full batch visibility. Batch payouts let you send, track, and reconcile large volumes of payments using a single request. Unlike individual `payouts`, batch payouts are processed asynchronously. Submitting one batch immediately returns a `batchId`, while validation, execution, and the final payout outcomes occur in the background. Batch payouts are built for high-volume workflows such as payroll, marketplace disbursements, vendor payments, invoice settlements, and creator payouts—where *speed, scale, reliability, and transparency* matter. For single payouts, see [Transfer Money](/docs/payouts/transfer-money).\ To create a batch payout using a CSV file, see [Batch Payouts](/docs/nium-portal/batch-payouts). ## Batch payout uses Batch payouts solve three core problems for entities that process a high number of payments: - **Scale without complexity**: Submit up to *1,000 payouts in a single request*, while still receiving per-payout results and full visibility for auditing. - **Built-in reliability**: All payouts are *validated before execution*, helping prevent downstream failures, reconciliation gaps, and reducing operational overhead. - **End-to-end transparency**: Track every payout using: - Batch-level and item-level statuses - Real-time webhook notifications - Status endpoints for reconciliation and reporting ## Using batch payouts A batch of payouts is processed asynchronously in four steps: 1. **Create and submit**: Send a batch containing multiple payout instructions. 2. **Reviewed**: Each payout is checked by Nium for schema, compliance, and corridor-specific rules. 3. **Processed**: Valid payouts move into execution. 4. **Complete**: Each payout updates to a final status. You can mix different beneficiary types, customers, wallets, and payout methods within the same batch. As payouts update, you will receive webhooks with updates to the `state` and `status` of payouts. ### Payout methods If you are unsure whether to submit a batch or create payouts another way, use this quick guide. You can create payouts using one of the following methods: - **Pre-created beneficiary**: Create a beneficiary once and reuse it across multiple payouts.\ Use [Create Beneficiary](/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries), then reference the `beneficiaryHashId` in [Create Payout (Remittance)](/api#tag/payouts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance). - **Inline beneficiary details**: Include beneficiary details directly in the payout request (no beneficiary record is stored).\ Use [Create Payout (Remittance)](/api#tag/payouts/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance). - **CSV batch upload (Nium Portal)**: Upload and execute multiple payouts using a CSV file.\ For details, see [Batch Payout](/docs/nium-portal/batch-payouts#create-a-batch-payout). - **Batch payouts API (this page)**: Submit up to 1,000 payouts in one request with asynchronous processing, per-item results, and webhooks.\ Use [Create Batch Payout](/api#tag/payout/POST/api/v1/client/{clientHashId}/payout/bulk). | Requirement | Recommended method | | ----------------------------- | ------------------------- | | One-time payout | Inline beneficiary | | Recurring payout | Pre-created beneficiary | | Manual spreadsheet workflow | CSV batch upload (Portal) | | High-volume automated payouts | Batch payouts API | For full walkthroughs and examples for single payouts, see [Transfer Money](/docs/payouts/transfer-money). ### Funding behavior Batch payouts debit funds from the specified wallet for each individual `payout`. Funds are reserved only after the `payout` is successfully validated and processing begins; funds are not debited at submission time. When scheduling batch payouts, prefunding rules apply. For more information, see [Prefund Account](/docs/payins/program-client-and-client-prefund-account) ### Key concepts Key concepts of batch payouts include: | Concept | Description | | ----------------- | ------------------------------------------------------------- | | `batch` | A group of individual `payouts` submitted together *in bulk*. | | `batchExternalId` | Unique identifier you create to track a batch. | | `batchStatus` | Overall processing state of the batch. | | `item` | A single `payout` within a batch. | | `itemStatus` | The processing state of the individual payout. | ## Nium API The requests available to manage batch payouts include: | Request | Method | Endpoint | Description | | ---------------------------------------------------------------------------------------------------------- | -------- | ------------------------------- | ----------------------------------------------------------------- | | [Create Batch Payout](/api#tag/payout/POST/api/v1/client/{clientHashId}/payout/bulk) | **POST** | `/payout/bulk` | Submit a new batch of payouts. | | [Fetch Batch Payout Status](/api#tag/payout/GET/api/v1/client/{clientHashId}/payout/bulk/{batchId}/status) | **GET** | `/payout/bulk/{batchId}/status` | Retrieve batch-level status and summary | | [List Payouts in a Batch](/api#tag/payout/GET/api/v1/client/{clientHashId}/payout/bulk/{batchId}) | **GET** | `/payout/bulk/{batchId}` | Retrieve payout-level results (supports filtering and pagination) | Please note, the following limits apply: - Maximum payouts per batch: **1,000 payouts** - Maximum request payload size: **10 MB** ### Create a Batch Payout Use the POST request [Create Batch Payout](/api#tag/payout/POST/api/v1/client/{clientHashId}/payout/bulk) to create a batch payout. Use the `payouts` object to include the details of the `beneficiary` and `paymentAccount` for each payout. Please note: - A batch can complete successfully even if some individual payouts fail or are returned. - Submitting a batch does not execute payouts immediately. Use webhooks or the `status` field to track progress. #### Request example ```shell curl --request POST \ --url https://gateway.nium.com/api/payout/bulk \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' \ --data '{ "fundingSource": { "fundingInstrumentId": "fi_123456", "fundingChannel": "DIRECT_DEBIT", "statementNarrative": "November Payroll" }, "batchExternalId": "payroll-2025-11-30", "executeAt": "2025-11-30", "payouts": [ { "externalId": "TEST10-ITEM-001", "customerHashId": "1027d7c5-2577-4e1e-b462-c15728fe16e8", "walletHashId": "d396c4d4-dd23-4cc4-a5c0-d0a1d9f151d2", "beneficiary": { "beneficiary": { "name": "John Doe", "accountType": "INDIVIDUAL", "addresses": [ { "type": "BILLING", "line1": "6", "line2": "Levuka St", "city": "Cairns", "state": "Queensland", "countryCode": "AU", "postalCode": "4868" } ] }, "paymentAccount": { "accountNumber": "999994", "payoutCurrency": "AUD", "payoutMethod": "LOCAL", "routingCode": [ { "type": "BSB CODE", "value": "063019" } ] } }, "payout": { "payoutCurrency": "AUD", "sourceCurrency": "USD", "destinationAmount": "100" } } ] }' ``` #### Response example ```json { "batchExternalId": "TEST010", "batchId": "dee896d5-3f40-4f9f-a799-f4f84fa9791e", "status": "RECEIVED", "totalCount": 1 } ``` #### Lifecycle After a batch payout is submitted, it updates to the following statuses: | `status` | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **received** | The batch was accepted and waiting for payouts to be validated by Nium. | | **validated** | Validation completed. Returns counts for payouts that were accepted and payouts that returned validation errors. | | **processing** | Accepted payouts are being processed. | | **completed** | All accepted payouts have reached a final status. | | **partially\_failed** | Some **accepted** payouts ended in **returned** or **failed** status. Review the individual `payout` for more details. | | **failed** | Batch could not be processed. | | **cancelled** | The batch or schedule was cancelled before processing began. | For more information about the different statuses payouts go through, see [Transaction Lifecycle](/docs/payouts/transfer-money/remittance-lifecycle). ### Fetch Batch Payout Status Use the GET request [Fetch Batch Payout status](/api#tag/payout/GET/api/v1/client/{clientHashId}/payout/bulk/{batchId}/status) to retrieve the overall status of a batch. #### Request example ```shell curl --url https://gateway.nium.com/api/payout/bulk{batchId}/status \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-key: pQ7rS9tUvWxYz1a2B3c4D5e6F7g8H9i0' ``` #### Response example ```json { "batchExternalId": "TEST010", "batchId": "dee896d5-3f40-4f9f-a799-f4f84fa9791e", "status": "ACCEPTED", "summary": { "total": 1, "processing": 1, "failed": 0, "paid": 0, "returned": 0 }, "createdAt": "2025-12-09T07:15:21.926139Z", "completedAt": null, "links": { "self": "/api/v1/client/86528edd-55a3-4a2c-9939-144ed9be43ef/payout/bulk/dee896d5-3f40-4f9f-a799-f4f84fa9791e/status", "items": "/api/v1/client/86528edd-55a3-4a2c-9939-144ed9be43ef/payout/bulk/dee896d5-3f40-4f9f-a799-f4f84fa9791e?status=INITIATED" } } ``` ### List Payouts in a Batch Use the GET request [List Payouts in a Batch](/api#tag/payout/GET/api/v1/client/{clientHashId}/payout/bulk/{batchId}) to list the details of the `items` or individual `payouts` in a batch. #### Query parameters | Parameter | Description | | ------------ | ------------------------------------------------------------------------ | | `status` | Filter returned payouts by status. | | `externalId` | Filter returned payouts by the `externalId` used during payout creation. | | `limit` | Maximum number of payouts returned per page. | | `cursor` | Pagination cursor. | #### Response example ```json { "batchExternalId": "cust-001", "batchId": "b_20251103", "page": { "limit": 3, "nextCursor": "eyJvZmZzZXQiOjZ9", "prevCursor": "eyJvZmZzZXQiOjB9" }, "items": [ { "externalId": "INV-001", "transactionId": "RT987654321", "status": "ACCEPTED", "failure": [ { "status": "BAD_REQUEST", "code": "AC03", "message": "The beneficiary's account number is invalid or missing.", "body": "string", "errors": [ "tag key is mandatory" ], "field": "beneficiary.accountNumber", "action": "Confirm the correct beneficiary.accountNumber with the beneficiary.", "regex": "^[A-Za-z0-9 \-.]{1,255}$" } ], "createdAt": "2025-11-03T08:59:10Z", "updatedAt": "2025-11-03T09:00:12Z", "return": { "code": "AC03", "message": "The beneficiary's account number is invalid or missing.", "reasonCode": "InvalidCreditorAccountNumber" } } ] } ``` ## Webhook After creating a batch payout, you receive a webhook when the batch completes validation: #### Event example ```json { "event": "batch.completed", "batchId": "b_123", "status": "partially_failed", "counts": { "total": 1000, "accepted": 400, "paid": 390, "returned": 10, "validation_error": 600 } } ``` ## Error handling Errors that can be returned when creating a batch include: | HTTP status | Error code | Description | | ----------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------- | | 400 | `missing_field` | One or more required fields are missing or fail schema validation. Resubmit the request. | | 409 | `duplicate_externalId` | The same `externalId` appears more than once within the batch. Change the `externalId` and resubmit the request. | | 409 | `idempotency_conflict` | The `batchExternalId` conflicts with an existing request. Change the `batchExternalId` and resubmit the request. | | 413 | `payload_too_large` | The request exceeds 10 MB or contains more than 1,000 payouts. Create multiple batch payouts to process your payload. | Any payout that is returned or hits a validation error can be corrected and resubmitted individually or in a new batch. ## Next steps Batch payouts support scalable, asynchronous processing of high-volume payout workflows, with batch-level tracking, item-level results, and lifecycle webhooks. See: - [Nium Portal](/docs/nium-portal/batch-payouts#create-a-batch-payout) for details on how to create batch payouts using the dashboard. - [Track Payouts](/docs/payouts/track-payouts) to monitor batch progress, review item-level outcomes, and reconcile results. --- # Country and Regional Guides URL: https://docs.nium.com/docs/payouts/country-and-regional-guides Use these guides to understand payout behavior, beneficiary requirements, processing timelines, and return scenarios for specific countries and regional payment networks. --- # ACH Payments - USD URL: https://docs.nium.com/docs/payouts/country-and-regional-guides/usd-payments-to-the-united-states-ach Send USD payouts to US bank accounts using the ACH network. ACH (Automated Clearing House) is a local payment network used to send USD payments to bank accounts across the United States. ACH provides a **cost-effective alternative to wire transfers** and is widely used for payroll, vendor payments, and other recurring transactions. ACH payments are **not real-time**. Instead, payments are processed in scheduled clearing batches. Two ACH payment types are relevant for payouts: - **Same-day ACH** – A domestic ACH clearing system that processes payments in multiple settlement windows during the business day. - **International ACH (IAT)** – Used for cross-border ACH payments initiated by clients onboarded with Nium entities outside the United States. ## ACH processing windows ACH payments are processed in clearing batches throughout the day. All times below are **Eastern Standard Time (EST)**. | Window | Cutoff Time | Funds Available to Beneficiary | | ------------- | ----------- | ------------------------------ | | First window | 10:30 | 13:30 | | Second window | 14:45 | 17:00 | | Third window | 16:45 | 18:00 | If a payout request is submitted before the **daily cutoff time**, funds are typically credited **on the same business day**. ## Payment method details The following details the values to use when creating an ACH payment: | Attribute | Value | | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | Payout method | `LOCAL` | | Routing code type | `ACH CODE` | | Destination currency | USD | | Delivery time | Same day | | Cutoff time | 15:15 ET | | Availability | Business days only | | Beneficiary bank network | All US banks with ABA routing numbers | | Account verification | Supported | | Narrative | `remitter.name` and `customerComments` appear on the beneficiary account statement (10 character limit each) | | Supported countries | United StatesUS Virgin IslandsGuamAmerican SamoaNorthern Mariana IslandsPuerto Rico | ## Payout lifecycle ACH payouts follow the standard remittance lifecycle with additional ACH-specific status updates. Remittance Lifecycle | Step | Status | Description | Step Type | | ---- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | 1 | SCHEDULEDAWAITING\_FUNDSCANCELLEDEXPIREDFAILEDINITIATEDRFI\_REQUESTEDRFI\_RESPONDEDCOMPLIANCE\_COMPLETEDREJECTEDPG\_PROCESSING | For definitions, see [Track Payouts](/docs/payouts/track-payouts). | Generic | | 2 | `SENT_TO_BANK` | The payment has been submitted to the partner bank for ACH processing. Nium submits ACH payouts in batches to align with ACH clearing windows. | Country-specific | | 3 | `PAID` | The partner bank confirms that the payment has been submitted to the Federal Reserve for settlement. Confirmation is typically received at **19:00 ET**. | Country-specific | | 4 | `RETURN` | The payment was unsuccessful and returned by the receiving bank (for example invalid account details or closed account). Returns typically occur within **2–4 business days**, depending on the return reason code. | Country-specific | For more information, see [Payout Lifecycle](/docs/payouts/track-payouts#payout-lifecycle). ACH payments received before **15:15 ET** are typically processed and credited to the beneficiary account on the same business day. For ACH settlement schedules, see the following NACHA documentation: [Same Day ACH Schedules and Funds Availability](https://www.nacha.org/resources/same-day-ach-schedules-and-funds-availability). ## Beneficiary requirements The following fields are required when sending USD payouts using ACH: | Beneficiary field | Inline Beneficiary field | Description | | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `payoutMethod` | `paymentAccount.payoutMethod` | Must be `LOCAL`. | | `beneficiaryName` | `beneficiary.name` | Must match the bank account holder name. | | `beneficiaryAccountNumber` | `paymentAccount.accountNumber` | US bank account number (typically 8–17 digits). | | `beneficiaryAccountType` | `beneficiary.accountType` | Indicates whether the beneficiary is an individual or corporate entity. | | `routingCodeType1: "ACH CODE"` | `paymentAccount.routingCode.type` | Must be `ACH CODE`. | | `routingCodeValue1` | `paymentAccount.routingCode.value` | 9-digit ACH routing number (do not use wire routing numbers). | | `beneficiaryBankAccountType` | `paymentAccount.accountType` | Must be `Savings` or `Checking`. | | beneficiaryAddressbeneficiaryCitybeneficiaryStatebeneficiaryCountryCodebeneficiaryPostcode | beneficiary.addresses.line1beneficiary.address.citybeneficiary.address.statebeneficiary.address.countryCodebeneficiary.address.postalCode | Beneficiary address including street, city, state, and postal code. | **State is required for beneficiaries in:** - United States - Canada - Mexico For more information, see [Customer Onboarding](/docs/onboarding/customer-onboarding) ## Return codes and troubleshooting The following ISO return codes are commonly associated with ACH payouts. | ISO Code | ISO Definition | Reason | Resolution | | -------- | ---------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `AC03` | InvalidCreditorAccountNumber | Invalid account number or invalid combination of account number and routing code. | Verify the account number and routing code. Use [Nium Verify](/docs/verify) or confirm details with the beneficiary. | | `AC12` | InvalidAccountType | Invalid account type (Savings or Checking). | If not provided, Nium defaults to **Checking**. Ensure `paymentAccount.accountType` is set correctly. | | `AM09` | WrongAmount | Beneficiary denied receipt of the payment or does not recognize the sender. | Confirm the beneficiary details and verify that the payment was sent to the intended account. | | `AC04` | ClosedAccountNumber | The beneficiary account is closed or invalid. | Confirm updated account details with the beneficiary. | ### Notifications of Change (NOC) ACH networks may return **Notifications of Change (NOC)** when payment details are incorrect. Examples include: - incorrect routing numbers - outdated account information - formatting errors When a NOC is received, Nium stores the corrected information. Subsequent payouts using the same incorrect details may be rejected with validation errors until the information is updated. --- # EFT and Interac Payments - CAD URL: https://docs.nium.com/docs/payouts/country-and-regional-guides/cad-payments-to-canada-eft-and-interac Send CAD payouts to bank accounts in Canada using EFT or Interac. Nium supports local CAD payouts to Canada through three domestic payment rails: - **EFT (Electronic Funds Transfer)** for same-day batch processing to Canadian bank accounts. - **Interac e-Transfer** for near real-time payouts to bank accounts enabled with Interac. - **Interac Proxy** for near real-time payouts addressed to a beneficiary's email address or mobile number enabled for auto-deposit. Use EFT when you need broad bank account coverage and same-day settlement on business days. Use Interac when you need faster delivery and the beneficiary can receive Interac transfers. Use Interac Proxy when you only have the beneficiary's email address or mobile number. *** ## Payment method details The following table shows the values for each CAD payout rail. | Attribute | Interac | Interac Proxy | EFT | | ------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------- | | Payout method | `LOCAL` | `PROXY` | `LOCAL` | | Payout rail | `ca_interac` | `ca_interac` | `ca_eft` or blank | | Beneficiary identifier | Bank account number | Email address or mobile number | Bank account number | | Routing code type | `BANK Code` `TRANSIT NUMBER` | Not required | `BANK Code` `TRANSIT NUMBER` | | Delivery time | 15 to 60 minutes | 15 to 60 minutes | Same day | | Availability | 7 days a week | 7 days a week | Business days only | | Operating hours / cutoff | 05:00 to 22:30 ET | 05:00 to 22:30 ET | 18:00 ET | | Transaction limit | CAD 0.01 to CAD 25,000 | CAD 0.01 to CAD 25,000 | CAD 0.01 to CAD 99,000,000 | | Beneficiary coverage | Canadian bank accounts supporting Interac payments | Email or mobile numbers registered for Interac auto-deposit | Canadian bank accounts that support EFT | | Narrative | `remitter.name` and `customerComments` appear on the beneficiary statement | `remitter.name` and `customerComments` appear on the beneficiary statement | Not supported | *** ## EFT processing windows EFT payments are processed in clearing batches during the business day. All times below are Eastern Standard Time (EST). | Window | Cutoff time | Funds available to Beneficiary | | ------------- | ----------- | ------------------------------ | | First window | 04:00 | 11:30 | | Second window | 13:00 | 18:30 | | Third window | 18:00 | 23:00 | If a payout is submitted before the applicable cutoff, funds are typically credited on the same business day. *** ## Payout lifecycle CAD payouts follow the standard remittance lifecycle with additional Canada-specific status updates. | Step | Status | Description | Step type | | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | 1 | `SCHEDULED` `AWAITING_FUNDS` `CANCELLED` `EXPIRED` `FAILED` `INITIATED` `RFI_REQUESTED` `RFI_RESPONDED` `COMPLIANCE_COMPLETED` `REJECTED` `PG_PROCESSING` | Standard payout lifecycle statuses. For definitions, see [Track Payouts](https://docs.nium.com/docs/payouts/track-payouts). | Generic | | 2 | `SENT_TO_BANK` | EFT payouts are submitted to EFT clearing. Interac and Interac Proxy payouts are submitted to the Interac network. | Country-specific | | 3 | `PAID` | For EFT, the payment has been successfully submitted to EFT clearing and is expected to complete based on the batch credit schedule. For Interac and Interac Proxy, the beneficiary has been credited, typically within 15 to 60 minutes. | Country-specific | | 4 | `RETURN` | The payout was returned by the receiving bank or payment network, for example due to invalid account details, a closed account, or limit restrictions. Returns are typically received within 2 to 7 days. | Country-specific | For more information, see [Payout Lifecycle](https://docs.nium.com/docs/payouts/track-payouts#payout-lifecycle). > **Note:** For CAD EFT payouts, `PAID` can include the sub-statuses `PROCESSED_BY_CLEARING` and `DEEMED_PAID`. For more information, see [Track Payouts](https://docs.nium.com/docs/payouts/track-payouts). *** ## Beneficiary requirements ### EFT and Interac (account-based) The beneficiary structure is the same for EFT and Interac. The only rail-specific field is `payoutRail`. | Beneficiary field | Inline beneficiary field | Description | | -------------------------- | ----------------------------------- | ------------------------------------------------------------------------------- | | `payoutMethod` | `paymentAccount.payoutMethod` | Must be `LOCAL`. | | `payoutRail` | `payoutRail` | Use `ca_interac` for Interac payouts. For EFT, this can be `ca_eft` or omitted. | | `beneficiaryName` | `beneficiary.name` | Must match the beneficiary bank account name. | | `beneficiaryAccountNumber` | `paymentAccount.accountNumber` | Canadian bank account number. | | `beneficiaryBankCode` | `paymentAccount.bankCode` | 3-digit bank code that identifies the bank. | | `routingCodeType` | `paymentAccount.routingCode.type` | Must be `TRANSIT NUMBER`. | | `routingCodeValue` | `paymentAccount.routingCode.value` | 5-digit transit number that identifies the branch. | | `beneficiaryCountryCode` | `beneficiary.addresses.countryCode` | Must be `CA`. | | `beneficiaryAccountType` | `beneficiary.accountType` | Indicates whether the beneficiary is an individual or corporate entity. | | `beneficiaryAddress` | `beneficiary.addresses.line1` | Required only for clients onboarded with the Nium Canada or Australia entity. | For more information, see [Customer Onboarding](https://docs.nium.com/docs/onboarding/customer-onboarding). ### Interac Proxy Interac Proxy payouts are addressed to a beneficiary's email address or mobile number instead of bank account details. The beneficiary must have **Interac auto-deposit enabled** for the proxy identifier — straight-through processing is only possible when auto-deposit is active. > Nium only processes Interac Proxy payments where auto-deposit is enabled on the proxy identifier. Payments to identifiers without auto-deposit are not supported. | Beneficiary field | Inline beneficiary field | Description | | ------------------------ | ----------------------------------- | -------------------------------------------------------------------------------- | | `payoutMethod` | `paymentAccount.payoutMethod` | Must be `PROXY`. | | `payoutRail` | `payoutRail` | Must be `ca_interac` or omitted. | | `proxyType` | `paymentAccount.proxyType` | Must be `EMAIL` or `MOBILE`. | | `proxyValue` | `paymentAccount.proxyValue` | The beneficiary's email address or mobile number. See format requirements below. | | `beneficiaryName` | `beneficiary.name` | Name of the beneficiary. | | `beneficiaryCountryCode` | `beneficiary.addresses.countryCode` | Must be `CA`. | | `beneficiaryAccountType` | `beneficiary.accountType` | Indicates whether the beneficiary is an individual or corporate entity. | | `beneficiaryAddress` | `beneficiary.addresses.line1` | Required only for clients onboarded with the Nium Canada or Australia entity. | ## Return codes and troubleshooting The following ISO return codes are commonly associated with CAD payouts to Canada. | ISO code | ISO definition | Reason | Resolution | | -------- | ---------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `AC03` | InvalidCreditorAccountNumber | The beneficiary account number is invalid or does not exist at the receiving bank. | Verify the account number, bank code, and transit number with the beneficiary. | | `AC04` | ClosedAccount | The beneficiary bank account is closed and cannot receive payments. | Confirm updated account details with the beneficiary before retrying the payout. | | `AG03` | TransactionNotSupported | The beneficiary account is not Inetrac supported or auto-deposit enabled for proxy payments. | Confirm the beneficiary has Interac auto-deposit enabled for the email or mobile number provided. | --- # SEPA Payments - EUR URL: https://docs.nium.com/docs/payouts/country-and-regional-guides/eur-payments-to-sepa Send EUR payouts to bank accounts in SEPA countries using SEPA Instant or SEPA Credit. SEPA (Single Euro Payments Area) is a standardized payment network for sending EUR between bank accounts across SEPA countries. Nium supports EUR local payouts through two SEPA rails: - **SEPA Instant (SCT Inst)** for real-time payouts - **SEPA Credit (SCT)** for same-day payouts When a beneficiary bank supports SEPA Instant and the payout amount is within the supported limit, Nium attempts to route the payment through the instant network first. If instant processing is unavailable, Nium routes the payment through standard SEPA Credit. ## SEPA payment rails | Feature | SEPA Credit (SCT) | SEPA Instant (SCT Inst) | | ------------ | ------------------- | ------------------------ | | Speed | Same day | Within 10 seconds | | Availability | Business hours only | 24/7/365 | | Cutoff time | 14:00 EET | Not applicable | | Amount limit | No fixed limit | Up to EUR 999,999,999.99 | ## Supported countries Nium supports SEPA payouts to bank accounts in the following SEPA countries: - Andorra - Albania - Austria - Belgium - Bulgaria - Switzerland - Cyprus - Czech Republic - Germany - Denmark - Estonia - Spain - Finland - France - United Kingdom - Guernsey - Gibraltar - Guadeloupe - Greece - Croatia - Hungary - Ireland - Isle of Man - Iceland - Italy - Jersey - Liechtenstein - Lithuania - Luxembourg - Latvia - Monaco - Moldova - Montenegro - North Macedonia - Martinique - Malta - Netherlands - Norway - Poland - Portugal - Réunion - Romania - Serbia - Sweden - Slovenia - Slovakia - San Marino - Vatican City Some banks in supported SEPA countries may not be connected to the SEPA network or may not support SEPA Instant. In those cases, Nium may route the payment through a different available rail to complete delivery. For more information, contact your Nium account manager or [Nium Support](mailto:support@nium.com). ## Payment method details The following table shows the values to use when creating a EUR local payouts to a SEPA beneficiary. | Attribute | Value | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Payout method | `LOCAL` | | Routing code type | `SWIFT Code` | | Destination currency | EUR | | Delivery time | Real-time for payouts up to EUR 999,999,999.99 when the beneficiary bank supports SEPA InstantSame day for payouts processed through SEPA Credit | | Cutoff time and availability | SEPA Instant: 24/7/365SEPA Credit: Business hours only, with a cutoff of 14:00 EET | | Beneficiary bank network | Banks in supported SEPA countries that are connected to the SEPA network | | Account verification | Supported. For more information, see [Verification of Payee](https://docs.nium.com/docs/onboarding/vop-guidelines). | | Narrative | `remitter.name` and `customerComments` appear on the beneficiary account statement | ## Payout lifecycle SEPA payouts follow the standard remittance lifecycle with additional SEPA-specific status updates. | Step | Status | Description | Step type | | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | 1 | `SCHEDULED``AWAITING_FUNDS``CANCELLED``EXPIRED``FAILED``INITIATED``RFI_REQUESTED``RFI_RESPONDED``COMPLIANCE_COMPLETED``REJECTED``PG_PROCESSING` | Standard payout lifecycle statuses. For definitions, see [Track Payouts](https://docs.nium.com/docs/payouts/track-payouts). | Generic | | 2 | `SENT_TO_BANK` | The payment has been submitted to the SEPA network for processing. | Country-specific | | 3 | `PAID` | The beneficiary has been credited either in real time through SEPA Instant or on the same day through SEPA Credit. | Country-specific | | 4 | `RETURN` | The payout was returned by the receiving bank or network, for example due to invalid account details or a closed account. Returns are typically received within 2 to 3 days. | Country-specific | For more information, see [Payout Lifecycle](https://docs.nium.com/docs/payouts/track-payouts#payout-lifecycle). ## Beneficiary requirements The following fields are required when sending EUR payouts through SEPA. | Beneficiary field | Inline beneficiary field | Description | | --------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `payoutMethod` | `paymentAccount.payoutMethod` | Must be `LOCAL`. | | `beneficiaryName` | `beneficiary.name` | Must match the registered bank account name. | | `beneficiaryAccountNumber` | `paymentAccount.accountNumber` | Must be a valid IBAN. | | `beneficiaryAccountType` | `beneficiary.accountType` | Indicates whether the beneficiary is an individual or corporate entity. | | `routingCodeType1: "SWIFT CODE"``routingCodeValue1` | `paymentAccount.routingCode.type``paymentAccount.routingCode.value` | `paymentAccount.routingCode.type` must be `SWIFTCODE`.`paymentAccount.routingCode.value` must be an 8-character or 11-character SWIFT code.Some banks accept only 11-character SWIFT codes. | | `beneficiaryCountryCode` | `beneficiary.addresses.countryCode` | Must be a valid country code for the beneficiary. | | `beneficiaryAddress` | `beneficiary.addresses.line1` | Required only for clients onboarded with the Nium Canada or Australia entity. | For more information, see [Customer Onboarding](https://docs.nium.com/docs/onboarding/customer-onboarding) ## Return codes and troubleshooting The following ISO return codes are commonly associated with SEPA payouts. | ISO code | ISO definition | Reason | Resolution | | -------- | ---------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AC06` | BlockedAccount | The beneficiary bank account is blocked and cannot receive payments. | Use [Nium Verify](https://docs.nium.com/docs/verify) if enabled, or confirm the beneficiary details before retrying the payout. | | `AC04` | ClosedAccount | The beneficiary bank account is closed and cannot receive payments. | Use [Nium Verify](https://docs.nium.com/docs/verify) if enabled, or confirm updated account details with the beneficiary. | | `AC01` | IncorrectAccountNumber | The IBAN is invalid or does not exist at the receiving bank. | Verify the IBAN with the beneficiary before retrying the payout. | | `RC02` | InvalidBankIdentifier | The SWIFT code is invalid, unsupported, or does not match the beneficiary account. | Confirm that the IBAN and SWIFT code belong to the same bank.Confirm whether the beneficiary bank requires an 11-character SWIFT code.Verify that the SWIFT code is still valid and can receive the selected payout rail. | ## Verification of Payee From October 9, 2025, EUR local payouts are subject to Verification of Payee (VoP) requirements. Nium performs VoP checks on eligible EUR local payouts to verify that the beneficiary name matches the account holder name at the destination bank. You can also use [Nium Verify](https://docs.nium.com/docs/verify) before creating a payout to reduce payment rejections. For more details, override behavior, and testing guidance, see [Verification of Payee](https://docs.nium.com/docs/onboarding/vop-guidelines). --- # GBP Payments - UK and Crown Dependencies URL: https://docs.nium.com/docs/payouts/country-and-regional-guides/gbp-payments-to-the-united-kingdom-and-crown-dependencies Send GBP payouts to bank accounts in the United Kingdom and Crown Dependencies using Faster Payments or CHAPS. Nium supports local GBP payouts through the United Kingdom domestic payment infrastructure. GBP local payouts are processed through two payment rails: - **Faster Payments** for near real-time delivery - **CHAPS** for same-day high-value payouts This payout corridor covers the United Kingdom and connected jurisdictions whose banks participate in the same domestic clearing reach. ## Payment rails | Feature | Faster Payments | CHAPS | | ------------ | ------------------- | ------------------ | | Speed | Near instant | Same day | | Availability | 24/7/365 | Business days only | | Amount limit | Up to GBP 1,000,000 | No fixed limit | | Cutoff time | Not applicable | 15:30 GMT | Nium routes payouts of up to GBP 1,000,000 through Faster Payments for real-time delivery. Payouts above that threshold are routed through CHAPS. ## Supported countries and territories Nium supports local GBP payouts to the following destinations: United KingdomGibraltarIsle of ManGuernseyJersey ## Payment method details The following table shows the values to use when creating a GBP local payout. | Attribute | Value | | ------------------------------- | --------------------------------------------------------------------------------- | | Payout method | `LOCAL` | | Routing code type | `Sort Code` | | Beneficiary bank account number | 8-digit account numberIBAN | | Destination currency | GBP | | Delivery time | Real-time for payouts up to GBP 1,000,000Same day for higher-value payouts | | Cutoff time | 15:30 GMT for high-value payouts | | Availability | Faster Payments: 24/7/365CHAPS: Business days only | | Beneficiary bank network | UK and Crown Dependency banks with supported sort codes | | Account verification | Supported. For more information, see [Nium Verify](/docs/verify). | | Narrative | `NIUM Fintech` and `customerComments` appear on the beneficiary account statement | For more information about sort codes, see [Routing Codes](/docs/payouts/transfer-money/routing-codes). ## Payout lifecycle GBP payouts follow the standard remittance lifecycle with additional corridor-specific status updates. | Step | Status | Description | Step type | | ---- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | 1 | SCHEDULEDAWAITING\_FUNDSCANCELLEDEXPIREDFAILEDINITIATEDRFI\_REQUESTEDRFI\_RESPONDEDCOMPLIANCE\_COMPLETEDREJECTEDPG\_PROCESSING | Standard payout lifecycle statuses. For definitions, see [Track Payouts](/docs/payouts/track-payouts). | Generic | | 2 | `SENT_TO_BANK` | The payment has been submitted to the Faster Payments or CHAPS network. | Country-specific | | 3 | `PAID` | The beneficiary has been credited in real time for Faster Payments or on the same day for CHAPS. | Country-specific | | 4 | `RETURN` | The payout was returned by the receiving bank or network, for example due to an invalid sort code, an invalid account number, or a closed account. Returns are typically received within 2 to 3 days. | Country-specific | For more information, see [Payout Lifecycle](/docs/payouts/track-payouts#payout-lifecycle). ## Beneficiary requirements The following fields are required when sending GBP payouts to the United Kingdom and Crown Dependencies. | Beneficiary field | Inline beneficiary field | Description | | -------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `payoutMethod` | `paymentAccount.payoutMethod` | Must be `LOCAL`. | | `beneficiaryName` | `beneficiary.name` | Must match the bank account name. | | `beneficiaryAccountNumber` | `paymentAccount.accountNumber` | Must be an 8-digit account number or an IBAN. | | `routingCodeType1: "SORT CODE"``routingCodeValue1` | `paymentAccount.routingCode.type``paymentAccount.routingCode.value` | `paymentAccount.routingCode.type` must be `SORT CODE` when you provide a domestic account number.`paymentAccount.routingCode.value` must be a 6-digit UK sort code.If the beneficiary account number is provided as an IBAN, Nium can derive the sort code from the IBAN. | | `beneficiaryAccountType` | `beneficiary.accountType` | Indicates whether the beneficiary is an individual or corporate entity. | | `beneficiaryCountryCode` | `beneficiary.addresses.countryCode` | Must be a valid country code for the beneficiary. | | `beneficiaryAddress` | `beneficiary.addresses.line1` | Required only for clients onboarded with the Nium Canada or Australia entity. | Some valid sort codes do not support Faster Payments. This can affect routing and lead to payment rejection. If you are unsure whether a beneficiary bank can receive Faster Payments, verify the details with the beneficiary bank or use [Nium Verify](/docs/verify), if enabled for your account. For more information, see [Customer Onboarding](/docs/onboarding/customer-onboarding) ## Return codes and troubleshooting The following ISO return codes are commonly associated with GBP payouts. | ISO code | ISO definition | Reason | Resolution | | -------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `RC07` | IncorrectClearingSystemMemberIdentifier | The beneficiary bank sort code does not support the required payment rail. If you provided only an IBAN, Nium derives the sort code from the IBAN. | Use [Nium Verify](/docs/verify) if enabled, or confirm the beneficiary bank details before retrying the payout. | | `RC02` | InvalidBankIdentifier | The beneficiary bank sort code is invalid or missing. If you provided only an IBAN, Nium derives the sort code from the IBAN. | Verify the sort code or IBAN with the beneficiary before retrying the payout. | | `AC01` | IncorrectAccountNumber | The beneficiary account number is invalid or does not exist at the receiving bank. | Verify the beneficiary account number before retrying the payout. | | `AC04` | ClosedAccount | The beneficiary bank account is closed and cannot receive payments. | Confirm updated account details with the beneficiary before retrying the payout. | --- # Cards URL: https://docs.nium.com/docs/cards Cards allow your individual or corporate customer to pay any merchant—a store or commerce site—anywhere in seconds. Physical or digital cards are powered by global payment networks, such as Mastercard® and Visa®. A card is a payment instrument for your funds, stored at Nium, that's securely accepted by the major card payment networks in the world. A card is identified by its unique 16-digit primary account number (PAN), expiration date, and security code, called the card verification value (CVV). Depending on whether the physical card is issued for individual use or business use, the name of the cardholder is also present on the card. ## Card support Nium supports the complete card lifecycle, management, and security API operations. Refer to the following guides for more information: - [Card lifecycle](/docs/cards/card-lifecycle) - [Card management](/docs/cards/manage-cards) - [Card security](/docs/cards/card-security) ## Card type based on funding source **Prepaid card:** A prepaid card can be used to pay for things without cash, credit, or a bank account. You buy it with money loaded on it in advance. The card's balance acts as your spending limit. It's also called a prepaid debit card or a stored-value card. Financial entities may offer rewards or disbursements in the form of a prepaid card. It especially helps the unbanked to access and spend. **Debit card:** A debit card deducts money directly from a savings or checking account. It's also called a check card or a bank card. It's used to buy goods or services, get cash from an ATM, or add an extra amount of money to a purchase if allowed by a merchant. Nium, through its licenses and platform capabilities, can issue prepaid and debit cards to individuals or corporate businesses. The term *issue* is the technical word used to describe the provision of cards to customers with unique card numbers. Nium also offers prepaid and debit cards to its clients, with linkages to virtual account numbers (VANs). ## Card issuance at Nium You can primarily use Nium’s card issuance capabilities for the following: ### 1. [Spend](/docs/use-cases/spend-management) Nium offers its clients, who deal in expense management, procurement, and supplier payments, the option to offer cards to their customers for payments. It simplifies the monitoring and reconciliation of expenses while providing a fast and secure payment method. **Travel and entertainment expenses:** Businesses may need their employees to spend on travel and specific expenses on the company’s behalf as enabled under their specific organizational policies. **Purchase and procurement:** Businesses can use card payments for vendors or e-commerce merchants with a virtual card saved on the merchant portal. ### 2. [Payroll](/docs/use-cases/payroll) Nium offers its clients the option to pay their employees on record through cards. The employee, in turn, gets an employer-branded payment method to spend. ### 3. [Travel](https://docs.nium.com/travel/docs/quick-start-guide) The Nium travel-specific card is for virtual card payments for clients, such as online travel agencies and travel partners, to pay their suppliers with a single-use virtual card. ## Issue a card You can get cards in one or more of the following forms: | Physical card | Virtual card | Digital card | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A physical card is made out of plastic or metal. It's built with security features, such as an embedded chip so that it can be read by a merchant or an ATM which is authorized to read the details on its chip or magstripe or via near-field communication (NFC). | A virtual card is a visual representation of the card details, such as the PAN, expiration date, and CVV for access and use at online merchants. | A digital card is a tokenized value to be used with digital wallets, such as Apple Pay or Google Pay. It has the same card number, expiration date, and CVV as your physical card. | Nium issues the cards with an API call. **Physical:** When a customer asks for a physical card, it's printed and dispatched by Nium, the personalization vendor, to the address that the cardholder specifies. You and Nium need to agree on the turn-around time. The plastic card can be used at the merchant's location once it's received and activated. **Virtual:** When a customer asks for a virtual card, they get the 3 key details—card number, expiration date, and CVV—immediately so the card is ready for use. **Virtual upgraded to physical:** When a customer asks for a virtual card to be upgraded to a physical card, they get the virtual card immediately followed by the physical card as per the agreed schedule later. The virtual card and the physical card have the same details. The virtual card is ready to use on a merchant’s website during checkout by the cardholders and it's authenticated. The physical card is in an inactive state and needs to be activated by the cardholder before use. ## Use a card A card transaction is done when you present it to the merchant and the merchant attempts to read the card. Cards can be tapped at a card point-of-sale (POS) terminal that supports NFC reading or inserted or swiped. This scenario is identified as a *customer-present* and a *card-present transaction*. Card details, such as the card number, expiration date, and CVV, can also be entered on a merchant’s website during checkout by the cardholder. This information is authenticated. This scenario is identified as a *customer-present* but a *card-not-present* transaction. If the card is enrolled in websites such as Netflix or Spotify, where the merchant bills you automatically on the registered card for a monthly subscription, this scenario is identified as a *customer-not-present*, a *card-not-present*, or a *card-on-file* transaction. When you make a transaction on a card, it's completed within seconds of making it. The issuer authenticates and authorizes the transaction through a multi-stakeholder process. Nium supports different card authorization models, digital wallet tokenization, and 3D Secure (3DS) verification. Refer to the following guides for more information: - [Dynamic Authorization](/docs/cards/dynamic-authorization) - [Hosted Model](/docs/cards/dynamic-authorization/hosted-model) - [Extended Model](/docs/cards/dynamic-authorization/extended-model) - [Delegated Model](/docs/cards/dynamic-authorization/delegated-model) - [Digital Wallet Tokenization](/docs/cards/digital-wallet-tokenization) - [3DS Overview](/docs/cards/3ds-security) ## Fund a card Cards at Nium are linked to the virtual accounts or wallets of individual customers or corporate customers held at Nium. These accounts receive funding from the clients: 1. **Corporate-funded programs:** Nium typically supports card programs where you, the client, are funding Nium's bank account to hold and account for the virtual money to be used on cards. Nium also provides various account funding capabilities to collect funds from corporate customers on the Nium platform to fund the card program. 2. **Customer-funded programs:** Nium’s wallets support many collections and third-party funding programs. They also support individual customers who want to fund card programs. For more details on the card funding program, contact your Nium account representative. ## Restrict a card Apart from any regulatory compliance restrictions related to a person, place, etc., Nium places the below restrictions on the card issuing under any program. **Restriction by location**: Nium restricts the issuance of cards to countries that have been reviewed or agreed to mutually between the card networks and you. The restriction is made distinctly for virtual and physical cards, where physical cards *cannot* be shipped to cross-border markets. The list of countries is documented during the onboarding process and implemented: The primary card issuance country determines where the physical or virtual card is going to be issued. This value is configurable and can be changed in the future. You can only issue virtual or physical cards cross-border to approved countries. The Nium system verifies the cardholder’s billing address country against the approved countries listed. After that check, it allows the system to issue the cards to the respective countries. **Restriction by the number of cards**: Nium restricts the number of cards issued to a single customer—individual or corporate—per card network guidelines to a maximum—virtual or physical—of 1000 cards. The restriction is the upper limit and you can set a lower limit for your program as required. This restriction only accounts for active or locked cards and doesn't account for blocked or canceled cards. The platform checks the limits before every new issuance, assignment, or replacement of cards. The restriction on the number of cards can be imposed at: **Individual customer level**: The amount of all cards issued to a single individual customer needs to fall under the limit, irrespective of the corporate customer linked to the individual. **Corporate customer level**: The amount of all cards issued under a corporate customer, and linked to individual customers, needs to fall under the limit. ## Bulk card issuance Bulk card issuance refers to the process where many prepaid or debit cards are produced at the same time. Issuing cards in bulk is an efficient way to generate and distribute large quantities of cards and helps reduce delivery costs. Nium supports both personalized and generic card issuance. Cards can be personalized (Name on Card) or generic (no Name on Card), and be shipped in one single shipment. Bulk card issuance is often used for corporate programs, gift cards, payroll, or disbursements. For example: - Some payroll clients want to keep physical cards on hand and issue new cards when new employees join. - Some spend management clients want to issue physical cards to the employees for Travel & Expense spending. Please contact your Nium account manager or [Nium support](mailto:support@nium.com) if you’re interested in issuing cards in bulk. See the following for prerequisites and and details on how cards can be requested, assigned, and activated. ### Getting started To get started issuing cards in bulk: 1. Reach out to your account manager or [Nium support](mailto:support@nium.com) to get started. 1. Please note clients must, have an existing card program running with Nium to get approved to issue cards in bulk. 2. Upon receiving the client's request, Nium will take the necessary steps to set up a physical card program with the card manufacturer and the client's Nium account. 3. Nium will follow up with the client to confirm the quantity of physical cards to order. ### Card design and customization The client defines the card design, including branding, logos, and colors with Nium. Specifically, clients provide the card art or design to their Nium account manager or [Nium support](mailto:support@nium.com) while enabling bulk card issuance for the client. ### Placing an order Nium places a bulk order for cards based on the number .requested by the client. The client provide the preferred delivery address to their Nium account manager or [Nium support](mailto:support@nium.com) while providing the quantity of cards to order. ### Card manufacturing Physical cards are printed and encoded with unique identifiers such as the PAN (Primary Account Number), expiry dates, CVV, and, if applicable, personal details like the cardholder's name. Cards also undergo quality checks by the card manufacturer to ensure they are accurately created and secure. Fraud-prevention measures are also embedded, including holograms, EMV chips, and other security features. ### Card distribution and shipping Cards are shipped to the delivery address provided by the client to their Nium account manager or [Nium support](mailto:support@nium.com). ### Generic cards To order generic, or non-customized cards reach out to your account manager or [Nium support](mailto:support@nium.com) and provide the number of generic cards you'd like to order and the delivery address. Nium will verify the details, initiate the request, and ensure the requested quantity of card is delivered to the provided address. ### Assigning and activating physical cards Please note that bulk cards are shipped inactive. Cardholders must activate them using an online portal or mobile app as instructed by the client. 1. Verify the customer exists in your Nium account before assigning them a card. See the [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) request for details on how to add a new customer. 2. When the cards are received, clients can assign the cards to employees or customers using the [Assign Card](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/assignCard) request. 3. Once the card is assigned, Nium will send the [Activation Code](/docs/developers/notifications-and-webhooks/issuing-and-card-events/activation-code) to the client for the assigned card using a webhook event. 4. The client needs to forward the [Activation Code](/docs/developers/notifications-and-webhooks/issuing-and-card-events/activation-code) to the cardholder. 5. To activate the card, prompt the cardholder to activate their card using the [Activate Card V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/activate) request. Confirm that the activation code submitted is the same one returned in the [Activation Code](/docs/developers/notifications-and-webhooks/issuing-and-card-events/activation-code) webhook event. 6. Use the [Set/Reset PIN V2](/api#tag/security/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/showSecurityDetails) request to set a PIN (personal identification number) for the card. --- # Card Lifecycle URL: https://docs.nium.com/docs/cards/card-lifecycle To help your customers or recipients get and use their cards, the Nium One platform supports several APIs to address the cards' lifecycle process. The diagram below explains the different stages of a card's process and the APIs used: Card Lifecycle ### Add a new card The platform lets you issue cards in real time to your individual and corporate customers. The cards need to adhere to the endorsed use cases and the attributes ascribed to them during the client onboarding process. The `cardProductId` that your account manager gives you is unique to you and aligns with these attributes. Whether you're issuing a new card or adding a card, you can use the [Add Card V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) API to give your customers a unique non-cash payment instrument in their name. > 📒 NOTE > > Nium generates the `cardHashId` for a successful card issuance during the [Add Card V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) API as the card's unique identifier. Add Physical Card Add Virtual Card The customer can use the API to specify the following: 1. `cardExpiry`: The expiration date applies only to virtual cards and doesn't apply to physical cards. This field is in the `MMYY` format. For virtual cards, the expiration date can be a maximum of five years after the API is used. 2. `cardType`: This field accepts the card type issued. The acceptable values are: - `PHY`: This value is used to issue a physical card. - `VIR`: This value is used to issue a virtual card. - `VIRUP2PHY`: This value is used to issue a virtual card upgraded to a physical card. 3. `nameOnCard`: This field is used to print the customer's name on the card. If this field is empty, the first line on the card isn't printed. This field accepts alphanumeric characters along with spaces. The maximum character limit is 26. 4. `additionalLine` This field can be used to send the company name or an employee ID to be printed on the card. The additional line is printed directly below the name on the card. This field accepts alphanumeric characters along with spaces. The maximum character limit is 26. 5. `email`: The email address of the cardholder. 6. `countryCode`: The country code of the cardholder's phone number accepted in the two-letter [ISO Alpha-2](/docs/getting-started/currency-and-country-codes) country code format. 7. `mobile`: The cardholder's mobile phone number. 8. `issuanceMode`: This field is only required for the delivery of physical cards. The possible values are: - `NORMAL_DELIVERY_LOCAL` - `EXPRESS_DELIVERY_LOCAL` - `INTERNATIONAL_DELIVERY` 9. `plasticId`: The plastic ID that Nium defines and communicates to the client. It's used to determine the card designs that you receive as part of your program setup. 10. `delivery`: An object that contains the address details of the physical card delivery. ### Issue cards in bulk The platform lets you issue **physical** cards in bulk, which have the following benefits: - A large number of cards are issued and delivered instantly without cardholders assigned. - A large number of cards are issued with cardholder names personalized and delivered instantly. > 💁 TIP > > The platform's card operations team helps you through the process of ordering cards in bulk while you work with the solutions team to build the capability. ### Assign a card When you receive a cards-in-bulk order for a non-personalized card, you need to map it to the customers on Nium before it can be used. The [Assign Card](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/assignCard) API helps you assign your customer one of the cards received in bulk. The customer can then get and activate the card to start using it. Assign Physical Card ### Activate a physical card Unlike a virtual card, a customer needs to activate a physical card after they receive it. This prevents card fraud and misuse during delivery. It's important to remember the following states: - Physical cards are received in an `INACTIVE` state. - Virtual to physical cards are received in a `VIRTUAL_ACTIVE` state. The [Activate Card](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/activate) API lets your customer change the state of their physical card to `ACTIVE` and begin using it. You can collect verification data points, such as customer personal information, biometrics, etc., through your user experience to safeguard the activation process. Activate Physical Card ### Manage a card state Your customers may need to lock their card temporarily for security reasons or suspected activity and unlock it when they're ready to begin using it. The [Lock/Unlock Cards](/api#tag/lifecycle/PUT/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/lockAction) API lets your customers switch between a locked state and an active state as many times as needed. Lock/Unlock Card ### Block and replace a card Nium provides the capability to let your customers report and block a card if they suspect fraud, loss, theft, or damage. Once the card is blocked, Nium permanently closes it and it doesn't allow any more activity on it. Block/Replace Card The [Block And Replace Card](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/blockAndReplace) request blocks the card and gives you the option to request a new card. The replacement card requests information for similar fields, such as the card expiration date, contact email address, mobile number, and delivery address. It also adds a card and issues a new 16-digit primary account number (PAN) to the customer. ### Renew a card If a customer’s card is approaching its expiration date, you can ask them to renew it. The [Renew Card](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/renewCard) API uses the same PAN on the card, with a different expiration date and a CVV2. The API also lets the new card use the same or a different delivery address and contact details. Renew Card --- # Manage Cards URL: https://docs.nium.com/docs/cards/manage-cards After you set up your customer with their cards, you can offer them a number of functionalities using Nium APIs. The following are the card management APIs: ## Get card details The [Card Details V2](/api#tag/lifecycle/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}) API lets you get details about a card. Call this operation to help your customer see their card details to make sure they're accurate. Using the card's unique `cardHashId`, you can show your customer all card details, such as card status, demographics, and delivery information set during issuance, and other embossing and token details. Get Card Details ## Get card list The [Card List V2](/api#tag/lifecycle/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/cardsv2) API returns all the cards issued to a wallet so your customer can see them. This operation responds with the tabulated card details for your customer. Get Card List ## Update card details The [Update Card Details V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}) API lets you update your cardholder's contact information. You can let your customers change their card delivery address and contact details according to your policies. This operation captures the address for a card replacement or renewal and the contact information for 3DS and strong customer authentication (SCA) purposes. Update Card Details ## Use a card Your customers may need the flexibility to control their spending through your user experience. Nium APIs give you capabilities that let your customers control their card expenses. ### Transaction channels You can use your Nium-issued cards through various payment channels. Nium defines the following channels where the cardholder can restrict card usage. Refer to the [Card overview](/docs/cards) guide for more information. | By location | By mode | By physical card-use mechanism | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cross-border:** A cardholder can enable or disable cross-border transactions where the spending is in a foreign currency. \n \nDomestic transactions *are not* affected. | **ATM:** Enabling or disabling ATM usage lets a cardholder control if the card can be used to withdraw money at the ATM machine as applicable under the program. \n \n**In-store:** Enabling or disabling in-store usage lets a cardholder control if the card can be used to make card-present transactions at merchant locations. \n \n**Online:** Enabling or disabling online card usage lets a cardholder control if the card can be used online for card-not-present transactions by keying in the security details such as the 16-digit primary account number, the card name, the CVV, and the expiration date. | **Magnetic stripe:** Enabling the channel, also called magstripe, lets a cardholder use the capability to swipe at the merchant’s POS location while making a card-present transaction. \n \nDisabling it prevents magstripe use. \n \nOther card features such as insert (chip) and tap (NFC) *are not* affected. | ## Update a card restriction The [Update Channel Restriction](/api#tag/controls/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/channels) API lets a cardholder enable or disable, via block and unblock actions, the cross-border, ATM, in-store, online, and magnetic stripe card transaction channels. Update Card Restriction ## Get a card restriction The [Get Channel Restriction](/api#tag/controls/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/channels) API lets a cardholder get the transaction channel restriction set at the card level for cross-border, ATM, in-store, online, and magnetic stripe. The cardholder can check which channel is active or inactive. Get a Card Restriction ## Convert a card Use the [Convert Card](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/convert) request to convert a *virtual card* to a *physical card*. - Only active virtual cards can be converted. - The card's **expiry date remains the same** after conversion. This request is useful when your customer initially receives a virtual card and later requests a physical version for in-store or ATM use. ## Merchant category codes Merchant category codes (MCCs) are standard four-digit classifications for the merchants operating under the Visa® or Mastercard® network. There are hundreds of categories covering different goods or services such as lodging, food service, groceries, apparel, etc. Your customers may want to manage their spending by enabling or disabling certain merchant categories. The following are the Nium MCC management APIs: ## Update an MCC restriction The [Update MCC Channel Restrictions](/api#tag/controls/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/channels/mcc) API lets you create MCC-based channel restrictions at the card level. Merchant categories are allowlist or denylist. Your customer can create such merchant lists which can be set to active or inactive using the API call. Example: `Status = Active and ChannelStrategy = WHITE_LIST`. If the list contains commercial equipment or office supplies, the card can only transact at these merchants, while all other merchants are blocked for transactions. Example: `Status = Active and ChannelStrategy = BLACK_LIST`. If the list contains airline and lodging merchants, the card can't transact at these merchants, while all other merchants are open for transactions. Update Channel Restriction Nium, as a licensed entity, needs to restrict specific merchant categories as listed by regulators. Nium also filters required merchant categories based on the card program needs. These restrictions supersede any customer-level merchant restrictions. ## Get an MCC restriction The [Get MCC Channel Restrictions](/api#tag/controls/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/channels/mcc) API lets you fetch the MCC-based channel restrictions at the card level. It lets the cardholder check the active or inactive status of the merchant list. Get MCC Restriction ## Set card limits You can also give cardholders the flexibility to control how much and how frequently they spend on each card that they own at Nium. A customer can set each of the transaction card limits as `Active` or `Inactive`. They can also set a percentage of acceptance. The `additionalPercentage` value allows transactions to be breached by the set percentage over the limit, allowing a little flexibility on the limits. The [Card Limits](/api#tag/controls/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/limits) API lets a cardholder set their own custom card limits using the following parameters. Program-level restrictions supersede these controls. Set Card Limits ## Get card limits The [Fetch Card Limits](/api#tag/controls/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/limits) API lets a cardholder check the status of all the limits set. Fetch Card Limits | Card limit | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PER\_TRANSACTION\_AMOUNT\_LIMIT | A per-transaction amount limit means the maximum amount you can spend during a payment transaction. Limits are set by mutual agreement between the client and the customer. \n \nIf a customer sets a $100 per transaction limit, all transactions over $100 are effectively declined from the time of limit setting. | | DAILY\_AMOUNT\_LIMIT | A daily amount limit means the maximum amount a cardholder can make transactions on the purchase of goods or services and cash advances using the card within a day or a 24-hour period, starting at midnight. \n \nIf a $1,000 limit is set, and the system notes a $900 transaction until 6 p.m. local time and a $200 transaction is attempted at 7 p.m., it's declined. | | MONTHLY\_AMOUNT\_LIMIT | A monthly amount limit means the maximum transaction amount that can be spent in a month. The duration is the calendar month starting at midnight. It includes the sum of debit transactions subtracted by any reversals. \n \nThis limit is similar to the daily amount limit. The system accounts for this cap for transactions over the entire month. | | LIFETIME\_AMOUNT\_LIMIT | A lifetime amount limit means the maximum amount that can be spent, starting with the issuance of the card to the time when it's used. If a $5,000 limit is set and the system notes a $4,900 transaction in the lifetime of the card, if a $200 transaction is attempted, it's declined. | | LIFETIME\_COUNT\_LIMIT | A lifetime count limit is similar to the transaction amount limit. The limit can be placed on the number of transactions during the card's lifetime. | | TRANSACTION\_DURATION\_LIMIT | A transaction duration limit is set for a date range in the `YYYYMMDD-YYYYMMDD` format and Coordinated Universal Time (UTC)+00 time zone format. It restricts based on when the card is enabled for a transaction. | --- # Card Transactions URL: https://docs.nium.com/docs/cards/card-transactions A transaction is a record of a debit or credit event that impacts the wallet balance. ## Transaction types | Transaction type | Description | | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Auto_Sweep` | Automatically sweep from one currency to another within a wallet to authorize a transaction if multicurrency auto-sweep is set up. | | `Balance_Inquiry` | Balance inquiry transaction responds with a cumulative balance for single as well as multicurrency wallets in the base currency. | | `Chargeback_Credit` | Credit transaction in the case of a chargeback. | | `Debit` | Card transactions such as point-of-sale (POS), ATM, and e-commerce (ECOM). | | `Decline_Advice` | Declined transactions. Visa or Mastercard can decline any transaction if the Integrated Chip Card Card Verification Value (iCVV), Card Verification Value (CVV), or Dynamic Card Verification Value Card (dCVV) is invalid or if it's suspected of fraud. These declined transactions are reported and logged with the transaction type set as `Decline_Advice`. | | `Incremental_Auth _Reversal` | Online reversal of an incremental authorized transaction. | | `Original_Credit` | Received incoming Original Credit Transfer (OCT) and credited to the wallet linked to the cardholder's card. | | `Original_Credit _Reversal` | Online reversal of a direct transfer to a card, for example, reversal of an original credit transaction. | | `Partial_Reversal` | Online reversal of the partial amount of an earlier card transaction. | | `Reversal` | These are the three scenarios for a `Reversal` transaction:`Online Reversal`: A customer's purchase or transaction receives this status when a merchant initiates a reversal of its previously approved authorization.`Manual Reversal`: If due to any technical reason, an online reversal doesn't happen, the customer raises the issue. Then, the card operations team triggers a manual reversal from Nium One. After a successful reversal, the transaction is marked ‘Reversed’.`Transaction aging`: After a transaction is approved, if the merchant doesn't send the settlement after seven days, the transaction is automatically reversed based on Nium One's transaction aging rules. | | `Reversal_Advice` | Reversal is initiated when a timeout scenario happens. If Visa or Mastercard time out a card transaction, they generate a reversal advice to roll back the transaction. In the case of wallet clients, Nium applies the reversal advice and provides the credit back to the customer. In the case of [Delegated Model](/docs/cards/dynamic-authorization/delegated-model) authorization clients, Nium reverses funds on the client prefund account and also forwards the reversal advice to the Delegated Model client for crediting funds back to the customer. | | `Settlement_Credit` | Funds are credited to the cardholder's wallet when the settlement amount, processed during clearing, is less than the transaction amount, processed during the authorization. | | `Settlement_Debit` | Funds are debited from the cardholder's wallet when the settlement amount, processed during clearing, is more than the transaction amount, processed during the authorization. | | `Settlement_Direct _Debit` | Funds are debited from the cardholder's wallet for transactions based on the settlement file, for example, force posting. | | `Settlement_Direct _Reversal` | Funds are credited to the cardholder's wallet for the reversal of a debited transaction based on the settlement file. | | `Settlement_Reversal` | Funds are credited to the cardholder's wallet for the reversal of a debited transaction. | ## Examples ### Wallet client | # | Scenario | The platform creates the transaction record | | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | The account holder uses the card to shop at a merchant location. The merchant’s acquirer bank submits the transaction in real time for authorization. | The system creates a debit transaction record and captures details about the merchant, transaction amount, currency, and other relevant details. | | 2 | The account holder uses the card to shop at a merchant location. The merchant’s acquirer bank submits the transaction directly through clearing or forced posting. | The system creates a settlement direct debit transaction record and captures details about the merchant and the transaction amount. | | 3 | The account holder returns the previously purchased product to the merchant. The merchant triggers a full refund through its acquirer bank. Nium relates the refund to the original purchase transaction. | The system creates a new settlement reversal transaction record or credit amount. The system retains the original debit transaction record and there's no change to it. | ### [Delegated Model](/docs/cards/dynamic-authorization/delegated-model) client | # | Scenario | The platform creates the transaction record | | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | The account holder uses the card to shop at a merchant location. The merchant’s acquirer bank submits the transaction in real time for authorization. | The system forwards the request to the client for authorization. On approval from the client, the system creates a debit transaction record and captures details about the merchant, transaction amount, currency, and other relevant details. | | 2 | The account holder uses the card to shop at a merchant location. The merchant’s acquirer bank submits the transaction directly through clearing or forced posting. | The system creates a settlement direct debit transaction record and captures details about the merchant and the transaction amount. | | 3 | The account holder returns the previously purchased product to the merchant. The merchant triggers a full refund through its acquirer bank. Nium relates the refund to the original purchase transaction. | The system creates a new settlement reversal transaction record or credit amount. The system retains the original debit transaction record and there's no change to it. | ## Card transaction lifecycle In the Nium ecosystem, the card transaction lifecycle consists of two parts: - [Transaction authorization](#trans-auth) - [Transaction settlement](#trans-sett) ### Transaction authorization When a customer uses a card at a merchant location, the card middleware from the network receives an authorization request. #### For a wallet client If the authorization request passes all the limits and restrictions set for the client, customer, or card—and if there's sufficient balance—the transaction is approved. If not, the transaction is declined. #### For a Delegated Model client If the authorization request passes all the limits and restrictions set for the client, customer, or card, the card middleware forwards an authorization request to the client. The client needs to respond to the card middleware within a default hard limit of 2 seconds. If this fails, the authorization is declined. ### Transaction settlement Nium has a settlement cycle with the schemes where it receives a settlement file, for example, once a day for Visa. The card middleware processes the file and, if any adjustments are to be made to the transaction, they're done based on the data in the file. This file is treated as final. #### For a wallet client The settlement process is totally between Nium and the scheme. Every transaction is settled between Nium and the scheme. Any difference in the amounts, which may be credit or debit, is passed on to the customer’s wallet. #### For a Delegated Model client The settlement process is still between Nium and the scheme but Nium shares a settlement file with the client because the customer ledger is managed by the client. While Nium settles the transaction with the scheme and any differences are passed on to the client, it's up to the client to manage the customer ledgers. --- # Card Widget URL: https://docs.nium.com/docs/cards/card-widget The card widget allows you to embed a widget using a URL hosted by Nium. The widget enables you to securely embed and display sensitive card data in your mobile application or web page. To support this feature, a new API has been introduced called Get Card Details Widget API. Customers who don't follow the Payment Card Industry Data Security Standard (PCI DSS) need to integrate with this API to get the PCI DSS card details. This API is secured by JWT token authentication which is encrypted by AES RSA encryption algorithm. The card widget allows you to embed a widget using a URL hosted by Nium. The widget enables you to securely embed and display sensitive card data in your mobile application or web page. To support this feature, a new API has been introduced called [Get Card Details Widget](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/widget/token) API. Customers who don't follow the Payment Card Industry Data Security Standard (PCI DSS) need to integrate with this API to get the PCI DSS card details. This API is secured by JWT token authentication which is encrypted by AES RSA encryption algorithm. - This widget can be used by invoking Show Card Details API by passing the Customer Hash Id, Client Hash Id, Wallet Hash Id and Card Hash Id - Nium will respond with a widget URL, along with a JWT token - The URL plus token should only be valid for 10 minutes and then expire. - The widget will be shown on a URL hosted by Nium - The card details are written dynamically on the image, are not editable nor can be copied. - The widget URL is secured and Nium wraps the data in a JWT token which is encrypted by AES RSA encryption algorithm - For each plastic ID only one artwork is applicable for the widget display ## Steps to integrate a card widget: ### 1. Get a card widget URL. The [Get Card Details Widget](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/widget/token) API lets you get a card widget URL. The widget URL along with the token are only valid for 10 minutes before expiry. ```json { "widgetURL":"https://ipppreprod.partners.instarem.com/preprod/cards/widget/cardDetails?token=eyJhbGciOiJIUzI1NiJ9$$pEqF4g6d_UlPE0tRFQAIVBsLDxwBgxn9_vLb4UaC2Z8" } ``` ### 2. Add your widget URL to the client’s page. Use the retrieved card widget URL from **Step 1** and use it as input for **src=**`widgetUrl`. You can use an HTML iFrame tag on your page to add your image details. You can set the height and width of the iFrame tag depending on your page view. ```html ``` If you don't have Cascade Style Sheets set up in **Step 1**, then your default widget looks like the below image. Default Display with no Artwork ### 3. Upload the background image To provide your own artwork to display as background of this widget please contact your Nium representative. Specification for artwork template to be provided to Nium 1. Max file size should not be greater than 1 MB. 2. The pixel size of the image should be 999px width and 630px height at 144dpi. 3. Allowed image extensions are png, jpg and jpeg 4. Font Color - Only White Color font supported 5. You can use the top 210px and bottom 210px space to provide your custom design background images Template for Artwork (Image Format only) Sample widget display with Nium branding Sample widget Display --- # Card Security URL: https://docs.nium.com/docs/cards/card-security Your PIN is a four- or six-digit code that verifies a cardholder's identity. To complete an ATM or a point-of-sale (POS) transaction, you're required to enter your card PIN. Your PIN authorizes your transaction when you use your card. As soon as you enter your PIN, the payment system automatically matches it with your card profile before facilitating the transaction. This ensures that you're the only one authorizing your transactions and nobody else; thus, making your card safe and secure. Never share your card PIN with others to avoid any fraudulent activities on your account. ## Set a card PIN A PIN lets you access your account to get private sensitive information about your finances and help you make monetary transactions. Every country has a PIN-length requirement. | Country or region | PIN digits | | ----------------------------- | :--------: | | Singapore | 6 | | Europe and the United Kingdom | 4 | | Australia | 4 | | Hong Kong | 6 | If you're outside of the European Union (EU) and United Kingdom (UK) regions, you can use the [Set/Reset PIN](/api#tag/security/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin) API to set your personalized card PIN to provide a Base64 encoded PIN value. If you're within the EU and UK, you *won't* be able to use the [Set/Reset PIN](/api#tag/security/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin) API. Template for Artwork (Image Format only) ### Offline PIN for EU and UK An offline PIN is a method of card verification valid for Europay, MasterCard®, and Visa® (EMV) chip cards in the EU and UK. The PIN is encrypted and stored in the card’s EMV chip. This facilitates the user to make a transaction at a terminal with offline PIN validation capabilities. The key difference between an offline and an online PIN is the method of validation. When a cardholder uses the EMV chip card at a terminal with offline capabilities, the PIN entered is validated against the securely stored PIN in the EMV chip card. This is different from the online PIN method where the validation is performed by the card issuer over the network. In the case of offline PIN verification, the transmission of the PIN from the terminal to the card may be enciphered or in plain text, depending upon the terminal. If the entered PIN matches the stored offline PIN, the verification is successful. Otherwise, the verification fails. ## Get card PIN Use the [Fetch ATM PIN](/api#tag/security/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin) API to retrieve the preset PIN and display the PIN to the cardholder. Customers in the EU and UK receive physical cards with a preset PIN. This means the PIN is already present for first-time or subsequent use. Nium provides the Fetch ATM PIN operation to the client for implementation and the customer can then see the existing PIN from the client’s mobile app or website. The PIN block is encrypted for additional security and needs to be decoded before displaying it to the end customer in the client’s mobile app or website. If the customer intends to change the 4-digit PIN, they can do so at an ATM or terminal with the appropriate capabilities. When a customer updates it at an ATM or point-of-sale terminal, the same information is updated in the EMV chip card. Get Card Pin ## Get a PIN status If the card PIN is entered incorrectly three times, the PIN is blocked, and the card *cannot* be used for any transactions. Nium provides a [Fetch PIN Status](/api#tag/security/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin/status) API to the client for implementation and the customer can see the PIN's status from the client’s mobile app or website. Get Card Pin ## Unblock PIN If the card PIN is entered incorrectly three times, the PIN is blocked, and the card *cannot* be used for any PIN-based transactions. Nium provides the [Unblock PIN](/api#tag/security/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin/unblock) API to unblock a card PIN if it's been blocked from your client’s mobile app or website. This API is allowed only for the APAC region. Get Card Pin ## Fetch ATM PIN Nium's [Fetch ATM PIN](/api#tag/security/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin) API allows you to fetch the base64-encoded ATM PIN for physical cards and virtual-upgrade-to-physical cards. This API does not work for virtual cards. This is allowed only for EU and UK cards. ## Get card data Nium's [Fetch card data encrypted V2](/api#tag/security/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/retrieve) API helps you get the card details in a secure manner and display it in your mobile app or website. The secured details, such as the unmasked card number, CVV, and expiration date, are encrypted with the Pretty Good Privacy (PGP) method according to Payment Card Industry security regulations to maintain your customer’s data safe. To use this API, you have to exchange PGP keys with Nium as the entire API payload is encrypted. Get Card Pin ## Encrypt Fetch Card Data response payload with client PGP key The [Fetch card data encrypted](/api#tag/security/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/retrieve) API combines two existing APIs into one, providing you with a single-use API to get the Card Number, CVV2, and Expiration Date to display on your application and mobile app. This API has also been enhanced to transmit data in PGP-encrypted format. **NOTE:** This API is accessible only where encryption is enabled. #### Request example ```bash curl -X GET "https://gateway.nium.com/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardhashId}/retrieve" \ -H "content-type: application/json" \ -H "x-api-key: 0mZpIhaLVM1qd8IJhCfgjGJDsY7b5pdr00j" \ -H "x-request-id: 123e4567-e89b-12d3-a456-426655440000" \ -H "x-client-name: client1" ``` #### Response example ``` -----BEGIN PGP MESSAGE----- Version: BCPG v1.63 hQIMA/2Wo3RK+l68ARAAp3wKdl4XvKfYXrlJKpsuUAR+CoVB6CZuSHjQE0iRiP+x 6fgDDA8eRc9O0U99LXJQouI/ffNzS/cIy4wya4dpMYa5K9U0KqakqMN0fDGUee6N tab72R2fCfx/lf8FCb8csWwK4ctXaoC0Bt76JwOopBrQ4/jqMTUl0uJ6hVQSoK2N ZOozUrbvqECFAQBR3RTBPFLuAUAxW0noyPqgkmZr+wfPBextutwAPMyJmHUJo3Ts jmzJtbKdD+Xizd1zkn7lUVmBm/911d+ZTfbAXlVzbZZagFw/js1wNuYkxGiniNaC aRfVyke/KvAlK397vizgval44Cibb0yhmSzi0SHWnm9BUjdY/tvH9UBBWPgCPG/Z NZ2JGzJWixbtYbudCfuPeCjtwPltX2tVXQ0ejKEOASMxdh2iCgsX5tpHWocMa544 s9p8aXjQw5iHlSjPAG/8gh2jHmTyJPGZgtRdqqA65786/MzixC1dDfg7E+wOYOVA ZtyAIjE/ejzRyg0gDw4HCYGBQPz1UcSA6FQ+b2pSrO9DGixcnLGasbASWUcUZVPH +LyKj0t5+R6p9xMH4hH1AxzvZQwTl8B8zRtvtZEy1jMD3W0lNT/vdNMXncySfpIu 9nrBl+Oo/p+ZY2in6qMoKjCOY7UPvtWJungi+WOK6p5TAyaq3PrVrETe0KKNr4nS fgH+G6eRbhGfruXkS5WKAOCx8eTdJlfCG1HyP2mn1ge/dKh9KCfnrJRcIS+LqthO pTarSFpN3ZP8NbxKTjksCY5SJnRzc+SY/V7oC6EVYvgNNJryPevSZqcKL33qRufw hE2hwKHlhiK8QwrzBBwyPaOUZRuHEXxQPJqsew12rA== =ODQ2 -----END PGP MESSAGE----- ``` ### Response example: Payload after decryption ```json { "cvv": "715", "expiry": "12/26", "unMaskedCardNumber": "4613200505649498" } ``` ### Use cases | Case | Encryption flag | Card status | Response | Message | | :--- | :-------------- | :--------------------------------------------- | :------- | :--------------------------------------- | | 1 | true | | Success | | | 2 | false | | Failure | client encryption setup is not available | | 3 | | `Active` `Inactive` `T_BLOCK` `Virtual_Active` | Success | | | 4 | | `Expired` `P_Block` | Failure | | --- # PGP Prerequisites URL: https://docs.nium.com/docs/cards/card-security/pgp-prerequisites Some endpoints in Nium's API have prerequisites that your integration needs to comply with before you can use them. These prerequisites are in place for compliance and security purposes. Specifically, the following APIs require a PGP key (a GPG key using RSA encryption) before you can take advantage of them. - [Show Security Details Encrypted](/api#tag/security/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/showSecurityDetails) - [Set/Reset PIN V2](/api#tag/security/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin) - [Fetch ATM PIN V2](/api#tag/security/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin) - [Add Or Update Passcode](/api#tag/3ds/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/3ds/passcode) PGP encryption is 2048 bits and is applied on all client facing endpoints. ## Security Our APIs use the HTTPS protocol and require a PGP key that your integration needs to include in its requests, and you need to share with Nium. When you share the PGP key with us, Nium approves and adds your IP address to our allowlist to make sure Nium is the only communicating party when these requests get used. | API action | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | API request | Your integration provides a public PGP key to Nium.Nium encrypts your API request using the provided public PGP key.Decrypt the API request using your private PGP key. | | API response | Nium provides you with a public PGP key to encrypt your API response.Encrypt your API response using the provided public PGP key.Nium decrypts the API response using our private PGP key. | ## Generate PGP keys To generate a public and private PGP key for the above requests, take the following steps. These steps generate the keys using Git Bash on Windows. See the following table for a complete list of the commands used. Detials Dropdown - >PGP commands | Action | Command | | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Generate a PGP key | `gpg --full-generate-key` | | List PGP secret keys | `gpg --list-secret-keys` | | Export public key | `gpg --output clientfile-public.key --armor --export [example.rha@gmail.com](mailto:example.rha@gmail.com)` | | Export private key | `gpg --output clientfile-secret.key --armor --export-secret-key [example.rha@gmail.com](mailto:example.rha@gmail.com)` | #### Step 1: Use the generate PGP key command Run the `gpg---full-generate-key` command. PGP-1 #### Step 2: Set the key type Use `1` to set the type of the generated public and private key to **RSA**. PGP-2 #### Step 3: Set the key length Set the length of the PGP keys. We recommend setting the length of the keys to `2048` bits. PGP-3 #### Step 4: Set expiration time Set how many days the keys will be valid for. Nium recommends using `0` so the keys don't expire. PGP-4 #### Step 5: Enter key owner details Details requested include: - Name of the key owner - Email address of the key owner - Any additional comments for your future reference PGP-5 #### Step 6: Set a passphrase Set a passphrase for the private PGP key. PGP-6 #### Step 7: List the key List the generated keys using the `gpg --list-secret-keys` command. PGP-7 ## Export PGP keys Once you've generated a pair of PGP keys, take the following steps to export the keys. #### Step 1: Export your public PGP key Run the `$gpg --output company-pgp-public-key.key --armor --export cards.admin@company.com` command to export your public key. Running the command creates a file in your home directory with the title `company-pgp-public-key.key`. PGP Export #### Step 2: Export your private PGP key Run the `$gpg --output company-pgp-private-key.key --armor --export-secret-key cards.admin@company.com` command to begin exporting your private key. When prompted, enter the passphrase you set to export the private key. PGP Export - Private Entering your passphrase creates a file in your home directory with the title `company-pgp-private-key.key`. PGP Export - Passphrase #### Step 3: Contact Nium to import the PGP key Reach out to your Nium account manager or [Nium support](mailto:support@nium.com) with your PGP keys ready to share. Our team will configure the keys in our API with your `client` resource to encrypt and decrypt the relevant requests and responses. --- # Dynamic Authorization URL: https://docs.nium.com/docs/cards/dynamic-authorization The Dynamic Authorization model lets you participate in the card authorization transaction decision-making process. Every time your cardholder swipes the card at a terminal, makes an e-commerce transaction, or withdraws money from an ATM, Nium sends you the authorization request. Nium honors your transaction after you authorize it. Nium captures and settles it based on the scheme or network settlement file. Nium provides you with the settlement file and the platform settles the overall transaction amount. Nium supports three transaction authorization models: - [Hosted Model](#hosted-model) - [Delegated Model](#delegated-model) - [Extended Model](#extended-model) ## Hosted Model The Hosted Model is nearly identical to the Extended Model with regard to Nium maintaining and managing your customer's balance and you being the final decision-maker when it comes to authorizing the transaction. The only difference between the Hosted and Extended models is that for the latter, Nium asks you what you want to do with the funds. With the Hosted Model, Nium makes all the decisions for you and holds all the funds. ## Delegated Model In the Delegated Model, the wallet balance is at your side. You're the final decision-maker when it comes to authorizing your transaction. Nium performs a card verification and a balance check of your float or funding account during the transaction. Upon a positive result, you're involved in the decision-making process by validating the customer balance against the transaction amount and other rules that you might want to apply or check. If your system approves the transaction, Nium debits the float or funding source and responds to the card network. ## Extended Model In the Extended Model, Nium maintains and manages your customer balance while you're the final decision-maker when it comes to authorizing the transaction. Nium performs verification of the card and also validates the customer balance during the transaction. Upon a positive result, you're involved in the decision-making process by participating in the authorization and applying any rules that you might have. If your system approves the transaction, Nium debits the wallet and responds to the card network. > 📒 NOTE > > The Nium One platform also lets you fund in multiple currencies. Nium applies its multicurrency authorization logic during the authorization request. ## Model comparison — check types The table below shows who performs the check types between the three models. | Type of check | Hosted Model | Delegated Model | Extended Model | | :------------------------------- | :----------- | :-------------- | :------------- | | Card CHIP related checks | Nium | Nium | Nium | | Card PIN or CVV2 (if applicable) | Nium | Nium | Nium | | Velocity limits | Nium | Nium | Nium | | Float or funding account check | Nium | Nium | N/A | | Balance check | Nium | You—the client | Nium | | Final authorization decision | Nium | You—the client | You—the client | ## Model comparison — transaction types The table below shows the transaction types that are sent to the client between the three models. | Type of transaction | Hosted Model | Delegated Model | Extended Model | | :------------------------- | :----------- | :-------------- | :------------- | | `DEBIT` | N/A | Yes | Yes | | `REVERSAL` | N/A | Yes | No | | `ORIGINAL_CREDIT` | N/A | Yes | No | | `ORIGINAL_CREDIT_REVERSAL` | N/A | Yes | No | | `REVERSAL_ADVICE` | N/A | Yes | No | > 📒 Note > > Transactions aren't sent to clients who opt for the Hosted Model. > > Account Validation transactions aren't sent to clients who opt for the Extended Model. --- # Prerequisites URL: https://docs.nium.com/docs/cards/dynamic-authorization/prerequisites To take advantage of our Dynamic Authorization model, your system needs to respond to a request from the Nium One platform. To take advantage of our [Dynamic Authorization](/docs/cards/dynamic-authorization) model, your system needs to respond to a request from the Nium One platform. These following prerequisites only apply to the authorization [Delegated Model](/docs/cards/dynamic-authorization/delegated-model)and [Extended Model](/docs/cards/dynamic-authorization/extended-model). ## Integration First reach out to your Nium account manager or [Nium support](mailto:support@nium.com) and provide your URL \[format: `/api1/v1/authorization`]. Nium sends a Delegated Model request payload and receives a response payload with this URL. ## Security The API is in the HTTPS protocol. Allow list Nium's IP address to make sure only Nium is the authorized API sender. Aside from HTTPS, there are encryption keys that you and Nium need to share. | API action | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API request | Your integration provides a public PGP key to Nium.Nium encrypts your API request using the provided public PGP key.Decrypt the API request using your private PGP key. | | API response | Nium provides you with a public PGP key to to encrypt your API response.Encrypt your API response using the provided public PGP key.Nium decrypts the API response using our private PGP key. | ## Generate PGP keys To generate a public and private PGP key for the above requests, take the following steps. These steps generate the keys using Git Bash on Windows. See the following table for a complete list of the commands used. PGP commands | Action | Command | | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Generate a PGP key | `gpg --full-generate-key` | | List PGP secret keys | `gpg --list-secret-keys` | | Export public key | `gpg --output clientfile-public.key --armor --export [example.rha@gmail.com](mailto:example.rha@gmail.com)` | | Export private key | `gpg --output clientfile-secret.key --armor --export-secret-key [example.rha@gmail.com](mailto:example.rha@gmail.com)` | #### Step 1: Use the generate PGP key command Run the `gpg---full-generate-key` command. PGP-1 #### Step 2: Set the key type Use `1` to set the type of the generated public and private key to **RSA**. PGP-2 #### Step 3: Set the key length Set the length of the PGP keys. We recommend setting the length of the keys to `2048` bits. PGP-3 #### Step 4: Set expiration time Set how many days the keys will be valid for. Nium recommends using `0` so the keys don't expire. PGP-4 #### Step 5: Enter key owner details Details requested include: - Name of the key owner - Email address of the key owner - Any additional comments for your future reference PGP-5 #### Step 6: Set a passphrase Set a passphrase for the private PGP key. PGP-6 #### Step 7: List the key List the generated keys using the `gpg --list-secret-keys` command. PGP-7 ## Export PGP keys Once you've generated a pair of PGP keys, take the following steps to export the keys. #### Step 1: Export your public PGP key Run the `$gpg --output company-pgp-public-key.key --armor --export cards.admin@company.com` command to export your public key. Running the command creates a file in your home directory with the title `company-pgp-public-key.key`. PGP Export #### Step 2: Export your private PGP key Run the `$gpg --output company-pgp-private-key.key --armor --export-secret-key cards.admin@company.com` command to begin exporting your private key. When prompted, enter the passphrase you set to export the private key. PGP Export - Private Entering your passphrase creates a file in your home directory with the title `company-pgp-private-key.key`. PGP Export - Passphrase ## Payload Reach out to your Nium account manager or [Nium support](mailto:support@nium.com) with your PGP keys ready to share. Nium sends the authorization request to your integration. The request contains the transaction data and merchant data, so you can authorize or reject the request. --- # Hosted Models URL: https://docs.nium.com/docs/cards/dynamic-authorization/hosted-model The Hosted Model is the default authorization logic on the Nium One platform. This model allows Nium to serve as the primary statement of record holder and authorizing entity for clients and their customers. The model allows Nium to centralize the financial authorization process. This model only applies to card-based transactions. You need to work with your implementation manager to set it up. Hosted Model Process ## Hosted Model flow With the Hosted Model, Nium is the financial license holder, the ledger of balances, or the database of record. Nium holds the funds in segregated client and customer accounts. ### Physical funds flow 1. Nium receives funds from the client or the corporate customer to run the card program. 2. Nium provides virtual account numbers (VANs) to clients and corporate customers which lead to the same Nium bank account. For example, the Nium bank account receives $5,000 from the client or the corporate customer. ### Virtual funds flow 1. The prefund at the client level is used to fund customer wallets. For example, the Nium system client pool account increases in value by $5,000. > 📒 NOTE > > The Nium client system includes the client host and ancillary support systems that the client manages. 1. The corporate and individual customer funds are mapped on the Nium system which is the basis of balance checks during transactions. - For example, the client disburses $2,000 into the individual Y customer wallet - Individual Y can only spend $2,000 as the customer's wallet balance is checked by the Nium system during transactions. Hosted Model Process Flow ## Target segment The target segments for the Hosted Model are companies that don't need custom spending rules, such as: - Payroll platforms - Spend Management platforms --- # Extended Model URL: https://docs.nium.com/docs/cards/dynamic-authorization/extended-model The Extended Model is a customizable authorization logic if you're on the Hosted Model in the Nium One platform. This model requires you to make a decision as an extended step in the authorization decision chain. This model only applies to card-based transactions. By default, this model is turned off and not available. You need to work with your implementation manager to turn it on. ## Extended Model flow As the client, your key tasks are to apply any rules that you may have and provide a decision. Hosted Model Process Flow Nium recommends the Extended Model if you meet the following criteria: - You don't have a financial services license for e-money and you want to participate in the authorization decision. - You don't have the capability to process all types of transactions. ## 1.1 Authorization ### Authorization headers | Headers | Parameters | | ---------------------------- | ------------------------------------ | | Content-Type | application/octet-stream | | x-request-id | Universally Unique Identifier (UUID) | | x-client-name | String | | \[client-customized-headers] | String (static value only) | ### Request body | Fields | Description | Type | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `transactionId` | The transaction ID is a Nium-generated 36-character UUID, which is unique per transaction. | UUID | | `transactionType` | Allowed transaction type:•`DEBIT` | String | | `cardHashId` | A unique card identifier generated during a new card issuance. | UUID | | `processingCode` | The processing code is a 2-character field. Refer to the table below for more details on the processing code.•00 - Purchase transaction•01 - Cash Withdrawal or Cash Disbursement•02 - Debit Adjustment•09 - Purchase with Cashback•10 - Account Funding•11 - Quasi Cash Transaction (Debit)•20 - Merchant Return / Refund•21 - Incoming Credit for Mastercard•22 - Credit Adjustment•26 - Incoming Credit for Visa | String | | `billingAmount` | The amount of funds that the cardholder requests. It needs to be represented in the cardholder billing currency.The amount is 0 in case of an account verification request. | Double | | `transactionAmount` | The amount that the merchant charges the cardholder in the currency as defined in `transactionCurrencyCode`.The amount is 0 in case of an account verification request. | Double | | `billingCurrencyCode` | The billing currency refers to the currency used by the card network and Nium for end-of-day settlements. The format of this field should be a 3-letter code representing the currency. [3-letter ISO-4217 currency code](/docs/getting-started/currency-and-country-codes) | String | | `transactionCurrencyCode` | The transaction currency is the currency being used in the transaction between the cardholder and merchant. The format of this field contains the [3-letter ISO-4217 currency code](/docs/getting-started/currency-and-country-codes). | String | | `authCurrencyCode` | The auth currency code is the currency being used in the transaction between Nium and cardholder wallet account. The format of this field should be a 3-letter code representing the currency - [3-letter ISO-4217 currency code](/docs/getting-started/currency-and-country-codes). | String | | `authAmount` | The auth amount displays the amount charged by Nium to the cardholder wallet account during their purchase, and it is denoted in authCurrencyCode. | Double | | `effectiveAuthAmount` | The effective auth amount refers to the combined total of the "authAmount" and the charges documented under transactionFees. And it is denoted in authCurrencyCode. | Double | | `billingConversionRate` | The rate used by the card network to convert the transaction amount to the cardholder billing amount. | String | | `dateOfTransaction` | The transaction date is shown in the format of MMDDHHMMSS using UTC time. | String | | `localTime` | Reserved for future | String | | `localDate` | Reserved for future | String | | `merchantCategoryCode` | The code that defines the type of business, product, or service offered by a merchant is called the Merchant Category Code (MCC). [MCC List](https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf) | String | | `merchantTerminalId` | A code that identifies a terminal at the card acceptor location (TID). | String | | `merchantTerminalIdCode` | A merchant ID number, also known as a merchant number or MID, is a 15-digit numerical identifier that uniquely identifies a merchant. | String | | `merchantNameLocation` | A name and location of the card acceptor (merchant), including the city name and country codeposition 1-25: card acceptor nameposition 26-38: city nameposition 39-40: country code | String | | `posEntryMode` | This is a 4-digit code that identifies the actual method used at the point of service to enter the cardholder account number and the card expiration date.Position 1-2:•00: Unknown or terminal not used•01: Manual Key Entry•02: Magnetic Stripe•03: Bar code read (VISA only)•05: Chip card read•07: Proximity payment originating using VSDC chip data rules•10: Credential stored on filePosition 3:•0: Unknown•1: terminal can accept and forward online PINs•2: terminal cannot accept and forward online PINs | String | | `posConditionCode` | A code identifying transaction conditions at the point-of-sale or point of service.•00 - Normal transaction•01 - Cardholder not present•02 - Unattended cardholder-activated environment•03 - Merchant suspicious•05 - Cardholder present, card not present•06 - Preauthorized request•08 - Mail/telephone order•51 - Account verification request (AVR)•55 - ICC capable branch ATM•59 - Electronic commerce•90 - Recurring payment | String | | `posEntryCapabilityCode` | This field provides information about the terminal used at the point of service. The type of terminal field values include:•0 - Unspecified•2 - Unattended terminal (customer-operated)•4 - Electronic cash register•7 - Telephone device•8 - MCAS device•9 - Mobile acceptance solution (mPOS)Capability of terminal field values include:•0 - Unspecified•1 - Terminal not used•2 - Magnetic stripe read capability•5 - Integrated circuit card read capability | UUID | | `retrievalReferenceNumber` | A 12-digit number that's used with other data elements as a key to identify and track all messages related to a given customer transaction. | String | | `systemTraceAuditNumber` | A 6-digit number that the message initiator assigns that uniquely identifies a transaction. | String | | `acquiringInstitutionCountryCode` | This field accepts the [3-digit ISO country code](https://www.iso.org/iso-3166-country-codes.html) for the acquiring institution. | String | | `acquiringInstitutionCode` | A code that identifies the financial institution acting as the acquirer of the transaction. | String | | `paymentServiceFields` | This is a private use field. It contains the first data merchant number. | String | | `originalDateOfTransaction` | Original transaction date of the purchase, this is present for correction or reversal transaction. | String | | `originalSystemTraceAuditNumber` | Original System trace Audit Number of the purchase, this is present for correction or reversal transaction. | String | | `originalTransactionId` | Original transaction Id of the purchase, this is present for correction or reversal transaction. | UUID | | `transactionFees` | This field is an array containing a list of fees that need to be applied to a given transaction. The valid names of fees are ATM\_FEE, POS\_FEE, ECOM\_FEE, and TRANSACTION\_MARKUP. | Array | | `transactionFees.name` | The name of the fees or markup. | String | | `transactionFees.value` | The amount of the fees or markup. | Double | | `transactionFees.currencyCode` | This field contains the 2-letter ISO-2 country code for identifying the country prefix to a mobile number. | String | | `billingReplacementAmount` | Deprecated. This field is no longer in use and should be ignored. | Double | | `transactionReplacementAmount` | Deprecated. This field is no longer in use and should be ignored. | Double | ### Request example ```Bash curl -X POST \ 'http://' \ -H 'content-type: application/octet-stream' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: Nium-Collaborative-Service' \ -d '{ "transactionId": "5047d30f-e348-4baa-87c0-d799a63f8965", "transactionType": "DEBIT", "cardHashId": "a5ce460c-2ead-4e25-ad6c-b3a6e9d727ec", "processingCode": "010000", "billingAmount": 1.3, "transactionAmount": 1.12, "billingCurrencyCode": "SGD", "transactionCurrencyCode": "USD", "authCurrencyCode": "USD", "authAmount": 1.12, "effectiveAuthAmount": 1.14, "billingConversionRate": "1.000000000", "dateOfTransaction": "2601233174", "localTime": null, "localDate": null, "merchantCategoryCode": "5834", "merchantTerminalId": "450480", "merchantTerminalIdCode": null, "merchantNameLocation": null, "posEntryMode": "0710", "posConditionCode": "59", "posEntryCapabilityCode": null, "retrievalReferenceNumber": "344154374485", "systemTraceAuditNumber": "374485", "acquiringInstitutionCountryCode": "702", "acquiringInstitutionCode": "489028", "paymentServiceFields": null, "originalTransactionId": null, "originalDateOfTransaction": null, "originalSystemTraceAuditNumber": null, "originalAcquiringInstitutionCode": null, "billingReplacementAmount": 0.0, "transactionReplacementAmount": 0.0, "transactionFees": [ { "name": "TRANSACTION_MARKUP", "value": 0.044, "currencyCode": "SGD" }, { "name": "ECOM_FEE", "value": 0.02, "currencyCode": "USD" } ] }' ``` > 📒 NOTE > > The request example payload above isn't encrypted with a PGP key. In an actual integration, the payload is encrypted with Nium's public PGP key. ### Response body | Fields | Description | Type | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `responseCode` | Choose an appropriate 2-digit response code, from the response code list below, under which the client can process the transaction. | String | | `partnerReferenceNumber` | This is a unique number that the client generates for the given transaction which is used as a reference for it. We recommend clients generate a version 4 UUID. | String | ### Response example ```json { "responseCode": "00", "partnerReferenceNumber": "f2bc2c33-9bd0-4f16-be54-2a13ce9b174e" } ``` > 📒 NOTE > > The client is expected to send an HTTP 200 response status code with all responses. The following response payload isn't encrypted with a PGP key. In an actual integration, the payload is encrypted with Nium's public PGP key. ### Response codes | Response code | Response reason | Notes | | ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 00 | Success | This response code indicates that the authorization is approved. | | 03 | Invalid Merchant | Use this decline reason code if you, as the client, know that this transaction isn't allowed for the cardholder, at this particular merchant, based on the merchant category code. | | 12 | Invalid Transaction | Use this decline reason code if you, as the client, know that this transaction is invalid. | | 46 | Account Closed | Use this decline reason code if you, as the client, know that this account is no longer valid or is closed. | | 51 | Insufficient Funds | Use this decline reason code if you, as the client, know that the cardholder has insufficient funds in their account, wallet, or ledger. | | 57 | Transaction not Permitted | Use this decline reason code if you, as the client, know that this transaction, based on some transaction data elements, isn't allowed for the cardholder. | | 61 | Exceeds Amount based Limits | Use this decline reason code if you, as the client, know that this transaction causes the cardholder to go above any amount-based limits that have been set up. | | 65 | Exceeds Frequency based Limits | Use this decline reason code if you, as the client, know that this transaction causes the cardholder to go above any frequency-based limits such as daily or monthly. | ### 1.2 Timeout Because the card networks require a timely response from Nium, there's a timeout limit on the response from your system. If you don't respond to Nium within **2 seconds**, Nium declines the transaction to the card network. Whenever a timeout occurs, a potential ledger mismatch could arise in your system. For example, consider the following scenario: 1. Nium sends an Extended Model request to your end for an $88 expenditure. 2. After 2 seconds without receiving a response, the platform times out the request. 3. The platform declines the transaction to the card network. 4. A second later, your system finishes processing the authorization and attempts to respond with an authorization for $88. 5. This may become out of sync with the actual state of the transaction and the account balance. For every transaction your system approves, Nium marks the transaction as `_Unsettled_` and Nium provides a response to the scheme. #### Timeout scenario In the event of a timeout during your response to Nium, the following happens: 1. Nium declines the transaction to the scheme or network. 2. Nium credits the funds to the customer's wallet. ## 2. Settlement report This report contains the end-of-day settlement data that Nium and the scheme send. As a client administrator, you can sign into Nium's back office to see or download the report based on the selected date range. You can also set up a daily settlement data static report. You can download it and get it over Secure File Transfer Protocol. The file naming convention is: Client\_Settlement\_Report\_clientHashId\_YYYYMMDD.csv Refer to the [client settlement](/docs/reports/client-reports/client-settlement-report-v2) report for format details. --- # Delegated Models URL: https://docs.nium.com/docs/cards/dynamic-authorization/delegated-model The authorization API for the Dynamic Authorization consists of a request and a response body. Nium sends the request body to the authorization endpoint. The authorization endpoint accepts the request payload in the specification the document provides. The response payload contains fields in which the API responds to Nium for processing. The authorization API for the [Dynamic Authorization](/docs/cards/dynamic-authorization) consists of a request and a response body. Nium sends the request body to the authorization endpoint. The authorization endpoint accepts the request payload in the specification the document provides. The response payload contains fields in which the API responds to Nium for processing. With Delegated Model requests, Nium delays the response to the card network and sends the request to your system for your decision. ## 1. Delegated Model flow As the client, your two key tasks are to apply any rules that you may have and also deduct the customer's balance based on sufficient funds. Hosted Model Process Flow ### 1.1 Authorization #### Authorization headers | Headers | Parameters | | ---------------------------- | ------------------------------------ | | Content-Type | application/octet-stream | | x-request-id | Universally Unique Identifier (UUID) | | x-client-name | String | | \[client-customized-headers] | String (static value only) | #### Request body | Fields | Description | Type | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `transactionId` | The transaction ID is a Nium-generated 36-character UUID, which is unique per transaction. | UUID | | `transactionType` | Allowed transaction type:•`DEBIT` | String | | `cardHashId` | A unique card identifier generated during a new card issuance. | UUID | | `processingCode` | The processing code is a 2-character field. Refer to the table below for more details on the processing code.•00 - Purchase transaction•01 - Cash Withdrawal or Cash Disbursement•02 - Debit Adjustment•09 - Purchase with Cashback•10 - Account Funding•11 - Quasi Cash Transaction (Debit)•20 - Merchant Return / Refund•21 - Incoming Credit for Mastercard•22 - Credit Adjustment•26 - Incoming Credit for Visa | String | | `billingAmount` | The amount of funds that the cardholder requests. It needs to be represented in the cardholder billing currency.The amount is 0 in case of an account verification request. | Double | | `transactionAmount` | The amount that the merchant charges the cardholder in the currency as defined in `transactionCurrencyCode`.The amount is 0 in case of an account verification request. | Double | | `billingCurrencyCode` | The billing currency refers to the currency used by the card network and Nium for end-of-day settlements. The format of this field should be a 3-letter code representing the currency. [3-letter ISO-4217 currency code](/docs/getting-started/currency-and-country-codes) | String | | `transactionCurrencyCode` | The transaction currency is the currency being used in the transaction between the cardholder and merchant. The format of this field contains the [3-letter ISO-4217 currency code](/docs/getting-started/currency-and-country-codes). | String | | `authCurrencyCode` | The auth currency code is the currency being used in the transaction between Nium and cardholder wallet account. The format of this field should be a 3-letter code representing the currency - [3-letter ISO-4217 currency code](/docs/getting-started/currency-and-country-codes). | String | | `authAmount` | The auth amount displays the amount charged by Nium to the cardholder wallet account during their purchase, and it is denoted in authCurrencyCode. | Double | | `effectiveAuthAmount` | The effective auth amount refers to the combined total of the "authAmount" and the charges documented under transactionFees. And it is denoted in authCurrencyCode. | Double | | `billingConversionRate` | The rate used by the card network to convert the transaction amount to the cardholder billing amount. | String | | `dateOfTransaction` | The transaction date is shown in the format of MMDDHHMMSS using UTC time. | String | | `localTime` | Reserved for future | String | | `localDate` | Reserved for future | String | | `merchantCategoryCode` | The code that defines the type of business, product, or service offered by a merchant is called the Merchant Category Code (MCC). [MCC List](https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf) | String | | `merchantTerminalId` | A code that identifies a terminal at the card acceptor location (TID). | String | | `merchantTerminalIdCode` | A merchant ID number, also known as a merchant number or MID, is a 15-digit numerical identifier that uniquely identifies a merchant. | String | | `merchantNameLocation` | A name and location of the card acceptor (merchant), including the city name and country codeposition 1-25: card acceptor nameposition 26-38: city nameposition 39-40: country code | String | | `posEntryMode` | This is a 4-digit code that identifies the actual method used at the point of service to enter the cardholder account number and the card expiration date.Position 1-2:•00: Unknown or terminal not used•01: Manual Key Entry•02: Magnetic Stripe•03: Bar code read (VISA only)•05: Chip card read•07: Proximity payment originating using VSDC chip data rules•10: Credential stored on filePosition 3:•0: Unknown•1: terminal can accept and forward online PINs•2: terminal cannot accept and forward online PINs | String | | `posConditionCode` | A code identifying transaction conditions at the point-of-sale or point of service.•00 - Normal transaction•01 - Cardholder not present•02 - Unattended cardholder-activated environment•03 - Merchant suspicious•05 - Cardholder present, card not present•06 - Preauthorized request•08 - Mail/telephone order•51 - Account verification request (AVR)•55 - ICC capable branch ATM•59 - Electronic commerce•90 - Recurring payment | String | | `posEntryCapabilityCode` | This field provides information about the terminal used at the point of service. The type of terminal field values include:•0 - Unspecified•2 - Unattended terminal (customer-operated)•4 - Electronic cash register•7 - Telephone device•8 - MCAS device•9 - Mobile acceptance solution (mPOS)Capability of terminal field values include:•0 - Unspecified•1 - Terminal not used•2 - Magnetic stripe read capability•5 - Integrated circuit card read capability | UUID | | `retrievalReferenceNumber` | A 12-digit number that's used with other data elements as a key to identify and track all messages related to a given customer transaction. | String | | `systemTraceAuditNumber` | A 6-digit number that the message initiator assigns that uniquely identifies a transaction. | String | | `acquiringInstitutionCountryCode` | This field accepts the [3-digit ISO country code](https://www.iso.org/iso-3166-country-codes.html) for the acquiring institution. | String | | `acquiringInstitutionCode` | A code that identifies the financial institution acting as the acquirer of the transaction. | String | | `paymentServiceFields` | This is a private use field. It contains the first data merchant number. | String | | `originalDateOfTransaction` | Original transaction date of the purchase, this is present for correction or reversal transaction. | String | | `originalSystemTraceAuditNumber` | Original System trace Audit Number of the purchase, this is present for correction or reversal transaction. | String | | `originalTransactionId` | Original transaction Id of the purchase, this is present for correction or reversal transaction. | UUID | | `transactionFees` | This field is an array containing a list of fees that need to be applied to a given transaction. The valid names of fees are ATM\_FEE, POS\_FEE, ECOM\_FEE, and TRANSACTION\_MARKUP. | Array | | `transactionFees.name` | The name of the fees or markup. | String | | `transactionFees.value` | The amount of the fees or markup. | Double | | `transactionFees.currencyCode` | This field contains the 2-letter ISO-2 country code for identifying the country prefix to a mobile number. | String | | `billingReplacementAmount` | Deprecated. This field is no longer in use and should be ignored. | Double | | `transactionReplacementAmount` | Deprecated. This field is no longer in use and should be ignored. | Double | #### Request example ``` curl -X POST \ 'http://' \ -H 'content-type: application/octet-stream' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: Nium-Collaborative-Service' \ -d '{ "transactionId": "5047d30f-e348-4baa-87c0-d799a63f8965", "transactionType": "DEBIT", "cardHashId": "a5ce460c-2ead-4e25-ad6c-b3a6e9d727ec", "processingCode": "010000", "billingAmount": 1.3, "transactionAmount": 1.12, "billingCurrencyCode": "SGD", "transactionCurrencyCode": "USD", "authCurrencyCode": "USD", "authAmount": 1.12, "effectiveAuthAmount": 1.14, "billingConversionRate": "1.000000000", "dateOfTransaction": "2601233174", "localTime": null, "localDate": null, "merchantCategoryCode": "5834", "merchantTerminalId": "450480", "merchantTerminalIdCode": null, "merchantNameLocation": null, "posEntryMode": "0710", "posConditionCode": "59", "posEntryCapabilityCode": null, "retrievalReferenceNumber": "344154374485", "systemTraceAuditNumber": "374485", "acquiringInstitutionCountryCode": "702", "acquiringInstitutionCode": "489028", "paymentServiceFields": null, "originalTransactionId": null, "originalDateOfTransaction": null, "originalSystemTraceAuditNumber": null, "originalAcquiringInstitutionCode": null, "billingReplacementAmount": 0.0, "transactionReplacementAmount": 0.0, "transactionFees": [ { "name": "TRANSACTION_MARKUP", "value": 0.044, "currencyCode": "SGD" }, { "name": "ECOM_FEE", "value": 0.02, "currencyCode": "USD" } ] }' ``` > 📒 NOTE > > The example request payload above isn't encrypted with a PGP key. In an actual integration, the payload is encrypted with Nium's public PGP key. #### Response body | Field | Description | Type | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `responseCode` | Choose an appropriate 2-digit response code, from the response code list below, under which the client can process the transaction. | String | | `partnerReferenceNumber` | This is a unique number that the client generates for the given transaction which is used as a reference for it. We recommend clients generate a version 4 UUID. | String | #### Response example ```json { "responseCode": "00", "partnerReferenceNumber": "f2bc2c33-9bd0-4f16-be54-2a13ce9b174e" } ``` > 📒 NOTE > > The client is expected to send an HTTP 200 response status code with all responses. The following response payload isn't encrypted with a PGP key. In an actual integration, the payload is encrypted with Nium's public PGP key. #### Response codes | Response code | Response reason | Notes | | ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `00` | Success | This response code indicates that the authorization is approved. | | `03` | Invalid Merchant | Use this decline reason code if you, as the client, know that this transaction isn't allowed for the cardholder, at this particular merchant, based on the merchant category code. | | `12` | Invalid Transaction | Use this decline reason code if you, as the client, know that this transaction is invalid. | | `46` | Account Closed | Use this decline reason code if you, as the client, know that this account is no longer valid or is closed. | | `51` | Insufficient Funds | Use this decline reason code if you, as the client, know that the cardholder has insufficient funds in their account, wallet, or ledger. | | `57` | Transaction not Permitted | Use this decline reason code if you, as the client, know that this transaction, based on some transaction data elements, isn't allowed for the cardholder. | | `61` | Exceeds Amount-based Limits | Use this decline reason code if you, as the client, know that this transaction causes the cardholder to go above any amount-based limits that have been set up. | | `65` | Exceeds Frequency-based Limits | Use this decline reason code if you, as the client, know that this transaction causes the cardholder to go above any frequency-based limits such as daily or monthly. | ### 1.2 Timeout Because the card networks require a timely response from Nium, there's a timeout limit on the response from your system. If you don't respond to Nium within **2 seconds**, Nium declines the transaction to the card network. Whenever a timeout occurs, a potential ledger mismatch could arise in your system. For example, consider the following scenario: 1. Nium sends a Delegated Model request to your end for an $88 expenditure. 2. After 2 seconds without receiving a response, the platform times out the request. 3. The platform declines the transaction to the card network. 4. A second later, your system finishes processing the authorization and attempts to respond with an authorization for $88. 5. This may become out of sync with the actual state of the transaction and the account balance. For every transaction your system approves, Nium marks the transaction as `Unsettled` and provides a response to the scheme. #### Timeout scenario In the event of a timeout during your response to Nium, the following happens: 1. Nium declines the transaction to the scheme or network. 2. Nium credits the funds to your `prefund` account. 3. A reversal advice is sent to you with details about the original transaction. 4. You can reverse the transaction in the event the customer's wallet is debited at your end. ## 2. Settlement The payment settlement process is established on a file-based approach. The file is in a fixed-length format. You need to pull the file from the Nium server daily. > 📒 NOTE > > You need to subscribe to the settlement file to use the Delegated Model. ### 2.1 Security The Nium One platform provides a daily settlement file in a shared Secure File Transfer Protocol (SFTP) folder for your settlement purposes. The platform provides the host and path where the file resides. Use SFTP to access the server using your platform-issued username and password. You have read-only access to the path. The file is PGP encrypted using your public key, which you need to use to decrypt it. > 💁 TIP > > This file is encrypted with the same PGP public key that's used to encrypt the authorization payload. The file can then be decrypted using your private key. ### 2.2 File format This report contains the end-of-day settlement data as received between Nium and the scheme. There are two versions of the file format available for the daily client settlement report. Section 2.2.1 contains the latest version and 2.2.2 is the previous version that is deprecated and will eventually become unsupported. As a client administrator, you can sign in to the Nium portal and view or download the settlement report based on the selected date range. You also have the option to have the file delivered to you over Secure File Transfer Protocol (SFTP). #### 2.2.1 Settlement file naming convention: `[ClientHashID]_SETTLEMENT_YYYYMMDDHHmmSS.TXT.pgp` The following characteristics apply to this version of the settlement file - Download file name convention: \[ClientHashID]\_SETTLEMENT\_YYYYMMDDHHmmSS.TXT.pgp - The extracted file naming convention is `[ClientHashId]_SETTLEMENT_YYYYMMDDHHmmSS.TXT` - Fields in the settlement file are separated by a pipe \['|'] delimited - Each settlement file contains three sections:\ a. Header\ b. Detail Record\ c. Trailer - Current PGP encryption will apply, with no change in the logic. - The last 10 columns are added for future use. **Design Abbreviations** | Abbreviation | Description | | | :----------- | :------------ | :- | | AN | Alpha-Numeric | | | A | Alpha only | | | N | Numeric only | | | DT | Date | | **Header Record** | Field Name | Field Type | Field Length | Sample Value | Description | | :------------------ | :--------- | :----------- | :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | | Record Type | AN | 1 | H | Record Type Indicator, H indicates Header record. | | Batch Date | N | 8 | 20210425 | This field indicates the posting date of the file sent to the SFTP. The file contains settlement records of the date with the format: yyyyMMdd. | | Creation Date | N | 14 | 20210426013548 | This field indicates the creation date of the file. It has today's Nium cards processing date-time in UTC with the form: yyyyMMddHHmmss. | | Client Hash Id | AN | 36 | 123e4567-e89b-12d3-a456-426655440000 | This field indicates the client’s unique ID. | | File Identification | AN | 21 | DAILY SETTLEMENT FILE | Fixed value indicating that this is a daily settlement file | **Detailed Record** | Field Name | Field Type | Field Length | Sample Value | Description | | ------------------------------------ | ---------- | ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | Record Type | AN | 1 | D | Record Type Indicator, D indicates Detail record. | | CardHashId | AN | 36 | 3f860722-9f50-4689-9e3b-16c03560b7fc | The unique card hash ID. | | Masked Card Number | AN | 16 | 4111XXXXXXXX1111 | Masked PAN | | Transaction Id | AN | 36 | 28b0de5c-576e-4d34-b747-db37d811fcd1 | The transaction's unique transaction hash ID. | | Partner Transaction Reference Number | AN | 36 | 28b0de5c-576e-4d34-b747-db37d811fcd1 | The transaction reference number provided by the partner. | | Effective Date | N | 8 | 20202004 | The effective date when the settlement is released. | | Batch Date | N | 8 | 20202004 | The batch of the settlement clearance. | | Transaction Sign | A | 1 | D or C | D = Debit or C = Credit | | Transaction Currency | A | 3 | SGD or AUD | 3-character ISO3 currency code. | | Transaction Amount | N | 15,1,4 | AAAAAAAAAAAAAAATDDDD | Transaction amount in format (15,1,4). A indicates the amount, T indicates the dot separating the decimals, D indicates the decimals. | | Local Transaction Currency | A | 3 | SGD or AUD | 3-character ISO3 currency code. | | Local Transaction Amount | N | 15,1,4 | AAAAAAAAAAAAAAATDDDD | Local Transaction amount in format (15,1,4). A indicates the amount, T indicates the dot separating the decimals, D indicates the decimals. | | Billing Currency | A | 3 | SGD or AUD | 3-character ISO3 currency code. | | Billing Amount | N | 15,1,4 | AAAAAAAAAAAAAAATDDDD | Transaction amount in format (15,1,4). A indicates the amount, T indicates the dot separating the decimals, D indicates the decimals. | | Settlement Currency | A | 3 | SGD or AUD | 3-character ISO3 currency code. | | Settlement Amount | N | 15,1,4 | AAAAAAAAAAAAAAATDDDD | Transaction amount in format (15,1,4). A indicates the amount, T indicates the dot separating the decimals, D indicates the decimals. | | Authorization Code | AN | 6 | 557B06 | 6-character approval code for a transaction. | | System Trace Audit Number (STAN) | N | 12 | | This field contains a number assigned by the message initiator (merchant or acquirer) that uniquely identifies a cardholder transaction. | | Retrieval Reference Number (RRN) | N | 12 | | The acquirer usually defines it, but a merchant or an electronic terminal may define it. | | Scheme Transaction Identifier | N | 16 | | This contains a scheme-generated Transaction Identifier (TID) unique for each original authorization and financial request. | | Description | AN | 40 | RETAIL ONLINE | Description of transaction. | | Merchant Id | AN | 12 | | Unique Id of the Merchant where the card was used. | | Merchant Terminal Id | AN | 8 | | Unique Id for the Terminal where the card was used. | | Merchant Name | AN | 25 | | Merchant Name / Card Acceptor Name or Automated Teller Machine (ATM) location | | Merchant City | AN | 13 | | City of the Merchant / Card Acceptor or the Automated Teller Machine (ATM) | | Merchant Country | AN | 2 | | Country of the Merchant / Card Acceptor or the Automated Teller Machine (ATM) | | Merchant Category Code | N | 4 | 6011 | Alpha-numeric code identifying the merchant operating the POS/ATM. | | Acquirer Id | N | 12 | | This code identifies the financial institution acting as the acquirer of this customer transaction. | | Multiple Settlement Indicator | A | 1 | M or F | M - Indicating Multiple; F - Indicating Final | | Interchange Reference | N | 25 | 78600000317792070999001 | Interchange reference on transaction provided by merchant | | Interchange Fee Sign | A | 1 | - or - | - for Positive; - for Negative | | Interchange Fee | N | 9 | | | | Original Interchange Fee Sign | a | 1 | - or - | - for Positive; - for Negative | | Original Interchange Fee | N | 15 | | | | Token Requestor ID | AN | 11 | 40010030273 | ApplePay / GooglePay Token Requester ID | \*\* Trailer Record \*\* | Field Name | Field Type | Field Length | Sample Value | Description | | :----------- | :--------- | :----------- | :----------- | :------------------------------------------------------- | | Record Type | AN | 1 | T | Record Type Indicator, T indicates Trailer record. | | Record Count | N | 9 | 000000002 | This field indicates the total number of detail records. | #### 2.2.2 Settlement file naming convention: `[clientHashId]_MONTX_YYYYMMDDHHmmSS.TXT.pgp` > ⚠️ WARNING > > This file is a deprecated version which will become unsupported in Jun 2024. Refer to section 2.2.1 [Settlement file](#221-settlement-file-naming-convention-clienthashid_settlement_yyyymmddhhmmsstxtpgp) to get the latest version. Each settlement file consists of the following three sections: - Header record - Transaction record - Trailer record > 💁 TIP > > The total length of each settlement record in the file is 500 characters. Usually, the record data ends at 307 and is followed by spaces. #### Header record structure | From | To | Field name | Format length | Example value | Description | Mandatory / Optional | | ---- | --- | ------------------- | ----------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | 1 | 13 | Identifier | Alphanumeric (AN) length is 13 characters (13) AN(13) | 0000000000000 | This field contains all zeros to indicate it as a header record. | M | | 14 | 21 | Batch Date | `yyyyMMdd`(08) | 20210425 | This field indicates the posting date of the file sent to the SFTP. The file contains settlement records of the date with the format: `yyyyMMdd`. | M | | 22 | 35 | Creation Date | `yyyyMMddHHmmss`(14) | 20210426013548 | This field indicates the creation date of the file. It contains today's Nium cards processing date-time in UTC with the format: `yyyyMMddHHmmss`. | M | | 36 | 71 | Client Hash ID | AN(36) | 123e4567-e89b-12d3-a456-426655440000 | This field indicates the client unique ID. | M | | 72 | 91 | File Identification | AN(20) | TRANSACTION EXTRACT | This field indicates the identifier for the file. | M | | 92 | 500 | Filler | AN(409) | | Value = Spaces | O | #### Transaction record structure | From | To | Field name | Format length | Example value | Description | Mandatory / Optional | | ---- | --- | ------------------------------------ | ------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | 1 | 36 | Card Hash ID | AN(36) | 3f860722-9f50-4689-9e3b-16c03560b7fc | The unique card hash ID. | M | | 37 | 72 | Transaction ID | AN(36) | 28b0de5c-576e-4d34-b747-db37d811fcd1 | The transaction's unique transaction hash ID. | O | | 73 | 108 | Partner Transaction Reference Number | AN(36) | 28b0de5c-576e-4d34-b747-db37d811fcd1 | The transaction reference unique hash ID. | O | | 109 | 109 | Record Type | AN(1) | M | | M | | 110 | 117 | Effective Date | 9(8) | 20202004 | The effective date when the settlement is released. | M | | 118 | 125 | Batch Date | 9(8) | 20202004 | The batch of the settlement clearance. | M | | 126 | 126 | Transaction Type | AN(1) | D | Type of transaction: Debit = D; Credit = C | M | | 127 | 131 | Transaction Code | 9(5) | 00101 | 5 digits to refer debit and credit transactions: 00101 – RETAIL SALE; 00102 – SALE REVERSAL; 00103 – CASH ADVANCE; 00104 - CASH RVERSAL | M | | 132 | 151 | Billing Amount | 9(20) | 00000000000000100000 | Billing amount in format (15,4): 15 stands for whole, 4 stands for decimal value, 0 in 16th position stands for "." | M | | 152 | 154 | Billing Currency Code | 9(3) | SGD | 3-digit ISO3 currency code. | M | | 155 | 174 | Transaction Amount | 9(20) | 00000000000000100000 | Transaction amount in format (15,4): 15 stands for whole, 4 stands for decimal value, 0 in 16th position stands for "." | O (space when the transaction amount is the same as the billing amount) | | 175 | 177 | Transaction Currency Code | 9(3) | SGD | 3-digit ISO3 currency code. | O (space when the transaction currency is the same as the billing currency) | | 178 | 183 | Authorization Code | 9(6) | 557006 | 6-digit code for an approved transaction. | O | | 184 | 223 | Description | AN(40) | RETAIL ONLINE | Description of transaction. | O | | 224 | 239 | Card Acceptor ID | AN(16) | CARD ACCEPTOR | Alphanumeric card acceptor ID. | M | | 240 | 262 | Interchange Reference | 9(23) | 78600000317792070999001 | Interchange reference on transaction provided by merchant. | M | | 263 | 277 | Visa Transaction ID | 9(15) | 019164261950302 | Unique ID provided for the transaction by Visa. | M | | 278 | 288 | Token Requestor ID | AN(11) | 40010030273 | ApplePay / GooglePay Token Requester ID | M | | 289 | 307 | Token Number | AN(19) | 4513696691503434 | ApplePay / GooglePay Token Number | M | | 308 | 500 | For Future Purpose | AN(193) | | To add additional fields in future | O | #### Trailer record structure | From | To | Field name | Format length | Example value | Description | M/O | | ---- | --- | ------------- | ------------- | ------------- | ----------------------------------------------------------------- | --- | | 1 | 13 | Identifier | AN(13) | 9999999999999 | This field contains all nines to indicate it as a trailer record. | M | | 14 | 22 | Trailer Count | 9(09) | 000000002 | This field indicates the total number of detail records. | M | | 23 | 500 | Fillers | AN(478) |   | Value = Spaces | O | **Example of a decrypted settlement file with a sample record (*containing header, detail record and trailer*):** ``` 000000000000020230322202303222124557 cdabff2-e588-40db-82dc-9cfb9259c71cTRANSACTION EXTRACT 3874ab0b-cb93-474d-9576-e0ff9cf3de6648f29ad1-c9e8-cdfb-d253-2d1a08b4b6e448f29ad1-c9e8-cdfb-d253-2d1a08b4b6e4M2023032020230322D0010100000000000003408000AUD 2V1U0YHungry Jacks Mermaid WaterAU477388002000607 74773883079000920765851463079402693187 0000000000000000 9999999999999000000001 ``` --- # Digital Wallet Tokenization URL: https://docs.nium.com/docs/cards/digital-wallet-tokenization What is Tokenization? ## What is Tokenization? Usage of tokens in the digital payment world was designed to replacing sensitive data with a non-sensitive digital data equivalent. This tokenization process is a way to protect your cardholder sensitive data by exchange it with secure data, called a token. The sensitive data includes a 16 digit card number, card verification number, and card expiry date which must be exchanged with a digital token that serves as a unique reference to the card. This token will be used by Digital Wallet provides (e.g. Apple Pay, Google Pay) to initiate the authorization request to the card network, and it will be used by the card network to lookup the card information before they send it to the issuer institution. ## Apple Pay You can provision your card information to Apple Pay by taking a picture of your payment card. Apple sends card details to the card network and issuer to do authentication. Upon successful authentication, your Apple device replaces payment card details with a series of randomly generated numbers (or pay tokens) and store this information in a secure location (Secure Element-SE). Other non-sensitive information is visible via the Apple device app - WALLET. ## Google Pay In google pay, tokenization works in a similar flow as apple pay. Google will store this information in a secure location, Host Card Emulation (HCE). ### Step 1: Register a payment card detail in a digital wallet Digital Wallet-1 ### Step 2: How transactions can be done with a digital wallet. As the original PAN of the card is never stored on the end user's mobile device. Payment of transaction will be made by payment token that has been securely stored. Digital Wallet-2 ## Nium Tokenization Nium offers a card tokenization process, enables you to provide cardholders with a secure and convenient way to store and use their payment cards within their mobile and wearable devices. Digital Wallet-3 ## Provisioning Token Nium supports 2 methods for provisioning a token, to exchange a payment card into a token within the digital wallets. ### Direct Provisioning This method allows your customer to enter the card data directly into the digital wallet in their mobile or wearable device. It requires your customer to type in card information or take a photo of a physical card. ### Push Provisioning via your mobile app This method allows seamless provisioning to your customer. It requires you to develop the SDK for various mobile operating systems. You can use Nium iOS and Android SDKs to reduce your development timeline, this will eliminate a need for your mobile application to integrate separately with Google/Apple SDK while integrating with Nium API on the card program. However, you still need to go through UI/UX certification required by Apple/Google. > **NOTE:** > > Apple or Google has their own timeline on the certification process of your mobile app. You need to manage it directly with Apple or Google. --- # Apple Pay - Push Provisioning URL: https://docs.nium.com/docs/cards/digital-wallet-tokenization/apple-pay Learn how to integrate the Nium Push Pay SDK to enable cardholders to add their cards to Apple Wallet directly from your mobile banking app. This step-by-step guide covers iOS setup, SDK installation, and provisioning. NiumPushPay SDK helps Mobile app developers to easily implement an *Add to Apple Wallet* button or *Add to Google Pay* button in mobile banking applications. SDK can enable cardholders to provision their card details from their mobile app to their device's payment wallet in a simple, secure way, eliminating the need to enter their card information manually. The SDK is intended to be embedded into the mobile application(s). The SDK is intended to be embedded into the mobile application(s). Whereas the mobile app provider is in charge of the app's user experience, the SDK allows clients to take advantage of Nium's infrastructure. Set up NiumPushPay SDK so that you can add cards to Apple Wallet. Getting started with the iOS SDK requires the below steps. ### Step 1: Install SDK #### 1.1 Install Dependencies To integrate the Nium Push Provisioning libraries, use CocoaPods to install and configure dependencies. CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries in your projects. CocoaPods is distributed as a ruby gem, and is installed by running the following commands in Terminal: ```shell $sudo gem install cocoapods $pod setup ``` #### 1.2 Create a Podfile Create a Podfile for your CocoaPod to specify them during development. Close Xcode and enter the following commands in Terminal to create the Podfile: ```shell $cd ~/ $pod init $open -a Xcode Podfile ``` This creates a new Podfile and opens it in Xcode. #### 1.3 Update Podfile Replace the entire contents of the new Podfile with the following: ```ruby source 'https://github.com/CocoaPods/Specs.git' source 'https://bitbucket.org/instadevelopers/push-provisioning-pod.git' target '' do use_frameworks! pod 'NiumPayPushProvisioning' end ``` **NOTE:** Replace `` with your own Project name. #### 1.4 Populate the New Pod Save and close the Podfile, and then enter the following command in Terminal: ```shell $cd ~/ $pod install ``` ### Step 2: Configure the SDK into your app Import the above POD into your Controller with the following command: ```swift import NiumPayPushProvisioning ``` To configure SDK in your app, initialize the SDK by using the following method: ```swift initialize(application, clientHashId, customerHashId, walletHashId, apiSecret) ``` **NOTE:** This can be initialized in any part of the app, ideally after having the below details - `clientHashId` - `customerHashId` - `walletHashId` - `apiSecret` ```swift NiumCardsPushProvisioning.initialize(clientHashId: “clientHashId”, customerHashId: “customerHashId”, walletHashId: “walletHashId”, apiSecret: “secret”, env: .production) ``` ### Step 3: Create an *Add to Apple Wallet* Button You can create an *Add to Apple* wallet button by calling the `createButton(buttonStyle: AddPassButtonStyle, superview: UIView)` method. This method requires a superview which will contain this button. This method will return a button and you use this button to create an action for it. ```swift let addToAppleWalletButton = AddPassButton().createButton(.black, superview: buttonContainerView) addToAppleWalletButton.addTarget(self, action: #selector(self.addToWalletAction), for: .touchUpInside) ``` ### Step 4: Provision the Card to the Wallet To provision (add) a card to the wallet, use the method ` addToWallet(viewController: UIViewController, cardHashId: String, completion: (Result\) -> ())` Upon success, the card will be added to the Apple Wallet, and this callback will update whether provisioning was a success or failure. ```swift @objc func addToWalletAction(){ NiumCardsPushProvisioning.shared?.addToWallet(viewController: self, cardHashId: "Made Card Number", completion: { result in switch result { case .success(let message): print("card added") case .failure(let err): print(err.localizedDescription) } }) } ``` ### Step 5: Update single card visibility status Use **getSingleCardProvisionStatus(cardSuffix: String, completion:(Result\) -> ())** method to verify If the card is already provisioned to the Apple Wallet. If yes returns true, then hide the “Add to Apple Wallet” button. ```swift NiumCardsPushProvisioning.shared?.getSingleCardProvisionStatus(cardSuffix: String completion: { result in switch result { case .success(let status): if status { addToAppleWalletButton.isHidden = true } else { addToAppleWalletButton.isHidden = false } case .failure( _): //Handle Failure } }) ``` Note: Step 4 and Step 5 functionally similar, Step 4 is to get the provisioning status of a single card and Step 5 can be used to get the status of multiple cards. ### Step 6: Update multi-card visibility status Using the method **getMultiCardProvisionStatus(CardSuffix:\[String] ,CardListResultListener)** to verify If the list of cards are already provisioned to the Apple Wallet. ```swift NiumCardsPushProvisioning.shared?.getMultiCardProvisionStatus(cardSuffix:[String], completion: { result in switch result { case .success(let arrCardDetail): for cardDetail in arrCardDetail { if cardDetail.status { addToAppleWalletButton.isHidden = true } else { addToAppleWalletButton.isHidden = false } } case .failure( _): //Handle Failure } }) ``` ### Step 7: SSL Pinning (Initialize TrustKit) This step will do SSL Pinning for Domain name Call this method in AppDelegate → didFinishLaunchingWithOptions ```swift do { try NiumCardsPushProvisioning.initialiseTrustKit(domain: "nium.com") } catch let (error) { print(error) } ``` Note: In-App provisioning functionality will not be available for any apps that have not received the entitlement. Follow the below link to complete Entitlement. --- # Apple Pay - Flutter SDK URL: https://docs.nium.com/docs/cards/digital-wallet-tokenization/apple-pay/flutter-sdk Learn how to integrate Apple Pay Push Provisioning into your Flutter app using Nium’s SDK. This guide shows you how to integrate Nium’s Apple Pay Push Provisioning SDK into a Flutter app. You'll set up the project, configure iOS settings, and implement card provisioning using a platform channel. ## Step 1: Create a new Flutter project 1. Open Terminal and run: ```bash flutter create apple_push_provisioning_demo ``` 2. Navigate into the project directory: ```bash cd apple_push_provisioning_demo ``` 3. Open the project in your preferred IDE (such as VS Code or Android Studio). ## Step 2: Configure iOS settings Set up the iOS configuration by updating the Podfile. 1. Navigate to the `ios` directory: ```bash cd ios ``` 2. If a `Podfile` doesn’t exist, create one: ```bash pod init ``` 3. Open the `Podfile` and add: ```ruby target 'Runner' do use_frameworks! # CocoaPods source repositories source 'https://github.com/CocoaPods/Specs.git' source 'https://bitbucket.org/instadevelopers/push-provisioning-pod.git' # Apple Push Provisioning SDK pod 'NiumPayPushProvisioning' pod 'TrustKit' end ``` 4. Save and install dependencies: ```bash pod install ``` ## Step 3: Add card provisioning Use a platform channel to connect your Flutter app with native iOS code and call the SDK. ### Set up Flutter method channel Update `lib/main.dart`: ```dart import 'package:flutter/material.dart'; import 'package:flutter/services.dart'; void main() => runApp(MyApp()); class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( home: HomePage(), ); } } class HomePage extends StatefulWidget { @override _HomePageState createState() => _HomePageState(); } class _HomePageState extends State { static const MethodChannel _channel = MethodChannel('push_provisioning'); Future provisionCard(Map parameters) async { try { final result = await _channel.invokeMethod('provisionCard', parameters); debugPrint('Card provisioned: $result'); } on PlatformException catch (e) { debugPrint('Failed to provision card: ${e.message}'); } } @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: Text('Apple Push Provisioning SDK')), body: Center( child: ElevatedButton( onPressed: () => provisionCard({ 'cardId': 'CardId', 'additionalParam': 'value', }), child: Text('Provision Card'), ), ), ); } } ``` ### Implement the iOS method handler Update `ios/Runner/AppDelegate.swift`: ```swift import UIKit import Flutter import NiumPayPushProvisioning import TrustKit @UIApplicationMain @objc class AppDelegate: FlutterAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { GeneratedPluginRegistrant.register(with: self) // TrustKit Configuration let trustKitConfig: [String: Any] = [ kTSKSwizzleNetworkDelegates: false, kTSKPinnedDomains: [ "nium.com": [ kTSKEnforcePinning: true, kTSKIncludeSubdomains: true, kTSKPublicKeyHashes: ["yourHashValue"], kTSKReportUris: [""] ] ] ] TrustKit.initSharedInstance(withConfiguration: trustKitConfig) do { try NiumCardsPushProvisioning.initialize( clientHashId: "clientHashId", customerHashId: "customerHashId", walletHashId: "walletHashId", apiSecret: "apiSecret", env: .production ) print("NiumCardsPushProvisioning SDK initialized successfully") } catch { print("Error initializing SDK: \(error)") } let controller = window?.rootViewController as! FlutterViewController let channel = FlutterMethodChannel(name: "push_provisioning", binaryMessenger: controller.binaryMessenger) channel.setMethodCallHandler { (call: FlutterMethodCall, result: @escaping FlutterResult) in if call.method == "provisionCard" { guard let args = call.arguments as? [String: Any], let cardId = args["cardId"] as? String else { result(FlutterError(code: "INVALID_ARGUMENT", message: "Card ID is required", details: nil)) return } let sdk = NiumCardsPushProvisioning.shared sdk?.addToWallet(viewController: controller, cardHashId: cardId) { sdkResult in switch sdkResult { case .success(let message): print("Success: \(message)") case .failure(let error): print("Error: \(error)") } } } } return super.application(application, didFinishLaunchingWithOptions: launchOptions) } } ``` ## Step 4: Build and test 1. Run your app on an iOS device: ```bash flutter run ``` 2. In the app, tap **Provision Card** to start the provisioning flow. If successful, the card is added to the Apple Wallet. ## Troubleshooting ### Authentication errors with Bitbucket If you encounter access errors when pulling the SDK from Bitbucket, use a Bitbucket username and [App Password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/). Use this format in your `Podfile`: ```bash source 'https://:@bitbucket.org/instadevelopers/push-provisioning-pod.git' ``` ### CocoaPods issues Clear the CocoaPods cache if you face dependency problems: ```bash rm -rf ~/.cocoapods/repos/bitbucket-instadevelopers-push-provisioning-pod pod cache clean --all pod repo update pod install ``` If you continue to run into any issues, please contact your Nium account manager or . --- # Google Pay Push Provisioning URL: https://docs.nium.com/docs/cards/digital-wallet-tokenization/google-pay Learn how to use the Nium Push Pay SDK to enable cardholders to add cards to Google Pay directly from your mobile banking app. # Google Pay - Push Provisioning NiumPushPay SDK helps Mobile app developers to easily implement *Add to Apple Wallet* button or *Add to Google Pay* button in mobile banking applications. SDK can enable cardholders to provision their card details from their mobile app to their device's payment wallet in a simple, secure way, eliminating the need to enter their card information manually. The SDK is intended to be embedded into the mobile application(s). The SDK is intended to be embedded into the mobile application(s). Whereas the mobile app provider is in charge of the app's user experience, the SDK allows clients to take advantage of Nium's infrastructure. Set up NiumPushPay SDK so that you can add cards to *Google Pay*. Getting started with the Android SDK requires the below steps. ### Step 1 : Download the SDK and adding to libs folder To integrate the Nium Push Provisioning libraries, you need to perform a few basic tasks to prepare your Android Studio project. - Add the `NiumPushPay_SDK.aar` to the `app/libs` directory - Add the `play-services-tapandpay-17.0.1.aar` to the `app/libs` directory. Add flatDir in the root build.gradle file. ```swift allprojects { repositories { flatDir { dirs 'libs' } } } ``` And Add the dependency in the app level build.gradle as below ```swift implementation(name:'NiumPushPaySDK', ext:'aar') implementation(name:'play-services-tapandpay-17.0.1', ext:'aar') ``` **NOTE:** The Android SDK is compatible with apps supporting Android API level 21 and above. Apps can be written using Kotlin or Java 8, but must use AndroidX. ### Step 2 : Configure the SDK into your app To configure SDK in your app, initialize the SDK by using the `initialize(application,clientHashId,customerHashId,walletHashId,apiSecret)` method. Use `getInstance()` method to get the object of NiumPushPay SDK. **NOTE:** This can be initialized any part of the app, ideally after having the below details - `clientHashId` - `customerHashId` - `walletHashId` - `apiSecret` Also, override the `onActivityResult` method in your app and call the NiumPushPay SDK `onActivityResult()` method in the same activity where you initialize it. ```kotlin override fun onActivityResult(requestCode: Int,resultCode: Int, data: Intent?) { NiumPushPay.getInstance().onActivityResult(requestCode, resultCode, data) } ``` ### Step 3 : Verify if card added to wallet (Single card) Use `checkIfCardIsAddedToWallet (cardHashId, CardResultListener)` method. This method is used to check whether provisioned tokens(Added to google pay wallet or not) are present or not and if present then it is in active state or not. If yes returns true so that client can enable the integrate to wallet option for that particular card. ```kotlin NiumPushPay.getInstance().checkIfCardIsAddedToWallet(CARD_HASH_ID, object : CardResultListener { override fun onCardStatusSuccess(isCardAddedToWallet: Boolean) { Toast.makeText(context,"Success $isCardAddedToWallet", Toast.LENGTH_SHORT).show() } override fun onCardStatusFailure(errorEntity: ErrorEntity) { Toast.makeText(context, errorEntity.errMsg, Toast.LENGTH_SHORT).show() } }) ``` ### Step 4 : Verify if cards added to wallet (All cards) Use `getCards(CardListResultListener)` method. This method is used to check whether provisioned tokens are present or not; and if present, then sets the status to `True`. And at the end, send a list of cards with their status (whether card is provisioned or not). This is to check provision status for all available cards. ```kotlin NiumPushPay.getInstance().getCards(object : CardListResultListener { override fun onCardStatusSuccess(cardResultEntity: List) { Toast.makeText(context,"Success",Toast.LENGTH_SHORT).show() } override fun onCardStatusFailure(errorEntity: ErrorEntity) { Toast.makeText(context, errorEntity.errMsg, Toast.LENGTH_SHORT).show() } }) ``` ### Step 5 : Adding the card to the wallet (Provisioning) Use `addToWallet(PushProvisioingListener)` method. This method is used to add cards to the wallet. After the card is successfully added to the card, the wallet application can get provisioned tokens. This callback will update whether provisioning is success or failure. ```kotlin NiumPushPay.getInstance().addToWallet(cardHashId, object :PushProvisioningListener { override fun onPushProvisioningSuccess(tokenId: String,cardHashId: String) { Toast.makeText(context,"Success",Toast.LENGTH_SHORT).show() } override fun onPushProvisioningFailure(errorEntity: ErrorEntity) { Toast.makeText(context, errorEntity.errMsg, Toast.LENGTH_SHORT).show() } }) ``` --- # Google Pay - Flutter SDK URL: https://docs.nium.com/docs/cards/digital-wallet-tokenization/google-pay/flutter-sdk Learn how to integrate Google Pay Push Provisioning into your Flutter app using Nium’s SDK. This guide covers Android setup, SDK configuration, and platform channel integration. # Google Pay – Flutter SDK Learn how to integrate Google Pay Push Provisioning into your Flutter app using Nium’s SDK. This guide walks through project setup, Android configuration, SDK integration, and troubleshooting. ## Step 1: Create a Flutter project 1. Open your terminal and run: ```bash flutter create google_push_provisioning_demo ``` 2. Navigate into the project directory: ```bash cd google_push_provisioning_demo ``` 3. Open the project in your preferred IDE (such as VS Code or Android Studio). ## Step 2: Add the SDK to your Android project 1. Create a `libs` folder (if it doesn't already exist): ```bash cd android/app mkdir libs ``` 2. Move the SDK `.aar` files into the `libs` folder: ```bash mv ./NiumPushPay_SDK.aar ./your/path/google_push_provisioning_demo/android/app/libs ``` 3. Move p`lay-services-tapandpay-17.0.1.aar` to `/app/libs` directory: ```bash mv ./play-services-tapandpay-17.0.1.aar ~/google_push_provisioning_demo/android/app/libs ``` 4. Update the `/build.gradle.kts` configuration at the root of the project. ```kotlin allprojects { repositories { flatDir { dirs("libs") } } } ``` 4. Add the dependencies in `android/app/build.gradle.kts`: ```kotlin dependencies { implementation(name:'NiumPushPaySDK', ext:'aar'); implementation(name:'play-services-tapandpay-17.0.1', ext:'aar'); } ``` ## Step 3: Add card provisioning logic You’ll need to implement a method channel in your Flutter app and handle the corresponding logic in native Android code. ### Flutter method channel Update `lib/main.dart`: ```dart import 'package:flutter/material.dart'; import 'package:flutter/services.dart'; void main() => runApp(MyApp()); class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( home: HomePage(), ); } } class HomePage extends StatefulWidget { @override _HomePageState createState() => _HomePageState(); } class _HomePageState extends State { static const MethodChannel _channel = MethodChannel('push_provisioning'); Future provisionCard(Map parameters) async { try { final result = await _channel.invokeMethod('provisionCard', parameters); print('Card provisioned: $result'); } on PlatformException catch (e) { print('Failed to provision card: ${e.message}'); } } @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: Text('Google Push Provisioning SDK')), body: Center( child: ElevatedButton( onPressed: () => provisionCard({ 'cardId': 'CardId', 'additionalParam': 'value', }), child: Text('Provision Card'), ), ), ); } } ``` ### Android platform code Update `MainActivity.kt`: ```kotlin package com.example.google_push_provisioning_demo import androidx.annotation.NonNull import io.flutter.embedding.android.FlutterActivity import io.flutter.embedding.engine.FlutterEngine import io.flutter.plugin.common.MethodChannel import android.content.Intent import android.util.Log import com.nium.pushpay.sdk.NiumPushPay import com.nium.pushpay.sdk.listeners.CardListResultListener import com.nium.pushpay.sdk.listeners.CardResultListener import com.nium.pushpay.sdk.listeners.PushProvisioningListener import com.nium.pushpay.sdk.models.CardResultEntity import com.nium.pushpay.sdk.models.ErrorEntity class MainActivity : FlutterActivity() { private val CHANNEL = "push_provisioning" override fun configureFlutterEngine(@NonNull flutterEngine: FlutterEngine) { super.configureFlutterEngine(flutterEngine) // Initialize SDK NiumPushPay.initialize( application, "clientHashId", "customerHashId", "walletHashId", "apiSecret" ) MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler { call, result -> when (call.method) { "provisionCard" -> { val args = call.arguments as? Map<*, *> val cardId = args?.get("cardId") as? String if (cardId == null) { result.error("INVALID_ARGUMENT", "Card ID is required", null) return@setMethodCallHandler } // Adding the card to the wallet NiumPushPay.getInstance().addToWallet(cardId, object : PushProvisioningListener { override fun onPushProvisioningSuccess(tokenId: String, cardHashId: String) { runOnUiThread { result.success(mapOf( "success" to true, "tokenId" to tokenId, "cardHashId" to cardHashId )) } } override fun onPushProvisioningFailure(errorEntity: ErrorEntity) { runOnUiThread { result.error("PROVISION_FAILED", errorEntity.errMsg, null) } } }) } "checkCardStatus" -> { val args = call.arguments as? Map<*, *> val cardId = args?.get("cardId") as? String if (cardId == null) { result.error("INVALID_ARGUMENT", "Card ID is required", null) return@setMethodCallHandler } // Verify if card added to wallet (Single card) NiumPushPay.getInstance().checkIfCardIsAddedToWallet(cardId, object : CardResultListener { override fun onCardStatusSuccess(isCardAddedToWallet: Boolean) { runOnUiThread { result.success(mapOf("isCardAddedToWallet" to isCardAddedToWallet)) } } override fun onCardStatusFailure(errorEntity: ErrorEntity) { runOnUiThread { result.error("STATUS_CHECK_FAILED", errorEntity.errMsg, null) } } }) } "getAllCards" -> { // Verify if cards added to wallet (All cards) NiumPushPay.getInstance().getCards(object : CardListResultListener { override fun onCardStatusSuccess(cardResultEntity: List) { val cardsList = cardResultEntity.map { card -> mapOf( "cardHashId" to card.cardHashId, "isAddedToWallet" to card.isAddedToWallet ) } runOnUiThread { result.success(mapOf("cards" to cardsList)) } } override fun onCardStatusFailure(errorEntity: ErrorEntity) { runOnUiThread { result.error("GET_CARDS_FAILED", errorEntity.errMsg, null) } } }) } else -> { result.notImplemented() } } } } // Override onActivityResult as required by documentation override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) NiumPushPay.getInstance().onActivityResult(requestCode, resultCode, data) } } ``` ## Step 4: Build and test 1. Run the Flutter app: ```bash flutter run ``` 2. In the app, tap **Provision Card**. If successful, the card will be added to Google Wallet. ## Troubleshooting ### Bitbucket authentication If you're pulling private SDKs from Bitbucket, use your username and an [App Password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/). Example: ```bash source 'https://:@bitbucket.org/instadevelopers/push-provisioning-pod.git' ``` If you continue to run into issues, please contact your Nium account manager or [Nium support](mailto:support@nium.com) for additional assistance. --- # 3DS Security URL: https://docs.nium.com/docs/cards/3ds-security The Three-Domain Secure (3DS) security protocol, created and branded by Visa and Mastercard as Visa Secure and Mastercard SecureCode, respectively, further protects online payments by enabling cardholders to authenticate their purchases. ### 3DS authentication 3DS adds a layer of security, prior to authorization, to help authenticate online transactions by requiring customers to complete an additional verification with the card issuer. For example, when the merchant initiates 3DS at checkout, the cardholder needs to enter a one-time passcode received via email or Short Message Service (SMS) text to continue with their purchase. The one-time password (OTP) is a six-digit number. ### 3DS setup options supported by Nium Nium supports the following forms of 3DS authentication setups: | Options | Description | | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OTP | The OTP mode of authentication is used to verify users before completing a transaction or running a session in an app or website. | | OTP plus knowledge-based authentication (KBA) | The OTP plus KBA mode of authentication is a two-factor authentication that combines one-time passwords and KBA for enhanced online card transaction security. | | Out-of-band (OOB) authentication | The OOB mode of authentication is used for secure online card transactions using alternative communication channels. For example, a push notification with Approve or Decline. | | OOB with fallback (OTP) | The OOB with fallback OTP authentication mode is used with the provision of one-time passwords in the event of a response timeout for secure online card transactions. | | OOB with fallback (OTP and KBA) | The OOB authentication with fallback OTP and KBA mode is used with the provision of one-time passwords and KBA in the event of a response timeout for secure online card transactions. | The OOB with fallback (OTP and KBA) and OTP plus KBA option are relevant in the European Economic Area (EEA) and the UK due to the Payment Service Directive (PSD2) Strong Customer Authentication (SCA) regulation which mandates the application of two of three factors of authentication. In an OOB authentication, the channel that's used to authenticate a transaction is separate from the channel used by the cardholder to sign in or perform a transaction. OOB authentication is a type of two-factor authentication, such as Face ID, Touch ID, or something you have which is your mobile device, rather than multifactor authentication (MFA). If the primary method of authentication is OOB, then it's required to have a fallback mechanism. If the cardholder doesn't have mobile data or Wi-Fi service to receive push notifications or is unable to authenticate themselves via the mobile app or biometrics, the system moves to the fallback option. Depending on the region you're in, you can decide to go with either of these options: | Region | Option 1 | Option 2 | | :---------------------------------------- | :------------------------------------------------- | :----------- | | Asia-Pacific (APAC) | OOB authentication with OTP as a fallback | OTP only | | European Union and United Kingdom (EU/UK) | OOB authentication with OTP plus KBA as a fallback | OTP plus KBA | For 3DS configuration, you can let Nium manage it entirely for you or you can choose to be consulted on every transaction on the type of authentication to be made. If you're in the EU and UK, you can further choose to let Nium manage and validate the KBA on your behalf or you can manage and validate it. 3DS Authentication The table below details the above diagram's flow which explains the level of API integration needed for each type of authentication and the entity that performs it. | Scenario | Managed by | API integration | Implement API | | ---------------------------- | :---------- | --------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Consult on every transaction | Nium | No | - | | Consult on every transaction | You | Yes | [Check Authentication Method V2](/docs/cards/3ds-security/check-authentication) | | OTP authentication | Always Nium | Not applicable | - | | OTP plus KBA authentication | Nium | Yes | [Add or Update Passcode](/api#tag/3ds/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/3ds/passcode)[3DS Passcode Enrollment Status](/api#tag/3ds/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/3ds/passcode/status) | | OTP plus KBA authentication | You | Yes | [Passcode Validation V2](/docs/cards/3ds-security/passcode-validation) | | OOB authentication | Always you | Yes | [Initiate OOB Authentication V2](/docs/cards/3ds-security/initiate-oob) [OOB Authentication Callback](/docs/cards/3ds-security/oob-callback) | ### Implementation details You need to implement and provide Nium with a URL if you opt for: Being consulted on every transaction or Choose to enable the OTP plus KBA flow and manage the validation or Choose to enable the OOB authentication --- # One-Time Password URL: https://docs.nium.com/docs/cards/3ds-security/one-time-password In the payments ecosystem, authorization occurs after the completion of 3D Secure (3DS) authentication. The merchant uses the authentication data captured as part of the 3DS process to submit an authorization for approval. The following diagram captures the high-level interaction that takes place among key parties when a cardholder uses their card online, for example, to do shopping at an e-commerce merchant. Once the authentication is successful, the merchant end—acquirer, acquiring processor, payment service provider payment gateway—receives the Cardholder Authentication Verification Value (CAVV) or Universal Cardholder Authentication Field (UCAF) authentication result. It's expected that the merchant end includes the authentication result when submitting the transaction authorization to the network as authentication proof. 3DS Authentication When a cardholder attempts to make an online payment to a merchant supporting 3DS authentication, the following process occurs: 1. The cardholder performs an online transaction such as shopping at an e-commerce site, for instance. 2. The merchant initiates an authentication request by sending the request to the card network such as Visa, Mastercard, etc. 3. The card network routes the authentication request to the Nium platform. 4. The Nium platform prompts the cardholder, via the merchant’s checkout experience, to enter a one-time passcode that Nium sends via SMS and email. 5. The Nium platform verifies the one-time password (OTP) and completes the authentication. 6. The Nium platform sends the authentication result to the network and the merchant. --- # OTP and Knowledge URL: https://docs.nium.com/docs/cards/3ds-security/otp-and-knowledge The one-time password (OTP) and knowledge-based authentication (KBA) flow is a security mechanism used to authenticate a user during online transactions. It combines the use of an OTP and KBA to verify the identity of the user and authorize a transaction. The flow is designed to meet the requirements of the European Payment Services Directive (PSD2) and Strong Customer Authentication (SCA) for certain online transactions to enhance security and protect customers' financial information. PSD2 SCA regulation mandates the authentication process to involve two out of three factors of authentication: 1. What you have—possession factor 2. What you know—knowledge factor 3. Who you are—inherence factor The OTP plus KBA fulfills the mandate as follows: - An OTP delivered to the cardholder's mobile, and email address can be considered a valid possession factor. - The six-digit knowledge factor, which the cardholder needs to have securely created and stored in their profile, can be considered a valid knowledge factor. The Short Message Service (SMS) OTP plus the KBA option is relevant in the European Economic Area (EEA) and the United Kingdom (UK) due to the PSD2 SCA regulation. ## Six-digit knowledge factor If you're within the EEA and UK region and are interested in card issuance you need to collect and store a six-digit code—knowledge factor—from the account holders. You can collect this six-digit code at an appropriate stage in the customer lifecycle. You can indicate to the account holders when they need to use this code, for example, when they're doing an online transaction and they need to remember to use the code. ### Six-digit code KBA storage | Stored By | Use case | Relevant API | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You | You're expected to code to the Passcode Validation V2 API so you can validate the six-digit code and provide the results to Nium. Refer to the flows below to understand how it works. | [Passcode Validation V2](/docs/cards/3ds-security/passcode-validation) | | Nium | You're expected to code to the 3DS Passcode Enrollment Status API and the Add Or Update Passcode API to provide Nium with the passcode after you collect it from the cardholder. | [3DS Passcode Enrollment Status](/api#tag/3ds/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/3ds/passcode/status)[Add Or Update Passcode](/api#tag/3ds/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/3ds/passcode) | ### One-leg out If the issuer and acquirer *are not* within the EEA and the UK, then Nium may apply a one-leg out (OLO)-driven SCA exemption. When that happens, the 3DS authentication can be performed only by using the standard OTP-based authentication to provide a simplified user experience. ## OTP plus KBA The following diagrams capture the high-level interaction among key parties when a cardholder uses their card online to do shopping at an e-commerce merchant. Once the authentication is successful, the merchant end—acquirer, acquiring processor, payment service provider payment gateway—receives the Cardholder Authentication Verification Value (CAVV) or Universal Cardholder Authentication Field (UCAF) authentication result. It's expected that the merchant end includes the authentication result when submitting the transaction authorization to the network as authentication proof. ### Scenario 1: Nium manages the 3DS authentication and KBA validation. In this use case, Nium doesn't have to consult you on every transaction since Nium manages the 3DS Authentication and the KBA validation. Nium makes this decision based on the 3DS configuration: - \*\*Consult you on every transaction — \*\*Yes/**No.** - \*\*KBA validated by — Nium/\*\*You > 💁 TIP > > You *are not* expected to implement any API in this scenario. OTP Nium Flow #### Transaction flow 1. The cardholder performs an online transaction such as shopping at an e-commerce site. 2. The merchant initiates an authentication request by sending the request to the card network such as Visa, Mastercard, etc. 3. The card network routes the authentication request to Nium. 4. Nium prompts the cardholder, via the merchant’s checkout experience, to enter a one-time passcode that Nium sends via SMS text and email. 5. Nium verifies the OTP and determines that the cardholder needs to be further challenged for KBA. 6. Nium prompts the cardholder to enter the six-digit passcode. 7. The cardholder enters the six-digit passcode. 8. Nium validates the passcode and sends the results to the network and the merchant. ### Scenario 2: You manage the 3DS authentication and Nium handles the KBA validation. In this use case, Nium consults you on every transaction, however, Nium manages the KBA validation. Refer to the [3DS Overview](/docs/cards/3ds-security) guide for more information. Nium makes this decision based on the 3DS configuration: - \*\*Consult you on every transaction — Yes/\*\*No. - \*\*KBA validated by — Nium/\*\*You OTP Nium Flow-2 > 💁 TIP > > In this use case you need to implement only the Check Authentication Method V2 API. #### Transaction flow 1. The cardholder performs an online transaction such as shopping at an e-commerce site. 2. The merchant initiates an authentication request by sending the request to the card network such as Visa, Mastercard, etc. 3. The card network routes the authentication request to Nium. 4. Nium consults your system via the Check Authentication Method V2 API, which you need to implement, following the API contract mandated by Nium. 5. Nium prompts the cardholder, via the merchant’s checkout experience, to enter a one-time passcode that Nium sends via SMS text and email. 6. Nium verifies the OTP and determines that the cardholder needs to be further challenged for KBA. 7. Nium prompts the cardholder to enter the six-digit passcode. 8. The cardholder enters the six-digit passcode. 9. Nium validates the passcode and sends the results to the network and the merchant. ### Scenario 3: Nium manages the 3DS authentication and you manage the KBA validation. In this use case, Nium doesn't have to consult you on every transaction since Nium manages the 3DS authentication. Nium makes this decision based on the 3DS configuration: - \*\*Consult you on every transaction — \*\*Yes/**No.** - \*\*KBA validated by — \*\*Nium/**You** OTP Nium Flow-3 #### Transaction flow When a cardholder attempts to make an online payment to a merchant supporting 3DS authentication, the following process occurs: 1. The cardholder performs an online transaction such as shopping at an e-commerce site. 2. The merchant initiates an authentication request by sending the request to the card network such as Visa, Mastercard, etc. 3. The card network routes the authentication request to Nium. 4. Nium prompts the cardholder, via the merchant’s checkout experience, to enter a one-time passcode that Nium sends via SMS text and email. 5. Nium verifies the OTP and determines that the cardholder needs to be further challenged for KBA. 6. Nium prompts the cardholder to enter the six-digit passcode. 7. The cardholder enters the six-digit passcode. 8. Nium engages your system via the Passcode Validate API V2, which you need to implement, following the API contract mandated by Nium, to verify the six-digit passcode. 9. Your system performs the validation and returns its result. 10. Nium verifies the result and sends it to the network and the merchant. ### Scenario 4: You manage both the 3DS authentication and KBA validation. In this use case, Nium consults you on every transaction. Refer to the [3DS Overview](/docs/cards/3ds-security) guide for more information. Nium makes this decision based on the 3DS configuration: - \*\*Consult you on every transaction — Yes/\*\*No. - \*\*KBA validated by — \*\*Nium/**You** OTP Nium Flow-4 #### Transaction flow When a cardholder attempts to make an online payment to a merchant supporting 3DS authentication, the following process occurs: 1. The cardholder performs an online transaction such as shopping at an e-commerce site. 2. The merchant initiates an authentication request by sending the request to the card network such as Visa, Mastercard, etc. 3. The card network routes the authentication request to Nium. 4. Nium consults your system via the Check Authentication Method V2 API, which you need to implement, following the API contract mandated by Nium. 5. Nium prompts the cardholder, via the merchant’s checkout experience, to enter a one-time passcode that Nium sends via SMS text and email. 6. Nium verifies the OTP and determines that the cardholder needs to be further challenged for KBA. 7. Nium prompts the cardholder to enter the six-digit passcode. 8. The cardholder enters the six-digit passcode. 9. Nium engages your system via the Passcode Validate API V2, which you need to implement, following the API contract mandated by Nium, to verify the six-digit passcode. 10. Your system performs the validation and returns its result. 11. Nium verifies the result and sends it to the network and the merchant. --- # OOB Authentication URL: https://docs.nium.com/docs/cards/3ds-security/oob-authentication The out-of-band (OOB) authentication flow in 3D Secure (3DS) transactions is a mechanism that authenticates a cardholder using an external channel or device separate from the primary transaction channel. In this flow, instead of relying solely on the traditional browser-based authentication, an additional verification step is introduced through an OOB communication channel. This can include methods such as a dedicated mobile application. The purpose of the OOB authentication flow is to enhance the security of online transactions by providing an extra layer of verification, ensuring that the person initiating the transaction is a legitimate cardholder. > 💁 TIP > > The OOB authentication method is available in all geographic regions. The OOB authentication fulfills the mandate as follows: - The mobile app is bound to the device through a secure onboarding process, which can be considered a possession factor. - The biometrics which is typically a fingerprint or face can be considered an inherence factor. ## OOB authentication factor Nium expects its clients interested in card issuance to have a secure onboarding process to bind their mobile app to their cardholder's device—possession factor. Once it's securely bound, the mobile app prompts the cardholder to complete the authentication through biometrics which typically is a fingerprint. ### OOB applicability At Nium, we support the following forms of OOB authentication: | Options | Region | Description | | :------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OOB with fallback (OTP) | APAC | The OOB with fallback one-time-password (OTP) authentication mode is used with the provision of OTPs in the event of a response timeout for secure online card transactions. | | OOB with fallback (OTP and KBA) | EU/UK | The OOB authentication with fallback OTP and KBA mode is used with the provision of OTPs and KBA in the event of a response timeout for secure online card transactions. | OOB flows require participation from you, the owner of the program interacting with the cardholders. You need to implement certain APIs and expose them via an accessible URL for Nium. ### One-leg out If the issuer and acquirer *are not* within the EEA and the UK, then Nium may apply a one-leg out (OLO)-driven Strong Customer Authentication (SCA) exemption. When that happens, the 3DS authentication can be performed only by using the simple OOB authentication flow or the standard OTP-based authentication to provide a simplified user experience. ## OOB authentication flow The following diagrams capture the high-level interaction among key parties when a cardholder uses their card online to do shopping at an e-commerce merchant. Once the authentication is successful, the merchant end—acquirer, acquiring processor, payment service provider payment gateway—receives the Cardholder Authentication Verification Value (CAVV) or Universal Cardholder Authentication Field (UCAF) authentication result. It's expected that the merchant end includes the authentication result when submitting the transaction authorization to the network as authentication proof. ### OOB authentication flow This diagram explains how a simple OOB authentication works. OOB-1 When a cardholder attempts to make an online payment to a merchant supporting 3DS authentication, the following process occurs: 1. The cardholder performs an online transaction such as shopping at an e-commerce site. 2. The merchant initiates an authentication request by sending the request to the card network such as Visa, Mastercard, etc. 3. The card network routes the authentication request to Nium. 4. Nium engages with your system via the [Check Authentication Method V2](/docs/cards/3ds-security/check-authentication) API, if you opt for it. You need to have implemented the operation following the API contract, mandated by Nium, to check if the cardholder's device supports biometrics authentication. 5. Your system sends the results of the authentication method supported by the cardholder's device to Nium. These results can be OOB authentication, if the cardholder's device supports biometrics, otherwise the applicable fallback method is returned. For OOB authentication: 6. Nium prompts the cardholder, via the merchant’s checkout experience, to complete the authentication using your mobile application. 7. At the same time, Nium engages with your system, via the [Initiate OOB Authentication V2](/docs/cards/3ds-security/initiate-oob) API. You need to have implemented the operation following the API contract, mandated by Nium, to initiate the OOB authentication. 8. Your system delivers a push notification to the cardholder to complete the authentication for the online transaction using your mobile application. 9. The cardholder authenticates using biometrics through your mobile application. The results of the authentication are relayed to your system. 10. Your system informs Nium of the authentication results via the [OOB Authentication Callback](/docs/cards/3ds-security/oob-callback) API. you need to have implemented the operation following the API contract mandated by Nium. 11. Nium sends the authentication result to the network and the merchant. ### OOB authentication flow with fallback to OTP In this use case, you want to consult on every transaction and the flow supports only OOB authentication with fallback. While the mobile app offers a seamless experience through biometrics authentication, potential constraints can occur. These include data connectivity issues, the prevalence of biometrics support on devices, or network availability when the cardholder is roaming overseas. These limitations may occasionally present challenges for the cardholder to complete the authentication under these scenarios. In situations where OOB authentication isn't feasible, the cardholder is offered a backup authentication method option, for example, OTP only. Refer to the [OTP-based 3DS authentication flow](/docs/cards/3ds-security/one-time-password) guide for more information.06-08-03-oob-2 OOB-2 #### Transaction flow 1. The cardholder performs an online transaction such as shopping at an e-commerce site. 2. The merchant initiates an authentication request by sending the request to the card network such as Visa, Mastercard, etc. 3. The card network routes the authentication request to Nium. 4.  Nium engages with your system via the Check Authentication Method V2 API. You need to have implemented the operation following the API contract, mandated by Nium, to check if the cardholder's device supports biometrics authentication. 5. Your system sends the results of the authentication method supported by the cardholder's device to Nium. These results can be OOB authentication, if the cardholder's device supports biometrics, otherwise OTP only is returned. For OOB authentication: 6. Nium prompts the cardholder, via the merchant’s checkout experience, to complete the authentication using your mobile application. 7. At the same time, Nium engages with your system, via the [Initiate OOB Authentication V2](/docs/cards/3ds-security/initiate-oob) API. You need to have implemented the operation following the API contract, mandated by Nium, to initiate the OOB authentication. 8. Your system delivers a push notification to the cardholder to complete the authentication for the online transaction using your mobile application. 9. The cardholder authenticates using biometrics through your mobile application. The results of the authentication are relayed to your system. 10. In the event of a timeout or other unforeseen circumstances, such as the user *is not* able to complete the OOB authentication, the system triggers the OTP-based 3DS flow as a fallback. Refer to the [OTP-based 3DS authentication flow](/docs/cards/3ds-security/one-time-password) guide for more information. ### OOB authentication flow with fallback to OTP plus KBA In this use case, you want to consult on every transaction and the flow supports only OOB authentication with fallback. While the mobile app offers a seamless experience through biometrics authentication, potential constraints can occur. These include data connectivity issues, the prevalence of biometrics support on devices, or network availability when the cardholder is roaming overseas. These limitations may occasionally present challenges for the cardholder to complete the authentication under these scenarios. In situations where OOB authentication isn't feasible, the cardholder is offered a backup authentication method option i.e., OTP plus KBA. Refer to the [OTP + Knowledge-based authentication flow](/docs/cards/3ds-security/otp-and-knowledge) guide for more information. OOB-3 #### Transaction flow 1. The cardholder performs an online transaction such as shopping at an e-commerce site. 2. The merchant initiates an authentication request by sending the request to the card network such as Visa, Mastercard, etc. 3. The card network routes the authentication request to Nium. 4.  Nium engages with your system via the Check Authentication Method V2 API. You need to have implemented the operation following the API contract, mandated by Nium, to check if the cardholder's device supports biometrics authentication. 5. Your system sends the results of the authentication method supported by the cardholder's device to Nium. These results can be OOB authentication, if the cardholder's device supports biometrics, otherwise OTP plus KBA is returned. For OOB authentication: 6. Nium prompts the cardholder, via the merchant’s checkout experience, to complete the authentication using your mobile application. 7. At the same time, Nium engages with your system, via the [Initiate OOB Authentication V2](/docs/cards/3ds-security/initiate-oob) API. You need to have implemented the operation following the API contract, mandated by Nium, to initiate the OOB authentication. 8. Your system delivers a push notification to the cardholder to complete the authentication for the online transaction using your mobile application. 9. The cardholder authenticates using biometrics through your mobile application. The results of the authentication are relayed to your system. 10. In the event of a timeout or other unforeseen circumstances, for example, the user *is not* able to complete the OOB authentication, the system triggers the OTP plus the KBA flow as a fallback. Refer to the [OTP + Knowledge-based authentication flow](/docs/cards/3ds-security/otp-and-knowledge) guide for more information. ## Authentication APIs The following authentication APIs aren't exposed in the Swagger documentation. You, as the client, use these APIs for development. Nium directly calls these APIs. | API name | Action | Reference link | | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | Check Authentication Method V2 | If you opt to be consulted on every transaction, you need to implement this API. Respond with the authentication method applicable to the e-commerce transaction. | [Check Authentication Method V2](/docs/cards/3ds-security/check-authentication) | | Initiate OOB Authentication V2 | You need to implement the Initiate OOB Authentication V2 API as part of the OOB authentication process. Nium invokes the endpoint to perform the operation and start the OOB authentication step for an e-commerce transaction. | [Initiate OOB Authentication V2](/docs/cards/3ds-security/initiate-oob) | | OOB Authentication Callback | Use this callback to notify Nium after successfully processing your OOB authentication as part of the SCA flow. | [OOB Authentication Callback](/api#tag/3ds/POST/api/v2/client/{clientHashId}/3ds/oob/callback) | | Passcode Validation V2 | If you opt to validate the passcode, you need to implement the Passcode Validation V2 API as part of the KBA flow for an e-commerce transaction. | [Passcode Validation V2](/docs/cards/3ds-security/passcode-validation) | | Add Or Update Passcode | If you opt for Nium to manage the passcode, use this API to set or update it for a specific card. | [Add Or Update Passcode](/api#tag/3ds/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/3ds/passcode) | | 3DS Passcode Enrollment Status | If you opt for Nium to manage the passcode, use this API to retrieve the status of the passcode enrollment for all cards associated with the wallet. Results can be filtered by the `cardHashId`. | [3DS Passcode Enrollment Status](/api#tag/3ds/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/3ds/passcode/status) | --- # Check Authentication URL: https://docs.nium.com/docs/cards/3ds-security/check-authentication You need to implement the Check Authentication Method V2 API if you wish to be consulted for every e-commerce transaction. Nium invokes this API to get the authentication method from you during the e-commerce transaction. ```shell POST https:///v2/preference ``` `EComAuthCodeValidationBaseURL` is the URL that you provide during the setup and which Nium uses as a base URL. ## Headers | Header | Parameters | | ------------- | ---------------- | | content-type | application/JSON | | x-request-id | UUID | | x-client-name | String | ## Request body The API's request body is divided into these three areas: ### Card information | Field | Description | Type | Required/Optional | | ------------------ | ------------------------------------------------------------------------------------------------------------------- | ------ | ----------------- | | `maskedCardNumber` | The 16-digit masked card number in format 1234-56xx-xxxx-3456. | UUID | Required | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | Required | | `cardHashId` | The unique card identifier that's generated while new or add-on card issuance. | UUID | Required | | `email` | This field accepts the customer's email address ID. | String | Required | | `phoneNumber` | This field accepts the customer’s phone number. | String | Required | | `cardExpiry` | The card expiration year. This field contains the base64 encoded expiration date of the card in the `MM/YY` format. | Number | Required | ### Merchant information | Field | Description | Type | Required/Optional | | :------------ | :-------------------------------------------------------------------- | :----- | :---------------- | | `id` | The identifier for the merchant performing the purchase request. | String | Optional | | `name` | This field accepts the merchant's name. | String | Required | | `mcc` | The code that's used to describe the merchant type of business. | String | Optional | | `countryCode` | The country code of the merchant, for example, 840 numeric -3 format. | String | Optional | | `url` | The URL or app name for the merchant performing the purchase request. | String | Optional | ### Transaction information | Field | Description | Type | Required/Optional | | :---------- | :---------------------------------------------------------------------------------------------- | :----- | :---------------- | | `amount` | This field accepts the transaction amount up to two decimals. The formatted transaction amount. | Number | Required | | `currency` | This field accepts the three-letter ISO-4217 transaction currency code. | String | Required | | `timestamp` | The transaction time stamp, for example, 2020-03-21T20:55:49.0000Z. | String | Optional | ## Request example ``` curl -X POST \ /v2/preference> \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: Cards-Card-Service' \ -d '{ "clientHashId": "e4wc6a3b-52a0-2301-a670-08db16e8447a", "customerHashId": "df3dfdf-d75a-4d7e-b575-f8ed34egfh94", "card", { "maskedCardNumber" : "4611-35xx-xxxx-1234", "cardHashId": "5fh34flg-8e7a-4bb5-a010-3a07cf714534", "email": "melissa@xyz.com", "phoneNumber": "9834201949", "cardExpiry":"" }, "merchant", { "id":"", "name" : "Test Merchant", "mcc":"", "countryCode":"", "url":"" } "transaction", { "amount": "1.10", "currency": "EUR", "timestamp":"" } } ``` ## Response body | Field | Description | Type | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `respCode` | The response code. The possible values are: \n • `00`—If OOB is the only authentication method supported. \n • `01`—If OOB with the fallback option (OTP plus passcode) method is supported. \n • `02`—If OTP plus passcode is the only supported method. \n • `03`—If OTP is the only method supported. \n • `04`—If OOB with fallback option OTP. | String | | `message` | The message that's based on the preferences. The possible values are: \n • `OOB Only`—Only the OOB authentication method is supported. \n • `OOB with fallback to OTP+Passcode`—If the OOB with fallback option (OTP plus passcode) method is supported. \n • `OTP+Passcode Only`—If only the OTP plus passcode method is supported. \n • `OTP Only`—If the OTP-only method is supported. \n • `OOB with fallback OTP`—If the OOB with the fallback option (OTP) method is supported. | String | ## Response example ### Success response — for OOB only ```JSON { "respCode" : "00", "message" : "OOB Only" } ``` ### Success response — for OOB with fallback to OTP SMS + passcode ```JSON { "respCode" : "01", "message" : "OOB with fallback to OTP+Passcode" } ``` ### Success Response — for OTP SMS + Passcode only ```JSON { "respCode" : "02", "message" : "OTP+Passcode Only" } ``` ### Success response — for OTP only ```json { "respCode" : "03", "message" : "OTP Only" } ``` ### Success response — for OOB with fallback to OTP ```json { "respCode" : "04", "message" : "OOB with fallback to OTP" } ``` --- # OOB Authentication Callback URL: https://docs.nium.com/docs/cards/3ds-security/oob-callback Use this callback to notify Nium after successfully processing your out-of-band (OOB) authentication as part of the strong customer authentication (SCA) flow. ```shell POST https://gateway.nium.com/api/v1/client/{clientHashId}/notifications/3ds/oob/callback ``` ## Headers | Header | Parameters | | --------------- | ---------------- | | `content-type` | application/JSON | | `x-request-id` | UUID | | `x-client-name` | String | ## Request example ```Bash curl -X POST \ https://gateway.nium.com/api/v1/client/{clientHashId}/notifications/3ds/oob/callback \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: Cards-Customer-Service' \ ​ -d '{ "authTransactionId": "2096355c-57c3-43c6-9c4a-fb155a026e06", "referenceNumber": "1b6865e4-5839-424a-8e73-965ef15c5d89", "status": "Success", "statusCode": "SSS000" }' ``` ```Java OkHttpClient client = new OkHttpClient(); MediaType mediaType = MediaType.parse("application/octet-stream"); RequestBody body = RequestBody.create(mediaType, "{\r\n \"authTransactionId\": \"2096355c-57c3-43c6-9c4a-fb155a026e06\",\r\n \"referenceNumber\": \"1b6865e4-5839-424a-8e73-965ef15c5d89\",\r\n \"status\": \"Success\",\r\n \"statusCode\": \"SSS000\"\r\n}"); Request request = new Request.Builder() .url("https://gateway.nium.com/api/v1/oob/callback") .post(body) .addHeader("content-type", "application/json") .addHeader("x-request-id", "123e4567-e89b-12d3-a456-426655440000") .addHeader("x-client-name", "Cards-Customer-Service") .build(); Response response = client.newCall(request).execute(); ``` ```Javascript var settings = { "async": true, "crossDomain": true, "url": "https://gateway.nium.com/api/v1/oob/callback", "method": "POST", "headers": { "content-type": "application/json", "x-client-name": "Cards-Customer-Service", "x-request-id": "123e4567-e89b-12d3-a456-426655440000" }, "data": JSON.stringify({ "authTransactionId": "2096355c-57c3-43c6-9c4a-fb155a026e06", "referenceNumber": "1b6865e4-5839-424a-8e73-965ef15c5d89", "status": "Success", "statusCode": "SSS000" }), }; $.ajax(settings).done(function (response) { console.log(response); }); ``` ```Python import requests curl = "https://gateway.nium.com/api/v1/oob/callback" payload = json.dumps({ "authTransactionId": "2096355c-57c3-43c6-9c4a-fb155a026e06", "referenceNumber": "1b6865e4-5839-424a-8e73-965ef15c5d89", "status": "Success", "statusCode": "SSS000" }) headers = { 'content-type': 'application/json', 'x-client-name': 'Cards-Customer-Service', 'x-request-id': '123e4567-e89b-12d3-a456-426655440000' } response = requests.request("POST", url, data=payload, headers=headers) print(response.text) ``` ### Request body | Field | Description | Type | Required | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | | `authTransactionId` | An authorization transaction ID is the unique ID of the transaction received during the OOB authentication. | UUID | Required | | `referenceNumber` | A reference number is a unique ID associated with the OOB request from your system. | UUID | Required | | `status` | The status of the OOB authentication process. It signifies whether you can process the authentication or not. Since you use this callback only after processing the OOB authentication, the expected value from you is `Success`. Refer to the `statusCode` for the result of the OOB authentication. | String | Optional | | `statusCode` | The OOB authentication status code. It signifies whether the transaction is approved or declined. The possible values are: \n • `SSS000` — OOB authentication approved. \n • `VCU701` — OOB authentication declined. | String | Required | ## Response example ```JSON { "status" : "Success" } ``` ### Response body | Field | Description | Type | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `status` | The status of the request after processing at Nium. The possible values are: \n • `Success` — When the request is processed successfully. \n • `Failed` — When the request *is not* processed successfully. | String | --- # Initiate OOB URL: https://docs.nium.com/docs/cards/3ds-security/initiate-oob You need to implement the Initiate OOB Authentication V2 API as part of the out-of-band (OOB) authentication process. Nium invokes the endpoint to perform the operation and start the OOB authentication step of an e-commerce transaction. ```URL POST https:///v2/oob ``` `EComAuthCodeValidationBaseURL` is the URL that you provide during the setup and which Nium uses as a base URL. ## Headers | Header | Parameter | | --------------- | ---------------- | | `content-type` | application/JSON | | `x-request-id` | UUID | | `x-client-name` | String | ## Request body The API's request body is divided into these four areas: | Field | Description | Required/Optional | Type | | :------------------ | :-------------------------------------------------------------------- | :---------------- | :--- | | `authTransactionId` | This field accepts the unique identifier generated for a transaction. | Required | UUID | ### Payment information | Field | Description | Required/Optional | Type | | :----------------- | :-------------------------------------------------------------------------------------------------------------------- | :---------------- | :----- | | `maskedCardNumber` | The 16-digit masked card number in the 1234-56xx-xxxx-3456 format. | Required | UUID | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | Required | UUID | | `cardHashId` | The unique card identifier that's generated while new or add-on card issuance. | Required | UUID | | `cardExpiry` | The card's expiration year. This field contains the base64 encoded expiration date of the card in the `MM/YY` format. | Required | String | ### Merchant information | Field | Description | Required/Optional | Type | | :------------ | :-------------------------------------------------------------------- | :---------------- | :----- | | `id` | The identifier for the merchant performing the purchase request. | Optional | String | | `name` | This field accepts the merchant's name. | Required | String | | `mcc` | The code that's used to describe the merchant business type. | Optional | String | | `countryCode` | The country code of the merchant, for example, 840 numeric -3 format. | Optional | String | | `url` | The URL or app name for the merchant performing the purchase request. | Optional | String | ### Transaction information | Field | Description | Required/Optional | Type | | ----------- | ----------------------------------------------------------------------------------------------- | ----------------- | ------ | | `amount` | This field accepts the transaction amount up to two decimals. The formatted transaction amount. | Required | Number | | `currency` | This field accepts the three-letter ISO-4217 transaction currency code. | Required | String | | `timestamp` | The transaction time stamp, for example, \n2020-03-21T20:55:49.0000Z. | Optional | String | ## Request example ```Bash curl -X POST \ /v2/oob> \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: Cards-Card-Service' \ -d '{ "authTransactionId" : "e5610bdf-12b1-9807-4ccf-09b70bcff776", "clientHashId":"", "card", { "maskedCardNumber" : "4611-35xx-xxxx-1234", "cardHashId":"", "cardExpiry":"" }, "merchant", { "id":"", "name" : "Test Merchant", "mcc":"", "countryCode":"", "url":"" } "transaction", { "amount": "1.10", "currency": "EUR", "timestamp":"" } } ``` ```Java OkHttpClient client = new OkHttpClient(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\r\n \"authTransactionId\" : \"e5610bdf-12b1-9807-4ccf-09b70bcff776\",\r\n \"clientHashId\" : \"e2710bdf-25b1-4535-9ccf-09b70bcff684\",\r\n \"cardHashId\" : \"e3008bdf-25b1-4535-9ccf-09b70bcff684\",\r\n \"customerHashId\" : \"e2708eef-25b1-4535-9ccf-09b70bcff684\",\r\n \"walletHashId\" : \"e2708bdf-25b1-4535-9ccf-09b70bcdd684\",\r\n \"merchantName\" : \"Test Merchant\",\r\n \"maskedCardNumber\" : \"4611-35xx-xxxx-1234\",\r\n \"transactionAmount\" : \"1.10\",\r\n \"transactionCurrency\" : \"EUR\"\r\n}"); Request request = new Request.Builder() .url("https:///oob") .post(body) .addHeader("content-type", "application/json") .addHeader("x-request-id", "123e4567-e89b-12d3-a456-426655440000") .addHeader("x-client-name", "Cards-Customer-Service") .build(); Response response = client.newCall(request).execute(); ``` ```Javascript var settings = { "https:///oob", "method": "POST", "timeout": 0, "headers": { "Content-Type": "application/json", "x-request-id": "123e4567-e89b-12d3-a456-426655440000", "x-client-name": "Cards-Customer-Service" }, "data": JSON.stringify({ "authTransactionId": "e5610bdf-12b1-9807-4ccf-09b70bcff776", "clientHashId": "e2710bdf-25b1-4535-9ccf-09b70bcff684", "cardHashId": "e3008bdf-25b1-4535-9ccf-09b70bcff684", "customerHashId": "e2708eef-25b1-4535-9ccf-09b70bcff684", "walletHashId": "e2708bdf-25b1-4535-9ccf-09b70bcdd684", "merchantName": "Test Merchant", "maskedCardNumber": "4611-35xx-xxxx-1234", "transactionAmount": "1.10", "transactionCurrency": "EUR" }), }; $.ajax(settings).done(function (response) { console.log(response); }); ``` ```Python import requests url = "https:///oob" payload = json.dumps({ "authTransactionId": "e5610bdf-12b1-9807-4ccf-09b70bcff776", "clientHashId": "e2710bdf-25b1-4535-9ccf-09b70bcff684", "cardHashId": "e3008bdf-25b1-4535-9ccf-09b70bcff684", "customerHashId": "e2708eef-25b1-4535-9ccf-09b70bcff684", "walletHashId": "e2708bdf-25b1-4535-9ccf-09b70bcdd684", "merchantName": "Test Merchant", "maskedCardNumber": "4611-35xx-xxxx-1234", "transactionAmount": "1.10", "transactionCurrency": "EUR" }) headers = { 'content-type': "application/json", 'x-request-id': "123e4567-e89b-12d3-a456-426655440000", 'x-client-name': "Cards-Customer-Service" } response = requests.request("POST", url, data=payload, headers=headers) print(response.text) ``` --- # Passcode Validation URL: https://docs.nium.com/docs/cards/3ds-security/passcode-validation You need to implement the Passcode Validation V2 API as part of the knowledge-based authentication (KBA) and the Strong Customer Authentication (SCA) requirement for e-commerce transactions. Nium invokes the operation to validate the customer's passcode during the authentication step of an e-commerce transaction. ```URL POST https:///v2/passcode ``` `EComAuthCodeValidationBaseURL` is the URL that you provide during the setup and which Nium uses as a base URL. ## Headers | Header | Parameters | | --------------- | ---------------- | | `Content-Type` | application/JSON | | `x-request-id` | UUID | | `x-client-name` | String | ## Request body The API's request body is divided into these four areas: | Field | Description | Required/Optional | Type | | ---------- | --------------------------------------------- | ----------------- | :----- | | `passcode` | This field contains the base64 encoded value. | Required | Number | ### Card information | Field | Description | Required/Optional | Type | | :----------------- | :-------------------------------------------------------------------------------------------------------------------- | :---------------- | :----- | | `maskedCardNumber` | The 16-digit masked card number in the 1234-56xx-xxxx-3456 format. | Required | UUID | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | Required | UUID | | `cardHashId` | The unique card identifier that's generated while new or add-on card issuance. | Required | UUID | | `cardExpiry` | The card's expiration year. This field contains the base64 encoded expiration date of the card in the `MM/YY` format. | Required | String | ### Merchant information | Field | Description | Required/Optional | Type | | :------------ | :-------------------------------------------------------------------- | :---------------- | :----- | | `id` | The identifier for the merchant performing the purchase request. | Optional | String | | `name` | This field accepts the merchant's name. | Required | String | | `mcc` | The code that's used to describe the merchant business type. | Optional | String | | `countryCode` | The country code of the merchant, for example, 840 numeric -3 format. | Optional | String | | `url` | The URL or app name for the merchant performing the purchase request. | Optional | String | ### Transaction information | Field | Description | Required/Optional | Type | | ----------- | ----------------------------------------------------------------------------------------------- | ----------------- | ------ | | `amount` | This field accepts the transaction amount up to two decimals. The formatted transaction amount. | Required | Number | | `currency` | This field accepts the three-letter ISO-4217 transaction currency code. | Required | String | | `timestamp` | The transaction time stamp, for example, \n2020-03-21T20:55:49.0000Z. | Optional | String | ## Request example ```Bash curl -X POST \ 'https:///v2/passcode' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: Cards-Card-Service' \ -d '{ "clientHashId":"", "passcode":"", "card", { "maskedCardNumber" : "4611-35xx-xxxx-1234", "cardHashId":"", "cardExpiry":"", }, "merchant", { "id":"", "name" : "Test Merchant", "mcc":"", "countryCode":"", "url":"" } "transaction", { "amount": "1.10", "currency": "EUR", "timestamp":"" } } }' ``` ## Response example A **successful verification** is returned if the given passcode matches the one found in the customer's profile. ```json { "message": "Request processed successfully", "referenceNumber": "481b18ad-1146-439b-a227-f42fda6ae306", "responseCode": "00" } ``` A **failed verification** is returned if the given passcode *does not* match the one found in the customer's profile. ```json { "message": "Passcode Mismatch", "referenceNumber": "9cac7923-42bf-4c9e-97d3-23ef41ba86b1", "responseCode": "01" } ``` A **failed verification** is returned if the customer *does not* have a passcode or *has not* set up the passcode. ```json { "message": "Passcode not setup by user", "referenceNumber": "5faee1b2-97b0-4355-b2ad-774f1bfcb6c5", "responseCode": "02" } ``` --- # Nium Verify URL: https://docs.nium.com/docs/verify Verify account holder details in real-time to ensure accurate payments and reduce fraud. Nium Verify is a real-time bank account verification solution offered by Nium. Its primary purpose is to help businesses ensure the accuracy of account details before processing payments. By verifying details upfront, Nium Verify helps to reduce the risk of payment failures, fraud, and assists in fulfilling compliance requirements. The service integrates seamlessly into existing payment workflows, offering a simple and efficient way to validate bank account information across multiple regions and payout methods. This means you potentially no longer need a separate process solely for verifying bank account details. ## How Nium Verify works At its core, Nium Verify validates bank accounts by requiring either the bank account number and its corresponding routing code or a linked proxy identifier (such as PayNow in Singapore or UPI in India). Verification involves submitting these details to the Nium Verify service, which then provides a status indicating the verification outcome. ## Who can use Nium Verify Nium Verify is available for different types of users: - **New Nium Users**: If you only need to verify bank account details and do not plan to use Nium's other services, you can use Verify independently. This approach allows you to submit account details directly for verification without fully integrating into the larger Nium payment platform. You might use this before triggering payouts, setting up direct debits, or creating a beneficiary on your own platform. - **Existing Nium Clients**: If you are already using or plan to use other Nium services, you can seamlessly integrate Nium Verify into your existing Nium integration. This allows for verifying accounts, for example, at the point of adding a beneficiary. To sign up for Nium Verify, contact your Nium account manager, Nium Support, or the Nium sales team (for independent use). Use of the service is subject to [Terms of Service](https://www.nium.com/legal/verify-terms-and-conditions). ## Supported payout methods The [Verify a Bank Account](/api#tag/nium-verify/POST/api/v1/client/{clientHashId}/verifications) request request specifically supports verification when the beneficiary's payout method is LOCAL or PROXY. | Payout Method | Description | | ------------- | ------------------------------------------------------------------------------------------- | | LOCAL | Used for local bank accounts via local clearing systems (like ACH) or local currency wires. | | PROXY | Used for transfers through proxy identifiers (like PayNow, UPI). | ## Supported corridors and account holder name availability Nium Verify can validate account information against clearing systems in a growing list of supported countries. For many of these corridors, Nium can also provide the full name of the account holder associated with the bank account. Corridors marked (Beta) are currently in development with limited coverage and may be subject to additional changes. Nium is continuously expanding support for more corridors. If you have any questions about using Nium Verify and a corridor, contact or your Nium account manager. ### Europe and United Kingdom Europe and United Kingdom | **Country – Currency** | **Payout Method** | **Account Holder Name** | **Name Match Status** | | ---------------------- | ----------------- | ----------------------- | --------------------- | | Austria - EUR | LOCAL | Available | Yes | | Belgium - EUR | LOCAL | Available | Yes | | Bulgaria - EUR | LOCAL | Available | Yes | | Croatia - EUR | LOCAL | Available | Yes | | Cyprus - EUR | LOCAL | Available | Yes | | Estonia - EUR | LOCAL | Available | Yes | | Finland - EUR | LOCAL | Available | Yes | | France - EUR | LOCAL | Available | Yes | | Germany - EUR | LOCAL | Available | Yes | | Greece - EUR | LOCAL | Available | Yes | | Ireland - EUR | LOCAL | Available | Yes | | Italy - EUR | LOCAL | Available | Yes | | Latvia - EUR | LOCAL | Available | Yes | | Lithuania - EUR | LOCAL | Available | Yes | | Luxembourg - EUR | LOCAL | Available | Yes | | Malta - EUR | LOCAL | Available | Yes | | Netherlands - EUR | LOCAL | Available | Yes | | Portugal - EUR | LOCAL | Available | Yes | | Slovakia - EUR | LOCAL | Available | Yes | | Slovenia - EUR | LOCAL | Available | Yes | | Spain - EUR | LOCAL | Available | Yes | | United Kingdom - GBP | LOCAL | Available | Yes | > **UK specific note:** The account holder's name is only returned for strong and partial matches and will not be returned for weak matches. ### APAC and MEA APAC and MEA | Country | Currency | Payout Method | Account Holder Name | Name Match Status | | ----------- | -------- | ------------- | ------------------- | ----------------- | | India | INR | Local, Proxy | Yes | Yes | | Singapore | SGD | Proxy | Yes | Yes | | Malaysia | MYR | Local, Proxy | Yes | Yes | | Indonesia | IDR | Local | Yes | Yes | | Thailand | THB | Local | No | No | | Vietnam | VND | Local | Yes | No | | Australia | AUD | Proxy | Yes | No | | Hong Kong | HKD | Proxy | Yes | Yes | | South Korea | KRW | Local | Yes | Not Available | | Pakistan | PKR | Local | Yes | Yes | | Nigeria | NGN | Local | Yes | No | | Tanzania | TZS | Local | Yes | No | ### North America and LATAM 🌍 North America and LATAM | Country | Currency | Payout Method | Account Holder Name | Name Match | | ------------- | -------- | ------------- | ------------------- | ---------- | | United States | USD | Local | Yes | Yes | ## Required fields for Nium Verify To verify a bank account, you must include the necessary account details for the "Account holder" - the recipient of the funds. Required fields vary depending on the specific country (corridor) and payout method. Essential "Account holder details" include details like the account holder's name, bank account number, and routing codes. The specific mandatory fields for each supported corridor are noted. mentioned in [Required Fields](/docs/verify/mandatory-fields) section. ## How to use Nium Verify You can integrate Nium Verify in two primary ways: - [**Using Nium Verify Independently**](#using-nium-verify-independently): This approach is for users who specifically need Nium Verify without integrating into Nium's other payment services. - [**Using Nium Verify as an Existing Client**](#using-nium-verify-as-an-existing-client): This method allows you to leverage Nium Verify within your existing Nium integration, often alongside other Nium services like beneficiary creation. ## Using Nium Verify independently This approach is for users who specifically need Nium Verify without integrating into Nium's other payment services. - [Step 1: Call Nium Verify](#step-1-call-nium-verify) - [Step 2: Handle the response](#step-2-handle-the-response) #### Step 1: Call Nium Verify Submit an Account Verification request using the [Verify a Bank Account](/api#tag/nium-verify/POST/api/v1/client/{clientHashId}/verifications) request. Ensure you include the mandatory fields as [required](/docs/verify/mandatory-fields) for the specific corridor you are verifying. #### Step 2: Handle the response The [Verify a Bank Account](/api#tag/nium-verify/POST/api/v1/client/{clientHashId}/verifications) request returns a response that includes a `status` field detailing the results. The `status` field returns the following values: - **valid**: The account exists and the verification was successful. Responses with this status can include `derivedAccountDetails` providing the account holder's name. - **invalid**: Details can't be validated. Review and confirm the provided account details and resubmit the request. If the account details are accurate and returns **invalid**, you must check the `failureCode` field for the specific reason. For more information, see [Status and Error Codes](/docs/verify/error-code). ## Using Nium Verify as an existing client This method allows you to leverage Nium Verify within your existing Nium integration, often alongside other Nium services like beneficiary creation. - [Step 1: Add the `beneficiary`](#step-1-add-the-beneficiary) - [Step 2: Review account verification status](#step-2-review-account-verification-status) Once the beneficiary is created, you can continue with creating [Payouts](/docs/payouts/transfer-money) as usual. #### Step 1: Add the `beneficiary` - Use the [Add Beneficiary V2](/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) request: This request allows you to include account verification details as part of the `beneficiary` creation process. - Alternatively, if the `beneficiary` already exists, you can fetch their details using the [Beneficiary Details V2](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) request. #### Step 2: Review account verification status - After adding or fetching the beneficiary, you will receive a response. Check the status and name fields within the `accountVerification` object in this response. - The statuses within the `accountVerification` object indicate the verification outcome for this integration method: - **verified**: The account details are correct, and you can proceed with Payouts. - **not\_verified**: The account details provided are incorrect. You must verify the information and submit it again. - **not\_supported**: This means the country specified for the account is not supported for account verification by Nium Verify. For details on how to test Verify, see [Testing Verify](/docs/verify/testing-verify). If you have any questions about using Nium Verify and a corridor, contact or your Nium account manager. To sign up for Nium Verify, please contact your Nium account manager or Nium Support. ### Key concepts | Term | Description | | :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Account holder** | The recipient of the funds, either a business or individual, whose account you want to verify. | | **Account holder details** | Includes details like the account holder's name, bank account number, routing codes, and more. See the [Beneficiary Validation Schema V2](/api#tag/beneficiary/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/currency/{currencyCode}/validationSchemas) for required fields. | --- # Testing Verify URL: https://docs.nium.com/docs/verify/testing-verify Use the test values below to simulate successful and failed verification scenarios with Nium Verify in the sandbox environment. Use the test values below to simulate how Nium Verify behaves with different bank account and proxy details. These examples help you confirm both successful and failed verification flows in your sandbox environment. ## Verify with bank account details Use the following values to test bank account details for different countries and currencies. | Country | Currency | Bank/Proxy | Account Name | Bank Account Number | Routing Code | Bank Code | Status | | ------- | -------- | ---------- | ------------------------ | ---------------------- | ------------ | --------- | --------------------- | | GB | GBP | Bank | JOHN SMITH | 1212121212 | 123456 | — | Valid (Match) | | GB | GBP | Bank | JOHN SMITH | 11111111 | 123456 | — | Valid (Partial Match) | | GB | GBP | Bank | JOHN SMITH | 131313131313 | 123456 | — | Valid (No Match) | | GB | GBP | Bank | JOHN SMITH | 22222222 | 123456 | — | Invalid | | ID | IDR | Bank | HJ. FARIDAH EFFEND | 1122334455 | CENAIDJA | — | Valid (Match) | | ID | IDR | Bank | HJ. FARIDAH | 1122334455 | CENAIDJA | — | Valid (Partial Match) | | ID | IDR | Bank | FIRA DIYANKA | 1122334455 | CENAIDJA | — | Valid (No Match) | | ID | IDR | Bank | JOHN DOE | 123456789012345 | SYJBIDJ1 | — | Invalid | | TH | THB | Bank | TEST DEMO | 1111111111 | KASITHB1 | — | Valid | | TH | THB | Bank | TEST DEMO | 2222222222 | KASITHB1 | — | Invalid | | VN | VND | Bank | NGUYEN VAN A | 11111111111 | VTCBVNVX | — | Valid (Match) | | VN | VND | Bank | NGUYEN VAN A | 11111111111 | VTCBVNVX | — | Valid (Partial Match) | | VN | VND | Bank | NGUY | 11111111111 | VTCBVNVX | — | Valid (No Match) | | VN | VND | Bank | NGUYEN | 2222222222 | VTCBVNVX | — | Invalid | | IN | INR | Bank | Beneficiary Name | 11111111111111 | HDFC0000522 | — | Valid (Match) | | IN | INR | Bank | Bene Name | 11111111111111 | HDFC0000522 | — | Valid (Partial Match) | | IN | INR | Bank | Bene | 11111111111111 | HDFC0000522 | — | Valid (No Match) | | IN | INR | Bank | TEST DEMO | 22222222222222 | HDFC0000522 | — | Invalid | | MY | MYR | Bank | TEST CUSTOMER WP 1 | 0033991118 | OCBCMYKL | — | Valid (Match) | | MY | MYR | Bank | TEST CUSTOMER | 0033991118 | OCBCMYKL | — | Valid (Partial Match) | | MY | MYR | Bank | DEMO | 0033991118 | OCBCMYKL | — | Valid (No Match) | | MY | MYR | Bank | TEST DEMO | 12343333 | OCBCMYKL | — | Invalid | | PK | PKR | Bank | ABDUL AZEEM | 1111111111 | HABBPKKA | - | Valid (Match) | | PK | PKR | Bank | ABDUL | 1111111111 | HABBPKKA | - | Valid (Partial Match) | | PK | PKR | Bank | TEST | 1111111111 | HABBPKKA | - | Valid (No Match) | | PK | PKR | Bank | ABDUL | 2222222222 | HABBPKKA | - | Invalid | | PK | PKR | Bank | ABDUL AZEEM | 1111111111 | - | HABB | Valid (Match) | | PK | PKR | Bank | ABDUL | 1111111111 | - | HABB | Valid (Partial Match) | | PK | PKR | Bank | TEST | 1111111111 | - | HABB | Valid (No Match) | | PK | PKR | Bank | ABDUL | 2222222222 | - | HABB | Invalid | | KR | KRW | Bank | ASAN | 1212121212 | 123456 | — | Valid (Match) | | KR | KRW | Bank | ASAN | 11111111 | 123456 | — | Valid (Partial Match) | | KR | KRW | Bank | ASAN | 131313131313 | 123456 | — | Valid (No Match) | | KR | KRW | Bank | JOHN SMITH | 22222222 | 123456 | — | Invalid | | NG | NGN | Bank | OYENIYI TOLULOPE OYEBIYI | 1111111111 | CMBBNGLA | — | Valid (Match) | | NG | NGN | Bank | OYENIYI | 1111111111 | CMBBNGLA | — | Valid (Partial Match) | | NG | NGN | Bank | TEST | 1111111111 | CMBBNGLA | — | Valid (No Match) | | NG | NGN | Bank | OYENIYI | 2222222222 | CMBBNGLA | — | Invalid | | TZ | TZS | Bank | NICHOLAS | 1111111111 | EQBLTZTZ | — | Valid (Match) | | TZ | TZS | Bank | NICH0 | 1111111111 | EQBLTZTZ | — | Valid (Partial Match) | | TZ | TZS | Bank | NIC | 1111111111 | EQBLTZTZ | — | Valid (No Match) | | TZ | TZS | Bank | NICHOLAS | 2222222222 | EQBLTZTZ | — | Invalid | | US | USD | Bank | MELANIE | 100000555 | 101000019 | — | Valid (Match) | | US | USD | Bank | MELANIE | 100000444 | 101000019 | — | Valid (Partial Match) | | US | USD | Bank | MELANIE | 100000333 | 101000019 | — | Valid (No Match) | | US | USD | Bank | MELANIE | 100000222 | 101000019 | — | Invalid | | EU | EUR | Bank | CREDITOR | FR28503399001111111111 | — | — | Valid (Match) | | EU | EUR | Bank | CREDITOR | FR28503399001212121212 | — | — | Valid (Partial Match) | | EU | EUR | Bank | CREDITOR | FR28503399001313131313 | — | — | Valid (No Match) | | EU | EUR | Bank | CREDITOR | FR28503399002222222222 | — | — | Invalid | - For EU corridors, we've used a **PL-based IBAN** (Poland) as a reference example. - To test other countries, replace the first **two letters of the IBAN** (e.g., `PL`) with the **ISO country code** of the EU country you want to test (e.g., `DE` for Germany, `FR` for France, `ES` for Spain). - The rest of the IBAN stays the same for testing purposes. ## Verify with proxy details These test values simulate proxy-based verification methods such as mobile number or email. | Country | Currency | Name | Proxy Type | Proxy Value | Status | | ------- | -------- | ------------- | ---------- | ----------------------- | --------------------- | | HK | HKD | NEW INDIA LTD | FPS ID | 0408922 | Valid (Match) | | HK | HKD | NEW INDIA LTD | MOBILE | +850-12345678 | Invalid | | IN | INR | Omi | VPA | omi1\@yesb | Valid (Match) | | IN | INR | Omi | VPA | omi2\@yesb | Valid (Partial Match) | | IN | INR | ABCD | VPA | omi001\@yesb | Invalid | | MY | MYR | Test Demo | NRIC | 1111 | Valid (Match) | | MY | MYR | Test Demo | NRIC | 1112 | Valid (Partial Match) | | MY | MYR | Test Demo | NRIC | 9999 | Invalid | | SG | SGD | Ranaditya | MOBILE | +6591234567 | Valid (Match) | | SG | SGD | Ranaditya | MOBILE | +6591234568 | Valid (Partial Match) | | SG | SGD | — | MOBILE | +6500000000 | Invalid | | AU | AUD | Layla Eade | EMAIL | | Valid | | AU | AUD | test | ABN | 22222222222 | Invalid | ## Testing name match Some corridors return a `nameMatch` field in the response detailing if the name provided matches the name registered with the bank. Use the test values in the tables above to trigger each possible outcome. ### Response values The `nameMatch` field in `derivedAccountDetails` returns one of the following values: | Value | Meaning | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `match` | The name provided exactly or closely matches the name registered at the bank. | | `partial_match` | The name partially matches — for example, a middle name is missing, initials differ, or there is a minor spelling variation. Review before proceeding. | | `no_match` | The name does not match the name registered at the bank. Do not proceed without manual review or updated account details. | ### Testing scenarios The tables above include a **Status** column that indicates the expected outcome. Use the provided account number for the scenario you want to test: - **Valid (Match)**: Use the account number from the Match row. The response returns `nameMatch: match`. - **Valid (Partial Match)**: Use the Partial Match account number. The response returns `nameMatch: partial_match`. - **Valid (No Match)**: Use the No Match account number. The response returns `nameMatch: no_match`. - **Invalid**: Use the Invalid account number. The request returns `status: invalid` with no nameMatch value. For corridors where name match is not supported, the `nameMatch` field is not returned in the response regardless of the account name provided. --- # Required Fields URL: https://docs.nium.com/docs/verify/mandatory-fields See which fields are required to verify bank account and proxy details in supported countries using Nium Verify. Use this guide to see which fields are required when verifying bank account or proxy details using **Nium Verify**. You'll also find what data is returned for each request and how the fields map to our API. For an overview of Nium Verify, see [Nium Verify](/docs/verify). ## Europe and United kingdom The table below lists required fields and expected response fields for each supported corridor. EU and UK - Required Fields | Country | Currency | Required Fields | Response Fields | | ------------------- | -------- | --------------------------------------- | -------------------------------------------------------- | | United Kingdom (GB) | GBP | Account Name, Account Number, Sort Code | Account Status, Account Holder Name\*, Name Match Status | | Austria (AT) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Belgium (BE) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Bulgaria (BG) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Croatia (HR) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Cyprus (CY) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Denmark (DK) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Estonia (EE) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Finland (FI) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | France (FR) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Germany (DE) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Greece (GR) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Ireland (IE) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Italy (IT) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Latvia (LV) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Lithuania (LT) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Luxembourg (LU) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Malta (MT) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Netherlands (NL) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Poland (PL) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Portugal (PT) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Slovakia (SK) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Slovenia (SI) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | | Spain (ES) | EUR | Account Name, Account Number (IBAN) | Account Status, Account Holder Name\*, Name Match Status | - The account holder’s name is returned only for strong or partial matches; the account name does not get returned for weak matches. ## APAC and MEA APAC and MEA - Required fields | Country | Currency | Required Fields | Response Fields | | ---------------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------ | | India (IN) | INR | Account Name, Account Number, IFSC Code | Account Status, Account Holder Name | | Malaysia (MY) | MYR | Account Name, Account Number, SWIFT Code | Account Status, Account Holder Name | | Indonesia (ID) | IDR | Account Name, Account Number, SWIFT Code | Account Status, Account Holder Name | | Thailand (TH) | THB | Account Name, Account Number, SWIFT Code | Account Status | | Vietnam (VN) | VND | Account Name, Account Number, SWIFT Code | Account Status, Account Holder Name | | South Korea (KR) | KRW | Account Name, Account Number, SWIFT Code | Account Status, Account Holder Name (EN + Local) | | Pakistan (PK) | PKR | Account Name, Account Number, SWIFT Code or Local Bank Code | Account Status, Account Holder Name, Name Match Status | | Nigeria (NG) | NGN | Account Name, Account Number, SWIFT Code | Account Status, Account Holder Name | | Tanzania (TZ) | TZS | Account Name, Account Number, SWIFT Code | Account Status, Account Holder Name | ## North America and LATAM North America and LATAM - Required Fields | Country | Currency | Required Fields | Response Fields | | ------------------ | -------- | -------------------------------------- | --------------------------------- | | United States (US) | USD | Account Name, Account Number, ACH Code | Account Status, Name Match Status | ## Country (proxy) Country - Proxy When using proxy-based identifiers (such as mobile number, VPA, or email), include the identifier type in `proxy.type` and the value in `proxy.value`. | Corridor | Currency | Required Fields | Response Fields | | -------------- | -------- | -------------------------------------------------------------- | ----------------------------------- | | Australia (AU) | AUD | Mobile, Email, ABN, Organization ID | Account Status, Account Holder Name | | Hong Kong (HK) | HKD | Mobile, Email, FPS ID | Account Status, Account Holder Name | | India (IN) | INR | VPA | Account Status, Account Holder Name | | Malaysia (MY) | MYR | Mobile, Passport, NRIC, Corporate Registration Number, Army ID | Account Status, Account Holder Name | | Singapore (SG) | SGD | Mobile, UEN, NRIC, VPA | Account Status, Account Holder Name | For proxy values, include the request parameter in `proxy.type` and the corresponding value in `proxy.value`. ### Field Definitions - Verification Type: - Bank: Verifies traditional bank account details. - Proxy: Verifies alternative identifiers such as mobile number or VPA. - Mandatory Fields: Fields you must provide for a successful verification. - Notes: Additional details or conditions that apply per country. ## Required Fields and API Fields This table shows how each required field maps to your API request or response: | Field | API Field | Example | Request/Response | | ------------------------------------ | ------------------------------------ | --------------------------- | ---------------- | | Account Name | `accountHolderName` | John Smith | Request | | Account Number | `bank.accountNumber` | 11111111 | Request | | Account Number (IBAN) | `bank.iban` | FR7630004028379876543210943 | Request | | SWIFT Code | `bank.routing.swift` | VTCBVNVX | Request | | Bank Code | `bank.bankCode` | HABB | Request | | ACH Number | `bank.routing.achCode` | 101000019 | Request | | Sort Code | `bank.account.sortCode` | 123456 | Request | | IFSC Code | `bank.account.ifsc` | HDFC0000522 | Request | | VAT Number | `bank.identification.registrationId` | FR12949982110 | Request | | Account Status | `status` | valid | Response | | Account Holder Name | `derivedAccountDetails.name` | John Smith | Response | | Name Match Status | `derivedAccountDetails.nameMatch` | match | Response | | Account Number Name (Local Language) | `derivedAccountDetails.nameLocal` | ジョン・スミス | Response | --- # Verify Error Codes URL: https://docs.nium.com/docs/verify/error-code See all error scenarios that you can receive from Nium Verify while verifying bank account and proxy details in supported countries. The following details all the possible values that can be returned in the `status` and `failureCode` fields, when [verifying a bank account](/api#tag/nium-verify/POST/api/v1/client/{clientHashId}/verifications) and what steps to take based on the returned value. When you [verify a bank account](/api#tag/nium-verify/POST/api/v1/client/{clientHashId}/verifications), the response details the result of the verification check: ```json { "id": "6a497525-b8b8-45a7-a2fe-6937907c8179", "accountHolderName": "JOHN SMITH", "currency": "GBP", "country": "GB", "externalId": "4438e362-c6ec-4b48-8883-133d9dc575cc", "status": "invalid", "failureCode": "inactive_account", "date": "2025-05-21T07:55:13.010Z" } ``` For most requests, `status` returns: | Status | Description | Recommended action | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`valid`** | The account exists and the verification was successful. Responses with this status can include `derivedAccountDetails` providing the account holder's name. | You can resume with your workflow. | | **`invalid`** | Details can't be validated. | Review and confirm the provided account details and resubmit the request.If the account details are accurate and returns **invalid**, see the `failureCode` field to understand why verification failed.. | ## Specific failure codes When the `status` of the response is **invalid**, the `failureCode` field returns a more granular reason for the failure. Available failure codes include: | Failure code | Description | Recommended action | | ----------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **`invalid_name`** | The provided `accountHolderName` does not match the name associated with the account. | Provide this information to your customer and ask them to verify their information and resubmit as needed. | | **`inactive_account`** | The bank account associated with the provided details is currently inactive. | Provide this information to your customer and ask them to check with their bank or submit details for an active bank account. | | **`account_not_found`** | The bank account associated with the provided details could not be located. | Provide this information to your customer and ask them to check with their bank for the correct details. | ## General error codes In addition to verification statuses, Nium Verify requests return standard HTTP status codes for general API errors: Error are returned in the following structure: ```json { "errors": [ { "code": "invalid_verification_id", "description": "invalid verification id" } ] } ``` These codes help identify problems with the request itself or the service availability. The specific error codes are as follows: | **HTTP Status Code** | **Error Code** | **Error Description** | **Recommended Action** | | -------------------- | ------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **400** | **invalid\_request** | The request payload is malformed or contains invalid fields. | Review the `field` and `description` fields in the response and correct the request format. | | **403** | **Forbidden** | The client ID or API key is invalid. | Verify that your `clientId` and API key are correct in the [Nium Portal](https://app.nium.com). | | **403** | **invalid\_client** | Your client ID is not enabled for Nium Verify. | Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to request access. | | **404** | **invalid\_verification\_id** | The `verificationId` does not match any existing record. | Confirm that the `verificationId` in your request is valid. | | **422** | **bank\_code\_not\_supported** | The selected bank is not supported for real-time verification. | This bank may not be part of Nium’s verification network. Contact your Nium account manager or [Nium Support](mailto:support@nium.com) for supported banks. | | **422** | **country\_currency\_not\_supported** | The country and currency combination is not supported for verification. | See the [supported corridors](/docs/verify#supported-corridors-and-account-holder-name-availability) and use a valid combination. | | **500** | **internal\_error** | A server-side error occurred. | Retry the request. If the issue persists, contact your Nium account manager or [Nium Support](mailto:support@nium.com). | --- # Foreign Exchange URL: https://docs.nium.com/docs/foreign-exchange Nium's Foreign Exchange (FX) service helps you convert your funds from any of the Nium Payin currencies into any of t≈he Nium Payout currencies at transparent and guaranteed FX rates. The converted funds can then be used to send payouts or spend through a card. Before diving into the details of the FX service and the API endpoints, it's important to understand the main aspects of any FX conversion. ## Rate The FX rate for a given currency pair is the rate at which banks trade that currency pair in the interbank currency market. Nium provides these rates to you for informational purposes, for example, if you want to track general market trends. Nium retrieves FX rates for all supported currency pairs every five minutes. We also offer the ability for you to transparently track the historical minimum, maximum, and average FX rates for a currency pair within hourly or daily intervals. ### Off-Market Rates Some quotes and conversion requests made outside of normal business hours can trigger *Off-market rates*. This includes: - Requests made outside the normal operating hours for the markets involved. - Weekends - Holidays These off-market requests return a `isOffMarket` field in the response of our `Quotes` and `Conversions` endpoints. Specifically, the `isOffMarket` field can be found in the response of the following requests: - [Create Quote](/api#tag/quotes/POST/api/v1/client/{clientHashId}/quotes) - [Fetch Quote by ID](/api#tag/quotes/GET/api/v1/client/{clientHashId}/quotes/{quoteId}) - [Create Conversion](/api#tag/conversions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions) - [Fetch Conversion By Id](/api#tag/conversions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions/{conversionId}) The `isOffMarket` field returns **true** if an off-market fee has been applied. Off-market requests are enabled if discussed with your Nium Account manager during onboarding - this field isn't returned unless off-market requests have been enabled by Nium. Note: Off-market rates only apply to: - `Quotes` with 5-minute lock periods - Immediate `Conversions` If you have any questions on what qualifies as off-market, please contact your Nium Account Manager or [Nium Support](mailto:support@nium.com) for more information. ## Quote An FX quote is an offer Nium makes to convert money across two currencies at a locked FX rate within a limited time frame. The quote is generated by taking the latest interbank FX rate for the two currencies and adding a previously agreed markup to it. On holidays, Nium uses the last traded interbank FX rate from the previous close-of-business day as the baseline. An example would be a Friday closing rate, which becomes the quote generated on a Sunday after adding the Nium markup. ## Lock Periods All FX quotes can be locked for a period of time to allow you time to show the locked rate to your users (internal or external) and make a decision about making an FX conversion at that locked rate. We support different lock periods ranging from 5 minutes to 24 hours, and you can choose to select the required lock period every time you get a quote from Nium using the FX Quote API. The lock periods supported are as below. - 5 minutes (default) - 15 minutes - 1 hour - 4 hours - 8 hours - 24 hours The longer the rate lock period, the higher is the Nium markup. When you get an FX quote, you also need to separately select a conversion schedule, which identifies the time you will need to settle the FX conversion. This is explained in the sections below. ## Conversion Nium performs an FX conversion when funds are converted from the funding source currency to the destination currency in a customer's wallet. FX conversions can be performed using either locked or market FX rates. Clients can use these converted funds to make payouts to external bank accounts depending on their business needs. For example, a payroll provider in the US can pay their employees in Canada by converting their USD funds into CAD ahead of the payroll schedule. The US payroll provider can then make payouts to their Canadian employees from their CAD balance on the payroll date. Clients can also execute scheduled FX conversions manually. Using manually scheduled FX conversions, clients can transfer funds from a source currency to a destination currency based on their settlement schedule needs. Manual conversions add more flexibility compared to timed conversions, which get executed at the [settlement cut-off time](/docs/foreign-exchange#settlement-cut-off-time). At the same time, in the same payroll example, clients can also control the timing of an FX conversion and when the conversion from USD to CAD is executed based on the funds arriving in their wallet. Please note manual FX conversions only apply when the settlement schedule is not `immediate`. ### Timed Conversions By default, FX conversions are configured to execute at the `conversionTime`. The `conversionTime` is calculated based on the [settlement cut-off time](/docs/foreign-exchange#settlement-cut-off-time). The `conversionTime` defines the time funds in the customer's wallet get converted from the source currency to the destination currency. This is helpful in instances where your internal workflow supports the automated processing of FX conversions at a predetermined schedule. ### Manual Conversions You can also manually execute FX conversions to control the timing of FX conversions to be settled in wallet. This is valuable in case of additional control of funds in wallet, where only the intended “source” funds are converted, and also the timing of conversions. Use `executionType#manual` to execute an FX conversion; once executed, the `conversion#status` updates from `created` to `processing`. For more information, see [Execute Conversion](/api#tag/conversions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions/{conversionId}/execute). ### Conversions During Payouts Nium can also perform an FX conversion during an individual payout, either using a locked or the market FX rate. You can instruct Nium to deduct funds from the wallet in the source currency and send the payout in the destination currency to your beneficiary’s account through Nium's payout network. The locked FX rate functionality for payouts is supported through the [Exchange Rate Lock And Hold](/api#tag/quotes-previous-version/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/lockExchangeRate) request. See the [Transfer Money - Audit ID](/docs/payouts#audit-id) guide for more information. ### Conversion Schedule You can select the preferred conversion schedule from the list below. This determines the time Nium waits to settle the conversion. **Immediate:** An immediate conversion schedule is settled instantly using the available balance in the customer's wallet. This can be done 24 hours a day, seven days a week, regardless of whether it's a working day or not. **endOfDay:** An end-of-day conversion schedule is settled at the end of the present day, regardless of whether the present day is a holiday or not. This is a slight variation from an immediate conversion schedule. It gives you some time to fund the source account. **nextDay:** A next-day conversion schedule is settled one business day later. This excludes holidays in the country of either the source currency, the destination currency, or the Nium regulatory region where you have been onboarded. For example, if a next-day FX conversion is initiated on a Monday for USD-GBP, and Tuesday is a holiday in the UK, and Wednesday is a holiday in the US, the FX conversion settles on Thursday, which is the next business day for the given currency pair. In this case, it doesn't matter whether Monday itself is a holiday or not in any of the zones. **twoDays:** A two-day conversion schedule is similar to a next-day conversion schedule, except that it settles two business days later, excluding holidays. Based on the conversion schedule, Nium calculates the conversion time and provides it in the response to the conversion creation request, so you know exactly how much time you have to fund the source account. ### Conversion Lifecycle FX conversions have the following states. | State | Description | | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------- | | Created | All conversions are initially in this state after you've initiated them. All conversions in this state can be canceled through the API. | | Processing | At the scheduled time, conversions briefly go into this state while Nium settles them. | | Completed | When conversions are successfully settled, and the wallet balances are updated, the conversions go into this state. | | Cancelled | When conversions are canceled, either by Nium or by you, they go into the canceled state. | See the following diagram for an overview of the states an FX conversion typically goes through. OOB-2 ## Settlement All FX conversions need to be settled when the source funds are available. This is the last step in the FX conversion process. Nium performs the conversion and updates the balances in the customer's wallet. ### Immediate Settlement If you already have the source funds in the customer's wallet, then FX conversions can be settled immediately using the pre-funded balance. Such conversions are done at any time, 24 hours a day, seven days a week, on demand. These are usually done using a market FX rate. Prefunded balance ### Scheduled Settlement If you want to fund the source amount in the customer's wallet after first getting a locked FX rate, then it's possible to settle FX conversions later on a scheduled date. This gives time to deposit the source funds into the customer's wallet. You need to first get an FX quote for the specific conversion schedule. The times are the end of the day, the next business day, or two business days. This is necessary to allow you time to deposit the source funds. This depends on the funding method such as Direct Debit from your external account, a wire transfer to a Nium virtual account, or an Automated Clearing House (ACH) credit to a Nium virtual account. Scheduled Conversion ## Settlement Cut-Off Time The settlement is done on the scheduled date—calculated according to the conversion schedule—at a specific cut-off time that's based on the Nium regulatory region that you have been onboarded with. This gives you until the end of the business day to fund the source funds. | Location — a regulatory region associated with the client | Time zone | Settlement cutoff — local time | | :-------------------------------------------------------- | :-------- | :----------------------------- | | Nium US | UTC-8 | 5 PM | | Nium HK | UTC+8 | 5 PM | | Nium SG | UTC+8 | 5 PM | | Nium EU | UTC+1 | 5 PM | | Nium AU | UTC+11 | 5 PM | | Nium UK | UTC+1 | 5 PM | ## Key Features To summarize, here are the key features of Nium's FX service: - **Transparency**: Nium bases all of its FX quotes on the live interbank FX rate and adds a transparent mutually agreed-upon FX markup. - **24 hours a day, seven days a week availability**: Nium's FX service is available daily around the clock with no downtime on bank holidays or weekends. - **Flexibility**: You can choose to convert and hold currencies within your wallet to enable payouts or card spending, or perform conversion across currencies dynamically as a part of the individual payout or card spend transaction. - **Locked rates**: Get locked FX rates to give your customers time to review and confirm the rate. - **Multiple settlement options**: Choose between converting funds in real-time using pre-funded balances, or converting on a future scheduled date, at a locked FX rate. This helps you know the exact source amount to fund and get the time to send the funds. ## Prerequisites These are the requirements for using the FX service: - Create a corporate customer and a multicurrency wallet for yourself, if you're a direct client, or for each one of your customers, if you're a platform. - Set up the wallets to support the required currencies. - Work with your account representative to ensure that your account is setup with the agreed FX markups for the lock periods and conversion schedules that you need to support for your business model. ## Availability The Nium FX service is available to clients onboarded with the following Nium locations. | Nium locations | Support | Source currencies | Destination currencies | | -------------- | ------- | :---------------------------------------------------------------------------------- | :--------------------- | | US | Yes | All payin currencies supported for your account, as supported in this Nium location | All payout currencies | | UK | Yes | All payin currencies supported for your account, as supported in this Nium location | All payout currencies | | EU | Yes | All payin currencies supported for your account, as supported in this Nium location | All payout currencies | | AU | Yes | All payin currencies supported for your account, as supported in this Nium location | All payout currencies | | SG | Yes | All payin currencies supported for your account, as supported in this Nium location | All payout currencies | | HK | Yes | All payin currencies supported for your account, as supported in this Nium location | All payout currencies | ## API Server URLs Use the following URLs to separate API calls between different environments. - Sandbox: `https://gateway.nium.com` - Production: `https://api.spend.nium.com` ## FX API Endpoints **FX rate:** | HTTP method | API name | Action | | :---------- | :----------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | [Exchange Rate V2](/api#tag/rates/GET/api/v2/exchangeRate) | This API fetches the interbank FX rate between a pair of currencies. This *does not* include the Nium markup. | | GET | [Aggregated Exchange Rates](/api#tag/rates/GET/api/v1/exchangeRates/aggregate) | This API fetches the historic interbank FX rates between a pair of currencies, for a specified date range within the last ninety days. This is set to provide daily aggregated interbank FX rates as the default, but can also be set to provide hourly aggregated data. | **FX quotes:** | HTTP method | API name | Action | | :---------- | :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Create Quote](/api#tag/quotes/POST/api/v1/client/{clientHashId}/quotes) | This API creates an FX quote for a pair of currencies based on your desired lock period and conversion schedule. The FX rate provided in this API includes the Nium markup and it can be used in any FX conversion within the quote's validity period. | | GET | [Fetch Quote by ID](/api#tag/quotes/GET/api/v1/client/{clientHashId}/quotes/{quoteId}) | This API fetches the details of an FX quote using the `quoteId` returned when the FX quote is created. | The [Create Quote](/api#tag/quotes/POST/api/v1/client/{clientHashId}/quotes) API is only enabled for FX conversions within a customer's wallet. In the near future, the same API is planned to also support quotes for payouts. Until then, use the [Exchange Rate Lock And Hold](/api#tag/quotes-previous-version/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/lockExchangeRate) request to lock FX rates for payouts. **FX Conversions:** | HTTP method | API name | Action | | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | [Create Conversion](/api#tag/conversions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions) | This API converts funds within a customer's wallet from a source currency to a destination currency at either a market FX rate or a locked FX rate obtained using the FX Quote API. | | GET | [Fetch Conversion by ID](/api#tag/conversions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions/{conversionId}) | This API fetches the details of an FX conversion using the `conversionId` returned when the FX conversion was created. | | POST | [Cancel Conversion](/api#tag/conversions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions/{conversionId}/cancel) | This API cancels an FX conversion that's in the `created` state and is yet to be settled. | | POST | [Execute Conversion](/api#tag/conversions/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions/{conversionId}/execute) | This API executes an FX conversion and updates the state to `processing`. | ## Related Guides See the following for more details on settling FX conversions: - [Immediately using Market Rates](/docs/foreign-exchange/market-rate) - [Immediately using Locked Rates](/docs/foreign-exchange/locked-rate) - [Scheduling FX conversions for a later settlement](/docs/foreign-exchange/scheduled) - [Canceling a scheduled FX conversion before settlement](/docs/foreign-exchange/cancelled) --- # Market Rate URL: https://docs.nium.com/docs/foreign-exchange/market-rate If you already have the required source amount in the customer wallet and you want to convert to the destination currency at the live market FX rate, follow these steps: Market Rate ## Step 1: Initiate the conversion Once you have confirmed that the customer wallet has sufficient funds in the source currency, you can initiate the conversion by providing the `sourceCurrencyCode`, `destinationCurrencyCode` and either the `sourceAmount` or the `destinationAmount` as below: ```bash curl -X POST "https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "sourceCurrencyCode": "USD", "destinationCurrencyCode": "AUD", "sourceAmount": 100, "customerComments": "Transfering for AUD payroll" }' ``` ## Step 2: Get the response Nium internally calculates the FX rate for an `immediate` conversion schedule for the currency pair and uses this rate to calculate the `destinationAmount` or `sourceAmount` and return the response with the status as `created`. The response also includes the `netExchangeRate`, which is the rate used to perform the FX conversion. This is calculated by getting the latest interbank rate for that currency pair—`exchangeRate`—and reducing the total markup rate—`markupRate`—that has been configured for your account for the combination of the currency pair, lock period, and conversion schedule. ```json { "id": "conversion_46nn6y8gDX2Os6DHjlHdke", "status": "processing", "conversionTime": "2023-06-15 06:43:15", "sourceCurrencyCode": "USD", "destinationCurrencyCode": "AUD", "sourceAmount": 100, "destinationAmount": 145.83, "quoteId": "quote_6ghWKO8SV8gBC9rQvsHOLi", "netExchangeRate": 1.458319800, "exchangeRate": 1.468600000, "markupRate": 0.010280200, "destinationMarkupAmount": 1.03, "systemReferenceNumber": "WFT1180326200", "customerComments": "Transfering for AUD payroll", "createdTime": "2023-06-15 06:43:16", "updatedTime": "2023-06-15 06:43:16" } ``` ## Step 3: Get the conversion settlement notification Since this is a conversion that's settled immediately using the available balance, the balances in the wallet are updated and you immediately receive a webhook notification that shows the new status as `completed`. ```json { "customerHashId":"e9f74ac0-8fc5-4879-8ace-6ca2084ba250", "template":"FX_CONVERSION_COMPLETED_WEBHOOK", "systemReferenceNumber":"WFT1180326200", "walletHashId":"ebc26772-2d3e-4ab0-916a-3a7706a0c358", "conversionId":"conversion_46nn6y8gDX2Os6DHjlHdke", "clientHashId":"8bf73eb1-99e7-4a76-8ef2-cdeac938593a", "status":"completed" } ``` --- # Locked Rate URL: https://docs.nium.com/docs/foreign-exchange/locked-rate If you want to get a confirmation from your customer or an internal user for the FX rate before you complete the FX conversion using available funds in the customer wallet, you can first get the FX quote and then initiate the conversion using that quote as below: Locked Rate ## Step 1: Get an FX quote Get an FX quote with the `lockPeriod` required to confirm the conversion with your customer or user and the `conversionSchedule` as `immediate` and `quoteType` as `balanceTransfer`. ```bash curl -X POST "https://gateway.nium.com/api/v1/client/{clientHashId}/quotes" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "sourceCurrencyCode": "USD", "destinationCurrencyCode": "AUD", "conversionSchedule": "immediate", "lockPeriod": "8hours", "quoteType": "balanceTransfer", }' ``` In response, you get an FX quote with the `netExchangeRate` as the quoted exchange rate. This is calculated by getting the latest interbank rate for that currency pair—`exchangeRate`—and reducing the total `markupRate` that's configured for your account for the combination of the currency pair, lock period, and conversion schedule. ```json { "id": "quote_4VmJfRsR2ZMKbJKf4Po1CX", "netExchangeRate": 1.447457500, "expiryTime": "2023-06-15 14:47:38", "sourceCurrencyCode": "USD", "destinationCurrencyCode": "AUD", "quoteType": "balanceTransfer", "conversionSchedule": "immediate", "lockPeriod": "8hours", "exchangeRate": 1.469500000, "markupRate": 0.022042500, "sourceAmount": null, "destinationAmount": null, "destinationMarkupAmount": null, "createdTime": "2023-06-15 06:47:38" } ``` ## Step 2: Create the conversion Once you get the quote, create the conversion as follows before the `expiryTime`. Send the `quoteId` obtained in the above API and one of the `destinationAmount` or `sourceAmount` depending on which side you want to be fixed. Nium calculates the other amount using the quoted FX rate. ```bash curl -X POST "https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "quoteId": "quote_4VmJfRsR2ZMKbJKf4Po1CX" "sourceAmount": "100", "comments": "Converting for AUD payroll" }' ``` ## Step 3: Get the response You get an initial response that shows the calculated `destinationAmount` or `sourceAmount` and the status as `created`. ```json { "id": "conversion_3YJoJvSsvPFZqlwsLhnnSc", "status": "processing", "conversionTime": "2023-06-15 06:48:56", "sourceCurrencyCode": "USD", "destinationCurrencyCode": "AUD", "sourceAmount": 100, "destinationAmount": 144.75, "quoteId": "quote_4VmJfRsR2ZMKbJKf4Po1CX", "netExchangeRate": 1.447457500, "exchangeRate": 1.469500000, "markupRate": 0.022042500, "destinationMarkupAmount": 2.2, "systemReferenceNumber": "WFT1968043576", "customerComments": "Transfering for AUD payroll", "createdTime": "2023-06-15 06:48:56", "updatedTime": "2023-06-15 06:48:56" } ``` ## Step 4: Get the notification when the conversion is settled Since this is a conversion that's settled immediately using the available balance, the balances in the wallet are updated and you immediately receive a webhook notification that shows the new status as `completed`. ```json { "customerHashId":"e9f74ac0-8fc5-4879-8ace-6ca2084ba250", "template":"FX_CONVERSION_COMPLETED_WEBHOOK", "systemReferenceNumber":"WFT1968043576", "walletHashId":"ebc26772-2d3e-4ab0-916a-3a7706a0c358", "conversionId":"conversion_3YJoJvSsvPFZqlwsLhnnSc", "clientHashId":"8bf73eb1-99e7-4a76-8ef2-cdeac938593a", "status":"completed" } ``` --- # Scheduled Rate URL: https://docs.nium.com/docs/foreign-exchange/scheduled In scenarios where you prefer to fund the FX conversion later and want to know the amount to be funded upfront, you can get a locked FX rate using the desired lockPeriod and conversionSchedule. Using this locked FX rate, you can calculate the source amount that's needed to fund into your customer’s wallet. In scenarios where you prefer to fund the FX conversion later and want to know the amount to be funded upfront, you can get a locked FX rate using the desired `lockPeriod` and `conversionSchedule`. Using this locked FX rate, you can calculate the source amount that's needed to fund into your customer’s wallet. Scheduled Rate ## Step 1: Get an FX quote Get an FX quote with `quoteType` as `balanceTransfer`, the desired `lockPeriod` required to confirm the conversion with your customer or user and the `conversionSchedule` as one of `endOfDay`, `nextDay`, or `twoDays`, depending on how long it takes for your wallet to be funded with the source currency. ```bash curl -X POST "https://gateway.nium.com/api/v1/client/{clientHashId}/quotes" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "sourceCurrencyCode": "USD", "destinationCurrencyCode": "AUD", "conversionSchedule": "2Days", "lockPeriod": "8hours", "quoteType": "balanceTransfer" }' ``` In response, you get an FX quote with the `netExchangeRate` as the quoted exchange rate. This is calculated by getting the latest interbank rate for that currency pair—`exchangeRate`—and reducing the total `markupRate` that's configured for your account for the combination of the currency pair, lock period, and conversion schedule. ```json { "id": "quote_1GYLNle0hw37IkPDAuwOFQ", "netExchangeRate": 1.437366600, "expiryTime": "2023-06-15 14:52:54", "sourceCurrencyCode": "USD", "destinationCurrencyCode": "AUD", "quoteType": "balanceTransfer", "conversionSchedule": "2Days", "lockPeriod": "8hours", "exchangeRate": 1.469700000, "markupRate": 0.032333400, "sourceAmount": null, "destinationAmount": null, "destinationMarkupAmount": null, "createdTime": "2023-06-15 06:52:54" } ``` ## Step 2: Initiate the conversion Once you get the quote, you can create the conversion as follows within the `expiryTime`. Send the `quoteId` you received in the above API and either the `destinationAmount` or `sourceAmount` depending on which one you want to be fixed. Nium calculates the other amount using the quoted FX rate. ```bash curl -X POST "https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "quoteId": "quote_1GYLNle0hw37IkPDAuwOFQ" "sourceAmount": "100", "comments": "Converting for AUD payroll" }' ``` ## Step 3: Get the response Get an initial response that shows the calculated `destinationAmount` or `sourceAmount`, the calculated `conversionTime`, and the `status` as `created`. ```json { "id": "conversion_1xVFhcSSdFLAyoKb9bKofR", "status": "created", "conversionTime": "2023-06-21 01:00:00", "sourceCurrencyCode": "USD", "destinationCurrencyCode": "AUD", "sourceAmount": 100, "destinationAmount": 143.74, "quoteId": "quote_1GYLNle0hw37IkPDAuwOFQ", "netExchangeRate": 1.437366600, "exchangeRate": 1.469700000, "markupRate": 0.032333400, "destinationMarkupAmount": 3.23, "systemReferenceNumber": "WFT3169755752", "customerComments": "Converting for AUD payroll", "createdTime": "2023-06-15 06:53:32", "updatedTime": "2023-06-15 06:53:32" } ``` ## Step 4: Fund the conversion You need to fund the source amount into the customer's wallet before the `conversionTime`. Become familiar with the time it takes for funds to be available in the customer wallet. Nium can only complete an FX conversion when the funds are available. This includes the time it takes for the bank to settle the funds to Nium and any risk hold period set up for your account. Refer to the [Fund Wallet](/docs/payins/fund-wallet) guide to learn about funding methods and the time it takes for funds to be available. ## Step 5: Get the conversion settlement notification Nium converts the funds in your wallet at the settlement cut-off time according to the local time in the Nium entity that you have been onboarded for. Once Nium completes the conversion, you receive a webhook notification that shows the status as `completed`. ```json { "customerHashId":"e9f74ac0-8fc5-4879-8ace-6ca2084ba250", "template":"FX_CONVERSION_COMPLETED_WEBHOOK", "systemReferenceNumber":"WFT3169755752", "walletHashId":"ebc26772-2d3e-4ab0-916a-3a7706a0c358", "conversionId":"conversion_1xVFhcSSdFLAyoKb9bKofR", "clientHashId":"8bf73eb1-99e7-4a76-8ef2-cdeac938593a", "status":"completed" } ``` ## Step 6: Handle a cancellation scenario Alternatively, in case the funds *are not* in the customer's wallet at the `conversionTime`, Nium cancels the conversion and deducts the cancellation fee in the source currency from the wallet. See [Scheduled FX conversion cancelled before settlement](#step-6-handle-a-cancellation-scenario) guide to understand how the cancellation fee is calculated. You get the following webhook notification that shows the new status of the transfer as `cancelled`. The `cancellationReason` is always `insufficient_funds` in this scenario. ```json { "customerHashId": "e9f74ac0-8fc5-4879-8ace-6ca2084ba250", "template": "FX_CONVERSION_CANCELLED_WEBHOOK", "cancellationFeeCurrencyCode": "USD", "cancellationReason": "insufficient_fund", "systemReferenceNumber": "7526349341F", "cancellationComment": "Insufficient Funds", "cancellationFee": 5.82, "walletHashId": "ebc26772-2d3e-4ab0-916a-3a7706a0c358", "conversionId": "conversion_1xVFhcSSdFLAyoKb9bKofR", "clientHashId": "8bf73eb1-99e7-4a76-8ef2-cdeac938593a", "status": "cancelled" } ``` --- # Cancelled Conversion URL: https://docs.nium.com/docs/foreign-exchange/cancelled In case you need to cancel a scheduled conversion at any point before the conversion is settled, you can do it as long as your account is set up for it. This is applicable for conversions that are in the created state. In case you need to cancel a scheduled conversion at any point before the conversion is settled, you can do it as long as your account is set up for it. This is applicable for conversions that are in the `created` state. Cancelled Rate ## Step 1: Request a cancellation of a scheduled conversion You can cancel a conversion scheduled for a future time if your account is set up for it. You can cancel a conversion that's in a `created` state as shown in the code example below. ```bash curl -X POST "https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions/{conversionId}/cancel" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "cancellationComments": "Cancelled due to payroll problem" }' ``` ## Step 2: Get the response Nium checks if the conversion is in the `created` state. If it is, Nium calculates the applicable `cancellationFee` by reversing the currencies and converting the original `destinationAmount` to a new `sourceAmount` at either the reverse rate as the original conversion or the market FX rate, whichever is lower. An additional cancellation markup is also deducted from this new `sourceAmount`, as agreed in your contract. The `cancellationFee` is the difference between the old `sourceAmount` and the new `sourceAmount`, and it's deducted from the wallet balance. The conversion status is changed to `pending_cancellation`. The conversion resource `id ` and the status are returned, along with the cancellation details shown in the code example below. ```json { "id": "conversion_7ANTNDEVTHwJS1eivXRdjJ", "status": "pending_cancellation", "systemReferenceNumber": "WFT7448284874", "cancellationFee": 5.86, "cancellationFeeCurrencyCode": "USD", "cancellationComment": "Cancelled due to payroll problem", "cancellationFeeSystemReferenceNumber": "3039391046F", "cancellationReason": "user_cancel" } ``` ## Step 3: Get the conversion cancellation notification Once Nium deducts the `cancellationFee` from the wallet balance and marks the conversion as `cancelled`, you see a notification that shows the status as `cancelled`. ```json { "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "conversionId":"conversion_7ANTNDEVTHwJS1eivXRdjJ", "status":"cancelled", "systemReferenceNumber":"WFT7448284874", "cancellationFee": 5.86, "cancellationFeeCurrencyCode": "USD", "cancellationComment": "Cancelled due to payroll problem", "cancellationReason": user_cancel, "template":"FX_CONVERSION_CANCELLED_WEBHOOK" } ``` --- # Transactions URL: https://docs.nium.com/docs/transactions A transaction, in the Nium One platform, is a record of a debit or credit event that impacts the wallet balance. The platform supports a number of transaction types. ## Cards Refer to the [Card transactions](/docs/cards/card-transactions) guide to learn more about transaction types and examples.\ See [Client transactions](/docs/reports/client-reports/client-transactions) to learn more about client transactions and examples. ## Payout | Type | Description | | --------------------------- | -------------------------------------------------------------- | | `Remittance_Debit` | The debit from the wallet for remittance to one's own account. | | `Remittance_Debit_External` | The debit from the wallet for remittance to another account. | | `Remittance_Reversal` | The reversal of a remittance transaction. | ## Payin | Type | Description | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `Wallet_Credit_Mode_Card` | The fund credit to a wallet using a card. | | `Wallet_Credit_Mode_Prefund` | The fund credit to a wallet using a client prefund. | | `Wallet_Credit_Mode_Prefund_Cross_Currency` | The cross-currency fund credit to a wallet using a client prefund. | | `Wallet_Credit_Mode_Offline` | The fund credit to a wallet using an offline mode, such as a bank transfer, from the customer’s own account. | | `Wallet_Credit_Mode_Offline_Cross_Currency` | The cross-currency fund credit to a wallet using an offline mode, such as a bank transfer, from the customer’s own account. | | `Wallet_Credit_Mode_Offline_ThirdParty` | The fund credit to a wallet, in the same currency, using an offline mode, such as a bank transfer from a third party. | | `Wallet_Credit_Mode_Direct_Debit` | The fund credit to a wallet, using Direct Debit, by pulling funds from the customer's verified and linked external bank account | | `Wallet_Credit_Mode_Direct_Debit_Reversal` | Reversal of credited Direct Debit funds, from wallet to customer's verified and linked external bank account | ## Foreign exchange (FX) conversion When the balance transfer within the wallet API is triggered, the system creates one record and captures the details about the from-account or the to-amount. | Type | Description | | ---------------------- | --------------------------------------------------------------------- | | `Wallet_Fund_Transfer` | The fund transfer within a wallet, from one currency pool to another. | ## Wallet to wallet transfers When a wallet to wallet transfer is executed using the Fund Transfer API, the system creates two records. - Debit in the sender's wallet - Credit in the receiver's wallet | Type | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `Customer_Wallet_Credit_Fund_Transfer` | The funds received in the wallet from another customer’s wallet of the same client. | | `Customer_Wallet_Debit_Fund_Transfer` | The funds sent from a wallet to another customer’s wallet of the same client. | | `Customer_Wallet_Debit_Intra_Region` | The funds sent from a wallet to another customer’s wallet of a different client but of the same regulatory region. | | `Customer_Wallet_Credit_Intra_Region` | The funds received from a wallet to another customer’s wallet of a different client but of the same regulatory region. | | `Customer_Wallet_Debit_Cross_Region` | The funds sent from a wallet to another customer’s wallet of a different client and of a different regulatory region. | | `Customer_Wallet_Credit_Cross_Region` | The funds received from a wallet to another customer’s wallet of a different client and of a different regulatory region. | ## Client funding | Type | Description | | ---------------- | ------------------------------------------------------------------------- | | `Client_Prefund` | The credit to the client-pool balance. | | `Client_Refund` | The deduction from the client-pool balance which transfers to the client. | | `Wallet_Refund` | The refund money from the wallet back to the client. | ## Fees | Type | Description | | -------------- | ------------------------------------------ | | `Fee_Debit` | The fee that's deducted for a transaction. | | `Fee_Reversal` | The reversal of a fee debit transaction. | | `Fee_Waiver` | The fee that's waived for a transaction. | ## Open banking | Type | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------- | | `Transfer_Local` | The local payments are debited from the wallet through the Payment Initiation Service (PIS) open banking. | | `Transfer_Local_Reversal` | The local payments are credited or reversed from the wallet through the PIS open banking. | ## PLAIS (EU) | Type | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Regulator_Auto_Sweep` | For European Economic Area (EEA) regulatory requirements, this transaction includes the amount moved from any other currency to the European Monetary Unit (EUR). This is the requested block currency by the regulator, in case of a block instruction. In addition, this is valid if there's insufficient balance in EUR for blocking. | | `Regulatory_Block` | For EEA regulatory requirements, this transaction includes the amount moved to the blocked amount from EUR. This is the requested block currency by the regulator, in case of a block instruction. | | `Regulatory_Debit` | For EEA regulatory requirements, this transaction includes the amount debited from the block amount or wallet balance of EUR. This is the requested block currency by the regulator. This is valid when the regulator asks to send the blocked amount to a beneficiary. | | `Regulatory_Debit_Reversal` | For EEA regulatory requirements, this transaction includes the amount returned in case of a `failed Regulatory_Debit` remittance. | ## Examples ### Payout transactions | Scenario | Transaction record created by the platform | | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The account holder submits a payout instruction. | The Nium One platform validates and processes the payout instruction. If the instruction can be accepted for processing, the platform creates a `Remittance_Debit`, if `purposeCode` is a transfer-to-own account. The platform can also create a `Remittance_Debit_External`, if the `purposeCode` isn't a transfer-to-own account transaction. If fees are configured and can be applied, the -latform also creates the necessary `Fee_Debit` transaction. | | The payout instruction is returned. This could be for various reasons, including rejected or returned-by-the- beneficiary's bank. | The platform creates a new transaction such as a `Remittance_Reversal` record or a credit record with the settlement status set to `Released`. The original remittance transaction record, `Remittance_Debit or Remittance_Debit_External, is retained, and the settlement status, in the original transaction, is set to `Released\`. | ### Payin transactions | Scenario | Transaction record created by the platform | | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | When the account holder receives money using a Virtual Account Number (VAN) assigned to the account holder's wallet | The platform creates a `Wallet_Credit_Mode_Offline` transaction record, where the account holder is the sender and the platform is able to match or a `Wallet_Credit_Mode_Offline_ThirdParty` transaction record, where the sender isn't the account holder or the platform is unable to match. If fees are configured and can be applied, the platform also creates the `necessary Fee_Debit` transaction. | ## Non-card transaction types **P2P transfers:** When a P2P transfer is executed, using the P2P Transfer API, the system creates two records, one for the debit leg and one for the credit leg: - A `Customer_Wallet_Debit_Fund_Transfer` transaction record is created in the sender’s wallet. - A `Customer_Wallet_Credit_Fund_Transfer` transaction record is created in the receiver’s wallet. **Currency exchange within wallet:** When the balance transfer within the wallet API is triggered, the system creates one record and captures the details about the from-to account or the to-amount. - A `Wallet_Fund_Transfer` transaction record is created in the account holder’s wallet. **Payout, remittance, transfer money:** When a transfer operation is executed using the Transfer Money API. - The system creates either a `Remittance_Debit or Remittance_Debit_External` transaction record. The system also creates a `Fee_Debit` transaction record, if any fee is applicable for processing the remittance transaction. These transactions have debit impacts on the account holder’s wallet. **Pay in, Receive, Collect:** When the account holder receives money using a VAN assigned to the account holder's wallet. - The system creates a `Wallet_Credit_Mode_Offline` transaction record. The account holder is the sender and the system matches. The `Wallet_Credit_Mode_Offline_ThirdParty` transaction record is where the sender isn't the account holder or the system is unable to match. **Moving funds between the client prefund and the account holder’s wallet and vice versa** - When, by using the [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund) API fundingchannel prefund, the funds are moved from the client-prefund account to the account holder’s wallet. The system then creates a `Wallet_Credit_Mode_Prefund` transaction record. - When, by using the [Withdraw Funds From Wallet](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/widget/token) API refundMode: CASH, the funds are removed from the account holder's wallet and returned to the client prefund. The system then creates a `Wallet_Refund` transaction record. --- # Transaction Statuses URL: https://docs.nium.com/docs/transactions/transaction-statuses Every transaction in the platform has two status data elements. - Transaction status - Settlement status In this page, we will cover the different types of [transaction status](#transaction-status), [settlement status](#settlement-status), and the [mapping between transaction and settlement status](#status-mapping). ## Transaction status | Status | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Approved** | The transaction authorization is successful. | | **Blocked** | The transaction is blocked based on a rule or risk policy. Blocked typically only applies to card transactions that are declined due to certain restrictions maintained as part of a rule or internal risk policy. | | **Cancelled** | The transaction is cancelled by the customer. | | **Declined** | The transaction authorization is unsuccessful. The `declined` transaction status applies to these situations:Card transactions are declined due to insufficient wallet balance.The velocity limits are getting exceeded.The declined response is received from the client under the remote-host authorization model.The received transaction is declined due to funding limits getting exceeded.The received transaction is declined under the transaction monitoring checks.The payout transactions are declined under the transaction monitoring checks.A P2P transaction is declined due to the transaction monitoring checks. | | **Error** | An error occurred while processing the transaction. | | **Initiated** | The transaction is initiated for processing. | | **Pending** | The Transaction is on hold. The pending transaction status applies to these situations: \n \nFor Receive, Payout, or Wallet to Wallet Transfer transactions awaiting clearance from internal transaction monitoring checksReceive transactions where customers are trying to fund their wallet by charging their credit/debit card (`Wallet_Credit_Mode_Card`) wherever allowed and where the transaction is awaiting a response from the respective credit/debit card issuer subject to the customer completing the necessary authentication leg required by the issuerSpend transactions captured as part of settlement posting (`Settlement_Direct_Debit` / `Settlement_Reversal` / `Settlement_Direct_Reversal` / `Settlement_Debit` / `Settlement_Credit`) awaiting manual review and clearance | | **Rejected** | A payin or payout transaction that's rejected based on the rules set by Nium platform. The `Rejected` status doesn't apply to card transactions. | ## Settlement status These are the possible values of the settlement status: | Status | Type | Description | | ------------------- | ------------------- | ------------------------------------------------------------------------------------------- | | **Disputed** | Card | Only in the case a dispute is raised for a transaction. | | **Dispute\_Closed** | Card | A dispute is raised on a transaction that's now closed. | | **Released** | Payout, Payin, Card | The transaction is released, such as after a reversal. | | **Settled** | Payout, Payin, Card | The transaction is settled with the scheme. | | **Unsettled** | Payout, Payin, Card | The transaction is yet to be settled with the scheme. | | **Waived** | Payout, Payin, Card | The card operations have waived a fee. The corresponding `Fee_Debit` transaction is waived. | ## Mapping between transaction status and settlement status | Transaction status | Settlement status | Description | | | :-------------------------- | :------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | **Approved** | **Unsettled** | The initial settlement status of a transaction that has been successfully processed by Nium. There is a possibility for the transaction to either be settled or released. | | | **Approved** | **Settled** | The status of a transaction after it has been settled through a card scheme for card transactions or paid to a beneficiary for wallet transactions. | | | **Approved** | **Released** | The status of a transaction after it has been reversed or canceled due to various reasons. | | | **Approved** | **Waived** | This applies specifically to `Fee_Debit` transactions in cases where Nium operations team has waived a fee. In such instances, the corresponding `Fee_Debit` transaction will have its settlement status updated from "Settled" to "Waived." | | | **Approved** | **Disputed** | The settlement status is updated from "Settled" to "Disputed" only when a dispute is raised for a transaction. | | | **Approved** | **Dispute\_Closed** | The settlement status is updated from "Disputed" to "Dispute Closed" only when the disputed transaction is resolved and closed. | | | **Declined** | **Unsettled** | Declined is a final state for a transaction and it will remain unsettled. | | | **Pending** | **Unsettled** | The status of a transaction when it's in a pending state due to various reasons, primarily awaiting compliance review, can potentially be updated to "Approved" or "Declined." | | | **Pending** -> **Approved** | **Unsettled** -> **Settled** or **Released** | When compliance approves the pending transaction, the transaction status transitions from "Pending" to "Approved." The settlement status remains initially "Unsettled" and will subsequently be updated to "Settled" or "Released" depending on the final status. | | | **Pending** -> **Declined** | **Unsettled** | After compliance reviews and declines the pending transaction, the transaction status changes from "Pending" to "Declined," while the settlement status remains the same as "Unsettled." | | | **Pending** -> **Rejected** | **Unsettled** | The payout or payin transaction is rejected based on the rules in the Nium platform. This status is not applicable for Card transactions. | | | **Blocked** | **Unsettled** | The transaction is blocked due to some rules or risk policies. | | --- # Transaction Response Labels URL: https://docs.nium.com/docs/transactions/response-labels The field labels in the response of the Transactions is an object consisting of various key-value pairs depending upon the transaction type. Transaction labels provide more details about wallet to wallet transfers, payouts and payins which helps both clients and customers reconcile payments more efficiently. We add new labels to this list as we support more use cases. The field labels in the response of the [Transactions](/docs/transactions) is an object consisting of various key-value pairs depending upon the transaction type. Transaction labels provide more details about [wallet to wallet transfers](/docs/wallets/wallet-to-wallet-transfers), [payouts](/docs/payouts) and [payins](/docs/payins) which helps both clients and customers reconcile payments more efficiently. We add new labels to this list as we support more use cases. ## – A – | Label | Description | | :-------------- | :-------------------------------------------------------- | | `accountName` | This field contains the account holder name for a refund. | | `accountNumber` | This field contains the account number for a refund. | ## – B – | Label | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `bankCode` | This field contains the bank code for a refund. | | `bankName` | This field contains the bank name for a refund. | | `beneficiaryCardType` | This field contains the beneficiary card type for remittance transactions. The possible values are VISA geoswift | | `beneficiaryContact` | This field contains the mobile number of the beneficiary. | | `beneficiaryCountry` | This field contains the 2-letter [ISO-2 country code](/docs/getting-started/currency-and-country-codes) of the beneficiary. | | `beneficiaryEmailId` | This field contains the email address of the beneficiary. | | `beneficiaryId` | This field contains the unique beneficiary ID for remittance transactions. | | `beneficiaryName` | This field contains the beneficiary's name for remittance transactions. | ## – C – | Label | Description | | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientReferenceNumber` | This field contains the internal transaction reference number of the client wherever sent. | | `clientTransactionId` | A unique ID you provide in the [Fund Wallet](/docs/payins/fund-wallet) request to help you track and reconcile transactions. | | `customerComments` | This field contains the customer comments for the transaction. | | `customFeeName` | This field contains any custom fee and accepts alphanumeric characters and spaces. The minimum length is 5 characters, and the maximum length is 30 characters. | ## – D – | Label | Description | | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | | `declineCode` | This field contains the code for a declined transaction. | | `declineType` | This field contains the type of decline for a transaction. | | `destinationCountry` | This field contains the 2-letter [ISO-2 country code](/docs/getting-started/currency-and-country-codes) of the destination country. | | `disputeAction` | This field contains the action taken on the disputed transaction. | | `disputeActionAmount` | This field contains the `disputeAction` amount of the disputed transaction. | | `disputeActionCurrency` | This field contains the `disputeAction` currency of the disputed transaction. | | `disputeAmount` | This field contains the amount of the disputed transaction. | | `disputeCurrency` | This field contains the currency of the disputed transaction. | | `disputeDate` | This field contains the date of the disputed transaction. | | `disputeReason` | This field contains the reason for the disputed transaction. | ## – E – | Label | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ecbExchangeRate` | This field contains the exchange rate quoted by the ECB. | | `ecbMarkupRate` | This field contains the difference between the `transactionExchangeRate` and the `ecbCurrencyExchangeRate` rates expressed in percentage where: \n `ecbMarkupRate` = (`ecbCurrencyExchangeRate` - `transactionExchangeRate`) / `ecbCurrencyExchangeRate` | | `exchangeRate` | This field contains the gross exchange rate applicable for a transaction. | ## – F – | Label | Description | | :---------- | :------------------------------------------------------------------------------------ | | `feeName` | This field contains the name of the fee charged. | | `feePeriod` | This field contains the period for which the fee is charged in the `MMM-YYYY` format. | ## – L – | Label | Description | | :----------------------- | :------------------------------------------------------------- | | `linkedMaskedCardNumber` | This field contains the masked card number of the linked card. | ## – M – | Label | Description | | :----------- | :--------------------------------------------------------------- | | `markupRate` | This field contains the applicable markup rate on a transaction. | ## – N – | Label | Description | | :---------------- | :------------------------------------------------------------------------------------------------------------------------- | | `narrative` | This field contains the comments entered while sending money to a virtual account number, if received from a partner bank. | | `netExchangeRate` | This field contains the net exchange rate applicable for a transaction after considering markup, if any. | ## – O – | Label | Description | | :-------------------------- | :----------------------------------------------------------------------- | | `originalAuthorizationCode` | This field contains the authorization code for the original transaction. | ## – P – | Label | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------- | | `payoutMethod` | This field contains the payout method requested. | | `payoutWalletName` | This field contains the wallet name of the beneficiary where payout has been made. | | `proxyName` | This field contains the name for proxy method. The possible values are: PayNow UPI PIX PayID DuitNow | | `proxyType` | This field contains the proxy type sent in the payment request. | | `proxyValue` | This field indicates the proxy value sent in the payment request. | | `purposeCode` | Purpose code for the transaction, used to classify the payment under local regulations or compliance rules. | ## – R – | Label | Description | | :----------------------- | :--------------------------------------------------------------- | | `receiverCustomerHashId` | This field contains the unique `customerHashId` of the receiver. | | `receiverFirstName` | This field contains the receiver's first name. | | `receiverLastName` | This field contains the receiver's last name. | | `remitterBankCode` | Bank code of the remitter’s (sender’s) bank. | ## – S – | Label | Description | | :--------------------- | :--------------------------------------------------------------------------------------------- | | `senderCustomerHashId` | This field contains the unique `customerHashId` of the sender. | | `senderFirstName` | This field contains the sender's first name. | | `senderLastName` | This field contains the sender's last name. | | `senderName` | Full name of the sender for the transaction. | | `senderWalletHashId` | Unique `walletHashId` of the sender’s wallet. | | `sourceOfFunds` | This field contains the source of funds as declared while initiating a remittance transaction. | | `swiftFeeType` | This field indicates the swift fee type applied in a remittance transaction. | ## – T – | Label | Description | | :------------------------ | :-------------------------------------------------------- | | `transactionExchangeRate` | The transaction exchange rate applied on the transaction. | --- # Prohibited Countries URL: https://docs.nium.com/docs/transactions/prohibited-countries - Transactions are not allowed when either the sender or receiver country belongs to the list of prohibited countries. Any transactions with sender or receiver belonging to the below list will receive a Reject status. - Transactions are not allowed when either the sender or receiver country belongs to the list of prohibited countries. Any transactions with sender or receiver belonging to the below list will receive a `Reject` status. - This list can change from time to time, depending on our risk policy. ## List of prohibited countries | Country code | Country name | | ------------ | -------------------------------- | | AF | Afghanistan | | BY | Belarus | | CD | Democratic Republic of the Congo | | CF | Central African Republic | | CU | Cuba | | GW | Guinea-Bissau | | HT | Haiti | | IR | Iran | | IQ | Iraq | | KP | North Korea | | LB | Lebanon | | LY | Libya | | ML | Mali | | MM | Myanmar | | RU | Russia | | SO | Somalia | | SS | South Sudan | | SD | Sudan | | SY | Syria | | VE | Venezuela | | YE | Yemen | | ZW | Zimbabwe | --- # Requests for Information URL: https://docs.nium.com/docs/transactions/transaction-rfis As a transaction is submitted, Nium evaluates it to check if it can be automatically approved. A request that isn’t automatically approved undergoes a manual review. As part of this manual review, additional information maybe requested to assist compliance review. This requests are called *requests for information* (**RFIs** for short). During this process, the compliance status of the transaction changes and the client is notified with a [Transaction Compliance Status webhook event](/docs/developers/notifications-and-webhooks/callbacks/transaction-compliance-status) through their `` in the following format: ```URL POST https://?type=TRANSACTION&value={transactionId} ``` After receiving this notification for the transaction specified by `transactionId`, the client is expected to perform the following steps: - [Step 1: Fetch the Transaction](#step1) - [Step 2: Respond to the Transaction RFI](#step2) ## Step 1: Fetch the Transaction Fetch the Transaction API using the `transactionID` in the webhook event you received. The response of the Transaction API is an array of objects that contain the details of all the transactions created by the customer. The following fields include the details needed to complete the RFI flow: | Parameters | Type | Description | | --------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `complianceStatus` | string | This field denotes the compliance status of the transaction which can be any one of the following: `CLEAR` `PENDING` `RFI_REQUESTED` `REJECT` | | [`rfiDetails`](#rfiDetails-array) | array of objects | This object contains the details of the RFIs if they have been requested by the agent for the transaction. The corresponding `complianceStatus` should be `RFI_REQUESTED` for this field to be considered by the client | ### `rfiDetails` array This array includes the details of all the RFIs that Nium has raised. \*\*NOTE:\*\*This array is only needed when `complianceStatus` is `RFI_REQUESTED`. ### `requiredData` array This array contains the fields of data required to be passed as part of each RFI: | Parameters | Type | Description | | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `description` | string | The unique name of the RFI. \n \nFor transactions with type = `data`, the `description` field can also be used to figure out the field name to use in the Respond to Transaction RFI request. | | `documentType` | enum | The type of the document, if applicable. \n \nAvailable values include: POI POA null | | `mandatory` | boolean | Details if the `requiredData` array needs to be included. \nAvailable values include `Yes` or `No` | | `remarks` | string | Returns any remarks entered by the compliance agent while raising the RFI. Max. length: 255 characters | | `rfiHashId` | string | The unique identifier (uuid) for the RFI. This field gets raised under the group of RFI objects. | | `rfiId` | string | The unique identifier (uuid) for the group of RFIs raised for the transaction. | | `rfiStatus` | enum | This field highlights whether the RFI has been responded to or not. \n \nAvailable values include:`RFI_REQUESTED`: this status highlights that the RFI is pending a response. `RFI_RESPONDED`: this status highlights that the client has responded to the RFI. | | `transactionEntityType` | enum | Details the type of entity for whom the RFI has been raised. Available values include: `CREDITOR`: The beneficiary involved in the transaction `DEBTOR`: The remitter involved in the transaction | | `type` | enum | Details if the RFI requires only data or if additional documents are required as well. Available values include:`data` `document` | | `[requiredData](#requiredData-array)` | array of objects | Returns the data fields required as part of the RFI. | ## Step 2: Respond to the Transaction RFI Use the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) request to respond to the RFI. Depending on the `rfiDetails` array in the Get Transaction response, clients can build their response to the RFIs using the [Respond to Transaction RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) request: | Parameters | Type | Description | | :------------------------------------------ | :--------------- | :---------------------------------------------------------------------------------------------------------------- | | `authCode` | string | The authorization code of the transaction for which the RFI was raised. | | `clientHashId` | string | Your client hash ID to which the customer is linked. | | `customerHashId` | string | The `customerHashId` created when the `customer` was initially created. | | `walletHashId` | string | Your `walletHashId`. | | [`rfiResponseRequest`](#rfiResponseRequest) | array of objects | Contains information required by distinct RFIs - each denoted by `rfiHashId` in the Get Transaction API response. | Max character length for any parameter unless explicitly specified is 255. ### `rfiResponseRequest` array | Parameters | Type | Description | | :------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------- | | `rfiHashId` | string | The `rfiHashId` of the RFI received as part of the Get Transaction API response. | | [`rfiResponseInfo`](#rfiResponseInfo) | object | The details required to be submitted as part of the RFI response in case of different types of RFIs. | ### `rfiResponseInfo` object Use these fields to respond to the various types of RFIs. For more details on the different types of RFIs, see [Transaction RFI Types](/docs/transactions/transaction-rfis/rfi-types). The client needs to send only the information required in that specific RFI type. See [RFI Examples](/docs/transactions/transaction-rfis/rfi-examples) for more details on how you can respond to each RFI. | Parameters | Type | Description | | :---------------------------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------- | | `bankAccountNumber` | string | The bank account number of the remitter/beneficiary. | | `bankName` | string | The name of the bank of the remitter/beneficiary. | | `dateOfBirth` | string | The date of birth of the remitter/beneficiary if they are individuals in YYY-MM-DD format. | | `firstName` | string | The first name of the remitter/beneficiary if they are individuals. | | `middleName` | string | The middle name of the remitter/beneficiary if they are individuals. | | `lastName` | string | The last name of the remitter/beneficiary if they are individuals. | | `nationality` | string | The nationality of the remitter/beneficiary if they are individuals. | | [`address`](#address) | object | The address of residence or address of registration depending on whether the remitter/beneficiary is an individual or a corporate entity. | | [`identificationDoc`](#identificationDoc) | object | Submit the requested documents. | | [`additionalInfo`](#additionalInfo) | object | This field is used to answer questions and collect any additional information about the remitter/beneficiary. | ### `address` object | Parameter | Type | Description | | -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `addressLine1` | string | Line 1 of the remitter's/beneficiary's address. \nMax. limit: 100 characters | | `addressLine2` | string | Line 2 of the remitter's/beneficiary's address. \nMax. limit: 100 characters | | `city` | string | The city of the remitter's/beneficiary's address. \nMax. limit: 50 characters | | `state` | string | The state of the remitter's/beneficiary's address. | | `country` | string | The 2-letter ISO Alpha-2 country code representing the remitter’s/beneficiary's country. | | `postcode` | string | The postal code of the customer’s address. Limit: 3-10 characters. Acceptable special characters include: `Hypen(-)``Hash(#)``Space( )` | ### `identificationDoc` object Use this object to submit the documents and the details requested in RFI: | Parameter | Type | Description | | --------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `identificationType` | enum | The type of document that needs to be submitted. \nAvailable values include: APPLICANT\_AUTHORITY\_LETTER BANK\_STATEMENT DRIVER\_LICENSE GOVERNMENT\_DOCUMENT INVOICE PASSPORT SALARY\_STATEMENT PERSONAL\_IMAGE UTILITY\_BILL OTHERS | | `identificationValue` | string | The ID number of the document requested in the RFI. | | `identificationDocIssuanceCountry` | string | The issuance country of the document. See [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) for the list of available values for the category `countryName`. | | `identificationDocExpiry` | string | The expiry date of the document, if present, in `YYYY-MM-DD` format. This should be a future date. | | `identificationDocIssuanceDate` | string | The issuance date of the document, if present, in `YYYY-MM-DD` format. Applicable if the document being submitted is an Australian Driver's License. This should be a past date. | | `identificationDocIssuingAuthority` | string | The issuing authority of the document. Applicable if the document being submitted is an Australian Driver's License. | | `identificationDocReferenceNumber` | string | The reference number of the document. Applicable if the document being submitted is an Australian Driver's License. | | [`identificationDocument`](#identificationDocument) | array of objects | Used to submit the multiple documents requested in the RFI. | ### `identificationDocument` array | Parameter | Type | Description | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- | | `fileName` | string | Name of the file being submitted along with the extension | | `fileType` | string | Type of the document file. Available values include: `application/pdf``image/png``image/jpg``image/jpeg` | | `document` | string | Base64 string of the document file. | ### `additionalInfo` object | Parameter | Type | Description | | :---------- | :----- | :------------------------------------------------------------------------------------------ | | `otherData` | string | Used when responding to any additional questions or data requested by the compliance agent. | --- # RFI Types URL: https://docs.nium.com/docs/transactions/transaction-rfis/rfi-types Once the client is made aware that RFIs have been raised, they'll need to understand what information needs to be submitted. This page highlights the various types of RFIs that can be raised. The following tables include the different types of RFIs that a client can receive and the required information needed to be submitted: ## Data based RFIs The following table details the RFIs that a compliance agent raises to seek additional information from the client: | RFI description | Required field | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ADDRESS** | rfiResponseRequest.rfiResponseInfo.address | | **BANK\_ACCOUNT\_NUMBER** | rfiResponseRequest.rfiResponseInfo.bankAccountNumber | | **BANK\_NAME** | rfiResponseRequest.rfiResponseInfo.bankName | | **DATE\_OF\_BIRTH** | rfiResponseRequest.rfiResponseInfo.dob | | **EMPLOYMENT\_STATUS** | rfiResponseRequest.rfiResponseInfo.additionalInfo.employmentStatus \nAcceptable values: SalariedNon Salaried | | **FIRST\_NAME** | rfiResponseRequest.rfiResponseInfo.firstName | | **INDUSTRY\_TYPE** | rfiResponseRequest.rfiResponseInfo.additionalInfo.industryType \nAcceptable values: Please refer to the [Fetch corporate constants](/api#tag/customer-account-corporate/GET/api/v2/client/{clientHashId}/onboarding/constants) API for a list of values for `INDUSTRY_TYPE` and `industrySector`. | | **IS\_PEP** | rfiResponseRequest.rfiResponseInfo.additionalInfo.isPep | | **LAST\_NAME** | rfiResponseRequest.rfiResponseInfo.lastName | | **MIDDLE\_NAME** | rfiResponseRequest.rfiResponseInfo.middleName | | **NATIONALITY** | rfiResponseRequest.rfiResponseInfo.nationality | | **POSITION** | rfiResponseRequest.rfiResponseInfo.additionalInfo.position \nAcceptable values: DIRECTOR UBO REPRESENTATIVESIGNATORY SHAREHOLDERTRUSTEE PARTNERMEMBERS SETTLOR PROTECTOR EXECUTOR | | **REASON\_FOR\_TRANSFER** | rfiResponseRequest.rfiResponseInfo.additionalInfo.reasonForTransfer \nAcceptable values: Medical TreatmentPurchase of Residential PropertyInsurance Claims PaymentInformation Service ChargesSalary or Wages or Fees for advisors technical assistance and academic knowledge including remuneration for specialistsFor payment of exported goodsTransfer to own accountHotel AccomodationUtility BillsPayment of Property RentalMutual Fund InvestmentAdvertising and Public relations-related expensesRepresentative office expensesDelivery fees for goodsEmigration Consultancy FeesFamily MaintenanceTravelRepayment of LoansInsurance PremiumInvestment in SharesRoyalty fees trademark fees patent fees and copyright feesConstruction costs or expensesGeneral Goods Trades - Offline tradeEducation-related student expensesTax PaymentProduct indemnity insuranceDonationsFees for brokers front end fee commitment fee guarantee fee and custodian feeTransportation fees for goodsPayment to customers of PSPTransfer to Cryptocurrency ExchangesRefundGiftsSalary | | **REMITTER\_BENEFICIARY\_RELATIONSHIP** | rfiResponseRequest.rfiResponseInfo.additionalInfo.remitterBeneficiaryRelationship. Put values here like VENDORS, EMPLOYEES, CUSTOMERS, etc. | | **SOURCE\_OF\_FUNDS** | rfiResponseRequest.rfiResponseInfo.additionalInfo.sourceOfFunds \nAcceptable values: SalaryPersonal WealthRetirement FundsBusiness Owner/ShareholderLoan FacilityPersonal AccountCorporate Account | | **THIRD\_PARTY\_FUNDING** | rfiResponseRequest.rfiResponseInfo.additionalInfo.thirdPartyFunding \nAcceptable values: `Yes` or `No` | | **TM\_OTHER\_DATA** | rfiResponseRequest.rfiResponseInfo.additionalInfo.otherData | ## Document based RFIs Documents requested through RFIs can be submitted through the `rfiResponseRequest.rfiResponseInfo.identificationDoc` object. The following table details the available values for `identificationType` being any of the following values as required: | RFI Description | Description | | :--------------------------- | :----------------------------------------------------------------------------------------- | | `APPLICANT_AUTHORITY_LETTER` | This RFI requires the LOA of the applicant to be submitted as a response. | | `BANK_STATEMENT` | The bank statement of the entity for the last 90 days. | | `DRIVER_LICENSE` | The Driver's License of the entity. | | `GOVERNMENT_DOCUMENT` | Government Letter. | | `INVOICE` | Invoice | | `PASSPORT` | Passport of the entity. | | `PERSONAL_IMAGE` | Selfie of the entity. | | `SALARY_STATEMENT` | Salary statement of the entity for the last 90 days. | | `UTILITY_BILL` | Utility bill for the last 90 days. | | `OTHERS` | Any other document as requested by the compliance agent based on their remarks in the RFI. | --- # RFI Examples URL: https://docs.nium.com/docs/transactions/transaction-rfis/rfi-examples This guide walks through how clients respond to RFIs. For a list of RFI types and definitions, see Transaction RFI Types. This guide walks through how clients respond to RFIs. For a list of RFI types and definitions, see [Transaction RFI Types](/docs/transactions/transaction-rfis/rfi-types). ## Step 1: Review webhook The client is expected to consume the [Transaction Compliance Status](/docs/developers/notifications-and-webhooks/callbacks/transaction-compliance-status) event to figure out if there is any change in the`complianceStatus` of the transaction. ## Step 2: Fetch the transaction The client is expected to call the Get Transaction API after receiving the webhook event. Next, the client must review the `complianceStatus` field of the event to figure out the current compliance status of the transaction. If `complianceStatus` returns `RFI_REQUESTED`, then the client should consume the information contained in `rfiDetails` field in the Fetch Transaction response. ## Step 3: Review `rfiDetails` The `rfiDetails` field is an array of objects, each containing the details of the RFI request. The client should review the details inside these objects: - The RFI's unique identifiers (`rfiHashId`, `rfiId` and `rfiStatus`) help identify the RFIs. - `description`and `remarks` parameters help identify why an RFI was raised. - `transactionEntityType` parameter helps identify who the RFI is for - `DEBTOR` or `CREDITOR`. - Use the `type`, `documentType` & `requiredData` field to respond to the RFI. #### Response Example ```json { "rfiDetails": [ { "rfiHashId": "9d6676fb-e6b9-435f-9c4b-f47f7f72b9a0", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "address", "mandatory": true, "type": "data", "documentType": "NA", "remarks": "Please provide the remitter's address as we couldn't locate the one submitted during the payout request", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Post Code", "value": "postcode", "type": "data" }, { "label": "Country", "value": "country", "type": "data" }, { "label": "State", "value": "state", "type": "data" }, { "label": "City", "value": "city", "type": "data" }, { "label": "Address Line2", "value": "addressLine2", "type": "data" }, { "label": "Address Line1", "value": "addressLine1", "type": "data" } ] }, { "rfiHashId": "42306dfe-32e8-49db-b33a-ba3718be1b85", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "bankName", "mandatory": true, "type": "data", "documentType": "NA", "remarks": "Please provide the name of the remitter's bank", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Bank Name", "value": "bankName", "type": "data" } ] }, { "rfiHashId": "29eb2280-a52a-418b-8749-bdc29f9c0623", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_RESPONDED", "description": "dateOfBirth", "mandatory": true, "type": "data", "documentType": "NA", "remarks": "Please provide the date of birth for the remitter since the dob submitted earlier doesn't match with the govt. records", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Date Of Birth", "value": "dateOfBirth", "type": "data" } ] } ] } ``` Based on the above Get Transaction response snippet, we can identify that, - The RFIs with the following unique IDs needs a response: - `rfiId`=`ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975` - `rfiHashId`=`9d6676fb-e6b9-435f-9c4b-f47f7f72b9a0` and `42306dfe-32e8-49db-b33a-ba3718be1b85` - `rfiStatus` = `RFI_REQUESTED` - The RFIs with the following unique IDs have already been responded to and doesn't need further action from the client. This is detailed in the `rfiStatus` field with the response returning `RFI_RESPONDED`. - `rfiId` = `ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975` - `rfiHashId`=`29eb2280-a52a-418b-8749-bdc29f9c0623` - The RFI with `rfiHashId`=`9d6676fb-e6b9-435f-9c4b-f47f7f72b9a0` has been raised to collect the debtor's address (remitter in case of a Payout Transaction) because the compliance agent found an inconsistency. - While responding to the RFI with `rfiId`=`ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975` & `rfiHashId`=`9d6676fb-e6b9-435f-9c4b-f47f7f72b9a0`the information should be a piece of data; no documentation is required. This is detailed in the `type` field with the response returning `data`. ## Data Based RFIs - [Address](#address) - [Bank name](#bank_name) - [Date of birth](#date_of_birth) - [Employment status](#employment_status) - [Other data](#tm_other_data) ### `ADDRESS` #### Response with RFI ```json { "rfiDetails": [ { "rfiHashId": "9d6676fb-e6b9-435f-9c4b-f47f7f72b9a0", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "address", "mandatory": true, "type": "data", "documentType": "NA", "remarks": "r", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Post Code", "value": "postcode", "type": "data" }, { "label": "Country", "value": "country", "type": "data" }, { "label": "State", "value": "state", "type": "data" }, { "label": "City", "value": "city", "type": "data" }, { "label": "Address Line2", "value": "addressLine2", "type": "data" }, { "label": "Address Line1", "value": "addressLine1", "type": "data" } ] } ] } ``` #### Request to answer RFI ```json { "rfiResponseRequest": [ { "rfiResponseInfo": { "address":{ "addressLine1": "High Street 101, 56th Avenue", "addressLine2": "Hyung County", "state":null, "city": "Singapore", "country": "SG", "postcode": "28046" }, "rfiHashId": "52a3c254-0efd-444d-a144-f0075eca0722" } ] } ``` ### `BANK_NAME` Similar response structures can be used for other RFIs like: - `FIRST_NAME` - `MIDDLE_NAME` - `LAST_NAME` - `INDUSTRY_TYPE` - `IS_PEP` - `NATIONALITY` #### Response with RFI ```json { "rfiDetails": [ { "rfiHashId": "42306dfe-32e8-49db-b33a-ba3718be1b85", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "bankName", "mandatory": true, "type": "data", "documentType": "NA", "remarks": "r", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Bank Name", "value": "bankName", "type": "data" } ] } ] } ``` #### Request to answer RFI ```json { "rfiResponseRequest": [ { "rfiResponseInfo": { "bankName": "State Bank of Mauritius" }, "rfiHashId": "52a3c254-0efd-444d-a144-f0075eca0722" } ] } ``` ### `DATE_OF_BIRTH` #### Response with RFI ```json { "rfiDetails": [ { "rfiHashId": "29eb2280-a52a-418b-8749-bdc29f9c0623", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "dateOfBirth", "mandatory": true, "type": "data", "documentType": "NA", "remarks": "r", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Date Of Birth", "value": "dateOfBirth", "type": "data" } ] } ] } ``` #### Request to answer RFI ```json { "rfiResponseRequest": [ { "rfiResponseInfo": { "dateOfBirth": "1986-10-24" }, "rfiHashId": "52a3c254-0efd-444d-a144-f0075eca0722" } ] } ``` ### `EMPLOYMENT_STATUS` Similar response structures can be used for other RFIs like: - `POSITION` - `REASON_FOR_TRANSFER` - `REMITTER_BENEFICIARY_RELATIONSHIP` - `SOURCE_OF_FUNDS` - `THIRD_PARTY_FUNDING` #### Response with RFI ```json { "rfiDetails": [ { "rfiHashId": "2bd9f61e-444e-4f9b-ab38-a32589f5a62c", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "employmentStatus", "mandatory": true, "type": "data", "documentType": "NA", "remarks": "r", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Employment Status", "value": "employmentStatus", "type": "data" } ] } ] } ``` #### Request to answer RFI ```json { "rfiResponseRequest": [ { "rfiResponseInfo": { "employmentStatus": "Salaried" }, "rfiHashId": "52a3c254-0efd-444d-a144-f0075eca0722" } ] } ``` ### `TM_OTHER_DATA` #### Response with RFI ```json { "rfiDetails": [ { "rfiHashId": "2bd9f61e-444e-4f9b-ab38-a32589f5a62c", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "otherData", "mandatory": true, "type": "data", "documentType": "NA", "remarks": "Please mention the relation of your organization with the US Govt. Agency", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Other Data", "value": "otherData", "type": "data" } ] } ] } ``` #### Request to answer RFI ```json { "rfiResponseRequest": [ { "rfiResponseInfo": { "additionalInfo": { "otherData": "Our organization is a subsidiary of the US Govt. Agency" }, "rfiHashId": "52a3c254-0efd-444d-a144-f0075eca0722" } ] } ``` ## Document based RFIs - [Drivers license](#driver_license) - [Invoice](#invoice) - [Others](#others) ### `DRIVER_LICENSE` A similar response structure can also be used for other RFIs, including: - `PASSPORT` - `SALARY_STATEMENT` - `BANK_STATEMENT` #### Response with RFI ```json { "rfiDetails": [ { "rfiHashId": "2ee641b9-1a58-440b-b25b-a01e7e09c7c2", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "driverLicense", "mandatory": true, "type": "document", "documentType": "POA", "remarks": "r", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Driver's License Document", "value": "identificationDocument", "type": "document" }, { "label": "Driver's License Issuing Date", "value": "identificationIssuingDate", "type": "data" }, { "label": "Issuing Authority", "value": "identificationIssuingAuthority", "type": "data" }, { "label": "Driver's License Number", "value": "identificationValue", "type": "data" } ] } ] } ``` #### Request to answer RFI ```json { "rfiResponseRequest": [ { "rfiResponseInfo": { identificationDoc: { "identificationType": "DRIVER_LICENSE", "identificationValue": "DL2194381", "identificationIssuanceAuthority": "ACT Road Users Services", "identificationIssuingDate": "2029-10-29", "identificationDocument": [ { "fileName": "Driver's License Front.jpg", "fileType": "image/jpg", "document": "" }, { "fileName": "Driver's License Back.jpg", "fileType": "image/jpg", "document": "" } ] }, "rfiHashId": "52a3c254-0efd-444d-a144-f0075eca0722" } ] } ``` ### `INVOICE` Similar response structure can be used for other RFIs like: - `APPLICANT_AUTHORITY_LETTER` - `GOVERNMENT_DOCUMENT` - `PERSONAL_IMAGE` #### Response with RFI ```json { "rfiDetails": [ { "rfiHashId": "5bbb5e72-151a-4998-b76e-4f210db22c3c", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "Invoice", "mandatory": true, "type": "document", "documentType": "NA", "remarks": "Please provide the copy of the Invoice not more than 90 days old", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Invoice", "value": "identificationDocument", "type": "document" } ] } ] } ``` #### Request to answer RFI ```json { "rfiResponseRequest": [ { "rfiResponseInfo": { identificationDoc: { "identificationType": "INVOICE", "identificationDocument": [ { "fileName": "Invoice-Page1.jpg", "fileType": "image/jpg", "document": "" }, { "fileName": "Invoice-Page2.jpg", "fileType": "image/jpg", "document": "" }, { "fileName": "Invoice-Page3.jpg", "fileType": "image/jpg", "document": "" } ] }, "rfiHashId": "52a3c254-0efd-444d-a144-f0075eca0722" } ] } ``` ### `OTHERS` #### Response with RFI Similar response structure can be used for other RFIs like `APPLICANT_AUTHORITY_LETTER` ```json { "rfiDetails": [ { "rfiHashId": "5bbb5e72-151a-4998-b76e-4f210db22c3c", "rfiId": "ff18e4f5-0eb2-4eb7-a57b-2e6fe7efd975", "rfiStatus": "RFI_REQUESTED", "description": "others", "mandatory": true, "type": "document", "documentType": "NA", "remarks": "Please provide the copy of the CEO's Letters", "transactionEntityType": "DEBTOR", "requiredData": [ { "label": "Other Document", "value": "identificationDocument", "type": "document" } ] } ] } ``` #### Request to answer RFI ```json { "rfiResponseRequest": [ { "rfiResponseInfo": { identificationDoc: { "identificationType": "OTHERS", "identificationDocument": [ { "fileName": "CEOLetter-Page1.jpg", "fileType": "image/jpg", "document": "" }, { "fileName": "CEOLetter-Page2.jpg", "fileType": "image/jpg", "document": "" }, { "fileName": "CEOLetter-Page3.jpg", "fileType": "image/jpg", "document": "" } ] }, "rfiHashId": "52a3c254-0efd-444d-a144-f0075eca0722" } ] } ``` --- # Reports URL: https://docs.nium.com/docs/reports Customer account statements ## Customer account statements > What happens when a client uses this API to fetch the statement for its customers? An account statement is downloaded for customers using this API, using the default template. > What setup tasks do clients need to do before they can use this new feature? See [Customer Account Statements](/docs/reports/customer-account-statements). --- # Daily Reports URL: https://docs.nium.com/docs/reports/daily-reports We have the following daily reports on Clients - [Daily Client Account Fees](/docs/reports/daily-reports/account-fees) - [Daily Client Assigned Cards](/docs/reports/daily-reports/assigned-cards) - [Daily Client Card Activity Summary](/docs/reports/daily-reports/card-activity) - [Daily Client Card Issuance](/docs/reports/daily-reports/card-issance) - [Daily Client Card Transaction Authorization](/docs/reports/daily-reports/card-authorizations) - [Daily Client Customer Onboarding](/docs/onboarding/corporate-customers/hk-onboarding) - [Daily Client Ledger Summary](/docs/reports/daily-reports/client-ledger-summary) - [Daily Client Transaction Summary](/docs/reports/daily-reports/transaction-summary) --- # Account Fees URL: https://docs.nium.com/docs/reports/daily-reports/account-fees This once-a-day static report contains a summary of any fee applied to any customer, both transactional and non-transactional, during the previous day. It may be set up on request. A client administrator can login to the Nium back-office and view or download this report. The report can also be delivered over SFTP upon request. File naming convention: `Client_Account_Fees_Report_{ClientHashId}_YYYYMMDD.csv` | Field | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Date/Time of Fee Debit** | The date and time of the transaction, formatted as `DD/MM/YYYY hh:mm:ss`. | | **Customer Hash ID** | The unique customer identifier \[36 character UUID]. | | **Wallet Hash ID** | The unique wallet identifier \[36 character UUID]. | | **Authorization Code** | The system-generated authorization code for the fee. | | **Transaction Type** | The type of transaction. Valid values are: `Fee_Debit`, `Fee_Waiver`, and `Fee_Reversal`. | | **Fee Name** | The name of the fee. | | **Transaction Status** | Status of the fee transaction. Valid values are: `APPROVED`, `DECLINED`, `PENDING`, and `REVERSAL`. | | **Trxn CCY** | 3-letter ISO currency code for the transaction currency. | | **Trn Amt** | Amount in transaction currency. | | **Auth Currency** | 3-letter ISO currency code for the authenticated currency. | | **Auth Amount** | Amount in authenticated currency. | | **Billing Currency** | 3-letter ISO currency code for the billing currency. | | **Billing Amount** | Amount in billing currency. | | **Comments** | Auto-generated system comments for the fee charged. | | **Fee Source** | This field indicates whether the fee is levied by the system as part of the fee setup or by the client via the Charge Fee API. | | **Fee Type** | This field is applicable only to fees that the system levies. This field indicates whether the fee is set up as percentage or flat. | | **Fee Value** | This field is applicable only to fees that the system levies. This field contains the fee value that is defined in the setup. | | **Fee Value Currency** | This field is applicable only to fees that the system levies and the fee type is flat. This field indicates the currency in which the *Fee Value* field is defined. | | **Additional Fee Type** | This field is applicable only to fees where the client has opted for additional fees as part of the payout request. This field contains the fee type opted by the client as fixed or percentage. | | **Additional Fee Value** | This field is applicable only to fees where the client has opted for additional fees as part of the payout request. This field contains the fee value that is added wherever required to the fee that is defined in the system. | --- # Assigned Cards URL: https://docs.nium.com/docs/reports/daily-reports/assigned-cards This once-a-day static report in csv format contains the details of bulk issued cards assigned to customers of a client during a day. It may be setup on request. A client administrator can login to the Nium back-office and view or download the same in CSV format. It can also be delivered over SFTP on request. For SFTP setup at Nium, clients need to provide public PGP key for encryption and static IP for whitelisting. File naming convention: `Client_Cards_Assigned_Report_{ClientHashId}_YYYMMDD.csv` | Field | Description | | ---------------------------- | ----------------------------------------------------------------------------------------- | | Date/Time of Card Assignment | Date/Time of transaction, formatted as `DD/MM/YYYY HH:mm:ss`. | | Masked Card Number | Masked card number, formatted as `1234-56xx-xxxx-8765`. | | Card Hash ID | Unique card identifier \[36 character UUID]. | | Status | Status of the card. Values included are `INACTIVE`, `ACTIVE`, `TEMP_BLOCK` and `P_BLOCK`. | | Customer Hash ID | Unique Customer Identifier \[36 character UUID]. | | Wallet Hash ID | Unique Wallet Identifier \[36 character UUID]. | --- # Card Activity URL: https://docs.nium.com/docs/reports/daily-reports/card-activity This once-a-day static report contains a count of all approved and declined card transactions classified into IN_STORE, ONLINE, and ATM. This includes the previous day transactions for all customers of a client. This once-a-day static report contains a count of all approved and declined card transactions classified into `IN_STORE`, `ONLINE`, and `ATM`. This includes the previous day transactions for all customers of a client. It may be setup on request. A client administrator can login to the Nium back-office and view or download the same. It can also be delivered over SFTP on request. File naming convention: `Client_Card_Activity_Summary_Report_{ClientHashId}_YYYYMMDD.csv` | STATUS | Approved | Declined | | --------------------------- | :------: | :------: | | `IN_STORE` - DOMESTIC | 1 | 0 | | `IN_STORE` - CROSS-CURRENCY | 0 | 0 | | `ONLINE` - DOMESTIC | 5 | 1 | | `ONLINE` - CROSS-CURRENCY | 8 | 0 | | `ATM` - DOMESTIC | 0 | 2 | | `ATM` - INTERNATIONAL | 5 | 0 | --- # Card Issuance URL: https://docs.nium.com/docs/reports/daily-reports/card-issance This once-a-day static report in csv format contains the details of cards issued [through Add Card flow] to customers of a client during a day. This once-a-day static report in csv format contains the details of cards issued \[through Add Card flow] to customers of a client during a day. It may be setup on request. A client administrator can login to the Nium back-office and view or download the same in CSV format. It can also be delivered over SFTP on request. File naming convention: `Client_Card_Issuance_Report_ {ClientHashId}_YYYYMMDD.csv` | Field | Description | | -------------------------- | ----------------------------------------------------------------------- | | Date/Time of Card Issuance | Date/Time of card issuance, formatted as 24-hour `DD/MM/YYYY HH:mm:ss`. | | Masked Card Number | Masked card number, formatted as `1234-56xx-xxxx-8765`. | | Card Hash ID | Unique card identifier \[36 character UUID]. | | Status | Activation status of the card. | | Customer Hash ID | Unique customer identifier \[36 character UUID]. | | Wallet Hash ID | Unique wallet identifier \[36 character UUID]. | --- # Card Authorizations URL: https://docs.nium.com/docs/reports/daily-reports/card-authorizations This once-a-day static report contains all card authorization details for customers of the client. It may be setup on request. A client administrator can login to the Nium back-office and view or download the same. It can also be delivered over SFTP on request. File naming convention: `Client_Card_Transaction_Authorization_Report_{ClientHashId}_YYYYMMDD.csv` | Field | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Date/Time of Transaction | Date/Time of transaction, formatted as 24-hour `DD/MM/YYYY HH:mm:ss`. | | Transaction Type | This report contains all transactions done on a card, including fees and adjustments. | | Status | Transaction status. Values included: `APPROVED`, `PENDING`, `DECLINED`, `REVERSAL`, and `BLOCKED`. | | Settlement Status | Settlement status of the transaction. Values included: `UNSETTLED`, `SETTLED`, `RELEASED`, `WAIVED`, `DISPUTED`, and `DISPUTE CLOSED`. | | Transaction Currency Code | 3-letter ISO currency code for the transaction amount. | | Transaction Amount | Transaction amount. | | Billing Currency Code | 3-letter ISO currency code for the billing amount. | | Billing Amount | Billing amount. | | Auth Currency Code | 3-letter ISO currency code for the authorization amount. | | Auth Amount | Authorization amount. | | Effective Auth Amount | Authorization amount after accounting for fees, etc. | | Previous Balance | Previous balance prior to the transaction. | | Settlement Date of Transaction | Date/Time of settlement, and used only for transactions with `SETTLED` status (this field is empty for all other status types). | | Settlement Currency Code | 3-letter ISO currency code for the settlement amount. | | Settlement Transaction Amount | Transaction amount at time of settlement. This field will have `0.0000` for unsettled transactions. | | Settlement Billing Amount | Billing amount at time of settlement. This field will have `0.0000` for unsettled transactions. | | Settlement Auth Amount | Settlement amount at time of settlement. This field will have `0.0000` for unsettled transactions. | | Customer Hash Id | Unique customer identifier \[36 character UUID]. | | Wallet Hash Id | Unique wallet identifier \[36 character UUID]. | | Card Hash Id | Unique card identifier \[36 character UUID]. | | Mask Card Number | Masked card number, formatted as `1234-56xx-xxxx-9876`. | | Pocket Name | Name of the pocket. If no pocket is assigned, value is `DEFAULT`. | | Merchant Category | Merchant category as grouped by Nium, based on MCC. | | Merchant Category Code | 4-digit Merchant Category Code. | | Merchant Id | Merchant Identifier assigned by the network. | | Merchant Name | Name of the merchant. | | Merchant City | Merchant city or location. | | Merchant Country | Country where merchant is situated. | | Merchant Latitude | Merchant latitude. | | Merchant Longitude | Merchant longitude. | | Merchant Tagged Name | Merchant tagged name. | | Merchant Zoom Index | Merchant zoom index on map. | | Business Transaction | Boolean flag to signify a business transaction. | | Authorization Code | 6-digit authorization code for the transaction. | | System Trace Audit Number | Unique 6-digit transaction identifier generated by Nium. | | Retrieval Reference Number | 12 digit number used with other data elements as a key to identify and track a transaction. | | Processing Code | 6-digit processing code for the transaction. | | Pos Entry Mode | 2-digit mode of entry for the transaction being done at POS. | | Pos Entry Capability Code | 1-digit code that describes the capability of the POS terminal at which the transaction takes place. | | Pos Condition Code | 2-digit code that describes the condition under which the transaction takes place at the point of service. | | Original Authorization Code | Used for reversals. Authorization code of the transaction being reversed. | | Original Date of Transaction | Used for reversals. Original date and time of transactions. | | Original System Trace Audit Number | Used for reversals. System trace audit number (STAN) of the original transaction. | | Acquiring Institution Code | Acquiring institution code. | | Original Acquiring Institution Code | Used for reversals. Original Acquiring institution code. | | Acquiring Institution Country Code | Acquirer country code. | | Comments | System generated comments. | | Labels | Labels capturing miscellaneous information such as fee name, exchange rate, etc. | --- # Onboarding Summary URL: https://docs.nium.com/docs/reports/daily-reports/onboarding This once-a-day static report in CSV format contains the details of customers onboarded for a client during a day. It is irrespective of the customer’s KYC status. It may be setup on request. A client administrator can login to the Nium back-office and view or download the same in CSV format. It can also be delivered over SFTP on request. File naming convention: `Client_Customer_Onboarding_Report_{ClientHashId}_YYYYMMDD.csv` | Field | Description | | ------------------------------ | --------------------------------------------------------------------------- | | Date/Time of Customer Creation | Date/Time of customer creation, formatted as 24-hour `DD/MM/YYYY HH:mm:ss`. | | Customer Hash Id | Unique customer identifier \[36 character UUID]. | | Wallet Hash Id | Unique wallet identifier \[36 character UUID]. | | First Name | First name of the customer. | | Middle Name | Middle name of the Customer, if provided. | | Last Name | Last name of the customer. | | KYC Status | Overall KYC status of the customer. | --- # Ledger Summary URL: https://docs.nium.com/docs/reports/daily-reports/client-ledger-summary This once-a-day static report contains the ledger summary for the client. It may be setup on request. A client administrator can login to the Nium back-office and view or download the same. It can also be delivered over SFTP. File naming convention: `Client_Ledger_ Summary_Report_{clientHashId}_YYYYMMDD.csv` | Field | Description | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Client Name | Name of the client | | Client Hash ID | Unique customer identifier \[36 character UUID] | | Client Type | Client type - Wallet/RHA | | Currency | 3-letter ISO currency code for currency | | Opening Balance - Client Pool | Client pool opening balance in specified currency | | Closing Balance - Client Pool | Client pool closing balance in specified currency | | Credit Amount - Client Pool | Total amount of all credit transactions in specified currency in client pool | | Credit Count - Client Pool | Total count of all credit transactions in specified currency in client pool | | Debit Amount - Client Pool | Total amount of all debit transactions in specified currency in client pool | | Debit Count - Client Pool | Total count of all debit transactions in specified currency in client pool | | Opening Balance - Wallet Pool | Wallet pool opening balance in specified currency | | Closing Balance - Wallet Pool | Wallet pool closing balance in specified currency | | Credit Amount - Wallet Pool | Total amount of all credit transactions in specified currency in client pool | | Credit Count - Wallet Pool | Total count of all credit transactions in specified currency in client pool | | Debit Amount - Wallet Pool | Total amount of all debit transactions in specified currency in client pool | | Debit Count - Wallet Pool | Total count of all debit transactions in specified currency in client pool | | Debit Amount | Total amount of `Debit` transaction type in specified currency | | Debit Count | Total count of `Debit` transaction type in specified currency | | Reversal Amount | Total amount of `Reversal` transaction type in specified currency | | Reversal Count | Total count of `Reversal` transaction type in specified currency | | Original\_Credit Amount | Total amount of `Original_Credit` transaction type in specified currency | | Original\_Credit Count | Total count of `Original_Credit` transaction type in specified currency | | Original\_Credit\_Reversal Amount | Total amount of `Original_Credit_Reversal` transaction type in specified currency | | Original\_Credit\_Reversal Count | Total count of `Original_Credit_Reversal` transaction type in specified currency | | Partial\_Reversal Amount | Total amount of `Partial_Reversal` transaction type in specified currency | | Partial\_Reversal Count | Total count of `Partial_Reversal` transaction type in specified currency | | Incremental\_Auth\_Reveral Amount | Total amount of `Incremental_Auth_Reveral ` transaction type in specified currency | | Incremental\_Auth\_Reveral Count | Total count of `Incremental_Auth_Reveral ` transaction type in specified currency | | Client\_Prefund Amount | Total amount of `Client_Prefund` transaction type in specified currency | | Client\_Prefund Count | Total count of `Client_Prefund` transaction type in specified currency | | Client\_Refund Amount | Total amount of `Client_Refund` transaction type in specified currency | | Client\_Refund Count | Total count of `Client_Refund` transaction type in specified currency | | Wallet\_Refund Amount | Total amount of `Wallet_Refund` transaction type in specified currency | | Wallet\_Refund Count | Total count of `Wallet_Refund` transaction type in specified currency | | Wallet\_Credit\_Mode\_Card Amount | Total amount of `Wallet_Credit_Mode_Card Amount` transaction type in specified currency | | Wallet\_Credit\_Mode\_Card Count | Total count of `Wallet_Credit_Mode_Card Amount` transaction type in specified currency | | Wallet\_Credit\_Mode\_Prefund Amount | Total amount of `Wallet_Credit_Mode_Prefund` transaction type in specified currency | | Wallet\_Credit\_Mode\_Prefund Count | Total count of `Wallet_Credit_Mode_Prefund` transaction type in specified currency | | Wallet\_Credit\_Mode\_Offline Amount | Total amount of `Wallet_Credit_Mode_Offline` transaction type in specified currency | | Wallet\_Credit\_Mode\_Offline Count | Total count of `Wallet_Credit_Mode_Offline` transaction type in specified currency | | Wallet\_Credit\_Mode\_Prefund\_Cross\_Currency Amount | Total amount of `Wallet_Credit_Mode_Prefund_Cross_Currency` transaction type in specified currency | | Wallet\_Credit\_Mode\_Prefund\_Cross\_Currency Count | Total count of `Wallet_Credit_Mode_Prefund_Cross_Currency` transaction type in specified currency | | Wallet\_Credit\_Mode\_Offline\_Cross\_Currency Amount | Total amount of `Wallet_Credit_Mode_Offline_Cross_Currency` transaction type in specified currency | | Wallet\_Credit\_Mode\_Offline\_Cross\_Currency Count | Total count of `Wallet_Credit_Mode_Offline_Cross_Currency` transaction type in specified currency | | Customer\_Wallet\_Credit\_Fund\_Transfer Amount | Total amount of `Customer_Wallet_Credit_Fund_Transfer` transaction type in specified currency | | Customer\_Wallet\_Credit\_Fund\_Transfer Count | Total count of `Customer_Wallet_Credit_Fund_Transfer` transaction type in specified currency | | Customer\_Wallet\_Debit\_Fund\_Transfer Amount | Total amount of `Customer_Wallet_Debit_Fund_Transfer` transaction type in specified currency | | Customer\_Wallet\_Debit\_Fund\_Transfer Count | Total count of `Customer_Wallet_Debit_Fund_Transfer` transaction type in specified currency | | Wallet\_Fund\_Transfer Amount | Total amount of `Wallet_Fund_Transfer` transaction type in specified currency | | Wallet\_Fund\_Transfer Count | Total count of `Wallet_Fund_Transfer` transaction type in specified currency | | Settlement\_Debit Amount | Total amount of `Settlement_Debit` transaction type in specified currency | | Settlement\_Debit Count | Total count of `Settlement_Debit` transaction type in specified currency | | Settlement\_Credit Amount | Total amount of `Settlement_Credit` transaction type in specified currency | | Settlement\_Credit Count | Total count of `Settlement_Credit` transaction type in specified currency | | Settlement\_Reversal Amount | Total amount of `Settlement_Reversal` transaction type in specified currency | | Settlement\_Reversal Count | Total count of `Settlement_Reversal` transaction type in specified currency | | Settlement\_Direct\_Reversal Amount | Total amount of `Settlement_Direct_Reversal` transaction type in specified currency | | Settlement\_Direct\_Reversal Count | Total count of `Settlement_Direct_Reversal` transaction type in specified currency | | Settlement\_Direct\_Debit Amount | Total amount of `Settlement_Direct_Debit` transaction type in specified currency | | Settlement\_Direct\_Debit Count | Total count of `Settlement_Direct_Debit` transaction type in specified currency | | Fee\_Debit Amount | Total amount of `Fee_Debit` transaction type in specified currency | | Fee\_Debit Count | Total count of `Fee_Debit` transaction type in specified currency | | Fee\_Reversal Amount | Total amount of `Fee_Reversal` transaction type in specified currency | | Fee\_Reversal Count | Total count of `Fee_Reversal` transaction type in specified currency | | Remittance\_Debit Amount | Total amount of `Remittance_Debit` transaction type in specified currency | | Remittance\_Debit Count | Total count of `Remittance_Debit` transaction type in specified currency | | Remittance\_Debit\_External Amount | Total amount of `Remittance_Debit_External` transaction type in specified currency | | Remittance\_Debit\_External Count | Total count of `Remittance_Debit_External` transaction type in specified currency | | Remittance\_Reversal Amount | Total amount of `Remittance_Reversal` transaction type in specified currency | | Remittance\_Reversal Count | Total count of `Remittance_Reversal` transaction type in specified currency | | Wallet\_Hold Amount | Total amount of `Wallet_Hold` transaction type in specified currency | | Wallet\_Hold Count | Total count of `Wallet_Hold` transaction type in specified currency | | Wallet\_Unhold Amount | Total amount of `Wallet_Unhold` transaction type in specified currency | | Wallet\_Unhold Count | Total count of `Wallet_Unhold` transaction type in specified currency | | Fee\_Waiver Amount | Total amount of `Fee_Waiver` transaction type in specified currency | | Fee\_Waiver Count | Total count of `Fee_Waiver` transaction type in specified currency | | Cashback\_Credit Amount | Total amount of `Cashback_Credit` transaction type in specified currency | | Cashback\_Credit Count | Total count of `Cashback_Credit` transaction type in specified currency | | Cashback\_Credit\_Client Amount | Total amount of `Cashback_Credit_Client` transaction type in specified currency | | Cashback\_Credit\_Client Count | Total count of `Cashback_Credit_Client` transaction type in specified currency | | Chargeback\_Credit Amount | Total amount of `Chargeback_Credit` transaction type in specified currency | | Chargeback\_Credit Count | Total count of `Chargeback_Credit` transaction type in specified currency | | Wallet\_Credit\_Mode\_Offline\_ThirdParty Amount | Total amount of `Wallet_Credit_Mode_Offline_ThirdParty` transaction type in specified currency | | Wallet\_Credit\_Mode\_Offline\_ThirdParty Count | Total count of `Wallet_Credit_Mode_Offline_ThirdParty` transaction type in specified currency | | Auto\_Sweep Amount | Total amount of `Auto_Sweep` transaction type in specified currency | | Auto\_Sweep Count | Total count of `Auto_Sweep` transaction type in specified currency | --- # Transaction Summary URL: https://docs.nium.com/docs/reports/daily-reports/transaction-summary This once-a-day static report contains the total amount and count of each transaction type per authorization currency for the client. It may be setup on request. A client administrator can login to the Nium back-office and view or download the same. It can also be delivered over SFTP. File naming convention: `Client_Transaction_Summary_Report_{clientHashId}_YYYYMMDD.csv` | Field | Description | | ---------------- | ------------------------------------------------------------------------------- | | Client Name | Name of the client | | Client Hash ID | Unique client identifier \[36 character UUID] | | Transaction Type | Refer to the [Transaction types](/docs/transactions) guide for the description. | | Auth Currency | 3-letter ISO code for authorization currency. | | Total Amount | Sum of all entries per transaction type per authorization currency. | | Count | Count of all entries per transaction type per authorization currency. | --- # Client Reports URL: https://docs.nium.com/docs/reports/client-reports The following reports are available at the client level: - [Client Negative Wallet Balance](/docs/reports/client-reports/negative-wallet-balance) - [Client Transactions](/docs/reports/client-reports/client-transactions) - [Client Settlement Report V1](/docs/reports/client-reports/client-settlement-report-v1) - [Client Settlement Report V2](/docs/reports/client-reports/client-settlement-report-v2) --- # Negative Wallet Balance URL: https://docs.nium.com/docs/reports/client-reports/negative-wallet-balance This once-a-day static report contains the details of customers with a negative balance in any wallet currency at the time of report generation. It may be setup on request. A client administrator can login to the Nium back-office and view or download the same. It can also be delivered over SFTP. File naming convention: `Client_Negative_Wallet_Balance_Report_{clientHashId}_YYYYMMDDHHmmss.csv` | Field | Description | | ---------------- | ----------------------------------------------- | | Customer Hash ID | Unique customer identifier \[36 character UUID] | | Wallet Hash ID | Unique wallet identifier \[36 character UUID] | | Currency | 3-letter ISO currency code | | Balance | Negative balance amount \[with sign] | --- # Client Transactions URL: https://docs.nium.com/docs/reports/client-reports/client-transactions The Nium One platform generates a daily client transaction static report for you. The report includes all the transactions that you and your customers do in a 24-hour period. You can start using the report as soon as you're ready. Just ask one of your system administrators to set it up for you. ### How to get the report Sign in to the Nium One platform back-office and download your report. Use the secure SSH File Transfer Protocol. The file naming convention is: `Client_Transaction_Report__.csv`. ### Terminology This guide includes terms and descriptions that Nium customers use. See [Transactions](/docs/transactions) for more information. | Field | Description | Type | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `id` | Id of the consent to retrieve. | String | | `consent` | The consents details with specified status for a specific PSU. | Object | | `consent.consentStatus` | Authentication status of the consent. | String | | `consent.frequencyPerDay` | The requested maximum frequency for an access per day. | String | | `consent.validUntil` | Valid date for the requested consent. The content is the local ASPSP date in `ISODate` and the format is **2017-10-30**. | String | | `consent.lastActionDate` | The date of the last action on the consent object either through the XS2A interface or the PSU/ASPSP interface having an impact on the status. | String | | `consent.recurringIndicator` | Available values include: TRUE: The consent is for *recurring* access to the account data.FALSE: The consent is for *one* access to the account data. | Boolean | | `consent.access` | This is an object which holds access data fields. | Object | | `consent.access.allPsd2` | The only valid value is **allAccounts**. | String | | `consent.access.availableAccounts` | The only valid values are: allAccountsallAccountsWithBalances | String | | `consent.access.accounts` | Array which holds account detail fields. | Array | | `consent.access.accounts.iban` | International Bank Account Number (IBAN) of an account, for example: `FR7612345987650123456789014`. | String | | `consent.access.accounts.bban` | Basic Bank Account Number (BBAN) Identifier. This data element is used for payment accounts which have no IBAN, for example: BARC12345612345678. | String | | `consent.access.accounts.currency` | The 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `consent.access.accounts.maskedPan` | Primary Account Number (PAN) of a card in a masked form. This is used for card account in responses, for example 1234. Maximum length: 35 | String | | `consent.access.accounts.msisdn` | An alias to access a payment account via a registered mobile phone number. Maximum length: 35 | String | | `consent.access.accounts.pan` | Primary Account Number (PAN) of a card, can be tokenized by the ASPSP due to PCI DSS requirements. This is used for card account in responses. Maximum length: 35 | String | | `consent.access.balances` | Array which holds balance detail fields. | Array | | `consent.access.balances.iban` | International Bank Account Number (IBAN) of an account balance, for example: FR7612345987650123456789014. | String | | `consent.access.balances.bban` | Basic Bank Account Number (BBAN) Identifier. | String | | `consent.access.balances.currency` | The 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `consent.access.balances.maskedPan` | Primary Account Number (PAN) of a card in a masked form. This is used for card account in responses, for example 1234. Maximum length: 35 | String | | `consent.access.balances.msisdn` | An alias to access a payment account via a registered mobile phone number. Maximum length: 35 | String | | `consent.access.balances.pan` | Primary Account Number (PAN) of a card, can be tokenized by the ASPSP due to PCI DSS requirements. This is used for card account in responses. Maximum length: 35 | String | | `consent.access.transactions` | This is an array which holds transaction detail fields. | Array | | `consent.access.transactions.iban` | International Bank Account Number (IBAN) of an account, for example: FR7612345987650123456789014. | String | | `consent.access.transactions.bban` | Basic Bank Account Number (BBAN) Identifier. | String | | `consent.access.transactions.currency` | The 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `consent.access.transactions.maskedPan` | Primary Account Number (PAN) of a card in a masked form. This is used for card account in responses, for example 1234. Maximum length: 35 | String | | `consent.access.transactions.msisdn` | An alias to access a payment account via a registered mobile phone number. Maximum length: 35 | String | | `consent.access.transactions.pan` | Primary Account Number (PAN) of a card, can be tokenized by the ASPSP due to PCI DSS requirements. This is used for card account in responses. Maximum length: 35 | String | | `consent.scaStatus` | Multiple level SCA approach in a corporate PSU context. | Object | | `consent.scaStatus.otp` | The PSU can authorize the consent using the OTP code received as part of SCA process. | String | | `consent.scaStatus.scaApproach` | This data element must be contained if the SCA approach is already fixed. The possible values are: EMBEDDEDDECOUPLEDREDIRECT The OAuth SCA approach will be subsumed by REDIRECT. | String | | `consent.scaStatus.scaRequred` | If the SCA is required for consent or not. | Boolean | | `consent.scaStatus.status` | The consent authorization status. | String | | `consent.scaStatus.tppNokRedirectUrl` | Redirect URL for the failure response. | String | | `consent.scaStatus.tppRedirectUrl` | Redirect URL for the success response. | String | | `payment` | One or more processes that implement the business logic related to payment flows such as payment initiation, single payment execution, including security checks, logging, etc. | String | --- # Client Settlement Report V1 URL: https://docs.nium.com/docs/reports/client-reports/client-settlement-report-v1 ⚠️ WARNING > ⚠️ WARNING > > This report version is deprecated. Refer to the [Client Settlement Report V2](/docs/reports/client-reports/client-settlement-report-v2) for the latest version. This report will become unavailable after Jun 2024. The Client Settlement Report serves to update you on the final status of transactions following card scheme settlements. This report is purely for informational purposes, and clients are not required to undertake any additional processing on their part. The balances within the Nium platform have already been adjusted accordingly, and the transaction status will be updated accordingly. This report is applicable for all models of dynamic authorization. If you are using the Delegated Model of Dynamic Authorization, you should continue to receive and process the daily settlement file outlined in [section 2.2](/docs/cards/dynamic-authorization/delegated-model#22-file-format). The Nium platform generates a daily report for you, encompassing all settlements sent by schemes within the last 24 hours. To start receiving settlement reports, contact your Nium representative. Once enabled, this report can be downloaded from the Nium Portal or delivered to you over Secure File Transfer Protocol (SFTP). ## Terminology The below table provides descriptions for the data provided in the client settlement report V1. | Field Header | Sample Value/Format | Description | | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Batch Date | **20210121 \[YYYYMMDD]** | Date when settlement file is processed. | | Effective Date | **20210118 \[YYYYMMDD]** | Date from when the transaction is effective. | | Posting Date | **20210118 \[YYYYMMDD]** | Date from when the transaction is posted to customer account/wallet. | | File Name | **FV\_MONTX\_YYYYMMDDHHmmss.TXT.pgp** | Name of scheme settlement file. It's a PGP encrypted file. | | Status | Available values include: **SUCCESS****PENDING****FAILED** | Transaction settlement status. | | Client Hash ID | **5a860711-8a50-4619-1e4b-24c03560b7xz** | Client hash identifier (ID) is a unique 36-char UUID. | | Customer Hash ID | **6a450711-2r50-1211-1e4b-12c03780b7qw** | Customer hash identifier (ID) is a unique 36-char UUID. | | Card Hash Id | **3f860722-9f50-4689-9e3b-16c03560b7fc** | Card hash identifier (ID) is a unique 36-char UUID. | | Masked Card Number | **4111-XXXX-XXXX-1111** | Masked PAN | | Authorization Code | **A45FR3** | 6-character approval code for a transaction. | | Transaction type | Available values include: **D****C** | Transaction identifier that shows if it's Debit or Credit. | | Account Number | **7561010103710131131** | Cardholder account number/ Proxy number | | Transaction Currency | Available values include: **SGD****AUD** | 3-character ISO3 currency code. | | Transaction Amount | **AAAAAAAAAAAAAAATDDDD** | Transaction amount in format (15,1,4): **A** indicates the amount, **T** indicates the dot separating the decimal, **D** indicates the decimal. Example: 500.45 USD as **000000000000500.4500**. | | Billing Currency | Available values include: **SGD****AUD** | 3-character ISO3 currency code. | | Billing Amount | **AAAAAAAAAAAAAAATDDDD** | Billing amount in format (15,1,4). Example: 500.45 USD as **000000000000500.4500**. | | Region | Available values include: **SG****HK****AU** | 2-letter ISO country code depicting region. | | Interchange Fee Sign | Available values include: **+****-**blank | **+** for Positive, **-** for Negative. | | Interchange Fee | **AAAAAAAAAAAAAAATDDDD** | Transaction interchange fee as determined by the scheme. | | Original interchange fee sign | Available values include: **+****-**blank | **+** for Positive, **-** for Negative. | | Original interchange fee | **AAAAAAAAAAAAAAATDDDD** | Transaction interchange fee as determined by the scheme. | | Issuer Markup | | Issuer Markup if it's configured. | | Exchange Rate Sign | Available values include: **+****-**blank | **+** for Positive, **-** for Negative. | | Exchange Rate | **0** | This field shall contain zero. | | Transaction Code Sign | **Blank** | Blank/Empty | | Transaction Code | **2051** | Identifies the nature of the transaction made and whether a debit, credit or memo. | | Merchant ID | **233062644221291** | Unique Id of the Merchant where the card was used. | | Merchant Category Code | **5814** | Alpha-numeric code identifying the merchant operating the POS/ATM. | | Merchant Name Location | **APC CORP Singapore SG** | Merchant Name and Location details. | | Merchant Country Code | **SGP** | 3-letter ISO country code of the merchant | | Ref Number | **MT233410132000010002589** | Reference number shared by the scheme. | | Visa Transaction ID | **MDH4ABC123456** | Unique transaction identifier from Visa or MasterCard. | | Interchange Reference | **78600000317792070999001** | Interchange reference on transaction provided by merchant. | | Original Payment Amount Sign | Available values include: **+****-**blank | **+** for Positive, **-** for Negative. | | Original Payment Amount | **0** | This field usually has 0 or blank. | | Original Transaction Code | **0** | This field usually has 0 or blank. | | Rolled Amount Sign | Available values include: **+****-** | **+** for Positive, **-** for Negative. | | Rolled Amount | **0** | This field usually has 0 or blank. | | Pos Entry Mode | **07** | A Point-of-Service (POS) entry mode identifies the mode in which a transaction is initiated at the point of service. | | Point of Service | **M90901M99996** | Alphanumeric code that identifies the card acceptor for defining the point of service terminal. | | ECOM Transaction | Available values include: **5****6****7****S** | Identifies whether the transaction is an electronic commerce transaction. | | Matched Authorization | Available values include: **Y****N** | This field will contain Y or N depending on whether the settlement was matched with an original transaction. | | Multi Clearing | Available values include: **M****F** | Indicates if the transaction is fully or partially settled. M - Indicates Multiple, F - Indicates Final. | | Recurring Transaction | Available values include: **1****0** | If it's a recurring transaction, then the value will be **1** else it will be **0**. | | Recurring MCC | **4101** | Recurring MCC Code. | | Card Block Code | **Black** | Alphanumeric value if the card has any block code. | | Record Type | **M** | 1-letter record type. It will have the value **"M"** | | Payment Indicator | Available values include: **B****G****P**Blank/Empty | Indicates the type of payment. Valid values are: B = Branch payment, G = GIRO payment, P = Postal payment. | | Fraud Matched Flag | Available values include: **Y****N**Blank/Space | Flag to indicate fraud. Valid values are: Y - Fraud Matched, N - Fraud Not Matched. | | Digital Card Indicator | Available values include: **1****0** | If the transaction was done using Apple or Google wallets, it will have the value of **1** otherwise **0**. | | Sms Dms Indicator | **Space** | Single or Dual message indicator. | | Wsp ID | Available values include: **216 - Google****103 - Apple** | Wallet service provider ID. | | Wsp | | Wallet service provider. | | Token Requester ID | **ex: 50120834693** | Unique identifier of Token requestor. | | Token Number | **16 digit number generated by scheme** | For tokenized transactions, it will have corresponding token number details that are shared by the schemes. | | Comments | **"Transaction settled"** | System-generated comments based on the settlement record processing. | | Created By | **"SYSTEM"** | This field contains **"SYSTEM"** | | Created Date | **12/01/2021 11:13:12 pm** | Creation timestamp in format DD/MM/YYYY HH:MM AM/PM | | Modified By | **SYSTEM** | This field contains **"SYSTEM"** | | Modified Date | **12/01/2021 11:13:12 pm** | Modification timestamp in format DD/MM/YYYY HH:MM AM/PM | --- # Client Settlement Report V2 URL: https://docs.nium.com/docs/reports/client-reports/client-settlement-report-v2 The Client Settlement Report serves to update you on the final status of transactions following card scheme settlements. This report is purely for informational purposes, and clients are not required to undertake any additional processing on their part. The balances within the Nium platform have already been adjusted accordingly, and the transaction status will be updated accordingly. This report is applicable for all models of dynamic authorization. If you are using the Delegated Model of Dynamic Authorization, you should continue to receive and process the daily settlement file outlined in [section 2.2](/docs/cards/dynamic-authorization/delegated-model#22-file-format). The Nium platform generates a daily report for you, encompassing all settlements sent by schemes within the last 24 hours. To start receiving settlement reports, contact your Nium representative. Once enabled, this report can be downloaded from the Nium Portal or delivered to you over Secure File Transfer Protocol (SFTP). ## Terminology The below table provides descriptions for the data provided in the client settlement report V2. | Field Header | Sample Value/Format | Field Description | | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Authorization Date | **01/04/2021** | Date when transaction was authorized by Nium. | | Settlement Date | **03/04/2021** | Date from when the transaction was settled by Nium. | | Status | Available values include: **SUCCESS****PENDING****FAILED** | Settlement status. | | Client Hash ID | **5a860711-8a50-4619-1e4b-24c03560b7xz** | Client hash identifier (ID) is a unique 36-char UUID. | | Customer Hash ID | **6a450711-2r50-1211-1e4b-12c03780b7qw** | Customer hash identifier (ID) is a unique 36-char UUID. | | Card Hash Id | **3f860722-9f50-4689-9e3b-16c03560b7fc** | Card hash identifier (ID) is a unique 36-char UUID. | | Masked Card Number | **4111-XXXX-XXXX-1111** | Masked PAN | | Authorization Code | **A45FR3** | 6-character approval code for a transaction. | | Transaction Sign | Available values include: **D****C** | Transaction identifier that shows if it's Debit or Credit. | | Card Proxy Number | **Ex: 7561010103710131131** | Cardholder account number/ Proxy number | | Transaction Currency | Available values include: **SGD****AUD** | 3-character ISO3 currency code. | | Transaction Amount | **AAAAAAAAAAAAAAATDDDD** | Transaction amount in format (15,1,4): **A** indicates the amount, **T** indicates the dot separating the decimal, **D** indicates the decimal. Example: 500.45 USD as **000000000000500.4500**. | | Local Transaction Currency | Available values include: **SGD****AUD** | 3-character ISO3 currency code. | | Local Transaction Amount | **AAAAAAAAAAAAAAATDDDD** | Transaction amount in format (15,1,4). Example: 500.45 USD as **000000000000500.4500**. | | Billing Currency | Available values include: **SGD****AUD** | 3-character ISO3 currency code. | | Billing Amount | **AAAAAAAAAAAAAAATDDDD** | Billing amount in format (15,1,4). Example: 500.45 USD as **000000000000500.4500**. | | Settlement Currency | Available values include: **SGD****AUD** | 3-character ISO3 currency code. | | Settlement Amount | **AAAAAAAAAAAAAAATDDDD** | Settlement amount in format (15,1,4). Example: 500.45 USD as **000000000000500.4500**. | | Region | Available values include: **SG****HK****AU** | 2-letter ISO country code depicting region. | | Interchange Fee Sign | Available values include: **+****-**blank | **+** for Positive, **-** for Negative. | | Interchange Fee | **AAAAAAAAAAAAAAATDDDD** | Transaction interchange fee as determined by the scheme. | | Original interchange fee sign | Available values include: **+****-**blank | **+** for Positive, **-** for Negative. | | Original interchange fee | **AAAAAAAAAAAAAAATDDDD** | Transaction interchange fee as determined by the scheme. | | Issuer Markup | | Issuer Markup if it's configured. | | Exchange Rate Sign | Available values include: **+****-**blank | **+** for Positive, **-** for Negative. | | Exchange Rate | **0** | This field shall contain zero. | | Transaction Code Sign | **Blank** | Blank/Empty | | Transaction Code | **2051** | Identifies the nature of the transaction made and whether a debit, credit or memo. | | Merchant ID | **233062644221291** | Unique Id of the Merchant where the card was used. | | Merchant Category Code | **5814** | Alpha-numeric code identifying the merchant operating the POS/ATM. | | Merchant Name Location | **ABC CORP Singapore SG** | Merchant Name and Location details. | | Merchant Country Code | **SGP** | 3-letter ISO country code of the merchant | | Ref Number | **MT233410132000010002589** | Reference number shared by the scheme. | | Scheme Transaction Id | **MDH4ABC123456** | Unique transaction identifier from Visa or MasterCard. | | STAN | **636181** | Field contains a number assigned by the message initiator that uniquely identifies a cardholder transaction. | | RRN | **383810121011** | Acquirer usually defines it, but a merchant or an electronic terminal may define it. | | Interchange Reference | **78600000317792070999001** | Interchange reference on transaction provided by the merchant. | | Pos Entry Mode | **07** | A Point-of-Service (POS) entry mode identifies the mode of transaction initiation at the point of service. | | ECOM Transaction | Available values include: **5****6****7****S** | Identifies whether the transaction is an electronic commerce transaction. | | Matched Authorization | Available values include: **Y****N** | Indicates if the settlement was matched with an original transaction. | | Multi Clearing | Available values include: **M****F** | Indicates if the transaction is fully or partially settled. **M** - Indicates Multiple, **F** - Indicates Final. | | Recurring Transaction | Available values include: **1****0** | If it's a recurring transaction, then the value will be **1** else it will be **0**. | | Wallet Provider | Available values include: **216- Google****103- Apple** | Wallet service provider Id | | Batch Date | **12/01/2021** | Date when settlement transactions were processed. | | Comments | **Transaction settled** | System-generated comments based on the settlement record processing. | | Created By | **SYSTEM** | This field contains **SYSTEM** | | Created Date | **12/01/2021 11:13:12 pm** | Creation timestamp in format DD/MM/YYYY HH:MM AM/PM | | Modified By | **SYSTEM** | This field contains **SYSTEM** | | Modified Date | **12/01/2021 11:13:12 pm** | Modification timestamp in format DD/MM/YYYY HH:MM AM/PM | --- # Settlement Report URL: https://docs.nium.com/docs/reports/client-reports/settlement-report Nium generates a daily client settlement report to help you reconcile transactions. The report includes the following transaction types: - **Payins**: Successful transactions credited to a customer's wallet, including wallet funding, collections, direct debit reversals, and payout reversals. - **Payouts**: Transactions with a remittance `status` of **PAID** and reversals with status **RETURN**. - **P2P**: Transfers (credits or debits) between client wallets. - **Fees**: Charges and reversals associated with other transactions. - **Foreign exchange (FX)**: Currency conversion charges applied when funds are exchanged between currencies. The table below describes each field in the settlement report: | **Field** | **Description** | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Wallet ID | Unique identifier of the wallet (`walletHashId`) associated with the transaction. | | Virtual Account Number | Virtual account number associated with the Payin transaction. | | Transaction Type | Type of transaction. See [Transaction types](/docs/transactions) for details. | | Transaction ID | Unique identifier for the transaction in the Nium One platform. | | External ID | Client-defined transaction ID used for reconciliation. | | Amount | Amount credited to or debited from the wallet. | | Currency | Currency used in the settlement. | | Credit/Debit | Indicates whether the wallet was credited or debited. | | Transaction Date | Timestamp for when the transaction was initiated.**Payin**: Date/time the credit was received by Nium.**Payout**: Date/time the remittance was initiated.**Format**: `DD-MM-YYYY hh:mm:ss` | | Settlement Date | The date the transactions was settled (i.e., settlement date). **Format**: `DD-MM-YYYY` | | Tags | Tags associated with the transaction. | ## Download the report To download a settlement report: 1. Log in to the [Nium Portal](https://app.nium.com), then go to **Reports** > **Scheduled**. 2. On this page, you can schedule settlement reports to run at any interval. - For more information, see the [Nium Portal reports guide](/docs/nium-portal/reports). 3. You can also request delivery via secure SSH File Transfer Protocol (SFTP). - Contact your Nium account manager or [Nium Support](mailto:support@nium.com) if you have any questions. Downloaded reports follow this naming convention: ``` SETTLEMENT_REPORT__.csv ``` --- # Customer Account Statements URL: https://docs.nium.com/docs/reports/customer-account-statements An account statement lists every transaction you make on the Nium One platform, including deposits, withdrawals, spending, fees, payments, refunds, and so forth. As a client offering a financial account to your customers, you can give your customers an account statement either periodically or based on their specific requests. An account statement helps your customers keep the information for their records to reconcile their transactions. It also helps them analyze their account activity. You can generate an account statement for your customers using the [Report APIs](/api#tag/reports) — a unified set of APIs designed to support multiple report types. This means you integrate once and can access different report types in the future without additional API integrations. - Clients can generate an account statement via an API and user interface. - A multicurrency account statement is a single document that lists all transactional activity across the currencies. - A currency-wise statement gives the flexibility to download statements in your desired currency. - A customizable frequency to download account statements. - An account statement can be downloaded any time and contain up to six months' worth of data. - An account statement is available in CSV and PDF file formats. | Format | Best used for | Other benefits | | ------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------- | | CSV | Customization, data analysis, and integration with other software. | This format is standard for all clients. | | PDF | An accurate representation for reviewing and printing. | Client-specific template with the client's logo and support email address. | ## Configure your account statement If you want to use this feature, you need to contact your Nium representative and provide the below details: - Your logo to be included in the statement. - Logo file — Saved in a public-domain file type, such as JPG, PNG, and PDF. - Logo dimensions — The maximum height is 60 pixels. The width is taken based on the logo's aspect ratio. - Logo size — The maximum file size is 250 KB. - The email address of your customer support team for customers to raise any issue regarding the statement. It's placed under the Important section at the bottom of the PDF. Nium makes use of the above details and works with you to finalize the statement template to be defined in the system and ready for use. ## Use your account statement A typical account statement contains the following: - Account holder's name and address - Period of statement - Wallet hash ID of the customer - Balance summary — the opening and closing balance of each currency - Currency-wise transaction details. The transactions made in each currency during the statement period, including deposits, withdrawals, transfers, fees, and exchange rates used for currency conversions. The filename uses dates in YYYY-MM-DD format and its naming convention is either: - `Account_statement_-.csv` - `Account_statement_-.pdf` Example file name: `Account_statement_2023-02-15-2023-03-14.csv` ## Generate a statement To generate an account statement: 1. Request a statement using the [Report APIs](/api#tag/reports) request. Nium receives the request and starts generating the report. 2. Once the account statement is generated, Nium sends the [Report Generation Status](#report-generation-status) webhook. 3. Use the webhook status to decide what to do next: - If `status` is `COMPLETED`, download the statement using the [Download Generated Report](/api#tag/reports/GET/api/v1/client/{clientHashId}/report/{reportRequestId}/download) request. - If `status` is `FAILED`, request the statement again and wait for the next webhook update. ## Push a statement to SFTP In addition to downloading the account statement via the View Account Statement request, Nium can push the generated report directly to your SFTP server. This is useful if you prefer to automate retrieval without calling the API after every webhook. To set up SFTP delivery, contact your Nium representative with your SFTP server details. The following authentication types are supported: - **Password-based** — authenticate using a username and password. - **SSH key-based** — authenticate using a private SSH key. - **SSH key + password-based** — authenticate using both a private SSH key and a password. Once configured, the report is automatically pushed to your SFTP server after the Report Generation Status webhook fires with `status: COMPLETED`. You do not need to call the View Account Statement request separately in this case. ## Nium API & webhook requests ### Requests | API Requests | Endpoint | Description | | -------------------------- | --------------------------------------------------------------------- | ------------------------------------------ | | Initiate Report Generation | `POST /api/v1/client/{clientHashId}/report` | Request to generate the account statement. | | Download Generated Report | `GET /api/v1/client/{clientHashId}/report/{reportRequestId}/download` | Get the generated account statement. | ### Webhook | Webhook Requests | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Report Generation Status | Webhook to provide the status of account statement generation. If `status` = `COMPLETED`, call the View Account Statement request to view the account statement. | #### Report Generation Status This event is triggered when the requested report status is changed. The report is either successfully generated or failed. ``` https:///webhook ``` **Header** | Field | Description | | -------------- | ---------------- | | `Content-Type` | application/json | **Request example** ```curl curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name": "REPORT_GENERATION_STATUS", "requestedAt": "2026-01-22T10:30:00Z", "generatedAt": "2026-01-22T10:45:30Z", "reportRequestId": "6fde3c79-aa16-40f0-bcd9-3d542d3d9880", "status": "COMPLETED", "message": "Report generated successfully. File is ready for download." }' ``` **Response body** | Field | Description | Type | | ----------------- | ---------------------------------------------------------------------------------------------------------------------- | ------ | | `name` | The name of the webhook — `REPORT_GENERATION_STATUS`. | string | | `requestedAt` | This field contains the report requested date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | string | | `generatedAt` | This field contains the report generated date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | string | | `reportRequestId` | The unique report identifier that's generated when the report is requested for which the webhook is triggered. | string | | `status` | The status of the generated report as `COMPLETED` or `FAILED`. | string | | `message` | The message for the above status if the report is generated successfully or not. | string | ## Transaction types The below tables list transaction types and their naming convention on the account statements. **Payin and Payout transactions** | Transaction type | Naming convention | Description | | -------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Customer wallet credit fund transfer | Account-to-account transfer | The funds received in the wallet from another customer's wallet of the same client. | | Customer wallet debit fund transfer | Account-to-account transfer | The funds sent from a wallet to another customer's wallet of the same client. | | Customer wallet debit intra region | Account-to-account transfer | The funds sent from a wallet to another customer's wallet of a different client but of the same regulatory region. | | Customer wallet credit intra region | Account-to-account transfer | The funds received from a wallet to another customer's wallet of a different client but of the same regulatory region. | | Customer wallet debit cross region | Account-to-account transfer | The funds sent from a wallet to another customer's wallet of a different client and of a different regulatory region. | | Customer wallet credit cross region | Account-to-account transfer | The funds received from a wallet to another customer's wallet of a different client and of a different regulatory region. | | Regulatory auto sweep | PLAIS auto sweep | For European Economic Area (EEA) regulatory requirements, this transaction includes the amount moved from any other currency to the European Monetary Unit (EUR). This is the requested block currency by the regulator, in case of a block instruction. In addition, this is valid if there's insufficient balance in EUR for blocking. | | Regulatory block | PLAIS block | For EEA regulatory requirements, this transaction includes the amount moved to the blocked amount from EUR. This is the requested block currency by the regulator, in case of a block instruction. | | Regulatory debit | PLAIS debit | For EEA regulatory requirements, this transaction includes the amount debited from the block amount or wallet balance of EUR. This is the requested block currency by the regulator. This is valid when the regulator asks to send the blocked amount to a beneficiary. | | Remittance debit / Remittance debit external | Outward fund transfer | Remittance debit: The debit from the wallet for remittance to one's own account.Remittance debit external: The debit from the wallet for remittance to another account. | | Remittance reversal | Outward fund transfer — returned | The reversal of a remittance transaction. | | Wallet credit mode card | Funding | The fund credit to a wallet using a card. | | Wallet credit mode offline | Inward fund transfer | The fund credit to a wallet using an offline mode, such as a bank transfer, from the customer's own account. | | Wallet credit mode prefund | Funding | The fund credit to a wallet using a client prefund. | | Wallet credit mode prefund cross currency | Funding | The cross-currency fund credit to a wallet using a client prefund. | | Wallet credit mode offline third-party | Inward fund transfer | The fund credit to a wallet, in the same currency, using an offline mode, such as a bank transfer from a third party. | | Wallet fund transfer | Exchanged | The fund transfer within a wallet, from one currency pool to another. | | Wallet refund | Unload | The refund money from the wallet back to the client. | | Regulatory debit reversal | PLAIS reversal | For EEA regulatory requirements, this transaction includes the amount returned in case of a failed Regulatory\_Debit remittance. | | Transfer local | Local fund transfer | The local payments debited from the wallet through the payment initiation service (PIS) open banking. | | Transfer local reversal | Local fund transfer — Returned | The local payments that are credited or reversed from the wallet through the PIS open banking. | **Card transactions** | Transaction type | Naming convention | Description | | -------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Auto sweep | Exchanged | Automatically sweep from one currency to another within a wallet to authorize a transaction if multicurrency auto-sweep is set up. | | Chargeback credit | Dispute credit | Credit transaction in the case of a chargeback. | | Debit | Spend | Card transactions, such as POS and ECOM. | | Debit | Cash withdrawal | Card transactions — ATM only. | | Original credit | Merchant credit | Receiving incoming Original Credit Transfer (OCT) and credit to the wallet linked to the cardholder's card. | | Reversal | Reversal | Online reversal of a transaction. | | Reversal advice | Reversal advice | Reversal is initiated when a timeout scenario happens. If Visa or Mastercard time out a card transaction, they generate a reversal advice to roll back the transaction. In the case of wallet clients, Nium applies the reversal advice and provides the credit back to the customer. In the case of Delegated Model authorization clients, Nium reverses funds on the client prefund account and forwards the reversal advice to the Delegated Model authorization client for crediting funds back to the customer. | | Settlement credit | Refund | Funds are credited to the cardholder's wallet when the settlement amount, processed during clearing, is less than the transaction amount, processed during the authorization. | | Settlement debit | Additional charge | Funds are debited from the cardholder's wallet when the settlement amount, processed during clearing, is more than the transaction amount, processed during the authorization. | | Settlement direct debit | Spend | Funds are debited from the cardholder's wallet for transactions based on the settlement file; for example, force posting. | | Settlement direct reversal | Transaction reversal | Funds are credited to the cardholder's wallet for the reversal of a debited transaction based on the settlement file. | | Settlement reversal | Refund | Funds are credited to the cardholder's wallet for the reversal of a debited transaction. | **Fee transactions** | Transaction type | Naming convention | Description | | ----------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Account inactive fee | Monthly account inactivity fee | Monthly fee charged for inactive accounts. | | Account maintenance fee | Monthly account maintenance fee | Monthly fee charged for account maintenance. | | Add-on card fee | New add-on card fee | Per card issuance fee charged for each add-on card issuance. | | ATM decline fee | Fee for declined cash withdrawal | Per transaction fee charged on an ATM transaction decline. | | ATM fee | Fee for cash withdrawal | Per transaction fee charged on an ATM transaction. | | Ecom fee | Fee for online purchases | Per transaction fee charged on e-commerce or online transactions. | | International ATM fee | Fee for international cash withdrawal | Per transaction fee charged on an international ATM transaction. | | Non-ATM Decline Fee | Fee for a declined transaction | Per transaction fee charged on a non-ATM transaction decline. | | P2P fee | Fee for account-to-account transfer | Per transaction fee charged on a P2P fund transfer. | | Plastic fee | New plastic card issuance fee | One-time physical card issuance fee. | | Remit bank fee | Fee for outward fund transfer | Per transaction fee charged on Remittance\_Debit and Remittance\_Debit\_External transactions when the `payoutMethod` = `LOCAL`. | | Remit bank fee swift | Fee for outward fund transfer | Per transaction fee charged on Remittance\_Debit and Remittance\_Debit\_External transactions when the `payoutMethod` = `SWIFT`. | | Remit card fee | Fee for outward fund transfer | Per transaction fee charged on Remittance\_Debit transactions when the `payoutMethod` = `CARD`. | | Remit cash fee | Fee for outward fund transfer | Per transaction fee charged on Remittance\_Debit transactions when the `payoutMethod` = `CASH`. | | Remit wallet fee | Fee for outward fund transfer | Per transaction fee charged on Remittance\_Debit transactions when the `payoutMethod` = `WALLET`. | | Transaction markup | Fee for foreign transaction | Per transaction fee charged on cross-currency transactions when the transaction currency is different from the authorized currency. | | Virtual card fee | New virtual card issuance fee | One-time virtual card issuance fee. | | Wallet credit offline fee | Fee for inward fund transfer | Per payin transaction fee when the customer is a remitter (self-funding). | | Wallet credit third-party fee | Fee for inward fund transfer | Per payin transaction fee when the customer isn't the remitter. | | Wallet refund fee | Fee for unload funds to program | Per transaction fee charged on wallet refund. | --- # Open Banking URL: https://docs.nium.com/docs/open-banking Open banking allows secure access to European bank account data and payment services through Nium's standardized open banking APIs. Open banking helps financial institutions, third-party providers (TPPs), and fintech platforms offer innovative banking experiences while ensuring compliance with global regulations like PSD2 (Payment Services Directive Two). Open banking allows secure access to European bank account data and payment services through Nium's standardized open banking APIs. Open banking helps financial institutions, third-party providers (TPPs), and fintech platforms offer innovative banking experiences while ensuring compliance with global regulations like **PSD2** (Payment Services Directive Two). With Nium's Open Banking solutions, you can: - Access **Account Information Services (AIS)** to fetch customer account details. - Use **Payment Initiation Services (PIS)** to initiate and manage payments securely. Whether you're a **Nium client** looking to integrate Open Banking into your systems or a **third-party provider** (TPP) interacting with Nium customers, this section guides you through: - [Client Integration](/docs/open-banking/client-integration): As a Nium client, learn how to connect with our open banking APIs to handle account details and payment workflows. - [Third-Party Integration](/docs/open-banking/third-party-integration): Learn how TPPs access customer data and provide services through Nium's standardized Open Banking APIs. By integrating with Nium's Open Banking APIs, you can: - **Simplify your integration**: Easy-to-use APIs streamline the connection between your system and Nium's ecosystem. - **Ensure compliance**: Fully aligned with PSD2 regulations to ensure secure data sharing and customer consent. - **Create a seamless user experience**: Securely redirect customers for authentication and deliver clear transaction updates. --- # Client Integration URL: https://docs.nium.com/docs/open-banking/client-integration Account information service (AIS) flow ## Account information service (AIS) flow As part of the Nium PSD2 Open Banking AIS flow, Nium provides APIs for fetching consolidated customer account information, based on authorization and customer consent. As a Nium One client, you need to integrate with the Nium ecosystem for Open Banking AIS as described below. ### Step 1: Provide your client AIS redirect URL Nium stores the consent ID and sends details about customer identification and reference number on a pre-configured client AIS redirect URL to you. Then, you need to provide your client redirect URL during your program setup. You need to implement your own authentication mechanism to authenticate AIS requests received. ### Step 2: Get the consent detail To authenticate the customer, fetch the consent details by calling the [Account Details By Customer Consent ID.](/api#tag/open-banking-onboarding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/consent/account) API and display it on the authorization page. #### Query parameter | Field | Description | | ----- | --------------------------------------------------------- | | `id` | The account consent ID of the customer to fetch the data. | ### Step 3: Update the customer consent status Update the customer’s response against the consent ID by calling the Nium [Account Details By Customer Consent ID.](/api#tag/open-banking-onboarding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/consent/account) API to update the customer's consent as received. This step can be used later to update the consent status if the customer revokes the consent. ```URL GET https://gateway.nium.com/api/v1/consent/{accountConsentId}?status={consentStatus} ``` #### Path parameter | Field | Description | | ------------------ | ---------------------------------------------------------------- | | `accountConsentId` | The account consent ID for which the status needs to be updated. | #### Query parameter | Field | Description | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | The status of the customer consent. It may be `AUTHORIZED` when the customer has provided consent. Otherwise, it may be updated to `REJECTED` at Nium if the customer has revoked consent or opted out. | The AIS flow is now complete and the TPP can redirect the customer and display the details accordingly. ## Payment initiation service (PIS) flow As a part of the Nium PSD2 Open Banking PIS flow, Nium provides APIs for initiating a payout based on whether the Strong Customer Authentication (SCA) requirement is needed or not. As a Nium One client, you need to integrate with the Nium ecosystem for the Open Banking PIS as described below. When a payout transaction is initiated, internal validations are run. The transaction is also checked to see if SCA is required. In case there's an internal validation failure, the transaction status becomes REJECTED. ### Step 1: Redirect to the authorization page URL In cases where SCA is required, Nium redirects the customer to a pre-configured URL that you provide for authentication. You need to provide your client redirect URL during the client program setup. You also need to implement your own SCA authentication mechanism to authenticate your PIS requests. ```URL GET https://?authType=PAYMENT&customerHashId={customerHashId}&referenceNumber={systemReferenceNumber} ``` #### Path parameter | Field | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------- | | customerHashId | This parameter contains the Nium customer's universally unique identifier (UUID) | | referenceNumber | This parameter contains the Nium transaction authorization reference UUID, also known as `systemReferenceNumber` at Nium. | ### Step 2: Fetch the payment details To authenticate the customer, fetch the payment details by calling the [Payment Details By System Reference Number](/api#tag/open-banking-onboarding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/consent/payment) API and display it on the authorization page. This API lets you fetch payment details using the transaction system reference number as part of the Open Banking PIS flow and based on the customer's consent. ```URL GET https://gateway.nium.com/api/v1/payment/{systemReferenceNumber}/detail ``` You can now continue with an authorization that may succeed or fail. In both cases, you trigger the Nium API to update the authorization status. ### Step 3: Update the authorization status ```URL GET https://gateway.nium.com/api/v1/payment/{systemReferenceNumber}?status={status} ``` #### Query parameter | Field | Description | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | status | This query parameter accepts two values which are `APPROVED` and `REJECTED`. If the status is `APPROVED`, the transaction status is `INITIATED`. It then goes through the [lifecycle of a transaction](/docs/payouts/transfer-money/remittance-lifecycle). If the status is `REJECTED`, the transaction status is `REJECTED`. The transaction is captured in the system with the transaction type as `transfer_local`. | --- # Customer ID URL: https://docs.nium.com/docs/open-banking/client-integration/customer-id The Account Details by Customer Consent ID API - HYPERLINK - (apis-reference-accountdetailsbycustomerconsentid) allows Client to get the account details using the customer's consent ID for open banking, as part of the AIS flow. The **Account Details by Customer Consent ID API - HYPERLINK - (apis-reference-accountdetailsbycustomerconsentid)** allows Client to get the account details using the customer's consent ID for open banking, as part of the AIS flow. ## Example response ```JSON { "id": "db50d17a-d849-42a6-8a49-07371fccd717", "consent": { "consentStatus": "received", "frequencyPerDay": 4, "validUntil": "2021-04-15", "lastActionDate": "2021-03-17", "recurringIndicator": true, "access": { "allPsd2": null, "availableAccounts": null, "accounts": [ { "iban": "LT563590020000000102", "bban": null, "currency": "EUR", "maskedPan": null, "msisdn": null, "pan": null }, { "iban": "LT563590020000000102", "bban": null, "currency": "EUR", "maskedPan": null, "msisdn": null, "pan": null } ], "balances": [ { "iban": "LT563590020000000102", "bban": null, "currency": "EUR", "maskedPan": null, "msisdn": null, "pan": null }, { "iban": "LT563590020000000102", "bban": null, "currency": "EUR", "maskedPan": null, "msisdn": null, "pan": null } ], "transactions": [ { "iban": "LT563590020000000102", "bban": null, "currency": "EUR", "maskedPan": null, "msisdn": null, "pan": null }, { "iban": "LT563590020000000102", "bban": null, "currency": "EUR", "maskedPan": null, "msisdn": null, "pan": null } ] }, "scaStatus": { "otp": null, "scaApproach": "REDIRECT", "scaRequred": true, "status": "IDENTIFIED", "tppNokRedirectUrl": "http://www.google.com", "tppRedirectUrl": "http://www.epiphany.eu" } }, "payment": null } ``` ## Response Body | Field | Description | Type | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `id` | ID of the consent to retrieve. | String | | `consent` | The consents details with specified status for a specific PSU. | Object | | `consent.consentStatus` | Authentication status of the consent. | String | | `consent.frequencyPerDay` | The requested maximum frequency for an access per day. | String | | `consent.validUntil` | Valid date for the requested consent. The content is the local ASPSP date in `ISODate` and the format is 2017-10-30. | String | | `consent.lastActionDate` | The date of the last action on the consent object either through the XS2A interface or the PSU/ASPSP interface having an impact on the status. | String | | `consent.recurringIndicator` | TRUE: The consent is for *recurring* access to the account data. FALSE: The consent is for *one* access to the account data. | Boolean | | `consent.access` | This is an object which holds access data fields. | Object | | `consent.access.allPsd2` | The only valid value is: allAccounts. | String | | `consent.access.availableAccounts` | The only valid values are: • allAccounts • allAccountsWithBalances | String | | `consent.access.accounts` | Array which holds account detail fields. | Array | | `consent.access.accounts.iban` | International Bank Account Number (IBAN) of an account, for example: FR7612345987650123456789014. | String | | `consent.access.accounts.bban` | Basic Bank Account Number (BBAN) Identifier. This data elements is used for payment accounts which have no IBAN, for example: BARC12345612345678. | String | | `consent.access.accounts.currency` | The 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `consent.access.accounts.maskedPan` | Primary Account Number (PAN) of a card in a masked form. This is used for card account in responses, for example 1234. Maximum length: 35 | String | | `consent.access.accounts.msisdn` | An alias to access a payment account via a registered mobile phone number. Maximum length: 35 | String | | `consent.access.accounts.pan` | Primary Account Number (PAN) of a card, can be tokenized by the ASPSP due to PCI DSS requirements. This is used for card account in responses. Maximum length: 35 | String | | `consent.access.balances` | Array which holds balance detail fields. | Array | | `consent.access.balances.iban` | International Bank Account Number (IBAN) of an account balance, for example: FR7612345987650123456789014. | String | | `consent.access.balances.bban` | Basic Bank Account Number (BBAN) Identifier. | String | | `consent.access.balances.currency` | The 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `consent.access.balances.maskedPan` | Primary Account Number (PAN) of a card in a masked form. This is used for card account in responses, for example 1234. Maximum length: 35 | String | | `consent.access.balances.msisdn` | An alias to access a payment account via a registered mobile phone number. Maximum length: 35 | String | | `consent.access.balances.pan` | Primary Account Number (PAN) of a card, can be tokenized by the ASPSP due to PCI DSS requirements. This is used for card account in responses. Maximum length: 35 | String | | `consent.access.transactions` | This is an array which holds transaction detail fields. | Array | | `consent.access.transactions.iban` | International Bank Account Number (IBAN) of an account, for example: FR7612345987650123456789014 | String | | `consent.access.transactions.bban` | Basic Bank Account Number (BBAN) Identifier. | String | | `consent.access.transactions.currency` | The 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `consent.access.transactions.maskedPan` | Primary Account Number (PAN) of a card in a masked form. This is used for card account in responses, for example 1234. Maximum length: 35 | String | | `consent.access.transactions.msisdn` | An alias to access a payment account via a registered mobile phone number. Maximum length: 35 | String | | `consent.access.transactions.pan` | Primary Account Number (PAN) of a card, can be tokenized by the ASPSP due to PCI DSS requirements. This is used for card account in responses. Maximum length: 35 | String | | `consent.scaStatus` | Multiple level SCA approach in a corporate PSU context. | Object | | `consent.scaStatus.otp` | The PSU can authorize the consent using the OTP code received as part of SCA process. | String | | `consent.scaStatus.scaApproach` | This data element must be contained, if the SCA approach is already fixed. The possible values are: • EMBEDDED • DECOUPLED • REDIRECT The OAuth SCA approach will be subsumed by REDIRECT. | String | | `consent.scaStatus.scaRequred` | If the SCA is required for consent or not. | Boolean | | `consent.scaStatus.status` | The consent authorization status. | String | | `consent.scaStatus.tppNokRedirectUrl` | Redirect URL for the failure response. | String | | `consent.scaStatus.tppRedirectUrl` | Redirect URL for the success response. | String | | `payment` | One or more processes that implement the business logic related to payment flows such as payment initiation, single payment execution, including security checks, logging, etc. | String | --- # System Reference Number URL: https://docs.nium.com/docs/open-banking/client-integration/system-reference-number The Payment Details by System Reference Number API allows Client to fetch payment details using system reference number of the transaction, as part of the Open Banking PIS flow and based on customer's consent. The **[Payment Details by System Reference Number API](/api#tag/open-banking-onboarding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/consent/payment)** allows Client to fetch payment details using system reference number of the transaction, as part of the Open Banking PIS flow and based on customer's consent. ## Response example ```json { "systemReferenceNumber": "308a4d01-8549-4cbb-b83f-05cd768d606f", "debtorAccount": { "iban": "DE06000000000023456789", "bban": "BARC12345612345678", "pan": "5309050000012345", "maskedPan": "******12345", "msisdn": "+49 170 1234567", "currency": "EUR" }, "creditorAccount": { "iban": "DE06000000000023489765", "bban": "BARC12345612349087", "pan": "5609050000012345", "maskedPan": "******12345", "msisdn": "+49 170 1234897", "currency": "EUR" }, "instructedAmount": { "amount": 1000.5, "currency": "EUR" }, "routingCodeValue": "AAAADEBBXXX", "statementNarrative": "Family maintenance", "creditorName": "John Smith", "comments": "Request initiated", "status": "INITIATED" } ``` ## Response Body | Field | Description | Type | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `systemReferenceNumber` | The unique, system generated reference number for the transaction. | UUID | | `debtorAccount` | This object contains the account details for the debtor in this transaction. | Object | | `debtorAccount.iban` | The International Bank Account Number (IBAN) for the debtor’s account, for example, FR7612345987650123456789014. | String | | `debtorAccount.bban` | The Basic Bank Account Number (BBAN) Identifier. This data elements is used for payment accounts which have no IBAN, for example, BARC12345612345678. | String | | `debtorAccount.pan` | The Primary Account Number (PAN) of the debtor’s card, can be tokenized by the ASPSP due to PCI DSS requirements. | String | | `debtorAccount.maskedPan` | The masked Primary Account Number (PAN) of the debtor’s card. Masked data is represented by \*. | String | | `debtorAccount.msisdn` | An alias to access a payment account via a registered mobile phone number. | String | | `debtorAccount.currency` | The debtor’s 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `creditorAccount` | This object contains the account details for the creditor in this transaction. | Object | | `creditorAccount.iban` | The International Bank Account Number (IBAN) for the creditor’s account, for example, FR7612345987650123456789014. | String | | `creditorAccount.bban` | The Basic Bank Account Number (BBAN) Identifier for the creditor’s account. This data elements is used for payment accounts which have no IBAN, for example, BARC12345612345678. | String | | `creditorAccount.pan` | The Primary Account Number (PAN) of the creditor’s card, can be tokenized by the ASPSP due to PCI DSS requirements. | String | | `creditorAccount.maskedPan` | The masked Primary Account Number (PAN) of the creditor’s card. Masked data is represented by \*. | String | | `creditorAccount.msisdn` | An alias to access a payment account via a registered mobile phone number. | String | | `creditorAccount.currency` | The creditor’s 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `instructedAmount` | This object contains the amount and currency of the transaction. | Object | | `instructedAmount.amount` | The amount of the transaction. | Double | | `instructedAmount.currency` | The 3-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) of the transaction. | String | | `routingCodeValue` | The BIC routing code for the transaction. | String | | `statementNarrative` | The narrative for the transaction. | String | | `creditorName` | The name of the receiver for this flow. | String | | `comments` | The system-generated comments for the transaction. | String | | `status` | The status of the transaction. The possible values are: • INITIATED • PAID • PENDING • REJECTED • RETURN • SENT\_TO\_BANK | String | --- # Third-Party Integration URL: https://docs.nium.com/docs/open-banking/third-party-integration The Nium Payment Services Directive Two (PSD2) Open Banking API is the mechanism for third-party providers to interact with Nium customers and products based in Europe. The Open Banking API is useful for a regulated third-party provider (TPP) who wants to get account details for Nium customers in Europe. To get started using the Nium PSD2 Open Banking API, see our open banking portal. If you have any questions about getting started with open banking, please contact your Nium account manager or [Nium support](mailto:support@nium.com). --- # Use Cases URL: https://docs.nium.com/docs/use-cases Nium's financial solutions power a variety of fintech applications across industries, enabling businesses to efficiently manage payments, streamline operations, and scale globally. This section highlights key scenarios where Nium helps companies simplify complex financial workflows. Each use case provides practical insights into how Nium's APIs and capabilities solve real-world challenges for businesses. Explore detailed solutions tailored for: - [Spend Management](#spend-management): Automate corporate expense controls and supplier payments. - [Payroll](#payroll): Streamline workforce payments and payroll operations. - [Financial Institutions](#financial-institutions): Enable licensed institutions to deliver secure, compliant financial services. ## Spend Management Spend management platforms centralize corporate expense controls, simplify reconciliation, and ensure policy compliance. With Nium, you can: - Offer employee cards for business expenses with real-time controls. - Automate invoice payments to vendors and suppliers globally. - Integrate seamless foreign exchange (FX) solutions for cross-border spending. See [Spend Management](/docs/use-cases/spend-management) to learn more about how Nium enhances spend management with capabilities like corporate cards, dynamic authorization, and intelligent payouts. ## Payroll Nium empowers payroll platforms and corporations to pay employees and tax authorities with accuracy and speed. Our solutions support: - Payroll platforms facilitating salaries, benefits, and expenses. - Global corporations paying employees across markets. See [Payroll](/docs/use-cases/payroll) for more details, including seamless funding, foreign exchange conversions, and payouts. ## Financial Institutions Nium provides licensed financial institutions with robust tools to manage funds, handle foreign exchange, and offer payment services. Key capabilities include: - Streamlined funding and payouts for customers. - Competitive and flexible FX conversion options. - Bulk and transaction-level payment solutions. See [Financial Institutions](/docs/use-cases/financial-institutions) to learn more about the tools we have available for efficient fund management and cross-border transactions. --- # Financial Institutions URL: https://docs.nium.com/docs/use-cases/financial-institutions Nium’s suite of APIs empowers Financial Institutions to innovate and streamline their operations and services. Our solutions cater to various aspects of finance management, helping Financial Institutions ensure efficient and secure transactions for their customers. **Financial Institutions** (FIs) are entities that the applicable government’s regulatory authority licenses to provide regulated financial services within the jurisdiction of the license. This guide highlights key Nium capabilities that empower Financial Institutions. Please note: - Our Financial Institution offering is available only to entities with valid licenses and registrations to provide regulated financial services in the jurisdictions where their services are offered. - Nium provides services directly to the Financial Institution, which then uses Nium's services to move and manage customer funds. Nium does not provide services to the Financial Institution's underlying customers. If you have any questions: - Contact [Nium Sales](https://www.nium.com/contact-us) - Or reach out to [Nium Support](mailto:support@nium.com) - Your Nium account manager, if you're an existing Nium customer Nium provides services that enable Financial Institutions to serve their customers within their licensed jurisdictions. Additionally, Nium generally does not support FIs operating on a cross-border basis, including “offshore banks” regulated in country A that provide services to residents in country B. ## Compliance Requirements Compliance requirements for Financial Institutions partnering with Nium vary by country, depending on factors like payment corridors and transaction volumes. Additionally, every Financial Institution using Nium worldwide must comply with at least the following: - Nium does not permit third parties to fund accounts. - Adhere to [Nium’s Prohibited and Restricted Business Categories policy](https://www.nium.com/regulatory-disclosures/prohibited-business-categories), including for underlying customers they send payments on behalf of and the nature of the payments. ## Funds Flow Here are some examples of how FIs use Nium to move funds for customers. ### Example 1: Like-for-Like Payments 1. The FI funds its Nium account in the same currency. 2. The FI uses its Nium account to make payouts in the same currency. 3. The Nium platform pays the beneficiaries directly in the same currency. Like-for-Like Payments ### Example 2: Bulk FX Payments 1. The FI funds its Nium account in one currency. 2. The FI converts funds in bulk to the destination currency. 3. The FI makes multiple payouts in the destination currency through Nium. ### Example 3: Transaction-Level FX Payments 1. The FI funds its Nium account in one currency. 2. The FI initiates individual payments, converting each transaction to the recipient’s currency. 3. Nium processes the foreign exchange (FX) conversion and pays the recipient directly. ### Example 4: Lock & Hold FX Payments 1. The FI books FX deals and funds its Nium account before the settlement date. 2. After the settlement date, the FI converts funds in bulk to the destination currency. 3. The FI makes multiple payouts in the destination currency through Nium. ## Key Features The following breaks down the different Nium features Financial Institutions use to manage funds for their customers. ### Funding Clients use our Payin solution to fund their Nium accounts. Nium’s Payin solutions empower Financial Institutions to manage their own funds seamlessly and efficiently, driving operational efficiency and client satisfaction. For more information, see [Payins](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments). #### Payins and Financial Institutions Features of payins Financial Institutions use to process the above include: - **Virtual Receiving Accounts (VRAs)**: Receive payments in multiple currencies without needing to open multiple bank accounts in each currency, streamlining fund management. - **Global Reach**: Fund using a wide network of currencies across different geographies, allowing seamless global transactions. #### Example Payin Solutions - **Funding Operational Accounts**: Nium enables Financial Institutions to receive funds in multiple currencies, supporting their operational needs and ensuring seamless account top-ups and fund transfers. ### Foreign Exchange Nium's Foreign Exchange (FX) solution enables Financial Institutions to convert funds into different currencies at competitive exchange rates. For more information, see [Foreign Exchange](/docs/foreign-exchange). #### FX and Financial Institutions Nium’s FX solution equips Financial Institutions with the tools to efficiently manage currency conversions: - **Competitive Exchange Rates**: Access real-time interbank rates with transparent and guaranteed FX rates. - **Multiple Conversion Options**: Perform conversions using either locked or market rates, offering flexibility based on your needs. - **Lock Periods**: Lock FX rates for periods ranging from 5 minutes to 24 hours, allowing time to confirm rates with your internal stakeholders. - **Scheduled Conversions**: Choose conversion schedules to settle funds at the end of the day, next business day, or two business days, giving you time to fund the source account. #### Example FX Solutions With Nium, Financial Institutions can enhance how they convert funds through our various FX solutions: - **Real-Time Conversions**: Convert funds instantly using market rates for immediate needs, available 24/7. - **Locked Rate Conversions**: Secure a locked FX rate for a specified period, providing predictability in exchange rates for your transactions. - **Bulk FX Conversions**: Convert large amounts of funds in bulk, then distribute payouts in the destination currency. - **Transaction-Level FX Conversions**: Convert funds on a per-transaction basis, ensuring each payment is processed at the best available rate. - **Scheduled FX Conversions**: Plan conversions to occur at a future date, allowing time to fund the source account while securing a favorable rate. ### Payouts Nium's payout solution enables Financial Institutions to facilitate domestic and international fund transfers for their customers; this includes: - **Multiple Currencies**: Financial Institutions can use Nium payouts to convert funds into a different currency. This provides more flexibility when processing cross-border transactions. - **Batch Payouts**: Perform hundreds of transfers with a simple click, streamlining your payment operations. - **Compliance and Security**: Comply with regulatory requirements and employ robust security measures to protect customer funds. With Nium’s payout solution, Financial Institutions can enhance their payment capabilities and offer customers fast and reliable ways to transfer funds. For more information, see [Transfer Money](/docs/payouts). #### Payouts and Financial Institutions Different ways Financial Institutions use payouts to move funds include: - **Scheduled Conversion of Funds**: Transfer funds from one currency to another at a pre-determined FX rate (within a period of 24-48 Hours). - **Transaction Fee Management**: FI clients can choose to: - Bear transaction costs. - Settle transaction costs offline per customer. - **Variety of Remittance Methods**: From banks to cards, FIs can use any method to transfer funds based on the individual customer's preference. #### Example Payout Solutions With Nium, Financial Institutions can expand the services they offer to their customers, including: - **Remittances**: Process customers sending funds overseas to family members. - **Overseas Spending**: Process common overseas expenditures, including emergency medical expenses and hotel accommodations. - **Business-to-Business (B2B) Payments**: Facilitate businesses paying their suppliers both domestically and internationally, ensuring timely and secure transactions. ### Additional Features Additional features FI clients take advantage of in Nium's platforms include: - **Cards**: A comprehensive card issuance solution that enables Financial Institutions to offer customers both physical and virtual cards. For more information, see [Cards](/docs/cards). - **Fees**: Use our transparent and competitive **Fee** solution to maximize value for you and your customers. For more information, see [Fees](/docs/fees-and-limits/fees). ## Integration Checklist Here’s a broad overview of the key steps Financial Institutions take and features they need to integrate with to go live with Nium. Following this checklist makes your integration with Nium comprehensive and ready to process live transactions. If you have any questions or need further assistance, please contact Nium Support. ### Step 1: Sign Up for a Sandbox and Nium Portal 1. **Sign Up**: Create an account with [Nium](https://app.nium.com/sign-up). 2. **Nium Portal**: Log in to Nium Portal, a no-code, user-friendly dashboard you can use to manage transactions and anything else processed through Nium. For more information, see [Nium Portal](/docs/nium-portal). 3. **API Keys**: Retrieve your API keys from Nium Portal and test [Nium's API](/api). ### Step 2: Fund Your Nium Account Integrate with [Payins](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) to fund your Nium account. #### Nium API Use the Payins endpoint and automatically get notified when funds are available to fund your Nium account. For more information, see [Payins](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) in our API Reference. #### Nium Portal Alternatively, access your account directly through Nium Portal. For more information, see [Payins](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments). #### Testing Payins To test Payins: - **Simulate Transactions**: Use our test requests to directly access your Nium account. For more information, see [Testing - Payins](/api#tag/payin/POST/api/v1/inward/payment/manual). - **Contact Support**: Reach out to [Nium Support](mailto:support@nium.com) if you need assistance. ### Step 3: Foreign Exchange (FX) Integrate with our [FX endpoints](/api#tag/rates/GET/api/v2/exchangeRate) to convert funds into different currencies. #### Nium API Use the FX endpoint to convert funds in your Nium account from one currency to another. For more information, see [ FX](/api#tag/rates/GET/api/v2/exchangeRate) in our API Reference. #### Nium Portal Alternatively, use the [Customer Balances](/docs/nium-portal) page to move and convert funds between currencies in your Nium account. ### Step 4: Payouts #### Nium API Integrate with [Payouts](/docs/payouts) and use the [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) request to process payouts. #### Nium Portal Alternatively, use [Batch Payouts](/docs/nium-portal/batch-payouts) in Nium Portal to move funds. #### Testing Payouts To test Payouts: - **Nium API**: Use the Transfer Money request to process payouts using your sandbox credentials. - **Nium Portal**: Use Batch Payouts in your Nium Portal sandbox environment. ### Step 5: After the Transaction #### Responding to RFIs Prepare to respond promptly to any Requests for Information (RFIs) to avoid interruptions in transaction processing. For more information, see [Transaction RFIs](/docs/transactions/transaction-rfis). ### Step 6: Additional Technical Requirements #### Webhooks Set up and configure webhooks to receive real-time notifications about transaction statuses and other events. Extensively test webhooks to confirm they are correctly set up and handling all necessary event notifications. For more information, see [Notifications and Webhooks](/docs/developers/notifications-and-webhooks). #### Reports Set up and configure reports to access detailed information about your transactions and other financial activities. Access reporting via our API or directly through the Nium Portal. We recommend thoroughly testing the reporting configurations to ensure they provide the necessary insights and data accurately. For more information, see: - [Nium API - Reports](/docs/reports) - [Nium Portal - Reports](/docs/nium-portal/reports) ## Next Steps Nium's platform provides comprehensive solutions to enhance the operational efficiency of Financial Institutions. By integrating with Nium, you can offer seamless financial services, ensuring compliance and customer satisfaction. ### Signing Up To get started with Nium: 1. **Sign Up**: Start by [signing up for Nium Portal and API access](https://app.nium.com/sign-up) to explore Nium's platform. 2. **Obtain API Keys**: After signing up, retrieve your API keys to authenticate your requests. 3. **Explore Nium's Documentation**: Familiarize yourself with our guides and API documentation to gain a preliminary understanding of how Nium works. - [Getting Started](/docs/getting-started). - [Nium API Reference](/api) Once you're ready to move forward, [contact us](https://www.nium.com/contact-us) and a member of our team will reach out. --- # Global Collections URL: https://docs.nium.com/docs/use-cases/financial-institutions/global-collections Global Collections enable Financial Institutions to collect funds on behalf of their Corporate/Individual customers across the world. These customers are the underlying beneficiaries of Financial Institutions who are owed funds for provided services or goods. Global Collections is primarily for Financial Institutions and Payment Service Providers who want to collect funds for an invoice. Financial Institutions are onboarded to Nium. These Financial Institutions are provided with a multi-currency account to collect funds on behalf of their underlying beneficiaries. Beneficiaries are in turn provided with virtual accounts. #### Global Collections include: - **Multi-currency virtual accounts**: Receive funds across multiple currencies and accounts (per beneficiary) for easier reconciliation. - **Integrated payout and foreign exchange (FX) margins**: Settle funds in any currency while boosting FX earnings. - **API-first design**: Issue accounts, reconcile payments, and move funds instantly. - **Easy customization**: Brand the product as your own, maintaining full control over the customer's experience. #### To use Global Collections, you'll need: 1. A valid payment license. 2. The ability to offer cross-border services. ## High-level flow diagram Global collections diagram ### Set up 1. Sign up with Nium and fetch your API credentials. 2. Our compliance team processes and reviews your request. When approved, your client account is created with Nium. - You'll be assigned a multi-currency wallet with the capability to receive funds in currencies defined during onboarding as well as store and transfer funds in or outside your Nium wallet. 3. Provide information about your beneficiaries via [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) API and you'll receive: - A unique `customerHashId` - the unique identifier for a customer of Nium. - A unique `walletHashId` - the unique identifier of the multi-currency virtual wallet created for the beneficiary. 4. You can request a unique virtual account number (VAN) per currency, per beneficiary. You can also request multiple VANs per currency for a beneficiary for easier reconciliation. Information that's needed to issue a VAN includes: - `customerHashId` - `walletHashId` For more information, see: - [Create a Nium Portal account](/docs/getting-started#step-1-create-a-nium-portal-account) - [Getting Started](/docs/getting-started) - [Wallets](/docs/wallets) - [Virtual Accounts](/docs/payins/virtual-account-number) ## Collections process High-Level Diagram - Intent Provided 1. Share the unique VAN assigned to the beneficiary with the sender. 2. The sender transfers funds to the VAN. 3. Nium's compliance team runs checks on the transaction; if the team raises a Request for Information (RFI), you can respond using the [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) request. 4. Approved funds are: - Credited to the beneficiary's wallet. - Auto-debited from your multi-currency wallet. - Tagged with transaction labels (e.g., `Customer_Wallet_Credit_Fund_Transfer`). If rejected, funds are refunded to the source. For more information on the requests used, see: - [Fetch Wallet](/api#tag/customer-wallet-balance/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet) - [Virtual Account Details](/api#tag/customer-virtual-accounts/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentIds) - [Fetch Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) ## Settlement process Funds in your multi-currency wallet can be settled to your local nostro account in: - SGD (Singapore) - USD (United States) - GBP (United Kingdom) - EUR (European Union) - MXN (Mexico) - COP (Colombia) ## Available payment methods | Currency | Sender Location | Allowed Payment Methods | Transaction Limit | | -------- | --------------- | --------------------------- | ---------------------------------------------------------- | | EUR | Europe | SEPA Instant, SEPA Standard | SEPA Instant: 100,000 EUR; SEPA Standard: No limit | | GBP | UK | Faster, BACS, CHAPS | Faster: 250,000 GBP; BACS: 20,000,000 GBP; CHAPS: No limit | | SGD | Singapore | FAST, PayNow | FAST: 200,000 SGD | | USD | USA | ACH | No limit | | MXN\* | Mexico | SPEI | No limit | | COP\* | Colombia | PSE | No limit | - **Use-case restrictions:** - **COP**: Collection accounts can only be used for the payment of Services and not for payment of Goods or debt collections. Nium provides local collections service in COP and not a depository account. - **MXN**: Collection accounts can only be used for the payment of Goods and Services and not for payment of debt collections. Nium provides local collections service in MXN and not a depository account. ## API requests | Request | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [Create Customer v5](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) | Onboard a beneficiary as a customer. | | [Customer Details](/api#tag/customer-management/GET/api/v1/client/{clientHashId}/customer/{customerHashId}) | Fetch the details of a beneficiary. | | [Virtual Account Details](/api#tag/customer-virtual-accounts/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/paymentIds) | Fetch the VAN details of a beneficiary. | | [Respond to RFI](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/rfi) | Submit additional information about the transaction. | | [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) | Fetch the transactions for a beneficiary. | ## Webhooks | Webhook | Description | | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [Wallet Funded](/docs/developers/notifications-and-webhooks/payin-events/wallet-funded) | Funds are credited to a beneficiary's wallet. | | [Fund Transfer Between Wallets](/docs/developers/notifications-and-webhooks/platform-events/fund-transfer-between-wallets) | Funds are auto-debited. | | [Fund Received from Wallet](/docs/developers/notifications-and-webhooks/platform-events/fund-received-from-wallet) | Transfer is received from a beneficiary's wallet. | ## Common Error Scenarios | Error Response | Description | | ----------------------------- | ------------------------------------------------------- | | `customerHashId is not valid` | Incorrect beneficiary ID. | | `walletHashId is not valid` | Incorrect wallet ID. | | `customer_not_enabled` | Customer not enabled (contact Nium Support). | | `missing_required_fields` | Required fields are missing. | | `duplicate_externalId` | `externalId` must be unique. | | `incomplete_client_setup` | The client is not properly set up or KYC is incomplete. | | `invalid_input` | Invalid field values. | | `customer_exists` | Customer already exists. | --- # Payroll URL: https://docs.nium.com/docs/use-cases/payroll Payroll clients use Nium financial services to help them as part of their overall payroll management services such as paying salaries, benefits, and expense reimbursement. Payroll clients typically have their own payroll management software, and Nium primarily provides the payments capability to facilitate funds movement for the money to be paid to the workforce. The target segments for Nium payroll clients can be broadly divided into two categories: - [Payroll platform providers](#ppp) - [Corporations paying salaries to their employees](#corp) ## Payroll platform providers These are primarily technology companies and start-ups that have built modern payroll management software that automates the management of payroll services such as salary, benefits, expenses, and tax payments for their customers to easily pay their workforce and tax authorities. These global payroll platform companies charge their customers a fee for the software-as-a-service that they provide. This model typically works for global companies with local entities that perform the hiring but would like to outsource the HR functions such as payroll, benefits, tax deduction, reporting, etc. The local entities of the global companies are legally the employers. The companies contract global payroll platforms as their agents to pay their employees and handle compliance activities, such as tax payments. For non-financial payroll platform providers, their business customers need to be onboarded to the Nium One platform with due diligence done on their business customers. For these payroll platform providers, the electronic know-your-business (eKYB) process for onboarding their business customers facilitates a seamless onboarding experience. Non-financial platforms *can not* make payments on behalf of their customers to employees. ### Client setup for non-financial payroll platform Client setup for non-financial payroll platform ### Funds flow for non-financial payroll platform Funds flow for non-financial payroll platform ### Steps for non-financial payroll platform 1. The payroll platform’s customer, who's the legal employer, approves payroll within the platform’s software by a cut-off date to be included in the upcoming payroll cycle run. The payroll platform calculates the employees' payroll and any withholding taxes to be paid to the local tax authorities. The payroll platform books the FX trade at a locked FX on behalf of the customer with Nium and informs their customer about the funding requirements. 2. The payroll platform’s customer provides funding through one of the following: - Pushes funds through a bank transfer into their account with Nium - Authorizes funds to be pulled from their bank account into their account with Nium through Direct Debit 3. Nium executes any FX trade from the funding currency to the payout currency. 4. Nium executes a payout to: - Customer’s local employees for salary payment in the local currency with the necessary purpose code, net any withholding of taxes. - Local tax authorities for tax payment in the local currency with the necessary references passed in the payment to the tax authority. This can happen independent of the salary payment at a pre-determined schedule, for example monthly, quarterly, etc. The remitter name in the payout instruction to the employee is the name of the corporate customer since they're the legal employer. ## Corporations paying salaries to their employees These are corporations with a direct relationship with Nium. Typically, they have their own payroll management software but are looking to integrate with financial service providers like Nium who can help them with funds movement for paying their employees. An example of these companies is a corporation that already has [Oracle NetSuite](https://www.netsuite.com/portal/home.shtml) integrated into their internal systems, and they're looking for a global financial service provider like Nium to help them with payouts to their global workforce dispersed in different countries. This model typically works for global companies that *do not* have local entities for hiring in the required markets. The payroll platform provider hires and pays their employees as the sole legal employer of record (EOR) and contracts out their employee services to their customers. The payroll platform provider as the EOR *does not* make payments on anyone’s behalf but pays its own employees. ### Client setup for EOR payroll model Client setup for EOR payroll model ### Funds flow for EOR payroll model Funds flow for EOR payroll model ### Steps for EOR payroll model 1. The platform’s customer reviews payroll within the platform software by a cut-off date to be included as part of the upcoming payroll cycle run. The payroll platform calculates the employees' payroll and any withholding of taxes to be paid to the local tax authorities. The payroll platform books the FX trade at a locked FX rate with Nium and informs their customer about the funding requirements. The payroll platform’s customer provides funding through one of the following: - Pushes funds through a bank transfer into the payroll platform’s bank account - Authorizes funds to be pulled from their bank account into the payroll platform’s bank account through Direct Debit 2. The payroll platform transfers funds from their bank account into their Nium account. 3. Nium executes any FX trade from the funding currency to the payout currency. 4. The payroll platform instructs Nium to perform a payout to: - Their local employees for salary payment in the local currency with the necessary purpose code, net any withholding taxes - The local tax authorities for tax payment in the local currency with the necessary references passed in the payment to the tax authority. This can happen independent of the salary payment at a predetermined schedule, for example, monthly, quarterly, etc. The remitter name in the payout instruction to the employee is the name of the payroll platform provider since they're the legal employer. --- # Spend Management URL: https://docs.nium.com/docs/use-cases/spend-management Spend Management is a term used to refer to how businesses and entities manage their spending and expenses. Platforms use Nium to help manage how much they're spending and expensing. *Spend Management* is a term used to refer to how businesses and entities manage their spending and expenses. Platforms use Nium to help manage how much they're spending and expensing. Specifically, clients use Nium to provide services that centralize and automate the processes for disbursing and monitoring corporate expenditures made by employees and enforce corporate policies related to expenses. These *Spend Management* clients usually use their platform to provide employee expense cards and/or accounts payable services. Typically, the platforms automate the process of reconciling accounts, verifying expenses based on corporate policies, delivering financial analyses, and integrating the platform with their underlying customers' accounting frameworks. Nium primarily provides payment capabilities that streamline the process of transferring funds for disbursement. Payments can be directed towards suppliers or merchants through methods such as bank transfers or corporate purchasing cards. Additionally, payments to employees can be facilitated via bank transfers, serving as reimbursements for expenses incurred when utilizing personal funds or cards. Typically, spend management will fall into two broad use cases: - [Spend using corporate cards](#spend-using-corporate-cards) - [Invoice payments](#invoice-payments) Additionally, Nium clients in Spend Management are part of one of the following two categories: - [Financial Institutions (FI)](#smfi) - [Non-Financial Institution Platforms](#smnonfi) ### Key features The following table shows the most important Spend Management capabilities for a B2B client: | Global Spend Management platform requirements | Nium solution | | :------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Global network reach on funding currencies and payout corridors | Nium's global payin and payout network corridors' expansion in your target markets. | | Easy funds management | Direct Debit with an automated way for funds to be pulled from your customers. | | Certainty in payments involving cross-currencies with guaranteed FX rates | Bulk FX conversion with a locked FX rate and flexible settlement period for funding in home and desired currency with payout in local currencies. | | Predictability of invoice schedules | Scheduled payouts to merchants and suppliers. Reimbursement to the employees based on the expected payroll date. | | Minimal declines and returns | Confirmation of payee accounts in advance of the scheduled payout date, intelligent routing, and guaranteed beneficiary amounts. | | Spend with cards | **Dynamic authorization** encompassing a suite of API-powered authorization models, offering unmatched flexibility and control, real-time visibility and reporting, and advanced fraud management capabilities. **Extended card authorization** model that helps you to hold funds at Nium, but lets you have your own authorization rules. A helpful feature for clients who lack e-money license to hold their customer funds. **Parent-child shared wallet** model and authorization on corporate accounts that help you manage funds better by tapping into key or centralized accounts for actual spends by different users. **Nameless transferable cards** that enable corporate-owned cards to be used by teams or different employees. **Multicurrency settlement for multicurrency cards** to spend & easily manage currencies. | | Collect revenue | Collect using bank transfer | | Access control and workflow automation tools for validation | Ability to make batch payouts on the UI, such as the Nium portalMaker-checker roles and permissionsEvent-triggered payment automation | ## Spend using corporate cards Corporate cards empower employees and users to securely and transparently pay any merchant who accepts Visa or Mastercard as a form of payment. Employees get access to a wide range of e-commerce sites and brick-and-mortar stores, while control is retained for spending parameters—such as geography, channel, merchant, amount, timing, and frequency—in accordance with corporate policies. Nium provides key features such as [Parent-child hierarchy](/docs/getting-started/parent-child-hierarchy), [Digital Wallet Tokenization](/docs/cards/digital-wallet-tokenization), [Dynamic Authorization](/docs/cards/dynamic-authorization) that allow you to customize your spend management platform and support you to manage your end-user ledger and funds. The dynamic and flexible platform also allows you to manage and offer spending controls. Card spend can be further categorized into two use cases: - [Travel and Entertainment (T\&E) Expensing](#travel-and-entertainment) - [Purchase and Procurement](#purchase-and-procurement) #### Travel and Entertainment (T\&E) Expensing Your corporate customer requires their employees to spend on travel and other expenses on the company's behalf, following specific organizational policies. You also want to track each expense meticulously, feeding comprehensive metrics into your reporting and data analytics providing insights to your customer. #### Purchase and Procurement Your corporate customer needs to make purchases at various vendors, suppliers, and merchants, whether online or in physical stores. Your customer achieves this through cards stored with e-commerce merchants or accessed collectively by a team. You can actively utilize card transaction data to monitor and reconcile all expenditures for your customer. ### Client setup Once you and your corporate customers have been onboarded to Nium, you can issue cards to your corporate customers which can be used by their employees. In a common scenario using the wallet there are two models — Hosted or Extended Authorization models, you can use the below client setup to fund the wallet account and use the cards. Client Setup ### Funds flow Funds Flow ## Invoice payments ### Client setup If you are a Spend Management client with no money transfer license, you onboard your customers onto Nium using the Nium APIs that are integrated with eKYB and eKYC verifications to provide seamless onboarding. The underlying customers fund their Nium wallets directly and instruct Nium (via your platform UX) to make payouts to suppliers or utilize payment cards issued by Nium to pay suppliers. Given that you are not directly receiving funds from your customers, you are not required to be licensed or rely on an applicable exemption from licensing requirements in the country(ies) where you are providing services. Client Setup 2 ### Funds flow The following steps are illustrated in the diagram below to help explain a non-financial B2B Spend Management client's funding flows. 1. Your B2B Spend Management customer approves an invoice payment within their Spend Management software by a cut-off date to be included as part of the upcoming invoice cycle run. The Spend Management software calculates the supplier invoice and any withholding of taxes to be paid to the local tax authorities. Your customer then books the FX trade at a locked FX with Nium and provides funding through one of the following: - Pushing funds through a bank transfer into their account with Nium. - Authorizing funds to be pulled from their bank account into their account with Nium through Direct Debit. 2. Nium executes any FX trade from the funding currency to the payout currency. 3. Your customer instructs Nium to perform a payout to: - Their suppliers for invoice payment in the local currency with the necessary purpose code, net any withholding of taxes. - Local tax authorities for tax payment in the local currency with the necessary references passed in the payment to the tax authority. This can happen independent of the invoice payment at a pre-determined schedule, for example, monthly, quarterly, etc. Client Setup 2 ## FI Spend Management Nium qualifies you as an FI Spend Management client if you are licensed to provide the financial services to your end customers in the countries in which your end customers are located. Your financial services license must permit you to accept funds from customers, retain those funds within a stored value account, and disburse the funds to suppliers (including potential use of payment cards). A variant of the FI Spend Management Client involves an unlicensed entity that receives sponsorship from another FI, such as a bank. In this scenario, you act as an intermediary for the FI, effectively leveraging the FI's payment services to serve your customer base. ## Non-financial spend management platform A Non-FI Platform Spend Management Client is generally unlicensed and does not directly receive funds from its customers. Instead, the Client enrolls its customers onto Nium's platform. These end customers independently fund their Nium accounts and then direct Nium to carry out Payouts to suppliers or use payment cards issued by Nium for supplier payments. As the Spend Management Client doesn't directly obtain funds from customers (with Nium being the recipient, holder, and transmitter of funds), there's no requirement for the Client to possess a license or rely on an applicable exemption from licensing obligations in the countries where it operates. This is because Nium is the entity responsible for providing the regulated payment services in question. --- # Fees and Limits URL: https://docs.nium.com/docs/fees-and-limits Clients use Fees and Limits to manages costs and spending controls for accounts, wallets, and transactions. These tools help you maintain transparency, compliance, and control when using Nium’s platform. Clients use **Fees and Limits** to manages costs and spending controls for accounts, wallets, and transactions. These tools help you maintain transparency, compliance, and control when using Nium’s platform. By understanding **Fees and Limits**, you can optimize costs and ensure secure, compliant transactions across the Nium platform. ## Fees Fees ensure fairness and clarity in how services are charged. Nium enables you to: - Automate predefined fees for common operations (e.g., card issuance, ATM usage). - Configure custom fees tailored to your business needs. - Set up customer-specific fees for differentiated pricing. > **Note**: Always consult with Nium’s legal and compliance teams before introducing new fees. If you have any questions about charing fees, please contact your Nium account manager or [Nium support](mailto:support@nium.com). *E.G.* Charge a virtual card issuance fee or add markups for foreign exchange transactions. For more information, see [Fees](/docs/fees-and-limits/fees). ## Limits Limits help you maintain advanced spend controls across customers, cards, and transactions. With Nium, you can: - Set client-level limits to manage overall account and wallet spending. - Apply card-level restrictions for specific merchant categories and transaction types. - Adjust limits dynamically based on customer verification status (e.g., KYC completion). *E.G.* Allow low transaction limits until a customer completes the KYC process. For more information, see [Limits](/docs/fees-and-limits/limits). --- # Fees URL: https://docs.nium.com/docs/fees-and-limits/fees When processing payments, fees and foreign exchange (FX) margins get applied to client transactions (customer transactions for platform clients), including payouts and account openings. When processing payments, **fees** and **foreign exchange (FX) margins** get applied to client transactions (customer transactions for platform clients), including payouts and account openings. Nium’s pricing engine supports a wide range of customizable pricing options through fees and FX margins, including, but not limited to: - Pricing based on payout or payin method - Tiered pricing structures Fees and FX margins are typically applied in the following scenarios: - **Real-time fee**: Charged at the time of the transaction. - For example, when a payout is processed, the corresponding fee (and any FX margin) is debited from the customer's wallet along with the transaction amount. - **One-time fee**: Charged when a one-off event occurs. - For example, a customer may be charged after completeing onboarding. - **Custom fee**: Charged for events outside the standard pricing model. - For example, a client may charge a monthly subscription fee or a fee based on the inbound payment method. Use the [Charge Fee](/api#tag/customer-fees/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fees) request to apply a custom fee to a customer’s wallet in any supported currency. Custom fees follow the same processing and accounting logic as predefined fees and can be included in the client’s regular invoicing. For the above events, pricing is configured in the client's account once mutually agreed upon with Nium during onboarding. - **FI clients** – Fees are charged to the FI client for real-time and one-time transactions. - **Direct clients** – Fees are charged to the client for real-time and one-time transactions. - **Platform clients** – Fees are charged to the platform client's customers. Clients can define customer segments during onboarding and configure pricing by segment. For example, high-volume customers may have different rates than low-volume customers. Use the [Fee Details](/api#tag/client-settings/GET/api/v2/client/{clientHashId}/fees) request to review the real-time transaction pricing. For additional details, see [Pricing details](#pricing-details). - Before charging any customer fees, you must obtain approval from Nium’s legal and compliance teams. - Do **not** use the [Charge Fee](/api#tag/customer-fees/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fees) request without explicit approval. - For more information, reach out to your Nium account manager or [Nium Support](mailto:support@nium.com). ## Pricing details The following table describes the fields returned in the [Fee Details](/api#tag/client-settings/GET/api/v2/client/{clientHashId}/fees) response. | Field | Description | Available values | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `fee` | Object containing the fee name, pricing rules, FX margin, and price configuration. | For more information, see [Predefined Fees](/docs/fees-and-limits/fees#pre-defined-fees) | | `isDefault` | Indicates if this plan is the default pricing configuration. Only one plan can be marked as default. | `true`, `false` | | `planName` | An array containing all the pricing information for that segment. The `planName` contains all the following fields. | Client-defined segment | | `price` | Specifies the fee to be charged. The fee can be a flat amount or percentage-based. Includes the following fields:type: Flat or Percentagevalue: The amount of the fee to be charged.currency: Currency in which fee is to be charged. If authCurrency in Payout transaction is different than this currency, then fee currency is converted to authCurrency and is charged in authCurrency.percentageOf: Accepts sourceAmount if price.type is percentage. | | | `products` | Array of products for which fees and FX margins are configured. Products can include payouts, payins, FX, cards, accounts, and Verify. Each `product` contains its name and the related fee configuration. | `payout`, `payins`, `fx`, `cards`, `accounts`, `verify` | | `rules` | Defines the conditions under which a fee is charged. Rules can be based on transaction volume, transaction amount, or quantity. | | | `rules.condition` | Criteria for applying the rule, joined using an **and** operator. | `destinationCurrency`, `sourceCurrency` | | `rules.tier ` | Specifies the configured tier. Details provided include:Start and end values of the configured tier range.`tier.on` which details the parameter and currency.Pricing based on the configured tier ranges. | | | `rules.type` | Type of rule used to determine pricing logic. Tiered rules can be based on total volume, individual transaction amount, or quantity of transactions. | `tier`, `nontier` | #### Response example ```json { "feePlans": [ { "planName": "GOLD", "isDefault": true, "products": [ { "name": "payout", "fees": [ { "fee": "remit_bank_fee", "rules": [ { "type": "nontier", "condition": { "operator": "and", "operands": [ { "destinationCurrency": "SGD" }, { "sourceCurrency": "USD" } ] }, "price": { "type": "flat", "value": "2", "currency": "USD" } } { "type": "tier", "condition": { "operator": "and", "operands": [ { "destinationCurrency": "USD" }, { "sourceCurrency": "SGD" } ] }, "tier": { "on": { "parameter": "source_amount", "currency": "USD" }, "ranges": [ { "start": "0", "end": "1000", "price": { "type": "flat", "value": "2", "currency": "SGD" } }, { "start": "1000", "end": "10000", "price": { "type": "flat", "value": "1.5", "currency": "SGD" } }, { "start": "10000", "end": "100000000", "price": { "type": "percentage", "value": "0.1", "currency": "SGD", "percentageOf": "source_amount" } } ] } } ] } ] } ] ``` ## Pricing components Nium’s *pricing engine* consists of the following key components: - **Plan name**: Defines the pricing configuration for a customer segment, assigned during onboarding. - **Product name**: Specifies the product the fee applies to. Supported products include payouts, payins, accounts, FX, cards, and verify. - **Fee name**: Predefined fee that is automatically applied when specific transaction events occur. - **Rules**: Conditions that determine when a fee is applied. Rules can be based on transaction volume, amount, or quantity. For example, a rule might apply a fee only if the transaction’s source currency is `USD`. - **Fees**: The amount charged for a given event, defined as either a flat fee or a percentage-based fee. For example, a transaction with `USD` as the source currency might be charged a flat fee of 1 USD. ## Pre-defined fees The following table lists the available **pre-defined fees** and **FX margin** types, along with their descriptions and when they are charged. ### Payouts The following fees are charged on a per-transaction basis. | Fee name | Description | **Real-time or One-time** | | -------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------- | | **REMIT\_BANK\_FEE** | Charged on remittance transactions when `payoutMethod` is **LOCAL**. | Real-time | | **REMIT\_BANK\_FEE\_SWIFT** | Charged on remittance transactions when `payoutType` is **SWIFT** and `swiftFeeType` is **SHA**. | Real-time | | **REMIT\_BANK\_FEE\_SWIFT\_BEN** | Charged on remittance transactions when `payoutType` is **SWIFT** and `swiftFeeType` is **BEN**. | Real-time | | **REMIT\_BANK\_FEE\_SWIFT\_OUR** | Charged on remittance transactions when `payoutType` is **SWIFT** and `swiftFeeType` is **OUR**. | Real-time | | **REMIT\_CARD\_FEE** | Charged on remittance transactions when `payoutType` is **CARD**. | Real-time | | **REMIT\_CASH\_FEE** | Charged on remittance transactions when `payoutType` is **CASH**. | Real-time | | **REMIT\_CHECK\_FEE** | Charged on remittance transactions when `payoutType` is **CHECK**. | Real-time | | **REMIT\_PROXY\_FEE** | Charged on remittance transactions when `payoutType` is **PROXY**. | Real-time | | **REMIT\_RETURN\_FEE** | Charged when a remittance transaction is returned. | Real-time | | **REMIT\_WALLET\_FEE** | Charged on remittance transactions when `payoutType` is **WALLET**. | Real-time | | **WALLET\_REFUND\_FEE** | Charged when funds are refunded to a customer’s wallet. | Real-time | | **AUTO\_SWEEP\_FEE\_EOD** | Charged when an automatic wallet sweep is triggered at end-of-day. | Real-time | ### Foreign exchange (FX) The following **foreign exchange (FX) markup fees** are applied to the exchange rate used in various types of transactions. Note, Nium applies a markup fee if the transaction currency and authorization currency differ. | Fee name | Description | **Real-time or One-time** | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | **TRANSACTION\_MARKUP** | *(Description needed)* | Real-time | | **FX\_MARKUP** | Applied to the exchange rate for: Balance transfers within a walletCross-currency wallet prefundingRemittance transactions | Real-time | | **FX\_MARKUP\_AUTO\_SWEEP** | Applied to the exchange rate used for automatic wallet sweep transactions. | Real-time | | **FX\_MARKUP\_AUTO\_SWEEP\_EOD** | Applied to the exchange rate used for end-of-day automatic wallet sweep transactions. | Real-time | | **FX\_MARKUP\_SETTLE\_IMMEDIATE** | Applied to conversions settled immediately (when `conversionSchedule` is **immediate**). | Real-time | | **FX\_MARKUP\_SETTLE\_ENDOFDAY** | Applied to conversions settled by 5:00 PM UTC on the same day (when `conversionSchedule` is **end\_of\_day**). | Real-time | | **FX\_MARKUP\_SETTLE\_NEXTDAY** | Applied to conversions settled by 5:00 PM UTC on the next business day (when `conversionSchedule` is **next\_day**). | Real-time | | **FX\_MARKUP\_SETTLE\_2DAYS** | Applied to conversions settled by 5:00 PM UTC two business days after initiation (when `conversionSchedule` is **2\_days**). | Real-time | | **FX\_MARKUP\_LOCK\_5MINS** | Applied to lock the exchange rate for 5 minutes (`lockPeriod` is **5\_mins**). | Real-time | | **FX\_MARKUP\_LOCK\_15MINS** | Applied to lock the exchange rate for 15 minutes (`lockPeriod` is **15\_mins**). | Real-time | | **FX\_MARKUP\_LOCK\_1HOUR** | Applied to lock the exchange rate for 1 hour (`lockPeriod` is **1\_hour**). | Real-time | | **FX\_MARKUP\_LOCK\_4HOURS** | Applied to lock the exchange rate for 4 hours (`lockPeriod` is **4\_hours**). | Real-time | | **FX\_MARKUP\_LOCK\_8HOURS** | Applied to lock the exchange rate for 8 hours (`lockPeriod` is **8\_hours**). | Real-time | | **FX\_MARKUP\_LOCK\_24HOURS** | Applied to lock the exchange rate for 24 hours (`lockPeriod` is **24\_hours**). | Real-time | | **FX\_MARKUP\_CANCELLATION** | Applied when an FX quote is cancelled before use. | Real-time | ### Payins The following fees are charged per payin transaction. | Fee name | Description | **Real-time or One-time** | | -------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------- | | **WALLET\_CREDIT\_THIRD\_PARTY\_FEE** | Charged per payin transaction when the sender (remitter) is not the account holder. | Real-time | | **WALLET\_CREDIT\_OFFLINE\_FEE** | Charged per payin transaction when the sender (remitter) is the account holder. | Real-time | | **WALLET\_CREDIT\_CARD\_FEE** | Charged when crediting funds to the wallet using a card. | Real-time | | **PREFUND\_PROCESSING\_FEE** | Charged when prefunding a client wallet. | Real-time | | **WALLET\_CREDIT\_DIRECT\_DEBIT\_FEE** | Charged when crediting funds to the wallet using direct debit. | Real-time | ### Accounts The following fees are charged during onboarding. | Fee name | Description | Real-time or One-time | | ----------------------------- | --------------------------------------------------------------------------------------------------- | --------------------- | | **ACCOUNT\_OPENING\_FEE** | One-time account opening fee that's charged when the customer is created. | One-time | | **ACCOUNT\_MAINTENANCE\_FEE** | Monthly fee that's charged for account maintenance at the start of the month for the present month. | One-time | | **ACCOUNT\_INACTIVE\_FEE** | A fee charged for inactive accounts. | One-time | | **P2P\_FEE** | Charged per fund transfer between two customers under the same or different client program. | Real-time | ### Cards The following fees are charged while issuing or managing cards. | Fee Name | Description | **Real-time or One-time** | | --------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- | | **PLASTIC\_FEE** | One-time fee for issuing a physical card. | One-time | | **REPLACEMENT\_FEE** | One-time fee for replacing a physical card. | One-time | | **VIR\_CARD\_FEE** | One-time fee for issuing a virtual card. | One-time | | **ADDON\_CARD\_FEE** | One-time fee charged for each issued **ADD\_ON** card. | One-time | | **ATM\_FEE** | Fee charged per ATM withdrawal. | Real-time | | **INTERNATIONAL\_ATM\_FEE** | Fee charged per ATM withdrawal made outside the card’s home country. | Real-time | | **ATM\_DECLINE\_FEE** | Fee charged when an ATM transaction is declined. | Real-time | | **NON\_ATM\_DECLINE\_FEE** | Fee charged when a non-ATM transaction is declined (e.g., when the merchant category code is not **6011**). | Real-time | | **ECOM\_FEE** | Fee charged per e-commerce or online transaction. | Real-time | | **POS\_FEE** | Fee charged per point-of-sale (POS) transaction. | Real-time | ## Real-time transactions When a fee or FX margin is charged during a real-time transaction, a separate transaction type called **Fee\_Debit** is created. If the transaction is later reversed, a second transaction type, **Fee\_Reversal**, is created. The **Fee\_Reversal** object includes the following details: - **feeFixedOrPercentage**: Indicates if the fee is a flat amount or a percentage. - **feeTransactionCurrency**: Currency in which the fee was charged. - **exchangeRate**: If the fee was charged in a different currency than configured, this shows the FX rate used to calculate the converted fee. - **feeAuthCurrency**: Currency used during the transaction’s authorization process. - **feeName**: Name of the fee applied. - **feeValueCurrency**: Currency in which the fee is defined (before conversion). - **feeSlab**: For tiered pricing, identifies the pricing tier applied to the transaction. - **feeValue**: Amount charged as the fee. --- # Limits URL: https://docs.nium.com/docs/fees-and-limits/limits The Nium platform supports advanced spend control features in the form of limits and restrictions. There are multiple types of limits out of which some can be set up at the client level and some can be set up at the card level. The client-level limits are applicable for all the customers, wallets, and cards created under that client. The client-level limits are divided into two categories: regulatory limits and authorization limits. The regulatory limits are account-specific limits, balance amount and count, etc., while the authorization limits are transaction-specific limits. The platform provides limit configurations based on the compliance clearance level of customers. If the customer is created, for example, but the Know Your Customer (KYC) process isn't completed, then the customer can make transactions until a certain limit. If the KYC is completed, then the limits would be higher and different. The restrictions can be set up at the card level only. They specify the types of merchant categories where cards should be allowed. ## Available Limits The following table provides an overview of the spending limits associated with Nium cards. Understanding these limits ensures they are applied correctly based on your specific use cases. - Nium wallet accounts can be either Corporate Accounts or Individual (Employee) Accounts. - When configured, employees may spend directly from the Corporate Account instead of their Individual (Employee) Account. | Limits | Description | Example | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------ | | Annual Count | The maximum number of transactions allowed on all cards associated with a wallet account in a calendar year. | 999,999,999 | | Annual Limit | The maximum total amount a wallet account can spend on all associated cards in a calendar year. | $5M | | ATM Withdrawal - Daily Count | The maximum number of ATM withdrawals allowed for a wallet account in a single day. | 5 | | ATM Withdrawal - Daily Limit | The maximum total amount a wallet account can withdraw from ATMs in a single day. | $1,500 | | ATM Withdrawal - Per Transaction Limit | The maximum amount allowed for a single ATM withdrawal. | $1,500 | | Daily Count | The maximum number of transactions allowed on all cards associated with a wallet account in a single day. | 5000 | | Daily Limit | The maximum total amount a wallet account can spend on all associated cards in a single day. | $50K | | Lifetime Count | The total number of transactions allowed on all cards associated with a wallet account for its entire duration. | 999,999,999 | | Lifetime Limit | The total amount a wallet account can spend on all associated cards for its entire duration. | $999,999,999 | | Max Balance Limit | The maximum amount of funds a wallet account can hold at any given time. | $5M | | Monthly Count | The maximum number of transactions allowed on all cards associated with a wallet account in a calendar month. | 50,000 | | Monthly Limit | The maximum total amount a wallet account can spend on all associated cards in a calendar month. | $800K | | Per Transaction Limit | The maximum amount allowed for a single purchase on a card. | $50K | --- # Nium Portal URL: https://docs.nium.com/docs/nium-portal Learn how to manage transactions using Nium Portal. When you sign up for a Nium account, you gain access to Nium Portal. Nium Portal is a no-code, user-friendly dashboard you can use to manage transactions, beneficiaries, customers, and anything else processed through Nium. For details on how to sign up for a Nium account and generate your API keys, see [Getting Started](/docs/getting-started). To log into Nium Portal: - Click **Log In** in the top right of any guide to login to Nium Portal. - Go to [app.nium.com](https://app.nium.com/). ## Dashboard The first page you see after logging in is the **Dashboard** page. The **Dashboard** page provides an overview of the transactions processed by the customer. Use the dropdown menus to filter what transactions to display. Dashboard ## Payment predictor Use the **Payment predictor** on the dashboard to estimate when a payout will arrive. This tool helps you plan better by predicting payment delivery times based on key details about your payouts. With the payment predictor, you can: - Set clear expectations for the delivery of payouts. - Avoid delays by planning around weekends and holidays. - Make informed decisions without needing to contact support or asking a third-party. When you click **Payment predictor**, you’ll be asked to enter: - **Beneficiary type**: Select whether the payout is to a **Corporation** or an **Individual**. - **Destination Country**: Choose the country where the payout is being sent. - **Destination Currency**: Select the currency of the payout. - **Payout Method**: Choose how the payout is made (e.g., **SWIFT**). - **Payout Method Category**: Further specify the method type (e.g., Local, Proxy, SWIFT, etc.). - **Payout Date**: Choose the intended date of the payout. After entering the details, the tool displays: - The **expected arrival date** of funds, based on processing times and cutoff times (for example, payouts made before 7:30 UTC may be processed same day). - Any relevant **holidays or weekends** that can affect payout timing. Payment Predictor ## Customer Balances The **Customer Balances** page provides an overview of the selected customers balances in the different wallets and currencies they use. Click the customer's name at the top of the page to review another customer's balances. Customer Balances 1 Review at a glance what features are available for each currency - this help you understand what tools you have available when managing those funds. Click on a currency to review the bank account details. Customer Balances 2 Click **Move Funds** to convert funds in the customer's balances to a different currency. Customer Balances 3 ### Virtual Accounts You can also use the **Customer Balances** page to create new Virtual Accounts in the different wallets and currencies your customers use. Please note, Virtual Accounts are only available for accounts and wallets that are enabled to recieve **Payins**. - See the **Payin** column to confirm a currency wallet is enabled to receive Payins. - To enable Payins for a currency, please contact your Nium Account Manage or [Nium Support](mailto:support@nium.com) . To create a Virtual Account: 1. Click **New Virtual Account** next to the currency you want to create an account for. Virtual Accounts 1 2. Select which bank account you want to create a Virtual Account with > **Continue**. Virtual Accounts 2 3. Your currency wallet will expand with a title detailing the name of the bank and the status of your request. 4. Once the bank has successfully assigned the virtual account, you'll see **--** update to your new Virtual Account number. Virtual Accounts 3 For more information about Virtual Accounts, see [Virtual Account Number](/docs/payins/virtual-account-number). ### Account Statements To download a PDF of your account activity: 1. Click **More actions**. 2. Select **Download statement**. Account statements are available for all currencies and can be filtered by the following timeframes: - Last 30 days - Last 60 days - Last 90 days - Custom date range Account Statements ## Client Settings Use the **Client Settings** page to configure which email domains can be invited into your Nium Portal dashboard. - For example, if you only want team members from your business to have access, only include your business's email domain. - You can also include additional email domains to ensure any users that need access won't have any issues getting invited Client Settings ## Managing Beneficiaries Use the **Beneficiaries** page to manage the different beneficiaries that have been created for a customer. Managing Beneficiaries ### Exporting Beneficiaries Export the details of beneficiaries by checking the box next to their name and clicking **Export selected as CSV**. Exporting Beneficiaries The CSV files you can export include: - **Payout template**: Creates a CSV file you can easily use, with minimal changes, to create a batch of payouts. For more information, see [Batch Payouts](/docs/nium-portal/batch-payouts). - **Complete template**: Creates a CSV file that includes all of the details avialble for the selected beneficiaries. ## Managing Users Use the **Users** page to invite team members and grant them access to your Nium Portal. For more information about the different permissions available for the different roles, see [Roles and Permissions](/docs/nium-portal/roles-and-permissions). Managing Users ## Batch Payouts Use the **Payouts** page to individually or programmatically create payouts for yourself or on behalf of clients. For more information, see [Batch Payouts](/docs/nium-portal/batch-payouts) . Batch Payouts --- # Roles and Permissions URL: https://docs.nium.com/docs/nium-portal/roles-and-permissions Nium Portal has several different roles available to help you control what users have access. Nium Portal has four roles available for users: | Role | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `VIEWER` | Can review details about resources and reports but cannot make changes or perform actions. | | `DEVELOPER` | Handles technical settings such as API keys and system configurations; suited for team members responsible for technical setup and integrations. | | `MANAGER` | Oversees and manages operational data (customers, clients, beneficiaries, users, etc.), with the ability to add, edit, and organize records. | | `APPROVER` | Responsible for approving or rejecting transactions and changes to ensure compliance and accuracy. | | `ADMIN` | Has full access to all settings, features, and administrative functions within the portal. | See the following for a breakdown of the permissions and capabilities available for each role in the different areas of Nium Portal. ## User Management | Permissions | `VIEWER` | `DEVELOPER` | `MANAGER` | `APPROVER` | `ADMIN` | | :------------------------- | :------- | :---------- | :-------- | :--------- | :------ | | View user list | ✅ | ✅ | ✅ | ✅ | ✅ | | Add and invite users | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | | Edit and update user roles | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | | Delete user | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | | Request password reset | ✅ | ✅ | ✅ | ✅ | ✅ | ## Client Management | Permissions | `VIEWER` | `DEVELOPER` | `MANAGER` | `APPROVER` | `ADMIN` | | ------------------------- | -------- | ----------- | --------- | ---------- | ------- | | View client balances | ✅ | ✅ | ✅ | ✅ | ✅ | | View client ID | ✅ | ✅ | ✅ | ✅ | ✅ | | View API Keys | 🚫 | ✅ | ✅ | ✅ | ✅ | | View client configuration | ✅ | ✅ | ✅ | ✅ | ✅ | ## Customer Management | Permissions | `VIEWER` | `DEVELOPER` | `MANAGER` | `APPROVER` | `ADMIN` | | ---------------------- | -------- | ----------- | --------- | ---------- | ------- | | View customer list | ✅ | ✅ | ✅ | ✅ | ✅ | | View customer balances | ✅ | ✅ | ✅ | ✅ | ✅ | | View customer data | ✅ | ✅ | ✅ | ✅ | ✅ | | Edit customer data | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Move funds | 🚫 | 🚫 | 🚫 | ✅ | ✅ | | Download statements | 🚫 | 🚫 | ✅ | ✅ | ✅ | ## Beneficiary Management | Permissions | `VIEWER` | `DEVELOPER` | `MANAGER` | `APPROVER` | `ADMIN` | | :---------------------------------- | :------- | :---------- | :-------- | :--------- | :------ | | View beneficiaries list | ✅ | ✅ | ✅ | ✅ | ✅ | | View beneficiary details | ✅ | ✅ | ✅ | ✅ | ✅ | | Add a new beneficiary | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Edit or update a beneficiary | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Delete beneficiaries | 🚫 | 🚫 | 🚫 | ✅ | ✅ | | Export the details of beneficiaries | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Create payouts to beneficiaries | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Approve payouts to beneficiaries | 🚫 | 🚫 | 🚫 | ✅ | ✅ | | Initiate payments to beneficiaries | 🚫 | 🚫 | ✅ | ✅ | ✅ | ## API Keys | Permissions | `VIEWER` | `DEVELOPER` | `MANAGER` | `APPROVER` | `ADMIN` | | --------------------- | -------- | ----------- | --------- | ---------- | ------- | | View API Keys | ✅ | ✅ | ✅ | ✅ | ✅ | | Generate new API Keys | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | ## Webhooks | Permissions | `VIEWER` | `DEVELOPER` | `MANAGER` | `APPROVER` | `ADMIN` | | :-------------- | :------- | :---------- | :-------- | :--------- | :------ | | Create webhooks | 🚫 | ✅ | ✅ | ✅ | ✅ | | Edit webhooks | 🚫 | ✅ | ✅ | ✅ | ✅ | | Delete webhooks | 🚫 | ✅ | ✅ | ✅ | ✅ | | View webhooks | ✅ | ✅ | ✅ | ✅ | ✅ | ## Reports Transaction Reports | Permissions | `VIEWER` | `DEVELOPER` | `MANAGER` | `APPROVER` | `ADMIN` | | :--------------------------- | :------- | :---------- | :-------- | :--------- | :------ | | View transaction reports | ✅ | ✅ | ✅ | ✅ | ✅ | | Download transaction reports | ✅ | ✅ | ✅ | ✅ | ✅ | | Respond to RFIs | 🚫 | 🚫 | ✅ | ✅ | ✅ | | View RFI details | 🚫 | 🚫 | ✅ | ✅ | ✅ | Scheduled Reports | Permissions | `VIEWER` | `DEVELOPER` | `MANAGER` | `APPROVER` | `ADMIN` | | :------------------------- | :------- | :---------- | :-------- | :--------- | :------ | | View scheduled reports | ✅ | ✅ | ✅ | ✅ | ✅ | | Create scheduled reports | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Edit scheduled reports | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Download scheduled reports | ✅ | ✅ | ✅ | ✅ | ✅ | ## Batch Payouts | **Permissions** | **`VIEWER`** | **`DEVELOPER`** | **`MANAGER`** | **`APPROVER`** | **`ADMIN`** | | --------------------------------------------- | ------------ | --------------- | ------------- | -------------- | ----------- | | Download templates | ✅ | ✅ | ✅ | ✅ | ✅ | | Upload batch files | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Submit batch files | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Submit batch files on behalf of another party | 🚫 | 🚫 | 🚫 | ✅ | ✅ | | Cancel their own batches | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Cancel batches created by another user | 🚫 | 🚫 | 🚫 | ✅ | ✅ | | Approve their own batches | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | | Approve another party's batches | 🚫 | 🚫 | 🚫 | ✅ | ✅ | | View batches | ✅ | ✅ | ✅ | ✅ | ✅ | | View transactions in batches | ✅ | ✅ | ✅ | ✅ | ✅ | | Download CSVs of their own batches | 🚫 | 🚫 | ✅ | ✅ | ✅ | | Download CSVs of other users' batches | 🚫 | 🚫 | 🚫 | ✅ | ✅ | --- # Payouts URL: https://docs.nium.com/docs/nium-portal/batch-payouts Nium Portal streamlines the process of managing payouts, allowing you to process transactions without the need for coding or integration. With Payouts, you can create one or more (batch) payouts directly within Nium Portal web app, saving time and effort. Nium Portal streamlines the process of managing payouts, allowing you to process transactions without the need for coding or integration. With **Payouts**, you can create one or more (batch) payouts directly within Nium Portal web app, saving time and effort. In other words, you can use payouts in Nium Portal to process hundreds of transactions at the same time without integrating or developing anything! This guide explains how to create payouts using the two available methods: - **Create Payouts**: In-line payouts directly in Nium Portal by selecting beneficiaries for quick and simple transactions. - **Upload Payouts**: Upload a CSV file to process up to 2,000 payouts at once. Ideal for large volumes of transactions. ## Create In-line Payouts In-line Payouts provide a fast and flexible way to create payouts directly in Nium Portal without needing to use CSV files. In-Line Payouts are perfect for small-scale, ad-hoc, or error-resolution payments. With In-Line Payouts, you can: - **Quickly resolve errors** by correcting payout details and reprocessing transactions directly in the portal. - **Handle ad-hoc or one-off transactions**—like vendor payments or employee reimbursements—without external tools, CSV files, or complex file management. - **Simplify small-scale payouts** by avoiding the time-consuming creation of CSV files. - **Empower users with no-code simplicity**, making payouts accessible to everyone, regardless of technical expertise. ### Create an In-line Payout 1. **Start a New Payout** - Log in to [Nium Portal](https://app.nium.com/). - Click **Payouts** > **New payouts** > **Create payouts**. Batch Payouts 2. **Choose the Payout Type** -- This step is only available if you are a licensed financial institution. Otherwise all payments are made as self payments. - Select **Self** if you're the sender. - Select **On behalf of** if sending on behalf of another party. Batch Payouts 3. **Select Beneficiaries** - Choose the individuals or companies you want to pay. Batch Payouts 4. **Add Payout Details** - Provide the required information, including amounts, currencies, and any other transaction details. Batch Payouts 5. **Add sender details** -- This step is only applicable for on-behalf of payments. - Add details about the sender (you or the party you're acting on behalf of). Batch Payouts 6. **Submit for review** - Review the details and submit the payout for approval. - Once approved, the payout will be processed. Batch Payouts Review the **Status** column to confirm if the in-line payout is available for approval from another admin or manager. Available statuses include: - **Cancelled**: Payout(s) was cancelled by an admin or manager. - **Rejected**: An admin or manager rejected the payout(s) when it was submitted for approval. Review **Approver notes** for more details on why the admin or manager rejected the payout(s). - **Submitted for payout**: The payout was approved and submitted for processing. ##### Approve an in-line payout In-line payouts can be approved by any client admin or manager. However, the maker of the in-line payout can't approve their own payouts. To approve an in-line payout, log in to [Nium Portal](https://app.nium.com/): 1. Click **Payouts** > review the list for the payout you want to approve. 2. Review the **Status** column to confirm the payout is available for approval and the status is **Submitted for approval** > Click **Review and approve**. 3. Review the payout details page for any mistakes. - If the details are accurate, click **Approve** to submit the payout(s) for processing and to create the `payouts`. - If there is a mistake, click **Decline** to reject the in-line payout(s). To resubmit the payout(s), correct the mistake in the in-line payouts and resubmit the payout(s) for validation and approval. ## Upload payouts Batch payouts let you process up to 2,000 transactions in one go. This method is ideal for handling structured, high-volume payouts. We recommend using the payout template in the [Nium Portal](https://app.nium.com/) to start creating your batch payouts CSV. You can find this payout template by logging in to the [Nium Portal](https://app.nium.com/) and clicking **New payout** > **Download payout template**. A ZIP file will begin to download; once unzipped, you'll find two payout templates: - Use the `payouts_template_own.csv` template when you check **Self** as the **Sender** of the payout. - Use the `payouts_template_onbehalf.csv` template when you check **On behalf of** as the **Sender** of the payout. Note that the title of the columns in your CSV must match the titles of the columns in the template; issues can come up with approval and submission if the CSV has incorrect or mismatched column titles. Examples of how to fill out these templates are available to download from the [nium-assets](https://github.com/nium-global/nium-assets) repo. For more information, see [Resources](#resources) below. ## Payouts validation sheet The fields required to successfully create a payout change depending on factors like `Destination currency`, `Destination country` and the `Payout method` you're using. To help you better understand what fields are required and optional, we have a **Payouts Validation sheet** available so you can confirm what fields you need to include in your batch payouts CSV. To use the **Batch Payouts Validation Sheet**, filter each column for the value you'd like to use. The remaining fields highlighted in blue are required, while the rest are optional. See [Regex and Accepted Values](/docs/developers/faqs/regex-and-accepted-values) for details on how Nium filters characters. ## Create a batch payout When your CSV is ready, you can submit it to create a batch of payouts using [Nium Portal](#nium-portal), our no-code web app. ### Nium Portal To create a batch payout, log in to [Nium Portal](https://app.nium.com/): 1. Click **Payouts** in the sidebar > **New payout** in the top right. 2. Next to **Sender**, check if you're creating the batch payout for your **Self** or **On behalf of** another party. Batch Payouts 3. Per the instructions in the Nium Portal, drag and drop your CSV file over the highlighted area. 4. Click **Upload batch payout file** > You'll see the newly created batch payout at the top of the **Batch payouts** list. Batch Payouts Review the **Status** column to confirm if the batch payout is available for approval from another admin or manager. Available statuses include: - **Cancelled**: Batch payout was cancelled by an admin or manager. - **Rejected**: An admin or manager rejected the batch payout when it was submitted for approval. Review **Approver notes** for more details on why the admin or manager rejected the payout. - **Uploaded**: The CSV was successfully uploaded on behalf of another party and accepted. - **Submitted for approval**: The CSV was accepted, validated, and submitted for approval. Once approved by the admin or manager (other than the maker of the batch payout), the payout details will be submitted for processing and payout creation. - **Submitted for payout**: The batch payout was approved and submitted for processing. - **Validation failed**: Formatting and validation issues caused the CSV to fail. Click on the individual entry for the payout to review the issues in detail and to understand what changes need to be made. - **Validation successful**: The CSV was accepted and validated; the payout is ready to submit for approval. - **#/# passed validation**: There are issues with some of the payouts in the CSV, but not all. Click on the individual entry for the payout to review the issues in detail and to understand what changes need to be made. #### Approve a batch payout Batch payouts can be approved by any client admin or manager. However, the maker of the batch payout can't approve their own payouts. To approve a batch payout, log in to [Nium Portal](https://app.nium.com/): 1. Click **Payouts** > review the list for the payout you want to approve. 2. Review the **Status** column to confirm the payout is available for approval and the status is **Submitted for approval** > Click **Review and approve**. 3. Review the payout details page for any mistakes. - If the details are accurate, click **Approve** to submit the batch for processing and to create the payouts. - If there is a mistake, click **Decline** to reject the batch payout. To resubmit the payout, correct the mistake in the batch payout CSV and resubmit the batch payout for validation and approval. ## Choosing Between In-Line and Upload Payouts - Use **In-Line Payouts** for quick fixes, small-scale payouts, or ad-hoc transactions. - Use **Upload Payouts** for high-volume or recurring payments. We recommend using Batch Payouts if you plan on creating 10 or more transactions. Both methods are designed to make payouts efficient, flexible, and accessible to users of all technical levels. ## Resources We have a few resources available to help you create your batch payouts CSV. Refer to the [Nium Playbook](https://playbook.nium.com/) for a breakdown of transaction limits for every available currency. We also have a template available in [Nium Portal](https://app.nium.com/) or our [public GitHub repo](https://github.com/nium-global/nium-assets). To download the resources from our public GitHub repo: 1. Open the [Nium Assets](https://github.com/nium-global/nium-assets) repo in your preferred web browser. 2. Click **Code** > **Download ZIP**. 3. Unzip the ZIP file and you'll have a CSV and XLSX file. - The `payouts_template_own.csv` and `payouts_template_onbehalf.csv` file is the **Payouts Template**. - The `payouts_validations_fi.xlsx` is the **Payouts Validation sheet**. The validation sheet is only required for on-behalf payments. | Resource | Description | Steps to download | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Payouts Template | Use this sheet as a template to create a CSV that will get approved and successfully create payouts once submitted. | Login to [Nium Portal](https://app.nium.com/). > Click **New payout** > Click **Download payout template**. Download the relevant template file directly from the [Nium Assets GitHub repo](https://github.com/nium-global/nium-assets). | | Payouts Validation Sheet | Use this sheet to understand what fields are required in your batch payouts CSV, depending on the payment corridor(s) you're using. | Login to [Nium Portal](https://app.nium.com/). > Click **New payout** > Click **Download payout template**. Download the relevant validation file directly from the [Nium Assets GitHub repo](https://github.com/nium-global/nium-assets). | | Sample Payouts - Self | Use this sheet as an example of how to fill out the Payouts Template to create a payout for yourself. | Download the `sample_payout_own.csv` file directly from the [Nium Assets GitHub repo](https://github.com/nium-global/nium-assets). | | Sample Payouts - On behalf of | Use this sheet as an example of how to fill out the Payouts Template to create a payout on behalf of another party. | Download the `sample_payout_onbehalf.csv` file directly from the [Nium Assets GitHub repo](https://github.com/nium-global/nium-assets). | --- # Reports URL: https://docs.nium.com/docs/nium-portal/reports Learn how to use Reports in Nium Portal to help you manage finances and automate reporting. Reports in Nium Portal are designed to enhance your financial management experience by providing detailed insights into your transactions. With Nium Portal, you can easily track, analyze, and manage your financial activities. ## Transactions reports The **Transactions** reports page offers a comprehensive view of all your financial transactions. You can filter and search transactions by transaction ID or the batch ID. You can further refine your view by different details about the transactions, including: - **Status**: View transactions based on their current status including Approved, Declined, Blocked, etc. - **Type**: Filter transactions by their type, including - [Payouts](/docs/payouts) - [Payins](/docs/payins) - [Foreign Exchange (FX)](/docs/foreign-exchange) - [Wallet to wallet](/docs/wallets/wallet-to-wallet-transfers) - [Client funding](/docs/transactions#client-funding) - [Fees](/docs/fees-and-limits) - [Cards](/docs/cards) - [Open banking](/docs/open-banking) - **Currency**: See transactions sorted by the currency used, helping you efficiently manage multi-currency accounts. - **Payout status**: Filter transactions based on it's current progress. Available values include: - **Sent to bank**: The transaction has been processed and sent to the bank for settlement. - **Returned**: The transaction was not completed and has been sent back, often due to issues like incorrect banking details or insufficient funds. Click on **Returned** for more details on why the transaction was returned. Additional filters include: - **Customer**: Filter transactions by the customer to focus on the activity of a specific user or business. This is helpful when reviewing transaction history for a particular client or when investigating transaction issues. - **Date range**: Select a specific time period to view transactions that occurred within that window. You can choose from pre-set ranges like "Last 30 days" or define a custom range. - **Transaction ID**: Search for a transaction using its unique identifier. This is useful when tracking or troubleshooting a specific transaction. - **External ID**: Filter using your own system's reference ID if you're passing an `externalId` when creating transactions. This helps map Nium transactions to your internal records. - **Batch payout**: View transactions that are part of a bulk payout. Use this to track the status of all payouts made in a batch and confirm successful processing of each. Nium Portal - Transactions With your transactions laid out in Nium Portal and available for easy review, your business can: - **Monitor Pending Transactions:** Quickly identify and review transactions that are still pending. - **View Transaction Details:** Access detailed information about each transaction, including the amount, currency conversion, and creation date. - **[Respond to transactions with Requests for Information (RFI)](/docs/onboarding/corporate-customers/requests-for-information):** Easily manage and respond to any RFIs related to any of your transactions. The **Transactions** reports page ensures you have full visibility and control over your financial operations, enabling you to make informed decisions and maintain accurate records. ### Payout transactions reports When you filter the Transaction reports page for payouts, two additional columns appear: - **Remittance Status**: Details the specific state of the payout in its lifecycle. This is different from the overall transaction status (pending, approved, etc.) and provides a detailed view of the payout process. For more information, see [Transaction Lifecycle](/docs/payouts/transfer-money/remittance-lifecycle). - **Beneficiary Name**: Shows the name of the beneficiary receiving the payout. This allows you to quickly identify who the payout is intended for. These additional columns give you more granular information about each payout transaction and help you manage those transactions more effectively. By using Transaction reports to manage payouts, you can: - **Monitor Remittance Status**: Track the exact stage of each payout, ensuring timely and accurate processing. - **Identify Beneficiaries**: Easily see who is receiving each payout, aiding in verification and record-keeping. This additional information helps ensure you have a detailed understanding of the payouts you process and enables you to manage your financial operations with greater precision. ### Responding to RFI transactions The **Transactions** reports page enables clients to easily view and respond to transaction RFIs (Requests for Information), streamlining the RFI process and reducing dependencies on APIs or external communication. The Nium Portal **Transactions** reports page simplifies handling RFIs by providing a no-code alternative that does not consume any developer resources. This ensures quicker responses and faster resolution of flagged transactions. Any authorized client team members can respond to RFIs directly from Nium Portal. Additional key benefits of using Nium Portal to respond to RFIs include: - **Inline RFI Responses**: Respond directly to RFIs within Nium Portal; clients can filter transactions requiring RFIs and respond directly within the portal. This helps both unblock clients and helps them process transactions more quickly. - **No API integration required**: Respond directly to RFIs without needing to integrate or connect with our API. You also avoid any delays that can arise due email or Slack communication with support teams. - **Creditor/Debtor Separation**: As you work through the different RFIs, for accuracy and clarity, clearly distinguish between the information of the creditor compared to the information of the debtor. #### Use Nium Portal to respond to RFIs To respond to RFI transactions on the Reports page: 1. Click **Reports** > **Transactions** on the left. 2. Click **View only RFI transactions** to view all transactions flagged with the `status` **RFI\_REQUESTED**. RFI - Nium Portal #1 3. Click **Respond to RFI** next to the transaction entry you want to address. RFI - Nium Portal #2 4. Fill in the required fields and upload the necessary documents. - Fields that are successfully completed are marked as **Responded** with a green checkmark. - Previously submitted RFI data is saved, helping you track which transactions need action. - When a document upload is requested, the following limitations apply: - **File format**: JPG, JPEG, PNG, or PDF - **File Size**: 5MB maximum RFI - Nium Portal #2 5. Once submitted, the `status` of the transaction updates to a pending state until our compliance team completes their review of the submitted information. Updates to transaction status are provided [via webhook events](/docs/developers/notifications-and-webhooks/callbacks/transaction-compliance-status) anytime there is a status change. For more information about our different webhook events, see [Webhooks - Overview](/docs/developers/notifications-and-webhooks). For more technical information on RFIs and how they come up, see: - [Requests for Information](/docs/transactions/transaction-rfis) - [RFI Types](/docs/transactions/transaction-rfis/rfi-types) - [RFI Examples](/docs/transactions/transaction-rfis/rfi-examples) By leveraging Nium Portal to respond to RFIs, clients can speed-up transaction processing, ensure smoother operations, and avoid any unnecessary technical complexities. ### GPI details Global Payments Innovation (GPI) provides real-time tracking and transparency for cross-border payments made through the SWIFT network. With Nium Portal, you can review these GPI details in-depth to gain better transparency on your international transactions. GPI details helping you monitor and manage payments with greater confidence. To review GPI details for SWIFT transactions, hover over the **Remittance status** and click **View status details**. GPI details #1 Key GPI details available include: - **Stage Code**: Details the current phase of the transaction. Each code, such as `G001`, `G002`, etc., corresponds to an update to the transaction, providing a clear view of the payment's progress. - **Stage Description**: A brief explanation of the transaction's current condition. This description gives insights into the payment's journey, such as whether it has been delivered to the next bank, is pending credit, or requires further documentation. - **Bank Name**: The name of the financial institution currently handling the transaction. Knowing the bank involved at each stage helps you track where the payment is and who is responsible for the next action. - **SWIFT Code**: The unique SWIFT/BIC code identifying the bank involved in the transaction stage. This code helps confirm the bank’s identity, providing a reliable way to ensure that the payment is routed correctly. - **Timestamp**: The exact date and time when the stage update occurred. The timestamp shows when the transaction reached each specific step, offering insights into processing times and helping to identify any potential delays. GPI details #2 ## Scheduled reports The **Scheduled** reports tab allows you to automate the generation and delivery of various financial reports. Scheduled reports help you maintain regular oversight and compliance an gets rid of the need to manually generate reports. To schedule a report, click **New report**: Sign up - **Report Type:** Choose from a variety of report types to match your needs. For more details on the different report types, see [Scheduled report types](#scheduled-report-types). - **Frequency:** Set the frequency of how often the report will get generated (daily, weekly, monthly, or trailing twelve months. - **Generation Time:** Set what time to generate the report. - **File Name and Delivery:** Specify the file name and delivery method, including optional SFTP details, and PGP key. All previous reports generated are available by clicking through the different pages on the Scheduled reports tab. ### Scheduled report types Understanding the different types of scheduled reports available can help you choose the right ones for your business needs: | Report Type | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Negative Wallet Balance** | Provides a summary of accounts with negative balances, helping you manage potential risks, understand which customers to reach out to, and take corrective actions. | | **Transaction Summary** | Offers a detailed overview of all transactions within the selected period, allowing you to track and analyze financial activities comprehensively over a specific period of time. | | **Assigned Cards** | Lists all the cards assigned to users, including their status and usage details, ensuring you have up-to-date information on the cards you've created. | | **Card Transaction Authorization** | Details the authorizations made on cards, including successful and failed attempts, to help you monitor card usage and security. | | **Card Issuance** | Summarizes the cards you've issued, providing insights into how your business is managing cards. | | **Customer Onboarding** | Summarizes the onboarding status of customers, highlighting key metrics and statuses to help you streamline the onboarding experience. | | **Card Activity Summary** | Provides a summary of card activities, including transactions and usage patterns, enabling you to understand card performance. | | **Account Fees** | Lists the fees charged to accounts, helping you keep track of revenue and cost management. | | **Transaction** | Offers a detailed view and breakdown of the transactions you've processed, giving you granular insights into individual financial movements. | | **Settlement** | A daily report designed to help your reconcile all the transactions you've processed. | By leveraging these Scheduled reports, you can automate routine tasks, ensure accuracy, and maintain a high level of financial oversight with minimal effort. ## Statements The **Statements** tab provides monthly account statements helping you track your account activity, reconcile transactions, and maintain accurate financial records. These statements summarize your account balances, credits, and debits, providing a clear snapshot of your financial position at the end of each month. Statements Each statement is available as a downloadable PDF and includes: - [Balance summary](#balance-summary) - [Account overview](#account-overview) Regularly reviewing your statements ensures accurate financial reporting and helps you quickly identify discrepancies, unauthorized transactions, or unexpected charges. ### Balance summary The **Balance Summary** page provides a high-level overview of your account balance across different currencies and wallets. This section helps you verify your opening and closing balances, track credits and debits, and ensure accurate reconciliation. Balance summary Details available on the balance summary page include: | Column | Description | Example | | ------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | | **Currency** | The three-letter [ISO-4217 currency code](/docs/getting-started/currency-and-country-codes) for the balance. | USD | | **Opening Balance** | The account balance at the start of the month. | 4,022.53 | | **Total Credit** | The total amount credited to the account throughout the month. | 0.00 | | **Total Debit** | The total amount debited from the account throughout the month | 660.00 | | **Closing Balance** | The final account balance at the end of the month. | 3,362.53 | This quick snapshot of your financial activity, helps you validate cash flow and quickly ensure internal reports match your records match. ### Account overview The pages following the balance summary provide a detailed breakdown of individual transactions, organized by currency and wallet. This allows you to track all credits and debits, making it easier to audit financial movements and reconcile your accounts. The following example shows an account where only the USD wallet had activity which debited $660.00: Wallet overview Each transaction entry includes a **DESCRIPTION** column, providing details about the transaction. These details help you understand where funds were sent or received, how currency conversions were applied, and any additional transaction metadata. | DESCRIPTION in Statement | Description | Example | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | Outward fund transfer \| `RT##########` | Details the fund transfer(s) that ocurred between your account and another, external bank account.The ID of the payout (or `remittance`) is also included, beginning with `RT`. | Outward fund transfer \| RT5901113752 | | To `name`, bank account no.: `####` | The owner of the external bank account.The last four digits of the external bank account number. | To Tiren Reg, bank account no. : 4324 | | `` `` at fx rate of `` | Transaction currency, amount, and foreign exchange rate used for currency conversion. | HKD 1,713.71 at fx rate of 7.7896 | | Comment: `` | Displays any remarks or notes added to the transaction for record-keeping or reconciliation purposes. | Comment: HIT | ## Next steps The Reports in Nium Portal are powerful tools designed to help you streamline your financial management processes. Whether you're tracking transactions or automating crucial finance reporting, Reports in Nium Portal provides the insights and control you need to manage finances effectively. For more information on the details in the different reports, and how to generate them using our API, see [Reports](/docs/reports). --- # Developers URL: https://docs.nium.com/docs/developers This section provides the tools, resources, and guidance developers need to seamlessly integrate and build on the Nium platform. Whether you are setting up APIs, managing webhooks, or troubleshooting integration challenges, this section supports every step of your development journey. ### Frequently Asked Questions (FAQs) Get quick answers to common questions about Nium's APIs, platform capabilities, and integration processes. The FAQs section is your go-to resource for troubleshooting and clarifying technical concepts. Explore the [Frequently Asked Questions](/docs/developers/faqs) to resolve queries quickly resolve queries and stay focused on developing. ### Notifications and Webhooks Nium supports a robust collection of [notifications and webhook events](/docs/developers/notifications-and-webhooks) that keeps your platform updated with real-time updates and changes. Webhooks automate event handling and allow you to track key activities such as wallet funding, payouts, card usage, and compliance updates. Integrating webhooks into your system allows you to automate workflows, reduce manual monitoring, and provide a seamless user experience. ### Nium API The **Nium API** is the backbone of the platform, enabling you to interact programmatically with Nium's services. It supports a wide range of capabilities, including wallet management, payouts, payins, card issuing, and FX transactions. With Nium APIs, you can: - Onboard customers and clients seamlessly. - Manage digital wallets, including funding, transactions, and balance tracking. - Automate payouts, payins, and card transactions. - Access real-time foreign exchange and settlement functionalities. - Integrate notifications via webhooks for automated event tracking. To get started, explore the [Nium API Reference](/api) for comprehensive details, including endpoints, request parameters, sample responses, and authentication guidelines. --- # Nium API URL: https://docs.nium.com/docs/developers/nium-api Nium's open APIs provide functionality to collect, convert, and disburse funds. The APIs also provide capability to onboard customers onto the Nium platform and issue cards. Nium follows the OpenAPI 3.0 specification for its REST API structure, and its setup consists of the following entities: - **Client:** The client is the entity that onboards into the Nium system. The client is responsible for onboarding and managing their corporate or individual customer. Nium sets up the client entity which is identified by a universally unique identifier (UUID) called the `clientHashId`. - **Customer:** The client onboards the corporate or individual customer. A UUID called the `customerHashId` identifies the customer. Nium generates and assigns the onboarded customer a unique identifier, `walletHashId`. This unique identifier keeps the API structure consistent. - **Wallet:** A wallet belongs to the corporate or individual customer. The `walletHashId` identifies the multicurrency wallet. - **Card:** A corporate or individual customer can have multiple cards, physical, virtual, and virtual upgrade to physical. The UUID `cardHashId` uniquely identifies the card instrument. ## API header requirements A 36-character UUID needs to be sent in the API header as `x-request-id` for every request. A client's name of your choosing needs to also be sent in the API header as `x-client-name` with every request. The client's name can be up to 32 characters in length. You need to provide this value while raising a support query. Nium's daily sandbox maintenance window is between 7 and 7:45 AM India Standard Time (IST). ## Name and email fields validation Nium APIs allow special characters according to [OWASP standards](https://owasp.org/www-community/OWASP_Validation_Regex_Repository). ## Regular expression for name The following regular expression is applicable to *firstName, middleName, lastName,* and *preferredName*. ``` ^[\\p{Alpha}ßẞŒœǿøǾØIJij](([',. -])?[\\p{Alpha}ßẞŒœǿøǾØIJij]*)*$ ``` ## Regular expression for email The following regular expression is applicable to *email*. ``` ^[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`` {|}~-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}$ ``` ## Currency and rate standards The number of digits after the decimal point in any amount depends on the currency. The rounding method is [half\_even](https://docs.oracle.com/javase/7/docs/api/java/math/RoundingMode.html#HALF_EVEN). For example: - The transaction amount is $10.00 when the currency is USD. - The transaction amount is ¥1000 when the currency is JPY. - The billing amount is S$10.00 when the currency is SGD. All exchange rates and markup rates need to be returned to nine places after the decimal. ## Amount and exchange rate database column definitions - Amount — numeric (19,4) generates the amount in the 15.4 format. - Rates — numeric (19,9) generates rates in the 10.9 format. ## Source and destination currency validation The source and destination amounts are supported until the last decimal place in the relevant currency. Refer to the [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standard for more information. See the examples below for more information. - In a conversion of USD to SGD, the source amount *cannot* be less than 0.01 as USD supports two decimal places. Similarly, the destination amount *cannot* be less than 0.01 as SGD supports two decimal places. - In a conversion of JPY to AUD, the source amount *cannot* be less than 1 as JPY supports zero decimal places. Similarly, the destination amount *cannot* be less than 0.01 as AUD supports two decimal places. - When a remittance transaction is executed with either source or destination currency as IDR, rounding is done half-even up to the nearest whole number. - Decimals (`.`) *are not* supported by the following currencies: - HUF - IDR - VND ## Currency and country codes See [Currency and country codes](/docs/getting-started/currency-and-country-codes) for an exhaustive list. --- # Authentication URL: https://docs.nium.com/docs/developers/nium-api/authentication To authencticate Nium APIs, you need to provide a combination of API key and client ID. | Field | Location | Description | Example | | :----------------------- | :------- | :-------------------------------------------------------------------------- | :----------------------------------------------- | | API Key | `Header` | Sent as the `x-api-key` header — provide your environment-specific API key. | `x-api-key: 0mZpIhaLVM1qd8IJhCfgjeJjsY7b5zde10j` | | Client ID (clientHashId) | `URI` | Sent as the `clientHashId` path parameter in the API URI. | `GET /v1/client/{clientHashId}/...` | ### Where to get API Keys You can sign up for a sandbox environment via the [Getting started](/docs/01-Getting%20Started/index.mdx) guide. To obtain a production API key, contact the [Nium support team](mailto:cards.support@nium.com) or your Nium account manager. Nium supports secure communication by adding the client's IP address to the allowlist. Clients can use a static IP or VPN IPs. The sandbox and production environments have separate keys and client ID's. --- # Request Metrics URL: https://docs.nium.com/docs/developers/nium-api/request-metrics Nium sends additional parameters with response of APIs documenting performance details as below: - **x-request-duration-ms**: This header parameter shall be sent by Nium in API response to each request and the value shall be the execution time in milliseconds. - **x-request-start-time**: This header parameter shall be sent by Nium in API response and the value shall be the UTC time for the start of execution of an API at Nium end. --- # Idempotency URL: https://docs.nium.com/docs/developers/nium-api/idempotency Idempotency is supported by all POST APIs, which allows you to retry requests and avoid mistakenly repeating the same one. When an API call is interrupted in transit and you don't get a response, this is handy. If, for example, a network connection fault prevents you from receiving a response to a request to create a customer, you can retry the request with the same idempotency key to ensure that no duplicate customers are generated. [Idempotency](https://en.wikipedia.org/wiki/Idempotence) is supported by all POST APIs, which allows you to retry requests and avoid mistakenly repeating the same one. When an API call is interrupted in transit and you don't get a response, this is handy. If, for example, a network connection fault prevents you from receiving a response to a request to create a customer, you can retry the request with the same idempotency key to ensure that no duplicate customers are generated. To facilitate idempotency clients are recommended to provide an additional idempotency-key: `` header to the request. The idempotency key is expected to be a unique value generated by the client that the server would use to recognize subsequent retries of the same request. While clients are free to use their logic to create the unique key, we would strongly recommend using V4 UUIDs, or any other random string with enough entropy to avoid collisions. The Idempotency keys can be up to **255** characters long. Nium's idempotency works by saving the body of the first request made, along with the resulting status code when received regardless of whether it succeeded or failed, for any given idempotency key. Any subsequent requests with the same key will return the same result, including `500` errors. All idempotency keys will be eligible to be removed from the system automatically after they're at least **24** hours old, and a new request will be generated if a key is reused after the original key has been purged. Results will only be saved if an API endpoint had started executing. If the request conflicted with another that was executing concurrently, no idempotent result will be saved as no API endpoint began execution and clients can expect to get the response for the original request. All `POST` requests would accept idempotency keys and sending idempotency keys in `GET` and `DELETE` requests will have no effect and should be avoided, as these requests are already idempotent. --- # API Updates URL: https://docs.nium.com/docs/developers/nium-api/api-updates As part of our effort to enhance the APIs, we provide newer functionalities and updates to the APIs communicated by the support team. Our typical development cycle is three weeks. We classify our changes into breaking and non-breaking changes. These changes can be classified as follows: **Example of breaking changes:** - Adding a required field(s) - Data type changes for existing elements - Response structure or format changes - URL structure changes for existing APIs - Any mandatory change in the designed flow introduced by new APIs **Example of non-breaking changes:** - Addition of new APIs - Additional of optional fields to request body - Adding new fields to the response - Adding new values to fields - Bug fixes In case of non-breaking changes, Nium you can view our [Changelog](/changelog) with details of upcoming changes at the end of the second week of the month \[Thursday or Friday]. Changes shall be available on Sandbox by the end of the third week \[Thursday of the third week]. Once this code is released, Nium shall do a production release on the tenth day after sandbox release. In case of breaking changes, Nium will communicate with you about the changes four weeks in advance from the date of production release. --- # Rate Limits URL: https://docs.nium.com/docs/reference/usage-limits Learn about API rate limits for both Sandbox and Production environments, including per-second, burst, and daily limits. Learn how usage patterns may affect these limits and how to request adjustments. Nium enforces rate limits to ensure consistent performance and platform stability across all API environments. These limits define how many requests your application can send per second and per day. This article lists the default rate limits for both Production and Sandbox environments. Rate limits may be adjusted over time based on your usage patterns or specific business needs. To request changes or if you have any questions, please contact your Nium account manager or [Nium Support](mailto:support@nium.com). Production The following limits apply to Production environments: Request rate Burst 100 per second 50 Sandbox The following limits apply to Sandbox environments: Request rate Burst 20 per second 20 ## Transactions limits Nium supports a maximum of **3 Transactions Per Second (TPS)** for each wallet issued by a client; this TPS limit only applies to the [Transfer Money](/docs/payouts/transfer-money) request. This TPS limit helps ensure consistent platform performance and fairness across our global customer base. For more information, see [Payouts](/docs/payouts). --- # Nium Environments URL: https://docs.nium.com/docs/developers/nium-api/nium-enviorments When you sign up to the Nium platform and obtain api keys, you are immediately granted access to the sandbox environment. The keys issued to you are specific to one of the environments. Use the sandbox for testing your implementation. ### Environment URLs The following table shows the URLs used by our sandbox and live production environments. | Enviornment | URL | | ----------- | -------------------------------- | | Sandbox | `https://gateway.nium.com/api` | | Production | `https://api.spend.nium.com/api` | --- # Deprecated APIs URL: https://docs.nium.com/docs/developers/nium-api/deprecated-apis This page lists all deprecated APIs and the date of their deprecation in the same groups they appear on the API reference page. ## Customer ### Customer account — Individual | Deprecated API | Deprecated date | Replaced with | | :----------------------------------------- | :-------------- | :-------------------------------------------------------------------------------------------------------- | | Add Customer | December 2023 | [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) | | Add Customer Using MyInfo (SG) | December 2023 | [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) | | Add Customer Using GreenID (AU) | December 2023 | [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) | | Add Customer Using E-Document Verification | December 2023 | [Unified Add Customer](/api#tag/customer-account---individual/POST/api/v4/client/{clientHashId}/customer) | ### Customer management | Deprecated API | Deprecated date | Replaced with | | :--------------- | :-------------- | :------------------------------------------------------------------------------------------------------------- | | Customer Details | December 2023 | [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) | | Customer List | December 2023 | [Customer List V3](/api#tag/customer-management/GET/api/v3/client/{clientHashId}/customers) | ## Wallet ### Wallet-to-Wallet Transfers | Deprecated API | Deprecated date | Replaced with | | :------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | | P2P Transfer | December 2023 | [Wallet to Wallet Transfer](/api#tag/wallet-to-wallet-transfers/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transfers) | ## Payout ### Beneficiary | Deprecated API | Deprecated Date | Replaced with | | :----------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------- | | [Add Beneficiary](/api#tag/beneficiary/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}) | December 2023 | [Add Beneficiary V2](/api#tag/beneficiary/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries) | ## Cards ### Lifecycle | Deprecated API | Deprecated date | Replaced with | | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Add Card V1](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) | March 2024 | [Add Card V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) | | [Card Details](/api#tag/lifecycle/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}) | March 2024 | [Card Details V2](/api#tag/lifecycle/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}) | | [Block/Unblock Cards](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/cardAction) | March 2024 | [Block and Replace Card V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/blockAndReplace) | | [Issue Replacement Card](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/replaceCard) | March 2024 | [Block and Replace Card V2](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/blockAndReplace) | ### Security | Deprecated API | Deprecated date | Replaced with | | :----------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Fetch CVV2](/api#tag/security/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/cvv) | March 2024 | [Fetch Card Data Encrypted V2](/api#tag/security/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/retrieve) | | [Unmask Card](/api#tag/security/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/unmask) | March 2024 | [Fetch Card Data Encrypted V2](/api#tag/security/GET/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/retrieve) | If you have any questions or concerns, contact your Nium Project Manager. --- # Hosted Components URL: https://docs.nium.com/docs/developers/pre-built-forms Hosted Components are secure, Nium-managed UI forms that embed directly into your platform — giving your customers a compliant, consistent experience without requiring you to build or maintain the underlying flows. Each Hosted Component handles a specific workflow: collecting beneficiary payment details, tax information, customer onboarding data, or responses to compliance information requests. Nium manages hosting, form logic, regulatory updates, and data transmission. ## Who should use Hosted Components Hosted Components are designed for clients that want to: - Reduce engineering effort on compliance and data-collection flows - Go live faster without building custom UI - Maintain a consistent, branded experience without owning the underlying form logic - Keep collected data flowing securely and directly into Nium ## Benefits - **Rapid integration**: Launch hosted forms in days. Nium manages hosting, scaling, and updates. - **Lower operational overhead**: Eliminate the need to build or maintain forms for compliance, document collection, and payment setup workflows. - **Secure and globally compliant**: All Hosted Components run on Nium's infrastructure, aligned with global standards for availability, privacy, and regulatory compliance. - **Automatic updates**: As regulatory requirements change, Nium updates the forms — no action required from your team. ## Available Hosted Components | Component | Purpose | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [Beneficiary Forms](/docs/developers/pre-built-forms/beneficiary-forms) | Collect payment account details from beneficiaries or recipients | | [Tax Forms](/docs/developers/pre-built-forms/tax-forms) | Collect tax information (W-9, W-8) from beneficiaries or recipients | | [Onboarding Forms](/docs/developers/pre-built-forms/onboarding-forms) | Guide customers through KYB/KYC data submission and compliance steps | | [KYC Pre-built Form](/docs/developers/pre-built-forms/kyc-form) | Collect identity verification information from customers without building a custom KYC interface | | [RFI Forms](/docs/developers/pre-built-forms/rfi-forms) | Collect additional information from customers during compliance reviews | ## Next steps Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable and configure Hosted Components for your account. --- # Onboarding Forms URL: https://docs.nium.com/docs/developers/pre-built-forms/onboarding-forms Onboarding Forms are secure, Nium-hosted web forms that guide your corporate customers through KYB and compliance steps — so you can onboard customers without building or maintaining a custom onboarding UI. This form is helpful for clients that: - Need faster go-to-market with limited engineering bandwidth - Want Nium to manage the form experience, validations, and regional compliance requirements - Are expanding into multiple countries without rebuilding onboarding flows - Want to reduce errors, RFIs, and back-and-forth with customers during onboarding If you need full UX and workflow control, or handle high onboarding volumes with dedicated engineering capacity, use [Nium's Onboarding APIs](/docs/onboarding/customer-onboarding) to build a custom integration instead. ## Overview To onboard corporate customers using Onboarding Forms, clients: 1. Invite the customer to onboard by sending or embedding the Onboarding Form link. 2. The customer completes the Nium-hosted form, including business details, stakeholder information, and document uploads. 3. Nium handles KYB, KYC, and compliance verification. 4. You track progress and outcomes via webhooks and the Nium API. 5. If Nium's compliance team needs additional information, an RFI is raised — customers respond using the [RFI Form](/docs/developers/pre-built-forms/rfi-forms). ## Key features Onboarding Forms are built with regional regulatory requirements in mind. Nium manages field logic, validations, and compliance alignment — you only need to track customer progress and outcomes. Other features include: - Secure, expiring form links. - Email-based one-time password (OTP) verification. - Save-and-resume capability — customers can complete the form across sessions. - Review and confirmation step before submission. - Integrated KYB and KYC flows, including automatic database verification in supported regions. - End-to-end application tracking via webhooks. #### Responsibilities | Feature | Client | Nium | | ------------------------------- | :----: | :---: | | Customer invitation | **X** | | | Branding (logo) | **X** | | | Form experience and validations | | **X** | | KYB/KYC execution | | **X** | | Compliance decisions | | **X** | | Application status tracking | **X** | | ## Branding You can add your organization's logo to the Onboarding Form for a consistent customer experience. Your logo appears at the top left corner of the form, replacing the Nium logo shown in the default view. Provide your logo to your Nium account manager during initial setup. ## Prerequisites Before integrating Onboarding Forms: - Your client account must be onboarded in Nium. You need your `clientHashId` and API key. - Hosted Components must be enabled for your account. Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable and configure this feature. ## Onboard customers with Onboarding Forms Onboarding Forms flow ### Step 1: Request access Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable Onboarding Forms for your account. Provide your logo during this step — it appears at the top left corner of the form. ### Step 2: Set up webhooks Integrate with the [Customer Status](/docs/developers/notifications-and-webhooks/platform-events/customer-status) webhook to track application status updates. Use the `externalId` to correlate status changes back to your customer records. ### Step 3: Create a session Use the [Create a Session](/api#tag/sessions/POST/api/v1/client/{clientHashId}/sessions) request to generate a `sessionId`. The `sessionId` securely binds the customer's session to Nium's hosted form. #### Request example ```shell curl --location --globoff 'https://gateway.nium.com/api/v1/client/{clientHashId}/sessions' \ --header 'Content-Type: application/json' \ --header 'x-api-key: {x-api-key}' \ --data '{ "featureType": "customer_onboarding_form", "clientHashId": "{clientHashId}", "externalId": "{your-customer-reference-id}", "integrationType": "standalone", "expiry": "2026-12-31T23:59:59+00:00", "rollingDurationMinutes": 30, "email": "{customer-email}" }' ``` | Field | Type | Required | Description | | | ------------------------ | ------- | :---------: | ------------------------------------------------------------------------------------------------ | --------------- | | `featureType` | String | Required | Set to `customer_onboarding_form` for Onboarding Forms. | | | `clientHashId` | String | Required | Unique identifier of your client account. | | | `externalId` | String | Required | Your internal identifier for the customer. Used to correlate webhook status updates. | | | `integrationType` | String | Required | `embedded` to display the form inside your portal. `standalone` to open in a new browser tab. | | | `expiry` | String | Optional | Date and time the session expires. Format: `yyyy-MM-dd'T'HH:mm:ssXXX`. | | | `rollingDurationMinutes` | Integer | Optional | Minutes of inactivity before the session expires. Minimum: `1`. | | | `domain` | String | Conditional | Required when `integrationType` is `embedded`. Must match the domain where the form is embedded. | | | `onBehalf` | boolean | Yes | Indicates whether the client accesses the form on behalf of the customer. | `true`, `false` | | `email` | string | Conditional | Required when `onBehalf = true`. Used for OTP authentication. | — | #### Successful response ```json { "sessionId": "e40e8072-7654-474b-ae31-c21a39c206ec", "externalId": "your-customer-reference-id", "featureType": "customer_onboarding_form", "metadata": { "integrationType": "standalone", "onBehalf": false, "email": "customer@example.com", "clientHashId": "a8734b87-f6e6-4fe1-95ed-b41a00104f64" }, "status": "active" } ``` Pass the `sessionId` to the static Onboarding Form URL: - **Production:** `https://nformify.nium.com/customers/initial-enquiry?sessionId=` - **Sandbox:** `https://nformify-sandbox.nium.com/customers/initial-enquiry?sessionId=` ### Step 4: Send or embed the form Surface the full URL (base URL + `sessionId`) to your customer: - **Standalone:** Send the link via email, SMS, or in-app notification. The form opens in a new browser tab. - **Embedded:** Embed the form directly in your portal or dashboard using the `embedded` integration type. ### Step 5: Customer completes the form The customer completes the form in the following order: **1. Choose customer type** The customer selects their business type to begin the onboarding enquiry. Choose customer type **2. Complete initial enquiry** The customer enters their business name and registration number. Nium uses this to auto-fill business and stakeholder details where available. Complete initial enquiry **3. Complete the form** The customer reviews and confirms business details, then enters information for all key stakeholders — Ultimate Beneficial Owners (UBOs), shareholders, directors, and signatories — and uploads required supporting documents. Complete the form **4. Accept terms and conditions** The customer reviews all entered details and accepts the terms and conditions before submitting the application. Accept terms and conditions **5. Complete KYC verification** After submission, the form redirects to the KYC verification step. You receive a webhook with `subStatus: awaiting_kyc`. Once all stakeholders complete KYC, you receive a webhook with `subStatus: under_review`. In supported regions, KYC is completed automatically via database verification — no further action required from the customer. KYC verification ### Step 6: Handle RFIs Nium's compliance team reviews the submitted application. Progress is communicated via webhooks. If additional information is needed to approve the application, Nium raises an RFI. Provide your customer with the relevant [RFI Form](/docs/developers/pre-built-forms/rfi-forms) link to respond. The review process is complete once all RFIs are resolved and the application `status` updates to `Clear`. After this, the customer can start initiating transactions. ## Next steps After a customer completes the Onboarding Form and the application status reaches `Clear`, you can: - Configure the customer's wallet and payment settings via the Nium API. - Contact your Nium account manager to confirm any additional setup required before the customer goes live. - Monitor ongoing application status using the [Customer Status](/docs/developers/notifications-and-webhooks/platform-events/customer-status) webhook. --- # RFI Forms URL: https://docs.nium.com/docs/developers/pre-built-forms/rfi-forms RFI Forms are secure, Nium-hosted forms that let your customers or operations teams respond to Requests for Information (RFIs) instantly — without requiring you to build or maintain a custom data collection interface. RFIs are raised by Nium's compliance team when additional information is needed to progress an onboarding application or clear a transaction. This form is helpful for clients that: - Want to resolve RFIs faster without building custom UI flows - Operate both customer-facing portals and internal operations dashboards - Need a single integration that handles both onboarding and transaction RFIs - Want Nium to manage form hosting, compliance updates, and data transmission ## Overview To collect RFI responses using RFI Forms, clients: 1. Receive a [callback](/docs/developers/notifications-and-webhooks/callbacks) from Nium when a new RFI is raised. 2. Create a session using the [Session API](/api#tag/sessions/POST/api/v1/client/%7BclientHashId%7D/sessions), providing the customer and RFI context. 3. Surface the session link to the customer or operations team. 4. The customer or ops team opens the Nium-hosted RFI Form and submits the required information. 5. Nium processes the submission and updates the case or transaction status automatically. ## Key features RFI Forms dynamically display the fields and document types required for each specific RFI — no configuration needed on your end. Nium handles validation, submission, and audit logging. Other benefits of using RFI Forms include: - No frontend build required — Nium hosts and maintains the form. - Supports both embedded (in-portal) and standalone (new tab) integration modes. - Works for onboarding RFIs and transaction monitoring RFIs from a single integration. - Secure, time-bound session access — each session is configurable with an expiry and inactivity timeout. - Full audit trail for every RFI raised and resolved, maintained by Nium. #### Responsibilities | Feature | Client | Nium | | -------------------------------------- | :----: | :---: | | RFI callback listener | **X** | | | Session creation | **X** | | | Link delivery to customer or ops team | **X** | | | Form experience and field display | | **X** | | Input validation and document handling | | **X** | | Data submission to Nium systems | | **X** | | Case and transaction status updates | | **X** | ## RFI types RFI Forms support two types of RFIs. Set the `featureType` field in the session request to match the RFI type. | RFI type | `featureType` value | When it's raised | Additional fields required | | --------------- | ------------------------- | ---------------------------------------------------------- | -------------------------- | | Onboarding RFI | `customer_onboarding_rfi` | During KYC/KYB review of a customer onboarding application | None | | Transaction RFI | `transaction_rfi` | During monitoring of a specific transaction | `walletHashId`, `authCode` | For transaction RFIs, `authCode` is the `systemReferenceNumber` returned in the response to the [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance), [Fund Wallet v2](/api#tag/customer-funding/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund), or [Wallet to Wallet Transfer](/api#tag/wallet-to-wallet-transfers/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transfers) requests. ## Branding You can add your organization's logo to the RFI Form for a consistent customer experience. Your logo appears at the top left corner of the form, replacing the Nium logo shown in the default view. Provide your logo to your Nium account manager during initial setup. ## Prerequisites Before integrating RFI Forms: - Your client account must be onboarded in Nium. You need your `clientHashId` and API key. - Customer records must exist with valid `customerHashId` values. - For transaction RFIs, the relevant `walletHashId` and transaction `systemReferenceNumber` must be available. - Hosted Components must be enabled for your account. Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable and configure this feature. ## Create an RFI Form session ### Step 1: Request access Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable RFI Forms for your account. During setup, provide your logo — it appears at the top left corner of the form. ### Step 2: Set up callbacks Integrate with Nium's [callbacks](/docs/developers/notifications-and-webhooks/callbacks) to receive notifications when RFIs are raised. Use these callbacks to: - Alert customers or your operations team immediately. - Display RFI status and links in your portal, app, or CRM. ### Step 3: Create a session When a customer or ops team member needs to respond to an RFI, use the [Create a Session](/api#tag/sessions/POST/api/v1/client/{clientHashId}/sessions) request to generate a `sessionId`. #### Request example — onboarding RFI ```shell curl --location --globoff 'https://gateway.nium.com/api/v1/client/{clientHashId}/sessions' \ --header 'Content-Type: application/json' \ --header 'x-api-key: {x-api-key}' \ --data '{ "featureType": "customer_onboarding_rfi", "customerHashId": "{customerHashId}", "integrationType": "standalone", "expiry": "2026-12-31T23:59:59+00:00", "rollingDurationMinutes": 30 }' ``` #### Request example — transaction RFI ```shell curl --location --globoff 'https://gateway.nium.com/api/v1/client/{clientHashId}/sessions' \ --header 'Content-Type: application/json' \ --header 'x-api-key: {x-api-key}' \ --data '{ "featureType": "transaction_rfi", "customerHashId": "{customerHashId}", "walletHashId": "{walletHashId}", "authCode": "{systemReferenceNumber}", "integrationType": "standalone", "expiry": "2026-12-31T23:59:59+00:00", "rollingDurationMinutes": 30 }' ``` | Field | Type | Required | Description | | ------------------------ | ------- | :---------: | --------------------------------------------------------------------------------------------------------------------- | | `featureType` | String | Required | `customer_onboarding_rfi` for onboarding RFIs. `transaction_rfi` for transaction monitoring RFIs. | | `customerHashId` | String | Required | Unique identifier of the customer the RFI is raised against. | | `walletHashId` | String | Conditional | Required when `featureType` is `transaction_rfi`. The wallet linked to the transaction. | | `authCode` | String | Conditional | Required when `featureType` is `transaction_rfi`. The `systemReferenceNumber` of the transaction. | | `integrationType` | String | Required | `embedded` to display the form inside your portal. `standalone` to open in a new browser tab. | | `expiry` | String | Optional | Date and time the session expires. Format: `yyyy-MM-dd'T'HH:mm:ssXXX`. Defaults to 1 hour from session creation. | | `rollingDurationMinutes` | Integer | Optional | Minutes of inactivity before the session expires. Minimum: `1`. Defaults to 30 minutes. | | `domain` | String | Conditional | Required when `integrationType` is `embedded`. The domain where the form is embedded — must match the session domain. | #### Successful response ```json { "sessionId": "e40e8072-7654-474b-ae31-c21a39c206ec", "featureType": "customer_onboarding_rfi", "metadata": { "customerHashId": "string", "authCode": "string", "integrationType": "standalone", "walletHashId": "string", "clientHashId": "string" }, "status": "active" } ``` | Field | Description | | ------------- | ------------------------------------------------------------------ | | `sessionId` | Unique session identifier. Pass this to the hosted form URL. | | `featureType` | The type of RFI form generated. | | `metadata` | Session context including customer and transaction identifiers. | | `status` | Status of the session. `active` means the session is ready to use. | ### Step 4: Open the form Pass the `sessionId` to the static RFI Form URL: - **Production:** `https://nformify.nium.com/rfi?sessionId=` - **Sandbox:** `https://nformify-sandbox.nium.com/rfi?sessionId=` The form loads automatically with the relevant RFI fields — no additional requests or setup required. Surface this link by: - Embedding the form in your customer portal or internal ops dashboard (`integrationType: "embedded"`) - Sending the link directly to the customer via email or in-app notification (`integrationType: "standalone"`) - Sharing the link through your back-office tooling for operations-led RFI workflows ## Security - **Time-bound sessions**: Each session has a configurable expiry and inactivity timeout. Generate a new session if the link expires before the customer or ops team uses it. - **Use HTTPS**: All requests to Nium APIs must use HTTPS in production environments. - **Authenticate before sharing**: For customer-facing RFI links, ensure customers are authenticated in your portal before the session link is generated or surfaced. - **Audit trail**: All RFI submissions are logged and stored by Nium for regulatory compliance — no action required from your team. ## Next steps After a customer submits an RFI Form, Nium processes the submission and updates the relevant case or transaction status automatically. You can: - Monitor RFI resolution status via [callbacks](/docs/developers/notifications-and-webhooks/callbacks). - Use the [Customer Status webhook](/docs/developers/notifications-and-webhooks/platform-events/customer-status) to track applications submitted via [Customer Onboarding v5](/docs/onboarding/customer-onboarding). If not using Customer Onboarding v5, use the [Customer Compliance Status webhook](/docs/developers/notifications-and-webhooks/platform-events/customer-compliance-status) for individual customer applications or [Customer KYB Status webhook](/docs/developers/notifications-and-webhooks/platform-events/client-kyb-status) for corporate customer applications. - Contact your Nium account manager if you need help configuring branding or embedding the form in your portal. --- # Beneficiary Forms URL: https://docs.nium.com/docs/developers/pre-built-forms/beneficiary-forms Beneficiary Forms are secure, Nium-hosted forms that collect payment account details from your beneficiaries or recipients — creating a verified payment account in Nium without requiring you to build or maintain a custom data-collection experience. This form is helpful for clients that: - Pay out to a large number of beneficiaries or recipients - Need beneficiaries to self-serve their payment account setup - Want Nium to handle payment detail collection and validation - Are building toward tax compliance workflows — Beneficiary Forms are a prerequisite for [Tax Forms](/docs/developers/pre-built-forms/tax-forms) ## Overview To collect beneficiary payment details using Beneficiary Forms, clients: 1. Create a session using the Nium API, providing the beneficiary's details and redirect URIs. 2. Redirect the beneficiary to the Nium-hosted form using the returned session URL. 3. The beneficiary completes a guided 4-step form: demographic information, communication preferences, account type, and bank transfer details. 4. Nium creates a `beneficiary` record and a linked `paymentAccount`. 5. The beneficiary is redirected to the client's success URL with the `beneficiaryHashId`. ## Key features Beneficiary Forms handle the full payment account setup experience, including field validation, currency and country-specific requirements, and secure data submission directly into Nium. Other benefits of using Beneficiary Forms include: - No frontend build required — Nium hosts and maintains the form. - Supports bank accounts and payment cards across multiple regions. - Secure session-based access — each session is single-use and short-lived. - Configurable redirect URIs for success, cancellation, and session expiry outcomes. #### Responsibilities | Feature | Client | Nium | | ------------------------------------ | :----: | :---: | | Session creation | **X** | | | Beneficiary redirect | **X** | | | Form experience and field validation | | **X** | | Payment account creation | | **X** | | Outcome handling and redirect | **X** | | ## Branding You can add your organization's logo to the Beneficiary Form for a consistent customer experience. Your logo appears at the top left corner of the form, replacing the Nium logo shown in the default view. Provide your logo to your Nium account manager during initial setup. ## Prerequisites Before integrating Beneficiary Forms: - Your client account must be onboarded in Nium. You need your `clientHashId`, `clientSecret`, and API key. - A customer record (`customerHashId`) must exist for the entity acting as the remitter. - Hosted Components must be enabled for your account. Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable and configure this feature. ## Create a Beneficiary Form session ### Step 1: Request access Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable Beneficiary Forms for your account. ### Step 2: Create a session Use the [Initiate Pre-built Form](/api#tag/pre-built-forms/POST/api/v1/client/{clientHashId}/prebuilt-forms-init) request to generate a `sessionId`. #### Request example ```shell curl --request POST "https://gateway.nium.com/api/v1/client/{clientHashId}/prebuilt-forms-init" \ --header "Content-Type: application/json" \ --header "x-api-key: {x-api-key}" \ --data '{ "clientSecret": "{clientSecret}", "modules": ["payment"], "referenceId": "{your-beneficiary-reference-id}", "userDetails": { "name": "Jane Smith", "email": "jane.smith@example.com", "entityType": "individual" }, "customerHashId": "{customerHashId}", "redirectUris": { "success": "https://yourplatform.com/payment/success", "cancel": "https://yourplatform.com/payment/cancel", "refresh": "https://yourplatform.com/payment/refresh" } }' ``` | Field | Type | Required | Description | | ------------------------ | ------ | :------: | ---------------------------------------------------------------------------------------- | | `clientSecret` | String | Required | Client secret for authentication. Keep this server-side — never expose in frontend code. | | `modules` | Array | Required | Set to `["payment"]` for Beneficiary Forms. | | `referenceId` | String | Required | Your internal identifier for the beneficiary. | | `userDetails.name` | String | Required | Full name of the beneficiary. | | `userDetails.email` | String | Required | Email address of the beneficiary. | | `userDetails.entityType` | String | Required | `individual` or `business`. | | `userDetails.mobile` | String | Optional | Mobile number of the beneficiary. | | `customerHashId` | String | Required | Unique identifier of the customer acting as remitter. | | `redirectUris.success` | String | Required | URL to redirect the beneficiary after successful completion. | | `redirectUris.cancel` | String | Required | URL to redirect the beneficiary if they cancel. | | `redirectUris.refresh` | String | Required | URL to redirect the beneficiary if the session expires. | #### Successful response ```json { "status": "SUCCESS", "sessionId": "25f82bda-d630-4b27-91e0-e99eaa9754f4", "redirectUrl": "https://onboard.sandbox.nium.com?code=25f82bda-d630-4b27-91e0-e99eaa9754f4", "expiresInSeconds": 30, "error": null } ``` | Field | Description | | ------------------ | ----------------------------------------------------------------------- | | `sessionId` | One-time session code. Expires after 30 seconds — redirect immediately. | | `redirectUrl` | The full hosted form URL with the session code appended. | | `expiresInSeconds` | Time in seconds before the session expires. | ### Step 3: Open the form Redirect the beneficiary to the `redirectUrl` returned in the session response. The session expires after 30 seconds — initiate the redirect immediately after receiving a successful response. The form can be opened as a full-page redirect or embedded in an iframe. The `redirectUrl` in sandbox responses points to the sandbox environment. Your Nium account manager will confirm the production URL during onboarding. ### Step 4: Handle outcomes When the beneficiary completes, cancels, or lets the session expire, Nium redirects them to the URI you provided in the session request. | Outcome | Redirect target | Query parameters | | --------- | ---------------------- | ------------------------- | | Completed | `redirectUris.success` | `?beneficiaryHashId={id}` | | Cancelled | `redirectUris.cancel` | — | | Expired | `redirectUris.refresh` | — | On success, store the `beneficiaryHashId` — you need it to retrieve payment account details and to initiate payouts. ### Step 5: Retrieve the beneficiary record After a beneficiary completes the form, use the following endpoints to retrieve their record and payment account details. **List all beneficiaries:** ```shell curl --location 'https://gateway.nium.com/api/v3/client/{clientHashId}/customer/{customerHashId}/beneficiaries' \ --header 'x-api-key: {x-api-key}' ``` **Get a specific beneficiary:** ```shell curl --location 'https://gateway.nium.com/api/v3/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}' \ --header 'x-api-key: {x-api-key}' ``` **List payment accounts for a beneficiary:** ```shell curl --location 'https://gateway.nium.com/api/v3/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts' \ --header 'x-api-key: {x-api-key}' ``` ## Form walkthrough The beneficiary completes the form across four steps. Nium guides them through each step in sequence. **Step 1: Demographic information** The beneficiary selects whether they are an individual or a business, then enters their name and address details. Demographic information **Step 2: Communication preferences** The beneficiary selects their preferred communication method (SMS or email) and provides their phone number and email address. Both are required as backup contact methods. The beneficiary accepts the Terms and Conditions and Privacy Policy before proceeding. Communication preferences **Step 3: Account type** The beneficiary selects the country where they want to receive payments, their preferred payment method (bank transfer or SWIFT), and the currency. Account type **Step 4: Bank transfer details** The beneficiary enters their bank account details — ACH code, account number, and account type. Nium validates the details and creates the payment account on submission. Bank transfer details ## Error reference | Code | Description | Resolution | | ---------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | | `CLIENT_NOT_FOUND` | `clientHashId` does not match an active Nium client. | Confirm the correct `clientHashId`. Contact Nium Support if the issue persists. | | `INVALID_CREDENTIALS` | `clientSecret` does not match the provided `clientHashId`. | Verify the correct `clientSecret` is configured. | | `CLIENT_INACTIVE` | Client account is disabled. | Contact Nium Support to review or restore the account. | | `MODULE_NOT_ALLOWED` | Beneficiary Forms are not enabled for your account. | Contact Nium Support to confirm which forms are enabled. | | `CUSTOMER_NOT_FOUND` | `customerHashId` does not exist or is not accessible. | Verify the correct `customerHashId` is provided. | | `SESSION_NOT_FOUND` | Session code is invalid or expired. | Create a new session and restart the flow. | | `SESSION_ALREADY_USED` | Session has already been completed. | Create a new session to continue. | ## Security - **Keep `clientSecret` server-side**: Never expose it in frontend code. All session creation requests must originate from your backend. - **Redirect immediately**: Sessions expire after 30 seconds. Redirect the beneficiary to the hosted form as soon as a valid `sessionId` is returned. - **Use HTTPS**: All requests to Nium APIs must use HTTPS in production environments. - **Store credentials securely**: Use a secrets manager (such as AWS Secrets Manager or HashiCorp Vault) for `clientSecret` and API keys. Never commit credentials to source control. ## Next steps After a beneficiary completes the Beneficiary Form, you can: - Initiate payouts using the `beneficiaryHashId` and `paymentAccountId` via the [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) endpoint. - Collect tax information from the beneficiary using [Tax Forms](/docs/developers/pre-built-forms/tax-forms). --- # Tax Forms URL: https://docs.nium.com/docs/developers/pre-built-forms/tax-forms Tax Forms are secure, Nium-hosted forms that collect tax information from your beneficiaries or recipients — linking verified tax records directly to their Nium beneficiary account without requiring you to build or maintain a custom tax collection experience. This form is helpful for clients that: - Operate platforms that pay out to beneficiaries or recipients subject to US tax reporting (for example, 1099 filing) - Need to collect W-9 (US persons) or W-8 (non-US persons) information at scale - Want Nium to handle tax form selection, validation, and data submission - Have already onboarded beneficiaries using [Beneficiary Forms](/docs/developers/pre-built-forms/beneficiary-forms) ## Overview To collect tax information using Tax Forms, clients: 1. Register a filer entity in Nium to act as the tax filer on behalf of beneficiaries. 2. Create a session using the Nium API, providing the beneficiary's details and redirect URIs. 3. Redirect the beneficiary to the Nium-hosted Tax Form using the returned session URL. 4. The beneficiary selects their tax form (W-9, W-8BEN, or W-8BEN-E) and completes a guided 5-step flow. 5. Nium links the tax information to the beneficiary's existing Nium record. 6. The beneficiary is redirected to the client's success URL. ## Key features Tax Forms guide the beneficiary through form selection and all required fields — covering taxpayer information, federal classification, tax identification number, certification, and delivery preferences. W-9 is recommended for US persons; W-8BEN and W-8BEN-E are available for non-US individuals and entities respectively. Other benefits of using Tax Forms include: - No frontend build required — Nium hosts and maintains the form. - Beneficiary-driven tax form selection — W-9, W-8BEN, or W-8BEN-E. - Secure session-based access — each session is single-use and short-lived. - Configurable redirect URIs for success, cancellation, and session expiry outcomes. #### Responsibilities | Feature | Client | Nium | | ------------------------------------ | :----: | :---: | | Filer registration | **X** | | | Session creation | **X** | | | Beneficiary redirect | **X** | | | Tax form selection (W-9 or W-8) | | **X** | | Form experience and field validation | | **X** | | Tax record creation and linking | | **X** | | Outcome handling and redirect | **X** | | ## Branding You can add your organization's logo to the Tax Form for a consistent customer experience. Your logo appears at the top left corner of the form, replacing the Nium logo shown in the default view. Provide your logo to your Nium account manager during initial setup. ## Prerequisites Tax Forms have two hard dependencies. Both must be in place before you create a session. **1. Beneficiary must exist** The beneficiary must have already completed a [Beneficiary Form](/docs/developers/pre-built-forms/beneficiary-forms). Tax Forms link tax information to an existing Nium beneficiary record — if no record exists, the session request fails with a `BENEFICIARY_REQUIRED` error. **2. Filer must be registered** A filer entity represents your organisation as the tax filer for your beneficiaries. You need a `filerHashId` before initiating any Tax Form session. To register a filer, use the [Create Filer](/api#tag/filers/POST/api/v1/client/{clientHashId}/filers) endpoint: ```shell curl --request POST "https://gateway.nium.com/api/v1/client/{clientHashId}/filers" \ --header "Content-Type: application/json" \ --header "x-api-key: {x-api-key}" \ --data '{ "customerHashId": "{customerHashId}", "name": "Acme Corp", "taxResidentCountryCode": "us", "tin": { "number": "123456780", "type": "ein" }, "address": { "type": "residence", "line1": "123 Main St", "city": "San Francisco", "state": "CA", "countryCode": "us", "postalCode": "94560" }, "contact": { "name": "Jane Smith", "departmentTitle": "Tax Department", "phoneNumber": { "number": "4155551234", "countryCode": "us" } } }' ``` A successful response returns a `filerHashId`. Store this — you need it for every Tax Form session. **3. Client account and Hosted Components enabled** Your client account must be onboarded in Nium with a `clientHashId`, `clientSecret`, and API key. Hosted Components must also be enabled for your account. Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable and configure this feature. ## Create a Tax Form session ### Step 1: Request access Contact your Nium account manager or [Nium Support](mailto:support@nium.com) to enable Tax Forms for your account. ### Step 2: Create a session Use the [Initiate Pre-built Form](/api#tag/pre-built-forms/POST/api/v1/client/{clientHashId}/prebuilt-forms-init) request to generate a `sessionId`. #### Request example ```shell curl --request POST "https://gateway.nium.com/api/v1/client/{clientHashId}/prebuilt-forms-init" \ --header "Content-Type: application/json" \ --header "x-api-key: {x-api-key}" \ --data '{ "clientSecret": "{clientSecret}", "modules": ["tax"], "referenceId": "{your-beneficiary-reference-id}", "userDetails": { "name": "Jane Smith", "email": "jane.smith@example.com", "entityType": "individual" }, "customerHashId": "{customerHashId}", "redirectUris": { "success": "https://yourplatform.com/tax/success", "cancel": "https://yourplatform.com/tax/cancel", "refresh": "https://yourplatform.com/tax/refresh" } }' ``` | Field | Type | Required | Description | | ------------------------ | ------ | :------: | ---------------------------------------------------------------------------------------------------------------- | | `clientSecret` | String | Required | Client secret for authentication. Keep this server-side — never expose in frontend code. | | `modules` | Array | Required | Set to `["tax"]` for Tax Forms. | | `referenceId` | String | Required | Your internal identifier for the beneficiary. Must match the `referenceId` used in the Beneficiary Form session. | | `userDetails.name` | String | Required | Full name of the beneficiary. | | `userDetails.email` | String | Required | Email address of the beneficiary. | | `userDetails.entityType` | String | Required | `individual` or `business`. | | `userDetails.mobile` | String | Optional | Mobile number of the beneficiary. | | `customerHashId` | String | Required | Unique identifier of the customer acting as remitter. | | `redirectUris.success` | String | Required | URL to redirect the beneficiary after successful completion. | | `redirectUris.cancel` | String | Required | URL to redirect the beneficiary if they cancel. | | `redirectUris.refresh` | String | Required | URL to redirect the beneficiary if the session expires. | #### Successful response ```json { "status": "SUCCESS", "sessionId": "3060f802-535c-444b-853d-6fabf540e833", "redirectUrl": "https://onboard.sandbox.nium.com?code=3060f802-535c-444b-853d-6fabf540e833", "expiresInSeconds": 30, "error": null } ``` | Field | Description | | ------------------ | ----------------------------------------------------------------------- | | `sessionId` | One-time session code. Expires after 30 seconds — redirect immediately. | | `redirectUrl` | The full hosted form URL with the session code appended. | | `expiresInSeconds` | Time in seconds before the session expires. | ### Step 3: Open the form Redirect the beneficiary to the `redirectUrl` returned in the session response. The session expires after 30 seconds — initiate the redirect immediately after receiving a successful response. The form can be opened as a full-page redirect or embedded in an iframe. The beneficiary selects their residency status and tax form — W-9 is recommended for US persons; W-8BEN and W-8BEN-E are available for non-US individuals and entities. The `redirectUrl` in sandbox responses points to the sandbox environment. Your Nium account manager will confirm the production URL during onboarding. ### Step 4: Handle outcomes When the beneficiary completes, cancels, or lets the session expire, Nium redirects them to the URI you provided in the session request. | Outcome | Redirect target | Query parameters | | --------- | ---------------------- | ---------------------- | | Completed | `redirectUris.success` | `?taxPayerHashId={id}` | | Cancelled | `redirectUris.cancel` | — | | Expired | `redirectUris.refresh` | — | ## Form walkthrough The following shows the W-9 flow. The W-8BEN and W-8BEN-E flows follow the same structure with form-specific fields. **Form selection** The beneficiary confirms whether they are a US person and selects their entity type. Based on their answers, the form recommends the appropriate tax form — W-9 for US persons, W-8BEN for non-US individuals, or W-8BEN-E for non-US entities. The beneficiary can also select a different form if needed. Tax form selection **Step 1 of 5: Taxpayer information** The beneficiary enters their name as it appears on their tax return, their business name (if applicable), and their mailing address. Taxpayer information **Step 2 of 5: Tax information** The beneficiary selects their federal tax classification, exemption status, and enters their tax identification number — either SSN/ITIN or EIN. Tax information **Step 3 of 5: Certification** The beneficiary reviews the IRS certification statements and signs by typing their name. The typed name acts as a legal signature certifying the accuracy of the submitted tax information. Certification **Step 4 of 5: Review** The beneficiary reviews all entered information — taxpayer details and tax information — before submission. Each section has an edit option to make corrections. Review **Step 5 of 5: Preferences** The beneficiary confirms their contact details, preferred communication method, and how they want to receive their 1099 form (by mail or electronically). They accept the Terms and Conditions and Privacy Policy before submitting. Preferences and submission ## Error reference | Code | Description | Resolution | | ---------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `CLIENT_NOT_FOUND` | `clientHashId` does not match an active Nium client. | Confirm the correct `clientHashId`. Contact Nium Support if the issue persists. | | `INVALID_CREDENTIALS` | `clientSecret` does not match the provided `clientHashId`. | Verify the correct `clientSecret` is configured. | | `CLIENT_INACTIVE` | Client account is disabled. | Contact Nium Support to review or restore the account. | | `MODULE_NOT_ALLOWED` | Tax Forms are not enabled for your account. | Contact Nium Support to confirm which forms are enabled. | | `CUSTOMER_NOT_FOUND` | `customerHashId` does not exist or is not accessible. | Verify the correct `customerHashId` is provided. | | `BENEFICIARY_REQUIRED` | No beneficiary record exists for this `referenceId`. | Complete a [Beneficiary Form](/docs/developers/pre-built-forms/beneficiary-forms) session for this beneficiary before initiating a Tax Form. | | `SESSION_NOT_FOUND` | Session code is invalid or expired. | Create a new session and restart the flow. | | `SESSION_ALREADY_USED` | Session has already been completed. | Create a new session to continue. | ## Security - **Keep `clientSecret` server-side**: Never expose it in frontend code. All session creation requests must originate from your backend. - **Redirect immediately**: Sessions expire after 30 seconds. Redirect the beneficiary to the hosted form as soon as a valid `sessionId` is returned. - **Use HTTPS**: All requests to Nium APIs must use HTTPS in production environments. - **Store credentials securely**: Use a secrets manager (such as AWS Secrets Manager or HashiCorp Vault) for `clientSecret` and API keys. Never commit credentials to source control. ## Next steps After a beneficiary completes the Tax Form, Nium links the tax record to their beneficiary account. You can then: - Initiate payouts using the [Transfer Money](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) endpoint. - Use the `taxPayerHashId` to retrieve or update tax records via the Nium API. - Contact your Nium account manager for guidance on 1099 filing workflows. --- # KYC Pre-built Form URL: https://docs.nium.com/docs/developers/pre-built-forms/kyc-form Learn how to use Nium's KYC pre-built form to collect identity verification information during customer onboarding. The **KYC Pre-built Form** allows you to collect identity verification information from customers without building your own verification interface. Instead of building a custom onboarding UI, you generate a secure session link and direct the customer to the pre-built form. Nium manages document collection, identity verification, and compliance checks based on regional regulatory requirements. The KYC pre-built form is the recommended identity collection method for **Customer Onboarding v5**. ## What the KYC pre-built form does The form manages the identity verification workflow for your onboarding process. Using the pre-built form: - Customers provide identity details through a guided verification flow. - Nium determines required documents based on region and configuration. - Identity verification may occur instantly or through manual document review. - Verification results update the customer's onboarding status. This approach allows you to integrate onboarding without building and maintaining your own KYC interface. ## When to use the pre-built KYC form Use the pre-built form if you: - Do not want to build and maintain your own KYC interface - Want Nium to manage region-specific document requirements - Want a branded onboarding experience - Want automated verification where available ## How it works The KYC verification workflow follows these steps: 1. Create a session using the **Create Session API**. 2. Generate a form link using the returned `sessionId`. 3. Share the link or embed the form in your application. 4. The customer completes identity verification. 5. Nium processes verification checks. 6. The customer's onboarding `status` and `substatus` update accordingly. You can retrieve the latest status using the **Get Customer Details API** or subscribe to **Customer Lifecycle webhooks**. ## Responsibilities When using the KYC pre-built form: - **Nium manages** document collection and identity verification. - **Nium determines** document requirements based on region and configuration. - **The client is responsible** for initiating onboarding and generating sessions. - **The client controls** when the onboarding process begins. ## Branding You can provide a company logo to display on the pre-built form. If no branding is provided, the default **Nium logo** is displayed. Contact your Nium account representative or [Nium Support](mailto:support@nium.com) to configure form branding. *** # Integrating pre-built forms ## Step 1: Provide branding assets (optional) Share your company logo with your Nium account representative or [Nium Support](mailto:support@nium.com). If no logo is provided, the Nium logo appears in the form. ## Step 2: Create a session Create a session to generate a `sessionId`. ### Example request ```shell curl --location 'https://gateway.nium.com/api/v1/client/{clientHashId}/sessions' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ***********' \ --data '{ "featureType": "kyc_form", "integrationType": "standalone", "expiry": "2026-02-25T10:30:00Z", "rollingDurationMinutes": 200, "onBehalf": false, "customerHashId": "549d0fd0-d5f1-411f-85a3-q19cbfd310r4" }' ``` ### Request parameters | Field | Type | Required | Description | Allowed values | | ------------------------ | ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `featureType` | string | Yes | Type of form to generate. | `kyc_form` | | `customerHashId` | string | Yes | Unique customer identifier returned from the [Create Customer (v5)](/api#tag/customer-onboarding-v5/POST/api/v5/client/{clientHashId}/customers) request. | — | | `integrationType` | string | Yes | Determines how the form is presented to the user. | `embedded`, `standalone` | | `expiry` | string (ISO-8601) | Yes | Absolute expiration time for the session. | — | | `rollingDurationMinutes` | integer | Yes | Inactivity timeout before the session expires. Minimum value: `1`. | — | | `domain` | string | Conditional | Required when `integrationType = embedded`. Must match the session domain. | — | | `onBehalf` | boolean | Yes | Indicates whether the client accesses the form on behalf of the customer. | `true`, `false` | | `email` | string | Conditional | Required when `onBehalf = true`. Used for OTP authentication. | — | - `expiry` defines the **absolute expiration time** of the session. - `rollingDurationMinutes` defines how long the session remains active during inactivity. ## Step 3: Present the form Append the generated `sessionId` to the form URL. ``` Sandbox: https://nformify-sandbox.nium.com/kyc?sessionId= Production: https://nformify.nium.com/kyc?sessionId= ``` You can present the form in two ways: | Integration type | Description | | ---------------- | ------------------------------------------------------- | | `embedded` | Displays the form within your application or dashboard. | | `standalone` | Opens the form in a new browser tab. | ## Step 4: Customer accesses the form The authorized signatory opens the form link. If authentication is required, an **OTP is sent to the configured email address**.\ The user must enter the OTP to proceed. ## Step 5: Customer completes KYC After authentication, the customer completes identity verification. The form displays: - The list of individuals requiring verification - Required documents based on region and stakeholder role - Real-time verification status updates The user must complete KYC for: - The authorized signatory - Any additional stakeholders specified during onboarding Depending on configuration: - Verification may complete instantly through automated checks - Documents may be uploaded for manual verification *** # Verification status updates Customer verification status changes as KYC progresses. ### Before KYC submission | Field | Value | | ----------- | -------------- | | `status` | `pending` | | `substatus` | `awaiting_kyc` | ### During verification review | Field | Value | | ----------- | -------------- | | `status` | `pending` | | `substatus` | `under_review` | ### After verification completes The customer `status` updates based on the verification outcome. Examples include: - `clear` - `rejected` You can retrieve the latest verification status using: - **Get Customer Details API** - **Customer lifecycle webhooks** *** # Session expiration If a form session expires: - The form link becomes invalid. - A new session must be generated. - Previously submitted information remains associated with the customer. Multiple sessions can be generated for the same customer if needed. *** # Retrying verification If a user does not complete the form: - The session expires based on `expiry` or `rollingDurationMinutes`. - A new session can be generated. - Previously submitted information remains associated with the customer. If verification fails: - The customer's KYC status updates accordingly. - A new session may be required depending on the failure reason. --- # Notifications and Webhooks URL: https://docs.nium.com/docs/developers/notifications-and-webhooks Nium uses webhooks to notify you, the clients, of your applications when any of the observable events occur. You can provide Nium the URL of your host endpoint to receive the webhook events from the Nium One platform. The platform delivers the webhook events to your client-specified endpoint with a `POST` HTTP request method. You need to provide the required URL in the following format: `https:///webhook` Nium sends different payloads depending on the trigger event. The trigger event can be identified based on the template field in the payload body. ### Webhook event structure - The body of the webhook event generally carries just enough details about the event. You're expected to use other APIs to fetch more details. - The body of the webhook event includes a field template to indicate the webhook event type. - Every webhook event includes the `x-request-id` data element in the header. The platform populates unique values in this data element for every unique webhook event, except when the platform attempts to redeliver a webhook event. - You can also configure a static identifier, say `x-partner-key`, as part of the client setup, so the platform can include the client-specified identifier in the header of every webhook event. The following is an example of a webhook event: ```curl Sample Webhook Event curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"a344b0c8-d27d-4db5-8194-aacdefb558ca", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"10.00", "transactionDate":"2020-09-29 09:24:46", "balanceCurrency":"SGD", "authAmount":"10.0", "walletBalance":"102.00", "mcc":"5499", "merchantName":"Frankie Tibbs", "merchantCountry":"IN", "merchantCity":"MUMBAI", "authCode":"114733" "effectiveAuthAmount":"11", "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319d2", "template":"CARD_POS_APPROVED_WEBHOOK" }' ``` ### Event and notification types Webhook events and notifications fall into the following categories: - **[Callbacks](/docs/developers/notifications-and-webhooks/callbacks):** Manage compliance-related events, notifications, and customer redirection callbacks. - **[Platform](/docs/developers/notifications-and-webhooks/platform-events):** Monitor core platform events, including client setup, virtual account assignments, and wallet transfers. - **[Payouts](/docs/developers/notifications-and-webhooks/payout-events):** Receive updates on payout lifecycles, such as transaction statuses and beneficiary verification. - **[Payins](/docs/developers/notifications-and-webhooks/payin-events):** Track events related to wallet funding, chargebacks, and funding instrument approvals. - **[Issuing and Cards](/docs/developers/notifications-and-webhooks/issuing-and-card-events):** Stay informed about card-related events, such as activation, transactions, declines, and settlements. ### Delivery Nium supports two forms of webhook events delivery: - At most once, by default - Retry delivery, which needs to be explicitly set up #### At most once The default delivery configuration that Nium supports is to deliver every webhook event at most once. An attempt is made to deliver a webhook event. If the delivery fails, due to a timeout or an HTTP response status code, other than 200, the platform does *not* retry delivering the webhook event. #### Retry delivering webhook You can work with Nium to configure the webhook events that you want the platform to retry delivering. It works in the following way: 1. Nium can enable a retry for specific webhook events—for example, the `Card Wallet Funding` webhook, which is triggered whenever a customer's wallet receives funds. 2. As soon as funding is applied to a customer wallet, under your client setup, Nium triggers the `Card Wallet Funding` webhook event to the your configured webhook url (the *Original Attempt*). 3. If delivery fails, Nium retries delivery up to 20 times (*Retry Attempt #1* through *Retry Attempt #20*). 4. Retries are sent on a fixed schedule: one retry every 5 minutes (with a maximum retry window of approximately 100 minutes). 5. Every redelivery includes the same `x-request-id` header value that was sent in the *Original Attempt*. This *is not* the default approach available for every webhook event for clients. Clients that want this feature enabled, for example, the platform retrying to deliver webhook events, can reach out to their Nium representative for support. This needs to be configured at the chosen webhook event level as part of the client configuration in the platform. Every redelivered webhook event has the same `x-request-id` header value to help you identify and ignore such duplicate webhook events. ## Notifications Nium supports three types of system-generated notifications, which are similar to trigger alerts that are sent in response to a specific user action or event. - Email notifications - SMS notifications - Webhooks notifications ### Email notifications Nium can trigger different types of customer notifications through email. The notifications follow the default Nium template but can be customized or turned off based on the client's needs. ### SMS notifications Nium can send Short Message Service (SMS) notifications to customers only for the 3D Secure (3DS) One Time Password ( OTP) protocol or the Visa Token Service (VTS) for Google Pay and Apple Pay. ### Webhooks notifications Nium provides webhooks to trigger email, SMS, or in-app notifications. Refer to the [Webhooks overview](/docs/developers/notifications-and-webhooks) guide. The following table summarizes different scenarios and corresponding notifications triggered **with SMS**: | Scenario | Email template | Webhook | SMS | | :---------------------------------------------------------------------------- | :------------------------- | :--------------------------------------------------------------------------------------------------- | :-- | | This template is triggered while adding a card to Google Pay. See note above. | `CARD_GOOGLEPAY_EMAIL` | [VTS Token](/docs/developers/notifications-and-webhooks/issuing-and-card-events/vts-token) | | | 3DS OTP during 3DS online transaction (Version 2 is currently in use). | `CARD_SAMPLE_EMAIL` | [3DS OTP](/docs/developers/notifications-and-webhooks/issuing-and-card-events/3ds-one-time-password) | | | 3DS OTP during 3DS online transaction. | `CARD_3DS_OTP_EMAIL` | [3DS OTP](/docs/developers/notifications-and-webhooks/issuing-and-card-events/3ds-one-time-password) | | | VTS OTP during VTP provisioning. | `CARD_VTS_PROVISION_EMAIL` | [VTS Token](/docs/developers/notifications-and-webhooks/issuing-and-card-events/vts-token) | | The following table summarizes different scenarios and corresponding notifications triggered **without SMS**: | Scenario | Email template | Webhook | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | The cardholder makes a balance transfer from one currency wallet to another currency wallet. This is applicable to the multi-currency program. | `CARD_BALANCE_TRF_BETWEEN_CURRENCIES_` `WITHIN_SAME_WALLET_EMAIL` | [Balance Transfer within Wallet](/docs/developers/notifications-and-webhooks/platform-events/balance-transfer-within-wallet) | | This template is triggered when a customer is registered. | `CARD_CUSTOMER_REGISTRATION_EMAIL` | [Customer Registration](/docs/developers/notifications-and-webhooks/platform-events/customer-registration) | | This template is triggered during a client prefund-request notification. | `CARD_PRE_FUND_APPROVAL_EMAIL` | [Prefund Approval](/docs/developers/notifications-and-webhooks/platform-events/prefund-approval) | | This template is triggered when the wallet is funded. | `CARD_WALLET_FUNDING_EMAIL` | [Wallet Funding](/docs/developers/notifications-and-webhooks/platform-events/fund-received-from-wallet) | | This template is triggered in the event of wallet encashment. | `CARD_WALLET_ENCASHMENT_EMAIL` | [Wallet Encashment](/docs/developers/notifications-and-webhooks/platform-events/wallet-enhancement) | | This template is triggered when a balance transfer happens within a customer's wallet. | `CARD_BALANCE_TRF_BETWEEN_CURRENCIES_` `WITHIN_SAME_WALLET_EMAIL` | [Balance Transfer Within Wallet](/docs/developers/notifications-and-webhooks/platform-events/balance-transfer-within-wallet) | | This template is triggered when a transfer between two customers occurs under the same client program. | `CARD_P2P_TRANSFER_BETWEEN_WALLETS_EMAIL` | [P2P Transfer Between Wallets](/docs/developers/notifications-and-webhooks/platform-events/p2p-transfer-between-wallets) | | This template is triggered when a physical card is assigned to a customer. | `CARD_ASSIGN_CARD_EMAIL` | No webhook | | This template is triggered when an `ADD-ON` card is issued using the [Add Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/add-card) API. | `CARD_ADD_ON_CARD_ISSUE_EMAIL` | [Add On Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/add-on-card) | | This template is triggered when the card's Personal Identification Number (PIN) is set. | `CARD_SET_PIN_EMAIL` | [Set Pin](/docs/developers/notifications-and-webhooks/issuing-and-card-events/set-pin) | | This template is triggered when the transaction is declined due to an incorrect PIN. | `CARD_PIN_BLOCK_DECLINE_EMAIL` | [Pin Block Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/pin-block-decline) | | This template is triggered when the card is replaced using the [Issue Replacement Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-replacement) API. | CARD\_CARD\_REPLACEMENT\_EMAIL | No webhook | | This template is triggered when the card is temporarily blocked. | `CARD_TEMPORARY_BLOCK_EMAIL` | [Temporary Block](/docs/developers/notifications-and-webhooks/issuing-and-card-events/temporary-block) | | This template is triggered when a temporarily blocked card is removed. | `CARD_TEMPORARY_BLOCK_REMOVAL_EMAIL` | [Temporary Block Removal](/docs/developers/notifications-and-webhooks/issuing-and-card-events/temporary-block-removal) | | This template is triggered when the card is permanently blocked. | `CARD_PERMANENT_BLOCK_EMAIL` | [Permanent Block](/docs/developers/notifications-and-webhooks/issuing-and-card-events/permanent-block) | | This template is triggered when the permanently blocked card is being replaced with a new card. | `CARD_PERMANENT_BLOCK_REPLACEMENT_EMAIL` | No webhook | | This template is triggered when the POS transaction is approved. | `CARD_POS_APPROVED_EMAIL` | [POS Approved](/docs/developers/notifications-and-webhooks/issuing-and-card-events/pos-approved) | | This template is triggered when the transaction is through an ATM. | `CARD_ATM_APPROVED_EMAIL` | [ATM Approved](/docs/developers/notifications-and-webhooks/issuing-and-card-events/atm-approved) | | This template is triggered on successful VTS provisioning for Apple Pay. | `CARD_ADD_CARD_CONFIRMATION_APPLEPAY_EMAIL` | [VTS Provisioning](/docs/developers/notifications-and-webhooks/issuing-and-card-events/vts-provisioning) `walletProvider` = `applePay` | | This template is triggered on successful VTS provisioning for Google Pay. | `CARD_ADD_CARD_CONFIRMATION_GOOGLEPAY_EMAIL` | [VTS Provisioning](/docs/developers/notifications-and-webhooks/issuing-and-card-events/vts-provisioning) `walletProvider` = `googlePay` | | This template is triggered when the transaction is declined due to a blocked card. | `CARD_BLOCK_CARD_DECLINE_EMAIL` | [Block Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/block-decline) | | This template is triggered when the transaction is declined due to an inactive card. | `CARD_INACTIVE_CARD_DECLINE_EMAIL` | [Inactive Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/inactive-decline) | | This template is triggered when the transaction is declined due to insufficient funds. | `CARD_INSUFFICIENT_FUNDS_DECLINED_EMAIL` | [Insufficient Funds Declined](/docs/developers/notifications-and-webhooks/issuing-and-card-events/insufficient-funds-declined) | | This template is triggered when the transaction is declined because the card is expired. | `CARD_EXPIRED_CARD_EMAIL` | [Expired Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/expired-card) | | This template is triggered when the card restricts the transactions. | `CARD_RESTRICTED_TRANSACTIONS_EMAIL` | [Restricted Transactions](/docs/developers/notifications-and-webhooks/issuing-and-card-events/restricted-transactions) | | This template is triggered when a transaction isn't supported. | `CARD_TRANSACTION_NOT_SUPPORTED_EMAIL` | [Transaction Not Supported](/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-not-supported) | | This template is triggered when the card transaction limit is exceeded. | `CARD_TRANSACTION_LIMIT_EXCEEDS_EMAIL` | [Transaction Limit Exceeds](/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-limit-exceeds) | | This template is triggered when the card has the wrong Card Verification Value 2 (CVV2). | `CARD_WRONG_CVV2_EMAIL` | [Wrong CVV2](/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-cvv2) | | This template is triggered when the card has the wrong expiration date. | `CARD_WRONG_EXPIRY_EMAIL` | [Wrong Expiry](/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-expiry) | | This template is triggered when the transaction is declined due to the wrong PIN entry. | `CARD_WRONG_PIN_DECLINE_EMAIL` | [Wrong PIN Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-pin-decline) | | This template is triggered when the transaction is declined due to the wrong PIN entry. | `CARD_PIN_RETRY_EXCEED_DECLINE_EMAIL` | [Pin Retry Exceed Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/pin-retry-exceed-decline) | | This template is triggered manually by the Fraud and Risk team for specific customers. | `CARD_RISK_AWARENESS_PIN_EMAIL` | No webhook | | This template is triggered manually by the Fraud and Risk team for specific customers. | `CARD_SUSPECTED_COMPROMISE_EMAIL` | No webhook | | This template is triggered manually by the Fraud and Risk team for specific customers. | `CARD_SUSPECTED_MISUSE_EMAIL` | No webhook | | 3DS OTP during 3DS online transaction. | `CARD_SAMPLE_EMAIL` | [3DS OTP](/docs/developers/notifications-and-webhooks/issuing-and-card-events/3ds-one-time-password) | | This template is triggered when the transaction is declined due to the Security and Risk policy set by Nium. | `CARD_MISC_EMAIL` | [Miscellaneous](/docs/developers/notifications-and-webhooks/issuing-and-card-events/miscellaneous) | | This template is triggered when the card system is down. | `CARD_SYSTEM_DOWN_EMAIL` | [Card System Down](/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-system-down) | | This template is triggered after adding a beneficiary with the payout method of the value `BANK`. | `ADD_BENEFICIARY_BANK_EMAIL` | No webhook | | This template is triggered after adding a beneficiary with the payout method of the value `WALLET`. | `ADD_BENEFICIARY_WALLET_EMAIL` | No webhook | | This template is triggered after adding a beneficiary with the payout method of the value `CASH`. | `ADD_BENEFICIARY_CASH_EMAIL` | No webhook | | This template is triggered after adding a beneficiary with the payout method of the value`CARD`. | `ADD_BENEFICIARY_CARD_EMAIL` | No webhook | | This template is triggered after editing a beneficiary with the payout method of the value `BANK`. | `EDIT_BENEFICIARY_BANK_EMAIL` | No webhook | | This template is triggered after editing a beneficiary with the payout method of the value`WALLET`. | `EDIT_BENEFICIARY_WALLET_EMAIL` | No webhook | | This template is triggered after editing a beneficiary with the payout method of the value `CASH`. | `EDIT_BENEFICIARY_CASH_EMAIL` | No webhook | | This template is triggered after editing a beneficiary with the payout method of the value `CARD`. | `EDIT_BENEFICIARY_CARD_EMAIL` | No webhook | | This template is triggered after deleting a beneficiary with the payout method of the value `BANK`. | `DELETE_BENEFICIARY_BANK_EMAIL` | No webhook | | This template is triggered after deleting a beneficiary with the payout method of the value `WALLET`. | `DELETE_BENEFICIARY_WALLET_EMAIL` | No webhook | | This template is triggered after deleting a beneficiary with the payout method of the value `CASH`. | `DELETE_BENEFICIARY_CASH_EMAIL` | No webhook | | This template is triggered after deleting a beneficiary with the payout method of the value `CARD`. | `DELETE_BENEFICIARY_CARD_EMAIL` | No webhook | | This template is triggered when a remittance transaction is initiated with the payout method of the value `BANK`. | `REMIT_TRANSACTION_INITIATED_EMAIL` | [Remit Transaction Initiated](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated) | | This template is triggered when a remittance transaction is initiated with the payout method of the value `CASH`. | `REMIT_TRANSACTION_INITIATED_CASH_EMAIL` | [Remit Transaction Initiated](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated) | | This template is triggered when a remittance transaction is initiated with the payout method of the value`WALLET`. | `REMIT_TRANSACTION_INITIATED_WALLET_EMAIL` | [Remit Transaction Initiated](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated) | | This template is triggered when a remittance transaction is initiated with the payout method of the value `CARD`. | `REMIT_TRANSACTION_INITIATED_CARD_EMAIL` | [Remit Transaction Initiated](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated) | | This template is triggered when a payout is done of the value `sent to Sender`. | `REMIT_TRANSACTION_SENT_TO_BANK_EMAIL` | [Remit Transaction Sent to Bank](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-sent-to-bank) | | This template is triggered when a payout is done of the value `sent to Beneficiary`. | `REMIT_TRANSACTION_SENT_TO_BANK_CASH_BENI_EMAIL` | [Remit Transaction Sent to Bank](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-sent-to-bank) | | This template is triggered when a remittance transaction is made with the payout method of the value `BANK is paid`. | `REMIT_TRANSACTION_PAID_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered when a remittance transaction is made with the payout method of the value `CASH is paid`. | `REMIT_TRANSACTION_PAID_CASH_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered when a remittance transaction is made with the payout method of the value `WALLET is paid`. | `REMIT_TRANSACTION_PAID_WALLET_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered when a remittance transaction is made with the payout method of the value `CARD is paid.` | `REMIT_TRANSACTION_PAID_CARD_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered to a beneficiary when a remittance transaction is made with the payout method of the value `BANK is paid`. | `REMIT_TRANSACTION_PAID_BANK_BENI_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered to a beneficiary when a remittance transaction is made with the payout method of the value `CASH is paid`. | `REMIT_TRANSACTION_PAID_CASH_BENI_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered to a beneficiary when a remittance transaction is made with the payout method of the value `WALLET is paid`. | `REMIT_TRANSACTION_PAID_WALLET_BENI_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered to a beneficiary when a remittance transaction is made with the payout method of the value `CARD is paid`. | `REMIT_TRANSACTION_PAID_CARD_BENI_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered when a remittance transaction is made with the payout method of the value `BANK is rejected`. | `REMIT_TRANSACTION_REJECTED_EMAIL` | No webhook | | This template is triggered when a remittance transaction is made with the payout method of the value `CASH is rejected`. | `REMIT_TRANSACTION_REJECTED_CASH_EMAIL` | No webhook | | This template is triggered when a remittance transaction is made with the payout method of the value `WALLET is rejected`. | `REMIT_TRANSACTION_REJECTED_WALLET_EMAIL` | No webhook | | This template is triggered when a remittance transaction is made with the payout method of the value `BANK is returned`. | `REMIT_TRANSACTION_RETURNED_EMAIL` | [Remit Transaction Returned](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-returned) | | This template is triggered when a remittance transaction is made with the payout method of the value `CASH is returned`. | `REMIT_TRANSACTION_RETURNED_CASH_EMAIL` | [Remit Transaction Returned](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-returned) | | This template is triggered when a remittance transaction is made with the payout method of the value `WALLET is returned`. | `REMIT_TRANSACTION_RETURNED_WALLET_EMAIL` | [Remit Transaction Returned](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-returned) | | This template is triggered when a remittance transaction is made with the payout method of the value `CARD is returned`. | `REMIT_TRANSACTION_RETURNED_CARD_EMAIL` | [Remit Transaction Returned](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-returned) | | This template is triggered when the compliance status, as a result of the Know Your Business (KYB) process, is anything other than complete for a client. | No email template | [Client KYB Status](/docs/developers/notifications-and-webhooks/platform-events/client-kyb-status) | | This template is triggered when an `ADD_ON` card is issued using the [Add Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/add-card) API. | `CARD_ADD_ON_CARD_ISSUE_EMAIL` | [Add Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/add-card) | | This template is triggered when a card is activate. | `CARD_ACTIVATION_CARD_EMAIL` | [Activate Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/activate-card) | | This template is triggered when the transaction is declined due to an insufficient client-prefund balance. | `CARD_INSUFFICIENT_FUNDS_DECLINED_EMAIL` | [Insufficient Funds Declined](/docs/developers/notifications-and-webhooks/issuing-and-card-events/insufficient-funds-declined) | | This template is triggered after adding a beneficiary with a proxy payout method. | `ADD_BENEFICIARY_PROXY_EMAIL` | No webhook | | This template is triggered after editing a beneficiary with a proxy payout method. | `EDIT_BENEFICIARY_PROXY_EMAIL` | No webhook | | This template is triggered after deleting a beneficiary with a proxy payout method. | `DELETE_BENEFICIARY_PROXY_EMAIL` | No webhook | | This template is triggered when a remittance transaction is initiated with a bank payout method. | `REMIT_TRANSACTION_INITIATED_PROXY_EMAIL` | [Remit Transaction Initiated](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated) | | This template is triggered when a remittance transaction is paid with a proxy payout method. | `REMIT_TRANSACTION_PAID_PROXY_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | | This template is triggered when a remittance transaction is returned with a proxy payout method. | `REMIT_TRANSACTION_RETURNED_PROXY_EMAIL` | [Remit Transaction Returned](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-returned) | | This template is triggered to a beneficiary when a remittance transaction is paid with a proxy payout method. | `REMIT_TRANSACTION_PAID_PROXY_BENT_EMAIL` | [Remit Transaction Paid](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) | --- # Callbacks URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/callbacks In addition to sending webhook event notifications for various event types, a client can set up their application to receive callback notifications on alerts related to compliance status changes and to assist with the automation of the eKYC flow. In addition to sending webhook event notifications for various [event types](/docs/developers/notifications-and-webhooks#event-types), a client can set up their application to receive callback notifications on alerts related to compliance status changes and to assist with the automation of the eKYC flow. ## Supported events - [Callback to receive: Transaction Compliance Status](/docs/developers/notifications-and-webhooks/callbacks/transaction-compliance-status) - [Callback to receive: Customer Compliance Status](/docs/developers/notifications-and-webhooks/callbacks/customer-compliance-status) - [Callback request to: Redirect Customers back to their Application](/docs/developers/notifications-and-webhooks/callbacks/redirect-customer) --- # Transaction Compliance Status URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/callbacks/transaction-compliance-status Nium sends a notification to the client callback URL when there's a change in compliance status and displays action is required for further processing. Nium sends a notification to the client callback URL when there's a change in compliance status and displays **action is required** for further processing. ```URL POST https://?type={requestType}&value={requestValue} ``` Example: `https://abc.com?type=TRANSACTION&value=FW2214491490` In this example, if the request type is `TRANSACTION` and the request value is any `transactionId`, it indicates a change in status for the transaction. Clients can call the [Transactions](/api#tag/customer-wallet-transactions/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions) API to check the latest status of the transaction. If a request for information (RFI) is raised, a response is filed using the [Respond to Transaction RFI](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions/{authCode}/rfi/upload) API. ## Security This API only supports the HTTPS protocol. You need to add Classless Inter-Domain Routing (CIDR) block of Nium to your firewall IP allowlist to make sure only Nium is authorized to make the call. ## Request example ```Bash curl -X POST \ 'https://?type={nudgeType}&value={nudgeValue}' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: client1' \ -d '{ "type" : "TRANSACTION", "value" : "FW2214491490", "clientHashId" : "82c68bab-3c04-3451-8d7b-cb38ad713d97", "customerHashId" : "91bd4b3b-458a-4a83-831b-7ea834492b19", "walletHashId" : "7bf8f915-edf6-44ff-970c-88a00795088d", "tags": [ { "key": "Transaction Reference Number", "value": "TR1234" } ], "externalId":"Custom1245" }' ``` ## Request body | Field | Description | Type | | :--------------- | :------------------------------------------------------------------------------------------ | :----- | | `type` | This field accepts the nudge type `TRANSACTION`. | String | | `value` | This field accepts the nudge value. | String | | `clientHashId` | This field accepts the unique client identifier generated and shared before API handshakes. | UUID | | `customerHashId` | This field accepts the unique customer identifier generated upon customer creation. | UUID | | `walletHashId` | This field accepts the Unique wallet identifier generated during customer creation. | UUID | --- # Customer Compliance Status URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/callbacks/customer-compliance-status Nium calls this API to inform clients about a change in compliance status about a specific customer. ```URL POST https:///callback/compliance?customerHashId={customerHashId} ``` ## Security This API only supports the HTTPS protocol. You need to add Classless Inter-Domain Routing (CIDR) block of Nium to your firewall IP allowlist to make sure only Nium is authorized to make the call. ## Request example ```Bash curl -X POST \ 'https:///callback/compliance?customerHashId={customerHashId}' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: client1' \ ``` ## Query parameters | Field | Description | Needed? | | :--------------- | :---------------------------------------------------------------------------------- | :------- | | `customerHashId` | This field accepts the unique customer identifier generated upon customer creation. | Required | ## Response example ```json No response ``` --- # Redirect Customer URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/callbacks/redirect-customer You can redirect a customer to their application using the callback URL method. To do so, a client needs to invoke the Nium API operation in an asynchronous way. The format described below shows how you can redirect the customer after you successfully complete the Electronic Know Your Customer (eKYC) process. Refer to the customer onboarding page for details specific to the supported region. You need to redirect the customer to the application where they keep the value fetched during the eKYC. Then, you use the eKYC value to call Nium's [Customer Update](/api#tag/customer-account---individual/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/updateCustomer) API to update the rest of the fields required for the onboarding flow. After receiving the compliance callback nudge, when applicable, a client fetches the customer data by calling the [Customer Details V2](/api#tag/customer-management/GET/api/v2/client/{clientHashId}/customer/{customerHashId}) API using the `customerHashId` field to check the status. Alternatively, the client can opt for the manual KYC process. ```URL POST https:///callback/compliance?customerHashId={customerHashId} ``` ## Security This API only supports the Hypertext Transfer Protocol Secure (HTTPS) protocol. You need to add Nium's IPs to your allow list so Nium's Classless Inter-Domain Routing (CIDR) super netting method to assign IP addresses can make the calls. ## Request example ```Bash curl -X POST \ 'https:///callback/compliance?customerHashId={customerHashId}' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -H 'x-client-name: client1' \ ``` ## Query parameters | Field | Description | Needed? | | :--------------- | :---------------------------------------------------------------------------------- | :------- | | `customerHashId` | This field accepts the unique customer identifier generated upon customer creation. | Required | --- # Platform Webhooks URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events Our platform events provide real-time updates on key activities and events across your Nium integration and platform. You can subscribe to platform events to enhance visibility into operations, such as client onboarding, compliance updates, fund transfers, and virtual account management. These events help you monitor client configurations, customer updates, wallet activities, and other critical operations. Specifically, platform events allow you to: - Track client setup, updates, and compliance status changes. - Monitor wallet activities, including balance transfers, fund movements, and cashback credits. - Manage events related to virtual accounts and FX conversions. By automating event handling, platform events ensure seamless integration and proactive issue management. ## Supported Events The following platform events are available: - [**Client Setup**](/docs/developers/notifications-and-webhooks/platform-events/client-setup) - [**Client KYB Status**](/docs/developers/notifications-and-webhooks/platform-events/client-kyb-status) - [**Client Refund Approval**](/docs/developers/notifications-and-webhooks/platform-events/client-refund-approval) - [**Customer Status**](/docs/developers/notifications-and-webhooks/platform-events/customer-status) - [**Customer Registration**](/docs/developers/notifications-and-webhooks/platform-events/customer-registration) - [**Customer Compliance Status**](/docs/developers/notifications-and-webhooks/platform-events/customer-compliance-status) - [**Customer ODD Status**](/docs/developers/notifications-and-webhooks/platform-events/customer-odd-status) - [**Customer Update**](/docs/developers/notifications-and-webhooks/platform-events/customer-update) - [**Wallet Enhancement**](/docs/developers/notifications-and-webhooks/platform-events/wallet-enhancement) - [**Balance Transfer Within Wallet**](/docs/developers/notifications-and-webhooks/platform-events/balance-transfer-within-wallet) - [**Cashback Credit**](/docs/developers/notifications-and-webhooks/platform-events/cashback-credit) - [**P2P Transfer Between Wallets**](/docs/developers/notifications-and-webhooks/platform-events/p2p-transfer-between-wallets) - [**Fund Transfer Between Wallets**](/docs/developers/notifications-and-webhooks/platform-events/fund-transfer-between-wallets) - [**Fund Received From Wallet**](/docs/developers/notifications-and-webhooks/platform-events/fund-received-from-wallet) - [**Fund Transfer Declined Between Wallets**](/docs/developers/notifications-and-webhooks/platform-events/fund-transfer-declined-between-wallets) - [**Prefund Approval**](/docs/developers/notifications-and-webhooks/platform-events/prefund-approval) - [**Virtual Account Assigned**](/docs/developers/notifications-and-webhooks/platform-events/virtual-account-assigned) - [**Virtual Account Assignment Failed**](/docs/developers/notifications-and-webhooks/platform-events/virtual-account-assignment-failed) - [**FX Conversion Completed**](/docs/developers/notifications-and-webhooks/platform-events/fx-conversion-completed) - [**FX Conversion Cancelled**](/docs/developers/notifications-and-webhooks/platform-events/fx-conversion-cancelled) - [**FX Conversion Failed**](/docs/developers/notifications-and-webhooks/platform-events/fx-conversion-failed) --- # Client Setup URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/client-setup This event is triggered when a new child client is set up with a replica configuration from a program manager client. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "b1cb53e3-6a1b-4b58-a10d-5a79c5967cef", "newClientHashId": "308a4d01-8549-4cbb-b83f-05cd768d606f", "newClientName": "OnboardingNewClientTest", "template": "CARD_CLIENT_SETUP_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------- | --------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | This field contains the `clientHashId` of the program manager or parent client that's being cloned. | UUID | | `newClientHashId` | This field contains the `clientHashId` of the newly created child or cloned client. | UUID | | `newClientName` | This field contains the name of the newly created child or cloned client. | String | | `template` | The value for this field is `CARD_CLIENT_SETUP_WEBHOOK`. | String | --- # Customer Status URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/customer-status This event is triggered when the status and/or substatus of a customer is updated. Applicable for customers onboarded using Customer Onboarding v5. This event is triggered when the `status` and/or `substatus` of a customer is updated. Applicable for customers onboarded using [Customer Onboarding v5](/docs/onboarding/customer-onboarding). ```curl URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "customerHashId": "5993e016-21b1-4c8f-9282-e5491546c47a", "template": "CUSTOMER_STATUS_WEBHOOK", "customerType": "INDIVIDUAL", "walletHashIds": [ "70adc339-5b3f-4711-ad82-39ed6420bd62" ], "externalId": "c3a2c77a-f451-4e4d-a212-48283dec4eac", "isResubmissionAllowed": "true", "subStatus": "", "clientHashId": "b23b124c-9cc8-4550-b66f-ed8250ff8a5e", "status": "rejected", "tags": [ { "value": "value", "key": "key" } ] }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The `clientHashId` of the parent client. | UUID | | `customerHashId` | Th the unique customer identifier generated at the time of customer creation. | UUID | | `customerType` | The type of the customer. | String | | `externalId` | Client-created unique ID. | String | | `isResubmissionAllowed` | Details if the customer can be resubmitted for onboarding | String | | `status` | The status of the customer. Available values include:pendingclearfailed | String | | `subStatus` | The substatus of the application. Details the next steps to take to onboard the application. | String | | `customerType` | This field contains the type of the customer. It should be INDIVIDUAL for individual customer. | String | | `tags` | Custom tags & values applied by the client when the customer was initially onboarded. Maximum 15 key-value pairs can be sent in tags. | Array | | `template` | The value for this field is **CUSTOMER\_STATUS\_WEBHOOK**. | String | | `walletHashIds` | The unique identifier of the customer’s wallet linked to the transaction. | String | --- # Client KYB Status URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/client-kyb-status This event is triggered when the compliance status, as a result of the KYB process, is anything other than complete for a client. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example example webhook when application is submitted and some required document is not submitted ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "86ce8d7b-f3fa-46d5-8d1c-53212aade5b5", "customerHashId": "857dc08e-dffa-4e9a-ad96-79041c8a7025", "clientId": "NIM1622197836971", "caseId": "a9ec3c55-f06d-4f0b-9f67-e89968b861bf", "newClientName": "Onboarding", "complianceStatus": "IN_PROGRESS", "status": "Pending", "template": "CARD_CLIENT_KYB_STATUS_WEBHOOK" }' ``` example webhook when application is submitted and agent has requested for RFI ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "86ce8d7b-f3fa-46d5-8d1c-53212aade5b5", "customerHashId": "857dc08e-dffa-4e9a-ad96-79041c8a7025", "clientId": "NIM1622197836971", "caseId": "a9ec3c55-f06d-4f0b-9f67-e89968b861bf", "newClientName": "Onboarding", "complianceStatus": "RFI_REQUESTED", "status": "Pending", "template": "CARD_CLIENT_KYB_STATUS_WEBHOOK" }' ``` example webhook when application is Approved ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "86ce8d7b-f3fa-46d5-8d1c-53212aade5b5", "customerHashId": "857dc08e-dffa-4e9a-ad96-79041c8a7025", "clientId": "NIM1622197836971", "caseId": "a9ec3c55-f06d-4f0b-9f67-e89968b861bf", "newClientName": "Onboarding", "complianceStatus": "COMPLETED", "status": "Clear", "template": "CARD_CLIENT_KYB_STATUS_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | This is the `clientHashId` of the parent client. | UUID | | `customerHashId` | This field contains the unique customer identifier generated at the time of customer creation. | UUID | | `clientId` | This field contains the internal client ID for KYB. | UUID | | `caseId` | This field contains the compliance case ID of the customer. | String | | `newClientName` | This field contains the name of the new client which has been onboarded. | String | | `complianceStatus` | This field contains the compliance status of the new client undergoing KYB. The possible values are: \n \n• INITIATED \n• IN\_PROGRESS \n• ACTION\_REQUIRED \n• RFI\_REQUESTED \n• RFI\_RESPONDED \n• COMPLETED \n• REJECT \n• ERROR \n• EXPIRED \n• CLOSED | String | | `status` | This field contains the status of the customer. The possible values are: \n• Pending \n• Clear \n• Failed | String | | `template` | The value for this field is `CARD_CLIENT_KYB_STATUS_WEBHOOK`. | String | --- # Client Refund Approval URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/client-refund-approval This event is triggered when a refund is processed to a client prefund account. ```curl URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```Bash curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "transactionCurrency":"SGD", "transactionAmount":"10", "authCode":"114733", "transactionDate":"2022-03-07 13:04:26", "template":"CARD_REFUND_APPROVAL_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier generated and shared before the API handshake. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](/docs/getting-started/currency-and-country-codes). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `authCode` | An authorization code of the transaction. | String | | `transactionDate` | This field contains the transaction date and time in `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `template` | The value for this field is `CARD_REFUND_APPROVAL_WEBHOOK`. | String | --- # Customer Registration URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/customer-registration This event is triggered when a customer is registered. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"a230207a-c598-479e-b94b-a12bb1a7d287", "customerHashId":"85c21489-94aa-4e65-ab7e-1c6bcea84e27", "walletHashId":"fbfdfcda-b823-457b-8901-c1a0950c68aa", "template":"CARD_CUSTOMER_REGISTRATION_WEBHOOK" }' ``` ### Request Body | **Field** | **Description** | **Type** | | ---------------- | ---------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with the customer creation. | UUID | | `template` | The value for this field is `CARD_CUSTOMER_REGISTRATION_WEBHOOK`. | String | --- # Customer Compliance Status URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/customer-compliance-status This event is triggered when an individual customer's compliance status is changed. ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```curl curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "b1cb53e3-6a1b-4b58-a10d-5a79c5967cef", "customerHashId":"85c21489-94aa-4e65-ab7e-1c6bcea84e27", "complianceStatus":"COMPLETED", "status":"Clear", "customerType":"INDIVIDUAL", "template":"CUSTOMER_COMPLIANCE_STATUS" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------ | ------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | This is the `clientHashId` of the parent client. | UUID | | `customerHashId` | This field contains the unique customer identifier generated at the time of customer creation. | UUID | | `complianceStatus` | This field contains the compliance status of the customer. | String | | `status` | This field contains the status of the customer. The possible values are: \n• Pending \n• Clear \n• Failed | String | | `customerType` | This field contains the type of the customer. It should be INDIVIDUAL for individual customer. | String | | `template` | The value for this field is CUSTOMER\_COMPLIANCE\_STATUS | String | --- # Customer ODD Status URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/customer-odd-status This event is triggered when the compliance status, as a result of the KYB process, is anything other than complete for a client. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example example webhook when oddStatus is odd\_due ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "86ce8d7b-f3fa-46d5-8d1c-53212aade5b5", "customerHashId":"857dc08e-dffa-4e9a-ad96-79041c8a7025", "oddStatus":"odd_due", "template": "CUSTOMER_ODD_STATUS_WEBHOOK", "customerType":"corporate" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | This is the `clientHashId` of the client. | UUID | | `customerHashId` | This field contains the unique customer identifier generated at the time of customer creation. | UUID | | `oddStatus` | This field contains the status of the odd process. Possible values of oddStatus: odd\_due, odd\_initiated, odd\_completed | String | | `customerType` | This field contains the status of the customer. The possible values is: `corporate` | String | | `template` | The value for this field is `CUSTOMER_ODD_STATUS_WEBHOOK`. | String | --- # Customer Update URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/customer-update This event is triggered when customer data is updated. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "a230207a-c598-479e-b94b-a12bb1a7d287", "customerHashId": "85c21489-94aa-4e65-ab7e-1c6bcea84e27", "fields": { "countryCode":"SG", "mobile": "67543800", "email": "john@xyzmail.com", "previousCountryCode":"US", "previousMobile": "123456789", "previousEmail": "jack@xyzmail.com" }, "template": "CARD_CUSTOMER_UPDATE_WEBHOOK" }' ``` ### Request Body | **Field** | **Description** | **Type** | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `fields` | This is an object that holds all the key-value pairs which are updated. For details, see the [Request example](#request-example). | Object | | `template` | The value for this field is `CARD_CUSTOMER_UPDATE_WEBHOOK`. | String | --- # Wallet Encashment URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/wallet-enhancement This event is triggered when funds are withdrawn from a wallet. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "brandName":"ABC Technologies Ltd.", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "transactionCurrency":"SGD", "transactionAmount":"10", "walletBalance":"10", "authCode":"114733", "template":"CARD_WALLET_ENCASHMENT_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `brandName` | This is the brand name field for the client's company name. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `walletBalance` | The available balance in the wallet. | String | | `authCode` | The authorization code of the transaction. | String | | `template` | The value for this field is `CARD_WALLET_ENCASHMENT_WEBHOOK`. | String | --- # Balance Transfer Within Wallet URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/balance-transfer-within-wallet This event is triggered when a balance transfer is done between two currencies of the same customer using the Balance Transfer Within Wallet API. This event is triggered when a balance transfer is done between two currencies of the same customer using the [Balance Transfer Within Wallet](/api#tag/conversions-previous-version/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transfer) API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "0498f10f-1968-494f-9f7a-454ed23942a", "customerHashId": "5ccc078b-8cc8-4d49-b231-73030f01b501", "walletHashId": "e83cca77-8b63-4a25-b580-1d872380ef29", "transactionCurrency": "SGD", "transactionAmount": "10.00", "transactionDate": "2020-09-29 09:24:46", "authCurrency": "SGD", "authAmount": "10.00", "exchangeRate":"0.8883", "markupRate":"0.5", "authCode": "114733", "template": "CARD_BALANCE_TRF_BETWEEN_CURRENCIES_WITHIN_SAME_WALLET_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `authCurrency` | This field contains the three-letter [ISO-4217 authorization currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `authAmount` | The authorization amount for the transaction. | String | | `exchangeRate` | The exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `markupRate` | The transaction markup applicable on the currency conversion between the source and the destination. This is a percentage. | String | | `authCode` | This field contains the authorization code of a transaction. | String | | `template` | The value for this field is `CARD_BALANCE_TRF_BETWEEN_CURRENCIES_WITHIN_SAME_WALLET_WEBHOOK`. | String | --- # Cashback Credit URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/cashback-credit This event is triggered for receiving a cashback notification on a transaction. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"5d9e5e64-b7a5-4fda-91b5-20b0136cd54d", "customerHashId":"b1370108-4bba-47cf-b85a-73aa24d63db8", "walletHashId":"80fadadd-6e74-4fe1-bce8-488dc42c0400", "authCurrency":"SGD", "authAmount":"2.00", "authCode":"CB2165129043", "cashbackName":"Cashback by WEEKLY scheduled job", "cashbackPeriod":"2020-12-07_2020-12-13", "template":"CARD_CASHBACK_CREDIT_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `authCurrency` | This field contains the three-letter [ISO-4217 authorization currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `authAmount` | This field contains an authorized amount. | String | | `cashbackName` | This field contains the defined cashback name. | String | | `cashbackPeriod` | This field contains the cashback period which includes the start and the end date. | String | | `template` | The value for this field is `CARD_CASHBACK_CREDIT_WEBHOOK`. | String | --- # P2P Transfer Between Wallets URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/p2p-transfer-between-wallets This event is triggered when a P2P transfer is done between two customers under the same client using the P2P Transfer API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "0498f10f-1968-494f-9f7a-454ed23942a", "customerHashId": "5ccc078b-8cc8-4d49-b231-73030f01b501", "walletHashId": "e83cca77-8b63-4a25-b580-1d872380ef29", "transactionCurrency": "SGD", "transactionAmount": "10.00", "transactionDate": "2020-09-29 09:24:46", "authCurrency": "SGD", "authAmount": "10.00", "receiverCustomerHashId":"d422f4aa-835e-95f8-042a-044b958fc950", "receiverWalletHashId":"1d63ae3f-8108-94f6-c5ec-175ed70f7111", "authCode": "114733", "template": "CARD_P2P_TRANSFER_BETWEEN_WALLETS_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `authCurrency` | This field contains the three-letter [ISO-4217 authorization currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `authAmount` | This field contains an authorization amount for the transaction. | String | | `receiverCustomerHashId` | This is the unique `customerHashId` of the recipient. | UUID | | `receiverWalletHashId` | This is the unique `walletHashId` of the recipient. | UUID | | `authCode` | This field contains the authorization code of the transaction. | String | | `template` | The value for this field is `CARD_P2P_TRANSFER_BETWEEN_WALLETS_WEBHOOK`. | String | --- # Fund Transfer Between Wallets URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/fund-transfer-between-wallets This event is triggered when a fund transfer is done between two customers of different clients. The sender’s client receives this webhook. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | ------------ | ---------------- | | Content-Type | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "receiverClientHashId": , "receiverCustomerHashId": , "receiverWalletHashId": , "sourceCurrency": , "destinationCurrency": , "sourceAmount": , "destinationAmount":, "transactionDate": , "authCurrency": , "authAmount": , "senderClientHashId": , "senderCustomerHashId":, "senderWalletHashId": , "authCode": , "template: "FUND_TRANSFER_BETWEEN_WALLETS_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `receiverClientHashId` | This is the unique clientHashId of the recipient. | UUID | | `receiverCustomerHashId` | This is the unique customerHashId of the recipient. | UUID | | `receiverWalletHashId` | This is the unique walletHashId of the recipient. | UUID | | `sourceCurrency` | This field contains the three-letter [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) transaction currency code that's transferred. | String | | `destinationCurrency` | This field contains the three-letter ISO-4217 transaction currency code that's received. | String | | `sourceAmount` | This field contains the transaction amount at the source which is transferred. | String | | `destinationAmount` | This field contains the transaction amount at the destination which has been transferred. | String | | `transactionDate` | This field contains the transaction date and time in the yyyy-MM-dd HH:mm Coordinated Universal Time format. | String | | `authCurrency` | This field contains the three-letter ISO-4217 transaction currency code. | String | | `authAmount` | This field contains an authorization amount for the transaction. | String | | `senderClientHashId` | This is the unique sender client identifier generated and shared before the API handshake. | UUID | | `senderCustomerHashId` | This is the unique sender customer identifier generated on customer creation. | UUID | | `senderWalletHashId` | This is the unique sender wallet identifier generated simultaneously with the customer's creation. | UUID | | `authCode` | This field contains the authorization code of the transaction. | String | | `template` | The value for this field is `FUND_TRANSFER_BETWEEN_WALLETS_WEBHOOK`. | String | --- # Funds Received From Wallet URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/fund-received-from-wallet This event is sent when a funds are received from the same or different client. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "receiverClientHashId": , "receiverCustomerHashId": , "receiverWalletHashId": , "sourceCurrency": , "destinationCurrency": , "sourceAmount": , "destinationAmount":, "transactionDate": , "authCurrency": , "authAmount": , "senderClientHashId": , "senderCustomerHashId": , "senderWalletHashId": , "authCode": , "template": "FUND_RECEIVED_FROM_WALLET_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `receiverClientHashId` | This is the unique `clientHashId` of the recipient. | UUID | | `receiverCustomerHashId` | This is the unique `customerHashId` of the recipient. | UUID | | `receiverWalletHashId` | This is the unique `walletHashId` of the recipient. | UUID | | `sourceCurrency` | This field contains the three-letter [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) transaction currency code that's transferred. | String | | `destinationCurrency` | This field contains the three-letter [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) transaction currency code that's received. | String | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `sourceAmount` | This field contains the transaction amount at the source which is transferred. | String | | `senderClientHashId` | This is the unique sender client identifier generated and shared before the API handshake. | UUID | | `senderCustomerHashId` | This is the unique sender customer identifier generated on customer creation. | UUID | | `senderWalletHashId` | This is the unique sender wallet identifier generated simultaneously with the customer's creation. | UUID | | `authCode` | This field contains the authorization code of the transaction. | String | | `template` | The value for this field is `FUND_RECEIVED_FROM_WALLET_WEBHOOK`. | String | --- # Fund Transfer Declined Between Wallets URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/fund-transfer-declined-between-wallets This event is triggered when a fund transfer is declined between two customers of different clients. The sender’s client receives this webhook. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "senderClientHashId": , "senderCustomerHashId":, "senderWalletHashId": , "sourceCurrency": , "destinationCurrency": , "sourceAmount": , "destinationAmount":, "transactionDate": , "authCurrency": , "authAmount": , "receiverClientHashId": , "receiverCustomerHashId":, "receiverWalletHashId": , "authCode": , "template": "FUND_TRANSFER_DECLINED_BETWEEN_WALLETS_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `senderClientHashId` | This is the unique sender client identifier generated and shared before the API handshake. | UUID | | `senderCustomerHashId` | This is the unique sender customer identifier generated on customer creation. | UUID | | `senderWalletHashId` | This is the unique sender wallet identifier generated simultaneously with the customer's creation. | UUID | | `sourceCurrency` | This field contains the three-letter [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) transaction currency code that's transferred. | String | | `destinationCurrency` | This field contains the three-letter ISO-4217 transaction currency code that's received. | String | | `sourceAmount` | This field contains the transaction amount at the source which is transferred. | String | | `destinationAmount` | This field contains the transaction amount at the destination which has been transferred. | String | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `authCurrency` | This field contains the three-letter ISO-4217 authorization currency code. | String | | `authAmount` | This field contains an authorization amount for the transaction. | String | | `receiverClientHashId` | This is the unique clientHashId of the recipient. | UUID | | `receiverCustomerHashId` | This is the unique customerHashId of the recipient. | UUID | | `receiverWalletHashId` | This is the unique walletHashId of the recipient. | UUID | | `authCode` | This field contains the authorization code of the transaction. | String | | `template` | The value for this field is `FUND_TRANSFER_DECLINED_BETWEEN_WALLETS_WEBHOOK`. | String | --- # Prefund Approval URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/prefund-approval This event is triggered for a client prefund request notification. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"fb7d467d-859f-4dc7-9880-a51505cb47cf", "prefundCurrency":"SGD", "transactionAmount":"1000.00", "transactionId":"CP7586549918", "transactionDate":"2020-12-16 09:36:05", "bankReferenceNumber":"DUMMYBANKREF", "iccSource":"DBSSG", "remitterAccountNumber":"HLFX11029100808072", "remitterBankName":"Bank of Singapore", "remitterName":"Kamal K", "uniquePaymentId":"8850932506060", "uniquePayerId":"DBS cards", "iccPayMode":"FAST", "iccTransactionId":"CP7586549918", "iccReceivedAt":"2019-04-15T12:26:01.31Z", "template":"CARD_PRE_FUND_APPROVAL_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `prefundCurrency` | This field contains the three-letter [ISO-4217 prefund currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionId` | This field contains the transaction reference number/ID. | String | | `transactionDate` | This field contains the date of the transaction. | String | | `bankReferenceNumber` | This field contains the bank reference number from the client. | String | | `iccSource` | This field contains the source of the fund. | String | | `remitterAccountNumber` | This field contains the remitter account number. | String | | `remitterBankName` | This field contains the remitter bank name. | String | | `remitterName` | This field contains the remitter name. | String | | `uniquePaymentID` | This field contains the unique payment ID. | String | | `uniquePayerID` | This field contains the unique payer ID. | String | | `iccPayMode` | This field contains the ICC payment mode. | String | | `iccTransactionId` | This field contains the ICC transaction ID. | String | | `iccReceivedAt` | This field contains the date and time when the ICC transaction is received. | String | | `template` | The value for this field is `CARD_PRE_FUND_APPROVAL_WEBHOOK`. | String | --- # Virtual Account Assigned URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/virtual-account-assigned This event is triggered when a virtual account has been assigned to the customer in an asynchronous flow. Unlike in the synchronous assignment of virtual accounts, which are returned in the response of the respective APIs, clients *do not* receive certain virtual accounts immediately in the response of the APIs. This happens in cases of an asynchronous assignment of virtual accounts. In the latter case, the webhook introduced notifies the clients once the virtual accounts have been assigned. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"845f4c18-546a-4e14-b8d4-fc26179e56da", "customerHashId":"993bac0f-31e9-471b-93e9-50d90994a13c", "walletHashId":"cc90e8d0-c993-4ea7-9169-ad6662a4d60d", "currencyCode":"GBP", "uniquePaymentId":"8874746216", "uniquePayerId":"8675116", "fullBankName":"JPMorgan Chase Bank N.A., London", "routingCodeType1":"BIC", "routingCodeValue1":"CHASGB2L", "routingCodeType2":"", "routingCodeValue2":"", "accountName":"NIUM FINTECH LIMITED", "accountType":"GLOBAL", "bankAddress":"25 Bank Street Canary Wharf, London, E14 5JP, United Kingdom", "template":"VIRTUAL_ACCOUNT_ASSIGNED_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The Unique client identifier generated during onboarding. | UUID | | `customerHashId` | The Unique customer identifier generated during customer creation. | UUID | | `walletHashId` | The Unique wallet identifier generated during customer creation. | UUID | | `currencyCode` | The three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `uniquePaymentId` | The unique payment ID. | String | | `uniquePayerId` | The unique payer ID. | String | | `fullBankName` | The complete name of the bank for the virtual account. | String | | `routingCodeType1` | The first routing code type. See the [Examples of Routing Codes](/api#tag/reference-data/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/country/{countryCode}/routingCodeType/{routingCodeType}/routingCodeValue/{routingCodeValue}/routingCode). | String | | `routingCodeValue1` | The routing code value for `routingCodeType1`. | String | | `routingCodeType2` | The second routing code type. See the [Examples of Routing Codes](/api#tag/reference-data/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/country/{countryCode}/routingCodeType/{routingCodeType}/routingCodeValue/{routingCodeValue}/routingCode). | String | | `routingCodeValue2` | The routing code value for `routingCodeType2`. | String | | `accountName` | The account name to be mentioned while doing a fund transfer. | String | | `accountType` | The account type. The possible values are: \n• `LOCAL` \n• `GLOBAL` \n• `LOCAL+GLOBAL`. | String | | `bankAddress` | The bank address. | String | | `template` | The value for this field is `VIRTUAL_ACCOUNT_ASSIGNED_WEBHOOK`. | String | --- # Virtual Account Assignment Failed URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/virtual-account-assignment-failed This event is triggered when a virtual account assignment fails. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "845f4c18-546a-4e14-b8d4-fc26179e56da", "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId": "e83cca77-8b63-4a25-b580-1d872380ef29", "currencyCode": "INR", "bankName": "DBS HONGKONG", "customMessage": "Account creation failed", "template":"VIRTUAL_ACCOUNT_ASSIGNMENT_FAILED_WEBHOOK" }' ``` ## Request body | **Field** | **Description** | **Type** | | ---------------- | ---------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `currencyCode` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `bankName` | This field contains the name of the bank for the virtual account. | String | | `customMessage` | This field contains a virtual account creation error message. | String | | `template` | The value for this field is `VIRTUAL_ACCOUNT_ASSIGNMENT_FAILED_WEBHOOK`. | String | --- # FX Conversion Completed URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/fx-conversion-completed Triggered when an FX conversion is completed between two currencies for the same customer. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "customerHashId":"e9f74ac0-8fc5-4879-8ace-6ca2084ba250", "template":"FX_CONVERSION_COMPLETED_WEBHOOK", "systemReferenceNumber":"WFT1180326200", "walletHashId":"ebc26772-2d3e-4ab0-916a-3a7706a0c358", "conversionId":"conversion_46nn6y8gDX2Os6DHjlHdke", "clientHashId":"8bf73eb1-99e7-4a76-8ef2-cdeac938593a", "status":"completed" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | -------- | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `template` | Set to `FX_CONVERSION_COMPLETED_WEBHOOK` for this event. | String | | `systemReferenceNumber` | The unique identifier that's generated by Nium to internally identify the `conversion`. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `conversionId` | The unique card identifier that's generated when creating a new `conversion`. | UUID | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | String | | `status` | The status of the `conversion `. This field is set to **completed** when the conversion of currencies has finished. | String | --- # FX Conversion Cancelled URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/fx-conversion-cancelled Triggered when an FX conversion between two currencies is cancelled. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "customerHashId":"e9f74ac0-8fc5-4879-8ace-6ca2084ba250", "template":"FX_CONVERSION_CANCELLED_WEBHOOK", "cancellationFeeCurrencyCode":"USD", "cancellationReason":"insufficient_fund", "systemReferenceNumber":"7526349341F", "cancellationComment":"Insufficient Funds", "cancellationFee":5.82", "walletHashId":"ebc26772-2d3e-4ab0-916a-3a7706a0c358", "conversionId":"conversion_1xVFhcSSdFLAyoKb9bKofR", "clientHashId":"8bf73eb1-99e7-4a76-8ef2-cdeac938593a", "status":"cancelled" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `template` | Set to `FX_CONVERSION_CANCELLED_WEBHOOK` for this event. | String | | `cancellationFeeCurrencyCode` | The currency code for the fee associated with the cancellation. | String | | `cancellationReason` | The reason for the cancellation of the FX conversion. | String | | `systemReferenceNumber` | The unique identifier that's generated by Nium to internally identify the `conversion`. | UUID | | `cancellationComment` | Additional comments regarding the cancellation. | String | | `cancellationFee` | The fee amount charged for the cancellation of the FX conversion. | String | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `conversionId` | The unique card identifier that's generated when creating a new `conversion`. | UUID | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | String | | `status` | The status of the `conversion `. This field is set to **cancelled** when the conversion of currencies has failed. | String | --- # FX Conversion Failed URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/platform-events/fx-conversion-failed Triggered when an FX conversion between two currencies has failed. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "customerHashId":"e9f74ac0-8fc5-4879-8ace-6ca2084ba250", "template":"FX_CONVERSION_FAILED_WEBHOOK", "cancellationFeeCurrencyCode":"USD", "systemReferenceNumber":"7526349341F", "errorMessage":"Partial failure", "walletHashId":"ebc26772-2d3e-4ab0-916a-3a7706a0c358", "conversionId":"conversion_1xVFhcSSdFLAyoKb9bKofR", "clientHashId":"8bf73eb1-99e7-4a76-8ef2-cdeac938593a", "status":"failed" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------------------- | -------------------------------------------------------------------------------------------------------------- | -------- | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `template` | Set to `FX_CONVERSION_FAILED_WEBHOOK` for this event. | String | | `cancellationFeeCurrencyCode` | The currency code for the fee associated with the cancellation. | String | | `systemReferenceNumber` | The unique identifier that's generated by Nium to internally identify the `conversion`. | UUID | | `errorMessage` | Details the error that occurred during the FX conversion process. | String | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `conversionId` | The unique card identifier that's generated when creating a new `conversion`. | UUID | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | String | | `status` | The status of the `conversion `. This field is set to **failed** when the conversion of currencies has failed. | String | --- # Payout Webhooks URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events Our payout events keep you informed of every stage in the payout lifecycle. These notifications ensure visibility into payout creation, status changes, and outcomes, allowing you to automate and streamline payout tracking. Specifically, payout events allow you to: - Monitor payout transaction status, from initiation to settlement. - Automate responses to expired, returned, or completed payouts. - Verify beneficiary details to ensure smooth processing. Payout events are especially useful for remittance transactions, beneficiary verifications, managing fund disbursements and helps reduce manual intervention. ## Supported Events The following payout events are available: - [**Remit Transaction Initiated**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated) - [**Remit Transaction Expired**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-expired) - [**Remit Transaction Returned**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-returned) - [**Remit Transaction Paid**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid) - [**Remit Transaction Sent to Bank**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-sent-to-bank) - [**Remit Transaction Cancelled**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-cancelled) - [**Beneficiary Verification Status**](/docs/developers/notifications-and-webhooks/payout-events/beneficiary-verification-status) - [**Remit Transaction Awaiting Funds**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-awaiting-funds) - [**Remit Transaction Rejected**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-rejected) - [**Remit Transaction Sub-status Update**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-sub-status-update) - [**Remit Transaction NOC**](/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-noc) --- # Remit Transaction Initiated URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-initiated This template is triggered when a transfer is created between two customers under the same client using the Transfers API. This template is triggered when a transfer is created between two customers under the same client using the [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "transactionCurrency":"INR", "transactionAmount":"5418.1700", "systemReferenceNumber":"RT1343085439", "exchangeRate":"54.454000000", "beneficiaryName":"Diana Prince", "beneficiaryAccountNumber":"xxxxxx3443", "beneficiaryBankName":"DBS Bank", "billingCurrency":"SGD", "billingAmount":"100.0000", "template":"REMIT_TRANSACTION_INITIATED_WEBHOOK", "estimatedDeliveryTime": "2023‐08‐24T06:39:51Z", "tags": [ { "key": "Transaction Reference Number", "value": "TR1234" }], "externalId":"Custom1245" }' ``` ### Request body | **Field** | **Description** | **Type** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This is the destination amount in case of a remittance. | String | | `systemReferenceNumber` | This is a unique system reference number that's generated by the card issuance platform for the transaction. | String | | `exchangeRate` | The exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `beneficiaryName` | This field contains the name of the beneficiary. | String | | `beneficiaryAccountNumber` | This field contains the bank account number of the beneficiary. | String | | `beneficiaryBankName` | This field contains the bank name of the beneficiary. | String | | `billingCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `billingAmount` | This field contains the source amount in case of remittance. | String | | `template` | The value for this field is `REMIT_TRANSACTION_INITIATED_WEBHOOK`. | String | | `estimatedDeliveryTime` | This field contains the estimated delivery time in the `2023‐08‐24T06:39:51Z` ISO 8601 format. | String | | `externalId` | A unique identifier provided by you to track requests or transactions. Refer to `externalId` field of [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. | String | --- # Remit Transaction Expired URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-expired This event is triggered when a remittance transaction is expired. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "transactionCurrency":"INR", "transactionAmount":"5418.1700", "systemReferenceNumber":"RT1343085439", "exchangeRate":"54.454000000", "beneficiaryName":"Diana Prince", "beneficiaryAccountNumber":"xxxxxx3443", "beneficiaryBankName":"DBS Bank", "billingCurrency":"SGD", "billingAmount":"100.0000", "payoutMethod":"CARD", "template":"REMIT_TRANSACTION_EXPIRED_WEBHOOK", "tags": [ { "key": "Transaction Reference Number", "value": "TR1234" }], "externalId":"Custom1245" }' ``` ### Request body | **Field** | **Description** | **Type** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This is the destination amount in case of a remittance. | String | | `systemReferenceNumber` | This is a unique system reference number generated by the card issuance platform for the transaction. | String | | `exchangeRate` | The exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `beneficiaryName` | This field contains the name of the beneficiary. | String | | `beneficiaryAccountNumber` | This field contains the bank account number of the beneficiary. | String | | `beneficiaryBankName` | This field contains the bank name of the beneficiary. | String | | `billingCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `billingAmount` | This field contains the source amount in case of remittance. | String | | `payoutMethod` | This field contains the payout method. The possible values are: LOCALSWIFTWALLETCARDPROXY | String | | `template` | The value for this field is `REMIT_TRANSACTION_EXPIRED_WEBHOOK`. | String | | `externalId` | A unique identifier provided by you to track requests or transactions. Refer to `externalId` field of [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. | String | --- # Remit Transaction Returned URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-returned This event is triggered when a remittance transaction is returned. ```json URL https:///webhook ``` ## Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ## Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "template": "REMIT_TRANSACTION_RETURNED_WEBHOOK", "transactionCurrency": "EUR", "billingAmount": "2255.00", "beneficiaryAccountNumber": "xxxxxxxxxxxxxxxxxx4200", "errorDescription": "", "remitter": { "address": "EXAMPLE STREET 42", "countryCode": "FR", "dob": "1985-09-15", "accountType": "CORPORATE", "name": "ACME SOLUTIONS SARL", "contactNumber": "33123456789", "identificationNumber": "RCS 123 456 789 (Paris)", "identificationType": "BUSINESS REGISTRATION NUMBER" }, "systemReferenceNumber": "ZL1GX90938293", "errorCode": "AC03", "walletHashId": "f46lb211-6e23-99ba-6356-8gb9t6s76458", "tags": [], "customerHashId": "0f5a988e-c99a-4ce5-4ab7-b769e182de6f", "errorReasonCode": "Wrong IBAN in SCT", "exchangeRate": "1.000000000", "billingCurrency": "EUR", "beneficiaryName": "John Smith", "beneficiaryBankName": "Sprout Bank", "transactionAmount": "2255.00", "clientHashId": "ecc9841c-c0df-c6e4-86f4-b320180d9859", "externalId" : "Custom1245" }' ``` ## Event body | **Field** | **Description** | **Type** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `beneficiaryAccountNumber` | The bank account number of the beneficiary. | String | | `beneficiaryBankName` | The bank name of the beneficiary. | String | | `beneficiaryName` | The name of the beneficiary. | String | | `billingAmount` | The source amount in case of a remittance. | String | | `billingCurrency` | The three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `errorCode` | The ISO-standard error code. | String | | `errorDescription` | A description of the corresponding ISO error code. | String | | `errorReasonCode` | The reason the ISO error was triggered, explaining why the transaction was returned. | String | | `exchangeRate` | The exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `systemReferenceNumber` | This is a unique system reference number generated by the card issuance platform for the transaction. | String | | `remitter` | The details of the *remitter* for on-behalf payouts; a *remitter* is the individual who initiated the transaction. | Object | | `template` | The value for this field is `REMIT_TRANSACTION_RETURNED_WEBHOOK`. | String | | `tags` | Custom tags & values applied by the client when the transaction was initiated. Maximum 15 key-value pairs can be sent in tags. | Array | | `transactionAmount` | The destination amount in case of a remittance. | String | | `transactionCurrency` | The three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `externalId` | A unique identifier provided by you to track requests or transactions. Refer to `externalId` field of [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. | String | ### Remitter object | **Field** | **Description** | **Type** | | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | -------- | | `accountType` | The type of account, such as `CORPORATE`. | String | | `address` | The entity’s street address. | String | | `contactNumber` | The entity’s or individual’s phone number. | String | | `countryCode` | The two-letter [ISO 3166-1 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html). | String | | `dob` | The individual’s date of birth or the company’s founding date (`YYYY-MM-DD`). | String | | `identificationNumber` | The unique number from the customer’s identification document, such as a business registration or driver's license. | String | | `identificationType` | The type of identification, such as a business registration number or driver's license. | String | | `name` | The legal name of the entity or individual. | String | --- # Remit Transaction Paid URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-paid This event is triggered when a remittance transaction is paid. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "transactionCurrency":"INR", "transactionAmount":"5418.1700", "systemReferenceNumber":"RT1343085439", "exchangeRate":"54.454000000", "beneficiaryName":"Diana Prince", "beneficiaryAccountNumber":"xxxxxx3443", "beneficiaryBankName":"DBS Bank", "billingCurrency":"SGD", "billingAmount":"100.0000", "template":"REMIT_TRANSACTION_PAID_WEBHOOK" "tags": [ { "key": "Transaction Reference Number", "value": "TR1234" }], "externalId":"Custom1245" }' ``` ### Request body | **Field** | **Description** | **Type** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the destination amount in case of a remittance. | String | | `systemReferenceNumber` | This field contains the unique system reference number generated by the card issuance platform for the transaction. | String | | `exchangeRate` | This field contains the exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `beneficiaryName` | This field contains the name of the beneficiary. | String | | `beneficiaryAccountNumber` | This field contains the bank account number of the beneficiary. | String | | `beneficiaryBankName` | This field contains the bank name of the beneficiary. | String | | `billingCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `billingAmount` | This field contains the source amount in case of a remittance. | String | | `template` | The value for this field is `REMIT_TRANSACTION_PAID_WEBHOOK`. | String | | `externalId` | A unique identifier provided by you to track requests or transactions. Refer to `externalId` field of [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. | String | --- # Remit Transaction Sent to Bank URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-sent-to-bank This event is triggered when a payout is sent to a partner bank. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -d '{ "clientHashId": "0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId": "e83cca77-8b63-4a25-b580-1d872380ef29", "transactionCurrency": "INR", "transactionAmount": "5418.1700", "systemReferenceNumber": "RT1343085439", "exchangeRate": "54.454000000", "beneficiaryName": "Diana Prince", "beneficiaryAccountNumber": "xxxxxx3443", "beneficiaryBankName": "DBS Bank", "billingCurrency": "SGD", "billingAmount": "100.0000", "beneficiaryEmailId": "dianaprice@xyemail.com", "beneficiaryContact": "+65-85067680", "partnerReferenceNumber": "UATPY102717100", "paymentReferenceNumber": null, "payoutMethod": "LOCAL", "template": "REMIT_TRANSACTION_SENT_TO_BANK_WEBHOOK", "estimatedDeliveryTime": "2023‐08‐24T06:39:51Z", "gpi": { "reasonCode": "G000", "statusDescription": "Delivered to next bank", "forwardBankName": "DONGUANN RURAL", "forwardBankCode": "DGCCCN22XXX", "timestamp": "2023-08-07 06:48:02", "remarks" : "The payment has been forwarded to next participant bank in the swift network. It can be either credited to beneficiary directly or passed to next bank." }, "tags": [ { "key": "Transaction Reference Number", "value": "TR1234" }], "externalId":"Custom1245" }' ``` ### Request body | **Field** | **Description** | **Type** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the destination amount in case of a remittance. | String | | `systemReferenceNumber` | This field contains the unique system reference number generated by the card issuance platform for the transaction. | String | | `exchangeRate` | This field contains the exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `beneficiaryName` | This field contains the name of the beneficiary. | String | | `beneficiaryAccountNumber` | This field contains the bank account number of the beneficiary. | String | | `beneficiaryBankName` | This field contains the bank name of the beneficiary. | String | | `billingCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance | String | | `billingAmount` | This field contains the source amount in case of remittance. | String | | `beneficiaryEmailId` | This field contains the email Id of the beneficiary. | String | | `beneficiaryContact` | This field contains the contact number of the beneficiary. | String | | `partnerReferenceNumber` | This field contains the unique transaction identifier. | String | | `paymentReferenceNumber` | This field contains the unique transaction identifier assigned by MoneyGram. This field is applicable only for a cash payout. | String | | `payoutMethod` | This field contains the payout method. | String | | `template` | The value for this field is `REMIT_TRANSACTION_SENT_TO_BANK_WEBHOOK`. | String | | `estimatedDeliveryTime` | This field contains the estimated delivery time in the `2023‐08‐24T06:39:51Z` ISO 8601 format. | String | | `gpi.reasonCode` | GPI code shared by the SWIFT partner bank | String | | `gpi.statusDescription` | Description of the GPI reason code | String | | `gpi.forwardBankName` | Name of the next participant bank to which the payment has been forwarded | String | | `gpi.forwardBankCode` | Bank identification code (BIC) of the next participant bank to which the payment has been forwarded. | String | | `gpi.timestamp` | Date and time of the last status change | String | | `gpi.remarks` | Detailed description of the `reasonCode`. This interpretation is provided by Nium. | String | | `externalId` | A unique identifier provided by you to track requests or transactions. Refer to `externalId` field of [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. | String | --- # Remit Transaction Cancelled URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-cancelled This template is triggered when a remittance transaction is cancelled. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "transactionCurrency":"INR", "transactionAmount":"5418.1700", "systemReferenceNumber":"RT1343085439", "exchangeRate":"54.454000000", "beneficiaryName":"Diana Prince", "beneficiaryAccountNumber":"xxxxxx3443", "beneficiaryBankName":"DBS Bank", "billingCurrency":"SGD", "billingAmount":"100.0000", "template":"REMIT_TRANSACTION_CANCELLED_WEBHOOK", "errorCode": "AC03", "errorReasonCode": "Wrong IBAN in SCT", "errorDescription": null, "externalId":"Custom1245" }' ``` ### Request body | **Field** | **Description** | **Type** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This is the destination amount in case of a remittance. | String | | `systemReferenceNumber` | This is a unique system reference number generated by the card issuance platform for the transaction. | String | | `exchangeRate` | The exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `beneficiaryName` | This field contains the name of the beneficiary. | String | | `beneficiaryAccountNumber` | This field contains the bank account number of the beneficiary. | String | | `beneficiaryBankName` | This field contains the bank name of the beneficiary. | String | | `billingCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `billingAmount` | This field contains the source amount in case of a remittance. | String | | `template` | The value for this field is `REMIT_TRANSACTION_CANCELLED_WEBHOOK`. | String | | `errorCode` | The ISO return code associated with the cancelled transaction. | String | | `errorReasonCode` | The reason returned by the bank or system explaining why the transaction was cancelled. | String | | `errorDescription` | Additional details describing the cancellation reason. This field may be `null` if no description is available. | String | | `externalId` | A unique identifier provided by you to track requests or transactions. Refer to `externalId` field of [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. | String | --- # Beneficiary Verification Status URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/beneficiary-verification-status This event is triggered when Nium has successfully verified the bank account details of the beneficiary as verified or not_verified. This event is triggered when Nium has successfully verified the bank account details of the beneficiary as `verified` or `not_verified`. Transactions to this beneficiary can still be returned due to several reasons, such as compliance reject, bank reject, account closed, or other reasons. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ``` curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "accountValidationId": "656863213342c9bccac25aef", "status": "verified", "template": "BENEFICIARY_VERIFICATION_STATUS" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `accountValidationId` | The unique client identifier that's generated and shared after calling [Nium Verify - Account verification](/api#tag/beneficiary/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/accountVerification) API | String | | `beneficiaryAccountName` | This field shows the payee name associated with the bank account. This is an optional field. | String | | `status` | This field indicates the status of the of account validation. The value for this field is `verified` or `not_verified`. | Boolean | | `template` | The value for this field is BENEFICIARY\_VERIFICATION\_STATUS. | String | --- # Remit Transaction Awaiting Funds URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-awaiting-funds This webhook is triggered when a payout request is made, but the wallet associated with the specified walletHashId does not have sufficient balance. The webhook is sent as part of the Transfers API flow. This webhook is triggered when a payout request is made, but the wallet associated with the specified `walletHashId` does not have sufficient balance. The webhook is sent as part of the [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API flow. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "template": "REMIT_TRANSACTION_AWAITING_FUNDS_WEBHOOK", "transactionCurrency": "USD", "billingAmount": "100000.00", "beneficiaryAccountNumber": "xxxxx3852", "systemReferenceNumber": "RT0295689319", "externalId": "", "walletHashId": "d396c4d4-dd23-4cc4-a5c0-d0a1d9f151d2", "tags": [], "customerHashId": "1027d7c5-2577-4e1e-b462-c15728fe16e8", "exchangeRate": "1.000000000", "billingCurrency": "USD", "beneficiaryName": "Donna Hickle", "beneficiaryBankName": "Bank of America, National Association", "transactionAmount": "100000.00", "clientHashId": "86528edd-55a3-4a2c-9939-144ed9be43ef" }' ``` ### Request body | **Field** | **Description** | **Type** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's provided during onboarding | UUID | | `customerHashId` | The unique customer identifier that's generated during customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This is the destination amount that the beneficiary receives. | String | | `systemReferenceNumber` | This is a unique system reference number that's generated by the system for the transaction. | String | | `exchangeRate` | The exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `beneficiaryName` | This field contains the name of the beneficiary. | String | | `beneficiaryAccountNumber` | This field contains the bank account number of the beneficiary. | String | | `beneficiaryBankName` | This field contains the bank name of the beneficiary. | String | | `billingCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `billingAmount` | This field contains the source amount in case of remittance. | String | | `template` | The value for this field is `REMIT_TRANSACTION_AWAITING_FUNDS_WEBHOOK`. | String | | `externalId` | A unique identifier provided by you to track requests or transactions. Refer to `externalId` field of [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. | String | --- # Remit Transaction Rejected URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-rejected This webhook is triggered when a payout request made via the Transfers API fails. Rejection may occur due to reasons such as incorrect configuration, insufficient wallet balance, or exceeding predefined transaction limits. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "template": "REMIT_TRANSACTION_REJECTED_WEBHOOK", "reason": "INSUFFICIENT_FUNDS", "transactionCurrency": "AUD", "reasonDescription": "Insufficient funds in wallet", "billingAmount": "100000.00", "beneficiaryAccountNumber": "xxxxx3852", "systemReferenceNumber": "RT9834178569", "externalId": "", "walletHashId": "d396c4d4-dd23-4cc4-a5c0-d0a1d9f151d2", "tags": [], "customerHashId": "1027d7c5-2577-4e1e-b462-c15728fe16e8", "exchangeRate": "1.567095900", "billingCurrency": "USD", "beneficiaryName": "Alvin Roob III", "beneficiaryBankName": "BANKWEST (A DIVISION OF COMMONWEALTH BANK OF AUSTRALIA)", "transactionAmount": "156709.59", "clientHashId": "86528edd-55a3-4a2c-9939-144ed9be43ef", "errorCode": "AC03", "errorReasonCode": "Wrong IBAN in SCT", "errorDescription": null }' ``` ### Request body | **Field** | **Description** | **Type** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's provided during onboarding | UUID | | `customerHashId` | The unique customer identifier that's generated during customer creation. | UUID | | `reason` | Code indicating the reason for transaction rejection. Possible value: INSUFFICIENT\_FUNDS. | String | | `reasonDescription` | Text description elaborating the reason for rejection. | String | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This is the destination amount that the beneficiary receives. | String | | `systemReferenceNumber` | This is a unique system reference number that's generated by the system for the transaction. | String | | `exchangeRate` | The exchange rate from the source currency to the destination currency, for example, 1 USD is equivalent to 1.392 SGD. | String | | `beneficiaryName` | This field contains the name of the beneficiary. | String | | `beneficiaryAccountNumber` | This field contains the bank account number of the beneficiary. | String | | `beneficiaryBankName` | This field contains the bank name of the beneficiary. | String | | `billingCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `billingAmount` | This field contains the source amount in case of remittance. | String | | `template` | The value for this field is `REMIT_TRANSACTION_REJECTED_WEBHOOK`. | String | | `errorCode` | The ISO return code associated with the cancelled transaction. | String | | `errorReasonCode` | The reason returned by the bank or system explaining why the transaction was cancelled. | String | | `errorDescription` | Additional details describing the cancellation reason. This field may be `null` if no description is available. | String | | `externalId` | A unique identifier provided by you to track requests or transactions. Refer to `externalId` field of [Transfers](/api#tag/payout/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance) API. | String | --- # Remit Transaction Sub-status Update URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-sub-status-update Webhook that notifies you when a remittance transaction in paid status moves to a more specific sub-status such as Sent_To_Beneficiary, Sent_To_Beneficiary_Bank, Processed_By_Clearing, or Deemed_PAID. This webhook fires whenever the sub-status of a remittance transaction in **paid** status changes. Use it to keep your systems and customer communications in sync across corridors that offer different levels of payment visibility. ```json URL https:///webhook ``` ## When this event occurs We send this event as soon as there is an update to the remittance `subStatus`. Typical transitions are: - **Sent\_To\_Beneficiary**: Funds reached the beneficiary (final leg). A return is rare and usually due to the beneficiary refusing funds (for example, ISO code **MD06**). - **Sent\_To\_Beneficiary\_Bank**: Funds reached the beneficiary’s bank. Returns may occur because of incorrect or closed accounts, or name/number mismatches (common ISO codes include **MD07**, **MM20**, **AG03**, **AC01**, **AC03**). - **Processed\_By\_Clearing**: Funds passed the clearing system; final credit is pending at the beneficiary bank. - **Deemed\_PAID**: No return was received within the corridor’s observation window, so the transaction is treated as paid. Any later return will trigger your standard return-handling flow. - **TIMED\_OUT**: No response was received from the beneficiary bank within the expected time. A final response is still awaiting. These sub-statuses improve transparency in corridors where a final, bank-confirmed “PAID” signal is not always available. ## Use cases - **Enterprise payroll**: Track the status of payouts at each stage of the transaction, including when it's credited (**Sent\_To\_Beneficiary**), at the beneficiary bank (**Sent\_To\_Beneficiary\_Bank**), in clearing (**Processed\_By\_Clearing**), or deemed paid (**Deemed\_PAID**). Use these statuses to automate follow-ups only when necessary. - **Financial institutions**: Show **Deemed\_PAID** where appropriate to set accurate expectations and reduce inquiries about transactions that may still reverse later. ## Endpoint and headers | **Field** | **Value** | | -------------- | ------------------ | | `Content-Type` | `application/json` | **POST** `https:///webhook` ## Request body ### Top-level fields | **Field** | **Description** | **Type** | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | Unique client identifier provisioned before integration. | UUID | | `customerHashId` | Unique customer identifier created when you onboard a customer. | UUID | | `walletHashId` | Unique wallet identifier created with the customer. | UUID | | `systemReferenceNumber` | Unique transaction reference in Nium. | String | | `transactionCurrency` | Transaction currency in [ISO-4217 format](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | Destination amount of the remittance. | String | | `billingCurrency` | Wallet balance currency in [ISO-4217 format](https://www.iso.org/iso-4217-currency-codes.html). | String | | `billingAmount` | Source amount of the remittance. | String | | `exchangeRate` | Applied FX rate (source → destination). | String | | `beneficiaryName` | Beneficiary name. | String | | `beneficiaryAccountNumber` | Beneficiary account number (may be masked). | String | | `beneficiaryBankName` | Beneficiary bank name. | String | | `template` | Fixed value: `REMIT_TRANSACTION_SUBSTATUS_UPDATE_WEBHOOK`. | String | | `subStatus` | Current sub-status. One of: `Sent_To_Beneficiary`, `Sent_To_Beneficiary_Bank`, `Processed_By_Clearing`, `Deemed_PAID`. | String | | `tags[]` | Optional metadata items to help reconciliation (for example, “Transaction Reference Number”). | Array | | `externalId` | Your unique identifier for the transaction (see **Transfers** API). | String | ### Sub-status meanings | **subStatus** | **What it means** | **Typical return cause(s)** | | -------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | | `Sent_To_Beneficiary` | Funds reached the beneficiary; final leg complete. | Beneficiary refusal (**MD06**). | | `Sent_To_Beneficiary_Bank` | Funds reached the beneficiary bank; final posting pending. | Incorrect/closed account, name mismatch (**MD07**, **MM20**, **AG03**, **AC01**, **AC03**). | | `Processed_By_Clearing` | Funds passed the clearing system; pending at beneficiary bank. | Corridor-specific reasons. | | `Deemed_PAID` | No return within corridor’s observation window; treated as paid. | Late scheme/partner returns (rare but possible). | | `TIMED_OUT` | No response received from the beneficiary bank within the expected time. Final response awaited. | Incorrect/closed account or name mismatch (**MD07**, **MM20**, **AG03**, **AC01**, **AC03**). | > The observation window and return behaviors vary by corridor and partner. Align your SLAs and customer messaging per corridor. ## Examples ### Deemed paid ```bash curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId": "0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId": "e83cca77-8b63-4a25-b580-1d872380ef29", "transactionCurrency": "INR", "transactionAmount": "5418.1700", "systemReferenceNumber": "RT1343085439", "exchangeRate": "54.454000000" }' ``` --- # Remit Transaction NOC URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-transaction-noc This event is triggered when NIUM receives a Notification of Change (NOC) from the ACH scheme for a US payout. It delivers a structured webhook containing the normalized reason for the change, the corrected value, and a recommended action — so clients can update their beneficiary or bank details before the next payment attempt. ## Header | Header | Value | | ------------ | ---------------- | | Content-Type | application/json | ## Request Example ```bash curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "template": "REMIT_TRANSACTION_NOC_WEBHOOK", "clientHashId": "ecc9841c-c0df-c6e4-86f4-b320180d9859", "customerHashId": "0f5a988e-c99a-4ce5-4ab7-b769e182de6f", "walletHashId": "f46lb211-6e23-99ba-6356-8gb9t6s76458", "systemReferenceNumber": "ZL1GX90938293", "externalId": "Custom1245", "beneficiaryAccountNumber": "xxxxxxxxxxxxxxxxxx4200", "beneficiaryBankName": "Chase Bank", "beneficiaryName": "John Smith", "billingAmount": "1000.00", "billingCurrency": "USD", "transactionAmount": "1000.00", "transactionCurrency": "USD", "exchangeRate": "1.000000000", "nocCode": "C02", "nocReasonCode": "ROUTING_NUMBER_CHANGED", "nocReasonDescription": "The routing/transit number for this account has changed. Update the routing number in your system using the correctedValue before initiating future payments to this beneficiary.", "correctedValue": "021000021", "tags": [] }' ``` ## Event Body | Field | Description | Type | | -------------------------- | ---------------------------------------------------------------------------------------------------- | ------ | | `template` | Fixed value: `REMIT_TRANSACTION_NOC_WEBHOOK` | String | | `clientHashId` | The unique client identifier generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier generated with customer creation. | UUID | | `systemReferenceNumber` | Unique system reference number generated by the platform for the affected transaction. | String | | `externalId` | Unique identifier provided by the client to track requests or transactions. | String | | `beneficiaryAccountNumber` | The bank account number of the beneficiary associated with the affected transaction. | String | | `beneficiaryBankName` | The bank name of the beneficiary. | String | | `beneficiaryName` | The name of the beneficiary. | String | | `billingAmount` | The source amount of the affected transaction. | String | | `billingCurrency` | The three-letter ISO-4217 currency code for the wallet balance. | String | | `transactionAmount` | The destination amount of the affected transaction. | String | | `transactionCurrency` | The three-letter ISO-4217 currency code for the transaction. | String | | `exchangeRate` | Exchange rate from source to destination currency. | String | | `nocCode` | The raw NACHA NOC code received from the ACH scheme (e.g., `C01`, `C02`). | String | | `nocReasonCode` | Normalized NIUM reason code describing what changed (see NOC Code Mapping below). | String | | `nocReasonDescription` | Human-readable description of the change and the recommended action for the client. | String | | `correctedValue` | The corrected value provided by the receiving bank (e.g., updated routing number or account number). | String | | `tags` | Custom key-value pairs assigned to the transaction (max 15 pairs). | Array | ## NOC Code Mapping | NACHA Code | NIUM Reason Code | Description | | ---------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | C01 | `ACCOUNT_NUMBER_UPDATED` | The account number is incorrect. Update the beneficiary account number using `correctedValue`. | | C02 | `ROUTING_NUMBER_CHANGED` | The routing/transit number is incorrect. Update the routing number using `correctedValue`. | | C03 | `ROUTING_AND_ACCOUNT_NUMBER_CHANGED` | Both the routing number and account number are incorrect. Update both fields; `correctedValue` contains the corrected account number. Contact NIUM support for the updated routing number. | | C04 | `BENEFICIARY_NAME_UPDATED` | The individual name or company name does not match bank records. Update the beneficiary name using `correctedValue`. | | C05 | `TRANSACTION_CODE_CHANGED` | The transaction code (checking vs. savings) is incorrect. Update the account type using `correctedValue`. | | C06 | `ACCOUNT_NUMBER_AND_TRANSACTION_CODE_CHANGED` | Both the account number and transaction code are incorrect. Update both fields using `correctedValue`. | | C07 | `ROUTING_ACCOUNT_AND_TRANSACTION_CODE_CHANGED` | The routing number, account number, and transaction code are all incorrect. Update all three fields. | ## Recommended Actions When you receive a `REMIT_TRANSACTION_NOC_WEBHOOK`: 1. Use `systemReferenceNumber` to identify the affected transaction. 2. Read `nocReasonCode` to determine which field needs updating. 3. Apply the `correctedValue` to the relevant beneficiary or bank detail in your system. 4. Re-initiate the payment with the updated details to avoid a return. NOC events are informational — the original transaction is not automatically re-submitted. If no action is taken and a subsequent payment is sent with the same incorrect details, NIUM will return the transaction. --- # Remit Delayed Transactions Webhook URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payout-events/remit-delayed-transactions-webhook This event is triggered when a payout is delayed in transit. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL ccurl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -d '{ "clientHashId": "0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId": "e83cca77-8b63-4a25-b580-1d872380ef29", "sourceCurrency": "SGD", "destinationCurrency": "INR", "systemReferenceNumber": "RT1343085439", "destinationCountry": "IN", "status": "SENT_TO_BANK", "updatedETA": "2024-03-15T10:30:00Z", "delayedReason": "Payment is under compliance review at the intermediary bank.", "template": "REMIT_TRANSACTION_DELAYED_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `sourceCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html) for source currency. | String | | `destinationCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html) for the destination currency. | String | | `systemReferenceNumber` | This is a unique system reference number that's generated by the card issuance platform for the transaction. | String | | `destinationCountry` | This field contains the two-letter [ISO-3166 country code](https://www.iso.org/iso-3166-country-codes.html) for the destination country. | String | | `status` | This field contains the current status of the transaction at the time the delay was detected. | String | | `updatedETA` | This field contains the revised estimated delivery time in the `2024-03-15T10:30:00Z` ISO 8601 format. | String | | `delayedReason` | This field contains a description of the reason the transaction has been delayed. | String | | `template` | The value for this field is `REMIT_TRANSACTION_DELAYED_WEBHOOK`. | String | --- # Payin Webhooks URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events Our Payin events help you track and manage funds received from various sources into your Nium wallets. Whether funds are added via bank transfers, card transactions, or micro-deposits, Payin events ensure you are updated in real time. Specifically, payin events allow you to: - Track successful wallet funding events and funding instrument approvals. - Identify and manage transaction returns, chargebacks, or failures. - Monitor micro-deposit verification processes. These events are critical for monitoring funding instrument status and wallet funding events. ## Supported Events The following payin events are available: - [**Transaction Return**](/docs/developers/notifications-and-webhooks/payin-events/transaction-return) - [**Chargeback Transaction Settled**](/docs/developers/notifications-and-webhooks/payin-events/chargeback-transaction-settled) - [**Micro-deposit Successful**](/docs/developers/notifications-and-webhooks/payin-events/micro-deposit-successful) - [**Funding Instrument Approved**](/docs/developers/notifications-and-webhooks/payin-events/funding-instrument-approved) - [**Funding Instrument Failed**](/docs/developers/notifications-and-webhooks/payin-events/funding-instrument-failed) - [**Funding Instrument Cancelled**](/docs/developers/notifications-and-webhooks/payin-events/funding-instrument-cancelled) - [**Wallet Funded**](/docs/developers/notifications-and-webhooks/payin-events/wallet-funded) --- # Transaction Return URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events/transaction-return This template is triggered when a return/reversal request is received for a Direct Debit transaction. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "template": "DIRECT_DEBIT_TRANSACTION_RETURN_WEBHOOK", "transactionCurrency": "USD", "routingValue": "011401533", "systemReferenceNumber": "FW4086323985", "debitReason": "R01", "walletHashId": "7a73f776-50f2-428c-9615-0c507ffcb59e", "transactionDate": "2023-03-30 12:28:24.879", "accountNumber": "XXXXXXXXXXXX1111", "customerHashId": "017d7c23-c9bc-49db-9612-8748e22c4fe6", "routingType": "ACH CODE", "beneficiaryName": "Albertha Bobbeth Charleson", "transactionAmount": "52.00", "debitCode": "ACH_RETURN", "clientHashId": "c3bcbcc0-07a9-4bdd-b8c8-de62c52bda83" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](/docs/getting-started/currency-and-country-codes). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `systemReferenceNumber` | The unique system-generated reference number for the transaction. | String | | `beneficiaryName` | The name of the beneficiary. | String | | `transactionDate` | The date when the Fund Wallet is called. | String | | `accountNumber` | This field contains the masked account number. | String | | `routingValue` | This field contains the bank code. | String | | `routingType` | This field contains the routing type of the ACH code or SORT code depending on the geography. | String | | `template` | The value for this field is `DIRECT_DEBIT_TRANSACTION_RETURN_WEBHOOK`. | String | | `debitCode` | This field contains the debit code of `RETURN` or `REVERSAL`. | String | | `debitReason` | This field contains the R-code for the US and a similar code for UK/EU. | String | | `walletBalance` | This field shows the balance after the debit. | String | --- # Chargeback Transaction Settled URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events/chargeback-transaction-settled This event is triggered when Nium claims the amount back from the customer’s wallet after a chargeback is raised. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "template": "DIRECT_DEBIT_TRANSACTION_CHARGEBACK_SETTLED_WEBHOOK", "transactionCurrency": "USD", "routingValue": "011401533", "systemReferenceNumber": "FW4086323985R", "debitReason": "R01", "walletHashId": "7a73f776-50f2-428c-9615-0c507ffcb59e", "transactionDate": "2023-03-30 12:28:24.879", "accountNumber": "XXXXXXXXXXXX1111", "customerHashId": "017d7c23-c9bc-49db-9612-8748e22c4fe6", "walletBalance": "88.24", "routingType": "ACH CODE", "beneficiaryName": "Albertha Bobbeth Charleson", "transactionAmount": "52.00", "debitCode": "ACH_REVERSAL", "clientHashId": "c3bcbcc0-07a9-4bdd-b8c8-de62c52bda83" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](/docs/getting-started/currency-and-country-codes). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `systemReferenceNumber` | The unique system-generated reference number for the transaction. | String | | `beneficiaryName` | The name of the beneficiary. | String | | `transactionDate` | The date when the Fund Wallet is called. | String | | `accountNumber` | This field contains the masked account number. | String | | `routingValue` | This field contains the bank code. | String | | `routingType` | This field contains the routing type of ACH code or SORT code depending on the geography. | String | | `template` | The value for this field is `DIRECT_DEBIT_TRANSACTION_CHARGEBACK_SETTLED_WEBHOOK`. | String | | `debitCode` | This field contains the debit code of `RETURN` or `REVERSAL`. | String | | `debitReason` | This field contains the R-code for the US and a similar code for UK/EU. | String | | `walletBalance` | This field shows the balance after the debit. | String | --- # Micro-deposit Successful URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events/micro-deposit-successful The client receives this event when a micro-deposit amount is successfully deposited in the customer's linked bank account. The expectation is for the client to call the Confirm Funding Instrument ID API after receiving this webhook. The client receives this event when a micro-deposit amount is successfully deposited in the customer's linked bank account. The expectation is for the client to call the [Confirm Funding Instrument ID](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/confirmFundingInstrument) API after receiving this webhook. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL { "template": "DIRECT_DEBIT_MICRODEPOSIT_SUCCESSFUL", "country": "US", "fundingInstrumentId": "444eebc5-196a-48c3-b89e-0689a41faff1", "routingValue": "", "fundingChannel": "DIRECT_DEBIT", "walletHashId": "0e552b64-da71-4888-be81-e8ab76a6f85e", "maskedAccountNumber": "${maskedAccountNumber}", "customerHashId": "8377480c-3169-4f86-ad7d-bc914d75b9a2", "createdAt": "2023-07-05 10:26:47", "statusDescription": "Awaiting_customer_verification | paid", "routingType": "", "currency": "USD", "clientHashId": "c3bcbcc0-07a9-4bdd-b8c8-de62c52bda83", "status": "PENDING", "updatedAt": "2023-07-05 10:32:13" } ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | `country` | The two-letter [ISO 3166-1-alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code where the bank account resides. | String | | `fundingInstrumentId` | The unique 36-character alphanumeric identifier of a funding instrument. In the context of Direct Debit, it serves as a bank account identifier. | String | | `routingValue` | The unique identifier value that's used to identify financial institutions and their branches worldwide. | String | | `fundingChannel` | The funding channel refers to the mode of funding a wallet. When adding a new funding instrument, only Direct Debit is supported. | String | | `walletHashId` | The unique 36-character wallet identifier that's generated and shared before the API handshake. | String | | `maskedAccountNumber` | The masked bank account number in the `XXXXXXXXXXXX1111` format. | String | | `customerHashId` | The unique 36-character customer identifier that's generated and shared before the API handshake. | String | | `createdAt` | The timestamp when the funding instrument is added. | Date-time | | `statusDescription` | The additional information of the status response. | String | | `routingType` | The routing type, for example, SWIFT Code, IFSC Code, ACH Code, BSB Code, SORT Code, Location ID, Bank Code, Transit Number, and Branch Code. | String | | `currency` | The three-letter [ISO-4217 currency code](/docs/getting-started/currency-and-country-codes). | String | | `clientHashId` | The unique client 36-character client identifier that's generated and shared before the API handshake. | String | | `status` | The present status of the funding instrument. The statuses are \n `PENDING`, `APPROVED`, `FAILED` and `CANCELLED`. | String | | `updatedAt` | The timestamp when the funding instrument is last updated. | Date-time | | `template` | The value for this field is `DIRECT_DEBIT_MICRODEPOSIT_SUCCESSFUL`. | String | --- # Funding Instrument Approved URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events/funding-instrument-approved The client receives this event when a funding instrument is successfully linked. The client can then proceed to initiate Direct Debit transactions. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL { "template": "DIRECT_DEBIT_FUNDING_INSTRUMENT_APPROVED", "country": "US", "fundingInstrumentId": "a5c88bdb-8a85-478b-a1ed-15a53434636d", "routingValue": "", "fundingChannel": "DIRECT_DEBIT", "walletHashId": "0e552b64-da71-4888-be81-e8ab76a6f85e", "maskedAccountNumber": "${maskedAccountNumber}", "customerHashId": "8377480c-3169-4f86-ad7d-bc914d75b9a2", "createdAt": "2023-07-11 06:49:37", "statusDescription": "Awaiting_customer_verification | approved", "routingType": "", "currency": "USD", "clientHashId": "c3bcbcc0-07a9-4bdd-b8c8-de62c52bda83", "status": "APPROVED", "updatedAt": "2023-07-11 06:50:43" } ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | `country` | The two-letter [ISO 3166-1-alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code where the bank account resides. | String | | `fundingInstrumentId` | The unique 36-character alphanumeric identifier of a funding instrument. In the context of Direct Debit, it serves as a bank account identifier. | String | | `routingValue` | The unique identifier value that's used to identify financial institutions and their branches worldwide. | String | | `fundingChannel` | The funding channel refers to the mode of funding a wallet. When adding a new funding instrument, only Direct Debit is supported. | String | | `walletHashId` | The unique 36-character wallet identifier that's generated and shared before the API handshake. | String | | `maskedAccountNumber` | The masked bank account number in the `XXXXXXXXXXXX1111` format. | String | | `customerHashId` | The unique 36-character customer identifier that's generated and shared before the API handshake. | String | | `createdAt` | The timestamp when the funding instrument is added. | Date-time | | `statusDescription` | The additional information of the status response. | String | | `routingType` | The routing type, for example, SWIFT Code, IFSC Code, ACH Code, BSB Code, SORT Code, Location ID, Bank Code, Transit Number, and Branch Code. | String | | `currency` | The three-letter [ISO-4217 currency code](/docs/getting-started/currency-and-country-codes). | String | | `clientHashId` | The unique client 36-character client identifier that's generated and shared before the API handshake. | String | | `status` | The present status of the funding instrument. The statuses are \n `PENDING`, `APPROVED`, `FAILED` and `CANCELLED`. | String | | `updatedAt` | The timestamp when the funding instrument is last updated. | Date-time | | `template` | The value for this field is `DIRECT_DEBIT_FUNDING_INSTRUMENT_APPROVED`. | String | --- # Funding Instrument Failed URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events/funding-instrument-failed The client receives this event when a funding instrument could not be successfully linked. The client can call the Add Funding Instrument API again to link their bank account. The client can get additional details about the reason for failure from the Get Funding Instrument Details request. The client receives this event when a funding instrument *could not* be successfully linked. The client can call the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) API again to link their bank account. The client can get additional details about the reason for failure from the [Get Funding Instrument Details](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) request. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL { "template": "DIRECT_DEBIT_FUNDING_INSTRUMENT_FAILED", "country": "US", "fundingInstrumentId": "a5c88bdb-8a85-478b-a1ed-15a53434636d", "routingValue": "", "fundingChannel": "DIRECT_DEBIT", "walletHashId": "0e552b64-da71-4888-be81-e8ab76a6f85e", "maskedAccountNumber": "${maskedAccountNumber}", "customerHashId": "8377480c-3169-4f86-ad7d-bc914d75b9a2", "createdAt": "2023-07-11 06:49:37", "statusDescription": "Awaiting_customer_verification | failed", "routingType": "", "currency": "USD", "clientHashId": "c3bcbcc0-07a9-4bdd-b8c8-de62c52bda83", "status": "FAILED", "updatedAt": "2023-07-11 06:50:43" } ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | `country` | The two-letter [ISO 3166-1-alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code where the bank account resides. | String | | `fundingInstrumentId` | The unique 36-character alphanumeric identifier of a funding instrument. In the context of Direct Debit, it serves as a bank account identifier. | String | | `routingValue` | The unique identifier value that's used to identify financial institutions and their branches worldwide. | String | | `fundingChannel` | The funding channel refers to the mode of funding a wallet. When adding a new funding instrument, only Direct Debit is supported. | String | | `walletHashId` | The unique 36-character wallet identifier that's generated and shared before the API handshake. | String | | `maskedAccountNumber` | The masked bank account number in the `XXXXXXXXXXXX1111` format. | String | | `customerHashId` | The unique 36-character customer identifier that's generated and shared before the API handshake. | String | | `createdAt` | The timestamp when the funding instrument is added. | Date-time | | `statusDescription` | The additional information of the status response. | String | | `routingType` | The routing type, for example, SWIFT Code, IFSC Code, ACH Code, BSB Code, SORT Code, Location ID, Bank Code, Transit Number, and Branch Code. | String | | `currency` | The three-letter [ISO-4217 currency code](/docs/getting-started/currency-and-country-codes). | String | | `clientHashId` | The unique client 36-character client identifier that's generated and shared before the API handshake. | String | | `status` | The present status of the funding instrument. The statuses are \n `PENDING`, `APPROVED`, `FAILED` and `CANCELLED`. | String | | `updatedAt` | The timestamp when the funding instrument is last updated. | Date-time | | `template` | The value for this field is `DIRECT_DEBIT_FUNDING_INSTRUMENT_FAILED`. | | --- # Funding Instrument Cancelled URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events/funding-instrument-cancelled The client receives this event when a funding instrument is cancelled via the customer's bank. The client can call the Add Funding Instrument API again to link their bank account. The client can get additional details about the reason for the failure from the Get Funding Instrument Details request. The client receives this event when a funding instrument is cancelled via the customer's bank. The client can call the [Add Funding Instrument](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) API again to link their bank account. The client can get additional details about the reason for the failure from the [Get Funding Instrument Details](/api#tag/customer-funding/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments/{fundingInstrumentId}/fundingInstrumentDetails) request. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL { "template": "DIRECT_DEBIT_FUNDING_INSTRUMENT_CANCELLED", "country": "US", "fundingInstrumentId": "370b6cb0-c5e9-4308-8873-e48bd74c4960", "routingValue": "110000000", "fundingChannel": "DIRECT_DEBIT", "walletHashId": "0e552b64-da71-4888-be81-e8ab76a6f85e", "maskedAccountNumber": "XXXXXXXXXXXX0081", "customerHashId": "8377480c-3169-4f86-ad7d-bc914d75b9a2", "createdAt": "2023-07-11 06:46:41", "statusDescription": "Awaiting_customer_verification | in_progress | cancelled", "routingType": "ACH CODE", "currency": "USD", "clientHashId": "c3bcbcc0-07a9-4bdd-b8c8-de62c52bda83", "status": "CANCELLED", "updatedAt": "2023-07-11 07:08:07" } ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | `country` | The two-letter [ISO 3166-1-alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code where the bank account resides. | String | | `fundingInstrumentId` | The unique 36-character alphanumeric identifier of a funding instrument. In the context of Direct Debit, it serves as a bank account identifier. | String | | `routingValue` | The unique identifier value that's used to identify financial institutions and their branches worldwide. | String | | `fundingChannel` | The funding channel refers to the mode of funding a wallet. When adding a new funding instrument, only Direct Debit is supported. | String | | `walletHashId` | The unique 36-character wallet identifier that's generated and shared before the API handshake. | String | | `maskedAccountNumber` | The masked bank account number in the `XXXXXXXXXXXX1111` format. | String | | `customerHashId` | The unique 36-character customer identifier that's generated and shared before the API handshake. | String | | `createdAt` | The timestamp when the funding instrument is added. | Date-time | | `statusDescription` | The additional information of the status response. | String | | `routingType` | The routing type, for example, SWIFT Code, IFSC Code, ACH Code, BSB Code, SORT Code, Location ID, Bank Code, Transit Number, and Branch Code. | String | | `currency` | The three-letter [ISO-4217 currency code](/docs/getting-started/currency-and-country-codes). | String | | `clientHashId` | The unique client 36-character client identifier that's generated and shared before the API handshake. | String | | `status` | The present status of the funding instrument. The statuses are \n `PENDING`, `APPROVED`, `FAILED` and `CANCELLED`. | String | | `updatedAt` | The timestamp when the funding instrument is last updated. | Date-time | | `template` | The value for this field is `DIRECT_DEBIT_FUNDING_INSTRUMENT_CANCELLED`. | String | --- # Wallet Funded URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events/wallet-funded This event is triggered when the wallet is funded. Wallets can be funded using the Fund Wallet API. This event is triggered when the wallet is funded. Wallets can be funded using the [Fund Wallet](/api#tag/customer-funding/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fundingInstruments) API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "brandName":"ABC Technologies Ltd.", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "transactionCurrency":"SGD", "transactionAmount":"10", "walletBalance":"10", "authCode":"FW1234567890", "template":"CARD_WALLET_FUNDING_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `brandName` | The brand name field is for the client's company name. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with the customer creation. | UUID | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](/docs/getting-started/currency-and-country-codes). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `walletBalance` | The available balance in the wallet. | String | | `authCode` | The authorization code of the transaction in the format of `FW` followed by an integer. | String | | `template` | The value for this field is `CARD_WALLET_FUNDING_WEBHOOK`. | String | --- # Incoming Funds URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/payin-events/incoming-funds This event is for Global Collections use case, when funds are received on behalf of Financial Institution's ultimate beneficiaries. This event is for Global Collections use case, when funds are received on behalf of Financial Institution's ultimate `beneficiaries`. At this time, this event is only triggered whe the `status` of a `payin` is **NO\_MATCH**. ```json URL https:///webhook ``` ## Request Parameters | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ## Request Example ```json { "clientHashId": "86ce8d7b-f3fa-46d5-8d1c-53212aade5b5", "customerHashId": "857dc08e-dffa-4e9a-ad96-79041c8a7025", "walletHashId": "857dc08e-dffa-4e9a-ad96-79041c8a7025", "systemReferenceNumber": "RT1343085439", "bankReferenceNumber": "5A826K18", "beneficiaryName": "Johnny Appleseed", "ExternalId": "XYZ123", "clientTransactionId":"12345", "email": "johnny.appleseed@nium.com", "receiverBank": "Monoova", "paymentType": "FAST", "remitterBankName": "Bank of Singapore", "remitterName": "John Smith", "template": "INCOMING_FUNDS_WEBHOOK", "transactionAmount": 5418.1700, "transactionCurrency": "SGD", "transactionDate": "2024-12-20", "uniquePayerId": "null", "virtualAccountNumber": "8850932067971" } ``` ### Request body | Field | Description | Type | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | | `clientHashId` | The unique identifier for the client generated during onboarding; the unique `clientId`. | String | | `customerHashId` | The unique identifier for the customer generated when the customer was added to the clients account a `customerId` was generated. | String | | `walletHashId` | The unique identifier for the client's wallet; the `walletId`. | String | | `systemReferenceNumber` | The unique identifier for the transaction, same as `AuthCode` in a transaction. | String | | `bankReferenceNumber` | The bank’s identifier for the transaction. | String | | `beneficiaryName` | The name of the beneficiary. | String | | `ExternalId` | The client’s identifier for the customer. | String | | `clientTransactionId` | The client’s identifier for the transaction. | String | | `email` | The client’s email address. | String | | `receiverBank` | The partner bank sending the inward credit confirmation to notify Nium of funds received. | String | | `paymentType` | The payment mode used to send the funds to Nium’s partner bank. | String | | `remitterBankName` | The name of the bank used by the remitter to send the funds. | String | | `remitterName` | The name of the remitter. | String | | `template` | Const of value: **INCOMING\_FUNDS\_WEBHOOK**. | Constant | | `transactionAmount` | The amount received. | String | | `transactionCurrency` | The currency code for the funds received in the transaction. | String, length must be three characters | | `transactionDate` | The date of the transaction. | String with the format `YYYY-MM-DD` | | `uniquePayerId` | The unique email ID provided to the customer in addition to a `uniquePaymentId` for supported regions and configurations. If the region doesn't support the `uniquePayerId`, the field will return **null**. | String | | `virtualAccountNumber` | The virtual account number is provided to customers for supported regions and configuration (for example, IBAN in EU, virtual account number from Moonova in AU). If not supported, returns **null**. | String | --- # Issuing and Card Webhooks URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events Our Issuing and Cards events provide real-time updates on card lifecycle updates and changes, including card issuance, transactions, authentication, and settlements. These notifications allow you to monitor card activities, manage card statuses, and proactively address transaction issues. Specifically, Issuing and card events allow you to: - Track card activation, usage, and authentication events. - Monitor transaction status, declines, and reversals. - Manage card blocks, replacements, and updates. Issuing notifications are essential for managing cardholder experiences, preventing fraud, and maintaining compliance. ## Supported Events The following issuing and card events are available: - [Add Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/add-card) - [Assign Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/assign-card) - [Add On Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/add-on-card) - [Activate Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/activate-card) - [Activation Code](/docs/developers/notifications-and-webhooks/issuing-and-card-events/activation-code) - [3DS One-Time-Password](/docs/developers/notifications-and-webhooks/issuing-and-card-events/3ds-one-time-password) - [Failed 3DS Authentication](/docs/developers/notifications-and-webhooks/issuing-and-card-events/failed-3ds-authentication) - [VTS Token](/docs/developers/notifications-and-webhooks/issuing-and-card-events/vts-token) - [VTS Provisioning](/docs/developers/notifications-and-webhooks/issuing-and-card-events/vts-provisioning) - [Set PIN](/docs/developers/notifications-and-webhooks/issuing-and-card-events/set-pin) - [Permanent Block](/docs/developers/notifications-and-webhooks/issuing-and-card-events/permanent-block) - [Temporary Block](/docs/developers/notifications-and-webhooks/issuing-and-card-events/temporary-block) - [Temporary Block Removal](/docs/developers/notifications-and-webhooks/issuing-and-card-events/temporary-block-removal) - [POS Approved](/docs/developers/notifications-and-webhooks/issuing-and-card-events/pos-approved) - [ATM Approved](/docs/developers/notifications-and-webhooks/issuing-and-card-events/atm-approved) - [Transaction Reversal](/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-reversal) - [Transaction Reversal Advice](/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-reversal-advice) - [Wrong PIN Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-pin-decline) - [Inactive Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/inactive-decline) - [Block Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/block-decline) - [Card System Down](/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-system-down) - [Expired Card](/docs/developers/notifications-and-webhooks/issuing-and-card-events/expired-card) - [Card Replacement](/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-replacement) - [Miscellaneous](/docs/developers/notifications-and-webhooks/issuing-and-card-events/miscellaneous) - [PIN Block Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/pin-block-decline) - [Card Unblock Pin](/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-unblock-pin) - [PIN Retry Exceed Decline](/docs/developers/notifications-and-webhooks/issuing-and-card-events/pin-retry-exceed-decline) - [PIN Retry Exceed Soft Block](/docs/developers/notifications-and-webhooks/issuing-and-card-events/pin-retry-exceed-soft-block) - [Insufficient Funds Declined](/docs/developers/notifications-and-webhooks/issuing-and-card-events/insufficient-funds-declined) - [Insufficient Funds Declined Client](/docs/developers/notifications-and-webhooks/issuing-and-card-events/insufficient-funds-declined-client) - [Wrong CVV2](/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-cvv2) - [Transaction Limit Exceeds](/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-limit-exceeds) - [Restricted Transactions](/docs/developers/notifications-and-webhooks/issuing-and-card-events/restricted-transactions) - [Wrong Expiry](/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-expiry) - [Transaction Not Supported](/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-not-supported) - [Settlement Debit](/docs/developers/notifications-and-webhooks/issuing-and-card-events/settlement-debit) - [Settlement Credit](/docs/developers/notifications-and-webhooks/issuing-and-card-events/settlement-credit) - [Settlement Direct Debit](/docs/developers/notifications-and-webhooks/issuing-and-card-events/settlement-direct-debit) - [Settlement Reversal](/docs/developers/notifications-and-webhooks/issuing-and-card-events/settlement-reversal) - [Card Expiry Alert](/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-expiry-alert) - [Card Details Updated](/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-details-updated) --- # Add Card URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/add-card This template is triggered when a card is issued using the Add Card API. This template is triggered when a card is issued using the [Add Card](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location 'https:///webhook' \ --header 'content-type: application/json' \ --data '{ "clientHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "cardHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "cardNumber":"4001-35xx-xxxx-1950", "walletHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "template": "CARD_ADD_CARD_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `template` | The value for this field is `CARD_ADD_CARD_WEBHOOK`. | String | --- # Assign Card URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/assign-card This template is triggered when a card is assigned to a customer. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location 'https:///webhook' \ --header 'content-type: application/json' \ --data '{ "clientHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "cardHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "cardNumber":"4001-35xx-xxxx-1950", "walletHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "template": "CARD_ASSIGN_CARD_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in `1234-56xx-xxxx-3456` format. | String | | `template` | The value for this field is `CARD_ASSIGN_CARD_WEBHOOK`. | String | --- # Add On Card URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/add-on-card This template is triggered when an ADD_ON card is issued using the Add Card API. This template is triggered when an `ADD_ON` card is issued using the [Add Card](/api#tag/lifecycle/POST/api/v2/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card) API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"5ccc078b-8cc8-4d49-b231-73030f01b501", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "cardHashId":"1f5c16eb-57cb-40b7-873f-96ca376f22ce", "cardNumber":"4611-35xx-xxxx-1950", "template":"CARD_ADD_ON_CARD_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ---------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | This field contains the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `template` | The value for this field is `CARD_ADD_ON_CARD_WEBHOOK`. | String | --- # Activate Card URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/activate-card This template is triggered when a physical card is activated. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"5ccc078b-8cc8-4d49-b231-73030f01b501", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "cardHashId":"1f5c16eb-57cb-40b7-873f-96ca376f22ce", "cardNumber":"4001-35xx-xxxx-1950", "cardActivationStatus":"Active", "cardActivationDateTime":"2020-09-29 09:24:46", "template":"CARD_ACTIVATION_CARD_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------------ | --------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | This field contains the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `cardActivationStatus` | This field contains the activation status of the card. | String | | `cardActivationDateTime` | This field contains the card activation date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `template` | The value for this field is `CARD_ACTIVATION_CARD_WEBHOOK`. | String | --- # Activation Code URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/activation-code Triggered when a physical card is printed and ready to be dispatched. Cardholders can use the activation code included on the event to activate the card. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"5ccc078b-8cc8-4d49-b231-73030f01b501", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "cardHashId":"1f5c16eb-57cb-40b7-873f-96ca376f22ce", "cardNumber":"4001-35xx-xxxx-1950", "activationCode":"12345678", "template":"CARD_ACTIVATION_CODE_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | The 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `activationCode` | The 8-digit activation code of the card. | String | | `template` | Set to `CARD_ACTIVATION_CODE_WEBHOOK` for this event. | String | --- # Failed 3DS Authentication URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/failed-3ds-authentication Triggered when authentication is declined with our 3DS Vendor and no authorization record was received. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"d4e1e512-hhd7-4eca-ad41-dd39325facc2", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "cardHashId":"a344b0c8-d27d-4db5-8194-aacdefb558ca", "merchantId":"FQVN6GDWYT0NOB6", "merchantName":"SP ONETREEPLANTED", "mcc":"8641", "merchantCountryCode":"SGD", "merchantUrl":"https://www.requestor.com", "transactionId":"aa3ae2e6-2d91-4579-8df2-0110fb06fc8c", "transactionCurrency":"SGD", "transactionAmount":"5499", "transactionDate":"2023-09-29 09:24:46", "authenticationResponse":"N", "authenticationType":"OTPSMS", "eci":"05", "template":"CARD_3DS_Failed_Authentication_WEBHOOK" }' ``` ### Request body #### Card Info | Current Fields | Description | Required | Length | | ------------------ | ----------------------------------------------------- | ---------- | ------- | | `maskedCardNumber` | This field accepts the mask card number. | *Required* | 16 Char | | `clientHashId` | Unique client identifier generated during onboarding. | *Required* | UUID | #### Merchant Info | Current Fields | Description | Required | Length | | -------------- | ----------------------------------------------------------------- | -------- | --------------- | | `merchantName` | This field accepts the merchant’s name. | Required | Up to 40 Char | | `mcc` | Code is used to describe the merchant type of business. | Optional | 4 Char | | `countrycode` | Country code of the merchant. For example: 840 numeric -3 format | Optional | Up to 3 Char | | `url` | URL or APP Name for the Merchant performing the purchase request. | Optional | Up to 2048 Char | #### Transaction Info | Current Fields | Description | Required | Length | | --------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------- | | `transactionAmount` | This field accepts the transaction amount up to 2 decimals. Formatted Transaction Amount | *Required* | Up to 48 Char | | `transactionCurrency` | This field accepts the 3-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) for the transaction. | *Required* | 3 Char | | `timestamp` | Transaction timestamp. For example: 2020-03-21T20:55:49.0000Z | Optional | 24 Char | #### Authentication Response | **Current Fields** | **Description** | **Required** | **Length** | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------- | | `authenticationType` | Type of authentication credential used for a given transaction. Possible values: OTPOTPSMSKBASINGLEOUTOFBANDOTHERblank | Optional | String | | `authenticationResponse` | The authentication response which is sent back to the merchant in 3DS. Possible values: N - Not AuthenticatedU - UnavailableR - Reject | Required | String | | `ECI` | Payment system specific value provided by ACS to indicate results of the attempt to authenticate. | Optional | String - 2 Char | --- # VTS Token URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/vts-token This event is triggered for a Visa Token Service (VTS). ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location 'https:///webhook' \ --header 'content-type: application/json' \ --data '{ "activationCode":"${activationCode}", "clientHashId":"${clientHashId}", "customerHashId":"${customerHashId}", "cardHashId":"${cardHashId}", "cardNumber":"${cardNumber}", "walletProvider":"${walletProvider}", "template":"${template}" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------------------- | -------- | | `activationCode` | This is the VTS activation token that's needed to set up the card. | String | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `walletProvider` | Provisioning is available for Apple Pay and Google Pay. Returned values include:applePaygooglePay | String | | `template` | The value for this field is `CARD_VTS_TOKEN_WEBHOOK`. | String | --- # VTS Provisioning URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/vts-provisioning This template is triggered on successful Visa Token Service (VTS) provisioning for either Google Pay or Apple Pay. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"18f3046c-17e8-4c8b-9fbd-9508305f37b5", "walletHashId":"6da29616-29f4-4cb2-ba46-24ca7f294bd8", "cardHashId":"00c31858-6a79-4bc2-bde5-5fd633aa20bd", "cardNumber":"4611-35xx-xxxx-2210", "walletProvider":"googlePay", "template":"CARD_VTS_PROVISION_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `walletProvider` | The provisioning is possible for Google Pay and Apple Pay. This can take one of the following two values: applePaygooglePay | String | | `template` | The value for this field is `CARD_VTS_PROVISION_WEBHOOK`. | String | --- # Set PIN URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/set-pin This template is triggered when the card PIN is set using the Set/Reset PIN API. This template is triggered when the card PIN is set using the [Set/Reset PIN](/api#tag/security/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin) API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "brandName":"ABC Technologies Ltd.", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "template":"CARD_SET_PIN_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `name` | This field contains the name of a client. | String | | `brandName` | The brand name field is for the client's company name. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `template` | The value for this field is `CARD_SET_PIN_WEBHOOK`. | String | --- # Permanent Block URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/permanent-block This template is triggered when a card is permanently blocked. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "brandName":"ABC Technologies Ltd.", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "template":"CARD_PERMANENT_BLOCK_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `name` | This field contains the name of a client. | String | | `brandName` | The brand name field is for the client's company name. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `template` | The value for this field is `CARD_PERMANENT_BLOCK_WEBHOOK`. | String | --- # Temporary Block URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/temporary-block This template is triggered when the card is temporarily blocked using the Block/Unblock Cards API. This template is triggered when the card is temporarily blocked using the [Block/Unblock Cards](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/cardAction) API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "brandName":"ABC Technologies Ltd.", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "template":"CARD_TEMPORARY_BLOCK_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `name` | This field accepts the name of a client. | String | | `brandName` | The brand name field is for the client's company name. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `template` | The value for this field is `CARD_TEMPORARY_BLOCK_WEBHOOK`. | String | --- # Temporary Block Removal URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/temporary-block-removal This template is triggered for the removal of a temporarily blocked card using the Block/Unblock Cards API. This template is triggered for the removal of a temporarily blocked card using the [Block/Unblock Cards](/api#tag/lifecycle/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/cardAction) API. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "brandName":"ABC Technologies Ltd.", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "template":"CARD_TEMPORARY_BLOCK_REMOVAL_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `name` | This field contains the name of a client. | String | | `brandName` | The brand name field is for the client's company name. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `template` | The value for this field is `CARD_TEMPORARY_BLOCK_REMOVAL_WEBHOOK`. | String | --- # POS Approved URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/pos-approved This template is triggered when the POS transaction is approved. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"a344b0c8-d27d-4db5-8194-aacdefb558ca", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"10.00", "transactionDate":"2020-09-29 09:24:46", "balanceCurrency":"SGD", "authAmount":"10.0", "walletBalance":"102.00", "mcc":"5499", "merchantName":"Frankie Tibbs", "merchantCountry":"IN", "merchantCity":"MUMBAI", "authCode":"114733" "effectiveAuthAmount":"11", "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319d2", "template":"CARD_POS_APPROVED_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | The transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `balanceCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `authAmount` | An authorization amount for the transaction. | String | | `walletBalance` | The available balance in the wallet. | String | | `mcc` | The four-digit merchant category code. | String | | `merchantName` | This field contains the merchant name. | String | | `merchantCountry` | This field contains the two-letter [ISO country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) for the merchant country. | String | | `merchantCity` | This field contains the merchant city. | String | | `authCode` | The authorization code of the transaction. | String | | `effectiveAuthAmount` | This field contains the authorization amount value in addition to fees such as transaction markup, e-commerce fees, etc. | String | | `rhaTransactionId` | This field contains the unique transaction ID for Delegated Model authorization clients. This is empty only for wallet clients. | UUID | | `template` | The value for this field is `CARD_POS_APPROVED_WEBHOOK`. | String | --- # ATM Approved URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/atm-approved This template is triggered when an ATM transaction is approved. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"eb61a0a7-978c-4014-80cf-164f08babae7", "walletHashId":"4f563cb9-56e1-49a9-b70b-0b893f4643ce", "cardHashId":"747b4427-5bab-4deb-bcbb-ad72130adf49", "cardNumber":"4001-35xx-xxxx-9155", "transactionCurrency":"SGD", "transactionAmount":"10.00", "transactionDate":"2020-09-29 09:24:46", "balanceCurrency":"SGD", "authAmount":"10.00", "walletBalance":"766.86", "mcc":"6011", "merchantCountry":"IN", "merchantCity":"MUMBAI", "authCode":"006384", "effectiveAuthAmount":"11", "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319d2", "template":"CARD_ATM_APPROVED_WEBHOOK" }' ``` ### Request Body | **Field** | **Description** | **Type** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | The transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `balanceCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `authAmount` | An authorization amount for the transaction. | String | | `walletBalance` | The available balance in the wallet. | String | | `mcc` | The four-digit merchant category code. | String | | `merchantCountry` | This field contains the two-letter [ISO-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) for the merchant country. | String | | `merchantCity` | This field accepts the merchant city. | String | | `authCode` | The authorization code of the transaction. | String | | `effectiveAuthAmount` | This field contains the authorization amount value in addition to fees such as transaction markup, ATM fees, international ATM fees, etc. | String | | `rhaTransactionId` | This field contains the unique transaction ID for Delegated Model authorization clients. This is empty only for wallet clients. | UUID | | `template` | The value for this field is `CARD_ATM_APPROVED_WEBHOOK`. | String | --- # Transaction Reversal URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-reversal This template is triggered when a transaction is reversed. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"5ccc078b-8cc8-4d49-b231-73030f01b501", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "cardHashId":"786d4171-1598-4abb-852a-dd24c160a719", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"10", "transactionDate":"2020-09-29 09:24:46", "balanceCurrency":"SGD", "walletBalance":"919", "merchantName":"Frankie Tibbs", "authCode" :"114723", "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319d2", "template":"CARD_TRANSACTION_REVERSAL_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `balanceCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `walletBalance` | This field contains the available balance in the wallet. | String | | `merchantName` | This field contains the merchant name. | String | | `authCode` | This field contains the authorization code of the transaction. | String | | `rhaTransactionId` | This field contains the unique transaction ID for Delegated Model authorization clients. This is empty only for wallet clients. | UUID | | `template` | The value for this field is `CARD_TRANSACTION_REVERSAL_WEBHOOK`. | String | --- # Transaction Reversal Advice URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-reversal-advice This template is triggered when a transaction is reversed due to a timeout or a merchant or scheme-initiated reversal. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -d '{ "name":"Samar", "customerHashId":"5ccc078b-8cc8-4d49-b231-73030f01b501", "walletHashId":"e83cca77-8b63-4a25-b580-1d872380ef29", "cardHashId":"786d4171-1598-4abb-852a-dd24c160a719", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"10", "transactionDate":"2020-09-29 09:24:46", "balanceCurrency":"SGD", "walletBalance":"919", "merchantName":"Frankie Tibbs", "authCode" :"114723", "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319d2", "template":"CARD_TRANSACTION_REVERSAL_ADVICE_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `balanceCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `walletBalance` | This field contains the available balance in the wallet. | String | | `merchantName` | This field contains the merchant name. | String | | `authCode` | This field contains the authorization code of the transaction. | String | | `rhaTransactionId` | This field contains the unique transaction ID for Delegated Model authorization clients. This is empty only for wallet clients. | UUID | | `template` | The value for this field is `CARD_TRANSACTION_REVERSAL_ADVICE_WEBHOOK`. | String | --- # Wrong PIN Decline URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-pin-decline This template is triggered when the transaction is declined due to the wrong PIN entry. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "template":"CARD_WRONG_PIN_DECLINE_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_WRONG_PIN_DECLINE_WEBHOOK`. | String | --- # Inactive Decline URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/inactive-decline This template is triggered when the transaction is declined due to an inactive card. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "template":"CARD_INACTIVE_CARD_DECLINE_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_INACTIVE_CARD_DECLINE_WEBHOOK`. | String | --- # Block Decline URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/block-decline This template is triggered when the transaction is declined due to a blocked card. ```JSON URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "template":"CARD_BLOCK_CARD_DECLINE_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_BLOCK_CARD_DECLINE_WEBHOOK`. | String | --- # Card System Down URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-system-down This template is triggered when there's a system malfunction or the system is unavailable at any point during the request-response cycle. Additionally, the same webhook is triggered for a Delegated Model authorization client when there's a malfunction at the client end or a connectivity issue between Nium and a Delegated Model authorization client. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "template":"CARD_SYSTEM_DOWN_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_SYSTEM_DOWN_WEBHOOK`. | String | --- # Expired Card URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/expired-card This template is triggered when the transaction is declined because the card is expired. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "template":"CARD_EXPIRED_CARD_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_EXPIRED_CARD_WEBHOOK`. | String | --- # Card Replacement URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-replacement This event is triggered when a replacement card has been issued. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location 'https:///webhook' \ --header 'content-type: application/json' \ --data '{ "clientHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "cardHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "cardNumber": "4001-35xx-xxxx-1950", "template": "CARD_CARD_REPLACEMENT_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `clientHashId` | Unique client identifier generated and shared upon client creation. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `template` | The value for this field is `CARD_CARD_REPLACEMENT_WEBHOOK`. | String | --- # Miscellaneous URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/miscellaneous This template is triggered when the transaction is declined due to the security and risk policy set by Nium. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name": "John", "transactionCurrency": "SGD", "transactionAmount": "40.00", "cardNumber": "4931-93xx-xxxx-8776", "cardHashId": "eceb4de1-7601-4912-8129-eaa03d88bfb3", "customerHashId": "09dca87a-578e-4d2f-829c-3b6dd9256ece", "walletHashId": "84e50dbe-f5fb-4931-9175-2a136589fb89", "mcc": "5022", "merchantName": "Frankie Tibbs", "merchantCountry": "IN", "merchantCity": "MUMBAI", "template": "CARD_MISC_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `mcc` | This field contains the four-digit merchant category code. | String | | `merchantName` | This field contains the name of a merchant. | String | | `merchantCountry` | This field contains the two-letter [ISO-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) for the merchant country. | String | | `merchantCity` | This field accepts the merchant city. | String | | `template` | The value for this field is `CARD_MISC_WEBHOOK`. | String | --- # PIN Block Decline URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/pin-block-decline This template is triggered when the transaction is declined due to the PIN being blocked as a result of the Customer exceeding incorrect PIN attempts. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "template":"CARD_PIN_BLOCK_DECLINE_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_PIN_BLOCK_DECLINE_WEBHOOK`. | String | --- # Card Unblock Pin URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-unblock-pin This event is triggered when the PIN of a card has been unblocked and can be used in transactions again. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location 'https:///webhook' \ --header 'content-type: application/json' \ --data '{ "name": "John Doe", "brandName": "ABC MERCHANT USA", "cardNumber": "4001-35xx-xxxx-1950", "cardHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "template": "CARD_UNBLOCK_PIN_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ------------------------------------------------------------------------------------ | -------- | | `name` | This field contains the name of a client. | String | | `brandName` | This field contains the brand name of the client's company name. | String | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `template` | The value for this field is `CARD_UNBLOCK_PIN_WEBHOOK`. | String | --- # PIN Retry Exceed Decline URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/pin-retry-exceed-decline This template is triggered when the transaction is declined due to the customer exceeding incorrect PIN attempts. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "template":"CARD_PIN_RETRY_EXCEED_DECLINE_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_PIN_RETRY_EXCEED_DECLINE_WEBHOOK`. | String | --- # PIN Retry Exceed Soft Block URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/pin-retry-exceed-soft-block This template is triggered when a soft block occurs during a POS/ATM transaction after three unsuccessful attempts using the card. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST ' \ -H 'content-type: application/json' \ -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "template":"CARD_PIN_RETRY_EXCEED_SOFT_BLOCK_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_PIN_RETRY_EXCEED_SOFT_BLOCK_WEBHOOK`. | String | --- # Insufficient Funds Declined URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/insufficient-funds-declined This template is triggered when the transaction is declined due to insufficient funds. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Dhruv", "customerHashId":"eb61a0a7-978c-4014-80cf-164f08babae7", "walletHashId":"4f563cb9-56e1-49a9-b70b-0b893f4643ce", "cardHashId":"747b4427-5bab-4deb-bcbb-ad72130adf49", "cardNumber":"4001-35xx-xxxx-9155", "transactionCurrency":"SGD", "transactionAmount":"1000000.00", "transactionDate":"2020-09-29 09:24:46", "balanceCurrency":"SGD", "walletBalance":"776.86", "mcc":"6011", "merchantName":"Frankie Tibbs", "merchantCountry":"IN", "merchantCity":"MUMBAI", "authAmount":"0.00", "authCode":"TR0294153505", "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319, "template":"CARD_INSUFFICIENT_FUNDS_DECLINED_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | The transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `balanceCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `walletBalance` | The available balance in the wallet. | String | | `mcc` | This field contains the four-digit merchant category code. | String | | `merchantName` | This field contains the merchant name. | String | | `merchantCountry` | This field contains the two-letter [ISO merchant country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf). | String | | `merchantCity` | This field contains the merchant city. | String | | `authAmount` | This field contains an authorization amount for the transaction. | String | | `authCode` | The system-generated alphanumeric authorization code for the transaction. | String | | `rhaTransactionId` | This field contains the unique transaction ID for Delegated Model authorization clients. This is empty only for wallet clients. | UUID | | `template` | The value for this field is `CARD_INSUFFICIENT_FUNDS_DECLINED_WEBHOOK`. | String | --- # Insufficient Funds Declined Client URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/insufficient-funds-declined-client This template is triggered when the transaction is declined due to an insufficient client prefund balance. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Dhruv", "customerHashId":"eb61a0a7-978c-4014-80cf-164f08babae7", "walletHashId":"4f563cb9-56e1-49a9-b70b-0b893f4643ce", "cardHashId":"747b4427-5bab-4deb-bcbb-ad72130adf49", "cardNumber":"4001-35xx-xxxx-9155", "transactionCurrency":"SGD", "transactionAmount":"1000000.00", "transactionDate":"2020-09-29 09:24:46", "balanceCurrency":"SGD", "walletBalance":"776.86", "mcc":"6011", "merchantName":"Frankie Tibbs", "merchantCountry":"IN", "merchantCity":"MUMBAI", "authAmount":"0.00", "authCode":"TR0294153505", "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319d2", "template":"CARD_INSUFFICIENT_FUNDS_DECLINED_CLIENT_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | The transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `balanceCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `walletBalance` | This field contains the available balance in the wallet. | String | | `mcc` | This field contains the four-digit merchant category code. | String | | `merchantName` | This field contains the merchant name. | String | | `merchantCountry` | This field contains the two-letter [ISO merchant country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf). | String | | `merchantCity` | This field contains the merchant city. | String | | `authAmount` | This field contains an authorization amount for the transaction. | String | | `authCode` | The system-generated alphanumeric authorization code for the transaction. | String | | `rhaTransactionId` | This field contains the unique transaction ID for Delegated Model authorization clients. This is empty only for wallet clients. | UUID | | `template` | The value for this field is `CARD_INSUFFICIENT_FUNDS_DECLINED_CLIENT_WEBHOOK`. | String | --- # Wrong CVV2 URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-cvv2 This template is triggered when the card has the wrong CVV2. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name": "Samar", "transactionCurrency": "SGD", "transactionAmount": "40.00", "cardNumber": "4931-93xx-xxxx-8776", "cardHashId": "eceb4de1-7601-4912-8129-eaa03d88bfb3", "customerHashId": "09dca87a-578e-4d2f-829c-3b6dd9256ece", "walletHashId": "84e50dbe-f5fb-4931-9175-2a136589fb89", "mcc": "5022", "merchantName": "Frankie Tibbs", "merchantCountry": "IN", "merchantCity": "MUMBAI", "template": "CARD_WRONG_CVV2_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | Unique wallet identifier generated during customer creation. | UUID | | `mcc` | This field contains the four-digit merchant category code. | String | | `merchantName` | This field contains the merchant name. | String | | `merchantCountry` | This field contains the two-letter [ISO-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) for the merchant country. | String | | `merchantCity` | This field contains the merchant city. | String | | `template` | The value for this field is `CARD_WRONG_CVV2_WEBHOOK`. | String | --- # Transaction Limit Exceeds URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-limit-exceeds This template is triggered when the card transaction limit is exceeded. ```JSON URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Dhruv", "customerHashId":"eb61a0a7-978c-4014-80cf-164f08babae7", "walletHashId":"4f563cb9-56e1-49a9-b70b-0b893f4643ce", "cardHashId":"747b4427-5bab-4deb-bcbb-ad72130adf49", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"10.00", "transactionDate":"2020-09-29 09:24:46", "balanceCurrency":"SGD", "walletBalance":"750.86", "mcc":"6011", "merchantName":"Frankie Tibbs", "merchantCountry":"IN", "merchantCity":"MUMBAI", "authAmount":"10.00", "authCode":"TR0808629472", "customMessage":"you have exceeded your cards daily amount limit", "template":"CARD_TRANSACTION_LIMIT_EXCEEDS_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `balanceCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `walletBalance` | The available balance in the wallet. | String | | `mcc` | The four-digit merchant category code. | String | | `merchantName` | This field contains the merchant name. | String | | `merchantCountry` | This field contains the two-letter [ISO-2 merchant country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf). | String | | `merchantCity` | This field contains the merchant city. | String | | `authAmount` | This field contains an authorization amount for the transaction. | String | | `authCode` | This field contains the authorization code of the transaction. | String | | `customMessage` | This field contains the system-generated message with details of the limit exceeded. | String | | `template` | The value for this field is `CARD_TRANSACTION_LIMIT_EXCEEDS_WEBHOOK`. | String | --- # Restricted Transactions URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/restricted-transactions This template is triggered when the card restricts the transactions. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f", "cardHashId":"48534c3a-908c-4bbd-baf2-161402a2c5e0", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"40.00", "merchantName":"Frankie Tibbs", "authCode":"114733", "template":"CARD_RESTRICTED_TRANSACTIONS_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `authCode` | This field contains the authorization code of the transaction. | String | | `template` | The value for this field is `CARD_RESTRICTED_TRANSACTIONS_WEBHOOK`. | String | --- # Wrong Expiry URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/wrong-expiry This template is triggered when the card has a wrong expiry. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name": "Samar", "brandName": "Lia Lau Pay", "cardNumber": "4931-93xx-xxxx-8776", "cardHashId": "eceb4de1-7601-4912-8129-eaa03d88bfb3", "customerHashId": "09dca87a-578e-4d2f-829c-3b6dd9256ece", "walletHashId": "84e50dbe-f5fb-4931-9175-2a136589fb89", "mcc": "5022", "merchantName": "Frankie Tibbs", "merchantCountry": "IN", "merchantCity": "MUMBAI", "template": "CARD_WRONG_EXPIRY_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `brandName` | This field contains the brand name of the client's company name. | String | | `cardNumber` | This field contains the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `mcc` | This field contains the four-digit merchant category code. | String | | `merchantName` | This field contains the merchant name. | String | | `merchantCountry` | This field contains the two-letter [ISO-2 country code](https://nium-documents.s3-eu-west-1.amazonaws.com/spend-documents/Country+Code.pdf) for the merchant country. | String | | `merchantCity` | This field accepts the merchant city. | String | | `template` | The value for this field is `CARD_WRONG_EXPIRY_WEBHOOK`. | String | --- # Transaction Not Supported URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/transaction-not-supported This template is triggered when a transaction is not supported. This template is triggered when a transaction *is not* supported. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "brandName":"ABC Technologies Ltd.", "customerHashId":"eb61a0a7-978c-4014-80cf-164f08babae7", "walletHashId":"4f563cb9-56e1-49a9-b70b-0b893f4643ce", "cardHashId":"747b4427-5bab-4deb-bcbb-ad72130adf49", "cardNumber":"4001-35xx-xxxx-1950", "authCode":"114733", "template":"CARD_TRANSACTION_NOT_SUPPORTED_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ---------------- | ----------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `brandName` | This field contains the brand name of the client's company name. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `cardNumber` | This field contains the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `authCode` | This field contains the authorization code of the transaction. | String | | `template` | The value for this field is `CARD_TRANSACTION_NOT_SUPPORTED_WEBHOOK`. | String | --- # Settlement Debit URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/settlement-debit This template is triggered when a settlement debit occurs. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"18f3046c-17e8-4c8b-9fbd-9508305f37b5", "walletHashId":"6da29616-29f4-4cb2-ba46-24ca7f294bd8", "cardHashId":"00c31858-6a79-4bc2-bde5-5fd633aa20bd", "transactionDate":"2020-11-19 12:05:06", "authCurrency":"SGD", "authAmount":"1.00", "authCode":"417224", "originalAuthCode":"417224", "template":"CARD_SETTLEMENT_DEBIT_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated while new/add-on card issuance. | UUID | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `authCurrency` | This field contains the three-letter [ISO-4217 authorization currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `authAmount` | This field contains an authorization amount for the transaction. | String | | `authCode` | This field contains the authorization code of the transaction. | String | | `originalAuthCode` | This field contains the authorization code of the original transaction. | String | | `template` | The value for this field is `CARD_SETTLEMENT_DEBIT_WEBHOOK`. | String | --- # Settlement Credit URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/settlement-credit This template is triggered when a settlement credit occurs. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"18f3046c-17e8-4c8b-9fbd-9508305f37b5", "walletHashId":"6da29616-29f4-4cb2-ba46-24ca7f294bd8", "cardHashId":"00c31858-6a79-4bc2-bde5-5fd633aa20bd", "transactionDate":"2020-11-19 12:05:06", "authCurrency":"SGD", "authAmount":"1.00", "authCode":"417224", "originalAuthCode":"417224", "template":"CARD_SETTLEMENT_CREDIT_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | The unique client identifier that's generated and shared before API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `transactionDate` | The transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `authCurrency` | This field contains the three-letter [ISO-4217 authorization currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `authAmount` | This field contains the authorization amount for the transaction. | String | | `authCode` | This field contains the authorization code of the transaction. | String | | `originalAuthCode` | This field contains the authorization code of the original transaction. | String | | `template` | The value for this field is `CARD_SETTLEMENT_CREDIT_WEBHOOK`. | String | --- # Settlement Direct Debit URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/settlement-direct-debit This template is triggered when a settlement Direct Debit occurs. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"18f3046c-17e8-4c8b-9fbd-9508305f37b5", "walletHashId":"00c31858-6a79-4bc2-bde5-5fd633aa20bd", "cardHashId":"6da29616-29f4-4cb2-ba46-24ca7f294bd8", "transactionCurrency":"SGD", "transactionAmount":"20.00", "transactionDate":"2020-11-19 12:05:06", "authCurrency":"SGD", "authAmount":"20.00", "effectiveAuthAmount":"21.00", "authCode":"SDD4437220479", "template":"CARD_SETTLEMENT_DIRECT_DEBIT_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | Type | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------ | | `effectiveAuthAmount` | This field contains the authorization amount value in addition to fees such as transaction markup, e-commerce fees, etc. | String | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `authCurrency` | This field contains the three-letter [ISO-4217 authorization currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `authAmount` | This field contains the authorization amount for the transaction. | String | | `authCode` | This field contains the authorization code of the transaction. | String | | `originalAuthCode` | This field contains the authorization code of the original transaction. | String | | `template` | The value for this field is `CARD_SETTLEMENT_DIRECT_DEBIT_WEBHOOK` | String | --- # Settlement Reversal URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/settlement-reversal This template is triggered when a settlement reversal received via a settlement file is processed. ```json URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```shell cURL curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "name":"Samar", "customerHashId":"5eb886da-0baa-4dca-bc02-bc66a4a2a09b" "walletHashId":"1e838976-86db-4666-a271-cb8ddf6d23e8", "cardHashId":"92f1a8da-6951-44d3-8e39-b4b77103c92f", "cardNumber":"4611-35xx-xxxx-8799", "transactionCurrency":"SGD", "transactionAmount":"11", "transactionDate":"2021-04-28 11:56:12", "merchantName":"Starbucks Coffee BRISBANE AU", "balanceCurrency":"SGD", "walletBalance":"982.99", "authCode":"062306SR", "template":"CARD_SETTLEMENT_REVERSAL_WEBHOOK" }' ``` ### Response body | **Field** | **Description** | **Type** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `name` | This field contains the name of a client. | String | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during new/add-on card issuance. | UUID | | `cardNumber` | This is the 16-digit masked card number in the format `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `transactionDate` | This field contains the transaction date and time in the `yyyy-MM-dd HH:mm:ss` Coordinated Universal Time format. | String | | `merchantName` | This field contains the merchant name. | String | | `balanceCurrency` | This field contains the three-letter [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) for the wallet balance. | String | | `walletBalance` | This field contains the available balance in the wallet. | String | | `authCode` | This field contains the unique system-generated alphanumeric authorization code for the transaction. | String | | `template` | The value for this field is `CARD_SETTLEMENT_REVERSAL_WEBHOOK`. | String | --- # Card Expiry Alert URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-expiry-alert This webhook event is triggered when a card is approaching its expiration date. This event is triggered on the following schedule: - 45 days before the card expires - 30 days before the card expires - 15 days before the card expires #### Endpoint ```json URL POST https:///webhook ``` #### Headers | **Field** | **Description** | | -------------- | ------------------------------------------------------------------------------------- | | `Content-Type` | Specifies the media type of the resource; here, `application/json`. | | `x-request-id` | A unique identifier for the request. Example: `123e4567-e89b-12d3-a456-426655440000`. | #### cURL Request Example ```shell curl --location --request POST 'https:///webhook' \ --header 'Content-Type: application/json' \ --header 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ --data-raw '{ "firstName": "John Doe", "cardNumber": "4611-35XX-XXXX-1234", "clientHashId": "d4e1e512-hhd7-4eca-ad41-dd39325facc2", "cardHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "expiryDay": "45", "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "walletHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "template": "CARD_EXPIRY_CARD_WEBHOOK" }' ``` #### Request Body Details | **Field** | **Description** | **Type** | | ---------------- | --------------------------------------------------------------------------------- | -------- | | `firstName` | First name of the card owner. | String | | `cardNumber` | The 16-digit masked card number, in the format `4611-35XX-XXXX-1234`. | String | | `clientHashId` | Unique client identifier generated and shared upon client creation. | UUID | | `cardHashId` | Unique card identifier created during new or add-on card issuance. | UUID | | `expiryDay` | Number of days remaining until the card expires. | String | | `customerHashId` | Unique customer identifier generated and shared at the time of customer creation. | UUID | | `walletHashId` | Unique wallet identifier generated during customer creation. | UUID | | `template` | The value for the Card Expiry Alert event is `CARD_EXPIRY_CARD_WEBHOOK`. | String | --- # Card Details Updated URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/card-details-updated This webhook event is triggered to notify the client or cardholder when any card details are updated. #### Endpoint ```json URL POST https:///webhook ``` #### Headers | **Field** | **Description** | | -------------- | ------------------------------------------------------------------------------------- | | `Content-Type` | Specifies the media type of the resource; here, `application/json`. | | `x-request-id` | A unique identifier for the request. Example: `123e4567-e89b-12d3-a456-426655440000`. | #### cURL Request Example ```shell curl --location --request POST 'https:///webhook' \ --header 'Content-Type: application/json' \ --header 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \ --data-raw '{ "clientHashId": "d4e1e512-hhd7-4eca-ad41-dd39325facc2", "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2", "cardHashId": "a344b0c8-d27d-4db5-8194-aacdefb558ca", "maskedCardNumber": "4611-35XX-XXXX-1234", "email": "testemail2@xyz.com", "countryCode": "SG", "mobile": "64352124", "updatedon": "YYYY-MM-DD HHmmss", "delivery": { "addressLine1": "350 Brettenham Road", "addressLine2": "Walthamstow", "city": "London", "country": "GB", "state": "London", "postCode": "E17 5AU" } }' ``` #### Request Body Details | **Field** | **Description** | **Type** | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `clientHashId` | Unique client identifier generated and shared upon client creation. | UUID | | `customerHashId` | Unique customer identifier generated and shared at the time of customer creation. | UUID | | `cardHashId` | Unique card identifier created during new or add-on card issuance. | UUID | | `maskedCardNumber` | The 16-digit masked card number in the format `4611-35XX-XXXX-1234`. | String | | `email` | The email address associated with the cardholder. | String | | `countryCode` | The two-letter [ISO-3166 country code](https://www.iso.org/iso-3166-country-codes.html). In this example `SG` is used for Singapore. | String | | `mobile` | The mobile phone number associated with the cardholder. | String | | `updatedon` | The date and time when the update was made. Format: `YYYY-MM-DD HHmmss`. | String | | `delivery` | An object containing the address details of where the physical card was delivered. | Object | | `addressLine1` | The first address line of the cardholder. | String | | `addressLine2` | The second address line of the cardholder. | String | | `city` | The city of the cardholder's address. | String | | `country` | Country of the address, here`GB` is used for Great Britain. | String | | `state` | State or region of the cardholder's address. | String | | `postCode` | Postal code of the cardholder's address. | String | --- # 3DS One-Time-Password URL: https://docs.nium.com/docs/developers/notifications-and-webhooks/issuing-and-card-events/3ds-one-time-password This template is triggered when a 3DS-enabled transaction is initiated. ```URL https:///webhook ``` ### Header | **Field** | **Description** | | -------------- | ---------------- | | `Content-Type` | application/json | ### Request example ```curl curl --location --request POST 'https:///webhook' \ -H 'content-type: application/json' \ -d '{ "referenceCode": "DWP", "otp":"112233", "clientHashId":"0498f10f-1968-494f-9f7a-454ed23942a0", "customerHashId":"2e096369-d93d-424b-93b8-1e7e14399b44", "cardHashId":"04390049-f005-4909-a307-9db59ca6e207", "cardNumber":"4001-35xx-xxxx-1950", "transactionCurrency":"SGD", "transactionAmount":"10.00", "merchantName":"Frankie Tibbs", "template":"CARD_3DS_OTP_WEBHOOK" }' ``` ### Request body | **Field** | **Description** | **Type** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `referenceCode` | This is a unique value generated with each new OTP value . In the instance where the consumer can receive multiple OTPs for the same transaction, this field can be leveraged to show the consumer which specific OTP is expected to be entered. This value should be sent in the SMS or Email along with the OTP and then displayed on the consumer screen. | String | | `otp` | This is the 3DS OTP (one time password) for the transaction. | String | | `clientHashId` | The unique client identifier that's generated and shared before the API handshake. | UUID | | `customerHashId` | The unique customer identifier that's generated on customer creation. | UUID | | `walletHashId` | The unique wallet identifier that's generated simultaneously with customer creation. | UUID | | `cardHashId` | The unique card identifier that's generated during the new/add-on card issuance. | UUID | | `cardNumber` | This field contains the 16-digit masked card number in the `1234-56xx-xxxx-3456` format. | String | | `transactionCurrency` | This field contains the three-letter [ISO-4217 transaction currency code](https://www.iso.org/iso-4217-currency-codes.html). | String | | `transactionAmount` | This field contains the transaction amount. | String | | `merchantName` | This field contains the merchant name. | String | | `template` | The value for this field is `CARD_3DS_OTP_WEBHOOK`. | String | --- # Frequently Asked Questions URL: https://docs.nium.com/docs/developers/faqs The following articles address the most common inquiries developers and businesses have while integrating and getting started with Nium. These articles aim to save you time by providing concise, clear answers to technical, operational, and support-related questions. Whether you are implementing our APIs, exploring our platform's architecture, preparing for production, or ensuring compliance with privacy and security standards, you will find essential information organized across the following categories: - [Implementation](/docs/developers/faqs/implementation): Focuses on how to integrate Nium solutions efficiently, including API sandbox testing, wallet functionality, and card activation workflows. - [Platform](/docs/developers/faqs/platform): Covers Nium's infrastructure, performance reliability, and multi-tenant architecture to ensure seamless operation at scale. - [Production](/docs/developers/faqs/production): Provides details about release management, high availability, and disaster recovery processes. - [Privacy and Security](/docs/developers/faqs/privacy-and-security): Outlines Nium's approach to data encryption, penetration testing, and compliance with international data privacy regulations. - [Nium Support](/docs/developers/faqs/support): Explains how to get help with critical issues, developer queries, and ongoing support. - [Regex and Accepted Values](/docs/developers/faqs/regex-and-accepted-values): Describes the regular expressions (regex) Nium uses to validate inputs and ensure consistent data submission throughout our platform and APIs. If you are new to Nium, we recommend beginning with [Getting Started](/docs/01-Getting%20Started/index.mdx) to familiarize yourself with our platform. Otherwise, explore the specific FAQs below to get the answers you need. If you have any questions, please don't hesitate to contact your Nium account manager, or [Nium support](mailto:support@nium.com). --- # Implementation URL: https://docs.nium.com/docs/developers/faqs/implementation Implementation ## Implementation How does your platform ensure that implementation/agency partners can efficiently delivery digital experiences without excessive development effort and time? Agency needs to consume the published APIs. In addition, if there is a need, we can do working sessions with developers to speed up the integration. How does client differ from customer? A client can be any service provider which provides a service to customers. A customer is someone who buys a service from a client. Can customer details be the business details? Yes, customer details can be the business details. Is there a testing environment for the API? Yes, there are sandbox environments, detailed in the API docs. ## Wallet Does wallet represent the client funds? Yes, the wallet represents client funds. Is one card equal to the one wallet? No, a single wallet can have multiple cards. How does balance transfer and different currencies work within wallet? Hierarchy is: client > customer > wallet > card. A wallet can store multiple currency balances. Balance transfer works for moving balance from one currency to another currency within the same wallet. ## Card How is card activation usually done? In theory, it can happen anytime. *Virtual cards* are already `VIRTUAL_ACTIVE` and can be used for e-commerce transactions immediately. No activation needed. Physical cards can be activated instantly, but customers are strongly encouraged to activate after cards are delivered. How do customers know their PIN in the first place? Each client needs to use the [Set/Reset PIN​](/api#tag/security/POST/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/card/{cardHashId}/pin) to help customers set their PIN. What is required to be live with virtual cards? Currently, virtual cards can go live. Do virtual cards need to be activated? **No, virtual cards are `VIRTUAL_ACTIVE` when issued and should not be activated again.** Our wallet supports multiple currencies. If one currency runs short, then the base currency will be used to clear the transaction. --- # Platform URL: https://docs.nium.com/docs/developers/faqs/platform Is your platform delivery architecture true multi-tenant SaaS? Yes, it is multi tenant architecture, we have a single DB and auto-scalable middleware stack. Are platform releases and updates instantly available to all customers? Yes, they are instantly available to all customers. Are new integrations with 3rd-party platforms or services instantly available to all customers? Yes, they are instantly available to all customers. How does the platform enable consistent performance and reliability through its architecture? Completely in-cloud, auto-scaling, built-in, RDS managed by Cloud provider. All of them are deployed in Multi-AZ (Availability Zone), so completely reliable. How does your platform architecture support rapid content delivery around the world? Not applicable. We are a completely API-based solution. For any UI we use Cloudfront of AWS. What is your hosting strategy? In multiple data-centers and geographies? We are hosted in AWS with backup which is hosted in another region. What technical skills are required of users of your platform? API response is in JSON, can be consumed in any technology, it is language independent. How do you monitor the platform and its performance? We use Nagios XI and log server for monitoring. Which certifications has your platform attained and maintains? We are PCI DSS certified and we perform quarterly PCI audits. What protections are in place to battle vulnerabilities to data theft? We are using AWS API GW, which provides coverage to major threats, such as injection, cross-site scripting, buffer manipulation (heartbleed SSL), phishing, man-in-the-middle, distributed denial of service (DDoS), etc. In addition, we use AWS EC2, so any vulnerability released by AWS will be continuously patched as communicated. --- # Production URL: https://docs.nium.com/docs/developers/faqs/production Production ## Production What software or runtime licenses are required to run your software in a production environment? We are a SaaS-based offering. So, no license required to consume the services. How is product documentation accessed? The product documentation is available in developer.nium.com/spend/index.html. What is your release management process, frequency, and method of communication? Average release cycle is one month, but all our changes are backward-compatible. We provide a [Changelog](/changelog) highlighting the changes done during the release on our website. Any non-backwards-compatible change will go into a major version which can be consumed by clients at their own liberty. ## High-Availability How do you support disaster recovery? We are using container service of AWS. Both our servers and databases are deployed in Multi-AZ (Availability Zone) which makes it highly available. How do you support high availability. Are there extra charges? We are using container service of AWS. Both our servers and databases are deployed in multi-AZ. How do upgrades work to limit the risk of changes to your customers? For major changes, we will upgrade the version in the URL. For minor changes, it will be backwards-compatible. --- # Privacy and Security URL: https://docs.nium.com/docs/developers/faqs/privacy-and-security Do you provide independent 3rd-party penetration testing? May we perform our own independent 3rd-party penetration tests? Yes, as a part of PCI audit, we did the penetration testing. Yes, you can perform penetration testing by requesting specific permission from us. How do you set up environments to comply with various international data privacy regulations? Card data environment is completely secured and has been validated by PCI DSS audit. How do you support independent data archiving over multi-year retention periods? Currently data will be stored in RDS.\ Once we reach archival stage, data will be archived and stored in S3 bucket. Do you support the encryption of data-at-rest? What are the costs involved? All the data is encrypted at rest. No extra cost involved. We are completely abiding by PCI encryption mandate. --- # Nium Support URL: https://docs.nium.com/docs/developers/faqs/support How do you support your customers during a critical failure of the service? It is documented in the Master service level agreement. Do you provide developer support with API guides, routine issue resolution, help with complex issues, etc.? Please reach out to and we will respond to you as soon as possible. --- # Regex and Accepted Values URL: https://docs.nium.com/docs/developers/faqs/regex-and-accepted-values This article breaks down the regular expressions (or regex for short) Nium uses to validate characters submitted through Nium Portal and our API. This article breaks down the regular expressions (or *regex* for short) Nium uses to validate characters submitted through Nium Portal and our API. > What is regex? Regex or *regular expressions* are patterns used to match a specific set of characters and symbols in strings of text or code. Nium uses regex to define which characters our web app () and our API accept. Defining what characters and data can be submitted helps ensure only accurate information gets passed through and no issues come up when moving funds. For example, Nium uses regex to make sure special symbols like `$` are not passed in fields like postal code or region. For more information about regex, see the following [developer guide from Mozilla](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions). > What does ^\[a-zA-Z0-9\_.,-\s] mean in the API reference? `^[a-zA-Z0-9_.,-\s]` is one of the stricter examples of a regex statement Nium uses to define what characters are accepted by Nium Portal and our API. When broken down, each set of characters in the above regex statement details and defines what characters are accepted by Nium's API: ` ^[a-zA-Z0-9_.,-\s]` | Characters | Description | Regex | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | | Caret (^) symbol | The caret symbol (^) defines when the character validation statement begins; right at the very beginning of the submitted input. In other words, the caret (^) is the character used to begin a regex statement. You can ignore this character when considering what characters can be accepted by Nium's API. | `^` | | Lowercase characters - a-z | This portion of the regex statement defines what case of characters (lowercase v. uppercase) are accepted by Nium's API. This statement defines the set of characters we consider valid in the submitted input. More specifically, it states that lowercase characters (`a`,`b`,`c`,`d`...) are accepted by Nium's API. | `[a-z` | | Uppercase characters - A-Z | This portion of the regex statement defines what case of characters (lowercase v. uppercase) are accepted by Nium's API. This statement defines the set of characters we consider valid in the submitted input. More specifically, it states that uppercase characters (`A`,`B`,`C`,`D`...) are accepted by Nium's API. | `A-Z` | | Numerical characters - 0-9 | This portion of the regex statement defines what numbers are accepted by Nium's API. This statement defines the set of numerical characters we consider valid in the submitted input. More specifically, it states that numbers (`0`,`1`,`2`,`3`...) are accepted by Nium's API. | `0-9` | | Underscore - \_ | This portion of the regex statement enables the underscore character (`_`) to be accepted by Nium's API. | `_` | | Period - . | This portion of the regex statement enables the period character (`.`) to be accepted by Nium's API. | `,` | | Comma - , | This portion of the regex statement enables the comma character (`,`) to be accepted by Nium's API. | `-` | | Blank spaces - ` ` | This portion of the regex statement enables the blank spaces (` `) to be accepted by Nium's API. | `\s]` | --- # Nium Embed URL: https://docs.nium.com/docs/sdks --- # API Reference — OpenAPI Specification URL: https://docs.nium.com/oas/nium.yaml Machine-readable OpenAPI 3 specification for all Nium APIs. Fetch the YAML to enumerate all endpoints, parameters, and schemas. --- # July 07, 2026 URL: https://docs.nium.com/changelog/july-07-2026 ### Originating FI Screening Added support for multi-party payment flows, letting you route payouts through up to 6 originating financial institutions (OFIs) in a single request. originating\_parties — include your chain of originating parties when submitting a payout; first-time parties undergo a short compliance review, then auto-clear for 12 months Requires enablement by your Nium account manager. GA rollout June 2026. For more information, see [OFI Screening Guide](/docs/payouts/transfer-money/ofi-screening-guide). ### Payout Schema API Added new API that lets you programmatically fetch field requirements, validation rules, and purpose codes for any payout corridor before submitting a transaction - eliminating rejected payouts caused by missing or malformed data. No changes required to existing integrations. [Payout Schema API](/api#tag/payout/GET/api/v1/client/{clientHashId}/customer/{customerHashId}/currency/{currencyCode}/payout/schema) can be queried by `destinationCountry`, `currency`, `payoutMethod` Available now for all clients. For more information, see [Payout Validation Schema](/docs/payouts/transfer-money/payout-validation-schema). ### V5 Simulate Customer Onboarding Status We've introduced simulation support for V5 Customer Onboarding, enabling users to drive compliance state transitions using action-based controls — submit\_kyc, raise\_rfi, clear, and reject — across both individual and corporate customer types. This release aligns simulation capabilities with the V5 data model, where customer lifecycle state is tracked through a combined status and subStatus pair for finer-grained control when testing compliance flows. For more information, see [Simulate Customer Onboarding Status (V5)](/api#tag/customer/POST/api/v5/simulations/onboard/{customerHashId}/transition). There are no changes at this time. There are no changes at this time. --- # April 17, 2026 URL: https://docs.nium.com/changelog/april-17-2026 ### V5 Customer Onboarding APIs We’ve launched V5 of our [Customer Onboarding APIs](/api#tag/customer-onboarding-v5) to simplify and accelerate global customer onboarding. This release introduces a unified onboarding API across customer types, enhanced file upload capabilities, stronger upfront validations to reduce RFIs, and a standardized data model for a more consistent experience. With clearer status tracking and built-in compliance workflows through [KYC Pre-built Form](/docs/developers/pre-built-forms/kyc-form), V5 reduces integration effort and enables faster go-live. V5 is now live across 9 regions: [EU](/docs/onboarding/customer-onboarding/eu-onboarding), [UK](/docs/onboarding/customer-onboarding/uk-onboarding), [NL](/docs/onboarding/customer-onboarding/nl-onboarding), [SG](/docs/onboarding/customer-onboarding/sg-onboarding), [AU](/docs/onboarding/customer-onboarding/au-onboarding), [US](/docs/onboarding/customer-onboarding/us-onboarding), [CA](/docs/onboarding/customer-onboarding/ca-onboarding), [JP](/docs/onboarding/customer-onboarding/jp-onboarding), and [HK](/docs/onboarding/customer-onboarding/hk-onboarding). For more information, see [V5 Customer Onboarding APIs](/docs/onboarding/customer-onboarding) ### Async Account Statement Generation Nium has revamped the account statement experience with asynchronous report generation. Clients can now request a statement using the new [Initiate report generation](/api#tag/reports/POST/api/v1/client/{clientHashId}/report) request, and receive a [Report Generation Status](/docs/developers/notifications-and-webhooks/platform-events) webhook once the report is ready. Upon a `COMPLETED` status, download the statement using the [Download report](/api#tag/reports/GET/api/v1/client/{clientHashId}/report/{reportRequestId}/download) request. Alternatively, statements can be pushed directly to your SFTP server — supporting password-based, SSH key-based, and SSH key + password-based authentication. The new statement APIs are part of the **Reports** section, a unified API set built to support multiple report types with a single integration. For more information, see [Customer Account Statement](/docs/reports/customer-account-statements). There are no changes at this time. There are no changes at this time. --- # March 3, 2026 URL: https://docs.nium.com/changelog/march-03-2026 Local Funding Available in Mexico and Colombia Local funding is now supported in Mexico (MXN) and Colombia (COP). You can create virtual accounts to receive funds locally in these corridors, enabling faster settlement and simplified reconciliation for incoming payments. For more information, see Virtual Accounts. There are no changes at this time. Nium Verify: Name Match for all Corridors Name match verification is now available for all corridors. The verification response includes a nameMatch field indicating if the account holder's name matches your records. The nameMatch field returns one of three values: match, partial\_match, or no\_match, alongside the name registered at the bank in derivedAccountDetails.name. For more information, see Nium Verify. Nium Verify: Pakistan Bank Code Support Pakistan (PKR) verification requests now accept a bank code as an alternative routing identifier. Pass the four-character bank identifier in the bank.bankCode field (for example, HABB for Habib Bank Limited) when a full SWIFT code is not available. For more information, see Required Fields. --- # December 23, 2025 URL: https://docs.nium.com/changelog/december-23-2025 Pre-built Forms Introduced Pre-built Forms, a ready-to-use experience that lets you collect required information from customers during onboarding and transaction-related compliance reviews—without building or maintaining your own forms. Pre-built Forms help you manage RFIs consistently across the customer lifecycle, reduce time to go live, and integrate seamlessly into your existing flows—whether used for customer onboarding or transaction compliance. For more information, see Pre-built Forms. There are no changes at this time. Payout Validator Introduced the Payout Validator, a new capability that lets you validate payouts before debiting funds or creating a transaction. The Payout Validator checks payout requests against Nium’s payout requirements and corridor rules—surfacing issues such as missing fields, invalid formats, or unsupported configurations upfront. This helps prevent failed payouts, reduce reversals, and give customers clear feedback before submission. For more information, see Payout Validator. --- # October 14, 2025 URL: https://docs.nium.com/changelog/october-14-2025 Updates There are no changes at this time. Updates There are no changes at this time. New Failure Code We’ve added a new failure code, RC07. This code appears when the routing code—or the combination of the beneficiary account number and routing code—is invalid. For more information, see Failure Codes. Verification of Payee (EU) Starting October 9, 2025, all EUR Local payouts from EU-based clients will be subject to Verification of Payee (VoP) checks in line with EU regulations. These checks confirm that the beneficiary name matches the account details before the payout is processed. Transactions with name mismatches will be automatically rejected. For more details, see Verification of Payee. Expanded Nium Verify Coverage: Europe We’ve expanded Nium Verify coverage across 19 European countries through the new EU Verification of Payee (VoP) framework. This enhancement provides deeper account-name matching and compliance-grade verification for all EUR Local payouts. 19 new markets added in Europe via VoP integration Direct connections to participating banks through the EPC network Real-time account name verification before initiating a payout Standardized responses (verified, not\_verified, not\_supported) across all EU markets Newly supported markets Austria, Belgium, Croatia, Cyprus, Denmark, Estonia, Finland, France, Germany, Greece, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Poland, Portugal, Slovenia, Slovakia, Spain Available now for all EUR Local corridors. --- # September 30, 2025 URL: https://docs.nium.com/changelog/september-30-2025 There are no changes at this time. There are no changes at this time. Verification of Payee (EU) Starting October 9, 2025, all EUR Local payouts from EU-based clients will be subject to Verification of Payee (VoP) checks in line with EU regulations. These checks confirm that the beneficiary name matches the account details before the payout is processed. Transactions with name mismatches will be automatically rejected. For more details, see Verification of Payee. --- # September 16, 2025 URL: https://docs.nium.com/changelog/september-16-2025 Core Platform ## Core Platform ### Introducing Live-Authorization for EU Applications Live-authorization is a digital alternative to paper-based Power of Attorney (POA) verification. - For EU applications, any applicant who is not a director must provide a POA signed by a director. If the director is based outside the EEA, this POA must be verified by an apostille. - Live-authorization is completely digital, requires no apostilization, and requires no manual review, accelerating the verification process. Live-authorization is currently available for EU applications and will be expanded to other regions soon.\ For more information, see [Letter of Authorization](/docs/onboarding/corporate-customers/letter-of-authorization). ### Onboarding Guide Changes We have upgraded our onboarding guides for the US region to include the following: - Addition of optional documents such as Proof of Business and Ownership Chart to improve approval TATs. A [Template for Ownership Chart](/docs/onboarding/corporate-customers/eu-onboarding/required-documents) has been added. - Improved guidance on key topics such as: - How to add positions - Expected documents for Proof of Business / Source of Wealth - New optional fields such as `expectedAccountUsage` and `natureOfBusiness` to avoid RFIs For more information, see [Onboarding](/docs/onboarding). ## Issuance and Cards There are no changes for this time period. ## Payouts and Payins ### Schema Preview (Beta) Nium has introduced a new beta feature for the `GetValidationSchema` request. Subscribed customers can now preview upcoming changes to the Beneficiary Schema before they go live. This early access allows teams to update beneficiary data in advance, ensuring a smooth transition when the changes are officially released. For more information, contact [Schema Preview (Beta)](/docs/payouts/beneficiaries/schema-preview). ### Upcoming Regulatory Change: Verification of Payee (VoP) Starting **October 9, 2025**, all **EUR Local** payouts from **EU-based** clients will be subject to **Verification of Payee (VoP)** checks, in line with EU regulations. Any payout with a name mismatch will be automatically rejected.\ For more information, see [Verification of Payee](/docs/onboarding/vop-guidelines). --- # August 5, 2025 URL: https://docs.nium.com/changelog/august-5-2025 Core Platform ## Core Platform There are no changes for this time period. ## Issuance and Cards There are no changes for this time period. ## Payouts and Payins ### New Feature #### Know When Funds Will Arrive — Estimated Delivery Time Clients can now view the expected delivery time of payouts at the moment a transaction is initiated. This information is shared via the `estimatedDeliveryTime` field in the `REMIT_TRANSACTION_SENT_TO_BANK` webhook. The timestamp reflects when the funds are expected to reach the beneficiary, based on real-time routing data, partner cutoffs, and local holidays. For more information, see [Estimated Delivery Time](/docs/payouts/transfer-money/estimated-delivery-time). ### Upcoming Regulatory Change Effective **October 9, 2025**, all **EUR Local** payouts from **EU-based** clients will undergo **Verification of Payee (VoP)** checks per EU regulation. Payouts with name mismatches will be rejected by default. See the [Verification of Payee](/docs/onboarding/vop-guidelines) guide for integration details and configuration steps. --- # July 22, 2025 URL: https://docs.nium.com/changelog/July-22-2025 Core Platform Enhancements Tags added to Webhooks We've now added tags to the following webhooks. This change will help you manage webhooks more efficiently. Client KYB Status Customer Registration Issuance and Cards There are no changes for this time period. Payouts and Payins There are no changes for this time period. --- # July 8, 2025 URL: https://docs.nium.com/changelog/July-8-2025 Core Platform Enhancements More details for Fee\_Debit transactions We’ve updated Fee\_Debit transaction labels to give customers more context about the fees charged: feeName — Shows which predefined fee applies to the transaction. tierType — Indicates whether the fee is based on tier rules or non-tier rules, per the updated Fee Details v3 request. condition — Lists the conditions under which the fee is charged (for example, source\_currency, destination\_currency, destination\_country). Nium’s pricing engine now supports more customization options, including fees based on payout and payin methods and tiered pricing. To view pricing with these options, use the Fee Details v3 request. New Features E\_DOC\_VERIFY for UBOs and Directors in the EU, UK, and SG We’ve expanded the E\_DOC\_VERIFY KYC method to: UBOs and Directors in the EU and UK. Both E\_KYC and E\_DOC\_VERIFY in SG. This reduces the need for notarized documents in the EU and speeds up the KYC process. For implementation details, see Onboarding Response – 200 to generate a redirectURL for stakeholders in these regions. No expiry for redirectURL in Corporate Onboarding redirectURL links for Corporate Onboarding no longer expire, unless the customer starts but does not complete the KYC flow in a single uninterrupted session. If the session times out, customers can restart the process using the same link or by refreshing their browser. As a result, the Regenerate KYC URL API will be deprecated (currently still supported with a dummy expiry for existing integrations). Standardized Letter of Authorization The Letter of Authorization (Power of Attorney) is now standardized across all Nium regions. You can direct customers to the updated template. Issuance and Cards There are no changes for this time period. Payouts and Payins There are no changes for this time period. --- # June 24, 2025 URL: https://docs.nium.com/changelog/june-24-2025 Core Platform ## Core Platform ### Enhancements #### Enhanced Pricing Engine Nium has enhanced its pricing engine, providing a variety of customizable pricing options such as pricing via different payout and payin methods, tiered pricing, and more. To view pricing based on advanced options, fetch the pricing details using the [Fee Details V3](/api#tag/client-settings/GET/api/v3/client/{clientHashId}/fees) request. ## Issuance and Cards There are no changes for this time period. ## Payouts and Payins There are no changes for this time period. --- # June 10, 2025 URL: https://docs.nium.com/changelog/june-10-2025 Core Platform New Features Enhanced Account Verification for Payouts Reduce failed transfers and improve payout success with Nium’s built-in bank verification. Before sending funds, confirm the recipient’s account details in real time—no test deposits or manual checks required. This helps you catch errors early, improve customer experience, and avoid unnecessary fees. For more information, see Nium Verify. Issuance and Cards There are no changes for this time period. Payouts and Payins There are no changes for this time period. --- # May 27, 2025 URL: https://docs.nium.com/changelog/may-27-2025 Core Platform ## Core Platform ### New Features #### Local Funding now available in Brazil We have introduced Local Funding in Brazil for corporate customers, reducing costs and improving transaction speed. As part of our banking partner requirements, we must collect a Brazilian `taxId` or CNPJ (Cadastro Nacional da Pessoa Jurídica) account number for these customers. See [Fund a Wallet – Brazil](/docs/payins/fund-wallet#brazil) for more information. ## Issuance and Cards There are no changes for this time period. ## Payouts and Payins ### Enhancements #### Early Warning Services (EWS) We're excited to announce a powerful enhancement to Nium Verify—a new integration leveraging Early Warning Services (EWS) to deliver real-time, high-accuracy US bank account verification. - **Expanded Coverage in the US**: Benefit from broader bank coverage with industry-grade EWS data, addressing gaps left by traditional credit bureau-based verification. - **Improved Accuracy**: Significantly reduce verification failures and false negatives. Expect fewer `bank_not_supported` and `not_verified` responses. - **Name Match Insights**: Gain added payment confidence with `nameMatch` results: - `match` - `partial_match` - `no_match` *Available only for US accounts.* --- # May 13, 2025 URL: https://docs.nium.com/changelog/may-13-2025 Core Platform New Features Get Fee Details V3 Introducing a new request — Get Fee Details V3. This new version provides more details on the pricing structure. For more information, see Fees. Validate the beneficiary schema to all Payouts Clients can confirm the validity of the payment object before debiting funds. This change improves user experience and reduces operational overhead. Financial Institution customers can now validate payment objects upfront before debiting funds, helping to reduce errors and operational overhead. Ongoing Due Diligence Nium will start the ODD (Ongoing Due Diligence) process for corporate customers approved more than a year ago. ODD is a periodic review process that active customers must undergo based on their risk profile and transaction activity. Our compliance officer will raise any required RFIs. You are expected to respond to RFIs in a timely manner to help us complete ODD. Failure to respond may result in the suspension of the account. You can subscribe to CUSTOMER\_ODD\_STATUS\_WEBHOOK to track the status and progress of ODD. See ODD Status for additional details. Issuance and Cards There are no changes for this time period. Payouts and Payins There are no changes for this time period. --- # April 29, 2025 URL: https://docs.nium.com/changelog/april-29-2025 Core Platform There are no changes for this time period. Issuance and Cards There are no changes for this time period. Payouts and Payins New Features Local Funding Now Available in Brazilian Real You can now fund in Brazilian Real (BRL) locally through Nium using Brazil’s most widely used payment systems: PIX (Instant Payment Platform) and TED (Electronic Funds Transfer). This update helps clients with a presence in Brazil move money faster and reduce cross-border friction. For more information, see Fund a Wallet. --- # April 15, 2025 URL: https://docs.nium.com/changelog/april-15-2025 Core Platform New Features Settlement Report Now Available We’ve launched a daily Settlement Report to support your reconciliation efforts. The report includes all settled transactions across payins, payouts, P2P transfers, and fees. You can download the report via the Nium Portal or receive it securely via SFTP. For more information, see Settlement Report. Enhancements Find Transactions Faster with Improved Filters We’ve enhanced the Transactions page in Nium Portal to help you locate the data you need—faster: Search by External ID View transactions across all platform customers Filter by date and time with access to full transaction history For more information, see [Nium Portal](/docs/nium-portal/reports#transactions-reports). Issuance and Cards There are no changes for this time period. Payouts and Payins There are no changes for this time period. --- # April 13, 2025 URL: https://docs.nium.com/changelog/april-13-2025 Core Platform New Features Updated Beneficiary Validations We’ve updated the validation rules for creating beneficiaries to align with those used for creating payouts. This update helps reduce rejections caused by typos or special characters. For more information, see Add Beneficiary V2. Ongoing Due Diligence (ODD) Corporate customers approved more than one year ago are now subject to Ongoing Due Diligence (ODD)—a periodic review based on their risk profile and transaction history. During this review, a compliance officer may issue one or more Requests for Information (RFIs). Prompt responses are required to complete the review. Failure to respond may result in temporary account suspension. For more details, see Corporate Customers. Issuance and Cards There are no changes for this time period. Payouts and Payins There are no changes for this time period. --- # April 1, 2025 URL: https://docs.nium.com/changelog/april-1-2025 Core Platform Enhancements clientTransactionId now included in reconciliation labels clientTransactionId is now included as a label in the following transaction types: Wallet\_Credit\_Mode\_Offline Wallet\_Credit\_Mode\_Offline\_Third\_Party clientTransactionId is provided by clients in the Fund Wallet request and helps you keep track of transactions for reconciliation purposes. For more information, see Transaction Response Labels. Issuance and Cards New Features Convert virtual cards to physical cards Empower your customers with more choice. With the new Convert Card request, you can upgrade an active virtual card to a physical one. This helps you support fast virtual issuance while still meeting customer demand for in-store or ATM access. For more information, see Manage Cards. New Flutter SDK guides for Apple Pay and Google Pay Now it’s easier than ever to integrate digital wallet provisioning into your Flutter apps. Our new guides walk you through implementing Apple Pay and Google Pay Push Provisioning using Nium’s SDKs—complete with platform channel setup, native code examples, and troubleshooting tips. Whether you're building for iOS or Android, you can get cards into wallets faster and streamline the in-app payment experience. For more information, see: Apple Pay - Flutter SDK Google Pay - Flutter SDK Payouts and Payins Enhancements Improved bank account verification with Nium Verify We’ve made it easier to integrate and more informative to use. Recent upgrades to Nium Verify improve visibility, clarity, and developer experience. Simplified integration: You no longer need to pass the customerId in your requests—less setup, fewer steps. Track verification history: Use the new List Verifications request to fetch all verifications sent to Nium. More detailed results: We’ve refined our response data to help you act with confidence: For valid accounts: A new derivedAccountDetails object includes the account holder’s name from bank records—and, where applicable, the name in the local language. For invalid accounts: A new failureCode explains why verification failed (e.g. incorrect name or inactive account). For unsupported accounts: Responses now include more specific reasons—such as unsupported banks or currency-country mismatches. These changes help you deliver a smoother onboarding experience and reduce verification delays. Learn more in the updated Nium Verify. --- # March 18, 2025 URL: https://docs.nium.com/changelog/march-18-2025 Core Platform Enhancements New rfiHashId for Easier RFI Tracking A new parameter, rfiHashId, is now available in the following requests: Fetch Corporate Customer RFI Details​ Respond to RFI for Corporate Customer You can now store and use an rfiHashId to uniquely identify and respond to Requests for Information (RFIs), helping ensure accurate tracking and preventing mix-ups. While templateId remains available, we strongly recommend migrating to rfiHashId for improved accuracy and future compatibility. For more details, see Requests for Information (RFIs). If you have any questions, please contact your Nium account manager or Nium Support. Issuance and Cards There are no changes for this time period. Payouts and Payins New features Nium Playbook Changelog We’ve launched a changelog for the Nium Playbook, making it easier to track updates to our transaction capabilities all in one place. Explore the changelog and stay up to date: Nium Playbook Failure Codes Guide We’ve published a new Failure Codes guide outlining why transactions may fail and the standardized ISO codes that are returned. These codes helps you by providing a: Simplified integration: Standardized failure codes reduce the need to interpret multiple financial messages. Faster resolution: Recommended actions are provided for each failure, helping you quickly identify and resolve issues. --- # March 4, 2025 URL: https://docs.nium.com/changelog/march-4-2025 Core Platform Enhancements Updates to Virtual Account Assignment Virtual accounts can now only be assigned when a customer’s compliance status is CLEAR. If the status is PENDING, the request will return an error. This change helps ensure virtual accounts are only assigned to valid customers. For more information, see Virtual Account Number. Use the Assign Payment ID request to assign virtual accounts. This change ensures virtual accounts are only assigned to eligible customers. Issuance and Cards There are no changes for this time period. Payouts and Payins There are no changes for this time period. --- # February 18, 2025 URL: https://docs.nium.com/changelog/february-18-2025 Core Platform Enhancements Wallet to Wallet Transfers Now Support External ID You can now include a senderExternalId in wallet-to-wallet transfer requests. Additionally, you can fetch wallet-to-wallet transfers using the externalId assigned when creating the customer. This enhancement simplifies transaction tracking and reconciliation. For more information, see Wallet to Wallet Transfer. Issuance and Cards There are no changes for this time period. Payouts and Payins New Features Fetch Transaction Lifecycles with External ID You can now fetch the lifecycle of a transaction and status changes it goes through using the externalID from our Transfer Money request. This change helps make transaction tracking and reconciliation even simpler. Search using your External IDs: Retrieve the lifecycle of a transaction using externalID as a parameter. Easier Reconciliation: Track transactions using your own reference IDs. No Breaking Changes: You can still fetch the lifecycle of transactions using the systemReferenceNumber. For more information, see Transaction Lifecycle. --- # February 4, 2025 URL: https://docs.nium.com/changelog/february-4-2025 Core Platform Deprecation Notices P2P Transfer Between Wallets Webhook Deprecation The P2P Transfer Between Wallets webhook event will be deprecated in March 2025. This event was sent for transfers that have Customer\_Wallet\_Credit\_Fund\_Transfer as the transactionType. The Fund Transfer Between Wallets event will be sent instead for transfers that have Customer\_Wallet\_Credit\_Fund\_Transfer as the transactionType. Issuance and Cards Enhancements New childCustomerHashId Field in Assign Card Request The Assign Card request now includes a childCustomerHashId field. This change helps you keep track of customers under a corporate client account and their activity for accurate record-keeping and oversight. Payouts and Payins New Features Send Payments and Add Beneficiaries in One Step We’ve made it easier to send payments through Nium! Previously, creating a beneficiary using our Beneficiary endpoint was required before initiating a transfer. With this latest change, you now have the flexibility to send payments without pre-creating a beneficiary. Specifically, customers can now send payments using the Transfer Money request by either: Including beneficiary details directly within the request, along with the account details. Including a beneficiaryId (similar to today’s behavior). This update simplifies payment processing and offers greater flexibility. See the Transfer Money guide. Start creating beneficiaries and payments today for a smoother payout experience! 🚀 Enhancements Faster Transaction Processing with Document Upload We’ve enhanced our Upload Transaction Receipt request to streamline payment processing and minimize delays caused by RFIs. Customers can now upload supporting documentation linked to a payment, allowing us to process transactions faster. Specifically, after using the Transfer Money request to initiate a transaction, retrieve the system reference number from the response. Then use the Upload Transaction Receipt request to upload documentation; include the system reference number as the transactionId in the path parameter. For more information, see the following requests: Transfer Money Upload Transaction Receipt --- # December 10, 2024 URL: https://docs.nium.com/changelog/december-10-2024 Core Platform Nium Portal New Features Nium Portal In-line Payouts In-line Payouts enables any user to create payouts directly in Nium Portal—no coding or integrations needed. Select a beneficiary, set payout details, and you're done! For more information, see Payouts. API Breaking Changes Transactions complianceStatus Changes The complianceStatus returned in the Transactions API response will only return RFI\_REQUESTED and RFI\_RESPONDED beginning January 15th, 2025. For compliance purposes, the remaining values won’t be supported. If you have any questions, please contact your Nium account manager or Nium Support. Issuance and Cards There are no updates for this time period. Payouts and Payins Enhancements Nium Verify now available in India and the European Union Nium Verify is live in the European Union and India! You can now verify corporate bank accounts in Belgium, France, Italy, Netherlands, and Poland and retrieve the account holder name. For a consolidated list of all Nium Verify’s coverage, see Nium Verify. New externalID Field We have introduced a new field, externalID, in the Transfer Money request to allow customers to include their custom reference ID for transactions. This enhancement simplifies reconciliation for clients. The externalID field is a string that accepts user-defined reference numbers. It supports idempotency by rejecting transactions with duplicate reference numbers, thereby preventing duplicates. Customers can filter transactions using externalID via the Transactions API and Fetch Remittance Lifecycle API. Additionally, this field is included in all payout webhooks to facilitate seamless reconciliation. For more info, see Transfer Money in our API Reference. API Breaking Changes Fetch Supported Corridor V2 Deprecation The Fetch Supported Corridor V2 request will be deprecated and unavailable as of April 1, 2025. We’ve launched an updated version, Fetch Supported Corridors V3, which offers enhanced details on supported remittance corridors. Please integrate with Fetch Supported Corridor V3 by April 1, 2025 to avoid any disruptions. For more information, contact your Nium account manager or reach out to Nium Support. --- # November 26, 2024 URL: https://docs.nium.com/changelog/november-26-2024 Core Platform There are no updates for this time period. Issuance and Cards New Features Multiple Wallets for Card Issuance Clients Multiple Wallets now supports card issuance, enabling users to issue cards from additional wallets. This helps manage funds across multiple wallets within card spend accounts, enabling flexible expense allocation and greater control over spending. Card UI Updates: Add Card UI: Added a walletHashId dropdown to enable wallet selection during card setup for customer-level association. Card List UI: walletHashId is now displayed, showing wallet associations for each card. Assign Physical Card UI: Added walletHashId and customerHashId fields for assigning physical cards to specific wallets and customers. Multiple Wallets and Card Issuance is currently available in: Australia Canada Hong Kong Singapore United Kingdom For more information on Multiple Wallets, see Wallets - Overview. If you’re interested in Multiple Wallets, please reach out to your Nium account manager or contact Nium Support. Payouts and Payins New Features Payins Playbook We’ve launched an online playbook for pay-in network capabilities. Use it as a guide to receive money on the Nium network. For more information, see the Payins User Guide. Enhancements Nium Verify now available in the United States Nium Verify is now live in the United States! You can verify bank accounts in the U.S. Please note our US offering is currently in beta. If you're interested, please reach out to your Nium account manager or contact Nium Support. For a full list of regions Nium Verify is available in, see Nium Verify. Paper check payouts now available in the United States We’ve enhanced our U.S. payout capabilities to support paper checks for beneficiaries. For more information, see Paper Checks. --- # November 12, 2024 URL: https://docs.nium.com/changelog/november-12-2024 Core Platform New Features Onboarding Forms: Now available in Japan and New Zealand Our onboarding forms are now available in Japan and New Zealand English! This update makes it easier for users in Japan and New Zealand to complete the onboarding process in their preferred language. For more information, see: JP onboarding NZ onboarding Issuance and Cards There are no updates for this time period. Payouts and Payins New Features Nium Verify: Now available in Tanzania and Nigeria Nium Verify is live in Tanzania and Nigeria! You can now verify bank accounts in these regions and retrieve the account holder's name as registered with the bank. For more information, see Nium Verify. Additionally, when verifying bank accounts in Vietnam, you can now retrieve the registered account holder’s name as part of the verification response. API Breaking Changes Deprecation Notice: Fetch Supported Corridor V2 API The Fetch Supported Corridor V2 request will be deprecated and unavailable as of April 1, 2025. We’ve launched an updated version, Fetch Supported Corridors V3, which offers enhanced details on supported remittance corridors. Please integrate with Fetch Supported Corridor V3 by April 1, 2025 to avoid any disruptions. For more information, contact your Nium account manager or reach out to Nium support. --- # October 29, 2024 URL: https://docs.nium.com/changelog/october-29-2024 Core Platform New Features Test Nium with our new Simulation requests Nium has introduced enhanced Simulation APIs to help developers test various services and refine their integrations confidently. This suite allows you to simulate different scenarios across onboarding, payouts, and compliance transitions. By leveraging these simulations, clients can ensure their implementation meets real-world demands without impacting actual operations. Available tests include: Onboarding Simulations: Test the compliance statuses for individual and corporate accounts, ensuring readiness before live operation. Payout Simulations: Validate transaction flows, including error handling and response to different compliance requirements. Flexible Status Transitions: Move transactions through various lifecycle statuses, such as RFI\_REQUESTED, PAID, or ERROR, to verify end-to-end processes. For step-by-step guides and API details, see Testing Nium. Nium Verify Ensure accurate bank details and reduce payment failures with real-time account verification. For more information, see Nium Verify. Enhancements Multiple Wallets - Account Statement Clients can now generate account statements for a specific wallet using the Fetch Wallet Statement request. This change helps you better reconcile and manage the different wallets you create. For more information, see Customer Account Statement. API Breaking Changes Biometric Authentication Requirement Nium will begin updating authentication requirements for online card transactions in line with the latest requirements from card issuers. These changes aim to enhance transaction security and improve the cardholder’s experience by implementing more robust authentication measures. By April 1st, 2025, all Nium clients must enable biometric authentication for online transactions made on devices that support biometric verification (e.g., fingerprint or facial recognition). Clients will need to integrate with Nium’s Out-of-Band (OOB) authentication flow to support this functionality. For more information about implementing, see OOB Authentication Flow. By integrating biometric authentication for online payments, Nium clients can provide their customers with a more convenient and secure method for verifying transactions. Biometric authentication helps increase the success rate of authentication while reducing fraud in high-risk scenarios. Higher authentication success rates Increased transaction approval rates Reduced fraud on high-risk transactions Improved security for step-up authentication when biometrics are used complianceStatus changes The complianceStatus returned in the API response will only return RFI\_REQUESTED and RFI\_RESPONDED beginning January 15th, 2025. For compliance purposes, the remaining values won’t be supported. If you have any questions, please contact your Nium account manager or Nium Support. Issuance and Cards There are no updates for this time period. Payouts and Payins New Features New beneficiaryIntermediaryBankCode field We’ve added a new beneficiaryIntermediaryBankCode to the Transfer Money request to help capture the correspondent’s (also called the intermediary’s) bank code. This new field helps reduce transaction rejections where SWIFT payouts to specific corridors require additional information about the intermediary bank. --- # October 15, 2024 URL: https://docs.nium.com/changelog/october-15-2024 Core Platform There are no updates for this time period. Issuance and Cards New Features Bulk Card Issuance Nium now supports issuing cards in bulk. Bulk card issuance refers to the process where many prepaid or debit cards are produced at the same time. Bulk issuance is an efficient way to generate and distribute large quantities of cards and helps in saving card delivery costs. Nium supports both personalized and generic card issuance. Cards can be personalized (Name on Card) or generic (no Name on Card), and can be shipped in one single shipment. Bulk card issuance is often used for corporate programs, gift cards, payroll, or disbursement programs. Please contact your Nium account manager or Nium support if you’re interested in issuing cards in bulk. For more information, see Cards Overview. Payouts and Payins There are no updates for this time period. --- # October 1, 2024 URL: https://docs.nium.com/changelog/october-1-2024 Core Platform New Features Multiple Wallets Corporate customers can now have multiple wallets on the Nium platform. Multiple Wallets offers more choice and convenience to clients and helps ledger management with single or multiple currencies. Currently, whenever a customer is onboarded on to Nium, a default wallet is created and linked with the customer. All transactions are credited and debited from that single wallet. With this change, customers can now hold balances and transfer funds between multiple wallets based on their business needs. The assignment of virtual accounts to any wallet is supported by the Assign Payment ID request. We’ve introduced three new APIs to support this feature: Add Wallet Update Wallet Fetch Wallet We're actively working on bringing card issuance and card-based transactions for additional wallets. Currently, card issuance and card-based transactions only support the default wallet that was created and linked with the customer after completing onboarding. Multiple wallets are currently only available in select regions. The regions Multiple Wallets are available include: Australia (AU) Canada (CA) Hong Kong (HK) Singapore (SU) United Kingdom (UK) United States (US) Please contact your Nium account manager or Nium support to evaluate your business use case and configure wallets for you. Enhancements Stay Informed with Our New Status Page Monitor the real-time status of Nium services with our new Status Page. Stay updated on service performance and incidents, and subscribe to notifications for timely alerts on any service changes or issues. See our guide for more information. Virtual Account related information The account type returned in the API response of Virtual Account Details V2 and the Client Details request for GMO\_JP bank has been changed from SAVINGS to LOCAL to make it standardized across all banking partners. Issuance and Cards There are no updates for this time period. Payouts and Payins There are no updates for this time period. --- # September 17, 2024 URL: https://docs.nium.com/changelog/september-17-2024 Core Platform Enhancements Intermediary Bank Code for Virtual Accounts from JPMC SG The virtual account detail returned by the Virtual Account Details V2 API will now include the intermediary bank SWIFT BIC for virtual accounts issued for non-SGD currencies. This will be available in the routingCodeValue2 field and should be used for fund transfers through virtual accounts issued by JPMC SG. Nium Portal Virtual Account Numbers You can now create virtual account numbers directly in the Nium Portal on the Customer Balances page. This caters to users who prefer the portal over our API. For more information, see Virtual Account Numbers. GPI Details for SWIFT Transactions Global Payments Innovation (GPI) details for SWIFT transactions are now included in transaction reports, providing end-to-end visibility into transaction statuses. For more information, see GPI details. Payout Return Reasons Transaction reports now display reasons for returned payout transactions, helping you identify and prevent issues. For more information, see Transaction reports. Nium Docs New Financial Institutions Use-Case Guide We’ve released a new use-case guide tailored for Financial Institutions (FIs). It provides detailed integration steps, fund flow examples, and an overview of key Nium features. For more information, see Financial Institutions. Issuance and Cards There are no updates for this time period. Payouts and Payins Enhancements Customer-Named Virtual Accounts Now Available for Hong Kong Payins We’re enhancing payin capabilities in Hong Kong! You can now collect funds into customer-named virtual accounts in HKD via local methods, and in USD, EUR, GBP, AUD, CAD, and CNY via wires. For more information, see Virtual Account Number. Enhanced Reference Info for Nepal Payments Beneficiaries in Nepal can now see the sender's name in Rupee payouts, improving transaction tracking. This adds transparency and security to every transaction. Enhancements to the Proof of Payments API The ultimate remitter’s name will now appear on the Proof of Payment PDF for on-behalf payouts, helping Financial Institutions manage third-party payout use cases more effectively. For more information, see the Get Proof of Payment request. --- # August 20, 2024 URL: https://docs.nium.com/changelog/august-20-2024 Core Platform There are no changes for this time period. Issuance and Cards Enhancements Apple SDK Our Apple Pay SDK has been enhanced to display the client's name when adding a card to an Apple Wallet. This helps you better manage cards in your Apple Wallet. SDK Version: 2.0.2 Run pod update or pod repo update to get the latest version. If you have any questions about our Apple SDK, please contact Nium Support. Card Webhook Update The walletProvider field in the VTS Token webhook is now restricted to applePay and googlePay. This corrects an issue where some responses returned APPLE or GOOGLE. For more information, see VTS Token. Payouts and Payins There are no changes for this time period. --- # August 6, 2024 URL: https://docs.nium.com/changelog/aug-6-2024 Core Platform - Enhancements Nium Portal - Redesigned Customer Balances Page We've redesigned the Customer Balances page to enhance usability: Review, at a glance, what features are enabled for each currency. This change helps you better understand what capabilities are available when managing those funds. Create Virtual Accounts for Payin-enabled currencies. Non-developers can now create Virtual Accounts in Nium Portal without directly using Nium’s API. For more details, see the Nium Portal - Customer Balances. There are no changes for this time period. There are no changes for this time period. --- # July 23, 2024 URL: https://docs.nium.com/changelog/july-23-2024 There are no changes for this time period. There are no changes for this time period. New features Account Verification We’ve released a new Account Verification request that helps you verify payee details while creating beneficiaries. This change helps you simplify your integration, removing the need for a separate integration dedicated to verifying account details. For more information, see Account Verification. Enhancements Updates to the Fetch Supported Corridors V3 Request We’ve made the following changes to the Fetch Supported Corridors V3 request: payoutMethodCategory query parameter: Helps you separate supported payout methods by corridor - for more information and a detailed breakdown, see the Nium playbook. The query parameters beneficiaryAccountType, customerType, and payoutMethod have been made enums. For more information, see the Fetch Supported Corridors V3 request. New isOffMarket Parameter We’ve introduced a new isOffMarket field to help you understand when off-market fees get applied to Conversion and Quote requests. The isOffMarket field is returned in the response to the following requests: Create Quote Fetch Quote by ID Create Conversion Fetch Conversion By Id Please note that this field isn't returned unless off-market requests have been enabled by Nium. For more information, see FX - Overview. --- # July 9, 2024 URL: https://docs.nium.com/changelog/july-9-2024 Enhancement A new query parameter status has been released for the Virtual Account Details V2 request. With this new parameter, the active/inactive virtual accounts can be filtered by Clients. There are no changes for this time period. There are no changes for this time period. --- # June 25, 2024 URL: https://docs.nium.com/changelog/june-25-2024 New features Reports are now available in Nium Portal. Reports enhance your financial management experience by providing detailed insights into your transactions. You can now track, analyze, and manage your financial activities with ease. For more information, see Reports. Breaking API Changes Starting October 1st, 2024, changes in Nium’s compliance policy will require additional documents and parameters to onboard corporate customers using the Onboard Corporate API. Please update your integration accordingly to avoid disruptions. If you have any questions, please contact your Nium account manager or Nium Support. Current State: These documents and parameters are optional. Future Requirement: From October 1st, 2024, these fields and parameters will be mandatory. Changes to Nium: If the required documents and parameters are not included, the API will return an error indicating the missing documents and/or parameters. Changes to the Onboard Corporate API include: Device Information: IP address and device name is now required for all regions when onboarding corporate customers. See the deviceDetails object in our API Reference for more information about the changes in each country: Australia (AU) Canada (CA) Europe (EU) Hong Kong (HK) Singapore (SG) United Kingdom (UK) United States (US) Europe (EU): Additional information and documents are now required for both eKYB and manual KYB when onboarding corporate customers in Europe (EU). For more details, see: EU Required Documents Stakeholder KYC expectedAccountUsage Singapore (SG): Proof of Identity and Proof of address documents are now required for stakeholders for both eKYB and Manual KYB when onboarding corporate customers in Singapore (SG). For more information, see SG Onboarding. There are no changes for this time period. There are no changes for this time period. --- # May 28, 2024 URL: https://docs.nium.com/changelog/may-28-2024 There are no changes for this time period. Enhancements Fetch Card Details V2: Fetching details using the Card Details V2 endpoint now returns the demographics object. The demographics object only gets returned if the card is assigned to an employee but issued within a corporate customer's wallet. For more information, see Card Details V2. Details that get returned in the demographics object include: firstName middleName lastName nameOnCard email mobile New Features Direct Debit is now available for Singaporean (SG) customers. Direct Debit enables SG-based businesses to fund their Nium wallets using their Singaporean (SG) bank account in real-time. The transaction type for Direct Debit transactions is WALLET\_CREDIT\_MODE\_DIRECT\_DEBIT. Reach out to your Nium account manager for details on how to activate Direct Debit. For more information, see Direct Debit SG. Enhancements Maximum limit for INR Proxy (UPI) transactions has been increased to INR 200,000 from INR 100,000. For more information, see the Nium - India Playbook. --- # April 30, 2024 URL: https://docs.nium.com/changelog/april-30-2024 Enhancements We’ve introduced three new reasons you can include when permanently blocking a customer: UNRESPONSIVE\_CUSTOMER DORMANCY OTHER Moving forward, when PERMANENT\_BLOCK is used, the customer's account will be considered closed, and they can no longer process any further activity. Applications rejected due to high risk or non-compliance will now be blocked from being resubmitted. Previously, such applications could be resubmitted but were rejected by our compliance team after review. With this change, applications that have been previously rejected will automatically be rejected without any wait. Resubmission is still allowed for reasons unrelated to compliance, such as incomplete applications, typos, or incorrect addresses. For individual customers, see Individual Customer Onboarding - Overview. For corporate customers, see Corporate Customer Onboarding - Overview. Enhancements We’ve released two new webhook events to help you manage cards: Card Details Updated: This event is triggered to notify the client or cardholder when any card details are updated. For more details, see Card Details Updated. Card Expiry Alert: This event is triggered when a card is approaching its expiration date. For more details, see Card Expiry Alert. There are no changes for this time period. --- # April 16, 2024 URL: https://docs.nium.com/changelog/april-16-2024 Enhancements Our eKYC Onboarding APIs are now available for individual customers in Canada. For more details, see CA onboarding. Our OpenAPI spec is now available on GitHub. You can download and review our OpenAPI spec to help you build your integration with Nium. For more details, see our Nium OpenAPI repo. We've added ▶ Run in Postman buttons to several guides. These buttons give you quick access to our Postman collection and enable you to see how requests run in real-time. For an example, see Individual Customer Onboarding. There are no changes for this time period. Enhancement We've added additional fields to the remitter object used in the Transfer Money request to provide more details about the payout sender. Fields added include: idExpiryDate idIssueDate originatingFICity originatingFICountry For more details, see Transfer Money. --- # March 5, 2024 URL: https://docs.nium.com/changelog/mar-5-2024 New Features Clients can now manually execute FX conversions. With this change, you're given greater control and flexibility over how funds get converted in customer wallets and the associated settlement timeframes. Pass the new ExecutionType field when making requests to the /Quote API to indicate a manual scheduled FX conversion. This field defaults to at\_conversion\_time if nothing is passed. FX conversions with the field ExecutionType set to at\_conversion\_time settle at standard time, 5 PM local time. Manual scheduled FX conversions must be executed using the /Execute endpoint (within the ExpiryTime) to transfer funds from the source currency to the destination currency within the wallet. New fields: ExecutionType: Set to at\_conversion\_time for timed conversions and manual for manual FX conversions. ExpiryTime: This is a timestamp that indicates when the FX conversion expires. Manual conversions must be executed before this time. We've also updated the following APIs: Create Quote Fetch Quote by ID Create Conversion Fetch Conversion By ID Enhancements We've added a new compliancestatus query parameter to the Transactions endpoint. For more information, see: Client Transactions Customer Wallet Transactions Our manual KYB Onboarding APIs are now available for corporate customers in Canada. For more details, see CA Onboarding. There are no changes for this time period. Enhancements We've released a new version of our Fetch Supported Corridors API. This new version provides greater details about the corridor being used. Changes include: Adding a mandatoryDataRequirements and supportingDocuments field. Adding specifics around the transaction's limitations and turnaround time. For more information, see Fetch Supported Corridors V3. We've added the following query parameters to the Beneficiary List V2 endpoint: beneficiaryName beneficiaryAccountNumber destinationCurrency payoutMethod Deprecation Notices We'll be deprecating Fetch Supported Corridors V2 within the next six months. As we prepare to do so, we'll surface more details. If you have any questions, reach out to the Nium Support team at any time. --- # February 20, 2024 URL: https://docs.nium.com/changelog/feb-20-2024 Enhancements We've added a new complianceStatus query parameter to the following endpoints: Transactions Client Transactions Enhancements You can now use PGP keys (also called RSA security) to transmit sensitive data. For more details, see PGP Prerequisites. API Breaking Changes We've removed the BEN enum from the payout#swiftFeeType field in the Transfer Money request. --- # February 6, 2024 URL: https://docs.nium.com/changelog/feb-6-2024 New Features We have introduced a new feature to Nium Portal called Batch Payouts. With batch payouts, you can now effortlessly process multiple transactions in one go while ensuring all your payouts are handled seamlessly. Learn more about batch payouts from our blog. For details on how to create batch payouts, see Batch Payouts. We've released a Postman collection for all Nium APIs. Use the collection to build your integration. For more information, see Postman Collection. New features We've released several new APIs related to Card Security and 3DS authentication. These new APIs enable you to send and receive data in a more secure manner (e.g., RSA encrypted). For more information, see the following from our API reference: Show Security Details Encrypted Set/Reset PIN V2 Fetch ATM PIN V2 Add Or Update Passcode Enhancements We've made some improvements and fixes to our Google Pay Push Provisioning SDK to support EU and UK address verification. For details on our Google Pay Push Provisioning SDK, see Google Pay Push Provisioning. There are no changes for this time period. --- # January 23, 2024 URL: https://docs.nium.com/changelog/jan-23-2024 New features We have introduced a new Webhook event type called CUSTOMER\_COMPLIANCE\_STATUS applicable for individual customers. This event is triggered when there is a change to the individual customer's compliance status. For more information, see the Customer-compliance status event in our API reference. Prior to this change, you had to configure a separate URL to receive the customer compliance status from Nium. The new event update will improve the developer experience by simplifying the number of integration steps. You can now use the same URL configured to receive all Webhook events and subscribe to the new event. You can also subscribe to the event type CARD\_CLIENT\_KYB\_STATUS\_WEBHOOK to receive the compliance status of corporate customers. The Callback to receive customer-compliance status will continue to be supported. Enhancement We have introduced two new fields - ClientMarkupRate and MarkupRate - to help you apply FX markup rates to your customers. The ClientMarkupRate is the markup rate you negotiated with Nium. The MarkupRate field details the FX markup fees configured for your customer. If there are no fees configured for your customer, the MarkupRate will default to the ClientMarkupRate. Both fields can be found in the response body of the following APIs: Create Quote Fetch Quote by ID Create Conversion Fetch Conversion By Id Having these fields readily available offers a convenient way to charge FX markup fees to your customers and helps you further monetize your FX services for revenue generation. There are no changes for this time period. Other Changes Enabled local Nigerian Naira (NGN) payouts to Nigeria for person-to-person (P2P) and business-to-person (B2P) use cases. --- # December 19, 2023 URL: https://docs.nium.com/changelog/dec-19-2023 There are no changes for this time period. There are no changes for this time period. New features Introduced a new payment option FASTER\_DIRECT\_DEBIT is now available as a fundingChannel in the Fund Wallet API. This option is available for eligible clients to choose between Faster Direct Debit and Standard Direct Debit in the US. Enhancements For AUD currency transactions, additional details will now be visible to the beneficiary. The enhancement will provide the remitter's name and other narrative information to the beneficiary, leading to better transparency of each transaction, benefiting both the sender and the beneficiary. Other The minimum supported value for VND local transactions is updated to 2000 VND due to the restrictions put in place by Nium's bank partner. --- # December 5, 2023 URL: https://docs.nium.com/changelog/dec-5-2023 There are no changes for this time period. New features Introduced Card Widget which provides embeddable HTML that shows Payment Card Industry Data Security Standard (PCI DSS) data in end-user applications. The Nium hosted URL for the embeddable HTML can be retrieved using the new Get Card Details Widget API. This API is secured by JWT token authentication, which is encrypted by the AES RSA encryption algorithm. New features Introduced a new Account Verification API on Nium's payments network. This feature is also commonly referred to as Confirmation Of Payee. Using this feature, customers can ensure the money reaches the intended payee or beneficiary by verifying if the payee details, including account number, are valid. Contact your Nium representative to activate this feature. Refer to the Account Verification (Confirmation Of Payee) user guide for more details. Enhancements Updated the Remittance Lifecycle user guide under the Transfer Money category with simulation account details that will allow you to create transactions in the sandbox environment. With these instructions, you will now be able to replicate PAID, SENT TO BANK, and RETURN statuses and their state transitions. Introduced a new user guide on GPI tracking that offers insights into improved tracking for SWIFT wire transactions. Other Local ZAR currency payouts for P2P use cases have been temporarily deactivated due to a technical issue with our payment partner. Nium continues to support payouts for other use cases such as B2P and B2B. We are working closely with our partner to resolve this issue at the earliest. --- # November 21, 2023 URL: https://docs.nium.com/changelog/nov-21-2023 There are no changes for this time period. There are no changes for this time period. New Features Introduced a new Proof of Payment (POP) API to generate proof for the transactions that are in PAID status. You can use this API to download the proof of payment. Proof of payment is a PDF generated by Nium to provide the necessary details of the transaction such as sender details, beneficiary details, transaction date & time, paid amount, fees, and FX rate. You can provide POP documents to your customers or suppliers for enhancing transparency. Your customers typically use this document, also known as a transaction receipt, for reconciliation and tax verification purposes. Introduced collections capability in Japan. To support this capability, a new data object, InvoiceDetails, is added to the request body of the Fund Wallet API. You will now be able to receive funds locally from individuals and businesses in JPY currency in real-time and hold the funds in customer wallets in JPY currency. You can also issue JPY virtual accounts to your customer wallets using the Assign Payment ID API. Contact your Nium representative to learn more about this feature. Introduced the Direct Debit capability for your corporate customers in Australia (AU). AU-based businesses can now fund from their AU bank account into their Nium-issued wallets using Direct Debit. For this feature, the transactionType is shown as WALLET\_CREDIT\_MODE\_DIRECT\_DEBIT in the response body of the Wallet Transactions API. Contact your Nium representative to activate this capability. Refer to the Direct Debit AU user guide for more details on this feature. --- # November 7, 2023 URL: https://docs.nium.com/changelog/nov-7-2023 There are no changes for this time period. Enhancement Introduced a new field called referenceCode in the Cards 3DS OTP Webhook. referenceCode is a unique value generated with each new OTP value. In instances where the consumer can receive multiple OTPs for the same transaction, this can be leveraged to show the consumer which OTP is expected to be entered. This value should be sent in the SMS or Email along with the OTP and then displayed on the consumer screen. Enhancement We have added two new parameters in the gpi object to enhance the GPI details shared with you in the Fetch Remittance Lifecycle Status API and Remit Transaction Sent to Bank Webhook. forwardBankCode: Bank identification code (BIC) of the next participant bank to which the payment has been forwarded. remarks: Detailed description of the reasonCode. This interpretation is provided by Nium. --- # October 24, 2023 URL: https://docs.nium.com/changelog/oct-24-2023 New Features We have added several new features to the Nium portal in the sandbox environment, including global wallets view, reports for payout transactions, configuring webhook events, inviting new users to your sandbox, and transparency with chronometer in the transaction details. Read the announcement blog for more details. API Breaking Changes Document details are required when onboarding in EU Nium must report the "documentNumber" associated with the individual stakeholder positions of corporate customers to regulatory authorities through various reports. Until now, clients were not obligated to provide stakeholderDetails.documentDetails in the eKYB process. However, starting January 1, 2024, stakeholderDetails.documentDetails will become a mandatory field for both the eKYB and Manual KYB procedures when the position corresponds to UBO, TRUSTEE, or PARTNER. Additionally, stakeholderDetails.kycMode, and stakeholderDetails.documentDetails.document will continue to be optional in the eKYB process when a searchID is provided, but they will be required fields when searchID is not provided for the manual KYB flow. See EU Required Parameters and EU Required Documents for more details. New Features If you are using the delegated model, we have improved the settlement report file to offer more comprehensive information for transaction matching. The new settlement file includes additional fields and is formatted with the pipe symbol as a delimiter, making it simpler to parse and handle. We're delivering the updated V2 version of the file to the same SFTP location where V1 was previously shared. Clients can take advantage of this enhanced file to improve their settlement processing. Detailed information on the format of the file is available in the Client Settlement Report guide. Enhancements Ability to update the name on the card for corporate cards. We have enhanced the Update Card Details V2 API, which will allow customers or cardholders to update card data at the individual card level, including the name on the card. We have included new delivery options for the EU & UK. In the Add Card V2 API, the issuanceMode field has two new options: international\_delivery\_track and international\_delivery\_track\_sign. New features Introduced a new API to retrieve Account Ownership Certificate (AOC) for your customers. To download the account ownership certificate, you can call the Account Ownership Certificate API. The Account Ownership certificate is a PDF generated by Nium to provide the details of the virtual account(s) assigned to the name of the underlying customer. AOCs are usually required by online marketplaces or payment gateways for registration. AOC documents can be used by your underlying customers to provide account details for collections across different payment platforms. Additionally, AOCs are required for loan applications or when dealing with government agencies. Enhancement Added transparency about the timing of the interbank FX rate. To ensure that you know the exact time at which we obtained the last traded interbank FX rate being used in an FX quote, a new field called rateCaptureTime was added in the API response for creating a quote and fetching an existing quote. The rateCaptureTime field contains the timestamp at which we obtained it from our rate service provider. --- # October 10, 2023 URL: https://docs.nium.com/changelog/oct-10-2023 Enhancements Corporate customer onboarding enhancements Added a new status field in the Client-KYB Status webhook to enhance corporate customer onboarding. Currently, the Client KYB Status webhook only provides access to the complianceStatus parameter, and you proceed with the transaction upon receiving a complianceStatus value of COMPLETED. However, certain transactions may not succeed because transactions are only allowed when the status is Clear. To address this issue and prevent transaction failures, we have now included the status field in the webhook, which is already available in the Customer Details API. We strongly recommend that clients utilize both complianceStatus and status to ensure the successful execution of transactions. Note that the complianceStatus being COMPLETED does not signify a terminal state, as there is still a possibility of receiving Requests for Information (RFIs) even after this webhook has been received. In rare instances, RFIs may still be raised even after the status has reached Clear due to post-approval due diligence. However, transactions will not be blocked in such situations. Amendment to attestation for US Clients. For US clients, it is necessary to update the applicant declaration or attestation in your onboarding process to incorporate the UBO (Ultimate Beneficial Owner) declaration. Use the following amended attestation: "I certify that I am the authorized representative of the customer; all information provided and documents submitted are complete and correct. I confirm that I have provided all the UBOs present. I have read and accepted the Nium Terms and Conditions." Individual customer onboarding enhancements Enhancement in the Unified Add Customer API by adding a new optional field isTncAccepted to support both onboarding and the terms and conditions (T\&C) acceptance in a single API call. isTncAccepted is a boolean field with a default value of false. With this change, the customer's initial consent to the T\&Cs can be recorded during the onboarding flow. Introduced shortened enum values for intendedUseOfAccount and estimatedMonthlyFunding fields in the Unified Add Customer API. The shortened values and their corresponding descriptions are available in the enum values description guide. This enhancement will make the API easier to use and reduce the chance of validation errors. The Regenerate KYC URL API now supports individual customers in addition to corporate customers. There are no changes for this time period. Enhancements Extended the Get Card Widget API to support UnionPay. This improvement expands the Nium card widget's support to include UnionPay China cards alongside the currently supported Visa cards. This update will facilitate payments to UnionPay cardholders in China for those who do not meet Payment Card Industry Data Security Standard (PCI DSS) compliance requirements. If you are not compliant with PCI DSS, you need to integrate with the Get Card Widget API to get the recipient’s encrypted card token number. You then pass the token number in the field encryptedBeneficiaryCardToken when you add a beneficiary to make a payout to a card. Steps to make payouts to UnionPay cards will remain the same as existing Visa card payouts. GPI Details for SWIFT Wires SWIFT GPI (Global Payments Innovation) was developed in 2017 to improve the experience of making a payment via the SWIFT network. With this enhancement, we are utilizing the information received from our SWIFT partner banks to offer end-to-end visibility into the status of a transaction, starting from the moment it's initiated to the moment it's deposited to the beneficiary account. In essence, we're enabling the tracking of SWIFT wire transactions. The GPI details can be obtained using the Fetch Remittance Lifecycle Status API, which now includes a new gpi object with four parameters in the API response: reasonCode: GPI code shared by the SWIFT partner bank statusDescription: Description of the GPI reason code timestamp: Date and time of the last status change forwardBankName: Name of the next participant bank to which the payment has been forwarded The Remit Transaction Sent to Bank Webhook will have the following enhancements: The gpi object with the above described four parameters will also be available in the webhook response. We will send a new event notification whenever there is a change in reasonCode or forwardBankName. --- # September 26, 2023 URL: https://docs.nium.com/changelog/sep-26-2023 There are no changes for this time period. There are no changes for this time period. New features Introduced the new Fetch Aggregated Exchange Rates endpoint that allows you to track and monitor historic market trends for any currency pair. After you specify the required sourceCurrencyCode and destinationCurrencyCode fields, this API returns the aggregated daily FX data for the past ninety days. You can also specify the following optional fields: start and end dates that need to be within the last ninety days. window to specify whether the results should be grouped by hour or day. For both the hourly and daily window views, the following are displayed for the specified currency pair during the selected time window: min - The minimum FX rate captured. max - The maximum FX rate captured. average - The average FX rate calculated. time - The starting timestamp of the FX rate aggregation. For additional information, refer to the FX Overview Guide. --- # September 12, 2023 URL: https://docs.nium.com/changelog/sep-12-2023 New features Added a new RFI template called otherData for corporate onboarding. Currently, the RFIs requiring additional data are limited to businessName, transactionCountries, and intendedUseOfAccount. Prior to this change, when additional information was required, an RFI was raised using an email or with the otherDocument RFI template. Since the otherData RFI handles non-document requests, any type of information can now be collected without the need to add any new RFI templates in the future. The otherData RFI is available in preprod for testing now and will be available in production starting October 10, 2023. The request body for the Respond to RFI API accepts the businessInfo.additionalInfo.otherData object as an item in the rfiResponseRequest array object. Examples for usage of otherData: Template in the response of the Fetch RFI Details API Request body for the Respond to RFI API There are no changes for this time period. There are no changes for this time period. --- # August 29, 2023 URL: https://docs.nium.com/changelog/aug-29-2023 Enhancements For security and to inform customers of any account takeover, notifications are sent in two ways. 1\. Notification by Email The new email template CUSTOMER\_UPDATE\_EMAIL has been introduced to send email notifications to customers whenever there is any update in the email address or mobile number of the customer. For any change in the email address, notifications are sent to both the previous and updated email addresses. For any change in the mobile number, the notification is sent to the current email address. Currently, this is applicable only for individual customers whose kycStatus is Clear. 2\. Notification by Webhook To send the contact information of the customer prior to the update, three new key-value pairs have been included in the fields parameter: previousCountryCode previousMobile previousEmail The CARD\_CUSTOMER\_UPDATE\_WEBHOOK parameter notifies about the customer’s previous and newly updated contact information to you. Example of the updated field in the request body of the webhook template: "fields": "countryCode": "SG", "mobile": "67543800", "email": "", "previousCountryCode": "US", "previousMobile": "123456789", "previousEmail": "" , New features The new OOB Callback v2 API simplifies the request payload for providing Nium with the result of 3DS out-of-band authentication. After you perform authentication using Biometrics or other means, you can provide the success or failure to Nium against the Transaction ID. The OOB Callback v1 API will be deprecated and become unsupported on March 31, 2024. There are no changes for this time period. --- # August 15, 2023 URL: https://docs.nium.com/changelog/aug-15-2023 Enhancements EU Corporate Customer Onboarding: Allows an application to be submitted without the collection of the REGISTER\_OF\_DIRECTORS and REGISTER\_OF\_SHAREHOLDERS documents for Public and Private companies when not required. Starting August 14, businessDetails.additionalInfo.businessExtractCoveredStakeholder is no longer validated, allowing an application to be submitted without these two documents. There are no longer any notes related to these documents in the remarks field in the response object of the Onboard Corporate Customer API. An RFI will be raised if either of these documents is required. Typically, when the BUSINESS\_REGISTRATION\_DOC does not contain the details of directors and shareholders based on customer input. See here for the complete list of required business documents for EU corporate customers. EU, SG, and UK Individual Customer Onboarding: Has three additional parameters in the KYC redirect URL to help you better understand the status of a customer’s verification: errorCode, errorMessage, and isSuccess. This is applicable for the eDocument verification flow in EU, UK, and SG and applicable for the eKYC flow in SG. The isSuccess field is returned as true or false depending on the customer’s completion status of the verification flow with the vendor. The errorCode and errorMessage fields are populated whenever isSuccess is false. US Corporate Customer Onboarding: All new US corporate customers registered in Delaware and New Jersey require a CERTIFICATE\_OF\_GOOD\_STANDING document. If not provided, this document appears in the remarks field in the response of the Onboard Corporate Customer API, and the application stays in the IN\_PROGRESS status until the document is provided. Impact: The enum value CERTIFICATE\_OF\_GOOD\_STANDING has been added to the enum list of the businessDetails.documentDetails.documentType field in the Onboard Corporate Customer API. The CERTIFICATE\_OF\_GOOD\_STANDING is a required document when the address.registeredAddress.state field is DE or NJ, and the application stays in the IN\_PROGRESS state until submitted. See here for the complete list of required documents for US corporate customers. Items available for testing in the sandbox environment: The enums list added CERTIFICATE\_OF\_GOOD\_STANDING, and the remarks field is available for missing documents for both eKYB and Manual KYB clients. By August 22, Manual KYB clients can use the remarks field for CERTIFICATE\_OF\_GOOD\_STANDING documents. There are no changes for this time period. There are no changes for this time period. --- # August 1, 2023 URL: https://docs.nium.com/changelog/aug-1-2023 New features You can now use a new method to link a bank account for Debit ACH US through a micro-deposit. This option is especially beneficial in cases where instant verification is not supported. Your customer now has the flexibility to choose between two verification options: instant or micro-deposit. To support the micro-deposit option, you need to implement the Confirm Funding Instrument API. Once the micro-deposit is successfully delivered, a new webhook, DIRECT\_DEBIT\_MICRODEPOSIT\_SUCCESSFUL is sent by Nium to notify you of the successful transaction. These enhancements aim to provide you and your customers with broader coverage and improved options for bank account verification. Philippine peso (PHP) currency support is now enabled for collections and funding. You now have the option to call the Assign Payment ID API with the parameter bankName set as NETBANK\_PH\_PHP and the currencyCode set as PHP. This configuration allows your customers to generate a PHP virtual account, facilitating expanded payment processing and management. New features Introduced a new feature, Wallet to Wallet Transfers that enables fund transfers between Nium customers' wallets using the new Wallet to Wallet Transfer API. With this functionality, customers can easily transfer funds to another Nium onboarded customer. The sender and receiver of the funds can belong to the same client setup or different client setups onboarded with Nium, depending on their geographic presence. This enhancement benefits global clients with multiple client setups on the platform. It allows customers across these client setups to conduct wallet-to-wallet transfers seamlessly, enhancing the overall user experience and facilitating smoother financial transactions. Transferring funds between customers of the same client setup does not require any configuration changes within the client setup. However, for funds transfer between customers of different client setups, you need to contact your Nium representative. They can help you enable this feature, allowing your customers to utilize it seamlessly. Enhancement Added a new enum value called "Travel related spending" in the parameter intendedUseOfAccount within the Unified Add Customer API. The new value will support individual customers' travel-related use cases. This addition better supports and accommodates various financial transactions related to travel expenses for our customers. Deprecation notices In the Client Details API, the multiCurrencySupported field is being removed from the API's response object as it is an unused field and is set to false by default. This field was giving misleading information that the client does not have support for multiple currencies. Clients will see the currencies enabled for their setup in the currencies field of the response. In the Unified Add Customer, Customer Details V2, and Customer List V3 APIs, the preferredName field has been changed from required to optional, meaning it is no longer required for customer onboarding purposes. You now have the flexibility to provide this information if needed, but it is not required when using the API for customer registration. The P2P Transfer API is deprecated and becomes unsupported on January 31, 2023. --- # July 19, 2023 URL: https://docs.nium.com/changelog/july-19-2023 New features Introduced a new Transaction Prescreening capability for scheduled transactions. This functionality enables payroll clients to send transactions to Nium for compliance or risk-related checks before the scheduled date of the transactions. It’s recommended to initiate a scheduled payout five to seven days in advance if the client wants to prescreen the transaction. A new preScreening boolean field, with a value as true/false, is introduced in the payout object of the Transfer Money API. New transaction types are introduced for prescreening transactions: Remittance\_Debit\_External\_Prescreening and Remittance\_Debit\_Prescreening (self-payment). Note: The reverted FX conversion feature is improved by changing the URL names of the Conversion APIs listed below to clearly distinguish between a conversion within a customer’s wallet and a transfer from one customer’s wallet to another customer’s wallet. Introduced the capability to perform FX conversions within a customer’s wallet using locked FX rates as well as scheduled settlement. This service helps you convert your funds from any of the supported Nium payin currencies into any of the Nium payout currencies at transparent and guaranteed FX rates. The converted amount can then be used to send payouts or spend through a card. You can choose from a range of lock periods (up to 24 hours) for the FX quote so that you have time to confirm the rate with your customers or internal users and initiate the FX conversion. You can also choose from a range of conversion schedules (up to two business days) so that you get the necessary time to fund with the source amount required for the FX conversion. Refer to the FX Overview guide for more information on this capability. The following new APIs are introduced to support this capability: Create Quote API: Creates an FX quote for a pair of currencies based on a lock period and conversion schedule. Fetch Quote by ID API: Fetches the details of an FX quote using the quoteId. Create Conversion API: Converts funds within a customer's wallet from a source currency to a destination currency at either a market FX rate or a locked FX rate obtained using the Create Quote API. Fetch Conversion by Id API: Fetches the details of an FX conversion using the conversionId. Cancel Conversion API: Cancels an FX conversion that’s yet to be settled. Enhancements Direct Debit 1\. Introduced an option for faster settlement time for Direct Debit ACH in the US. Reach out to your Nium sales representative for more information. 2\. Introduced additional webhooks when there’s a change in the status of your funding instrument: DIRECT\_DEBIT\_FUNDING\_INSTRUMENT\_APPROVED — when the status of your fundingInstrument changes from Pending to Approved. After this, you can call the Fund Wallet API to initiate a debit from your bank account. DIRECT\_DEBIT\_FUNDING\_INSTRUMENT\_FAILED — when the status of your fundingInstrument changes from Pending to Failed. After this, you can call the Get Funding Instrument Details API to know the reason for the failure and act accordingly. DIRECT\_DEBIT\_FUNDING\_INSTRUMENT\_CANCELLED — when the status of your fundingInstrument status changes from Approved to Cancelled. You receive this as an acknowledgement that the customer has cancelled the mandate via their bank. Enhanced the ability for a client to embed the card widget within the client’s domain. A new clientDomain field is introduced in the request body of the Get Card Widget API. This field contains the domain name where the widget needs to be embedded. New features We have introduced a new Unblock PIN API that allows you to unblock a card’s personal identification number (PIN) when an invalid PIN number is entered more than four times. You can query the PIN status using the Fetch PIN Status API. This API is applicable for Physical cards only and available for clients in the APAC region. --- # July 5, 2023 URL: https://docs.nium.com/changelog/july-5-2023 API breaking changes We've identified that the previously announced FX conversions APIs require a few critical improvements. As a result, we're reverting the feature effective immediately and plan to relaunch the revised APIs shortly. Stay tuned for an updated announcement. New features We've introduced a beta version of AI-powered docs. OpenAI now backs our docs to provide human-like interaction with the Ask a question search field. You can find this feature in the header section of all documentation pages. Enhancements We've made enhancements to the daily downloadable Client Account Fees Report by adding the following new fields: Fee Source: This field indicates the source of the fee levied by the system, the default fee setup or the client charge fee API. Fee Type: This field applies only to fees levied by the system and indicates whether the fee was set up as a percentage or a flat fee. Fee Value: This field applies only to fees levied by the system and contains the defined value of the fee in the client setup. Fee Value Currency: This field applies only to flat fee types and indicates the currency in which the fee value was defined. Additional Fee Type: This field applies only to fees where clients have opted for additional fees as part of the payout request. It shows the fee type chosen by the client, either fixed or percentage. Additional Fee Value: This field applies only to fees where clients have opted for additional fees as part of the payout request. It contains the amount value that was added to the fee. Deprecation notice The designation parameter in Unified Add Customer, Customer List V3, and Customer Details V2 APIs, is deprecated and becomes unsupported on December 16, 2023. --- # June 20, 2023 URL: https://docs.nium.com/changelog/jun-20-2023 New features Note: We have identified that a few critical improvements are required to the below announced FX conversions APIs. As a result, we have reverted the feature effective immediately and will be re-launching the revised APIs shortly. Stay tuned for an updated announcement. We are introducing the capability to perform FX conversions within a customer’s wallet using locked FX rates as well as scheduled settlement. This service helps you convert your funds from any of the supported Nium payin currencies into any of the Nium payout currencies at transparent and guaranteed FX rates. The converted amount can then be used to send payouts or spend through a card. You can choose from a range of lock periods (up to 24 hours) for the FX Quote so that you have time to confirm the rate with your customers or internal users and initiate the FX conversion. You can also choose from a range of conversion schedules (up to two business days) so that you get the necessary time to fund with the source amount required for the FX conversion. Refer to the FX Overview guide for more details on this capability. The following new APIs are being introduced to support this capability: Create Quote API: Create an FX quote for a pair of currencies based on a lock period and conversion schedule. Fetch Quote by id API: Fetch the details of an FX Quote using the quoteId. Create Transfer API: Convert funds within a customer's wallet from a source currency to a destination currency at either a market FX rate or a locked FX rate obtained using the Create Quote API. Fetch Transfer by id API: Fetch the details of an FX Transfer using the transferId. Cancel Transfer API: Cancel an FX Transfer that is yet to be settled. Enhancements cardProductId parameter, that is required request body parameter in the Add Card V2 API, has been changed from a 3-digit number to UUID format. This change is only applicable to new clients. Clients that are setup previously with a 3-digit cardProductId can continue to use it. addressLine1 and addressLine2 parameters in the Address object of all card lifecycle APIs, Add Card V1 & V2, Update Card Details V2, Block and Replace Card, and Renew Card, have additional validation. As per the new validation rules, only chars in the below regex pattern are allowed. Regex: \[a-zA-Z0-9.'-#@%&,:/ ]+ Revised posting logic on transaction settlements for all Wallet based Clients. Previously, A separate transaction was posted for Settlement Debit and Settlement Credit depending on if the fluctuation was higher or lower respectively. In the revised logic, fluctuations are accounted for by reversing the original transaction including relevant fees that were charged and posting a new transaction as Settlement Direct Debit for the new amount (higher or lower) and recalculate all relevant fees and markups. There is no impact to wallet clients as the amount being debited or credited has not changed, only the methodology has been updated. This change is not applicable to clients on Delegated Mode (RHA). Following are example scenarios where this change is applicable: FX Rates have fluctuated in the time period between authorization and settlement. Example: The FX rates have fluctuated between SGD (billing Currency) and USD (authorization currency i.e., the receiving wallet). Fluctuated higher- FX rate between SGD and USD was 1.33510 at the time of authorization. FX rate between SGD and USD has become 1.34100 at the time of clearing. Fluctuated lower- FX rate between SGD and USD was 1.33510 at the time of authorization. FX rate between SGD and USD has become 1.33100 at the time of clearing. FX Rates have fluctuated between the transaction currency and the billing currency in the time period between authorization and settlement. Example: The transaction was performed in PHP (Philippine Peso) and the billing currency is SGD (Singapore Dollar). Fluctuated higher- FX Rate between PHP and SGD was 0.02410 at the time of authorization. FX Rate between PHP and SGD has become 0.02490 at the time of clearing. Fluctuated lower- FX Rate between PHP and SGD was 0.02410 at the time of authorization. FX Rate between PHP and SGD has become 0.02380 at the time of clearing. There has been a change in the transaction amount between authorization and clearing. Example: The cardholder has left a tip in a restaurant due to which the transaction amount during clearing is higher than the transaction amount at the time of authorization. --- # June 6, 2023 URL: https://docs.nium.com/changelog/jun-6-2023 Enhancement The responses for the Confirm Funding Instrument API, the Get Funding Instrument List API, and the Get Funding Instrument Details API responses are enhanced to include the new bankName field in the funding instrument linked for direct debit. API breaking change This is a reminder notice about the breaking changes to beneficiary APIs that are enhanced with two new fields, beneficiaryContactName and beneficiaryEntityType. The fields are required to make a local payout to a business in South Africa with the South African rand (ZAR) currency. Details on the changes are available in an earlier communication in the May 9, 2023 changelog. The changes will become effective on June 15, 2023. New features Activate Card V2 API is a new operation that features the concept of an activation code to help cardholders activate their cards using it. The activation code is provided in the card kit cardholders receive with the physical copy of the card. The platform generates an activation code for all PHY-type cards using the Add Card V2 API only. This feature is not available if the Add Card V1 API is used when creating cards. The activation code is sent in the embossing file to the personalization vendor and printed on the letter accompanying the card. The API structure mirrors the structure of all other Card V2 APIs with logical tags. The API includes the activation code as a required field to activate the physical card. This prevents cards from being activated immediately upon creation. Deprecation notice Activate Card V1 API is deprecated and becomes unsupported on December 31, 2023. Activate Card V2 is the latest version of this API. Enhancement Search and filter transactions in the Transaction Report of the client portal, with additional filter options using a card hash ID, transaction status, or settlement status. The transaction status and settlement status now support searching with multiple values. --- # May 23, 2023 URL: https://docs.nium.com/changelog/may-23-2023 New features Link a corporate customer to an individual customer is a new feature for Spend Management and Payroll Management use cases. You can now link an individual customer, or employee, to their corporate customer and create that hierarchy in the system. Note: For details on how to link a corporate customer to an individual customer or the Spend and Payroll Management feature, refer to the Platform tab. Spend Management: Assigns a card to an employee linked to a corporate account. You can issue cards using the Add Card V2 API and provide the customer details as mentioned below: customerHashId: the customerHashId of the corporate customer walletHashId: the unique walletHashId of the corporate customer childCustomerHashId: the customerHashId of the individual customer The card is issued to a corporate customer and is linked to an individual customer. You can fetch the childCustomerHashId with the Card Details V2 and Card List APIs. The query parameters are enhanced to include the clientHashId, customerHashId, walletHashId, and childCustomerHashId to help filter the results. Payroll Management: Assigns a card to an employee for their own account. You can issue cards using the Add Card V2 API and provide the customer details as mentioned below: customerHashId: the customerHashId of the corporate customer walletHashId: the unique walletHashId of the corporate customer childCustomerHashId: NULL The card is issued to an individual customer. Card List V2 API retrieves a list of all cards issued to a wallet using the walletHashId and the customerHashId path parameters. The API structure mirrors the structure of all other Card V2 APIs with logical tags. The API shows the delivery address on file, the address where the card is delivered, and its embossing details. Card List V1 API is deprecated and becomes unsupported on December 31, 2023. A transaction is declined if the Know Your Customer (KYC) verification process is in the pending status. This change is in accordance with compliance regulations. All cards associated with the customer and their wallet are also temporarily blocked until the status changes to verified. Enhancements Search and filter cards in the client portal using a new Search and Filter feature entering a card number, a card hash ID, and a card proxy number, on the customer details screen. The functions help find a card among multiple ones attached to a wallet. Card Details V1 and V2, and Card List V1 and V2 APIs provide device details for Mastercard. Before, device details were only available for Visa cards. New features Spend and Payroll management: Link a corporate customer to an individual customer is a new feature for Spend Management and Payroll Management use cases. You can now link an individual customer, or employee, to their corporate customer and create that hierarchy in the system. Only an individual customer can be linked to a corporate customer. The opposite isn’t true. To establish a connection or relationship between the individual customer and the corporate customer, you need to configure the relationship with the childMustHaveParent parameter set to true. If this flag is false, you have the option to establish the connection, but the hierarchy is not enforced by the system. Spend Management clients need to be configured with the billingAddressAsCorporate parameter set to true. This parameter allows the billing address of an Individual customer to be the same as the business address of a corporate customer. Payroll Management clients need to be configured with the billingAddressAsCorporate parameter set to false. To setup the hierarchy, you need to onboard the corporate customer first and then onboard the individual customer using the Unified Add Customer API. The fields below have been impacted: parentCustomerHashId: A new required parameter has been added if the childMustHaveParent flag is set to true. kycMode: accepts MANUAL\_KYC value if the billingAddressAsCorporate parameter is set to true. billingAddress: details are optional if the billingAddressAsCorporate parameter is set to true. You can fetch the parentCustomerHashId for an individual customer with the following enhanced APIs: Customer List V3 API: Allows all individual customers to have the parentCustomerHashId parameter value available. You can fetch all the Individual customers linked to a corporate customer by providing the parentCustomerHashId parameter as a part of the query parameter. Customer Details V2 API: The parentCustomerHashId parameter, in the individual customer details section, provides the customerHashId of a corporate customer to which the individual customer is linked. Transaction management is enhanced with the update of the following APIs to include the transactions that individual customers make on the cards issued to corporate accounts: Transactions API: The childCustomerHashId parameter is added for all the transactions. The value includes the customerHashId of the individual customer for the applicable transactions. The childCustomerHashId can be used as a query parameter in this API. Client Transactions API: The childCustomerHashId parameter is added for all the transactions. The value includes the customerHashId of the individual customer for the applicable transactions. The childCustomerHashId can be used as a query parameter in this API. Electronic document verification, or E\_DOC\_VERIFY, is now available as an option in kycMode for Know Your Customer (KYC) applicants in all regions. Corporate customers in Australia (AU), Singapore (SG), and the United States (US) previously completed the applicant KYC verification process via MANUAL\_KYC, which delays the approval process. Using E\_DOC\_VERIFY, customers can now complete the KYC verification process for non-resident applicants following the redirect URL of Nium's KYC vendor and uploading documents on the vendors' UI resulting in real-time approvals. E\_DOC\_VERIFY is also available for Electronic Know Your Business (eKYB) and manual KYB. E\_DOC\_VERIFY is also available for European Union (EU) and United Kingdom (UK) applicants. Enable E\_DOC\_VERIFY by passing the businessDetails.applicantDetails.kycMode=E\_DOC\_VERIFY object in the Onboard Corporate Customer API. Refer to Region-specific KYB requirements to see the available applicant and stakeholder KYC modes. Refer to the applicant KYC information on the following pages to learn how to integrate: AU, SG, US Customer account statement generates a statement that gives a list of all transactions your customer makes on the platform, including deposits, withdrawals, spending, fees, payments, and refunds. You can give your customers an account statement periodically or based on their specific requests to help them keep the information for their records or to reconcile their transactions. You can now generate an account statement for your customers via the Account Statement API as a PDF or a CSV document. Contact your Nium representative to use this feature. Enhancements Customer List V3 API features a new query parameter, named customerType, so you can fetch your customer list based on your customer type. The accepted values are INDIVIDUAL or CORPORATE. Unified Add Customer API makes the new customer onboarding delivery address parameters listed below optional. You can now choose to use the fields but they’re not required. deliveryAddress deliveryAddress2 deliveryCity deliveryCountry deliveryLandmark deliveryState deliveryZipCode --- # May 9, 2023 URL: https://docs.nium.com/changelog/may-9-2023 New features Introduced the Direct Debit capability on Nium's payments network for UK and EU customers. The capability provides convenience to UK-based and EU-based businesses to fund from their UK and EU bank account respectively into their Nium-issued wallets using Direct Debit. To support this feature, new APIs have been added and the existing APIs have been modified as mentioned below. The transaction type for this payment method in Nium's system is WALLET\_CREDIT\_MODE\_DIRECT\_DEBIT. Contact your Nium representative to activate this feature. Refer to the Direct Debit user guide for more details on this feature. addFundingInstrument API — Links the customer’s bank account to their Nium wallet. Additional data elements have been added to receive bank account details in setting up Direct Debit for UK and EU customers. confirmFundingInstrument API — Receives the one-time password (OTP) entered by the customer for validation by Nium against the OTP generated by Nium before setting up a Direct Debit mandate. This is a new API. getFundingInstrumentDetail API — Provides the details of the account that's linked. getFundingInstrumentList API — Provides the list of accounts that are linked. fundWallet API — Initiates the payment instruction to pull the funds. Enhancements Introduced the new field statementNarrative in the Fund Wallet API to allow you to pass information that you would like to display in the payer's account statement for every debit transaction done via Direct Debit. The information that you can pass has a maximum length of 10 characters for the US and UK and a maximum length of 140 characters for EU. API breaking changes Introduced two new fields in both V1 and V2 of beneficiary APIs. These fields are required for making a local payout to a business in South Africa with South African rand (ZAR) currency. The updated APIs that include the new fields are addBeneficiary, updateBeneficiary, beneficiaryDetail, and beneficiaryList. beneficiaryContactName (beneficiary\_contact\_name in v1) - This field requires the name of the contact person of the business. beneficiaryEntityType (beneficiary\_entity\_type in v1) - This field requires a beneficiary entity type and needs to be one of the following lowercase values: sole\_propriatorship partnership privately\_owned\_company publicly\_owned\_company government\_owned\_company go financial\_institution The changes are effective June 15, 2023. New features In the previous year, we implemented restrictions on card issuance to countries that were approved in the Payment Instruction File (PIF) submitted to the card schemes. However, following additional feedback from the schemes, we have updated our approach and now restrict card issuance based on card type: physical or virtual. With this new approach, you have the flexibility to configure the countries where you want to issue virtual cards (pending approval from the schemes), even if physical card issuance to those countries is not permitted. For example, VISA has granted approval for virtual card issuance in Vietnam for a client based in Singapore, but physical cards are still prohibited. Enhancements In the previous release notes, we announced that ADD\_ON type additional cards will no longer be supported from Sep 30th, 2023. With this release, ADD\_ON cards will not be renewable via the Card Renewal API. API breaking changes Removed the maskedCardNumber field from the response object of Add Card API v2. If needed, you can use Card Details API (v1 or v2) to get the maskedCardNumber field. The maskedCardNumber field still exists in Add Card API v1. Deprecation notices Add-on Cards are no longer issued after September 30, 2023. Add Card API v1 will return an error if the card being created is an 'Add-On’ card after Sep 30th, 2023. Clients must make the change to either switch to Add Card API v2 or ensure that cardIssuanceAction field in Add Card API v1 is passed as 'NEW' to indicate creation of the primary card. All existing Add-On cards are going to continue to work. Refer to the Deprecated APIs page for the complete list. New features Fetch Corporate Constants API Fetch Corporate Constants API is now available for you to look up the enum values related to the onboarding of your corporate customers. This API returns acceptable values of various fields that need to be passed via the Onboard Corporate Customer API. There are many fields in Onboard Corporate Customer API which are of type enum and some of these fields have values that change often, such as intendedUseOfAccount and IndustrySector. Integrating this API helps you handle these changes without the need of any further development on your end when values are updated. Keeping enum values updated is beneficial to customers as it improves the approval rates and reduces the approval turnaround time. You need to integrate the Fetch Corporate Constants API and display the output to customers as a dropdown list while they complete your onboarding form. Use this API for all possible fields such as businessType, documentType, annualTurnover, intendedUseOfAccount, etc. For further details, see the Fetch Corporate Constants user guide. Regenerate KYC URL API for Onboarding Corporate Customers The KYC URL returned in the response of Onboard Corporate Customer has an expiration time; and once expired, the link cannot be used to complete the applicant KYC. Use the Regenerate KYC URL API to generate a new KYC URL with a renewed expiration time. This API can be used for all regions if applicantDetails.kycMode='E\_DOC\_VERIFY' and in Singapore for both E\_DOC\_VERIFY and E\_KYC. API breaking changes Introducing a new validation on businessRegistrationNumber. The change is applicable to Nium clients in all geographies that are onboarding corporate customers in the US. Going forward, you are expected to send only 9 digit numerals in this field. Any other format will result in a validation error. The change is effective July 1, 2023. Deprecation notices Starting Sep 1, 2023 many of the enum values for the below listed fields will be removed or updated to support a newer version of our risk scoring model. Make use of the new Fetch Corporate Constants API to get the latest values that are supported for these fields. Going forward integrate this API instead of hardcoding the new enum values for the associated fields. Once your integration is completed, please reach out to Nium support to get your template configured for the latest risk model. A few values are deprecated in the following fields of the Onboard Corporate Customer API: riskAssessmentInfo.industrySector riskAssessmentInfo.annualTurnover riskAssessmentInfo.intendedUseOfAccount riskAssessmentInfo.totalEmployees Refer to the Deprecated APIs page for the complete list. --- # April 25, 2023 URL: https://docs.nium.com/changelog/apr-25-2023 New features Updated Fetch Remittance Lifecycle Status API with additional remittance statuses in its response. The new statuses provide granular information about each state of the transaction. The new statuses are: INITIATED — This status indicates that the transaction is accepted for processing. IN\_PROGRESS — This status indicates that the transaction is undergoing compliance review. RFI\_REQUESTED — This status indicates that Nium's compliance has raised a request for information (RFI). RFI\_RESPONDED — This status indicates that the customer has responded to the RFI. COMPLIANCE\_COMPLETED — This status indicates that Nium’s compliance has completed its review and that the transaction is going to be sent to the beneficiary’s bank. REJECTED — This status indicates that the transaction is rejected due to compliance reasons. SCHEDULED — This status indicates that the transaction is scheduled and is going to be processed on the set date. The description of the new statuses is available in the statusDetails field of this API. Added the Saudi riyal (SAR) currency for the Payin use case of collections and funding through an international wire transfer. Enhancements The response body of the Card Transaction Reversal webhook event type is updated to include the notification of additional transaction reversal scenarios. We now support transaction aging scenarios in addition to the merchant reversals. New features Electronic Know Your Business (eKYB) identification process for onboarding US corporate customers. The eKYB check is now available for onboarding US corporate customers for clients in all countries where Nium operates. Using eKYB, corporate customers can get approved soon after submitting their application. Applicants aren't required to upload documents, making this an automated process. See the US Corporate Customer Onboarding guide for more information about the implementation instructions of the eKYB process. Contact Nium customer support to get your template configured for eKYB to use this feature. Enhancements Updates to the Customer List report that can be downloaded from the UI portal. The following fields are added to the report: Billing Country Case Id Client Hash Id Client Id Client Name Compliance Region Registered Date Segment Wallet Compliance Level The following fields are removed from the report: Compliance Profile Designation KYC Status Preferred Name API breaking changes We've introduced two additional required fields for onboarding corporate customers in the US. businessDetails.applicantDetails.additionalInfo.applicantDeclaration businessDetails.description The required fields apply to Nium clients in all countries. Applications missing any of the required fields result in a validation error. The changes are effective July 1, 2023. Clients are required to collect a declaration from the applicant during the time of corporate customer onboarding for the eKYB and manual KYB processes. This update only applies to corporate customers in the US. Clients are required to show the following text to the applicant and collect a click-to-accept agreement for the declaration. "I certify that I am the authorized representative of the customer and all information provided and documents submitted are complete and correct. I have read and accept the Nium Terms and Conditions." After the applicant accepts the declaration, they send a Yes value for the below field in the Onboard Corporate Customer API. businessDetails.applicantDetails.additionalInfo.applicantDeclaration