Webhook URL

ภาพรวม

ฟีเจอร์นี้ส่งข้อมูลของใบแจ้งหนี้ที่ชำระแล้วไปยังเซิร์ฟเวอร์ของร้านค้า มีไว้เพื่อให้ร้านค้าประมวลผลการชำระเงินโดยอัตโนมัติ และส่งมอบสินค้าหรือบริการให้ลูกค้าของคุณ

Webhook URL ตั้งค่าแยกสำหรับแต่ละโปรเจกต์ และชี้ไปยังสคริปต์ตัวจัดการการชำระเงินภายในร้านค้า ที่อยู่ต้องใช้ HTTPS และชื่อโดเมน: ไม่รับที่อยู่ IP และใบรับรองถูกตรวจสอบทุกครั้งที่ส่ง

ทุกครั้งที่สถานะใบแจ้งหนี้เปลี่ยนเป็นชำระแล้ว (Paid) บริการจะส่งคำขอ POST ไปยัง URL นี้ในรูปแบบต่อไปนี้:

{
   "wallet":{
      "id":"47aa71e2-07a0-482e-9172-7114d7376ba0",
      "name":"usdt-tron",
      "blockchain":"tron",
      "cryptocurrency":"usdt",
      "address":"TKbstUwMzLrfTAGL4erYb7gc7ghmHQ9zG7"
   },
   "project":{
      "id":"9deea1e2-0c08-41a3-bdc2-a34eada3892d",
      "name":"My project",
      "commissionPayer":"seller",
      "commissionRate":1
   },
   "invoice":{
      "id":"a4c9e2ee-9a03-43e5-a1a1-00caf679d16a",
      "uid":"AFhygKX21ecd",
      "createDatetime":"2024-02-26 13:29:24",
      "timeToPayDatetime":"2024-02-27 01:29:24",
      "commissionFiatUSD":0.05,
      "amountFiatUSD":5.02,
      "amountFiat":5,
      "calcAmountFiat":5.02,
      "currencyFiat":"USD",
      "description":null,
      "serviceData":null,
      "status":"paid"
   },
   "payment":{
      "id":"f986ad8d-2298-473d-982a-efbc817b975d",
      "amount":5.02,
      "hash":"74763b65e43bcc9492a6ce9a7f26fbfdbd7635aecd3454420b5e9534cba50ee6",
      "transactionDatetime":"2024-02-26 13:32:57"
   }
}

การแจ้งเตือนถูกส่งทุกครั้งที่มีการเปลี่ยนเป็นชำระแล้ว — ทั้งเมื่อบริการพบการชำระเงินโดยอัตโนมัติ และเมื่อร้านค้าจับคู่การชำระเงินกับใบแจ้งหนี้ด้วยตนเอง

พารามิเตอร์คำขอ

