Retrieve a Transfer with Deposit Instructions

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.

Endpoint

GET https://api.spherepay.co/v2/transfer/{id}

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer <token>

Path parameters

string

required

The unique transfer ID, prefixed with payout_ (e.g. payout_d243ab2b1de4447d8a046d87fefe58cf).

  -H "Authorization: Bearer $SPHEREPAY_API_KEY"

Response fields

string

Unique transfer identifier, prefixed with payout_.

type

string

Transfer direction: on_ramp or off_ramp.

status

string

Current transfer status. Possible values:

Value	Description
`pendingFunding`	Awaiting the customer’s deposit.
`pendingReview`	Under manual review before processing.
`fundsReceived`	Incoming funds detected, processing starting.
`processing`	Conversion or delivery in progress.
`succeeded`	Transfer completed successfully.
`undeliverable`	Funds could not be delivered to the destination.
`returned`	Funds were returned to the originator.
`pendingRefundInformation`	Additional information needed to issue a refund.
`failed`	Transfer failed.
`canceled`	Transfer was canceled before funding.
`refunded`	Funds were refunded to the customer.
`unexpectedError`	An unexpected error occurred. Contact support.
`failedPrecondition`	A required precondition was not met.
`expired`	The transfer expired before being funded.

customer

string

The customer ID associated with this transfer.

externalId

string

Integrator-defined reference ID, if provided at creation.

source

object

Details of the funding source.

Show source properties

string

Source resource ID (wallet or bank account).

type

string

Source type: wallet or bank_account.

destination

object

Details of the delivery destination.

Show destination properties

string

Destination resource ID.

type

string

Destination type: wallet or bank_account.

currency

string

Destination currency (e.g. usdc, usd, brl).

network

string

Destination network or payment rail (e.g. sol, ach, pix).

amount

string

Amount delivered or expected at the destination.

exchangeRate

string

Exchange rate applied between source and destination currencies.

depositAccount

object

Deposit instructions the customer uses to fund the transfer. Present on on-ramp transfers in pendingFunding status.

Show depositAccount properties

type

string

Always bank_account for on-ramp transfers.

bankDetails

object

Full bank account details for funding.

Show bankDetails properties

bankName

string

Name of the receiving bank.

accountHolderName

string

Account holder name.

accountType

string

Account type (e.g. checking, savings).

accountNumber

string

Account number.

routingNumber

string

ACH routing number (US wire/ACH).

bic

string

BIC/SWIFT code (international wires).

iban

string

IBAN (SEPA transfers).

pixKey

string

PIX key (BRL/PIX transfers).

brCode

string

EMV QR code payload for PIX payments. Scan with a banking app to auto-fill payment details.

bankAddress

string

Physical address of the receiving bank.

beneficiaryAddress

string

Address of the account beneficiary.

memo

string

Reference memo that must be included with the deposit so SpherePay can match the funds to this transfer.

fees

object

Fee breakdown for the transfer.

Show fees properties

integratorFee

object

Your integrator fee.

Show integratorFee properties

fixedAmount

string

Fixed fee component.

bpsRate

string

BPS rate applied.

bpsAmount

string

Computed BPS fee amount.

totalAmount

string

Total integrator fee charged.

currency

string

Currency of the fee.

platformFee

object

SpherePay platform fee (same structure as integratorFee).

quote

object

Quote linked to this transfer, if applicable.

Show quote properties

string

Quote ID.

expiresAt

string

ISO 8601 expiry timestamp of the quote.

tracking

object

Network-level tracking identifiers, populated once the transfer is processing or complete.

Show tracking properties

source

object

Tracking data for the inbound leg.

Show source tracking properties

imad

string

Input Message Accountability Data (wire transfers).

omad

string

Output Message Accountability Data (wire transfers).

traceNumber

string

ACH trace number.

transactionId

string

On-chain transaction hash (crypto transfers).

uetr

string

Unique End-to-End Transaction Reference (SWIFT).

destination

object

Tracking data for the outbound leg (same structure as source).

created

string

ISO 8601 timestamp of transfer creation.

updated

