Какие события генерирует крипто-checkout?

InfraIO Pay отправляет один вебхук на каждый переход состояния. Эта конечная машина состояний намеренно небольшая, чтобы вы могли привязать выполнение заказа ровно к одному событию, а остальные игнорировать.

  • payment.pending — покупатель отправил транзакцию; подтверждения ещё накапливаются.
  • payment.confirmed — транзакция достигла порога подтверждений своей сети.
  • payment.settled — средства переведены на ваш расчётный кошелёк. Выполняйте заказ здесь.
  • session.expired — окно оплаты закрылось без платежа. Никогда не тарифицируется.

По какому событию выполнять заказ?

Выполняйте заказ по payment.settled. Транзакция в статусе pending всё ещё может не подтвердиться, а пороги подтверждений различаются в зависимости от сети, поэтому если считать любой более ранний статус финальным, вы рискуете отправить заказ против платежа, который никогда не дойдёт. Расчёт (settlement) — это момент, когда деньги безвозвратно становятся вашими.

Если нужно показать покупателю прогресс, можно отображать pending и confirmed в интерфейсе, но необратимое действие (отправка, предоставление доступа, минт) всегда привязывайте к settled.

Как проверить, что вебхук настоящий?

Каждый вебхук подписан секретом вашего эндпоинта. Пересчитайте HMAC по исходному телу запроса и сравните его в constant-time с заголовком подписи; отклоняйте всё, что не совпадает. Если вы новичок в HMAC, справка MDN по SubtleCrypto.sign — хорошее введение, а руководство Stripe по лучшим практикам работы с вебхуками хорошо раскрывает операционную сторону.

Проверяйте подпись до парсинга или обработки. Неподписанный или неверно подписанный запрос никогда не должен попадать в вашу бизнес-логику.

Как сделать доставку безопасной для повторов?

Вебхуки доставляются по принципу at-least-once, поэтому после сетевого сбоя одно и то же событие может прийти более одного раза. Каждое событие несёт ключ идемпотентности; фиксируйте обработанные ключи и игнорируйте (no-op) повторы. Отвечайте 2xx быстро, а медленную работу выполняйте асинхронно, чтобы отправитель не получил тайм-аут и не выполнял ненужные повторы. InfraIO хранит журнал доставок с replay в один клик для случаев, когда вам нужно намеренно переобработать событие.