KYC for Individual Customers

KYC (Know Your Customer) is a legal identity verification process required before any individual customer can send or receive funds through SpherePay. It is mandated by anti-money laundering (AML) regulations and must be completed once per customer. You choose how to integrate — via API or hosted link — and which compliance model to use.

Required information

SpherePay requires the following information to verify an individual customer’s identity. Fields marked as API are submitted in the customer creation request; fields marked as ID Document are extracted automatically from the uploaded document.

Field	Source	Notes
Email address	API	`email` field in the customer creation request
Phone number	API	`phone` field in the customer creation request
Country of residence	API	`address.country` in the customer creation request
Residential address	API	Full `address` object (street, city, postal code, state)
Tax identification number	API	`personalInformation.taxIdentificationNumber` — accepted types vary by country
First name & last name	ID Document	Auto-extracted from the uploaded government-issued ID
Date of birth	ID Document	Auto-extracted from the uploaded government-issued ID
Government-issued ID document	ID Document	Uploaded via `POST /v2/document` — passport, ID card, or driver’s license
Proof of address	ID Document	Uploaded via `POST /v2/document`

In certain circumstances SpherePay may request additional information, such as for politically exposed persons (PEPs), elderly customers, high-risk profiles, or customers with unusually high expected transaction volumes. SpherePay will contact you directly when this applies.

KYC flow overview

The flow below shows the steps required for individual KYC. The only step that differs between onboarding models is TOS acceptance — it is handled in-flow in Sphere-Managed and embedded in your platform’s terms in Platform-Managed.

Sphere-Managed (default)
Platform-Managed (opt-in)

Create customer with full personalInformation and address
Generate TOS link → redirect customer to accept terms
Upload government-issued ID document
Upload proof of address document
Complete face liveness verification (Sumsub SDK, in-flow)
Poll GET /v2/customer/{id} until status reaches approved

Create customer with full personalInformation and address
Upload government-issued ID document
Upload proof of address document
Upload liveness report document from your KYC provider
Poll GET /v2/customer/{id} until status reaches approved

Choose an integration method

You must pick a single integration method and onboarding model for each customer. Mixing methods for the same customer — or falling back to one if the other fails — is not supported and will result in an unsuccessful onboarding.

KYC via API — Sphere-Managed

Default model. Sphere handles TOS, face liveness, and OTP via hosted links.

KYC via API — Platform-Managed

Opt-in model. Upload a liveness report document. No hosted redirects required.

KYC via hosted link

Fastest integration. SpherePay hosts the entire verification experience.

KYC via API — Sphere-Managed

This is the default model for all new API integrations. Sphere handles compliance steps in-flow using hosted links and redirects: Terms of Service acceptance, face liveness verification, and OTP contact verification. Before you begin, ensure you have:

A SpherePay API key
The customer’s personal information (full address, tax ID)
A copy of the customer’s government-issued identity document

Create a customer

Call POST /v2/customer with type: "individual" and include the full personalInformation and address objects. These fields allow SpherePay to verify the customer’s identity programmatically.

{
  "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"
  },
  "personalInformation": {
    "taxIdentificationNumber": "123456789",
    "taxIdentificationNumberType": "ssn",
    "taxIdentificationNumberCountry": "USA"
  }
}

The personalInformation object accepts the following fields:

Field	Description
`taxIdentificationNumberCountry`	The customer’s country code (e.g. `USA`, `SGP`, `GBR`)
`taxIdentificationNumberType`	The ID number type, e.g. `ssn` (USA), `nric` (Singapore), `nino` (UK)
`taxIdentificationNumber`	The actual identification number
`taxIdentificationNumberDescription`	Human-readable description — only required when type is `other`

Accept Terms of Service

Generate a TOS link and redirect the customer to accept the Terms and Conditions and Privacy Policy.

POST https://api.spherepay.co/v2/customer/{id}/tos-link

This step can be done in parallel with uploading documents.

Upload ID document

Upload the customer’s government-issued identity document using POST /v2/document.

