Order statuses

An order runs through three phases in order: the deposit comes in, the payout goes out, and if the payout cannot be delivered, a refund goes back. status names the phase and how it went.

Deposit

Status	Meaning
deposit_awaiting	The order exists and we are waiting for the user to pay. Show them transferInstructions.
deposit_validating	You called Confirm order, or a provider reported an incoming payment. We are checking it.
deposit_successful	The deposit checked out. The payout starts.
deposit_invalid	The deposit was wrong — wrong amount, wrong narration, wrong sending account.
deposit_canceled	Cancelled before payment, by the user or by Cancel order. Only an order still in deposit_awaiting can be cancelled.
deposit_expired	Not paid by order.expiresAt, or an intermediate action was retried past its attempt cap.

deposit_canceled and deposit_expired are not the end of the story. If the user's payment turns up late we still accept it: the order moves to deposit_successful and the payout runs. Do not release goods or reverse your own records on deposit_canceled or deposit_expired alone — keep listening. deposit_invalid can also be walked back by our support team after a manual check.

Payout

Status	Meaning
payout_pending	We are sending the funds out.
payout_successful	Delivered. This is the happy ending — the crypto is on-chain, or the fiat is in the user's account, or your balance is credited.
payout_failed	Delivery failed — an unusable wallet address, a rejected bank account, a provider outage. Not terminal: a retry moves the order back to payout_pending first, and then to payout_successful if it lands.

Refund

When a payout cannot be delivered at all, the deposit goes back to the user.

Status	Meaning
refund_initiated	A refund has been decided but not started yet.
refund_pending	The refund is being sent.
refund_successful	The user has their money back. Terminal.
refund_failed	The refund attempt failed. Not terminal — a retry re-enters at refund_initiated.

Once a refund exists, the order carries a refund block alongside deposit and payout with its own amounts and transaction. See Get order.

Working with statuses

• Only payout_successful and refund_successful are truly final. Everything else can still move, including the three that look like dead ends.

• Every transition is delivered as an order-status-change webhook, and the whole history is on the order as statusChangeLogs.

• Statuses can be skipped. Do not assume you will observe every intermediate value — branch on the status you receive, not on the one you expected next.

• In sandbox you can force six outcomes with the depositSandboxForcedFlow and payoutSandboxForcedFlow fields on the quote: a deposit success, invalid, underpayment or overpayment, and a payout success or failure. There is no way to force a cancellation, an expiry or a refund. Read the field's own options array — which values a leg offers varies. See Create quote.