Callback и Webhook системы в платежной интеграции
Обработка уведомлений об изменении статуса платежей — один из ключевых компонентов любой платежной интеграции. Именно от того, насколько правильно настроена система callback-уведомлений, зависит автоматизация бизнес-процессов: своевременное подтверждение заказов, отправка товаров, уведомление клиентов и синхронизация данных между системами.
В этой статье мы подробно разберем, как работает система callback-уведомлений в P2P-платежных API, какие данные передаются в уведомлениях, как их правильно обрабатывать и какие подводные камни существуют.
Что такое callback в платежной системе
Callback — это POST-запрос, который платежная система отправляет на URL мерчанта при изменении статуса сделки или выплаты. Это асинхронное уведомление, которое позволяет мерчанту не опрашивать сервер постоянно, а получать информацию только в моменты изменений.
URL для уведомлений можно задать двумя способами: в настройках мерчанта в админке (глобальный URL для всех сделок) или передать параметр callback_url при создании сделки через API. Важный нюанс: callback_url из запроса имеет приоритет над URL из админки. Это позволяет гибко настраивать обработку для разных типов сделок.
Формат callback-уведомления
Уведомление отправляется как POST-запрос с телом в формате JSON. Структура данных включает: id (уникальный идентификатор сделки в системе), external_id (идентификатор заказа в системе мерчанта), status (общий статус: success, fail, pending), sub_status (детальный статус), amount (сумма в минимальных единицах), currency (код валюты), payment_gateway (код платежного метода).
Полный список подстатусов и их значение
pending — сделка создана, ожидает начальной обработки. На этом этапе система ищет подходящие реквизиты для оплаты. Мерчанту не требуется никаких действий.
accepted — сделка принята системой, реквизиты найдены и зарезервированы. Система готовится предоставить их клиенту.
waiting_for_payment — реквизиты предоставлены клиенту, система ожидает перевода. Это ключевой статус для клиента: ему нужно перевести средства на указанные реквизиты в течение времени резервирования (обычно 10-20 минут). Мерчант должен отобразить клиенту таймер обратного отсчета и четкие инструкции по переводу.
successfully_paid — платеж успешно зачислен на счет трейдера. Система проверяет корректность поступления. Мерчант может начинать обработку заказа: подтверждать, запускать сборку, отправлять товар или активировать услугу.
successfully_paid_by_resolved_dispute — оплата подтверждена после разрешения спора администратором. Аналогично successfully_paid, но с отметкой, что оплата была спорной.
fully_completed — сделка полностью завершена. Все средства переведены, никаких дальнейших действий не требуется. Используется для финальной синхронизации статуса.
waiting_details_to_be_selected — система ожидает выбора типа реквизитов. Может возникать, если платежный метод поддерживает несколько типов реквизитов и мерчант должен выбрать подходящий.
waiting_for_dispute_to_be_resolved — по сделке открыт спор, ожидается решение администратора. Мерчант должен приостановить выполнение заказа и подготовить документы для разбирательства.
canceled_by_dispute — сделка отменена по результатам спора. Средства возвращаются одной из сторон в зависимости от решения администратора.
expired — срок действия сделки истек. Клиент не перевел средства в течение установленного времени. Мерчант отменяет заказ и предлагает клиенту создать новый.
cancelled — сделка отменена мерчантом или системой по иным причинам. Мерчант отменяет заказ.
Статусы выплат
Выплаты имеют свою последовательность статусов: pending (создана), waiting_for_trader (ожидание трейдера), processing_by_trader (трейдер обрабатывает), processing_by_administrator (администратор проверяет), fully_completed (выплата выполнена), cancelled (отменена).
Обработка callback на стороне мерчанта
Для корректной обработки callback-уведомлений сервер мерчанта должен реализовать POST-эндпоинт, который принимает JSON, парсит его и выполняет действия в зависимости от статуса.
Важные технические детали:
- Сервер должен возвращать HTTP 200 в ответ на уведомление. Если сервер возвращает 4xx или 5xx, платежная система повторяет отправку несколько раз с увеличивающимся интервалом.
- Рекомендуется проверять IP-адреса отправителя. Платежная система отправляет уведомления с определенных IP-адресов, которые можно получить через поддержку.
- Для защиты от повторной отправки (duplicate callbacks) рекомендуется использовать id уведомления для дедупликации.
- Рекомендуется логировать все полученные callback-уведомления для аудита и отладки.
Обработка ошибок и повторные попытки
Если система мерчанта временно недоступна или возвращает ошибку, платежная система повторяет отправку callback-уведомления. Типичная стратегия повторных попыток: первая попытка через 1 минуту, вторая через 5 минут, третья через 15 минут, четвертая через 30 минут, пятая через 60 минут. После этого уведомление считается потерянным.
Чтобы минимизировать риск потери уведомлений, рекомендуется: держать callback-эндпоинт всегда доступным, возвращать 200 как можно быстрее (обработку выполнять асинхронно), использовать очередь задач для обработки уведомлений.
Выводы
Callback-система — это основа автоматизации платежных процессов. Правильная обработка всех статусов и подстатусов гарантирует, что бизнес-процессы будут выполняться своевременно и без сбоев. Надежный callback-эндпоинт с корректной обработкой всех статусов — это то, что отличает профессиональную платежную интеграцию от любительской.
