Уведомления по выплатам (webhook)

Мы уведомляем вас о каждой смене терминального статуса выплаты. Опрашивать GET /v1/payouts/{id} не нужно.

Куда приходит

1. notify_url, переданный при создании выплаты — если он указан;
2. иначе — общий callbackUrl мерчанта из настроек кабинета.

Если не задано ни то, ни другое, уведомление не отправляется.

Когда приходит

Событие	Когда
payout.completed	исполнитель подтвердил перевод получателю
payout.cancelled	выплата отменена (вручную или по истечении срока)
payout.failed	выплата закрыта с ошибкой

Тело запроса

POST с Content-Type: application/json:

{
  "event": "payout.completed",
  "paymentId": "b3f1c0e2-...",
  "ext_id": "payout_001",
  "status": "completed",
  "amount": 3000,
  "currency": "RUB",
  "timestamp": "2026-09-08T12:47:00Z",
  "data": {
    "payoutId": "b3f1c0e2-...",
    "ext_id": "payout_001",
    "method": "card",
    "rate": 81.5,
    "amount_usdt": 36.809816,
    "receipt_url": "/uploads/receipts/b3f1c0e2-..._1788900000.png",
    "recipient": {
      "requisites": "4276123456781234",
      "holderName": "Иван Иванов",
      "bank": "sberbank"
    }
  }
}

Поле paymentId дублирует payoutId — так контракт уведомлений совпадает с приёмом платежей, и вам не нужно разбирать два разных формата.

Подпись

Заголовок X-Signature — HMAC-SHA256 от тела запроса, ключ — Secret Key мерчанта. Проверяйте подпись прежде, чем доверять телу.

Повторные попытки

Если ваш сервер ответил не 2xx или не ответил, мы повторяем доставку (количество попыток и интервал настраиваются на нашей стороне, по умолчанию 5 попыток с интервалом 60 секунд). Обработчик должен быть идемпотентным: одно и то же событие может прийти повторно.

Чек по выплате

Когда исполнитель прикладывает чек, ссылка приходит в data.receipt_url и доступна в кабинете мерчанта на вкладке Сделки → Пейаут. Файл отдаётся только авторизованному пользователю: по API его нужно запрашивать с тем же Bearer-токеном кабинета, публичной ссылкой он не является.