Customer KYB via API (Business Only)

This guide walks you through the process of onboarding business customers using the Customer KYB API.

Introduction

To initiate the KYB process via API, you will need to include all the optional fields in the customer creation request. Once submitted, the customer information is verified programmatically. Any required supporting documents must then be uploaded to complete the KYB process.

Information

This method applies only to business customers and is not supported for individual customers.

KYB via API Flow

For the full list of required business documents and their API values, see Business Document Guideline.

Onboarding a Customer step by step using KYB API

The following steps will guide you through the process of onboarding a business customer step by step using KYB API.

1. Create a Customer

To create a customer, you can use the Create Customer endpoint.

POST https://api.spherepay.co/v2/customer

POST https://api.sandbox.spherepay.co/v2/customer

Information

To onboard a business customer via API, you would need to submit all the optional fields in the customer creation request. By doing so, the customer information will then be verified programmatically and need not an independent KYB link to be generated. Once the information has been sent, business document uploads and business representative (UBO) identification document uploads will be required to complete the KYB process.

Request Example

{
  "type": "business",
  "email": "business@example.com",
  "phone": "+1234567890",
  "address": {
    "line1": "123 Main St",
    "line2": "string",
    "city": "San Francisco",
    "postalCode": "94107",
    "state": "CA",
    "country": "USA"
  },
  "businessInformation": {
      "legalName": "SpherePay Pte Ltd",
      "tradeName": "SpherePay",
      "description": "SpherePay is a payment processing platform",
      "entityType": "corporation",
      "naicsCode": "1234567890",
      "website": "https://spherepay.co",
      "incorporatedOn": "2026-01-01",
      "identificationNumberType": "ein",
      "identificationNumber": "1234567890",
      "identificationNumberCountry": "USA",
      "identificationNumberDescription": "Employer Identification Number",
      "estimatedAnnualRevenueInUsd": "100000_999999",
      "expectedMonthlyPaymentsInUsd": "800000",
      "accountPurpose": "third_party_money_transmission",
      "accountPurposeDescription": "Handles client funds",
      "primarySourceOfFunds": "third_party_funds",
      "primarySourceOfFundsDescription": "Client funds",
      "isDao": false,
      "regulatedActivities": ["money_services"],
      "regulatedActivitiesDescription": "The business engages in money services",
      "participatesInRegulatedFinancialActivity": true,
      "regulatedFinancialActivityDescription": "The business engages in money services",
      "moneyServicesDescription": "Handles client funds",
      "complianceScreeningExplanation": "Approved by third-party",
      "operatesInProhibitedCountries": false
  }
}

Business Identification Fields

The businessInformation object includes identification details for the business. The accepted values depend on the business's country of incorporation:

identificationNumberCountry — The business's country code (e.g. USA, SGP, GBR).
identificationNumberType — The type of identification number. Accepted values vary by country — for example, ein for the United States, uen for Singapore, or crn for the United Kingdom.
identificationNumber — The actual identification number.
identificationNumberDescription — A human-readable description of the document type.

For the full list of accepted business identification types and codes by country, see Business Identification Types by Country.

2. Accepting Terms of Service & Signing Merchant Service Agreement

After a business customer has been created, you can generate a TOS link to redirect the customer to the Terms of Service and Privacy Policy. To generate a TOS link, you can use the Generate TOS Link endpoint

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

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

Once the link is generated, you can redirect the customer to the link to complete the onboarding process. The customer is expected to accept the Terms and Conditions, and Privacy Policy before proceeding. After the customer has accepted the Terms and Conditions, SpherePay will automatically redirect the user to a form to fill out required information for the Merchant Service Agreement (MSA). Once the form is completed, the customer will be redirected to the Merchant Service Agreement page to sign the agreement.

3. Upload Business Documents

Upload the required business documents to verify the company's identity, legal standing, and ownership structure. These documents use target="customer" since they belong to the business entity itself.

Required Business Documents

For the full list of required business documents and their API values, see Business Document Guideline.

To upload documents, use the Upload Document endpoint.

POST https://api.spherepay.co/v2/document

POST https://api.sandbox.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_66c4168d418a410eae282b83883bdc39"' \
--form 'documentType="incorporation_certificate"' \
--form 'file=@"/path/to/your/document.pdf"' \
--form 'country="USA"'

