Guides

Transfer states

Every kind of transfer uses one set of states. These are the paths each kind can take:

User to userpending→completedorin_review→completed/failed

On-rampawaiting_funds→funds_received→completedorreturnedcanceledfailed

Off-ramppending→payout_submitted→completedorreturned→refunded

Conversionpending→completedorfailed

Each kind in detail

Transfers of every kind share these states. Which states a kind uses, and how it moves between them:

user_to_user: pending → completed; or pending → in_review → completed or failed; pending → canceled only before posting.
conversion: pending → completed, or pending → failed (quote expired, stock or treasury too low). Settles in one ledger transaction, so it is final in the response.
onramp: awaiting_funds → funds_received → completed. Exceptions: in_review (after funds arrive), returned (funds sent back to the sender, final), canceled (from awaiting_funds, final), failed.
offramp: pending → payout_submitted → completed. Exceptions: in_review (before submission), undeliverable and returned (rail rejected the payout; both move on to refunded), refunded (source wallet credited back, final), failed (refused before the wallet was debited, final).

Final states

completed, failed, canceled, refunded, and returned for an on-ramp are final: the transfer won't change again. Each change fires transfer.state_changed, with the previous state in previous_attributes.

Reasons

When a transfer is in an exception state (in_review, failed, returned, undeliverable, refunded or canceled), state_reason holds a machine-readable code and a message you can show the user.