Paying employees, suppliers, marketplace sellers, or other third parties? Use Third-Party Flows instead.
Scoping output
By the end of discovery, you and SpherePay should agree on:- Customer type — individual or business
- Legal entity that owns both source and destination
- First motion — on-ramp, off-ramp, or both
- Pattern — one-off transfer, Onramper Account, or Offloader Wallet
- Fiat currency and rail
- Stablecoin and network
- One-off transfers vs reusable instructions
- Movement/conversion only vs fiat balance holding
- Expected monthly volume, average and maximum transaction size
- Verification profile and corridor enablement requirements
- Reconciliation fields your finance team needs
Choose your pattern
One-off transfer
Explicit API control per on-ramp or off-ramp. Best when each movement is initiated individually.
Onramper Account
Reusable fiat deposit instructions that auto-convert to stablecoin in the customer’s wallet.
Offloader Wallet
Reusable stablecoin deposit address that auto-converts to fiat in the customer’s bank account.
| Pattern | Discovery signals | Primary objects |
|---|---|---|
| One-off transfer | Per-movement API control; ad-hoc conversions; per-transfer status tracking | Customer, wallet, bank account, transfer |
| Onramper Account | Reusable fiat deposits; auto-convert to stablecoin; no transfer call per deposit | Customer, wallet, Onramper Account |
| Offloader Wallet | Reusable stablecoin deposits; auto-convert to fiat; no transfer call per deposit | Customer, bank account, Offloader Wallet |
How the flow works
- On-ramp
- Off-ramp
Customer bank account or reusable funding account → SpherePay → Customer wallet
Pattern: One-off transfer
Use when: The customer initiates each on-ramp or off-ramp individually and needs explicit per-transfer control. Discovery signals:- Each movement is initiated at a point in time — not triggered by a standing deposit address
- Integrator owns retry, idempotency, and status UX per transfer
- Customer may need to quote or execute transfers one at a time
Create or retrieve the customer
Register the legal entity via POST /v2/customer.
Complete KYC or KYB
Finish individual KYC or business KYB until the verification profile reaches
approved.Register instruments
Link the customer’s wallet and bank account on the same customer record.
Lock a rate (optional)
If the customer needs a guaranteed rate, create a rate-locked quote via POST /v2/quote (valid for 30, 60, or 300 seconds, redeemable once) and reference its
quoteId when creating the transfer.Create each transfer
Call POST /v2/transfer with customer, source, and destination.
Track and reconcile
Poll GET /v2/transfer/ until a terminal status — see Transfer lifecycle.
Confirm source and destination instruments belong to the same onboarded customer. Some corridors require provider-specific enablement beyond standard KYC/KYB — confirm access with SpherePay before building.
Pattern: Onramper Account
Use when: The customer needs reusable fiat deposit instructions that automatically convert to stablecoin in a wallet they own. Discovery signals:- Customer will send fiat to the same deposit instructions repeatedly
- No
POST /v2/transfercall should fire on each deposit - Destination is a stablecoin wallet owned by the same legal entity
Create or retrieve the customer
Register the legal entity via POST /v2/customer.
Register the destination wallet
The customer must already own the on-chain address. Register via POST /v2/wallet.
Create an Onramper Account
Call POST /v2/virtual-account. See Onramper Accounts.
Share deposit instructions
Provide
depositInstructions from the response. SpherePay converts incoming fiat and delivers stablecoin automatically.Track deposits and conversions
Poll GET /v2/transfer filtered by customer (use
type=microdeposit for verification deposits) to list transfers processed through the account. Each fiat deposit appears as a transfer once detected — reconcile against your expected deposits. There is no per-deposit API call to anchor status on, so design your polling cadence and reconciliation keys before launch.Pattern: Offloader Wallet
Use when: The customer needs a reusable on-chain address that automatically converts incoming stablecoin to fiat in a bank account they own. Discovery signals:- Customer will send stablecoin to the same address repeatedly
- No
POST /v2/transfercall should fire on each deposit - Fiat destination is a bank account owned by the same legal entity
Create or retrieve the customer
Register the legal entity via POST /v2/customer.
Register the destination bank account
Link the customer’s existing account via POST /v2/bank-account.
Create an Offloader Wallet
Call POST /v2/offloader-wallet. See Offloader Wallets.
Share the offloader address
Provide the on-chain address from the response. SpherePay converts stablecoin and pays out fiat automatically.
Track deposits and payouts
Poll GET /v2/transfer filtered by customer to track stablecoin deposits and the resulting fiat payouts through to a terminal status — see Transfer lifecycle.
What to send Sphere before kickoff
- Customer type: individual or business
- Legal entity owning source and destination
- First flow: on-ramp, off-ramp, or both
- Selected pattern: one-off transfer, Onramper Account, or Offloader Wallet
- Fiat currency and rail
- Stablecoin and network
- Expected monthly volume
- Average and maximum transaction size
- One-off vs reusable instructions
- Movement/conversion only vs fiat balance holding
- Reconciliation requirements
Validate before engineering starts
| Blocker | What it usually means |
|---|---|
| Verification profile not approved | Required KYC/KYB profile is incomplete, pending, missing, or rejected |
| Provider/corridor not enabled | Customer may be approved generally but not enabled for the specific corridor or rail |
| Unsupported rail, currency, or network | Combination not available for your product — Supported rails |
| Ownership mismatch | Source or destination instrument does not belong to the onboarded customer |
| Wallet confusion | POST /v2/wallet registers an existing address — SpherePay does not generate or custody private keys |
| Onramper Account confusion | Automates fiat-to-stablecoin conversion via deposit instructions — confirm movement-only vs balance-holding requirements |
| Offloader Wallet updates | Changing source/destination currency or rail type requires a new wallet; other fields may be PATCHable |
Pre-kickoff checklist
- Same legal entity owns source and destination
- Pattern selected and confirmed with SpherePay
- Customer created or retrieved; verification profile
approvedfor target corridor - Provider/corridor enabled if required
- Wallet and/or bank account registered on the correct customer
- Rail, currency, and network confirmed
- Reconciliation and status mapping defined
- Kickoff inputs sent to SpherePay
Before go-live
SpherePay has no separate sandbox — integration testing runs against production with real identity data. Run a small-dollar live transfer on each corridor before launch. The first transfer to a new beneficiary may trigger a compliance RFI from the banking partner. Set this expectation with your customer up front, and make sure your designated RFI owner is ready to respond. For end-customer settlement questions, share the SpherePay Knowledge Base articles When will the funds land in my account? and My funds are missing or have not landed in my account so users can self-serve instead of opening support tickets with you.Go deeper
Treasury management
First-party treasury outcome — round-trip on-ramp/off-ramp examples.
Transfers
One-off transfer lifecycle, BRL/PIX constraints, and status reference.
Third-Party Flows
When source and destination are not the same legal entity.
Onboarding
KYC, KYB, and verification profile requirements.
Knowledge Base & FAQ
End-customer support articles — settlement times, missing funds, minimums, and dashboard guides — to hand to your users.