Customer Onboarding

Nium is introducing anew version of our Customer Onboarding requests. This new version (Version 5) provides a unified and streamlined approach to onboarding both corporate and individual customers (across multiple regions) using a single request.

This new request offers region specific data transfer objects (DTO) all seamlessly handled by Nium''s backend.

Compared to previous versions, Version 5 introduces:

A single onboarding request for all type of customers. This includes
- Corporate customers
- Individual customers
- Employee onboarding for spend management and payroll.
Region-specific DTOs that's flexible and compliant.
Transparent validations for fields and documents.
A standardized address object.
A clearer, optimized structure to enable faster onboarding and an improved developer experience.
An API and form based experience that includes:
- Regional Know Your Customer (KYC) request and/or documentation requirements handled within a single form.
- Pre-build verification flow that you can use to improve your customer's experience.

Customer Onboarding

Customers (also called clients) are broadly divided into 3 types in Nium:

Corporate customers
Individual customers
Employees of a corporation

Currently, after clients with customers complete their integration, the next step is to onboard their customers.

To onboard customers, clients submit a customer application using the Unified Add Customers request. Nium then verifies the customer in accordance with local Know your Customer (KYC) and Know your Business (KYB) regulatory requirements.

After they submit their application, customers have to wait until Nium verifies their details before they can start transacting.

Corporate Customers

The following defines 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 regional regulatory requirements.
Child Customer – Payroll	Payroll Child Customers are employees of a corporate customer who receive payroll payments through Nium. KYC requirements for payroll employees are similar to those for individual customers.
Child Customer – Spend Management	Spend Management Child Customers are employees of a corporate customer who are issued a corporate card. KYC requirements for cardholders are simplified. In addition to standard KYC, employees must provide an employment letter for verification.

Corporate Customers

The following table defines 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 applicable regional regulations.
Applicant	An Applicant is the individual who submits the onboarding application on behalf of the corporate customer. The applicant is typically an authorized representative or signatory of the business. As part of onboarding, the applicant must complete Know Your Customer (KYC) verification to meet compliance requirements.
Stakeholder	A Stakeholder is any individual or entity listed in the business’s official registration documents—such as a director, officer, ultimate beneficial owner (UBO), control person, or shareholder. All stakeholders must be disclosed during onboarding. Nium requires complete information for each stakeholder and performs KYC verification in line with regional regulations. Stakeholders may be either natural persons (individuals) or legal entities (businesses).

Employees of a Corporate Program

The following table defines the entity types related to employees participating in a corporate program with Nium.

Entity Type	Definition
Corporate Customer – Payroll	Corporate Employee Customers are employees of a corporate customer who receive payroll payments through Nium. KYC requirements for payroll employees are similar to those for individual customers.
Corporate Customer – Spend Management	Spend Management Corporate Employee Customers are employees of a corporate customer who are issued a corporate card. KYC requirements for cardholders are simplified. In addition to standard KYC, employees must provide an employment letter for verification.

Verification Methods

Businesses (KYB)

The different ways business cane verify their details include:

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)

The different ways Individuals cane verify their details include:

Electronic KYC:
Enables real-time identity verification using region-specific electronic methods.
Verification speed and data sources may vary by geography.
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: Configuration your Client account

Configure your client account with your Nium account manager.
Integrate with the Customer Status webhook.
- Whitelist the required IP addresses.

Step 2: Regulatory Region

A client account must exist in the corresponding region before you can onboard customers.
For Region-specific KYB and KYC offerings, see the relevant Nium Playbook page.

Regions

Customer Registered Country	Regulatory Region
GB, Switzerland, Monaco	UK
EEA countries	EU or NL (preferred)
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 enables you to you to prefill business and stakeholder data into your form for certain regions. Check region specific guides to for the availability of Public Details API and Exhaustive Details API.

Nium enables you to prefill business and stakeholder data into your forms for certain regions.

See the Fetch Public Details and Exhaustive Corporate Details Using Business ID requests for more details.

Step 4: Upload Required Documentation

Use the Upload Document request to upload the necessary documentation.

Step 5: Submit Onboarding Application

Use the Onboard Corporate Customer V5 request using the data from Step 3 if it wasn't prefilled. Data that's required includes:

Customer Information
Registered Business Address
Business Details
Applicant & Stakeholder Details
- Document details using the fileId from Step 4.
  - Business documents for corporate applicants and a Letter of Authorization.
  - For employee onboarding, and employment Letter.

Once submitted, Nium performs electronic verification on all directors and stakeholders.

If additional KYC is required for any entity—such as the applicant or a stakeholder—the client receives a webhook with

status as pending.
substatus as awaiting_kyc.

If KYC is required, then the webhook returns:

status as pending.
substatus as under_review if manual review is required.

Step 6: Submit Onboarding Application

Use Nium's Onboarding Forms to complete verification for the applicant and all stakeholders.

