Webhook
Webhook نوعی روش بازخورد برای اطلاعات پرداخت است.
هنگامی که وضعیت فاکتور تغییر می کند ، درخواست ارسال به url_callback مشخص شده هنگام ایجاد فاکتور ارسال می شود.
هنگامی که وضعیت فاکتور تغییر می کند ، درخواست ارسال به url_callback مشخص شده هنگام ایجاد فاکتور ارسال می شود.
واکنش
پارامترهای پاسخ
| نام | تعریف |
|---|---|
| type | نوع فاکتور (کیف پول / پرداخت) |
| uuid | UUID پرداخت |
| order_id | شناسه سفارش در سیستم خود (برای شناسایی سفارش) |
| amount | مقدار فاکتور |
| payment_amount | مبلغی که در واقع توسط مشتری پرداخت می شود |
| payment_amount_usd | مبلغی که در واقع توسط مشتری به دلار پرداخت می شود |
| merchant_amount | مبلغی که به تعادل بازرگان اضافه شده است ، با همه کمیسیون ها کم می شود. |
| commission | مبلغ کمیسیون رمزنگاری |
| 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 انجام می شوداگر شما عملکرد تبدیل خودکار را برای payer_currency فعال نکرده اید (به عنوان مثال تبدیل خودکار BTC به USDT) قسمت convert وجود نخواهد داشت. ساختار |
| txid | هش معامله در blockchain.قسمت txid وجود نخواهد داشت1) پرداخت توسط P2P پرداخت شده است (پرداخت کننده وجوه را از حساب رمزنگاری خود به آدرس مندرج در فاکتور پس گرفت و پرداخت بدون blockchain انجام شد ، فقط در سیستم ما)2) پرداخت پرداخت نشده است3) با پرداخت یا مشتری اشتباه کرد و ما آن را به صورت دستی "پرداخت شده" مشخص کردیم |
| sign | امضاء |
تعریف
نوع فاکتور (کیف پول / پرداخت)تعریف
UUID پرداختتعریف
شناسه سفارش در سیستم خود (برای شناسایی سفارش)تعریف
مقدار فاکتورتعریف
مبلغی که در واقع توسط مشتری پرداخت می شودتعریف
مبلغی که در واقع توسط مشتری به دلار پرداخت می شودتعریف
مبلغی که به تعادل بازرگان اضافه شده است ، با همه کمیسیون ها کم می شود.تعریف
مبلغ کمیسیون رمزنگاریتعریف
آیا فاکتور نهایی شده است. وقتی فاکتور نهایی شد ، پرداخت فاکتور غیرممکن است (پرداخت می شود یا منقضی می شود)تعریف
وضعیت پرداختگزینه های موجود:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paidتعریف
آدرس کیف پول پرداخت کنندهتعریف
uuid از کیف پول استاتیکتعریف
شبکه blockchain که در آن پرداخت انجام می شودتعریف
فاکتورتعریف
ارز که مشتری در واقع با آن پرداخت کرده استتعریف
رشته اطلاعات اضافی که هنگام ایجاد فاکتور ارائه داده ایدتعریف
اطلاعات مربوط به ارز که پرداخت به طور خودکار به آن تبدیل می شود. تبدیل از payer_currency به USDT انجام می شوداگر شما عملکرد تبدیل خودکار را برای payer_currency فعال نکرده اید (به عنوان مثال تبدیل خودکار BTC به USDT) قسمت convert وجود نخواهد داشت. ساختارتعریف
هش معامله در blockchain.قسمت txid وجود نخواهد داشت1) پرداخت توسط P2P پرداخت شده است (پرداخت کننده وجوه را از حساب رمزنگاری خود به آدرس مندرج در فاکتور پس گرفت و پرداخت بدون blockchain انجام شد ، فقط در سیستم ما)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
از آنجا که با دریافت webhooks محصولات را منتشر کرده یا موجودی کاربران خود را اعتبار می‌دهید، باید مطمئن شوید که webhooks را از Cryptomus دریافت می‌کنید و نه از کسی دیگر.
ما به شما توصیه می کنیم هر دو روش را بررسی کنید:
- از فهرست سفید آدرس IP استفاده کنید و درخواست‌ها به url_callback را فقط از IPهای ما مجاز کنید. ما webhooks را از IP 91.227.144.54 ارسال می‌کنیم.
- در هر webhook که به url_callback شما می‌آید، امضاء را تأیید کنید، درباره این موضوع بیشتر در پایین بخوانید.
تأیید امضای Webhook
کلیدهای API شما محرمانه هستند و هیچ‌کس به جز شما و Cryptomus نباید آنها را بداند. بنابراین، هنگام تأیید امضاء، مطمئن خواهید بود که webhook توسط Cryptomus ارسال شده است.
ما با استفاده از این الگوریتم یک علامت ایجاد می کنیم. MD5 هش از بدنه درخواست پست رمزگذاری شده در Base64 و همراه با کلید API شما.
از آنجا که امضای در بدنه درخواست می آید ، برای تأیید آن ، باید علامت را از بدن پاسخ استخراج کنید ، یک هش را از بدن و کلید API خود تولید کنید و آن را با پارامتر علامت مطابقت دهید.
نمونه ای در PHP:
برای دریافت داده JSON ارسال شده از طریق پست به Webhook Handler خود:
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 از بریدگی ها فرار می کند و برخی از زبان های دیگر چنین نمی کنند. بنابراین ، ممکن است با عدم تطابق علامت روبرو شوید. شما باید از برش ها با backslash فرار کنید تا به درستی کار کند.
در 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