Saltar al contenido principal
Advance a sandbox transfer
Este endpoint funciona solo contra https://api.sandbox.spherepay.co. Mueve una transferencia al estado indicado a través del mismo pipeline de estados que usa producción. El webhook transfer.* correspondiente se entrega cuando los webhooks están habilitados para la aplicación; undeliverable no tiene evento de webhook. Avanzar al estado actual no hace nada y devuelve la transferencia sin cambios, y una transición que el ciclo de vida no permite se rechaza con 422.

Autorizaciones

Authorization
string
header
requerido

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

Parámetros de ruta

id
string
requerido

Cuerpo

application/json
status
enum<string>
requerido

The status to advance the transfer to.

Opciones disponibles:
pendingFunding,
pendingReview,
fundsReceived,
processing,
succeeded,
undeliverable,
returned,
processingRefund,
refundFailed,
pendingRefundInformation,
failed,
canceled,
refunded,
unexpectedError,
failedPrecondition,
expired,
unfunded
Ejemplo:

"succeeded"

Respuesta

created
string<date-time>
requerido

The datetime the transfer was created.

Ejemplo:

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

customer
string
requerido

The customer ID.

Ejemplo:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

depositAccount
Deposit Bank Account · object
requerido

The deposit bank account for an on ramp transfer.

destination
Destination Wallet · object
requerido

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

id
string
requerido

A unique identifier for transfer.

Pattern: ^payout_[a-z0-9]{32}$
Ejemplo:

"payout_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

source
Source Bank Account · object
requerido

The source of an on ramp transfer.

Ejemplo:
status
enum<string>
requerido

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

Opciones disponibles:
pendingFunding,
pendingReview,
fundsReceived,
processing,
succeeded,
undeliverable,
returned,
processingRefund,
refundFailed,
pendingRefundInformation,
failed,
canceled,
refunded,
unexpectedError,
failedPrecondition,
expired,
unfunded
Ejemplo:

"pendingFunding"

statusHistory
Transfer Status History Entry · object[]
requerido

Timeline of status transitions for this transfer, ascending by transitionedAt.

Ejemplo:
type
enum<string>
requerido

The transfer type.

Opciones disponibles:
on_ramp,
off_ramp,
fiat_to_fiat,
unmatched_deposit,
microdeposit
Ejemplo:

"on_ramp"

updated
string<date-time>
requerido

The last datetime the transfer was updated.

Ejemplo:

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

externalId
string

The external reference (not stored as unique).

Ejemplo:

"merchant_ref_123"

fees
object

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

fundingDeadline
string<date-time>

The datetime by which the deposit must arrive into the deposit account. A later deposit is not applied to this transfer. Present only on bank-funded transfers that have a deadline. Distinct from quote.expiresAt, which is the expiry of the quoted rate.

Ejemplo:

"2026-11-03T12:00:00.000Z"

paymentDescription
string

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

Ejemplo:

"INV-2026-004 - Q1 software services"

paymentReason
string

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

Ejemplo:

"professional_services"

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.

returnAddress
string

Crypto wallet address where funds are sent if the transfer fails or is refunded. Only present on off-ramp transfers created with a custom return address.

Ejemplo:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

tracking
object

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

Última modificación el 16 de noviembre de 2026