Transfers API Guide

What is it?

The Transfers API lets you create on-ramp and off-ramp transfers for your customers and track their lifecycle from creation to completion (or failure).

When to use

Use Transfers API when you want to embed transfers into your product and control your own UX.

If you want a pre-built experience, consider the Ramp widget instead.

High-level workflow

1. You create a transfer intent (API).
2. The transfer moves through statuses as funds are received and processed.
3. You track status by polling the transfer endpoints.

Integration overview

1. Onboard the customer (KYC/KYB gates transfers) Start here: /platform/customers
2. Create funding instruments (bank account and/or wallet)
   • Bank accounts: /platform/bank-accounts
   • Wallets: /platform/wallets
3. Create a transfer (API)
   Use POST /v2/transfer. See full guide and examples below.
4. Track status and handle outcomes
   Use GET /v2/transfer and GET /v2/transfer/{id}. See examples below.

Supported rails & currencies

SpherePay supports a variety of currencies for transfers. You can check the list of supported currencies in the table below. See Supported rails & currencies for more details.

Transfer Creation (API)

Request examples

{
  "amount": "100.00",
  "customer": "{{customer_id}}",
  "source": {
    "type": "bank_account",
    "id": "{{bank_account_id}}",
    "currency": "usd",
    "network": "ach"
  },
  "destination": {
    "type": "wallet",
    "id": "{{wallet_account_id}}",
    "currency": "usdc",
    "network": "ethereum"
  }
}

{
  "amount": "100.00",
  "customer": "{{customer_id}}",
  "source": {
    "type": "wallet",
    "id": "{{wallet_account_id}}",
    "currency": "usdc",
    "network": "ethereum"
  },
  "destination": {
    "type": "bank_account",
    "id": "{{bank_account_id}}",
    "currency": "usd",
    "network": "ach"
  }
}

{
  "amount": "500.00",
  "customer": "{{customer_id}}",
  "source": {
    "type": "bank_account",
    "id": "{{bank_account_id}}",
    "currency": "brl",
    "network": "pix"
  },
  "destination": {
    "type": "wallet",
    "id": "{{wallet_account_id}}",
    "currency": "usdc",
    "network": "polygon"
  },
  "integratorBpsFeeRate": "50"
}

{
  "amount": "500.00",
  "customer": "{{customer_id}}",
  "source": {
    "type": "wallet",
    "id": "{{wallet_account_id}}",
    "currency": "usdc",
    "network": "polygon"
  },
  "destination": {
    "type": "bank_account",
    "id": "{{bank_account_id}}",
    "currency": "brl",
    "network": "pix"
  },
  "integratorBpsFeeRate": "50"
}

BRL/PIX transfer constraints

BRL transfers use the PIX instant payment network and have the following constraints:

• Transfer limits: Applied to the source-currency amount (no FX conversion). On-ramp (PIX BRL → USDC/USDT): R$1.00–R$7,500.00. Off-ramp (USDC/USDT → PIX BRL): $1.00–$7,500.00 (stablecoin units, ~1:1 USD). Limits may be increased based on due diligence — contact your SpherePay representative.
• Supported wallet networks: polygon, ethereum, base, tron. Solana is not supported for BRL transfers.
• Supported stablecoins: USDC on Polygon/Ethereum/Base, USDT on Polygon/Ethereum/Tron. USDT on Base and USDC on Tron are not supported.
• Fees: Only integratorBpsFeeRate (basis points) is supported. integratorFixedFee is not allowed for BRL transfers because fees are collected on the stablecoin side, and a fiat-denominated fixed fee would require cross-currency conversion.
• Bank accounts: The destination (off-ramp) or source (on-ramp) bank account must be a PIX account (currency brl, network pix). See Bank Accounts for creating PIX accounts.
• Verification: BRL transfers require a separate verification profile. Contact your SpherePay representative for access.

Response example

{
  "id": "payout_1234567890abcdef12345678",
  "type": "on_ramp",
  "status": "pendingFunding",
  "customer": "customer_123abc..."
}

For full request/response details, see the Create Transfer API Reference.

Track transfers (list + retrieve)

List transfers

For full API specification, refer to the List Transfers API Reference.

Retrieve a transfer by ID

For the full API specification, see the Get a Transfer API Reference.