Corporate Customers

Run in Postman

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.

note

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 details Stakeholder details Applicant details Documented 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 KYB Stakeholder 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 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.

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

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

European Union — EU 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.	N/A
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, regardless of residence

Hong Kong — 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)

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

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.	`MANUAL_KYC` manual submission of documents.

Singapore — 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 and is applicable via a live selfie photograph. `MANUAL_KYC` manual submission of documents	N/A
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.	`MANUAL_KYC` (manual submission of documents, regardless of residence)

United Kingdom — 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 `MANUAL_KYC` for non-UK 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, regardless of residence

United States — 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

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	`MANUAL_KYC` manual submission of documents.	`MANUAL_KYC` manual submission of documents, regardless of residence.

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

The following details how to onboard corporate customers using a custom Integration.

Submission of information

You need to send the required information below by one or more APIs summarized in the table.

Region	eKYB required steps
AU	1. (Optional) Public Corporate Details using Business ID API 2. Onboard Corporate Customer API
EU / SG / UK	1. Public Corporate Details using Business ID API 2. Exhaustive Corporate Details using Business ID API 3. Onboard Corporate Customer API
US	Onboard Corporate Customer API

For MANUAL_KYB, you only need to call the Onboard Corporate Customer API.

note

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 or contact Nium Support.

Onboard API response

You can implement the following actions based on the status field in the response.

HTTP code	Status	Next steps
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	`BAD_REQUEST`	Correct the data and resubmit the application.

200 response

Once the application is submitted via the Onboard Corporate Customer 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, it means the customer has to be redirected to the vendor's page for completion of the applicant's KYC. Refer to the individual region pages for more information. Once the process is completed, wait for webhook events to indicate the change in the corporate customers' application status. The filed expiry indicates the number of mins the redirectURL is valid for and is typically 1440 minutes. See Regenerate KYC URL for next steps on expiry.
Additional documents might be required, which can be submitted via the Upload Document for Corporate Customer 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`

{
    "clientId": "NIM1679801521238",
    "caseId": "c800e2e0-1add-4c34-8244-b7baa4924a0e",
    "status": "IN_PROGRESS",
    "remarks": "SHAREHOLDER -> VERIFIED|BUSINESS -> KYC : SCREENING COMPLETED, ALIAS_KYC : SCREENING COMPLETED|Application is being reviewed by our compliance agent|VERIFIED|APPLICANT -> KYC : SCREENING COMPLETED|VERIFIED",
    "customerHashId": "88464f2d-8caa-4cd4-a1db-346d9defde05",
    "walletHashId": "91cb0636-c30a-4304-ba47-a589dead86c9",
    "redirectUrl": "https://integrationspreprod.partners.instarem.com/preprod/compliance/callback/load?referenceNumber=18afec3f-c8fe-491a-bf4f-28651df943ec&token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI0MDhjZDlmNS1hN2I5LTQ2YTYtYjE1YS0zOWY2NzE5ZjdiMTd8fGVjNWQ4OGUzLTg2ZGItNDc0ZS04ZDg1LWQxZmNiYzQ4MzllNnx8MTY3OTgwMTUyNSIsImV4cCI6MTY3OTgwMjQyNSwiaWF0IjoxNjc5ODAxNTI1fQ.dHaxPZlGyYnclIuuZ9Miu56gtBSqL3YoYSYLFQJ4lEafHGAHV1fs_63HwToJ3kb1E6FYn6SF2YGCfnkiwoFfiA",
    "expiry":"1440"
    "errors": []
}

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.

{
    "status": "BAD_REQUEST",
    "message": "Unable to create customer v1: Validation failed for input provided",
    "errors": [
        "[\"The maximum length of email is 60 characters\"]"
    ]
}

caution

All corporate customers are required to have a unique business name and business registration number.

Bad request example with a non-unique name:

{
    "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.

{
    "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, 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 event.

To learn more about webhooks, see 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.
`REJECTED`	The corporate customer needs to resubmit the application to reinitiate 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. After the missing information is received, you receive this webhook event.

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.

note

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 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.

{
    "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 reinitiate 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.

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 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 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. For the complete list of RFI templates and required fields or documents by region, see the 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.

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

Regenerate KYC URL API

The KYC URL, which is returned in the response of the Onboard Corporate Customer API, has an expiration time. Once expired, the link cannot be used to complete applicant KYC. Use the Regenerate KYC URL API to generate a new URL with a new expiration time.

This API can be used when applicantDetails.kycMode is the following:

E_DOC_VERIFY in any region
E_DOC_VERIFY or E_KYC in Singapore

A diagram of the journey for applicant KYC.

Identifying an expired link

An expired link can be identified in the below ways:

When an applicant is trying to click on the link, you can check the expiry based on the expiry field in the response of Onboard Corporate Customer API. In case of expiry, you can regenerate a new URL using the Regenerate KYC URL and direct the applicant to the new redirect URL.
When an applicant is redirected to the redirect URL received in the Onboard Corporate Customer API, despite being expired, the applicant lands on the browser and is redirected back to the client to the configured client KYC redirect URL with the following parameters. Customer do not see the vendor UI in this case.

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 URL expired scenario, the redirect URL contains:

errorCode=R408
errorMessage=redirectURLExpired

When you detect the above values, regenerate a new URL using the Regenerate KYC URL API and advise the applicant accordingly. You can save this URL and redirect the applicant until it is expired again.

caution

Once a new redirectURL is generated, the old URL is auto-expired and cannot be used anymore.

Update Corporate Customer API

After the onboarding is complete and the customer is approved, the Update Corporate Customer 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.

caution

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.

Note

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.

note

Once the Update Corporate Customer API the complianceStatus changes to ACTION_REQUIRED, the customer status remains CLEAR which will allow the customer to transact.

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

Introduction​

Onboarding process flow​

Definitions​

Region-specific KYB and KYC offerings​

Australia — AU onboarding​

European Union — EU onboarding​

Hong Kong — HK onboarding​

Japan — JP onboarding)​

New Zealand— NZ onboarding​

Singapore — SG onboarding​

United Kingdom — UK onboarding​

United States — US onboarding​

Other Countries — SG onboarding​

Implementation​

Submission of information​

Onboard API response​

200 response​

Response example for IN_PROGRESS with redirectUrl​

400 response​

errorDetails object​

Webhooks​

complianceStatus field​

status field​

RFI process​

Terms and Conditions​

Regenerate KYC URL API​

Identifying an expired link​

Example of a redirect to the client in a failed case​

Update Corporate Customer API​

Note​

Region businessType matrix​

Introduction

Onboarding process flow

Definitions

Region-specific KYB and KYC offerings

Australia — AU onboarding

European Union — EU onboarding

Hong Kong — HK onboarding

Japan — JP onboarding)

New Zealand— NZ onboarding

Singapore — SG onboarding

United Kingdom — UK onboarding

United States — US onboarding

Other Countries — SG onboarding

Implementation

Submission of information

Onboard API response

200 response

Response example for `IN_PROGRESS` with `redirectUrl`

400 response

`errorDetails` object

Webhooks

`complianceStatus` field

`status` field

RFI process

Terms and Conditions

Regenerate KYC URL API

Identifying an expired link

Example of a redirect to the client in a failed case

Update Corporate Customer API

Note

Region `businessType` matrix