🔔 Уведомление Webhook

Настройте Webhook для получения уведомлений. HaloPay уведомит мерчанта о конечном результате транзакции. URL Webhook можно настроить на странице управления приложениями.

При наступлении следующих событий на интерфейс обратного вызова, настроенный мерчантом, отправляется запрос:

✅ Платёжная транзакция успешна
⏱️ Время платежа истекло
💡 Недостаточная оплата
✅ Выплата успешна
❌ Выплата не удалась

Частота колбэков: 5s, 15s, 30s, 3m, 10m, 20m, 30m, 30m, 30m, 60m, 3h, 3h, 3h, 6h, 6h. Всего: 24h3m50s

Содержимое колбэка всегда зашифровано. Подробнее см. Подпись.

Уведомление Webhook

Заголовки

Имя	Значение	Обязательно	Тип	Описание
X-Appid	h3j6k9m2n...	Y	string	Уникальный идентификатор мерчанта. Найдите его на странице управления приложениями.
X-Timestamp	1700349280	Y	string	Временная метка в секундах (10 цифр). Запрос действителен в течение двух минут.
X-Sign	e0c6a719ebc366da...	Y	string	hmacSHA256 (body (json-строка)+timestamp+appKey)
X-EventType	Paid	Y	string	Код статуса транзакции

Body платежа

{
  "appid": "ad4cyr8dpfs9j2u1",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd17b7e4ad06f0d6ec24099c013",
  "status": "PAID",  (TO-BE-PAID/PAID/TIME-OUT)
  "time": 1773471015
}

💡

Даже если клиент не заплатит полную сумму, мы всё равно отправим уведомление обратного вызова со статусом TO-BE-PAID, а поле amount_collected покажет количество оплаченных токенов.

Если лимит времени платежа превышен, мы отправим обратный вызов со статусом TIME-OUT, а поле amount_collected снова покажет количество оплаченных токенов.

Body выплаты

{
  "appid": "ad4cyr8dpfs9j2u1",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "currency_id": 75,
  "status": "PAID",  (PAID/FAIL)
  "time": 1773473637,
  "token_amount": "1",
  "trade_no": "202603141533083d1eba01c48c2a873c",
  "txid": "aa23e0aebd2e4c5b82786a5e8b1f414222c7c525a438b95e2cc7d67c81187a5d",
  "type": "TRANSFER"
}

Body QR-платежа

{
  "appid": "1aiqfs0agrd3b9fm", (По умолчанию отличается от APPID платежа.)
  "trade_no": "2c8b150bf35abc59189e333c107247db",
  "type": "QR_PAYMENT",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TRX",
  "txid": "2cdf12e85ec73a61280daaf49c4f27686519407fa0dc7b7744596cad29cbd53c",
  "currency_id": 75,
  "from_address": "TSpjU4PUYzAyY88wyKEEMD7MryneC1WLeb",
  "to_address": "TY1RJdyJh4y1tgmPFrnSaWFhM1HwqTvCQ1",
  "token_amount": "11",
  "status": "PAID",  (PAID)
  "time": 1773473913
}

Параметры

Поле	Тип	Описание
appid	string	APPID мерчанта
trade_no	string	ID транзакции
out_trade_no	string	ID заказа мерчанта
amount	string	Сумма транзакции (сумма в фиатной валюте)
token_amount	string	Сумма транзакции (в токенах)
chain	string	Название цепи
chain_id	int	ID цепи
type	string	Тип транзакции ("PAYMENT/TRANSFER/QR_PAYMENT")
currency_id	int	Глобальный уникальный ID валюты TokenList
txid	string	Хэш транзакции в цепи
status	string	Статус транзакции (TO-BE-PAID/PAID/TIME-OUT/FAIL). Обратный вызов TO-BE-PAID будет запущен, если заказ не полностью оплачен.
time	int	Окончательное время в цепи (при ошибке возвращает период тайм-аута)
amount_collected	string	Количество токенов, которые заплатил пользователь
contract	string	Адрес контракта токена, основной валютой являются ETH/TRX/BNB
from_address	string	Адрес кошелька для платежа
to_address	string	Адрес кошелька для получения

💡

Мерчанты подписывают данные для обеспечения безопасности. После успешной обработки заказа верните "Success" в теле HTTP-ответа. При ошибке обработки HaloPay повторит отправку, Webhook выполнит до 15 повторных попыток (Частота колбэков: 5s, 15s, 30s, 3m, 10m, 20m, 30m, 30m, 30m, 60m, 3h, 3h, 3h, 6h, 6h, Всего: 24h3m50s).

📌 Пример

Запрос на сервер Webhook мерчанта

POST /webhook/callback HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Appid: ad4cyr8dpfs9j2u1
X-Timestamp: 1773471015
X-Sign: e0c6a719ebc366da...
X-EventType: Paid

{
  "appid": "ad4cyr8dpfs9j2u1",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd17b7e4ad06f0d6ec24099c013",
  "status": "PAID",
  "time": 1773471015
}

Ответ от сервера Webhook мерчанта

HTTP/1.1 200 OK
Content-Type: text/plain

Success

Уведомление Webhook​

📌 Пример​

Уведомление Webhook

📌 Пример