Response Example

{
  "id": "document_7a2b3c4d5e6f7890abcdef1234567890",
  "target": "customer",
  "targetId": "customer_66c4168d418a410eae282b83883bdc39",
  "documentType": "incorporation_certificate",
  "description": "Certificate of Incorporation",
  "fileName": "incorporation_certificate.pdf",
  "fileSize": 1048576,
  "mimeType": "application/pdf",
  "createdAt": "2025-05-23T11:30:00Z"
}

4. Register Business Representative (UBO)

A business representative, also known as an Ultimate Beneficial Owner (UBO), is any individual who owns 25% or more of the company. All individuals meeting this threshold must be registered — repeat this step for each qualifying UBO.

To register a business representative, use the Register Business Representative endpoint.

POST https://api.spherepay.co/v2/business-representative

POST https://api.sandbox.spherepay.co/v2/business-representative

Request Example

{
  "customerId": "customer_66c4168d418a410eae282b83883bdc39",
  "type": "individual",
  "email": "john.doe@example.com",
  "phone": "+14155551234",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "Chicago",
    "state": "IL",
    "postalCode": "60601",
    "country": "USA"
  },
  "personalInformation": {
    "taxIdentificationNumber": "123456789",
    "taxIdentificationNumberType": "ssn",
    "taxIdentificationNumberCountry": "USA"
  },
  "representationDetails": {
    "roles": ["ubo"],
    "ownershipPercentage": "50",
    "isControlPerson": true,
    "isSigner": true,
    "title": "CEO",
    "relationshipEstablishedAt": "2020-01-01"
  }
}

Personal Information Fields

The personalInformation object contains the UBO's tax identification details. The accepted values depend on the representative's country of residence:

taxIdentificationNumberCountry — The representative's country code (e.g. USA, SGP, GBR).
taxIdentificationNumberType — The type of identification number. Accepted values vary by country — for example, ssn for the United States, nric for Singapore, or nino for the United Kingdom.
taxIdentificationNumber — The actual identification number.
taxIdentificationNumberDescription — A human-readable description of the document type. Required when taxIdentificationNumberType is other.

For the full list of accepted identification types and codes by country, see Individual Identification Numbers by Country.

5. Upload Identification Documents for Business Representative (UBO)

Once the business representative (UBO) has been registered, upload their identification documents. These documents use target="business-representative" since they belong to the individual representative, not the business entity.

Important: UBO identification documents must be uploaded before requesting face liveness verification (Step 6).

Required UBO Documents

For the full list of accepted identification documents for individuals, see Document Guideline.

To upload documents, use the Upload Document endpoint.

POST https://api.spherepay.co/v2/document

POST https://api.sandbox.spherepay.co/v2/document

Request Example

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

Response Example

{
  "id": "document_4914a2f6226e42cc8d207ead9573b29f",
  "target": "business_representative",
  "targetId": "business_representative_4914a2f6226e42cc8d207ead9573b29f",
  "documentType": "id_card",
  "description": "John Doe ID card for identity verification",
  "fileName": "id_card_john_doe.jpg",
  "fileSize": 2048576,
  "mimeType": "image/jpeg",
  "createdAt": "2025-05-23T11:45:00Z"
}

6. Face Liveness Verification for Business Representative (UBO)

Important: Documents must be uploaded before requesting face liveness verification.

Once the required documents for the business representative (UBO) have been uploaded, you can request for face liveness verification. To request for face liveness verification, you can use the Request Face Liveness Verification for Business Representative endpoint.

POST https://api.spherepay.co/v2/business-representative/{id}/face-verification-link

POST https://api.sandbox.spherepay.co/v2/business-representative/{id}/face-verification-link

Response Example

{
  "url": "<https://sumsub.com/websdk/p/sbx_12345678-abcd-efgh-ijkl-123456789012>",
  "expiresAt": "2025-05-23T23:59:59Z"
}

Once the link is generated, you can redirect or open the link in a new tab for the business representative (UBO) to complete the face liveness verification process. The business representative is expected to complete the face liveness verification process before proceeding.

7. Submit Business Representative (UBO) Verification

Important: The business representative (UBO) must be verified before submitting the business customer for verification.

Check Readiness Before Submitting

