SG Onboarding

This page contains details about the Singapore Know Your Business (KYB) flows and links to the following sub-pages for a quick reference:

Page name	Description
SG required fields	This page lists the required API fields of each entity type.
SG required documents	This page contains tables listing the required documents for verification of the business entity, stakeholders, and applicants.
SG position mapping	This page gives a quick glance at the required positions of each entity type.
SG request examples	This page contains API request examples for SG entities.

Nium offers eKYB and Manual KYB flows for customers in Singapore.

The eKYB flow is fully automated, allowing corporate customers to be approved within a few minutes of submitting their application, making it the preferred mode for all customers. Reach out to Nium's sales team to configure the eKYB flow for your account.

eKYB flow

The following steps are required to complete the eKYB application.

Step 1. Get Public Corporate Details Using Business ID API

To start the eKYB process, collect the basic details about the corporate customer from the applicant through an onboarding form, including the businessRegistrationNumber and countryCode. For a list of valid country codes, see Currency and country codes. Then call Nium's Public Corporate Details Using Business ID API.

This API returns publicly available information about the corporate customer, which you then display to the customer so they can select and confirm the businessName and businessRegistrationNumber along with any other optional details.

You need to store the searchReferenceId that's returned in this response since it's required in subsequent steps.

This API may return multiple results for a given businessRegistrationNumber. When there's more than one, display all the results to let the customer select the right one.

When no results are returned, you should call the Onboard Corporate Customer API with a full request body. Such applications go through manual review, making the eKYB process not applicable in this case.

2. Get Exhaustive Corporate Details Using Business ID API

Call the Exhaustive Corporate Details Using Business ID endpoint using the searchReferenceId stored in Step 1 as the parameter.

This returns the public and non-public information about the corporate customer.

You need to store the searchId that's returned in this response since it's required in the subsequent steps.

caution

This is a chargeable API. Work with your Nium representative before using it. It's best to use this API only once per customer.

Step 3. Display the information to the applicant

You need to display the above-received information to the applicant for their confirmation, edits, or additions. Then, submit the form. All the fields required to call the Onboard Corporate Customer API are collected in this step. Any additional fields that are required, and not returned in the above step, are to be added by the applicant.

Step 4. Post Onboard Corporate Customer API

You then call the Onboard Corporate Customer API with the full request body, including the searchId you stored in Step 2.

If the searchId parameter isn't passed, the application is treated as MANUAL_KYB and goes through a manual review.

Applicant KYC

In Singapore, the supported applicant methods for the eKYB flow are E_KYC, E_DOC_VERIFY, and MANUAL_KYC.

• You need to use E_KYC for Singaporean residents and E_DOC_VERIFY for non-Singaporean residents and pass that value in businessDetails.applicantDetails.kycMode.
• If required, you can use MANUAL_KYC for non-Singaporean residents, but those applications go through manual review and cannot be verified in real time.
  • The uploading of documents is required for MANUAL_KYC which has to be sent in the businessDetails.applicantDetails.documentDetails object. For details, see SG required documents.

E_KYC

As a response to the Onboard Corporate Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirectURL. The applicant then lands on the KYC vendor's page, where he can complete the KYC verification using Singpass authentication. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium.

Redirection can result in the following scenarios, based on the below parameters.

• errorCode
• errorMessage
• isSuccess – This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful.
• referennceId (used to identify the individual for whom redirection happened.)

Scenario	Expected action from client	Query parameters in the redirection
The applicant completed the required steps in the vendor’s UI.	Wait for webhook.	errorCode: N/A errorMessage: N/A isSuccess: TRUE
The customer has provided incorrect data in the vendor's UI. (customer didn't click accept in the vendor's page)	Ask customer to submit correct data in the vendors page.	errorCode: I400 errorMessage: vendorValidationError isSuccess: FALSE
Any unexpected error from the vendor.	Try after some time or reach out to Nium's support.	errorCode: I500 errorMessage: unexpectedError isSuccess: FALSE

Based on the scenario, you can implement the next steps as provided in the table above.

Example of a redirect to the client in a successful case

https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11-

f95c315ce83c&isSuccess=true&errorCode=&errorMessage=&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX

Example of a redirect to the client in a failed case

https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11-

f95c315ce83c&errorCode=I400&errorMessage=vendorValidationError&isSuccess=false&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX

Applicant E_DOC_VERIFY

As a response to the Onboard Corp Customer API, Nium returns a redirect URL. You need to save this URL and redirect the applicant to the redirectURL. Applicant then lands on our KYC vendor's page, where he can complete the KYC verification by uploading his proof of identity and proof of address documents with a live selfie. After that, applicants are redirected back to your client KYC redirect URL that was configured with Nium.

Redirection can result in the following scenarios, based on the below parameters.

• errorCode
• errorMessage
• isSuccess - This field indicates if the applicant completed the required steps in the vendor’s UI. It doesn't mean KYC is successful.
• referennceId (used to identify the individual for whom redirection happened.)

