Pular para o conteúdo principal
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 este endpoint para iniciar uma movimentação de dinheiro para um cliente verificado. O SpherePay suporta duas direções de transferência (transfer): on-ramp (fiat → cripto) e off-ramp (cripto → fiat). Você define a direção pelos tipos que fornece para source e destination — uma origem bank_account com um destino wallet cria um on-ramp, e o inverso cria um off-ramp. A resposta inclui instruções de depósito que seu cliente precisa para financiar a transferência.
O cliente deve ter um perfil de verificação approved antes que você possa criar uma transferência em seu nome.

Autorizações

​
Authorization
string
header
obrigatório

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

Corpo

application/json
​
customer
string
obrigatório

The customer's ID.

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

"customer_1234567890"

​
quoteId
string
obrigatório

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

Exemplo:

"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

​
source
object
obrigatório
​
destination
object
obrigatório
​
externalId
string

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

Exemplo:

"merchant_ref_123"

Resposta

​
id
string
obrigatório

A unique identifier for transfer.

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

"payout_a1b2c3d4e5f6a7b8c9d0e1f2"

​
type
enum<string>
obrigatório

The transfer type.

Opções disponíveis:
on_ramp,
off_ramp,
unmatched_deposit
Exemplo:

"on_ramp"

​
status
enum<string>
obrigatório

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

Opções disponíveis:
pendingFunding,
pendingReview,
fundsReceived,
processing,
succeeded,
undeliverable,
returned,
pendingRefundInformation,
failed,
canceled,
refunded,
unexpectedError,
failedPrecondition,
expired
Exemplo:

"pendingFunding"

​
customer
string
obrigatório

The customer ID.

Exemplo:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

​
source
Source Bank Account · object
obrigatório

The source of an on ramp transfer.

Exemplo:
{
  "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "type": "bank_account"
}
​
destination
Destination Wallet · object
obrigatório

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

​
depositAccount
Deposit Bank Account · object
obrigatório

The deposit bank account for an on ramp transfer.

​
updated
string<date-time>
obrigatório

The last datetime the transfer was updated.

Exemplo:

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

​
created
string<date-time>
obrigatório

The datetime the transfer was created.

Exemplo:

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

​
externalId
string

The external reference (not stored as unique).

Exemplo:

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

Última modificação em 18 de junho de 2026