Callback-уведомления в платежной интеграции: почему от их правильной настройки зависит судьба вашего бизнеса
В любой платежной системе есть один компонент, о котором вспоминают только когда что-то идет не так. Это callback-уведомления. Они работают в фоне, незаметно для пользователя, и от их корректной настройки зависит, получит ли клиент свой товар после оплаты, получит ли мерчант деньги после возврата, и в чью пользу решится спор, если что-то пойдет не так.
Callback — это POST-запрос, который платежная система отправляет на сервер мерчанта при изменении статуса сделки или выплаты. По сути, это асинхронный сигнал, который сообщает бизнесу: произошло событие, реагируй.
Казалось бы, что может пойти не так? Принять POST, распарсить JSON, выполнить действие. На практике неправильная обработка колбэков — причина номер один проблем в платежных интеграциях. За годы работы я видел десятки кейсов, когда мерчанты теряли заказы, отправляли товары без оплаты или дважды подтверждали один и тот же заказ из-за того, что не разобрались с колбэками.
Как устроены callback-уведомления в P2P-платформах
Возьмем для примера платформу PayShark. Каждый раз, когда статус сделки или выплаты меняется, система отправляет POST-запрос на URL, который мерчант указал при создании сделки или в настройках своего аккаунта.
В теле запроса — JSON с набором ключевых полей. Поле id — уникальный идентификатор сделки в системе платежной платформы. Поле external_id — идентификатор заказа в системе мерчанта, который он передал при создании сделки. Поле status — общий статус сделки: success, fail или pending. Поле sub_status — детальный статус, который уточняет, на каком этапе находится сделка. Поля amount, currency и payment_gateway — сумма, валюта и платежный метод.
Самое важное поле — sub_status. Именно по нему мерчант определяет, что делать дальше.
Карта подстатусов и действий
Когда сделка только создана, ее подстатус — pending. Это означает, что система ищет подходящие реквизиты и резервирует их. На этом этапе мерчанту не нужно ничего делать, кроме как отобразить клиенту индикатор загрузки.
Когда реквизиты найдены, подстатус меняется на waiting_for_payment. Теперь клиенту нужно показать реквизиты для перевода: номер карты, получателя, точную сумму. Мерчант должен отобразить эту информацию на странице заказа и запустить таймер обратного отсчета на время резервирования реквизитов.
Когда клиент перевел деньги и трейдер подтвердил получение, подстатус меняется на successfully_paid. Это критический момент. Мерчант должен немедленно подтвердить заказ, запустить процесс сборки и отправки, уведомить клиента об успешной оплате.
Когда сделка полностью завершена и все средства переведены, подстатус меняется на fully_completed. Это финальный статус, после которого никаких дальнейших изменений не будет.
Если клиент не перевел деньги в течение времени резервирования, подстатус становится expired. Мерчант должен отменить заказ и предложить клиенту новый способ оплаты.
Если сделка отменена мерчантом или системой, подстатус — cancelled. Заказ отменяется, товар возвращается в резерв.
Если возник спор между клиентом и трейдером, подстатус — dispute. Мерчант приостанавливает выполнение заказа и ждет решения администраторов платформы.
Пять правил надежной обработки колбэков
Правило первое — возвращайте HTTP 200 как можно быстрее. Не делайте внутри обработчика колбэка тяжелых операций: обновления базы данных, отправки писем, интеграции с CRM. Вся эта работа должна выполняться асинхронно, через очередь задач. Ваша цель — подтвердить получение уведомления за минимальное время, чтобы платежная система не начала повторные отправки.
Правило второе — реализуйте дедупликацию. Платежная система может отправить один и тот же колбэк несколько раз, если предыдущий ответ не был получен или был получен с ошибкой. Храните ID обработанных уведомлений в базе данных и проверяйте перед каждой обработкой.
Правило третье — логируйте все. Каждый полученный колбэк должен быть записан в лог с полным телом запроса, временем получения и результатом обработки. Это спасет вас, когда через полгода клиент скажет, что не получил заказ, и нужно будет восстанавливать хронологию событий.
Правило четвертое — проверяйте источник. Колбэки могут приходить только с определенных IP-адресов платежной системы. Настройте firewall или проверку в коде, чтобы отсеивать поддельные уведомления.
Правило пятое — обрабатывайте все подстатусы. Если ваша система обрабатывает только successfully_paid и игнорирует expired, cancelled и dispute, рано или поздно это приведет к проблеме. Клиент не перевел деньги вовремя, заказ повис в статусе ожидания, а через неделю клиент требует возврат.
Статусы выплат
Для выплат система статусов немного отличается. После создания выплата проходит через pending, waiting_for_trader, processing_by_trader и fully_completed. Если что-то пошло не так, выплата переходит в cancelled.
Каждое изменение статуса выплаты также сопровождается callback-уведомлением. Если вы используете Payout API для массовых выплат, обработка колбэков критически важна для своевременного обновления статусов выплат в вашей системе.
Практический кейс
Крупная финтех-платформа, обрабатывающая около 5000 транзакций ежедневно, столкнулась с проблемой: около 2 процентов заказов зависали в статусе pending после оплаты. Клиенты платили, но не получали товар, и службе поддержки приходилось вручную разбираться с каждым случаем.
Причина оказалась банальной: callback-эндпоинт платформы был настроен на синхронную обработку, и при высокой нагрузке не успевал обработать все уведомления в течение тайм-аута. Платежная система считала, что уведомление не доставлено, и не отправляла повторно, так как статус сделки не менялся.
Решение заняло два часа: перевели обработку колбэков на асинхронную очередь задач (RabbitMQ), оптимизировали запросы к базе данных и настроили мониторинг пропущенных уведомлений. Проблема исчезла полностью, и больше ни один заказ не зависал из-за необработанного колбэка.
Заключение
Callback-уведомления — это не техническая деталь, а ключевой элемент автоматизации платежного бизнеса. Правильная обработка колбэков обеспечивает своевременное подтверждение заказов, корректное управление статусами и защиту от спорных ситуаций. Уделите этому компоненту интеграции столько же внимания, сколько и созданию сделок — и ваша платежная система будет работать как часы.
