วงจรชีวิตของใบแจ้งหนี้

ใบแจ้งหนี้เดินทางจากการสร้างไปจนถึงการปิดหรือหมดอายุ ส่วนนี้อธิบายสถานะที่ใบแจ้งหนี้เป็นได้ วิธีเปลี่ยนจากสถานะหนึ่งไปอีกสถานะหนึ่ง และสิ่งที่ร้านค้าทำได้ในแต่ละขั้น

สถานะของใบแจ้งหนี้

สถานะ	ค่าใน API	คำอธิบาย	รวมในการค้นหาการชำระเงิน
ยังไม่ชำระ (Unpaid)	unpaid	ใบแจ้งหนี้ถูกออกแล้ว กำหนดเวลาชำระเงินยังไม่ผ่าน และยังไม่ได้รับการชำระเงิน	ใช่
ชำระแล้ว (Paid)	paid	พบการชำระเงินและจับคู่กับใบแจ้งหนี้แล้ว	ไม่
หมดอายุ (Expired)	expired	กำหนดเวลาชำระเงินผ่านไปแล้วโดยไม่ได้รับการชำระเงิน	ใช่ ต่ออีกหนึ่งชั่วโมงหลังหมดอายุ
ยกเลิก (Canceled)	canceled	ใบแจ้งหนี้ถูกร้านค้ายกเลิกด้วยตนเองหรือผ่าน API	ไม่

การเปลี่ยนสถานะ

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

ใบแจ้งหนี้ในสถานะชำระแล้วก็ไม่เปลี่ยนสถานะเช่นกัน — ไม่สามารถชำระซ้ำหรือยกเลิกได้

กำหนดเวลาชำระเงิน

กำหนดเวลาถูกตั้งตอนสร้างใบแจ้งหนี้ อยู่ระหว่าง 30 นาทีถึง 12 ชั่วโมง ค่าที่อนุญาต: 30 นาที 1 ชั่วโมง 3 ชั่วโมง 6 ชั่วโมง และ 12 ชั่วโมง

ก่อนถึงกำหนดเวลา ลูกค้าจะเห็นฟอร์มชำระเงินและชำระใบแจ้งหนี้ได้ เมื่อหมดอายุแล้ว ใบแจ้งหนี้จะเปลี่ยนเป็นสถานะหมดอายุ และฟอร์มชำระเงินจะไม่เปิดให้ชำระอีก

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

หน้าต่างค้นหาการชำระเงิน

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

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

การยกเลิกใบแจ้งหนี้

คุณยกเลิกใบแจ้งหนี้ได้หากมีข้อผิดพลาด การยกเลิกต้องเข้าเงื่อนไขสองข้อ:

• ใบแจ้งหนี้ยังไม่ถูกชำระ — นั่นคืออยู่ในสถานะยังไม่ชำระ
• ยังไม่มีใครเปิดหน้าชำระเงินของใบแจ้งหนี้ ตัวนับการดูเป็นศูนย์

เงื่อนไขข้อที่สองป้องกันการยกเลิกใบแจ้งหนี้ที่ลูกค้าเห็นแล้วและอาจเริ่มชำระแล้ว

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

สิ่งที่ล็อกตอนสร้างและสิ่งที่คำนวณใหม่ตอนชำระ

ตอนสร้างใบแจ้งหนี้ บริการแปลงจำนวนเงินเฟียตเป็นคริปโตตามอัตราแลกเปลี่ยนปัจจุบัน แล้วล็อกจำนวนที่ได้ไว้สำหรับใบแจ้งหนี้ นี่คือจำนวนที่ลูกค้าเห็น และเป็นจำนวนที่บริการค้นหาแบบ on-chain อัตราแลกเปลี่ยนไม่มีผลต่อจำนวนเหล่านี้อีก: ไม่ว่าเวลาผ่านไปนานเท่าใด ลูกค้าชำระตรงตามจำนวนที่ล็อกไว้

ณ เวลาชำระเงิน จำนวนทางบัญชีจะถูกคำนวณใหม่:

ฟิลด์	เกิดอะไรขึ้น
amountFiat	จำนวนเงินดั้งเดิมของใบแจ้งหนี้ในสกุลเงินเฟียต ไม่เปลี่ยนแปลงเลย
amountFiatUSD	ถูกเขียนทับด้วยจำนวนเงินที่ได้รับจริง แปลงเป็น USD ตามอัตราแลกเปลี่ยน ณ เวลาชำระเงิน
commissionFiatUSD	คำนวณใหม่จากค่า amountFiatUSD ใหม่ตามอัตราค่าธรรมเนียมของโปรเจกต์

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

การแจ้งเตือนตลอดอายุของใบแจ้งหนี้

การแจ้งเตือนตั้งค่าเป็นรายโปรเจกต์ ใบแจ้งหนี้มีการแจ้งเตือนสองแบบ:

• การชำระเงินขาเข้า (Incoming payment) ส่งไปยังอีเมลและ Telegram เมื่อตรวจพบธุรกรรมขาเข้าใด ๆ บนกระเป๋าเงินของคุณ ไม่ว่าจะจับคู่กับใบแจ้งหนี้ได้หรือไม่
• ใบแจ้งหนี้ชำระแล้ว (Invoice paid) ส่งไปยังอีเมล Telegram และ Webhook URL ทันทีที่ใบแจ้งหนี้เปลี่ยนเป็นชำระแล้ว — ทั้งการจับคู่อัตโนมัติและด้วยตนเอง

จึงได้กฎวินิจฉัยง่าย ๆ: หากการแจ้งเตือนการชำระเงินขาเข้ามาถึงแต่ไม่มีการแจ้งเตือนใบแจ้งหนี้ชำระแล้วตามมา แปลว่าการชำระเงินไม่ถูกจับคู่เพราะยอดเงินไม่ตรงกัน และต้องจัดการด้วยตนเอง

การพาลูกค้ากลับไปยังเว็บไซต์ร้านค้า

ในการตั้งค่าโปรเจกต์ คุณตั้งค่า URL ได้สองรายการซึ่งลูกค้าจะกลับไปจากหน้าชำระเงิน:

• URL เมื่อสำเร็จ (Successful URL) — เปลี่ยนเส้นทางอัตโนมัติหลังใบแจ้งหนี้ถูกชำระ
• URL เมื่อไม่สำเร็จ (Unsuccessful URL) — เปลี่ยนเส้นทางอัตโนมัติเมื่อมีการเปิดใบแจ้งหนี้ที่หมดอายุหรือถูกยกเลิก

URL แต่ละรายการเปิดใช้แยกกัน หากไม่ได้ตั้งค่า URL ลูกค้าจะยังอยู่บนหน้าชำระเงินและเห็นสถานะใบแจ้งหนี้

พารามิเตอร์ uid — ตัวระบุใบแจ้งหนี้สำหรับลูกค้า — จะถูกต่อท้าย URL: https://example.com/order/success?uid=AFhygKX21ecd ร้านค้าใช้ค่านี้ค้นหาคำสั่งซื้อและแสดงหน้าของร้านเองให้ลูกค้า

การมาถึง URL เหล่านี้ไม่ใช่การยืนยันการชำระเงิน — ลูกค้าเปิดลิงก์เองก็ได้ ให้ส่งมอบคำสั่งซื้อโดยอิงจาก webhook หรือหลังจากตรวจสอบสถานะใบแจ้งหนี้ผ่าน API