Колбек от банка

Банк редко сообщает результат сразу в ответ на запрос. Чаще он присылает уведомление позже, когда платёж дошёл до окончательного состояния. Такие уведомления приходят в ядро — вопреки названию, сервис колбеков к ним отношения не имеет и занимается только уведомлениями мерчанту.

Как это выглядит целиком

Два вида адресов

Большинство провайдеров принимают адрес уведомления в самом запросе на платёж. В этом случае мы даём им персональный адрес, в котором зашит идентификатор транзакции: когда уведомление придёт, мы сразу знаем, о каком платеже речь.

Некоторые провайдеры так не умеют — у них адрес настраивается один раз на стороне банка и одинаков для всех платежей. Для них есть общий адрес на интеграцию, и транзакцию приходится искать по содержимому уведомления: по нашему номеру заказа, по идентификатору на стороне банка или по другому полю, о котором договорились с конкретным провайдером. Именно поэтому в ядре живёт набор частных случаев на такие интеграции — это не наследие, а следствие того, что провайдеры разные.

Из этого следует практическое правило: интеграция с общим адресом требует правки в ядре, а не только нового драйвера.

Проверка отправителя

Уведомление приходит из интернета, поэтому первым делом проверяется, откуда оно пришло: у каждой интеграции есть список разрешённых адресов провайдера. Список поддерживается вместе с подключением провайдера, и его расширение — отдельная задача для инфраструктурной команды.

Подпись тела проверяется не всегда, и это осознанное решение. В большинстве интеграций уведомление вообще не считается источником правды.

Почему телу уведомления не верят

Уведомление для нас — не результат, а сигнал, что пора спросить банк. Получив его, ядро в большинстве случаев не разбирает содержимое, а обращается к драйверу с вопросом о текущем статусе платежа и принимает решение уже по ответу банка.

Так сделано по двум причинам. Во-первых, подделанное или случайно повторённое уведомление не сможет изменить судьбу платежа: мы всё равно спросим банк. Во-вторых, форматы уведомлений у провайдеров разные и меняются, а запрос статуса стабилен.

Исключения бывают там, где провайдер жёстко ограничивает частоту запросов и уведомление — единственный доступный источник. В таких интеграциях подпись тела обязательна.

Что происходит дальше

Ядро находит транзакцию, при необходимости запрашивает у банка статус, сохраняет полученные от драйвера данные и, если результат окончательный, финализирует платёж — со всеми последствиями для баланса, описанными в базовом флоу. Транзакция в терминальном статусе не изменится, даже если уведомление пришло повторно.

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

Почему это не единственный путь

Уведомление может не дойти — из-за сети, из-за ошибки на стороне провайдера, из-за того, что адрес не был передан. Поэтому оно дублируется регулярным переспросом статуса: даже полностью молчащий провайдер не оставит платёж в подвешенном состоянии навсегда.

Где ломается чаще всего

Симптом	Обычная причина
Уведомления не приходят вовсе	Адрес провайдера не в списке разрешённых, запросы отбиваются на подступах
Уведомление пришло, платёж не изменился	Не нашлась транзакция: интеграция с общим адресом, а поле для поиска изменилось
Платёж закрылся позже, чем пришло уведомление	Нормальное поведение: решение принято по ответу банка, а не по уведомлению
Уведомления приходят многократно	Провайдер повторяет доставку, пока не получит ожидаемый ответ

Куда дальше

• Колбек мерчанту — обратное направление, другой сервис.
• Слой драйверов — кто разбирает ответ банка.
• Очереди, таймеры и отложенные задачи — что происходит, когда уведомления нет.