Understanding the SpherePay integration model before writing any code will save you significant time. Every integration — whether you’re building on-ramp, off-ramp, or embedding the ramp widget — follows the same core sequence: authenticate, onboard a customer, register a transfer instrument, and execute a transfer. This page explains each step and the key concepts behind them.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.
Integration sequence
Authenticate
Generate an API key from your SpherePay dashboard. Every API request must include this key as a Bearer token in the
Authorization header. See Authentication for setup instructions.Create and verify a customer
A customer represents the end user or business on whose behalf you are moving money. Before any transfer can be initiated, the customer must pass identity verification — KYC for individuals, KYB for businesses. No transfer can be created without a verified customer record.
Register a transfer instrument
Once your customer is verified, link the account or wallet that will serve as the source or destination of the transfer. For on-ramp transfers, you link a bank account as the fiat source and a wallet as the crypto destination. For off-ramp, the direction is reversed.
Step 1 — Create and verify a customer
A customer in SpherePay represents an end user or business on whose behalf you are moving money. Before a customer can transact, they must pass identity verification:- Individual customers go through a KYC (Know Your Customer) flow. This involves identity document submission and a face liveness check.
- Business customers go through a KYB (Know Your Business) flow. This involves business document submission and verification of a director or authorized representative.
Step 2 — Register a transfer instrument
Once a customer is verified, register the transfer instrument that will serve as the source or destination of a transfer:- Bank accounts — used as the fiat source for on-ramp or the fiat destination for off-ramp.
- Wallets — used as the crypto destination for on-ramp or the crypto source for off-ramp.
Step 3 — Execute a transfer
With a verified customer and the appropriate instruments in place, callPOST /v2/transfer to initiate the money movement. You specify the customer, the source instrument, the destination instrument, and the amount. SpherePay handles everything else.
See Transfers for full details on transfer types, statuses, and supported rails.
Key concepts
| Concept | Description |
|---|---|
| Customer | An individual or business on whose behalf transfers are executed. Must be KYC/KYB verified before any transfer can be initiated. |
| Bank Account | A fiat bank account linked to a customer, used for sending or receiving fiat funds. |
| Wallet | A crypto wallet address linked to a customer, used for sending or receiving stablecoins. |
| Transfer | A single money movement event between a customer’s bank account and wallet, in either direction. |
What SpherePay handles for you
Once you submit a transfer, SpherePay manages the full lifecycle:- Identity verification orchestration via Sumsub
- Compliance screening and sanctions checks
- Fiat-to-crypto and crypto-to-fiat conversion
- Settlement and payout via the underlying banking and blockchain rails
SpherePay does not maintain a separate sandbox environment. Testing happens directly against production systems using real identity information. This ensures your integration is validated against the same identity verification and banking partnerships your customers will use.