Webhook

Webhook - це своєрідний метод зворотного зв’язку для платежної інформації.
Коли статус рахунку -фактури змінюється, запит на повідомлення надсилається на URL_CALLBACK, вказаний при створенні рахунку -фактури.

Реакція

Параметри відповіді

НазваВизначення
typeТип рахунку -фактури (гаманець / оплата)
uuidUUID платіж
order_idІдентифікатор замовлення у вашій системі (для визначення замовлення)
amountКількість рахунку -фактури
payment_amountСума, яка фактично сплачена клієнтом
payment_amount_usdСума, фактично сплачена клієнтом у доларах США
merchant_amountСума, що додається до балансу торговця, з усіма комісіями віднімаються.
commissionСума комісії Cryptomus
is_finalЧи доопрацьована рахунок -фактура. Коли рахунок -фактура доопрацьовано, неможливо сплатити рахунок -фактуру (він або виплачується, або закінчився)
statusСтатус платежуДоступні варіанти:confirm_checkpaidpaid_overfailwrong_amountcancelsystem_failrefund_processrefund_failrefund_paid
fromАдреса гаманця платника
wallet_address_uuiduuid статичного гаманця
networkМережа blockchain, в якій здійснюється платіж
currencyВалюта рахунків -фактур
payer_currencyВалюта, з якою клієнт фактично заплатив
additional_dataДодаткова інформаційна рядок, яку ви надали під час створення рахунку -фактури
convertІнформація про валюту, до якої буде автоматично перетворити платіж. Перетворення виконується з payer_currency до USDTПоле convert не буде існувати, якщо ви не включили функцію автоматичного перетворення для payer_currency (наприклад, автоматичне перетворення BTC на USDT) Структура
txidТранзакція хеш на блокчейн.Поле txid не буде існувати, якщо1) Оплата була сплачена P2P (платник відкликав кошти зі свого рахунку Cryptomus на адресу, зазначену в рахунку -фактурі, і платіж здійснювався без блокчейна, лише в нашій системі)2) Оплата не була сплачена3) Щось було не так з оплатою, або клієнт допустив помилку, і ми позначили це як "оплачувані" вручну
signПідпис

Визначення

Тип рахунку -фактури (гаманець / оплата)

Визначення

UUID платіж

Визначення

Ідентифікатор замовлення у вашій системі (для визначення замовлення)

Визначення

Кількість рахунку -фактури

Визначення

Сума, яка фактично сплачена клієнтом

Визначення

Сума, фактично сплачена клієнтом у доларах США

Визначення

Сума, що додається до балансу торговця, з усіма комісіями віднімаються.

Визначення

Сума комісії Cryptomus

Визначення

Чи доопрацьована рахунок -фактура. Коли рахунок -фактура доопрацьовано, неможливо сплатити рахунок -фактуру (він або виплачується, або закінчився)

Визначення

Статус платежуДоступні варіанти:- 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 (платник відкликав кошти зі свого рахунку Cryptomus на адресу, зазначену в рахунку -фактурі, і платіж здійснювався без блокчейна, лише в нашій системі)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}
Копіювати

Перевірка WebHook

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

Ми рекомендуємо вам перевірити це обома способами:

  • Використовуйте IP -адресу Whitelist і дозволяйте запитими до URL_Callback лише з наших IPS. Ми надсилаємо Webhooks з IP. 91.227.144.54
  • Перевірте підпис у кожному веб -куці, який надходить до вашого url_callback, читайте більше про це нижче.

Перевірка підпису Webhook

Ваші ключі API є секретними, і ніхто, крім вас, і криптовалюта не повинні їх знати. Отже, під час перевірки підпису ви будете впевнені, що WebHook був надісланий Cryptomus.

Ми створюємо знак за допомогою цього алгоритму. Хеш MD5 тіла запиту, кодованого в Base64, і поєднується з вашим ключем API.

Оскільки підпис надходить у тілі запиту, щоб перевірити його, вам потрібно витягнути знак із тіла відповіді, генерувати хеш з тіла та клавішу API та відповідати його параметром знаку.

Приклад у PHP:

Щоб отримати дані JSON, що надсилаються повідомленням своєму обробнику WebHook:


1$data = file_get_contents('php://input');
2$data = json_decode($data, true);
Копіювати

Скажімо, ми отримали WebHook з даними в це масив
По -перше, нам потрібно витягнути знак із масиву:


1$sign = $data['sign'];
2unset($data['sign']);
Копіювати

Тепер давайте генеруємо знак за допомогою нашого ключа платежу API:


1$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);
Копіювати

Нарешті, ми можемо перевірити, чи знак, який ми створили за допомогою нашого ключа платежу API, дорівнює знаку, який прийшов до Webhook.


1if (!hash_equals($hash, $sign)) {
2   return new InvalidHashException();
3}
4
5// or
6
7if ($hash !== $sign) {
8   return new InvalidHashException();
9}
Копіювати

На даний момент ви можете бути впевнені, що веб -кук був від криптовалюта і що ви отримали всі дані правильно

Існує різниця при кодуванні масиву даних у PHP та інших мовах. PHP уникає косоок, а деякі інші мови - ні. Тому ви можете зіткнутися з невідповідністю знаку. Ви повинні уникнути косої косою рушкою, щоб змусити його працювати належним чином.

в 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"}
Копіювати

в 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            
Копіювати