Skip to content

Chapter 2 · API integration

Payment statuses: pending, succeeded, failed, canceled, expired

What each status means and when to fulfil the order.

2 min read

On this page
  1. Statuses
  2. Why is my payment stuck in pending?
  3. Why did my payment fail?
  4. When to fulfil the order
  5. After a successful payment
  6. Legacy API (v1/v2) statuses

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_in 300–900 seconds) and then becomes expired.
  • 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.succeeded webhook with a verified signature, or
  • status: "succeeded" in the response of GET /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_url field gets a link to the receipt page (live only).
  • API v3 has no refunds — succeeded is 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).

Was this article helpful?

Didn’t find an answer?

Send a request — a specialist will check your account and reply.