Guides
Start typing to search…

Self Hosted Customer Onboarding

Overview

Self-Hosted Onboarding allows partner platforms to embed 1money's KYB (Know Your Business) verification flow directly into their own user experience. Instead of building a full KYB form from scratch, platforms redirect their end users to a 1money-hosted onboarding page where they can complete the entire verification process.

Key benefits:

  • Minimal integration effort (4 API calls + 1 redirect)
  • 1money handles all KYB form UI, validation, document upload, and identity verification
  • Platforms retain control over customer lifecycle via OpenAPI
  • Real-time status polling to track verification progress

Related OPENAPI Endpoint:

If you would like to understand the accepted parameters and response for each API, or learn more about the detailed workflow and logic of the APIs, please click on each endpoint for a more detailed explanation.

Architecture

Integration Steps

Prerequisites

  • A valid 1money OpenAPI key pair (API Key + API Secret)
  • Self-hosted onboarding feature enabled for your entity (contact 1money support)

Step 1: Create a Lightweight Customer

Create Customer for Hosted Onboarding

Create a customer record with minimal information. The end user will fill in the remaining details during the hosted onboarding flow.

Notes:

  • customer_type: Use BUSINESS for corporate customers (B2B2B) or INDIVIDUAL for individual customers (B2B2C). Note that, Currently, only BUSINESS available in our platform. INDIVIDUAL is on the roadmap.
  • The Idempotency-Key header is required. If a customer with the same idempotency key already exists, it will be returned without creating a duplicate. Only a valid UUID is accepted.
  • Save the customer_id for subsequent API calls.

Step 2: Create an Onboarding Grant

Create Onboarding Grant

Generate a one-time-use grant token that produces a hosted onboarding URL for the end user.

Notes:

  • redirect_url (optional): Where the user is redirected after completing or canceling the onboarding. If omitted, the user stays on the 1money page after submission.
  • locale (optional): UI language for the onboarding page. Default: en-US.
  • The grant token expires after 30 minutes by default. If it expires, create a new one.
  • Grant tokens are single-use — once exchanged, the token cannot be reused. Create a new grant if the user needs to restart.

Step 3: Redirect the End User

On your frontend, redirect the end user's browser to the onboarding_url returned in Step 2.

What happens after redirect:

  1. The user's browser hits the onboarding_url, which exchanges the grant token for a secure session cookie.
  2. The user is automatically redirected to the hosted onboarding page.
  3. First visit (profile not yet completed): The user is taken to the Company Profile page to enter basic business information (company name, country of incorporation, industry, etc.).
  4. Profile already completed: The user is taken directly to the KYB form page.
  5. The user fills in the full KYB application:
    • Company information
    • Related parties (beneficial owners, controllers, signers)
    • Document uploads
    • Identity verification
  6. After submission, the user is redirected back to your redirect_url (if provided).

Step 4: Listen or Poll Customer Status

After the user is redirected back to your platform, poll the customer status to track verification progress.

Webhook: Customer Webhook

Fetch Status: Get Hosted Customer by ID

Step 5: Handle Re-Entry (Optional)

If a user needs to return to the onboarding flow (e.g., to fix issues after PENDING_RESPONSE status, or if they abandoned the form midway), simply create a new onboarding grant for the same customer_id:Create Onboarding Grant

The user will be redirected to the onboarding page with their previously saved progress intact.

FAQ

Q: Can I create multiple customers with the same email?

A: No, email addresses must be unique within your entity. Attempting to create a duplicate will return a 400 error.

Q: What happens if the grant token expires?

A: Create a new grant with POST /v1/customers/onboarding/grants using the same customer_id. Any previously saved form data is preserved.

Q: Can the user resume an incomplete onboarding?

A: Yes. Create a new grant for the same customer_id. The user's previous progress (company info, related parties, uploaded documents) is automatically restored.

Q: How long is the hosted session valid?

A: The browser session is valid for 24 hours after the grant token is exchanged. If the session expires, create a new grant.

Q: Does the user receive any emails during onboarding?

A: No. The self-hosted onboarding flow does not send invitation or notification emails to the end user. All communication is handled by the partner platform.

Q: What webhooks are available?

A: After KYB submission, a kyb.pending webhook event is sent to your registered webhook URL. Additional status-change webhooks may be available — check the Webhooks documentation for details.

Updated about 8 hours ago