curl --location 'https://api.spherepay.co/v2/document' \
--header 'Authorization: Bearer <your_api_key>' \
--form 'target="customer"' \
--form 'targetId="customer_4914a2f6226e42cc8d207ead9573b29f"' \
--form 'documentType="id_card"' \
--form 'side="front"' \
--form 'file=@"/path/to/your/document.jpg"' \
--form 'country="SGP"'

Upload both the front and back for ID cards and driver’s licenses. Passports require front only (with country-specific exceptions). See the Document Guideline for accepted formats by country.

Complete face liveness verification

Check the customer’s required array via GET /v2/customer/{id}. Then perform exactly one of the following, depending on what appears in required:

liveness_check in required — Generate a face verification link via POST /v2/enhanced-due-diligence/face-verification-link and redirect the customer to complete an interactive liveness check via the Sumsub SDK.
liveness_report_document in required — Upload a liveness report document from your identity verification provider via POST /v2/document with documentType: "liveness_report".

Do not perform both paths. Check the required array and follow only the matching option.

Poll for verification result

Once all required steps are complete, SpherePay processes the verification automatically — no submit call is needed. 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.

KYC review typically takes 0–2 business days after all required documents and data are submitted.

KYC via API — Platform-Managed

This opt-in model is for platforms that already perform KYC, collect liveness verification, and embed Sphere’s Terms of Service. Your platform handles compliance upstream — no hosted redirects are required.

Platform-Managed is not available by default. Your platform must meet qualification requirements and receive approval from Sphere’s Compliance team before going live. Contact your dedicated Solutions Engineer to initiate the approval process.

Additional prerequisites beyond the standard set:

A liveness report document from your identity verification provider (e.g. Sumsub, Persona)
Platform-Managed onboarding approved for your application by Sphere Compliance

Create a customer

Call POST /v2/customer with type: "individual", full personalInformation, and address. The request body is identical to the Sphere-Managed path.

{
  "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"
  },
  "personalInformation": {
    "taxIdentificationNumber": "123456789",
    "taxIdentificationNumberType": "ssn",
    "taxIdentificationNumberCountry": "USA"
  }
}

Upload ID document and proof of address

Upload the customer’s identity documents via POST /v2/document. Repeat for each required document type.

curl --location 'https://api.spherepay.co/v2/document' \
--header 'Authorization: Bearer <your_api_key>' \
--form 'target="customer"' \
--form 'targetId="customer_4914a2f6226e42cc8d207ead9573b29f"' \
--form 'documentType="id_card"' \
--form 'side="front"' \
--form 'file=@"/path/to/your/document.jpg"' \
--form 'country="SGP"'

Upload liveness report

Upload the liveness report produced by your identity verification provider. This replaces the in-flow face liveness check used in Sphere-Managed.

curl --location 'https://api.spherepay.co/v2/document' \
--header 'Authorization: Bearer <your_api_key>' \
--form 'target="customer"' \
--form 'targetId="customer_4914a2f6226e42cc8d207ead9573b29f"' \
--form 'documentType="liveness_report"' \
--form 'file=@"/path/to/liveness_report.pdf"'

Only upload this document if liveness_report_document appears in the required array of the customer’s verification profile.

Poll for verification result

Once all required data and documents are submitted, SpherePay processes the KYC verification automatically. Poll GET /v2/customer/{id} until status reaches approved.

What’s next

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

Bank accounts

Wallets

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.

Overview

Onboarding

Transfers

Automation

Reference data

Operational

KYC for Individual Customers

Required information

KYC flow overview

Choose an integration method

KYC via API — Sphere-Managed

KYC via API — Platform-Managed

KYC via hosted link

KYC via API — Sphere-Managed

KYC via API — Platform-Managed

What’s next

Bank accounts

Wallets

Transfers API

Verification profile

Overview

Onboarding

Transfers

Automation

Reference data

Operational

Documentation Index

​Required information

​KYC flow overview

​Choose an integration method

KYC via API — Sphere-Managed

KYC via API — Platform-Managed

KYC via hosted link

​KYC via API — Sphere-Managed

​KYC via API — Platform-Managed

​What’s next

Bank accounts

Wallets

Transfers API

Verification profile

Required information

KYC flow overview

Choose an integration method

KYC via API — Sphere-Managed

KYC via API — Platform-Managed

What’s next