Token Share Onboarding

Overview

Token share onboarding enables you to share pre-existing KYC data for a customer's onboarding session using Sumsub token sharing, requiring the CustomerID and customer verification information from authorized partner organizations to avoid duplicate verification processes.

The POST onboarding/:CustomerID/prefill endpoint leverages NOAH's integration with the Sumsub identity verification service through triparty agreements, enabling transfer of verified applicant data via cryptographically secured tokens that include compliance profiles, documents, and verification status while meeting regulatory requirements. The system automatically identifies missing information needed for compliance and requests only the additional data required through dynamic forms or hosted onboarding sessions, significantly reducing redundant verification processes.

Note: The endpoint does not include or collect NOAH's Terms and Conditions. After using the POST onboarding/:CustomerID/prefill endpoint, use the POST onboarding/:CustomerID endpoint to collect the customer's acceptance of the platform's Terms and Conditions as part of the onboarding process. This is a regulatory and compliance requirement because financial services platforms need documented proof that customers have read and agreed to the legal terms governing their use of the service. Similarly, the list of fiat options to be supported by the customer can only be set via the POST onboarding/:CustomerID endpoint. See the Hosted Onboarding recipe for details because the fiat options and the required regulatory and compliance agreements can only be captured in the hosted onboarding session.

Example Scenario

Imagine a customer who has already completed KYC verification with one of Noah's partners and now wants to use your platform. Instead of going through the entire verification process again, you can leverage their existing KYC data to reduce onboarding time. The customer only needs to provide any additional information specific to your service, while their identity verification, document checks, and compliance requirements are already satisfied through the shared verification data.

Recipe

Implement a scenario as described above by following the steps below.

1. Provide a Sumsub Token

Provide a Sumsub token via the POST onboarding/:CustomerID/prefill endpoint, as described in KYC Platform. In this step, you query the POST onboarding/:CustomerID/prefill endpoint, selecting the SumSubToken type:

curl -L 'https://api.sandbox.noah.com/v1/onboarding/:CustomerID/prefill' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
  "Type": "SumSubToken",
  "Token": "string"
}'

As can be seen above, in your request, include your API Key in the header, along with a CustomerID.

Once compliance profiles are added to Sumsub, any missing information can be requested via Dynamic Forms and/or a dynamic Hosted Onboarding session, as defined in the next step. For details, see KYC Platform.

2. Initiate a Hosted Onboarding Session

Submit a call to the POST onboarding/:CustomerID endpoint, to collect the prerequisite Terms and Conditions acceptance from your customer (and any missing data as per the token share):

curl -L 'https://api.sandbox.noah.com/v1/onboarding/:CustomerID' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
  "Metadata": {},
  "ReturnURL": "https://example.com",
  "FiatOptions": [
    {
      "FiatCurrencyCode": "USD"
    }
  ]
}'

As can be seen above, in your request, include your API Key in the header along with a CustomerID, the URL to which the user is redirected at the end of the Hosted Onboarding session, and the list of fiat options to be supported by the customer.

note

NOAH expects a full ReturnURL value, including the https://.

View the POST onboarding/:CustomerID endpoint for detailed instructions on initiating a session.

The response will consist of a HostedURL, where the Hosted Onboarding session is ready for the customer to enter their details:

{"HostedURL":"https://checkout.sandbox.noah.com/kyc?session=xyz"}

3. Direct the Customer to Hosted Onboarding

Redirect your customer to the HostedURL to enter their details in the Hosted Onboarding session.

4. Customer Status Updates via Webhooks

Set up to receive notifications through webhooks about the status of the Hosted Onboarding session, which can be Pending, Approved, or Declined.

For more details, see Customer Webhooks.

5. Close the Hosted Onboarding Session

NOAH emits a postMessage once the onboarding process is complete. You can listen to this event in your application, as follows:

window.addEventListener('message', (event) => {
  if (event.data?.type === 'kycCompleted') {
    closeHostedSession(); // <-- Replace this with platform-specific close method
  }
});

tip

• The message sent is: { type: 'kycCompleted' }
• It is sent once a valid KYC review status is detected.