string

ISO 8601 timestamp of the most recent status update.

  "id": "payout_d243ab2b1de4447d8a046d87fefe58cf",
  "externalId": "merchant_ref_123",
  "type": "on_ramp",
  "status": "pendingFunding",
  "customer": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "fees": {
    "integratorFee": {
      "fixedAmount": "1.00",
      "bpsRate": "10",
      "bpsAmount": "0.50",
      "totalAmount": "1.50",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "2.00",
      "bpsRate": "10",
      "bpsAmount": "0.50",
      "totalAmount": "2.50",
      "currency": "usd"
    }
  },
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "amount": "496.00",
    "exchangeRate": "1.00"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "SpherePay Inc.",
      "accountType": "checking",
      "accountNumber": "1234567890",
      "routingNumber": "026009593",
      "bic": "BOFAUS3N",
      "iban": null,
      "pixKey": null,
      "brCode": null,
      "bankAddress": "100 N Tryon St, Charlotte, NC 28202, USA",
      "beneficiaryAddress": "350 Mission St, San Francisco, CA 94105, USA",
      "memo": "BBE6C7EB4A3F"
    }
  },
  "quote": {
    "id": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "expiresAt": "2026-04-01T10:15:00.000Z"
  },
  "tracking": {
    "source": {
      "imad": "20260401BOFAUS3N000042",
      "omad": "20260401BOFAUS3N000042000001",
      "traceNumber": "026009591234567",
      "transactionId": null,
      "uetr": null
    },
    "destination": {
      "imad": null,
      "omad": null,
      "traceNumber": null,
      "transactionId": "4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b",
      "uetr": null
    }
  },
  "created": "2026-04-01T10:00:00.000Z",
  "updated": "2026-04-01T10:05:30.000Z"
}

Error codes

Status	Code	Description
`400`	`address/invalid`	The request is malformed.
`404`	`resource/not-found`	No transfer exists with the given ID.
`422`	`validation/failed`	The provided ID did not pass format validation.

Last modified on May 12, 2026

List On-Ramp and Off-Ramp Transfers

Cancel an Unfunded Pending Transfer

⌘I

  -H "Authorization: Bearer $SPHEREPAY_API_KEY"

  "id": "payout_d243ab2b1de4447d8a046d87fefe58cf",
  "externalId": "merchant_ref_123",
  "type": "on_ramp",
  "status": "pendingFunding",
  "customer": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "fees": {
    "integratorFee": {
      "fixedAmount": "1.00",
      "bpsRate": "10",
      "bpsAmount": "0.50",
      "totalAmount": "1.50",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "2.00",
      "bpsRate": "10",
      "bpsAmount": "0.50",
      "totalAmount": "2.50",
      "currency": "usd"
    }
  },
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "amount": "496.00",
    "exchangeRate": "1.00"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "SpherePay Inc.",
      "accountType": "checking",
      "accountNumber": "1234567890",
      "routingNumber": "026009593",
      "bic": "BOFAUS3N",
      "iban": null,
      "pixKey": null,
      "brCode": null,
      "bankAddress": "100 N Tryon St, Charlotte, NC 28202, USA",
      "beneficiaryAddress": "350 Mission St, San Francisco, CA 94105, USA",
      "memo": "BBE6C7EB4A3F"
    }
  },
  "quote": {
    "id": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "expiresAt": "2026-04-01T10:15:00.000Z"
  },
  "tracking": {
    "source": {
      "imad": "20260401BOFAUS3N000042",
      "omad": "20260401BOFAUS3N000042000001",
      "traceNumber": "026009591234567",
      "transactionId": null,
      "uetr": null
    },
    "destination": {
      "imad": null,
      "omad": null,
      "traceNumber": null,
      "transactionId": "4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b",
      "uetr": null
    }
  },
  "created": "2026-04-01T10:00:00.000Z",
  "updated": "2026-04-01T10:05:30.000Z"
}

Documentation Index

​Endpoint

​Authentication

​Path parameters

​Response fields

​Error codes

Endpoint

Authentication

Path parameters

Response fields

Error codes