Skip to main content
When Sphere routes you here: Discovery confirmed the same legal entity owns both the source and destination — for example, treasury on-ramp, treasury off-ramp, or reusable funding/cash-out for that entity’s own bank account and wallet. This page scopes the first-party implementation pattern to build. For object definitions and API payloads, follow the links into Concepts and API Reference.
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.

​
How the flow works

Customer bank account or reusable funding account → SpherePay → Customer wallet
For a treasury round-trip example, see Treasury management.

​
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
1

Create or retrieve the customer

Register the legal entity via POST /v2/customer.
2

Complete KYC or KYB

Finish individual KYC or business KYB until the verification profile reaches approved.
3

Register instruments

Link the customer’s wallet and bank account on the same customer record.
4

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

Create each transfer

Call POST /v2/transfer with customer, source, and destination.
6

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.
Related Solution: Treasury management

​
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/transfer call should fire on each deposit
  • Destination is a stablecoin wallet owned by the same legal entity
1

Create or retrieve the customer

Register the legal entity via POST /v2/customer.
2

Complete KYC or KYB

Reach approved on the required verification profile.
3

Register the destination wallet

The customer must already own the on-chain address. Register via POST /v2/wallet.
4

Create an Onramper Account

Call POST /v2/virtual-account. See Onramper Accounts.
5

Share deposit instructions

Provide depositInstructions from the response. SpherePay converts incoming fiat and delivers stablecoin automatically.
6

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.
Onramper Accounts are an add-on product. Create one account per customer — shared accounts break deposit attribution. Confirm the product is enabled for your rail and region.
Related Solutions: Payment acceptance, Treasury management

​
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/transfer call should fire on each deposit
  • Fiat destination is a bank account owned by the same legal entity
1

Create or retrieve the customer

Register the legal entity via POST /v2/customer.
2

Complete KYC or KYB

Reach approved on the required verification profile.
3

Register the destination bank account

Link the customer’s existing account via POST /v2/bank-account.
4

Create an Offloader Wallet

Call POST /v2/offloader-wallet. See Offloader Wallets.
5

Share the offloader address

Provide the on-chain address from the response. SpherePay converts stablecoin and pays out fiat automatically.
6

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.
Offloader Wallets are an add-on product. Create one wallet per customer. To change source/destination currency or rail type, create a new wallet — other fields may be PATCHable via Update Offloader Wallet. Verify the bank account holder’s legal name and physical address (no PO boxes) before creating the wallet — partners reject PO box addresses, and correction paths for an attached bank account are limited.
Related Solution: Treasury management

​
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

​
Pre-kickoff checklist

  • Same legal entity owns source and destination
  • Pattern selected and confirmed with SpherePay
  • Customer created or retrieved; verification profile approved for 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.
Last modified on June 22, 2026