Документация/Приём платежей/Статусы
Статусы платежа
Статус отвечает на вопрос «что происходит», признак final — на вопрос «изменится ли это ещё». Решение о выдаче товара принимается только по обоим сразу.
Признак final
Критерий успеха
Оплата успешна только при status = "succeeded" и final = true одновременно. Любой ответ с final = false — это промежуточное состояние, а не успех.
Неизвестный статус — не успех
Обработчик обязан переживать появление нового состояния. Никогда не приводите незнакомый статус к успеху: правильная реакция — оставить заказ неоплаченным и запросить статус явно.
Состояния
| Статус | final | Что делать |
|---|---|---|
| awaiting_payment_data | false | Плательщик ещё не отправил платёжные данные |
| processing | false | Ждать вебхук или статус; повторно платёж не создавать |
| requires_action | false | Выполнить next_action; 3-D Secure — только в браузере плательщика |
| authorized | false | Средства заблокированы; выполнить capture или отмену по согласованному потоку |
| succeeded | true | Единственный успешный результат списания |
| declined | true | Отказ; показать безопасное сообщение, при необходимости создать новый платёж |
| failed | true | Технически или валидационно не выполнено |
| canceled | true | Платёж отменён |
| expired | true | Сессия или авторизация истекла |
| manual_review | false | Товар не выдавать; обратиться в поддержку или дождаться сверки |
| partially_refunded | true | Частичный возврат, если возможность доступна каналу |
| refunded | true | Полный возврат |
authorized намеренно выделен: деньги заблокированы, но не списаны. В интерфейсах его показывают контурной, а не залитой пилюлей — удержание не должно выглядеть как расчёт.
Чтение статуса
Основной канал изменений — вебхуки. Прямой запрос статуса нужен для восстановления после пропущенной доставки, сверки, выяснения неизвестного сетевого результата и контрольного чтения перед выдачей товара.
GET /api/v1/payments/{payment_id}Расписание опроса
Через 1, 2, 4, 8 секунд, затем раз в 10 секунд и не дольше срока жизни сессии. Плотный цикл запрещён. Запрос статуса читает состояние платформы и не инициирует обращение к провайдеру.