Skip to main content
Retrieve a Transfer
curl --request GET \
  --url https://api.spherepay.co/v2/transfer/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "payout_a1b2c3d4e5f6a7b8c9d0e1f2",
  "type": "on_ramp",
  "status": "pendingFunding",
  "customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "amount": "<string>",
    "exchangeRate": "5.455"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "John Doe",
      "accountType": "savings",
      "accountNumber": "1234567890",
      "routingNumber": "1234567890",
      "bic": "1234567890",
      "iban": "1234567890",
      "pixKey": "+5511999999999",
      "brCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "bankAddress": "123 Main St, Anytown, USA",
      "beneficiaryAddress": "123 Main St, Anytown, USA",
      "memo": "BBE6C7EB4A3F"
    }
  },
  "updated": "2021-01-01T00:00:00.000Z",
  "created": "2021-01-01T00:00:00.000Z",
  "externalId": "merchant_ref_123",
  "fees": {
    "integratorFee": {
      "fixedAmount": "1.00",
      "bpsRate": "10",
      "bpsAmount": "0.10",
      "totalAmount": "1.10",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "2.00",
      "bpsRate": "10",
      "bpsAmount": "0.10",
      "totalAmount": "2.10",
      "currency": "usd"
    }
  },
  "quote": {
    "id": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "expiresAt": "2021-01-01T00:00:00.000Z"
  },
  "paymentReason": "professional_services",
  "paymentDescription": "INV-2026-004 — Q1 software services",
  "tracking": {
    "source": {
      "imad": "20250224MMQFMP0B000012",
      "omad": "123456789012345678901234",
      "traceNumber": "021000021234567",
      "transactionId": "4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b",
      "uetr": "097B365480122XK9"
    },
    "destination": {
      "imad": "20250224MMQFMP0B000012",
      "omad": "123456789012345678901234",
      "traceNumber": "021000021234567",
      "transactionId": "4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b",
      "uetr": "097B365480122XK9"
    }
  }
}
Use this endpoint to fetch the complete details of a single transfer by its unique ID. The response includes the current status, the source and destination resources, fee breakdown, deposit instructions for on-ramp transfers, and network-level tracking identifiers once the transfer has been processed. Poll this endpoint or use webhooks to monitor status transitions throughout the transfer lifecycle.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string
required

The payout ID.

Example:

"payout_d243ab2b1de4447d8a046d87fefe58cf"

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,
microdeposit
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.

​
paymentReason
string

The reason for the payment. Present on BRL transfers and third-party off-ramp transfers.

Example:

"professional_services"

​
paymentDescription
string

A free-text description of the payment purpose. Present on third-party off-ramp transfers.

Example:

"INV-2026-004 — Q1 software services"

​
tracking
object

Tracking references for the transfer. Only included when at least one reference exists.

Last modified on June 18, 2026