Before calling the submit endpoint, fetch the business representative using the Get Business Representative endpoint and inspect the verificationProfiles array. Each profile contains a criteria object with the following arrays:

complete — Requirements that have been fulfilled.
pending — Requirements currently being processed.
required — Requirements that still need to be fulfilled before the representative can be verified.
errors — Any validation errors with a name and detail for each.

GET https://api.spherepay.co/v2/business-representative/{id}

GET https://api.sandbox.spherepay.co/v2/business-representative/{id}

Example response when NOT ready — several requirements are still outstanding:

{
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "incomplete",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number"
        ],
        "pending": [],
        "required": [
          "identity_document",
          "liveness_check",
          "identity_verification"
        ],
        "errors": []
      }
    }
  ]
}

Example response when READY to submit — only identity_verification remains in required:

{
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "incomplete",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "identity_document",
          "liveness_check"
        ],
        "pending": [],
        "required": [
          "identity_verification"
        ],
        "errors": []
      }
    }
  ]
}

When Can You Submit?

You can only call the submit verification endpoint when identity_verification is the only item remaining in the required array. If other requirements are still listed, complete those steps first. The identity_verification requirement is fulfilled by SpherePay after submission.

Submit Verification

To start the verification process, use the Submit Business Representative Information for Verification endpoint.

POST https://api.spherepay.co/v2/business-representative/{id}/submit-verification

POST https://api.sandbox.spherepay.co/v2/business-representative/{id}/submit-verification

Response Example

{
  "businessRepresentativeId": "business_representative_4914a2f6226e42cc8d207ead9573b29f"
}

8. Submit Business Customer for Verification

Once the business representative (UBO) has been verified, you can submit the business customer for verification. This is the final step in the onboarding process and will trigger the verification process.

Check Readiness Before Submitting

Before calling the submit endpoint, fetch the customer using the Get Customer endpoint and inspect the verificationProfiles array.

GET https://api.spherepay.co/v2/customer/{id}

GET https://api.sandbox.spherepay.co/v2/customer/{id}

Example response when NOT ready — several requirements are still outstanding:

{
  "verificationProfiles": [
    {
      "name": "kyb_profile_a",
      "status": "incomplete",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "business_address",
          "business_identification_number"
        ],
        "pending": [],
        "required": [
          "terms_of_service",
          "merchant_service_agreement",
          "incorporation_certificate",
          "shareholder_registry",
          "directors_registry",
          "proof_of_address",
          "business_representatives",
          "identity_verification",
          "kyb_a_approval"
        ],
        "errors": []
      }
    }
  ]
}

Example response when READY to submit — only identity_verification and kyb_a_approval remain in required:

{
  "verificationProfiles": [
    {
      "name": "kyb_profile_a",
      "status": "incomplete",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "business_address",
          "business_identification_number",
          "terms_of_service",
          "merchant_service_agreement",
          "incorporation_certificate",
          "shareholder_registry",
          "directors_registry",
          "proof_of_address",
          "business_representatives"
        ],
        "pending": [],
        "required": [
          "identity_verification",
          "kyb_a_approval"
        ],
        "errors": []
      }
    }
  ]
}

When Can You Submit?

You can only call the submit verification endpoint when identity_verification and kyb_a_approval are the only items remaining in the required array. If other requirements are still listed, complete those steps first. The identity_verification and kyb_a_approval requirements are fulfilled by SpherePay after submission.

Submit Verification

To start the verification process, use the Submit Verification endpoint.

POST https://api.spherepay.co/v2/customer/{id}/submit-verification

POST https://api.sandbox.spherepay.co/v2/customer/{id}/submit-verification

Response Example

{
  "customerId": "customer_4914a2f6226e42cc8d207ead9573b29f"
}

Once submitted, the verification process will take approximately 0-2 business days to complete. You can check the KYB status by polling the Get Customer endpoint — when status changes to approved in the verification profile, the business customer is fully onboarded.

9. Register Customer's Wallet & Bank Account

Once the business customer has been created and the KYB process is complete, you can register a wallet and a bank account for the customer. For bank accounts, see /api-guide/bank-accounts. For wallets, see /api-guide/wallets.

10. Create a Transfer

Once the business customer has been created and the KYB process is complete, you can create a transfer for the customer. See /api-guide/transfers-api.

Customer KYB via API (Business Only)

On this page