Payment statuses: pending, succeeded, failed, canceled, expired
What each status means and when to fulfil the order.
On this page
A payment is created as pending and moves to a final status exactly once.
Statuses
| Status | Meaning | Event (webhook) |
|---|---|---|
pending |
Created; the customer hasn't paid yet. | — |
succeeded |
Paid. Fulfil the order in this status. | payment.succeeded |
failed |
The payment didn't go through; the reason is in failure. |
payment.failed |
canceled |
Canceled by you (via the API) or by the customer on the checkout page. | payment.canceled |
expired |
Not paid before expires_at. |
payment.expired |
There is no payment.created event — the create response is enough.
Why is my payment stuck in pending?
- The customer is still on the checkout page — they haven't entered a card or confirmed the SMS code.
- In live mode a payment lives at most 15 minutes (
expires_in300–900 seconds) and then becomesexpired. - If no webhook arrived, check the status with
GET /api/v3/payments/{id}.
Why did my payment fail?
The reason is in the failure object: {"code", "message"}. In live mode the code looks like gateway_<n> or payment_failed. In the sandbox: insufficient_funds, card_declined, expired_card, otp_attempts_exceeded (the SMS code was entered wrong 3 times).
A failed payment can't be retried — create a new payment for the customer.
When to fulfil the order
Fulfil the order only based on:
- a
payment.succeededwebhook with a verified signature, or status: "succeeded"in the response ofGET /api/v3/payments/{id}.
The customer's browser returning to return_url is not proof of payment: anyone can change the payment_id and status parameters added to the return URL.
After a successful payment
- The amount of a live payment is credited to the cashbox balance.
- The
receipt_urlfield gets a link to the receipt page (live only). - API v3 has no refunds —
succeededis final.
Legacy API (v1/v2) statuses
In v1/v2 integrations statuses stay as before: pending, paid (funds credited to the cashbox balance), expired or canceled. In v2 an unpaid invoice is canceled automatically after 15 minutes (another 15 minutes if the customer has entered a card and is waiting for the SMS code).