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لن يكون حقل تحويل موجودًا إذا لم تقم بتمكين وظيفة التحويل التلقائي لـ payer_currency (على سبيل المثال ، تحويل Auto BTC إلى USDT) بناء
txidتجزئة المعاملة على blockchain.لن يكون حقل txid موجودًا إذا1) تم دفع الدفع بواسطة P2P (سحب الدافع الأموال من حساب Cryptomus الخاص به إلى العنوان المشار إليه في الفاتورة وتم إجراء الدفع بدون blockchain ، فقط في نظامنا)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لن يكون حقل تحويل موجودًا إذا لم تقم بتمكين وظيفة التحويل التلقائي لـ payer_currency (على سبيل المثال ، تحويل Auto BTC إلى USDT) بناء

تعريف

تجزئة المعاملة على blockchain.لن يكون حقل txid موجودًا إذا1) تم دفع الدفع بواسطة P2P (سحب الدافع الأموال من حساب Cryptomus الخاص به إلى العنوان المشار إليه في الفاتورة وتم إجراء الدفع بدون 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 فقط من IPS لدينا. نرسل webhooks من IP. 91.227.144.54
  • تحقق من التوقيع في كل webhook الذي يأتي إلى url_callback ، اقرأ المزيد عن هذا أدناه.

التحقق من توقيع webhook

مفاتيح واجهة برمجة التطبيقات الخاصة بك سرية ولا أحد باستثناءك وينبغي أن يعرفها cryptomus. لذلك ، عند التحقق من التوقيع ، سوف تكون متأكدًا من إرسال Webhook بواسطة Cryptomus.

ننشئ علامة باستخدام هذه الخوارزمية. تجزئة MD5 لجسم طلب البريد المشفر في BASE64 وجمع مع مفتاح API الخاص بك.

عندما يأتي التوقيع في جسم الطلب ، للتحقق منه ، تحتاج إلى استخراج العلامة من جسم الاستجابة ، وإنشاء تجزئة من الجسم ومفتاح API الخاص بك ومطابقة معلمة الإشارة.

مثال في PHP:

لتلقي بيانات JSON التي تم إرسالها بواسطة Post إلى معالج 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            
ينسخ