พารามิเตอร์	คำอธิบาย
wallet.id	ID ของกระเป๋าเงินในรูปแบบ UUID
wallet.name	ชื่อกระเป๋าเงิน
wallet.blockchain	บล็อกเชนของกระเป๋าเงินคริปโต
wallet.cryptocurrency	สกุลเงินคริปโตของกระเป๋าเงิน
wallet.address	ที่อยู่ของกระเป๋าเงินคริปโต
project.id	ID ของโปรเจกต์ในรูปแบบ UUID
project.name	ชื่อโปรเจกต์
project.commissionPayer	ผู้จ่ายค่าธรรมเนียมบริการ
project.commissionRate	อัตราค่าธรรมเนียมเป็น %
invoice.id	ID ของใบแจ้งหนี้ในรูปแบบ UUID
invoice.uid	ID ของใบแจ้งหนี้ (สำหรับลูกค้า)
invoice.createDatetime	วันที่และเวลาที่สร้างใบแจ้งหนี้ (UTC)
invoice.timeToPayDatetime	วันที่และเวลาที่ใบแจ้งหนี้มีอายุถึงสำหรับลูกค้า (UTC) การค้นหาการชำระเงินดำเนินต่ออีก 1 ชั่วโมงหลังจุดนี้ — เผื่อเครือข่ายที่ช้า ดังนั้นการแจ้งเตือนอาจมาถึงสำหรับใบแจ้งหนี้ที่แสดงเป็นหมดอายุไปแล้ว
invoice.commissionFiatUSD	จำนวนค่าธรรมเนียมบริการ คำนวณจากจำนวนเงิน invoice.amountFiatUSD
invoice.amountFiatUSD	จำนวนเงินเป็น USD ตอนสร้างใบแจ้งหนี้คำนวณจาก invoice.amountFiat ตามอัตราแลกเปลี่ยนปัจจุบัน ณ เวลาชำระเงินจะถูกเขียนทับด้วยจำนวนเงินที่ได้รับจริง แปลงเป็น USD ตามอัตราแลกเปลี่ยน ณ ขณะนั้น ค่าธรรมเนียมใน invoice.commissionFiatUSD ก็ถูกคำนวณใหม่จากค่านี้ด้วย
invoice.amountFiat	จำนวนเงินดั้งเดิมของใบแจ้งหนี้ในสกุลเงินเฟียต ไม่เปลี่ยนแปลง
invoice.calcAmountFiat	จำนวนเงินที่คำนวณในสกุล invoice.currencyFiat ตามอัตราแลกเปลี่ยนคริปโต ณ เวลาชำระเงิน อาจต่างจาก invoice.amountFiat เพราะลูกค้าอาจชำระใบแจ้งหนี้หลังการสร้างไประยะหนึ่งแทนที่จะชำระทันที ในช่วงเวลานั้น อัตราแลกเปลี่ยนคริปโตเทียบกับ invoice.currencyFiat อาจขยับไปทางใดก็ได้
invoice.currencyFiat	สกุลเงินเฟียต
invoice.description	คำอธิบายที่ตั้งไว้ตอนสร้างใบแจ้งหนี้
invoice.serviceData	ข้อมูลฝั่งบริการที่ตั้งไว้ตอนสร้างใบแจ้งหนี้
invoice.status	สถานะใบแจ้งหนี้
payment.id	ID ของการชำระเงินในรูปแบบ UUID
payment.amount	จำนวนเงินชำระในสกุลเงินคริปโต
payment.hash	แฮชของธุรกรรม on-chain
payment.transactionDatetime	วันที่และเวลาของธุรกรรม on-chain (UTC)

ลายเซ็นของการแจ้งเตือน

คำขอทุกคำขอถูกเซ็นด้วยคีย์ลับของ Webhook ลายเซ็นเดินทางใน header X-Timestamp และ X-Signature และช่วยให้แน่ใจว่าการแจ้งเตือนมาจากบริการจริง ไม่ใช่จากบุคคลภายนอกที่รู้ที่อยู่ตัวจัดการของคุณ

ตรวจสอบลายเซ็นก่อนประมวลผลคำสั่งซื้อ กลไกและตัวอย่างสำเร็จรูปอยู่ในการตรวจสอบลายเซ็น Webhook

คำแนะนำในการจัดการ

อย่าปฏิเสธการแจ้งเตือนเพียงเพราะกำหนดเวลาชำระเงินผ่านไปแล้ว การตรวจสอบแบบ “ใบแจ้งหนี้หมดอายุแล้ว การชำระเงินจึงใช้ไม่ได้” ดูสมเหตุสมผลแต่ตัดการชำระเงินจริงทิ้งไปส่วนหนึ่ง: บนเครือข่ายที่ช้า ธุรกรรมอาจได้รับการยืนยันหลังกำหนดเวลา และร้านค้าจับคู่การชำระเงินกับใบแจ้งหนี้ที่หมดอายุด้วยตนเองได้ การแจ้งเตือนนั้นเองคือการยืนยันการชำระเงิน

ตรวจสอบจำนวนเงินกับฟิลด์ดั้งเดิม invoice.amountFiat นี่คือจำนวนของใบแจ้งหนี้ตามที่ออกไว้ และไม่เปลี่ยนแปลง ส่วนฟิลด์ amountFiatUSD สะท้อนจำนวนที่ได้รับจริง และอาจต่างจากจำนวนที่ออกไว้ — ทั้งจากการเคลื่อนไหวของอัตราแลกเปลี่ยนและจากการจับคู่การชำระเงินด้วยตนเอง

