Webhook

Webhook — основной способ узнать, что со сделкой что-то произошло. При каждом значимом изменении платформа отправляет POST на ваш адрес с полным состоянием сделки в теле запроса.

Опрашивать API в цикле не нужно и не рекомендуется: GET-методы существуют для сверки и разбора инцидентов, а не для отслеживания в реальном времени.

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

• сделка создана;
• Pay-In оплачен и подтверждён;
• Pay-Out взят в работу, переназначен или завершён;
• по сделке открыт или закрыт спор;
• сделка отменена — вами, по тайм-ауту или решением оператора;
• matching-заявка наполнилась или закрылась.

Промежуточные состояния сверки (checking, checking_manually) отдельными уведомлениями не сопровождаются — следующее уведомление приходит уже с результатом.

Куда отправлять

Адрес задаётся тремя способами, от общего к частному:

1. В кабинете — поле Callback url в разделе «Профиль → API интеграция».
2. Через API — метод PATCH /merchant.
3. Для отдельной сделки — поле callbackUrl в теле запроса на создание. Переопределяет два предыдущих.

Осторожно

Если адрес не задан ни одним из способов, уведомления не отправляются. Сделки при этом создаются и обрабатываются как обычно — вы просто не узнаете об их исходе.

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

Требование	Детали
Протокол	HTTPS с валидным сертификатом
Метод	POST, Content-Type: application/json
Успешный ответ	HTTP 200 или 201. Любой другой код — попытка считается неудачной
Тайм-аут	10 секунд на ответ
Тело ответа	Не анализируется, может быть пустым
Идемпотентность	Обязательна: одно и то же уведомление может прийти повторно

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

Заголовки запроса

POST /callback HTTP/1.1
Host: example.com
Content-Type: application/json
x-signature: 7d3a1f9c4b2e8a6d5f0c3b7a9e1d4f8c2a6b0e5d3c7f1a9b4e8d2c6f0a3b7e1d

x-signature — HMAC-SHA256 от тела запроса на вашем API-ключе, в hex. Проверять обязательно: без этого ваш endpoint принимает любые запросы от кого угодно. Порядок проверки и примеры кода — в разделе Подпись запросов.

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

{
  "category": "trade",
  "id": "45450d2a-e352-439d-9886-134f27c54750",
  "merchantTransactionId": "order-1001",
  "amount": 5000,
  "crypto": "61865875",
  "rate": "80.82",
  "fee": "4330612",
  "type": "pay-in",
  "method": "c2c",
  "status": "success",
  "requisite": {
    "id": "8d920c8f-ca6d-4a69-ada0-fe7f43db286c",
    "bank": "SBER",
    "ownerName": "Иван Иванов",
    "cardNumber": "4111111111111111",
    "sbpNumber": null,
    "accountNumber": null,
    "bankBic": null,
    "link": null,
    "currency": "RUB"
  },
  "paymentPageUrl": "https://pay.example.com/external/4b9a1a2c",
  "dispute": {
    "disputeCreatedAt": null,
    "disputeResolvedAt": null,
    "disputeMerchantCheckUrl": null,
    "disputeTraderCheckUrl": null,
    "disputeTraderFiatAmount": null,
    "disputeTraderDeclineReason": null,
    "cancelReason": null
  },
  "payerInfo": {
    "ip": "203.0.113.45",
    "userId": "usr_847392"
  },
  "payerBank": null,
  "paymentLifetime": 15,
  "createdAt": "2026-08-23T10:00:00.000Z",
  "invoicesUrl": [],
  "receiptValidation": null,
  "matchingId": null,
  "matchingTradeType": null,
  "merchantId": "befbd03c-3c62-42c8-9292-9074abcf7500",
  "callbackUrl": "https://example.com/callback",
  "successUrl": null,
  "errorUrl": null
}

Состав полей

Поле	Описание
category	trade — уведомление о сделке, matching — о matching-заявке. Разбирайте тело по-разному в зависимости от значения
id	Идентификатор сделки на нашей стороне
merchantTransactionId	Ваш идентификатор из запроса на создание
matchingTransactionId	Ваш идентификатор matching-заявки. Присутствует, только если сделка связана с matching
amount	Сумма в фиатной валюте. При success_changed — уже пересчитанная
crypto	Сумма в USDT в минимальных единицах, строкой
rate	Курс фиат → USDT, зафиксированный при создании сделки
fee	Ваша комиссия в минимальных единицах USDT, строкой
type	pay-in или pay-out
method	Платёжный метод сделки — c2c, sbp, qr, c2c_invoice, sbp_invoice и другие
status	Текущий статус — см. Статусы сделок
requisite	Реквизиты сделки
paymentPageUrl	Готовая платёжная страница для Pay-In
dispute	Данные спора и cancelReason для отменённых сделок
payerInfo	Данные плательщика в том виде, в каком вы их передали
payerBank	Банк плательщика, если вы указали его при создании
paymentLifetime	Время жизни сделки в минутах
createdAt	Момент создания в UTC, ISO 8601
invoicesUrl	Ссылки на загруженные чеки, массив
receiptValidation	Краткий публичный результат проверки чека либо null
matchingId, matchingTradeType	Связь сделки с matching-заявкой
merchantId	Идентификатор вашего кабинета
callbackUrl, successUrl, errorUrl	Адреса, которые применились к этой сделке

Заметка

Денежные величины (crypto, fee, rate, суммы внутри dispute) передаются строками, чтобы не потерять точность. Приводите их к числу явно и не полагайтесь на автоматическое преобразование типов в вашем языке.

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

Если ваш сервер не ответил 200/201, платформа повторит доставку. Всего попыток — шесть, интервалы растут:

Попытка	Пауза перед следующей
1	~5 секунд
2	~30 секунд
3	~2 минуты
4	~10 минут
5	~30 минут
6	~2 часа

К каждой паузе добавляется случайное отклонение до ±20 %, чтобы одновременно упавшие уведомления не пришли одной волной. После исчерпания попыток доставка прекращается — возобновить её можно только запросом в поддержку.

История всех попыток по каждому уведомлению видна в кабинете, в разделе Callback вызовы: там же код ответа вашего сервера и номер текущей попытки.

Что запомнить

• Проверяйте подпись до обработки — всегда.
• Отвечайте 200 быстро, обрабатывайте асинхронно.
• Считайте, что уведомления могут прийти повторно и не по порядку.
• Бизнес-логику запускайте только на финальных статусах.

Развёрнутые рекомендации по этим четырём пунктам — в разделе Надёжность интеграции.