Перейти к содержимому

Глава 2 · API-интеграция

Статусы платежа: pending, succeeded, failed, canceled, expired

Что означает каждый статус и когда подтверждать заказ.

2 мин чтения

На этой странице
  1. Статусы
  2. Почему платёж висит в pending
  3. Почему платёж стал failed
  4. Когда подтверждать заказ
  5. После успешной оплаты
  6. Статусы старого API (v1/v2)

Платёж создаётся в статусе pending и переходит в один из окончательных статусов ровно один раз.

Статусы

Статус Что означает Событие (webhook)
pending Создан, покупатель ещё не оплатил. —
succeeded Оплачен. Подтверждайте заказ в этом статусе. payment.succeeded
failed Платёж не прошёл; причина — в поле failure. payment.failed
canceled Отменён вами (через API) или покупателем на странице оплаты. payment.canceled
expired Не оплачен до expires_at. payment.expired

События payment.created нет — достаточно ответа на запрос создания.

Почему платёж висит в pending

  • Покупатель ещё на странице оплаты — не ввёл карту или не подтвердил SMS-код.
  • В боевом режиме платёж живёт не дольше 15 минут (expires_in 300–900 секунд), затем становится expired.
  • Если вебхук не пришёл, проверьте статус через GET /api/v3/payments/{id}.

Почему платёж стал failed

Причина — в объекте failure: {"code", "message"}. В боевом режиме код имеет вид gateway_<n> или payment_failed. В песочнице: insufficient_funds, card_declined, expired_card, otp_attempts_exceeded (SMS-код введён неверно 3 раза).

Платёж в статусе failed повторить нельзя — создайте для покупателя новый платёж.

Когда подтверждать заказ

Подтверждайте заказ только на основании:

  • вебхука payment.succeeded с проверенной подписью, или
  • status: "succeeded" в ответе GET /api/v3/payments/{id}.

Возврат браузера покупателя на return_url не является доказательством оплаты: параметры payment_id и status, добавляемые к адресу возврата, может изменить кто угодно.

После успешной оплаты

  • Сумма боевого платежа зачисляется на баланс кассы.
  • В поле receipt_url появляется ссылка на страницу чека (только live).
  • В API v3 нет возвратов (refund) — succeeded окончательный статус.

Статусы старого API (v1/v2)

В интеграции v1/v2 статусы остаются прежними: ожидает оплаты, оплачен (средства зачислены на баланс кассы), истёк или отменён. В v2 неоплаченный счёт автоматически отменяется через 15 минут (ещё 15 минут, если покупатель ввёл карту и ждёт SMS-код).

Статья была полезной?

Не нашли ответ?

Отправьте обращение — специалист проверит ваш аккаунт и ответит.