> For the complete documentation index, see [llms.txt](https://docs.fonbnk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fonbnk.com/server-to-server/order-statuses.md). # 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. ```mermaid flowchart TD A[deposit_awaiting] --> B[deposit_validating] A --> E[deposit_canceled] A --> F[deposit_expired] B --> C[deposit_successful] B --> D[deposit_invalid] B --> F E -.late deposit.-> C F -.late deposit.-> C C --> G[payout_pending] G --> H[payout_successful] G --> J[payout_failed] J -.retry.-> G J --> I[refund_initiated] I --> K[refund_pending] I --> M[refund_failed] K --> L[refund_successful] K --> M M -.retry.-> I ``` ### 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](/server-to-server/api-endpoints/confirm-order.md), 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](/server-to-server/api-endpoints/cancel-order.md). 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. | {% hint style="warning" %} `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. {% endhint %} ### 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](/server-to-server/api-endpoints/get-order.md). ### 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](/server-to-server/webhooks.md), 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](/server-to-server/api-endpoints/create-quote.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.fonbnk.com/server-to-server/order-statuses.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.