Webhook

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

Реакція

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

НазваТип параметраВизначення
typeТип рахунку -фактури (гаманець / оплата)
uuidUUID платіж
order_idІдентифікатор замовлення у вашій системі (для визначення замовлення)
amountКількість рахунку -фактури
payment_amountСума, яка фактично сплачена клієнтом
payment_amount_usdСума, фактично сплачена клієнтом у доларах США
merchant_amountСума, що додається до балансу торговця, з усіма комісіями віднімаються.
commissionСума комісії Cryptomus
is_finalЧи доопрацьована рахунок -фактура. Коли рахунок -фактура доопрацьовано, неможливо сплатити рахунок -фактуру (він або виплачується, або закінчився)
statusСтатус платежуДоступні варіанти:• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid• locked
fromАдреса гаманця платника
wallet_address_uuiduuid статичного гаманця
networkМережа blockchain, в якій здійснюється платіж
currencyВалюта рахунків -фактур
payer_currencyВалюта, з якою клієнт фактично заплатив
payer_amountПланова сума платежу встановлена ​​під час створення платежу
payer_amount_exchange_rateОбмінний курс, що застосовувався під час здійснення платежу
transfer_idІдентифікатор внутрішнього P2P-переказу в системі (для локальних платежів).
additional_dataДодаткова інформаційна рядок, яку ви надали під час створення рахунку -фактури
convertІнформація про валюту, до якої буде автоматично перетворити платіж. Перетворення виконується з payer_currency до USDTПоле convert не буде існувати, якщо ви не включили функцію автоматичного перетворення для payer_currency (наприклад, автоматичне перетворення BTC на USDT) Структура
convert_fromІнформація про валюту, з якої було здійснено неправильний платіжПред'явіть, якщо платіж неправильний Структура
aml_verification_urlstring|nullURL-адреса підтвердження AMLПрисутній, якщо payment_status заблоковано
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- locked

Визначення

Адреса гаманця платника

Визначення

uuid статичного гаманця

Визначення

Мережа blockchain, в якій здійснюється платіж

Визначення

Валюта рахунків -фактур

Визначення

Валюта, з якою клієнт фактично заплатив

Визначення

Планова сума платежу встановлена ​​під час створення платежу

Визначення

Обмінний курс, що застосовувався під час здійснення платежу

Визначення

Ідентифікатор внутрішнього P2P-переказу в системі (для локальних платежів).

Визначення

Додаткова інформаційна рядок, яку ви надали під час створення рахунку -фактури

Визначення

Інформація про валюту, до якої буде автоматично перетворити платіж. Перетворення виконується з payer_currency до USDTПоле convert не буде існувати, якщо ви не включили функцію автоматичного перетворення для payer_currency (наприклад, автоматичне перетворення BTC на USDT) Структура

Визначення

Інформація про валюту, з якої було здійснено неправильний платіжПред'явіть, якщо платіж неправильний Структура

Тип параметра

string|null

Визначення

URL-адреса підтвердження AMLПрисутній, якщо payment_status заблоковано

Визначення

Транзакція хеш на блокчейн.Поле txid не буде існувати, якщо1) Оплата була сплачена P2P (платник відкликав кошти зі свого рахунку Cryptomus на адресу, зазначену в рахунку -фактурі, і платіж здійснювався без блокчейна, лише в нашій системі)2) Оплата не була сплачена3) Щось було не так з оплатою, або клієнт допустив помилку, і ми позначили це як "оплачувані" вручну

Визначення

Підпис

Структура convert

НазваВизначення
to_currencyКод валюти, до якого буде перетворено платіж
commissionПлата за конверсію
rateОбмінний курс
amountСума конверсії в to_currency, яка була додана до балансу торговця, з усіма комісіями віднімали.Сума тут дорівнює merchant_amount * ставці

Визначення

Код валюти, до якого буде перетворено платіж

Визначення

Плата за конверсію

Визначення

Обмінний курс

Визначення

Сума конверсії в to_currency, яка була додана до балансу торговця, з усіма комісіями віднімали.Сума тут дорівнює merchant_amount * ставці

Структура convert_from

НазваТип параметраВизначення
from_currencystringВід валюти
from_amountstring|nullСума від
from_networkstring|nullМережевий код Blockchain

Тип параметра

string

Визначення

Від валюти

Тип параметра

string|null

Визначення

Сума від

Тип параметра

string|null

Визначення

Мережевий код Blockchain

Приклад відповіді


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  "payer_amount": "0.00234567",
18  "payer_amount_exchange_rate": "42650.00000000",
19  "transfer_id": "uuid-123-456",
20  "additional_data": null,
21  "convert": {
22    "to_currency": "USDT",
23    "commission": null,
24    "rate": "0.07700000",
25    "amount": "0.22638000"
26  },
27  "convert_from": {
28    "from_currency": "USDT",
29    "from_amount": "10.00",
30    "from_network": "tron"
31  },
32  "aml_verification_url": null,
33  "txid": "6f0d9c8374db57cac0d806251473de754f361c83a03cd805f74aa9da3193486b",
34  "sign": "a76c0d77f3e8e1a419b138af04ab600a"
35}
Копія

Перевірка WebHook

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

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

  • Використовуйте IP -адресу Whitelist і дозволяйте запитими до URL_Callback лише з наших IPS. Ми надсилаємо Webhooks з IP. 91.227.144.54
  • Перевірте підпис у кожному webhook, який приходить на ваш 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}
Копія

На цьому етапі ви можете бути впевнені, що webhook був від Cryptomus і що ви правильно отримали всі дані.

Існує різниця при кодуванні масиву даних у 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            
Копія