Skip to main content
Create a Transfer
curl --request POST \
  --url https://api.spherepay.co/v2/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "500.00",
  "customer": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "source": {
    "type": "bank_account",
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "currency": "usd",
    "network": "ach"
  },
  "destination": {
    "type": "wallet",
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "currency": "usdc",
    "network": "sol"
  },
  "integratorBpsFeeRate": "10"
}
'
{
  "id": "payout_a1b2c3d4e5f6a7b8c9d0e1f2",
  "type": "on_ramp",
  "status": "pendingFunding",
  "customer": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "externalId": "merchant_ref_123",
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "amount": "498.50",
    "exchangeRate": "1.00"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "SpherePay LLC",
      "accountNumber": "1234567890",
      "routingNumber": 26009593,
      "memo": "BBE6C7EB4A3F"
    }
  },
  "fees": {
    "integratorFee": {
      "fixedAmount": "0.00",
      "bpsRate": "10",
      "bpsAmount": "0.50",
      "totalAmount": "0.50",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "1.00",
      "bpsRate": "0",
      "bpsAmount": "0.00",
      "totalAmount": "1.00",
      "currency": "usd"
    }
  },
  "created": "2026-04-01T10:00:00.000Z",
  "updated": "2026-04-01T10:00:00.000Z"
}
Use this endpoint to initiate a money movement for a verified customer. SpherePay supports two transfer directions: on-ramp (fiat → crypto) and off-ramp (crypto → fiat). You define the direction by the types you supply for source and destination — a bank_account source with a wallet destination creates an on-ramp, and the reverse creates an off-ramp. The response includes deposit instructions your customer needs to fund the transfer.
The customer must have an approved verification profile before you can create a transfer on their behalf.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
customer
string
required

The customer's ID.

Pattern: ^customer_[a-z0-9]+$
Example:

"customer_1234567890"

​
quoteId
string
required

The quote ID from a previously created quote. The transfer uses the locked exchange rate, currency, and network from the quote.

Example:

"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

​
source
object
required
​
destination
object
required
​
externalId
string

Integrator-defined external reference. The value is not stored as unique.

Example:

"merchant_ref_123"

Response

​
id
string
required

A unique identifier for transfer.

Pattern: ^payout_[a-z0-9]{24}$
Example:

"payout_a1b2c3d4e5f6a7b8c9d0e1f2"

​
type
enum<string>
required

The transfer type.

Available options:
on_ramp,
off_ramp,
unmatched_deposit
Example:

"on_ramp"

​
status
enum<string>
required

The transfer status. See Transfer Lifecycle for status definitions and transitions.

Available options:
pendingFunding,
pendingReview,
fundsReceived,
processing,
succeeded,
undeliverable,
returned,
pendingRefundInformation,
failed,
canceled,
refunded,
unexpectedError,
failedPrecondition,
expired
Example:

"pendingFunding"

​
customer
string
required

The customer ID.

Example:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

​
source
Source Bank Account · object
required

The source of an on ramp transfer.

Example:
{
  "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "type": "bank_account"
}
​
destination
Destination Wallet · object
required

The destination of an On-ramp transfer. See Wallets for registration.

​
depositAccount
Deposit Bank Account · object
required

The deposit bank account for an on ramp transfer.

​
updated
string<date-time>
required

The last datetime the transfer was updated.

Example:

"2021-01-01T00:00:00.000Z"

​
created
string<date-time>
required

The datetime the transfer was created.

Example:

"2021-01-01T00:00:00.000Z"

​
externalId
string

The external reference (not stored as unique).

Example:

"merchant_ref_123"

​
fees
object

Fee breakdown for the transfer. For floating-rate BRL transfers, this is omitted until settlement is complete.

​
quote
object

The quote used for this transfer, if any. When present, the locked exchange rate from the quote was applied to the destination amount and exchange rate.

Last modified on June 18, 2026