Transfer Lifecycle and Status Reference

A transfer in SpherePay is the movement of funds between financial accounts — a wallet and a bank account. Every transfer has a source and a destination. After you create a transfer, SpherePay moves it through a series of statuses as funds are received, processed, and delivered. Understanding these statuses lets you build accurate status displays and handle edge cases like failures and refunds.

The `instructions` field

When you create a transfer, the response includes an instructions field that describes what funds the customer needs to send and where. For off-ramp transfers, the depositInstructions sub-field contains the details your customer needs to initiate the on-chain transaction — the destination address, network, currency, and amount.

Use depositInstructions to build and deliver transaction details directly to your customers for off-ramp transfers. Present the address, network, and amount clearly so they can send the exact amount to the correct address.

Transfers that are funded are executed on the next transfer execution cycle.

Transfer statuses

The table below lists every possible status a transfer can reach, in the order they typically occur.

Status	Description
`pendingFunding`	SpherePay is waiting to receive funds from the customer before processing the transfer. This applies to incoming crypto deposits, wires, and ACH transfers.
`pendingReview`	A rare, temporary state triggered when transfer data needs further confirmation. Typically resolves in seconds; otherwise SpherePay will reach out within 24 hours.
`fundsReceived`	SpherePay has received the funds from the customer and is preparing to process the transfer.
`processing`	SpherePay is actively processing the transfer.
`succeeded`	The transfer has succeeded and the funds have been delivered to the destination.
`returned`	The transfer was returned by the destination bank. A refund will be initiated back to the customer.
`pendingRefundInformation`	SpherePay is waiting for the customer to provide further information needed to complete the refund.
`failed`	The transfer has failed. A refund will be initiated back to the customer.
`canceled`	The transfer was canceled by the customer. A refund will be initiated back to the customer.
`refunded`	The refund has been delivered to the customer.
`unexpectedError`	The transfer encountered an unexpected error. A refund will be initiated back to the customer.
`failedPrecondition`	The transfer failed because the customer provided invalid information. A refund will be initiated back to the customer.
`undeliverable` (deprecated)	This status is no longer used.

Tracking status updates

SpherePay can push transfer status updates to your systems via webhooks — subscribe to the transfer.* events to be notified of every transition listed above. Alternatively, poll GET /v2/transfer/{id} at a reasonable interval to track progress.

curl https://api.spherepay.co/v2/transfer/{{transfer_id}} \
  -H "Authorization: Bearer {{api_key}}"

Poll until the transfer reaches a terminal state: succeeded, refunded, failed, canceled, returned, unexpectedError, or failedPrecondition. Once a transfer enters a terminal state, its status will not change.

See the Get a Transfer API reference for the full response schema.

Onboarding

Transfers

Automation

Webhooks

Reference data

Operational

Transfer Lifecycle and Status Reference

The `instructions` field

Transfer statuses

Tracking status updates

​The instructions field

​Transfer statuses

​Tracking status updates

The `instructions` field

Transfer statuses

Tracking status updates