Webhook
Webhook - это своего рода метод обратной связи для получения платежной информациию
При изменении статуса счета-фактуры на url_callback, указанный при создании счета-фактуры, отправляется запрос POST.
При изменении статуса счета-фактуры на url_callback, указанный при создании счета-фактуры, отправляется запрос POST.
Ответ
Параметры отклика
| Имя | Описание |
|---|---|
| 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 |
| from | Адрес кошелька плательщика |
| wallet_address_uuid | uuid статического кошелька |
| network | Блокчейн-сеть, в которой производится платеж |
| currency | Валюта счета-фактуры |
| payer_currency | Валюта, которой клиент фактически расплатился |
| additional_data | Строка дополнительной информации, которую вы указали при создании счета-фактуры |
| convert | Информация о валюте, в которую будет автоматически конвертирован платеж. Конвертация производится из payer_currency в USDTПоле convert не будет существовать, если вы не включили функцию автоматической конвертации для payer_currency (например, автоматическое преобразование BTC в USDT) Структура |
| txid | Хэш транзакции в блокчейне.Поле txid не будет существовать, если1) платеж был произведен посредством p2p (Плательщик снял средства со своего счета Cryptomus на адрес, указанный в счете-фактуре, и платеж был произведен без блокчейна, только в нашей системе)2) Платеж не был произведен3) Что-то было не так с платежом или клиент допустил ошибку, и мы пометили ее как 'paid' вручную |
| sign | Подпись |
Описание
Тип счета (кошелек / платеж)Описание
uuid платежаОписание
Идентификатор заказа в Вашей системе (для идентификации заказа)Описание
Сумма счета-фактурыОписание
Сумма, фактически уплаченная клиентомОписание
Сумма, фактически уплаченная клиентом в долларах СШАОписание
Сумма, добавленная к балансу продавца, с вычетом всех комиссионных.Описание
Сумма комиссии CryptomusОписание
Окончательно ли оформлен счет-фактура. Когда выставление счета завершено, оплатить счет невозможно (он либо оплачен, либо срок его действия истек)Описание
Статус платежаДоступные опции:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paidОписание
Адрес кошелька плательщикаОписание
uuid статического кошелькаОписание
Блокчейн-сеть, в которой производится платежОписание
Валюта счета-фактурыОписание
Валюта, которой клиент фактически расплатилсяОписание
Строка дополнительной информации, которую вы указали при создании счета-фактурыОписание
Информация о валюте, в которую будет автоматически конвертирован платеж. Конвертация производится из payer_currency в USDTПоле convert не будет существовать, если вы не включили функцию автоматической конвертации для payer_currency (например, автоматическое преобразование BTC в USDT) СтруктураОписание
Хэш транзакции в блокчейне.Поле txid не будет существовать, если1) платеж был произведен посредством p2p (Плательщик снял средства со своего счета Cryptomus на адрес, указанный в счете-фактуре, и платеж был произведен без блокчейна, только в нашей системе)2) Платеж не был произведен3) Что-то было не так с платежом или клиент допустил ошибку, и мы пометили ее как 'paid' вручнуюОписание
Подпись
Структура convert
| Имя | Описание |
|---|---|
| to_currency | Код валюты, в которую будет конвертирован платеж |
| commission | Комиссия за конвертацию |
| rate | Коэффициент конверсии |
| amount | Сумма конвертации в to_currency, которая была добавлена на баланс продавца, с вычетом всех комиссионных.сумма здесь равна merchant_amount * rate |
Описание
Код валюты, в которую будет конвертирован платежОписание
Комиссия за конвертациюОписание
Коэффициент конверсииОписание
Сумма конвертации в to_currency, которая была добавлена на баланс продавца, с вычетом всех комиссионных.сумма здесь равна merchant_amount * rate
Пример ответа
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
Поскольку, получая webhooks, вы выпускаете продукты или пополняете балансы своих пользователей, вам необходимо убедиться, что вы получаете webhooks от cryptomus, а не от кого-либо другого.
Мы рекомендуем вам проверить это обоими способами:
- используйте список доверенных ip-адресов и разрешайте запросы к url_callback только с наших ip-адресов. Мы отправляем веб-ссылки с ip. 91.227.144.54
- Проверяйте подпись в каждом webhook, который приходит на ваш url_callback, подробнее об этом читайте ниже.
Проверка подписи webhook
Ваши api-ключи являются секретными, и никто, кроме вас и cryptomus, не должен их знать. Таким образом, при проверке подписи вы будете уверены, что webhook был отправлен cryptomus.
Мы создаем вывеску, используя этот алгоритм. MD5-хэш тела POST-запроса, закодированный в base64 и объединенный с вашим API-ключом.
Поскольку подпись содержится в теле запроса, чтобы проверить ее, вам нужно извлечь знак из тела ответа, сгенерировать хэш из тела и вашего API-ключа и сопоставить его с параметром sign.
Пример в 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