KYC via API — Platform-Managed
Step-by-step guide for onboarding individual customers using the Platform-Managed model. Your platform handles liveness verification and ToS upstream — no hosted redirects required.
Introduction
This guide covers the Platform-Managed KYC integration — an opt-in onboarding model for platforms that already perform KYC/KYB, collect liveness verification, and embed Sphere's Terms of Service.
Platform-Managed must be approved for your application
This model is not available by default. Your platform must meet qualification requirements and receive approval from Sphere's Compliance team before going live. See the Onboarding Guide for prerequisites, then contact your dedicated Solutions Engineer to initiate the approval process.
Using the default Sphere-Managed model?
If your application uses the default Sphere-Managed model, see KYC via API — Sphere-Managed instead.
Before you begin
Ensure you have:
- A SpherePay API key — see Authentication
- The customer's personal information ready (name, date of birth, full address, tax ID)
- A copy of the customer's government-issued identity document for upload
- A liveness report document from your identity verification provider (e.g., Sumsub, Persona)
- Platform-Managed onboarding approved for your application by Sphere Compliance
KYC via API Flow — Platform-Managed
Core Steps
1. Create a Customer
To create a customer, use the Create Customer endpoint.
POSThttps://api.spherepay.co/v2/customer
Information
Include personalInformation and a full address in the creation request. These fields allow SpherePay to verify the customer's identity programmatically.
Request Example
{
"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"
}
}Personal Information Fields
The personalInformation object contains the customer's tax identification details. The accepted values depend on the customer's country of residence:
taxIdentificationNumberCountry— The customer's country code (e.g.USA,SGP,GBR).taxIdentificationNumberType— The type of identification number. Accepted values vary by country — for example,ssnfor the United States,nricfor Singapore, orninofor the United Kingdom.taxIdentificationNumber— The actual identification number.taxIdentificationNumberDescription— A human-readable description of the document type. Optional — only required whentaxIdentificationNumberTypeisother.
For the full list of accepted identification types and codes by country, see Tax ID Numbers by Country.
2. Upload Required Documents
Upload the customer's identity documents. Use the Upload Document endpoint.
Required Documents
For the full list of required documents and accepted formats, see the Document Guideline.
https://api.spherepay.co/v2/document
Request Example
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"'Response Example
{
"target": "customer",
"targetId": "customer_4914a2f6226e42cc8d207ead9573b29f",
"documentType": "id_card",
"fileName": "document.jpg",
"fileSize": 2048576,
"mimeType": "image/jpeg",
"createdAt": "2025-05-23T11:45:00Z"
}3. Upload Liveness Report
Upload the liveness report document produced by your platform's identity verification provider. This replaces the in-flow face liveness check used in the Sphere-Managed model.
POSThttps://api.spherepay.co/v2/document
Request Example
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"'Response Example
{
"target": "customer",
"targetId": "customer_4914a2f6226e42cc8d207ead9573b29f",
"documentType": "liveness_report",
"fileName": "liveness_report.pdf",
"fileSize": 1048576,
"mimeType": "application/pdf",
"createdAt": "2025-05-23T11:50:00Z"
}4. Poll for Verification Result
Once all required data and documents are submitted, SpherePay processes the KYC verification automatically — no submit call is needed. Poll the Get Customer endpoint until status in verificationProfiles reaches approved.
https://api.spherepay.co/v2/customer/{id}
Approved Response Example
{
"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.
What's Next
With the customer onboarded, register their payment methods before initiating a transfer.
Register Payment Methods
Create a Transfer
Make Routine Transfers Easier with Onramper Accounts & Offloader Wallets
Last updated on