Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt

Use this file to discover all available pages before exploring further.

The hosted link integration is the fastest way to onboard customers in SpherePay. Instead of building a custom verification UI, you create a customer via the API, retrieve a hosted link, and redirect your customer to complete their full verification on a SpherePay-managed page. The hosted experience handles document upload, face liveness verification, and all required questions in a single flow. This approach works for both individual customers (KYC) and business customers (KYB).
Use the hosted link approach for the fastest time to integration. It requires minimal frontend work — you only manage the initial API call and the redirect.

​
When to use this approach

The hosted link is ideal when:
  • You want to integrate quickly without building a custom onboarding UI
  • You prefer to delegate document upload, liveness checks, and OTP to SpherePay
  • You are prototyping or running an initial launch before investing in a fully custom flow
If you need complete control over the data collection experience or want to embed verification steps directly inside your product, use the API-based integration instead.
Pick a single integration method for each customer. Do not mix the hosted link and API approaches for the same customer, or fall back to one if the other fails — this will result in an unsuccessful onboarding.

​
How it works

  1. You call POST /v2/customer to create a customer record with basic contact details.
  2. You call the TOS link endpoint in parallel to generate a Terms of Service acceptance link.
  3. You call the KYC/KYB link endpoint to generate a hosted verification link.
  4. You redirect or send the link to your customer.
  5. The customer completes the entire verification process on the hosted page.
  6. You poll GET /v2/customer/{id} to detect when the verification profile reaches approved.

​
Step-by-step guide

1

Create a customer

Call POST /v2/customer with the customer’s basic contact information and address. For the hosted link path, you do not need to include personalInformation — the customer enters that information on the hosted page.For individual customers:
{
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "address": {
    "line1": "233 South Wacker Drive",
    "line2": "Suite 4700",
    "city": "Chicago",
    "postalCode": "60606",
    "state": "IL",
    "country": "USA"
  }
}
For business customers:
{
  "type": "business",
  "email": "contact@acmecorp.example.com",
  "phone": "+14155551234",
  "addresses": [
    {
      "type": "registered",
      "country": "USA",
      "line1": "123 Main Street",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60601"
    },
    {
      "type": "operating",
      "country": "USA",
      "line1": "456 Market Street",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60602"
    }
  ]
}
Save the id from the response — you’ll need it in the next steps.
2

Generate a Terms of Service link

Generate a TOS link and redirect the customer to accept the Terms and Conditions. This step can be done in parallel with generating the KYC/KYB link.
POST https://api.spherepay.co/v2/customer/{id}/tos-link
Redirect the customer to the returned URL to complete TOS acceptance.
3

Generate the hosted KYC or KYB link

In parallel with the TOS step, generate the hosted verification link for your customer.
POST https://api.spherepay.co/v2/customer/{id}/kyc-link
This single endpoint works for both individual (KYC) and business (KYB) customers — SpherePay determines the correct flow based on the customer’s type.Once the link is generated, redirect the customer to the returned URL. The hosted experience handles:
  • Document upload (ID document, proof of address)
  • Face liveness verification
  • OTP contact verification
  • Business document upload and UBO registration (for business customers)
During the KYC/KYB flow, the customer may register a bank account. It will remain in pending status until their identity is fully verified and the verification profile reaches approved.
4

Redirect or send the link to your customer

Redirect the customer directly from your application, or send them the link via email or SMS. The customer does not need an existing SpherePay account to complete the hosted verification.
5

Poll for verification status

After the customer completes the hosted flow, poll GET /v2/customer/{id} until status in verificationProfiles reaches approved.
GET https://api.spherepay.co/v2/customer/{id}

{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "identity_document",
          "liveness_report_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual"
}
When required is empty and status is approved, the customer is fully onboarded and ready to transfer.
Poll on a reasonable interval — for example, every 30 seconds — rather than continuously. You can also use webhooks if your integration supports them.

​
What’s next

Once the customer’s verification profile is approved, register their payment methods and initiate a transfer.

Bank accounts

Register a bank account so the customer can send or receive funds via bank rail.

Wallets

Register a crypto wallet address to enable on-ramp and off-ramp transfers.

Transfers API

Create and manage transfers once the customer has registered their payment methods.

Verification profile

Understand verification statuses, criteria arrays, and what triggers state changes.
Last modified on May 12, 2026