KYC & KYB Status Reference

What each verification status means, what triggers it, and what a customer can do at each stage.

SpherePay tracks the state of each customer's verification through a verificationProfiles array on the customer object. Each profile has a status field that reflects where the customer is in the review process.

Fetch the current status at any time using the Get Customer endpoint.

Status Values

Status	Meaning	Can Initiate Transfers?
`incomplete`	Requirements are still outstanding. The `criteria.required` array lists what must be completed before submission is possible.	No
`pending`	All requirements have been submitted via `submit-verification`. SpherePay is reviewing the submission.	No
`approved`	SpherePay has reviewed and approved the verification. The customer is fully onboarded.	Yes
`rejected`	SpherePay has reviewed and rejected the verification. The customer cannot initiate transfers.	No

Status Lifecycle

A verification profile moves through states in the following order:

incomplete → pending → approved
                    ↘
                     rejected

A customer starts as incomplete. The criteria.required array lists all outstanding requirements.
Once all requirements are fulfilled and submit-verification is called, the profile moves to pending.
SpherePay completes the review and transitions the profile to either approved or rejected.

Reading the Status

The verificationProfiles array is returned in the Get Customer response. A customer may have one or more profiles.

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

The `criteria` object

The criteria object gives a precise breakdown of what is completed, in progress, or still outstanding:

Field	Description
`complete`	Requirements that have been fulfilled.
`pending`	Requirements currently being processed (e.g. an uploaded document under review).
`required`	Requirements that must be completed before the customer can be submitted for verification.
`errors`	Validation errors, each with a `name` and `detail` field.

Submission Readiness

You can only call submit-verification when the only items remaining in required are the final SpherePay-fulfilled requirements:

KYC: identity_verification and kyc_a_approval
KYB: identity_verification and kyb_a_approval

If other requirements are still listed, complete those steps first.

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 customer_id.

Listening for Status Changes

Rather than polling the Get Customer endpoint, set up webhooks to receive status updates as they happen. See Webhooks for setup instructions.