PaycrypВебхук оплаты: как сайт узнаёт, что заказ оплачен
Вебхук — уведомление от платёжного сервиса вашему серверу. Он помогает обновить заказ без участия покупателя, но перед выдачей нужно проверить подлинность события, сумму и связь с покупкой.
Почему страницы успеха недостаточно
Покупатель может закрыть браузер сразу после подтверждения в банке. Если выдача зависит только от его возвращения на сайт, оплаченный заказ останется без результата.
Вебхук позволяет серверу получить событие самостоятельно. В Paycryp для подтверждения используется payment.confirmed; есть также события отмены, истечения срока, отклонения и возврата.
Проверьте подпись
Заголовок X-Paycrypt-Signature содержит данные подписи. Важно сохранить именно такое написание: внешние технические имена не меняются вместе с названием бренда в интерфейсе.
Подпись проверяется по исходному телу запроса и секрету терминала. Если сначала разобрать JSON, а затем собрать его заново, пробелы и порядок могут отличаться. Поэтому raw body сохраняют до преобразования.
Секрет не размещают в браузере и не пишут в публичные логи. Полный пример проверки находится в документации API.
Найдите свой заказ
После проверки найдите заказ по orderId. Сверьте валюту и исходную цену baseAmount. Не выдавайте произвольный товар только потому, что событие содержит знакомый e-mail или похожую сумму.
В полезном журнале обработки остаются идентификатор платежа, номер заказа, событие и результат действия. Контакты покупателя и секреты туда без необходимости не добавляют.
Будьте готовы к повторам
Вебхуки могут доставляться повторно. Значение X-Paycrypt-Delivery обозначает доставку и остаётся тем же при её повторах. Обработка должна понимать, что событие уже выполнено.
Защитите также саму выдачу по идентификатору платежа. Это помогает при сбое между изменением заказа и ответом сервера: повтор не создаст второй доступ или второй цифровой ключ.
Учитывайте порядок событий
Paycryp передаёт version — время изменения платежа. Применяйте только более новое состояние. Старое подтверждение не должно возвращать уже возвращённый платёж в статус оплаченного.
При сомнении запросите актуальный платёж через GET. Это также полезно после восстановления вашего сервера, если часть уведомлений была пропущена.
Что проверить на тестах
- Корректное подтверждение открывает нужный заказ.
- Неверная подпись не меняет данные.
- Повтор не выдаёт товар второй раз.
- Старое событие не отменяет новое состояние.
- Временный сбой выдачи можно обработать отдельно.
- Проверка через GET восстанавливает актуальный статус.
После сохранения результата сервер отвечает успешным HTTP-кодом. Долгую выдачу лучше отделить от приёма события так, чтобы уже принятое уведомление не терялось при перезапуске.