Короткий ответ
Надежная платежная интеграция разделяет заказ и попытку оплаты, хранит идентификаторы на сервере, обрабатывает повторные уведомления идемпотентно и сверяет статусы с реестром.
- Секреты API находятся только на сервере.
- Заказ и платеж — разные сущности.
- Webhook может приходить повторно или не по порядку.
- Финансовый реестр нужен даже при работающем API.
Модель данных до первого запроса
Создайте отдельные записи для заказа, платежной попытки и события уведомления. Один заказ может иметь несколько попыток: отказ, истечение срока и новый платеж. Поэтому нельзя использовать только номер заказа как единственный идентификатор транзакции.
Храните сумму и валюту на сервере и не доверяйте значениям из браузера. Изменение заказа должно проходить через вашу бизнес-логику, а не через параметры redirect URL.
- merchant_order_id — внутренний заказ;
- provider_payment_id — платежная попытка;
- event_id — полученное уведомление;
- amount и currency — ожидаемые параметры;
- status и updated_at — текущее состояние.
Создание платежа и выдача клиенту
Сервер проверяет заказ, создает платеж через согласованный API и сохраняет ответ. Затем фронтенд получает только данные, необходимые для отображения ссылки или QR. Секреты и служебные заголовки не передаются клиенту.
Повторный запрос пользователя не должен незаметно создавать множество активных платежей. Определите правило: возвращать существующую актуальную попытку или создавать новую с явной связью.
Обработка webhook
Webhook подтверждает изменение статуса независимо от поведения браузера. Проверяйте подлинность события по документации, сравнивайте сумму и идентификаторы, сохраняйте исходный факт получения и отвечайте быстро. Тяжелые действия лучше выполнять после фиксации события.
Идемпотентность означает, что одно уведомление, полученное несколько раз, приводит к одному бизнес-результату. Нельзя дважды выдать товар, начислить баланс или отправить одинаковое поручение.
- проверить событие;
- записать идентификатор;
- сравнить ожидаемые параметры;
- атомарно изменить статус;
- поставить дальнейшую обработку в очередь.
Наблюдаемость и сверка
Логи должны позволять восстановить путь заказа без записи секретов или лишних персональных данных. Добавьте корреляционный идентификатор, метрики ошибок и очередь повторной проверки зависших платежей.
Ежедневно сопоставляйте внутренние операции с кабинетом и реестром. API отвечает за онлайн-сценарий, а сверка подтверждает полноту учета.
Вопросы и ответы
Можно ли вызывать платежный API из браузера?
Секретные методы следует вызывать с сервера. Фронтенд получает только данные, необходимые покупателю.
Что делать при повторном webhook?
Проверить идентификатор события и текущее состояние, затем выполнить изменение идемпотентно.
Нужно ли опрашивать статус, если есть webhook?
Webhook является основным каналом события, но выборочная повторная проверка и ежедневная сверка повышают надежность.
Источники и правила
Используем официальные материалы платежной системы и политики WHITECAPITAL. Для конкретного подключения приоритет имеют договорные документы.
Материал предназначен для операционной ориентации и не является обещанием подключения, универсальной доступности метода, фиксированной комиссии или срока расчетов.