Scenario	Expected action from client	Query parameters in the redirection
The applicant completed the required steps in the vendor’s UI.	Wait for webhook.	errorCode: N/A errorMessage: N/A isSuccess: TRUE
The document has already been submitted in the vendor's UI.	KYC Process is completed. Client needs to wait for webhook.	errorCode: R403 errorMessage: documentAlreadySubmitted isSuccess: FALSE
The customer has provided incorrect data in the vendor's UI.	Ask customer to submit correct data in the vendors page.	errorCode: I400 errorMessage: vendorValidationError isSuccess: FALSE
Verification failure at the vendor.	The application goes to manual review. The client needs to wait for webhook.	errorCode: R401 errorMessage: vendorVerificationFailure isSuccess: FALSE
Internal Server error at Nium.	Try after some time or reach out to Nium's support.	errorCode: R500 errorMessage: internalServerError isSuccess: FALSE
Any unexpected error from the vendor.	Try after some time or reach out to Nium's support.	errorCode: I500 errorMessage: unexpectedError isSuccess: FALSE
Validation already completed and customer retries the same link.	KYC Process is completed. The client need to wait for webhook.	errorCode: R606 errorMessage: verificationAlreadyCompleted isSuccess: FALSE

Based on the scenario, you can implement the next steps as provided in the table above.

Example of a redirect to the client in a successful case

https://www.clientRedirectURL.com/?clientId=NIM1681898211881&caseId=4ff53849-3d30-45c8-af11-

f95c315ce83c&isSuccess=true&errorCode=&errorMessage=&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX

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&referenceId=247f2897-00ee-48f2-ad71-69be1887XXXXXX

When the applicant's businessDetails.applicantDetails.address.country is US, the applicant's address' state needs to be a valid 2 letter state code. Use the Fetch corporate constants API for acceptable values.

When the applicant's businessDetails.applicantDetails.address.country is GB, the applicant's postcode needs to be in the SW4 6EH format.

Stakeholder KYC

For the eKYB flow, Nium offers E_KYC, E_DOC_VERIFY and MANUAL_KYC for stakeholder verification.

• For resident stakeholders (address.country=SG), set E_KYC or MANUAL_KYC as kycMode based on stakeholder preference.
• For non-resident stakeholders set kycMode as E_DOC_VERIFY or MANUAL_KYC based on stakeholder preference.
  • E_DOC_VERIFY will require live-selfie and hence should be used only when stakeholder is accessible, similarly E_KYC will require singpass authentication.

For MANUAL_KYC include required documents in businessDetails.stakeholders.stakeholderDetails.documentDetails. Steps to implement stakeholder E_DOC_VERIFY or E_KYC redirectURL are similar to that of applicant mentioned above. For details on implementation, see Onboard API Response - 200 response

note

The referenceId available in the browser redirection is the same as the one submited in the Onboard API request for the stakeholder. In case, multiple stakeholders have redirectURL, you can use the referenceId to identify them and land them to the appropriate page as required.

Upload documents

If searchId isn't passed, a document upload is required. Even if searchId is passed, some documents might be required in certain scenarios. Nium doesn't initiate verification until all required documents are submitted.

All required documents can be submitted in two ways:

• Upload Document API.
• Onboard Corporate Customer API

The Upload Document API is preferred since it uploads one document at a time, which reduces the loading time. This API can be called only while the application is in the IN_PROGRESS state.

You can use the remarks field to list which documents Nium expects in the response of both APIs.

caution

The API gateway has a limit of 10 MB for any API request. This makes Upload Document API the preferred way to upload documents since you can upload one document at a time.

For the entire list of required documents for manual and eKYB flows, see SG required documents.

Terms and Conditions

You must show customers the Nium terms and conditions configured for your client resource. You can fetch these specific terms and conditions using our Terms And Conditions API.

Customers can only submit the onboarding form once they accept the terms and conditions.

To fetch the Terms And Conditions API:

1. Wait for the Onboarding API to return a customerHashId.
2. Once returned, call our Accept Terms and Conditions API and include the customerHashId.
3. Show the customer the returned terms and conditions and record their acceptance before allowing them to transact.

For more details, see Terms and Conditions.

Step 5. Wait for webhook response

After submission, the status in the Onboard Corporate Customer response is IN_PROGRESS. The applicant needs to complete both the Applicant KYC and Upload documents steps to proceed further. Once done, Nium initiates real-time verification and sends the response via a webhook.

The application might be approved at this stage; and if it isn't approved, the application goes through a manual review. Any changes in the status is again communicated via a webhook. For the next steps based on the response of the webhook, see Webhooks.

Manual KYB flow

For manual KYB, you need to call the Onboard Corporate Customer API directly. In this flow, the entire request body needs to be passed in the Onboard Corporate Customer API.

Important points to keep in mind:

• Nium doesn't initiate verification until all required documents are submitted.
• Use E_KYC, MANUAL_KYC for resident applicants and E_DOC_VERIFY or MANUAL_KYC for non-residents.
• Use E_KYC, MANUAL_KYC for resident stakeholders and E_DOC_VERIFY or MANUAL_KYC for non-residents based on stakeholder preference.
• E_DOC_VERIFY will require live-selfie and hence should be used when stakeholder is accessible. Similarly E_KYC will require Singpass authentication.
• Include required documents in businessDetails.stakeholders.stakeholderDetails.documentDetails for MANUAL_KYC.
• Terms and Conditions flow is same mentioned in the eKYB flow.

After submission, the status in the response of the Onboard Corporate Customer API is IN_PROGRESS. Once documents are uploaded and the KYC completes, Nium initiates manual verification and sends the response via a webhook.

For the next steps to take to onboard your customer, see the response returned in the webhook.