Вебхуки по платёжным ссылкам

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

Куда приходит уведомление

Публичный HTTPS-адрес указывается в личном кабинете: Настройки → Callback URLs. В запросе на создание ссылки отдельный адрес не передаётся.

Уведомления создаются только платежами. Открытие формы, ввод суммы и восстановление сессии покупателя вебхуков не порождают.

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

{
  "id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
  "paymentLinkId": "11111111-2222-4333-8444-555555555555",
  "amount": 1500,
  "currency": "RUB",
  "status": "CONFIRMED",
  "paymentMethod": 2,
  "payload": "ORDER-1001"
}

Пример сокращён: уведомление может содержать дополнительные поля, в том числе данные возврата.

Поле	Как использовать
`id`	Идентификатор отдельного платежа. По нему храните платёж и исключайте повторную выдачу товара или зачисление.
`paymentLinkId`	Идентификатор ссылки из ответа на создание. У всех платежей одной многоразовой ссылки он одинаковый, а `id` разные. Приходит для обоих режимов ссылки. У платежа, не связанного со ссылкой, поля нет.
`amount`, `currency`	Сумма исходного платежа числом и его валюта. После возврата `amount` не уменьшается.
`status`	Статус платежа, не ссылки. Может измениться уже после подтверждения.
`payload`	Ваши данные из ссылки. Если их не передавали — пустая строка.

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

Поля usageMode, orderId и адрес ссылки в уведомление не входят.

Как обработать

Проверьте отправителя. Сверьте X-MerchantId и X-Secret с настройками магазина на своей стороне, секрет сравнивайте за постоянное время. Заголовок User-Agent сам по себе отправителя не подтверждает. API-ключ в логи не пишите.

Сохраните событие или положите его в собственную устойчивую очередь. Зафиксируйте id, paymentLinkId, статус, сумму и валюту. Если платёж вашей системе ещё неизвестен, сопоставьте его со ссылкой через API.

Ответьте 200 OK. Тело ответа не требуется. Подтверждайте и те уведомления, которые уже сохраняли раньше. Если сохранить не удалось — верните ошибку, тогда уведомление будет доставлено повторно. Долгую обработку выполняйте после сохранения: таймаут отправки 30 секунд.

Примените бизнес-действие идемпотентно. Выдача товара или зачисление по CONFIRMED должны выполниться ровно один раз для этого платежа, в том числе при одновременных запросах. Повторный CONFIRMED не означает новую оплату.

Что означает статус

Статус	Действие
`CONFIRMED`	Оплата подтверждена. Выдать товар или зачислить сумму один раз для этого платежа.
`CANCELED`	Оплата отменена. Успешным платежом не считать.
`DISPUTED`	Платёж на проверке. Применить свои правила работы со спорными платежами. После снятия проверки возможен повторный `CONFIRMED`.
`PARTIALLY_REFUNDED`	Частичный возврат. Обрабатывать каждую операцию по `refundId` с учётом `refundStatus`.
`CHARGEBACKED`	Полный возврат. Учесть отмену зачисления; если есть `refundId` — обработать конкретную операцию.

У возвратов смотрите refundStatus: Succeeded — выполнен, Declined — отклонён. Разные refundId при одинаковом статусе — разные операции. Поэтому нельзя отбрасывать все последующие события по одному id или по паре id + status.

Повторы и сверка

Уведомления могут дублироваться, приходить с задержкой и не в том порядке, в котором происходили события. Не откатывайте актуальное состояние из-за позднего сообщения.

При конфликте или неизвестном результате запросите состояние платежа через API. Все платежи по ссылке доступны отдельным эндпоинтом — «Платежи по ссылке».

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

Переход покупателя на return или failedUrl оплату не подтверждает. Финансовое решение принимайте по проверенному уведомлению и актуальным данным API.

Отключение, истечение срока и архивирование ссылки не прекращают уведомления по уже созданным платежам.

Вебхуки по платёжным ссылкам

Куда приходит уведомление#

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

Как обработать#

Что означает статус#

Повторы и сверка#

Куда приходит уведомление

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

Как обработать

Что означает статус

Повторы и сверка