Transaction statuses
Every status an order or a funding can have, where your money is in each, and how to read a status change.
Every money movement has a status, in the server's words. This page lists each one the contract defines, with where your money is, and the rules for reading a change.
Order statuses
| Status | Your money | What to do |
|---|---|---|
| Processingprocessing | Held. Delivery is in progress. | Wait for the next state. |
| Succeededsucceeded | Captured. The order is paid for. | Nothing. completed_at is set. |
| Failedfailed | Released back to available. | Read status_reason; order again if it makes sense. |
| Under reviewunder_ | Your funds stay held. | No action needed. |
An order is accepted as processing and ends as succeeded, with its amount captured, or failed, with it released back to available. under_review keeps the amount held until the outcome is known. Why an order is in its status is status_reason; see Orders and statuses.
A Telegram Premium gift Telegram refuses, for example to an account that may already have Premium, is failed: the amount held for it is released once. Its status_reason says why.
Funding statuses
| Status | Meaning |
|---|---|
| Pendingpending | Received, not yet credited (counted in pending_funding). |
| Creditedcredited | On the balance. Raises one funding.credited event. |
| Heldheld | Kept back, not credited. No event is raised for it. |
| Rejectedrejected | Not accepted. |
Only a credited funding is money you can spend. What each movement on the statement means is in Funding your account.
The events that announce them
An order's status has an event of the same name, and two more mark its start and its refund: order.accepted, order.processing, order.succeeded, order.failed, order.refunded, order.under_review. A credited funding raises funding.credited, and a confirmed GRAM deposit deposit.confirmed. Each event carries the object as it was at that change; see Webhooks.
Reading a status change
- Use the server's words. Show a status as the API names it, and never work one out from times or amounts.
- Order by
version. Each change of an order increasesversionby one. When a webhook and a poll disagree, the higherversionis the newer state. - Tolerate a status you do not know. New values may be added; treat one as not final, and read the object again later.
- A missing answer is not a status. A timeout means unknown, never failed; see Recovering from failures.
- Only
succeededmeans delivered.processing, a request handed to a provider and a transaction seen on a network are not deliveries.
GRAM deposits
A GRAM deposit has statuses of its own: confirming, credited, on_hold and needs_attention. See Funding with GRAM. deposit.confirmed is raised once a deposit is confirmed, before it is credited, and no event follows its later statuses, so read GET /funding/deposits.
Related guides
- Orders and statuses: each order status, and how an order under review ends.
- Funding your account: fundings and the statement.
- Recovering from failures: what to do in each case.
