> ## 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.

# Transfer Lifecycle and Status Reference

> Understand how SpherePay transfers move through each status — from pendingFunding through succeeded, returned, or failed — and how to handle each state.

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.

<Tip>
  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.
</Tip>

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. Poll `GET /v2/transfer/{id}` at a reasonable interval to track progress.

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

<Note>
  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.
</Note>

See the [Get a Transfer API reference](/api-reference/transfer/get-id) for the full response schema.