Webhook - це своєрідний метод зворотного зв’язку для платежної інформації.
Коли статус рахунку -фактури змінюється, запит на повідомлення надсилається на url_callback, вказаний при створенні рахунку -фактури.
Реакція
Параметри відповіді
| Назва | Визначення |
|---|---|
| type | Тип рахунку -фактури (гаманець / оплата) |
| uuid | UUID платіж |
| order_id | Ідентифікатор замовлення у вашій системі (для ідентифікації замовлення) |
| amount | Кількість рахунку -фактури |
| payment_amount | Сума, яка фактично сплачена клієнтом |
| payment_amount_usd | Сума, фактично сплачена клієнтом у доларах США |
| merchant_amount | Сума, що додається до балансу торговця, з усіма комісіями віднімаються. |
| commission | Сума комісії Heleket |
| is_final | Чи доопрацьована рахунок -фактура. Коли рахунок -фактура доопрацьовано, неможливо сплатити рахунок -фактуру (він або виплачується, або закінчився) |
| status | Статус платежуДоступні варіанти:• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid |
| from | Адреса гаманця платника |
| wallet_address_uuid | uuid статичного гаманця |
| network | Мережа blockchain, в якій здійснюється платіж |
| currency | Валюта рахунків -фактур |
| payer_currency | Валюта, з якою клієнт фактично заплатив |
| additional_data | Додаткова інформаційна рядок, яку ви надали під час створення рахунку -фактури |
| convert | Інформація про валюту, до якої буде автоматично перетворити платіж. Перетворення виконується з payer_currency до USDTПоле convert не буде існувати, якщо ви не включили функцію автоматичного перетворення для payer_currency (наприклад, автоматичне перетворення BTC на USDT) Структура |
| txid | Транзакція хеш на блокчейн.Поле txid не існуватиме, якщо1) Оплата була сплачена P2P (платник відкликав кошти зі свого рахунку Heleket на адресу, зазначену в рахунку -фактурі, і платіж здійснювався без блокчейна, лише в нашій системі)2) Оплата не була сплачена3) Щось було не так з оплатою, або клієнт допустив помилку, і ми позначили це як "оплачувані" вручну |
| sign | Підпис |
Визначення
Тип рахунку -фактури (гаманець / оплата)Визначення
UUID платіжВизначення
Ідентифікатор замовлення у вашій системі (для ідентифікації замовлення)Визначення
Кількість рахунку -фактуриВизначення
Сума, яка фактично сплачена клієнтомВизначення
Сума, фактично сплачена клієнтом у доларах СШАВизначення
Сума, що додається до балансу торговця, з усіма комісіями віднімаються.Визначення
Сума комісії HeleketВизначення
Чи доопрацьована рахунок -фактура. Коли рахунок -фактура доопрацьовано, неможливо сплатити рахунок -фактуру (він або виплачується, або закінчився)Визначення
Статус платежуДоступні варіанти:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paidВизначення
Адреса гаманця платникаВизначення
uuid статичного гаманцяВизначення
Мережа blockchain, в якій здійснюється платіжВизначення
Валюта рахунків -фактурВизначення
Валюта, з якою клієнт фактично заплативВизначення
Додаткова інформаційна рядок, яку ви надали під час створення рахунку -фактуриВизначення
Інформація про валюту, до якої буде автоматично перетворити платіж. Перетворення виконується з payer_currency до USDTПоле convert не буде існувати, якщо ви не включили функцію автоматичного перетворення для payer_currency (наприклад, автоматичне перетворення BTC на USDT) СтруктураВизначення
Транзакція хеш на блокчейн.Поле txid не існуватиме, якщо1) Оплата була сплачена P2P (платник відкликав кошти зі свого рахунку Heleket на адресу, зазначену в рахунку -фактурі, і платіж здійснювався без блокчейна, лише в нашій системі)2) Оплата не була сплачена3) Щось було не так з оплатою, або клієнт допустив помилку, і ми позначили це як "оплачувані" вручнуВизначення
Підпис
Структура convert
| Назва | Визначення |
|---|---|
| to_currency | Код валюти, до якого буде перетворено платіж |
| commission | Комісія за конвертацію |
| rate | Коефіцієнт конверсії |
| amount | Сума конверсії в to_currency, яка була додана до балансу торговця, з усіма комісіями віднімали.Сума тут дорівнює merchant_amount * ставці |
Визначення
Код валюти, до якого буде перетворено платіжВизначення
Комісія за конвертаціюВизначення
Коефіцієнт конверсіїВизначення
Сума конверсії в to_currency, яка була додана до балансу торговця, з усіма комісіями віднімали.Сума тут дорівнює merchant_amount * ставці
Приклад відповіді
1{
2 "type": "payment",
3 "uuid": "62f88b36-a9d5-4fa6-aa26-e040c3dbf26d",
4 "order_id": "97a75bf8eda5cca41ba9d2e104840fcd",
5 "amount": "3.00000000",
6 "payment_amount": "3.00000000",
7 "payment_amount_usd": "0.23",
8 "merchant_amount": "2.94000000",
9 "commission": "0.06000000",
10 "is_final": true,
11 "status": "paid",
12 "from": "THgEWubVc8tPKXLJ4VZ5zbiiAK7AgqSeGH",
13 "wallet_address_uuid": null,
14 "network": "tron",
15 "currency": "TRX",
16 "payer_currency": "TRX",
17 "additional_data": null,
18 "convert": {
19 "to_currency": "USDT",
20 "commission": null,
21 "rate": "0.07700000",
22 "amount": "0.22638000"
23 },
24 "txid": "6f0d9c8374db57cac0d806251473de754f361c83a03cd805f74aa9da3193486b",
25 "sign": "a76c0d77f3e8e1a419b138af04ab600a"
26}CopyПеревірка WebHook
Оскільки отримуючи webhooks, ви випускаєте продукти або зараховуєте баланси своїх користувачів, вам потрібно переконатися, що ви отримуєте webhooks від Heleket, а не від когось іншого.
Ми рекомендуємо вам перевірити це обома способами:
- Використовуйте IP -адресу Whitelist і дозволяйте запитими до URL_Callback лише з наших IPS. Ми надсилаємо Webhooks з IP. 31.133.220.8
- Перевірте підпис у кожному webhook, який приходить на ваш url_callback, читайте більше про це нижче.
Перевірка підпису Webhook
Ваші ключі API є секретними, і ніхто, крім вас, і криптовалюта не повинні їх знати. Отже, під час перевірки підпису ви будете впевнені, що WebHook був надісланий Heleket.
Ми створюємо знак за допомогою цього алгоритму. Хеш MD5 тіла запиту, кодованого в Base64, і поєднується з вашим ключем API.
Оскільки підпис надходить у тілі запиту, щоб перевірити його, вам потрібно витягнути знак із тіла відповіді, генерувати хеш з тіла та клавішу API та відповідати його параметром знаку.
Приклад у PHP:
Щоб отримати дані JSON, що надсилаються повідомленням своєму обробнику WebHook:
1$data = file_get_contents('php://input');
2$data = json_decode($data, true);CopyСкажімо, ми отримали webhook з даними в це масив
По -перше, нам потрібно витягнути знак із масиву:
1$sign = $data['sign'];
2unset($data['sign']);CopyТепер давайте генеруємо знак за допомогою нашого ключа платежу API:
1$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);CopyНарешті, ми можемо перевірити, чи знак, який ми створили за допомогою нашого ключа платежу API, дорівнює знаку, який прийшов до webhook.
1if (!hash_equals($hash, $sign)) {
2 return new InvalidHashException();
3}
4
5// or
6
7if ($hash !== $sign) {
8 return new InvalidHashException();
9}CopyНа цьому етапі ви можете бути впевнені, що webhook був від Heleket і що ви правильно отримали всі дані.
в PHP:
1// data array
2$data = [
3 'amount' => '20',
4 'currency' => 'USDT',
5 'network' => 'tron',
6 'txid' => 'someTxidWith/Slash'
7];
8
9// json data we send to webhooks
10$data = json_encode($data, true);
11echo $data;
12// Outputs a string, slash in txid is escaped, pay attention to this.
13// we send a webhook data with all escaped slashes
14// {"amount":"20","currency":"USD","network":"btc","txid":"someTxidWith\/Slash"}Copyв JS:
1const data = {
2 amount: '20',
3 currency: 'USDT',
4 network: 'tron',
5 txid: 'someTxidWith/Slash'
6};
7
8const jsonData = JSON.stringify(data);
9console.log(jsonData);
10// {"amount":"20","currency":"USDT","network":"tron","txid":"someTxidWith/Slash"}
11// slash in txid is not escaped and you will get error checking sign.
12// Instead, you should do it like this:
13// const jsonData = JSON.stringify(data).replace(/\//mg, "\/");
14 Copy