Webhook'и по выплатам

Получить статус выплаты можно двумя способами: через автоматические webhook-уведомления (рекомендуется) или ручным опросом GET /v1/payouts/{payoutId}.

Адрес отправки уведомлений

Адрес определяется в следующем порядке приоритета:

1. callbackUrl, переданный в теле запроса POST /v1/payouts — применяется только к этой выплате;
2. callbackUrl, указанный в настройках мерчанта;
3. если не задано ни одно из значений, уведомления по выплате не отправляются.

Подпись всегда формируется на основе apiToken мерчанта, независимо от того, какой адрес используется.

Пример запроса

{
  "amount": 1000.5,
  "currency": "RUB",
  "paymentType": "C2C",
  "externalId": "payout-123",
  "callbackUrl": "https://merchant.example/payouts/webhook",
  "account": {
    "name": "Ivan Ivanov",
    "requisites": "4111111111111111",
    "userId": "u-42"
  }
}

Требования к callbackUrl

Поле возвращается в объекте выплаты (GET /v1/payouts/{payoutId}). Значение null означает, что используются настройки мерчанта.

Условия отправки

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

• CREATED — уведомление не отправляется;
• COMPLETED — уведомление помещается в очередь отдельно, в рамках транзакции завершения выплаты, когда известен итоговый размер комиссии.

Также предусмотрена ручная отправка уведомления из панели администрирования.

Повторные записи исключаются по совокупности значений (адрес, идентификатор выплаты, статус) среди неотправленных уведомлений.

Формат уведомления

POST {callbackUrl}
Content-Type: application/json
X-Type: PAYOUT_UPDATE
X-Signature: HMAC-SHA512(тело запроса, apiToken) в формате hex

Пример тела запроса

{
  "id": "0198c3f1-2a4b-7c3d-9e0f-1a2b3c4d5e6f",
  "status": "COMPLETED",
  "amount": "1000.5",
  "fee": "60",
  "currency": "RUB",
  "type": "C2C",
  "note": null,
  "externalId": "payout-123",
  "merchantId": "0198c3f1-1111-7222-8333-444455556666",
  "settlementCurrency": "USD",
  "settlementAmount": "11.28",
  "createdAt": "2026-07-29T10:00:00.000Z",
  "completedAt": "2026-07-29T10:04:12.317Z"
}

Поля тела запроса

Проверка подписи (X-Signature)

Каждое уведомление содержит заголовок X-Signature — это HMAC SHA512 хэш в HEX-формате от тела запроса. Подпись формируется с использованием вашего API-токена в качестве секретного ключа.

Пример проверки подписи

import crypto from "crypto";

const apiToken = "your_API_token";

app.post("/payouts/webhook", (req, res) => {
  const signature = req.headers["x-signature"];
  const body = JSON.stringify(req.body);

  // Проверка подписи
  const hmac = crypto.createHmac("sha512", apiToken);
  hmac.update(body);
  const calculatedSignature = hmac.digest("hex");

  if (calculatedSignature !== signature) {
    console.error("❌ Невалидная подпись webhook'а!");
    return res.status(403).send("Invalid signature");
  }

  console.log("✅ Подпись валидна");

  // Обработка уведомления
  const data = req.body;
  if (data.status === "COMPLETED") {
    console.log(`✅ Выплата ${data.externalId} отправлена!`);
  }

  res.status(200).send("OK");
});

Если на один адрес поступают уведомления и по заказам, и по выплатам, дополнительно проверяйте заголовок X-Type: PAYOUT_UPDATE.

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

Дополнительно применяется механизм circuit breaker: адрес, стабильно возвращающий ошибки, временно исключается из отправки.

Рекомендации по работе с уведомлениями

Смотрите также