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, you can start onboarding your customers.

To onboard customers, you 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 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. 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.

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 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 to determine if the Fetch Public Details or Fetch Exhaustive Corporate Details requests are available:

• Fetch Public Corporate Details
• Fetch Exhaustive Corporate Details

Step 4: Upload required documentation

Use the Create a File 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

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 for the applicant and all stakeholders, including any missing details or documents.
• Submit KYC API: Use the Submit KYC 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 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 request, except for the authenticationCode, which is required if you are 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 when the application is initially 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.
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.	No further action is possible. Contact Nium Support if you need to reopen an account.
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 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"
    }
  ]
}

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

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

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

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

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.

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

For individual customers

• Update any customer field.
• Update or replace addresses.
• Update bank account details