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.Documentation Index
Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
Use this file to discover all available pages before exploring further.
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.
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. |
Polling for status updates
SpherePay does not push transfer status updates via webhook by default. PollGET /v2/transfer/{id} at a reasonable interval to track progress.
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.