Колбек мерчанту

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

Кто что делает

Ядро в момент финализации собирает тело уведомления, подписывает его, берёт адрес из настроек мерчанта и кладёт готовую задачу в очередь. Сервис доставки забирает задачу, отправляет запрос, записывает попытку и при неудаче повторяет.

Разделение важно понимать при отладке: состав уведомления и подпись — это ядро, а доставка и повторы — сервис колбеков. Если мерчант жалуется на содержимое, смотреть надо в финализацию транзакции, а не в сервис доставки.

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

Что уходит мерчанту

Полный формат — Callback в публичной документации. В теле — идентификатор заказа мерчанта, результат, сумма и валюта, тип операции, текст ошибки при отказе и служебные поля, специфичные для отдельных сценариев. Для двухстадийных платежей добавляется расширенный статус. Отправляется всё это обычным запросом в формате формы, а не в JSON — историческое решение, с которым живут все интеграции.

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

Подпись

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

Это тот же принцип, по которому мерчант подписывает запросы к нам, только в обратную сторону — см. Аутентификация и подписи.

Повторы

Публичное описание — Callback service logic. Политика простая и одинаковая для всех: не больше одиннадцати попыток, первая повторная почти сразу, дальше пауза растёт с каждым разом. Успехом считается нормальный ответ мерчанта; ошибка, таймаут или недоступность — повод повторить.

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

Отсюда главное правило, которое стоит объяснять мерчантам при интеграции: колбек — уведомление, а не гарантия. Корректная интеграция всегда дополняет его собственным запросом статуса, иначе редкая недоступность на стороне мерчанта превращается в потерянный заказ.

История отправок

Каждая попытка записывается в тот же лог взаимодействий, где видна переписка с банками: что мы отправили, что ответил мерчант, какая это была попытка. При споре «мы не получали уведомление» смотреть нужно сюда.

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

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

Куда дальше

• Колбек от банка — входящее направление, другой механизм и другой сервис.
• Баланс, комиссии, финализация — момент, который порождает уведомление.
• superpos-callback — карточка сервиса доставки.