NZ onboarding

Overview

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

Nium offers eKYB flow for customers in New Zealand.

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.

eKYB flow

The following steps are required to complete the eKYB application.

Step 1. Call Onboard Corporate Customer API

You need to collect all the details required to call the Onboard Corporate Customer API through an onboarding form and call it with the full request body.

Applicant KYC

New Zealand supports all three KYC flows, (E_KYC,E_DOC_VERIFY and MANUAL_KYC). You need to pass the following parameter in the businessDetails.applicantDetails.kycMode object:

• E_KYC for New Zealand residents
• E_DOC_VERIFY for non-New Zealand residents

If required, you can use Manual_KYC for non-New Zealander residents, but those applications go through manual review and cannot be verified in real time. Document details are mandatory for all KYC modes but uploading documents is mandatory only forMANUAL_KYC mode which needs to be sent in the businessDetails.applicantDetails.documentDetails object. For details, see NZ required documents for applicants.

Upon submission, the status in the response of the Onboard Corporate Customer API is IN_PROGRESS.

If any documents are required, the applicant needs to upload them to proceed further. Once done, Nium initiates real-time verification and sends the response via a webhook. The application can be approved at this stage. If it can't be approved, it goes through manual review.

Any changes in thestatus is communicated via a webhook. For the next steps based on the response of a webhook, see Webhooks.

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. The applicant then lands on the 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.

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&isSucces=true&errorCode=&errorMessage=

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&isSucces=false

For applicants where the businessDetails.applicantDetails.address.country is US, the applicant's address' state needs to be a valid 2 letter state code. Use 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.

⚠️

CAUTION

There's an expiration time for the redirectURL so the applicant needs to complete the process soon after submitting the application.

If the URL expires, the applicant is redirected to your configured client KYC redirect URL with an error message. Use Regenerate KYC URL API to get a new URL with a new expiration time.

Stakeholder KYC

The E_KYC and MANUAL_KYC modes are offered for KYC of Individual stakeholders in the eKYB flow in New Zealanders.

For stakeholders, you pass E_KYC (for NZ residents) or MANUAL_KYC (for non-NZ residents) in businessDetails.stakeholders.stakeholderDetails.kycMode.

Applications with MANUAL_KYC go through manual review and cannot be verified in real-time.

Document details are mandatory for all KYC modes but uploading of documents is mandatory only for MANUAL_KYC which has to be sent in businessDetails.stakeholders.stakeholderDetails. See NZ required documents for details.

Upload documents, if required

If no results are returned as part of the Public Corporate Details Using Business ID API for the particular businessRegistrationNumber, you need to upload documents since Nium doesn't retrieve certain required information from some of its sources.

If the Public Corporate Details Using Business ID API returns a match, you generally don't need to upload documents. However, even in this flow, there might be a particular scenario that requires the applicant to provide some documents.

Documents can be submitted either of two ways:

• As part of the Onboard Corporate Customer API
• Via the Upload Document 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 is expecting, 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 KYB and eKYB flows, see NZ 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.

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.