UK onboarding


This page contains details about the United Kingdom Know Your Customer (KYC) flows and links to the following sub-pages for quick reference:

Page nameDescription
UK required parametersThis page lists the required API fields for onboarding an individual customer.
UK required documentsThis page contains tables listing the required documents for verification of an individual customer.
UK request examplesThis page contains API request examples for onboarding an individual customer in the UK regulatory region.

eDocVerify – UK

When using the Unified Add Customer API to add a customer in the United Kingdom, eDocument verification is performed.

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.
  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 as per the 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.

ScenarioExpected action from clientQuery parameters in the redirection
The customer completed the required steps in the vendor’s UI.You receive a callback from Nium.errorCode: N/A

errorMessage: N/A

isSuccess: true
The redirect URL expires due to timeout.Reinitiate the onboarding request.errorCode: R408

errorMessage: redirectURLExpired

isSuccess: FALSE
The document has already been submitted in the vendor's UI.KYC process is complete. You receive a callback from Nium.errorCode: R403

errorMessage: documentAlreadySubmitted

isSuccess: FALSE
The customer has provided incorrect data in the vendor's UI.Ask your customer to submit correct data in the vendors page.errorCode: I400

errorMessage: vendorValidationError

isSuccess: FALSE
Verification failure at the vendor.The application is sent for manual review.errorCode: R401

errorMessage: vendorVerificationFailure

isSuccess: FALSE
Internal server error at Nium.Ask your customer to try after some time or reach out to Nium support.errorCode: R500

errorMessage: internalServerError

isSuccess: FALSE
Any unexpected error from the vendor.Ask your customer to try after some time or reach out to Nium support.errorCode: I500

errorMessage: unexpectedError

isSuccess: FALSE
Validation already completed and customer retries the same link.KYC process is complete. You receive a callback from Nium.errorCode: R606

errorMessage: verificationAlreadyCompleted

isSuccess: TRUE

Example of a redirect to the client in a successful case

Example of a redirect to the client in an unsuccessful case