Transfers API

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 or by operational workflows (and optionally via webhooks, see Reference).

Integration overview

1. Onboard the customer (KYC/KYB gates transfers)
   Start here: /guide/compliance
2. Create funding instruments (bank account and/or wallet)
   • Bank accounts: /guide/product-guides/bank-accounts
   • Wallets: /api-reference/wallet
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"
  }
}

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.