Skip to content

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

StatusYour moneyWhat to do
ProcessingprocessingHeld. Delivery is in progress.Wait for the next state.
SucceededsucceededCaptured. The order is paid for.Nothing. completed_at is set.
FailedfailedReleased back to available.Read status_reason; order again if it makes sense.
Under reviewunder_reviewYour 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

StatusMeaning
PendingpendingReceived, not yet credited (counted in pending_funding).
CreditedcreditedOn the balance. Raises one funding.credited event.
HeldheldKept back, not credited. No event is raised for it.
RejectedrejectedNot 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 increases version by one. When a webhook and a poll disagree, the higher version is 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 succeeded means 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.