แยกวิเคราะห์จำนวนเงินแบบตัวเลข ศูนย์ท้ายถูกตัดออก: จำนวน 10.00 มาถึงเป็น 10 ให้จัดรูปแบบเพื่อแสดงผลที่ฝั่งคุณเอง จำนวนที่ต่ำกว่า 0.0001 มาถึงในสัญกรณ์เลขชี้กำลัง เช่น 1.0e-6 — การแยกวิเคราะห์ JSON มาตรฐานคืนตัวเลขที่ถูกต้อง มีเพียงการแยกสตริงด้วยตนเองเท่านั้นที่พัง

จัดการการแจ้งเตือนแบบ idempotent การแจ้งเตือนเดียวกันอาจมาถึงซ้ำ — เช่น หากสคริปต์ของคุณประมวลผลการชำระเงินสำเร็จแต่ตอบกลับด้วยโค้ดที่ไม่ใช่ 2xx ก่อนส่งมอบคำสั่งซื้อ ให้ตรวจว่า invoice.id นี้ถูกประมวลผลไปแล้วหรือยัง

Escape ค่าก่อนแสดงผล ฟิลด์ invoice.description และ invoice.serviceData ถูกส่งกลับมาตรงตามที่ร้านค้าส่งไว้ทุกประการ หากคุณเรนเดอร์ค่าเหล่านี้ใน HTML ให้ escape ที่ฝั่งคุณเอง

ตารางการส่ง

เซิร์ฟเวอร์ที่ Webhook URL ต้องตอบกลับด้วยโค้ด HTTP 2xx โค้ดอื่น การหมดเวลา หรือการเชื่อมต่อหลุดนับเป็นการส่งที่ล้มเหลว

ไม่มีการติดตามการเปลี่ยนเส้นทาง: การตอบกลับ 301 หรือ 302 คือการส่งที่ล้มเหลว ไม่ใช่การข้ามไปยังที่อยู่ใหม่ ให้ตั้งที่อยู่สุดท้ายของตัวจัดการ

การเชื่อมต่อมีเวลา 5 วินาที ส่วนคำขอทั้งหมดมี 10 วินาที หากตัวจัดการทำไม่ทันในเวลานี้ การส่งนับเป็นล้มเหลว

หลังการส่งล้มเหลว บริการจะลองส่งใหม่ตามตารางต่อไปนี้:

• 5 นาทีหลังการส่งล้มเหลวครั้งล่าสุด
• หลังจากนั้นอีก 15 นาที
• หลังจากนั้นอีก 30 นาที
• หลังจากนั้นอีก 1 ชั่วโมง
• หลังจากนั้นอีก 3 ชั่วโมง
• หลังจากนั้นอีก 6 ชั่วโมง
• หลังจากนั้นอีก 12 ชั่วโมง
• หลังจากนั้นอีก 24 ชั่วโมง

หลังจากนั้น การพยายามส่งจะหยุดลง

การปิดใช้งาน Webhook URL

บางครั้งสคริปต์ webhook ของร้านค้าประมวลผลการชำระเงินได้ถูกต้อง แต่ตอบกลับด้วยโค้ด HTTP ที่ไม่ใช่ 2xx ซึ่งทำให้เซิร์ฟเวอร์ของเราลองส่งใหม่บ่อยครั้งตามตารางข้างต้น เพิ่มภาระทั้งกับเซิร์ฟเวอร์ของเราและของคุณ

เพื่อป้องกันกรณีแบบนี้ เรามีกลไกที่ปิดใช้งาน Webhook URL ในโปรเจกต์ หากไม่อยากให้เกิดขึ้น ให้ทำตามขั้นตอนต่อไปนี้:

1. แก้โค้ดตัวจัดการ webhook ของคุณให้ตอบกลับด้วยโค้ด 2xx โดยปกติคือ 200 เมื่อประมวลผลการชำระเงินสำเร็จ ทดสอบด้วยโปรแกรมจำลองใดก็ได้ เช่น Postman
2. ติดต่อฝ่ายสนับสนุนทางเทคนิคเพื่อแก้ไขการตั้งค่า
3. เปิดใช้งาน Webhook URL อีกครั้งในการตั้งค่าโปรเจกต์ แล้วบันทึกโปรเจกต์