Webhook
Коли статус рахунку -фактури змінюється, запит на повідомлення надсилається на url_callback, вказаний при створенні рахунку -фактури.
Реакція
Параметри відповіді
| Назва | Тип параметра | Визначення |
|---|---|---|
| type | Тип рахунку -фактури (гаманець / оплата) | |
| uuid | UUID платіж | |
| 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_uuid | uuid статичного гаманця | |
| 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_url | string|null | URL-адреса підтвердження 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_currency | string | Від валюти |
| from_amount | string|null | Сума від |
| from_network | string|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:
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 Копія