Host-to-Host (H2H) интеграция Heleket для мерчантов

1. Что нужно перед стартом

Для приёма платежей вам потребуются два значения из личного кабинета:

Порядок получения ключа приёма платежей:

1. Бизнес → Мерчанты → Создать мерчанта, задайте имя.
2. В настройках мерчанта нажмите Оставить заявку, укажите URL сайта и подтвердите домен.
3. Дождитесь модерации мерчанта.
4. После одобрения скопируйте API-ключ платежей и Merchant ID в разделе Настройки.

Базовый endpoint всех запросов:

Все запросы отправляются методом POST в формате JSON и должны быть подписаны.

2. Аутентификация и подпись запроса

Каждый запрос аутентифицируется двумя HTTP-заголовками:

Алгоритм подписи: MD5 от строки, состоящей из base64-кодированного JSON-тела запроса, склеенного с вашим API-ключом.

$body = json_encode($data);
$sign = md5(base64_encode($body) . $API_KEY);

Если тело запроса пустое (запрос без параметров), подпись считается от пустой строки:

$sign = md5(base64_encode('') . $API_KEY);

Пример подписанного запроса

curl https://api.heleket.com/v1/payment \
  -X POST \
  -H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'sign: fe99035f86fa436181717b302b95bacff1' \
  -H 'Content-Type: application/json' \
  -d '{"amount":"15","currency":"USD","order_id":"1"}'

3. Схема H2H-потока

1. Клиент оформляет заказ у вас → вы фиксируете order_id на своей стороне
2. Ваш сервер → POST /v1/payment → Heleket возвращает uuid, адрес, сумму, url
3. Вы показываете клиенту реквизиты / адрес / QR (или ссылку url)
4. Клиент платит в блокчейне
5. Heleket → POST на ваш url_callback (webhook) при каждой смене статуса
6. Вы проверяете подпись вебхука → обновляете заказ
7. (Подстраховка) периодически опрашиваете POST /v1/payment/info по order_id

4. Создание платежа

Endpoint:

Основные параметры запроса

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

{ "amount": "15", "currency": "USD", "order_id": "1" }

{ "amount": "20", "currency": "USDT", "order_id": "1", "network": "tron" }

{ "amount": "25", "currency": "USD", "order_id": "1", "to_currency": "USDT" }

Ответ

{
1  "state": 0,
2  "result": {
3    "uuid": "1ec87133-b22d-4643-988f-cac29a6ac85d",
4    "order_id": "3",
5    "amount": "20000.00",
6    "payment_amount": null,
7    "payer_amount": "254.92",
8    "payer_currency": "USDT",
9    "currency": "RUB",
10    "merchant_amount": "249.82816502",
11    "network": "bsc",
12    "address": "0x2b...",
13    "txid": null,
14    "payment_status": "check",
15    "url": "https://pay.heleket.com/pay/1ec87133-b22d-4643-988f-cac29a6ac85d",
16    "expired_at": 1753202502,
17    "is_final": false,
18    "commission": "5.09853397",
19    "address_qr_code": "data:image/png;base64 ..."
20  }
21}

Ключевые поля ответа:

state: 0 означает успех. При ошибках валидации state: 1 (раздел 8).

5. Webhook: приём уведомлений о статусе

При каждой смене статуса инвойса Heleket отправляет POST на ваш url_callback.

Тело вебхука (основные поля)

Пример полезной нагрузки:

{
1  "type": "payment",
2  "uuid": "62f88b36-a9d5-4fa6-aa26-e040c3dbf26d",
3  "order_id": "97a75bf8eda5cca41ba9d2e104840fcd",
4  "amount": "3.00000000",
5  "payment_amount": "3.00000000",
6  "merchant_amount": "2.94000000",
7  "commission": "0.06000000",
8  "is_final": true,
9  "status": "paid",
10  "from": "THgEWubVc8tPKXLJ4VZ5zbiiAK7AgqSeGH",
11  "network": "tron",
12  "currency": "TRX",
13  "payer_currency": "TRX",
14  "txid": "6f0d9c8374db57cac0d806251473de754f361c83a03cd805f74aa9da3193486b",
15  "sign": "a76c0d77f3e8e1a419b138af04ab600a"
16}

Обязательная проверка вебхука

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

1. Белый список IP. Принимайте callback только с IP Heleket: 31.133.220.8.
2. Проверка подписи. Подпись считается тем же алгоритмом, что и для запросов, но проверяется так:

// 1. Считываем сырое тело запроса
1$data = json_decode(file_get_contents('php://input'), true);
2
3// 2. Достаём и убираем подпись из массива
4$sign = $data['sign'];
5unset($data['sign']);
6
7// 3. Считаем хэш от тела (без sign) + ваш API-ключ платежей
8$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);
9
10// 4. Сверяем
11if (!hash_equals($hash, $sign)) {
12    // подпись неверна — отклонить
13    http_response_code(400);
14    exit;
15}

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

• Идемпотентность. Один и тот же статус может прийти повторно (в т.ч. через ручную переотправку). Привязывайтесь к order_id + status и не выдавайте товар дважды.
• Реагируйте на финальные статусы (paid, paid_over), а не на промежуточные.
• Отвечайте HTTP 200 только после успешной обработки; иначе Heleket может повторить отправку.
• Сверяйте payment_amount / merchant_amount с ожидаемой суммой заказа.

6. Поллинг статуса (подстраховка к вебхукам)

Endpoint:

Передайте uuid или order_id (если передать оба — приоритет у order_id).

curl https://api.heleket.com/v1/payment/info \
  -X POST \
  -H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'sign: <подпись тела>' \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"1"}'

Ответ — тот же объект платежа, что и при создании, с актуальным payment_status и is_final. Используйте этот метод как периодическую сверку для «зависших» заказов, а не как основной механизм (вебхуки быстрее и дешевле по запросам).

7. Статусы платежа

Считайте платёж успешным при paid и paid_over. Для статусов вебхука дополнительно встречается confirm_check как промежуточный «почти готово».

8. Обработка ошибок

Ошибки валидации — HTTP 422, state: 1:

{ "state": 1, "errors": { "amount": ["validation.required"] } }

Частые сообщения (state: 1, поле message):

Внутренняя ошибка — HTTP 500:

{ "message": "Server error, #1", "code": 500, "error": null }

На стороне клиента трактуйте Gateway error / Server error / 500 как временные и применяйте повтор с экспоненциальной задержкой.

9. Чек-лист интеграции

• Мерчант создан и прошёл модерацию; получены Merchant ID и API-ключ платежей.
• Реализована подпись запросов (MD5 от base64-тела + ключ), учтено экранирование слешей.
• Создание инвойса через POST /v1/payment с уникальным order_id и заданным url_callback.
• Эндпоинт вебхука доступен по HTTPS и принимает POST.
• Проверка вебхука: фильтр по IP 31.133.220.8 и сверка подписи.
• Обработка вебхука идемпотентна (нет двойной выдачи товара).
• Товар/услуга выдаётся на paid / paid_over; сумма сверяется.
• Реализован fallback-поллинг через POST /v1/payment/info.
• Логируются uuid, order_id, txid, статусы — для разбора спорных платежей.
• API-ключи хранятся в секретах, не в коде/репозитории.

Справочник кодов валют и сетей, методы возвратов, статические кошельки и выплаты — в соответствующих разделах документации Heleket.