เว็บฮุก

Webhook คือวิธีการตอบกลับข้อมูลการชำระเงิน
เมื่อสถานะใบแจ้งหนี้เปลี่ยนแปลง คำขอ POST จะถูกส่งไปยัง 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เครือข่ายบล็อคเชนที่ใช้สำหรับการชำระเงิน
currencyสกุลเงินใบแจ้งหนี้
payer_currencyสกุลเงินที่ลูกค้าชำระจริง
additional_dataสตริงข้อมูลเพิ่มเติมที่คุณให้ไว้เมื่อสร้างใบแจ้งหนี้
convertข้อมูลเกี่ยวกับสกุลเงินที่จะแปลงการชำระเงินโดยอัตโนมัติ การแปลงจะดำเนินการจาก payer_currency เป็น USDTฟิลด์ แปลง จะไม่มีอยู่หากคุณไม่ได้เปิดใช้งานฟังก์ชันการแปลงอัตโนมัติสำหรับ payer_currency (เช่น แปลง BTC เป็น USDT อัตโนมัติ) โครงสร้าง
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

คำนิยาม

ที่อยู่กระเป๋าเงินของผู้ชำระเงิน

คำนิยาม

uuid ของกระเป๋าสตางค์แบบคงที่

คำนิยาม

เครือข่ายบล็อคเชนที่ใช้สำหรับการชำระเงิน

คำนิยาม

สกุลเงินใบแจ้งหนี้

คำนิยาม

สกุลเงินที่ลูกค้าชำระจริง

คำนิยาม

สตริงข้อมูลเพิ่มเติมที่คุณให้ไว้เมื่อสร้างใบแจ้งหนี้

คำนิยาม

ข้อมูลเกี่ยวกับสกุลเงินที่จะแปลงการชำระเงินโดยอัตโนมัติ การแปลงจะดำเนินการจาก payer_currency เป็น USDTฟิลด์ แปลง จะไม่มีอยู่หากคุณไม่ได้เปิดใช้งานฟังก์ชันการแปลงอัตโนมัติสำหรับ payer_currency (เช่น แปลง BTC เป็น USDT อัตโนมัติ) โครงสร้าง

คำนิยาม

แฮชธุรกรรมบนบล็อคเชนฟิลด์ txid จะไม่มีอยู่หาก1) ชำระเงินผ่านระบบ p2p (ผู้ชำระเงินถอนเงินจากบัญชี Cryptomus ไปยังที่อยู่ที่ระบุในใบแจ้งหนี้ และชำระเงินโดยไม่ใช้บล็อคเชน แต่ใช้ในระบบของเราเท่านั้น)2) ไม่ได้รับการชำระเงิน3) มีบางอย่างผิดปกติกับการชำระเงินหรือลูกค้าทำผิดพลาดและเราได้ทำเครื่องหมายว่า 'ชำระแล้ว' ด้วยตนเอง

คำนิยาม

ลายเซ็น

โครงสร้างของ 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}
สำเนา

การตรวจสอบเว็บฮุก

เนื่องจากการรับเว็บฮุกจะหมายถึงคุณกำลังเปิดตัวผลิตภัณฑ์หรือเครดิตยอดคงเหลือของผู้ใช้ คุณจึงต้องแน่ใจว่าคุณกำลังรับเว็บฮุกจาก Cryptomus และไม่ใช่จากบุคคลอื่น

เราขอแนะนำให้คุณตรวจสอบทั้งสองวิธี:

  • ใช้รายการที่อยู่ IP ที่อนุญาตและอนุญาตเฉพาะคำขอ url_callback จาก IP ของเราเท่านั้น เราส่งเว็บฮุกจาก IP 91.227.144.54
  • ตรวจสอบลายเซ็นในทุกเว็บฮุกที่ส่งไปยัง url_callback ของคุณ อ่านเพิ่มเติมเกี่ยวกับเรื่องนี้ด้านล่าง

การตรวจสอบลายเซ็นเว็บฮุก

คีย์ API i ของคุณเป็นความลับ และไม่มีใครควรรู้ยกเว้นคุณและ Cryptomus ดังนั้น เมื่อตรวจสอบลายเซ็น คุณจะมั่นใจได้ว่าเว็บฮุกนั้นถูกส่งโดย Cryptomus

เราสร้างสัญญาณโดยใช้อัลกอริทึมนี้ แฮช MD5 ของเนื้อหาคำขอ POST ที่เข้ารหัสด้วย base64 และรวมกับคีย์ API ของคุณ

เนื่องจากลายเซ็นมาอยู่ในเนื้อหาของคำขอ เพื่อตรวจสอบ คุณต้องแยกลายเซ็นจากเนื้อหาการตอบสนอง สร้างแฮชจากเนื้อหาและ API KEY ของคุณ และจับคู่กับพารามิเตอร์ลายเซ็น

ตัวอย่างใน php:

หากต้องการรับข้อมูล JSON ที่ส่งทางไปรษณีย์ไปยังตัวจัดการเว็บฮุกของคุณ ให้ทำดังนี้:


1$data = file_get_contents('php://input');
2$data = json_decode($data, true);
สำเนา

สมมติว่าเราได้รับเว็บฮุกพร้อมข้อมูลใน นี้ อาร์เรย์
ขั้นแรกเราต้องแยกเครื่องหมายจากอาร์เรย์:


1$sign = $data['sign'];
2unset($data['sign']);
สำเนา

ตอนนี้มาสร้างป้ายโดยใช้คีย์การชำระเงิน API ของเรา:


1$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);
สำเนา

ในที่สุด เราก็ตรวจสอบได้ว่าเครื่องหมายที่เราสร้างด้วยคีย์การชำระเงิน API ของเรานั้นเหมือนกับเครื่องหมายที่มากับเว็บฮุกหรือไม่


1if (!hash_equals($hash, $sign)) {
2   return new InvalidHashException();
3}
4
5// or
6
7if ($hash !== $sign) {
8   return new InvalidHashException();
9}
สำเนา

ณ จุดนี้ คุณสามารถมั่นใจได้ว่าเว็บฮุกมาจาก Сryptomus และคุณได้รับข้อมูลทั้งหมดอย่างถูกต้อง

มีความแตกต่างในการเข้ารหัสอาร์เรย์ข้อมูลใน PHP และภาษาอื่นๆ โดย PHP จะ escape เครื่องหมายทับ (slash) ในขณะที่บางภาษาไม่ escape ดังนั้นคุณอาจพบปัญหาความไม่ตรงกันของเครื่องหมาย คุณต้อง escape เครื่องหมายทับและ 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            
สำเนา