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 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 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 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	A Spend Management Child Customer is an employee of a corporate customer who is issued a corporate card. KYC requirements for cardholders are simplified. In addition to standard KYC, employees must provide an employment letter for verification.

Employees (corporate program)

Employees onboarded under a corporate program follow the individual-customer flow. 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	Simplified KYC for card issuance. An employment letter is required in addition to standard KYC.

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 two ways:

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.

note

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 Compliance Status webhook. 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.
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 lets you prefill business and stakeholder data in your form for supported regions.
Check the region-specific guide to determine if the Fetch Public Details or Fetch Exhaustive Corporate Details requests are available:

Step 4: Upload required documentation

Use the Upload Document for Corporate Customer request to upload the necessary documentation.

Step 5: Submit onboarding application

Use the Create Customer v5 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.
  - 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

If manual KYC 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 pending
The subStatus updates to under_review

Step 6: Complete KYC verification

Ask your customer to complete the hosted KYC form for the applicant and all stakeholders, including any missing details or documents.

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

note

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.

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 updates to under_review when initially submitted.
The status then updates to either clear or rejected once review is complete.
- RFIs may occur at pending or after clear.

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 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.	Start processing 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, use the Update Customer v5 request to restart onboarding.
`terminated`	—	The customer account has been terminated by Nium compliance.	No further action is possible.

Webhooks

After receiving the Create Customer v5 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

{
  "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 (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 Hosted RFI Form or call the Respond to RFI request depending on your integration.

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

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

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

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

Use the Update Customer v5 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 response, or fetch the details using the Fetch Public Corporate 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 the future).

For individual customers

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

Customer types​

Corporate customers​

Individual customers​

Employees (corporate program)​

Verification methods​

Businesses (KYB)​

Individuals (KYC)​

Onboarding customers​

Step 1: Configure 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: Complete KYC verification​

Step 7: Compliance review and RFIs​

Step 8: Update application​

Update customer details​

Status lifecycle​

Webhooks​

Example event​

Requests for Information (RFIs)​

Response codes​

200​

400​

400 error codes​

Ongoing due diligence (ODD)​

ODD process​

Example event​

Update customer​

For corporate customers​

For individual customers​

Customer types

Corporate customers

Individual customers

Employees (corporate program)

Verification methods

Businesses (KYB)

Individuals (KYC)

Onboarding customers

Step 1: Configure 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: Complete KYC verification

Step 7: Compliance review and RFIs

Step 8: Update application

Update customer details

Status lifecycle

Webhooks

Example event

Requests for Information (RFIs)

Response codes

200

400

400 error codes

Ongoing due diligence (ODD)

ODD process

Example event

Update customer

For corporate customers

For individual customers