Skip to main content

Hosted Onboarding

Overview​

Noah Hosted Onboarding streamlines compliance for non-licensed payment providers operating in Standard Model KYC scenarios. Through this solution, Noah establishes direct contractual relationships with your end customers, handling all KYB/KYC verification and Terms and Conditions acceptance on your behalf.

Use the POST onboarding/:CustomerID endpoint to initiate the onboarding flow.

There are multiple responses returned, based on the outcome of the onboarding process:

  • 200: Hosted onboarding session request successful. A HostedURL field is returned which can be used to redirect the customer to the hosted onboarding session. If some customer data has previously been prefilled, the OnboardingStatus and MissingSteps fields expose more information on what is still required to complete the onboarding. The OnboardingStatus field indicates an action is required to complete the onboarding. The MissingSteps field lists the verification step types that are still incomplete (e.g. IDENTITY, SELFIE, QUESTIONNAIRE). Only present when OnboardingStatus is ReviewNotStarted and the applicant has not yet submitted all required data.

  • 201: Customer onboarded. The customer was created and approved for all of the available fiat options.

  • 202: Onboarding in progress. No further data is required at this point, and the review is being processed asynchronously. A customer webhook will be sent when the review is complete or has advanced to the next step. The Verifications object contains the current verification state for the customer, including all required entity verifications that are still in progress.

    For more details on this process, see the Compliance Overview.

Example Scenario​

Consider a non-licensed fintech application onboarding a new business customer for cross-border payments:

Setup:

  • CustomerID: Business identifier matching your internal system
  • Type: Business entity requiring KYB verification
  • Onboarding: Noah-hosted verification flow
  • Compliance: Direct contractual relationship with Noah

Key Implementation Features:

  • Automated KYB/KYC verification managed by Noah
  • Terms and Conditions acceptance handled through hosted flow
  • Secure onboarding session creation via API
  • Regulatory compliance without licensing requirements
tip

Be aware of Noah's integration with Sumsub, as explained in Token Share Onboarding.

Recipe​

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

1. Access Your Business Dashboard

Connect With Our Team​

  • Contact us at business@noah.com or fill out our First Contact Form.
  • A Noah representative will then reach out to assess your business needs and discuss the best integration model.

Register Your Sandbox Account​

  • Register for a standard Noah account through our Business App using the business email address responsible for your integration with Noah. Note that you can register directly by clicking here, without needing approval to do so.
  • Notify your Noah Business contact, once registered, they will ask for the email address you registered with.
  • We will upgrade your account to access our Business Dashboard, this will enable your access to the Business Dashboard.

Kick-Off Your Onboarding​

  • Your Noah Business contact will be in touch to kick-off your Onboarding process.
  • During this stage, we initiate Know Your Business (KYB) checks and Onboarding review based on your institution. You can still begin your integration and test in the sandbox while the Onboarding is in progress.
tip

For more on KYB and Onboarding, see Compliance Models.

2. Generate your API Key

Once your Business account has been provided:

  • Log into your Business account at business.sandbox.noah.com.
  • Navigate to Configuration → API → API Keys → Create New
  • You can provide a Label to identify a specific API Key.
  • Expiry Dates are optional, if you provide one, your API Key will become invalid as of the date you have set.
tip

Review the Authentication docs for details on using your API key securely.

Public Keys & Request Signing

Request Signing is optional in Sandbox and required in Production - providing a Public Key when generating your API Key, will enable Request Signing. We recommend that you enable Request Signing before migrating to Production.

Read more about Request Signing →

3. Initiate a Hosted Onboarding Session

Submit a call to the POST onboarding/:CustomerID endpoint.

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://.

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"}
4. Direct the Customer to Hosted Onboarding

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

5. Customer Status Updates via Customer Webhook Events

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

For more details, see Customer Event.

6. 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.
7. Begin Your Integration

After successfully creating a customer, it’s time to run through our integration recipes for detailed guidance on your chosen use case:

  • Bank Onramp via Virtual Accounts – Accept bank transfers in fiat and receive near-instant settlement in crypto.
  • Global Payouts – Convert crypto and stablecoins to fiat, and disburse funds using local payment methods.
  • Automated Payouts - Accept deposits in crypto or stablecoins, and automatically payout fiat to local payment methods.
  • Hosted Checkout – Offer a streamlined payment interface to your customers to accept or payout fiat in 120+ currencies.
8. Migrate to Production

Our team are available to support you through the integration and onboarding process to ensure a smooth migration to production. Once your Onboarding and KYB procedures are complete, we will work closely with you to prepare for a migration to production, and perform the required testing.

We’ll guide you through this transition to ensure everything is optimized for a frictionless production launch.

tip

Additional Resources​

• Compliance & Identity – Dive deeper into KYC and AML requirements.
• API Reference – Full endpoint documentation, request/response schemas, and usage notes.

For questions or additional support, reach out anytime at business@noah.com.