Статусы платежа

Статус — в поле status объекта платежа. Статусов три.

status	Что значит	Что делать магазину
pending	Платёж создан. Покупатель ещё не заплатил.	Ждать. Заказ не выполнять. Если покупатель хочет вернуться к оплате до expires_at, отправить его на тот же confirmation_url — только если сумма заказа не менялась. Если менялась — создать новый платёж с новым ключом идемпотентности.
succeeded	Покупатель заплатил. paid равно true.	Сверить amount с суммой заказа и выполнить заказ один раз.
canceled	Платёж не оплачен: истёк срок, банк отказал или платёж остановила проверка. Причина — в cancellation_details.	Заказ не выполнять. Чтобы покупатель заплатил снова, создать новый платёж с новым ключом идемпотентности.

Как меняется статус

pending ──► succeeded
   │
   └──────► canceled

• Новый платёж всегда в статусе pending.
• Из pending платёж переходит в succeeded или в canceled.
• succeeded — окончательный статус: дальше он не меняется. Возврат денег статус тоже не меняет: у возврата свой статус (Возвраты), а сколько вернули — в refunded_amount.

Правила для кода

1. Выполняйте заказ только при status = succeeded. Не смотрите для этого на paid, income_amount или факт возврата покупателя на сайт.
2. Перед выполнением заказа сверьте amount.value и amount.currency с суммой заказа. Если сумма заказа изменилась после создания платежа (покупатель поменял корзину, открыл заказ в двух вкладках), создайте новый платёж с новым ключом идемпотентности. Платёж на старую сумму не засчитывайте; если его оплатят — верните деньги (как).
3. Незнакомый статус считайте как pending: ждите и запросите платёж позже.

Кто отменил платёж

У платежа со статусом canceled есть поле cancellation_details:

{
  "party": "avantpay",
  "reason": "expired_on_confirmation"
}

party — кто отменил:

party	Кто
merchant	Магазин. Сейчас не встречается: отменить платёж через API нельзя.
avantpay	AvantPay: истёк срок оплаты, платёж остановила проверка безопасности или его не удалось создать.
payment_network	Банк покупателя, платёжная система или СБП.

Не стройте логику заказа на party и reason: для решения достаточно status. Эти поля нужны, чтобы объяснить покупателю, что случилось.

Причины отмены

reason — почему отменён платёж. Что бы ни было в reason, заказ не выполняйте. Если покупатель хочет заплатить снова, создайте новый платёж с новым ключом идемпотентности.

reason	Кто ставит	Что случилось	Что сказать покупателю
3d_secure_failed	payment_network	Покупатель не прошёл проверку 3-D Secure: ввёл неверный код или не дождался его.	Попробуйте оплатить ещё раз. Если не получится — обратитесь в свой банк.
call_issuer	payment_network	Банк покупателя отказал без объяснения причины.	Обратитесь в свой банк или оплатите другим способом.
canceled_by_merchant	merchant	Платёж отменил магазин. Сейчас не встречается.	—
card_expired	payment_network	Истёк срок действия карты.	Оплатите другой картой или другим способом.
country_forbidden	payment_network	Картой этой страны здесь заплатить нельзя.	Оплатите картой другого банка или другим способом.
expired_on_confirmation	avantpay, payment_network	Покупатель не заплатил вовремя: прошёл expires_at или истёк срок QR-кода или ссылки у банка.	Время на оплату вышло. Начните оплату заново.
fraud_suspected	avantpay, payment_network	Платёж остановлен из-за подозрения в мошенничестве. У avantpay — покупатель заблокирован или превысил лимиты магазина: открытые и неоплаченные ссылки, частота покупок, сумма.	Оплатить сейчас нельзя. Если это ошибка — напишите в поддержку магазина.
general_decline	avantpay, payment_network	Причина не уточняется.	Попробуйте ещё раз или оплатите другим способом.
insufficient_funds	payment_network	Не хватает денег на счёте покупателя.	Пополните счёт или оплатите другим способом.
internal_timeout	payment_network	Банк или платёжная система не ответили вовремя.	Попробуйте оплатить ещё раз.
invalid_card_number	payment_network	Неверный номер карты.	Проверьте номер карты и оплатите ещё раз.
invalid_csc	payment_network	Неверный код CVV2/CVC2.	Проверьте код и оплатите ещё раз.
issuer_unavailable	payment_network	Банк покупателя недоступен.	Попробуйте позже или оплатите другим способом.
payment_method_limit_exceeded	avantpay, payment_network	Исчерпан лимит платежей для способа оплаты или карты. У avantpay — списание по сохранённому способу превысило лимит автоплатежей.	Попробуйте позже, на другую сумму или другим способом.
payment_method_restricted	payment_network	Операции этим способом запрещены, например карта заблокирована.	Обратитесь в свой банк или оплатите другим способом.
permission_revoked	avantpay	Списание по сохранённому способу невозможно: покупатель отключил автоплатежи.	Оплатите заново и снова сохраните способ оплаты.

Если придёт значение, которого нет в таблице, обработайте его как general_decline.