Once verified:

The status stays as pending.
The substatus updates to under_review.

Step 6: Compliance Review and RFIs

At this point, Nium's compliance team reviews the application.

If additional information is required, a Request for Information (RFI) gets raised.

If the review is successful, the application status updates to clear. This means the customer is approved and ready to begin transacting.

Step 7: Updating an Application

Once the application status is clear or rejected, you can use the Update Corporate Customer V5 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.

Note

The request body structure is the same as the Onboard Customer v5 request, except for the authenticationCode, which is mandatory for clients in the EU/UK/NL as part of regulatory requirements.
Always submit the complete request body with the latest details, including all supporting documents.

Statuses

Status	Substatus	Remarks	Next Action
`pending`	`awaiting_kyc`	Application submitted and awaiting KYC completion.	The customer must complete verification for all applicants and stakeholders in the hosted KYC form.
`pending`	`under_review`	Application under review by Nium.	Wait for Nium to take further action.
`error`	—	The application encountered an error.	Contact Nium technical support.
`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.	Begin transactions.
`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.	To reopen the account, call the Update Customer request to reinitiate onboarding.
`terminated`	—	The customer account has been terminated by Nium compliance.	No further action is possible.

Webhooks

After receiving the response from the Onboard Customer V5 request, Nium sends a webhook event to the configured client URL whenever there is a change in status or substatus.

Look for the corresponding template in the webhook event response under CUSTOMER_STATUS_WEBHOOK.

Example response

{
  "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"
    }
  ]

For more information, see Notifications and Webhooks.

Requests For Information

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 Respond to RFI request and submit the requested information.

For more information, see Responding to RFIs.

Response Codes

Perform the following actions based on the returned HTTP status code:

HTTP Code	Next Step
`200`	Check the status lifecycle to determine the next action.
`400`	Correct the data and resubmit the application.
`500`	Internal server error. Retry the onboarding request.

200

After submitting the Onboard Customer 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 request.

Review the errors field in the response, correct the customer details, and resubmit the request.

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

Ongoing Due Diligence (ODD) Process

When a customer is undergoing Ongoing Due Diligence (ODD), the following occurs:

When ODD becomes due
- The status field remains clear.
- The oddStatus is set to odd_due.
  Customers can continue to process transactions as usual during this period.
Customers should review and update any outdated information, if applicable.
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 to respond to these requests.
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.

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 Response

{
    "clientHashId": "86ce8d7b-f3fa-46d5-8d1c-53212aade5b5",
    "customerHashId":"857dc08e-dffa-4e9a-ad96-79041c8a7025",
    "externalId":"875329"
    "oddStatus":"odd_due",
    "template": "CUSTOMER_ODD_STATUS_WEBHOOK",
    "customerType":"corporate"
}

Update Customer Details

The Update Corporate Customer request enables you to modify information for both 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 Unified Add Customer response, or fetch the details using the Customer Details request.
Update any applicant field (requires the referenceId as above).
Update any business-related field.
Update or replace addresses.
Update bank account details (not currently supported; will be enabled in future releases).

For Individual Customers

Update any customer field.
Update or replace addresses.
Update bank account details (not currently supported; will be enabled in future releases).

Customer Onboarding​

Corporate Customers​

Individual Customers​

Corporate Customers​

Employees of a Corporate Program​

Verification Methods​

Businesses (KYB)​

Individuals (KYC)​

Onboarding Customers​

Step 1: Configuration your Client account​

Step 2: Regulatory Region​

Regions​

Step 3: Prefill Data (optional)​

Step 4: Upload Required Documentation​

Step 5: Submit Onboarding Application​

Step 6: Submit Onboarding Application​

Step 6: Compliance Review and RFIs​

Step 7: Updating an Application​

Update Customer Details​

Note​

Statuses​

Webhooks​

Example response​

Requests For Information​

Response Codes​

200​

400​

400 Error Codes​

Ongoing Due Diligence (ODD)​

Ongoing Due Diligence (ODD) Process​

Example Response​

Update Customer Details​

For Corporate Customers​

For Individual Customers​

Customer Onboarding

Corporate Customers

Individual Customers

Corporate Customers

Employees of a Corporate Program

Verification Methods

Businesses (KYB)

Individuals (KYC)

Onboarding Customers

Step 1: Configuration your Client account

Step 2: Regulatory Region

Regions

Step 3: Prefill Data (optional)

Step 4: Upload Required Documentation

Step 5: Submit Onboarding Application

Step 6: Submit Onboarding Application

Step 6: Compliance Review and RFIs

Step 7: Updating an Application

Update Customer Details

Note

Statuses

Webhooks

Example response

Requests For Information

Response Codes

200

400

400 Error Codes

Ongoing Due Diligence (ODD)

Ongoing Due Diligence (ODD) Process

Example Response

Update Customer Details

For Corporate Customers

For Individual Customers