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

1. Що потрібно перед початком

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

Як отримати API-ключ платежів

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 webhook щоразу, коли змінюється статус інвойсу.

Основні поля webhook

Приклад корисного навантаження webhook

{
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}

Обов’язкова перевірка webhook

Оскільки на основі вебхука ви видаєте товар або поповнюєте баланс користувача, потрібно переконатися, що запит надійшов саме від Heleket. Перевіряйте обома способами:

1. Дозволяйте 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}

Рекомендації з обробки webhook

• Ідемпотентність. Той самий статус може надійти повторно (зокрема через ручне повторне надсилання). Прив’язуйтеся до order_id + status і не видавайте товар двічі.
• Реагуйте на фінальні статуси (paid, paid_over), а не на проміжні.
• Повертайте HTTP 200 лише після успішної обробки webhook.
• Порівнюйте payment_amount і merchant_amount з очікуваною сумою замовлення.

6. Опитування статусу як резервний механізм для webhook

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 також може надходити у webhook як проміжний статус.

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 і HTTP 500 тимчасовими та повторюйте запит з експоненційною затримкою.

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

• Мерчант схвалений, Merchant ID і API-ключ платежів отримані.
• Реалізовано підписування запитів з урахуванням екранування косих рисок.
• Інвойс створюється через POST /v1/payment з унікальним order_id і заданим url_callback.
• Endpoint webhook доступний через HTTPS і приймає POST-запити.
• Webhook перевіряється за IP-адресою та підписом.
• Обробка webhook є ідемпотентною.
• Товар або послуга надається лише для paid і paid_over після перевірки суми.
• Реалізовано резервне опитування через POST /v1/payment/info.
• uuid, order_id, txid і статуси записуються в журнал.
• API-ключі зберігаються в секретах, а не в коді або репозиторії.

Довідник кодів валют і мереж, методи повернення, статичні гаманці та виплати наведені у відповідних розділах документації Heleket.