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.