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.

A verification profile is a record of the requirements SpherePay needs to approve a customer — individual or business — before they can initiate or receive transfers. It is returned as part of the verificationProfiles array whenever you call GET /v2/customer/{id}. Monitoring the verification profile is the primary way to determine whether a customer is ready to transfer. Most integrations will see a single profile in the verificationProfiles array. A customer is ready to transfer when that profile’s status reaches approved. If you see unexpected profile names, contact your SpherePay representative.
Different verification profiles unlock different transfer capabilities. For example, USD/EUR transfers use kyc_profile_a, while BRL/PIX transfers require kyc_profile_b — a separate onboarding path. Contact your SpherePay representative to understand which profiles apply to your integration.

​
Verification statuses

The status field on a verification profile has four possible values.
StatusDescriptionCan initiate transfers?
incompleteThe customer has not yet completed all verification requirements. This is the initial state.No
pendingThe customer has completed all requirements and is waiting for SpherePay’s review.No
approvedSpherePay has approved the customer. They are fully onboarded and can initiate transfers.Yes
rejectedSpherePay could not approve the customer based on the submitted information.No

​
Status lifecycle

A verification profile moves through states in the following order: 
incomplete → pending → approved
                    ↘
                     rejected
  • The customer starts in incomplete. The criteria.required array lists all outstanding requirements.
  • Once all requirements are fulfilled, SpherePay automatically processes the verification and moves the profile to pending. No submit call is needed.
  • SpherePay completes the review and transitions the profile to either approved or rejected.

​
Verification criteria arrays

Each verification profile contains a criteria object with four arrays that describe the current state of each requirement.
ArrayDescription
completeRequirements that have been fulfilled. No further action needed.
pendingRequirements currently being processed by SpherePay. Wait for this to resolve.
requiredRequirements that must still be completed. You or your customer must act on these.
errorsRequirements with validation errors. Correct these before resubmitting.
When required is empty and status is approved, the customer is fully onboarded.

​
What triggers state transitions

ActionEffect
Customer creation with email, phone, and addressPopulates complete for email_address, phone_number, residential_address
Upload of identity documentMoves identity_document from required to pending, then complete after processing
Upload of liveness report or completion of face liveness checkFulfills liveness_report_document or liveness_check requirement
TOS acceptance via hosted linkFulfills terms_of_service requirement
All required items resolvedSpherePay automatically submits for review; status moves to pending
Manual review completed by SpherePayStatus moves to approved or rejected

​
How to check verification status

Call GET /v2/customer/{id} to retrieve the current state of a customer’s verification profile. 
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"
}
Poll GET /v2/customer/{id} to detect when approval occurs, then proceed with payment method registration and transfer setup.

​
Verification profile fields — individual customers

Each item in the criteria arrays corresponds to a specific requirement. The table below describes each field and what action resolves it.
ItemAction required
email_addressProvide an email address when creating or updating the customer
phone_numberProvide a phone number when creating or updating the customer
residential_addressProvide a full residential address when creating or updating the customer
tax_identification_numberProvide a tax ID via personalInformation.taxIdentificationNumber
identity_documentUpload a government-issued ID via POST /v2/document
liveness_report_documentUpload a liveness report from your KYC provider via POST /v2/document
liveness_checkComplete face liveness verification via the link from POST /v2/enhanced-due-diligence/face-verification-link — enhanced, only required for some integrations
terms_of_serviceAccept TOS via the hosted link from POST /v2/customer/{id}/tos-link — enhanced, only required for some integrations
email_verificationVerify email via OTP send and verify endpoints — enhanced, only required for some integrations
phone_verificationVerify phone via OTP send and verify endpoints — enhanced, only required for some integrations

​
Verification profile fields — business customers

ItemAction required
email_addressProvide an email address when creating or updating the customer
phone_numberProvide a phone number when creating or updating the customer
operating_addressProvide an operating address in the addresses array
registered_addressProvide a registered address in the addresses array
legal_nameProvide businessInformation.legalName
trade_nameProvide businessInformation.tradeName
entity_typeProvide businessInformation.entityType
descriptionProvide businessInformation.description
naics_codeProvide businessInformation.naicsCode
websiteProvide businessInformation.website
incorporated_onProvide businessInformation.incorporatedOn
identification_numberProvide businessInformation.identificationNumber — types vary by country
estimated_annual_revenueProvide businessInformation.estimatedAnnualRevenueInUsd
expected_monthly_paymentsProvide businessInformation.expectedMonthlyPaymentsInUsd
account_purposeProvide businessInformation.accountPurpose
source_of_fundsProvide businessInformation.primarySourceOfFunds
regulated_activitiesProvide businessInformation.regulatedActivities
business_representativesRegister and verify all UBOs via POST /v2/business-representative
incorporation_cert_documentUpload via POST /v2/document with documentType: "incorporation_certificate"
shareholder_registry_documentUpload via POST /v2/document with documentType: "shareholder_registry"
proof_of_address_documentUpload via POST /v2/document with documentType: "proof_of_address"
terms_of_serviceAccept TOS via hosted link — enhanced, only required for some integrations
master_service_agreementSign MSA via the hosted form presented after TOS acceptance — enhanced, only required for some integrations

​
Handling rejected customers

A rejected status means the verification could not be approved based on the submitted information. Customers with a rejected profile cannot initiate or receive transfers. If a customer is incorrectly rejected or requires re-review, contact support@spherepay.co with the customerId.

Individual KYC

Step-by-step guide for onboarding individual customers via API.

Business KYB

Step-by-step guide for onboarding business customers via API.

KYC via hosted link

Onboard customers using SpherePay’s hosted verification experience.

Customers overview

Overview of customer types, onboarding models, and integration methods.
Last modified on May 12, 2026