วงจรรายการรับเงิน

รายการรับเงิน (pay-in) คือคำขอให้ผู้ชำระเงินโอนเงินเข้ามาหนึ่งครั้ง ระบบจะบอกว่าต้องโอนเท่าไรและโอนไปที่ไหน แล้วจับคู่เงินที่เข้าบัญชีกับรายการให้อัตโนมัติ

ภาพรวม

   สร้างรายการ ──► สร้างใหม่ (pending) ──── ผู้ชำระเงินโอนตรงยอด ────► สำเร็จ (succeeded)
                        │                    ระบบจับคู่อัตโนมัติ
                        │
                        ├── ไม่มีเงินเข้าภายในเวลาที่กำหนด ──► หมดเวลา (expired)
                        │                                        │
                        │                                        └── ยืนยันด้วยสลิป ──► สำเร็จ
                        │
                        └── คุณหรือระบบยกเลิก ──► ยกเลิกแล้ว (canceled)

ชื่อในวงเล็บคือสถานะใน API ดูทุกสถานะที่ ตารางสถานะ

ขั้นตอน

1. คุณสร้างรายการ

   ระบบของคุณเรียก POST /v1/payins พร้อมผู้ชำระเงิน ยอดเงิน เลขคำสั่งซื้อของคุณ (reference) และ URL สำหรับแจ้งผล ระบบตอบกลับด้วย

   • amount ยอดที่ผู้ชำระเงินต้องโอน (อาจมีเศษสตางค์เพิ่ม)
   • paymentImage รูป QR หรือบัตรข้อมูลการโอน และ payTo ข้อมูลบัญชีปลายทาง
   • checkoutUrl หน้าชำระเงินสำเร็จรูปที่ส่งผู้ชำระเงินไปได้เลย

   รายการใหม่มีสถานะ สร้างใหม่ ดูรายละเอียดฟิลด์ใน รับเงิน (API)

2. ผู้ชำระเงินโอนเงิน

   PromptPay QR

   ผู้ชำระเงินสแกน QR ด้วยแอปธนาคาร ยอดเงินถูกกรอกให้แล้ว QR ใช้ได้กับรายการนี้ครั้งเดียว

   

   โอนผ่านธนาคาร

   หน้าชำระเงินแสดงธนาคาร เลขบัญชี ชื่อผู้รับ และ ยอดที่ต้องโอน ผู้ชำระเงินต้องโอนยอดนี้ ทุกหลักรวมเศษสตางค์ จากบัญชีที่ลงทะเบียนไว้

3. ระบบจับคู่อัตโนมัติ

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

   • โอนด้วย QR: เทียบ ชื่อผู้โอน กับชื่อบัญชีภาษาไทย ชื่อภาษาอังกฤษ และชื่อแฝงของผู้ชำระเงิน (ไม่สนคำนำหน้าชื่อ ช่องว่าง และตัวพิมพ์ใหญ่เล็ก ชื่อที่ธนาคารตัดให้สั้นก็จับคู่ได้) ถ้าชื่อไม่ตรงจะเทียบเลขบัญชีบางส่วนแทน
   • โอนผ่านธนาคาร: เทียบ เลขบัญชีต้นทาง (บางส่วน) และธนาคาร

4. ได้ผลลัพธ์

   ถ้าจับคู่ได้ รายการเป็น สำเร็จ ยอดหักค่าธรรมเนียมเข้ายอดคงเหลือของคุณ และระบบส่ง webhook payin.succeeded ถ้าผู้ชำระเงินใช้หน้าชำระเงินสำเร็จรูปและคุณส่ง returnUrl ไว้ หน้าจะพาผู้ชำระเงินกลับไปยังเว็บไซต์ของคุณ

ยอดเงินที่มีเศษสตางค์

เพื่อแยกรายการที่ยอดเท่ากันออกจากกัน ระบบจะเพิ่มเศษสตางค์ 0.01–0.99 บาทให้ยอดที่ต้องโอน เช่น ขอรับ 1,000.00 บาท ผู้ชำระเงินต้องโอน 1,000.82 บาท

• ในหน้าเว็บจัดการ ยอดที่คุณขอคือ ยอดที่ผู้ชำระเงินขอ และยอดที่ต้องโอนคือ ยอดที่โอนจริง
• ใน API คือ requestedAmount และ amount
• ใครได้เศษสตางค์ และบัญชีของคุณใช้เศษสตางค์หรือไม่ ขึ้นกับแพ็กเกจค่าธรรมเนียม ถ้าไม่แน่ใจ สอบถามฝ่ายสนับสนุน

บอกผู้ชำระเงินให้โอนตรงยอด

ถ้าผู้ชำระเงินปัดยอดเอง (เช่น โอน 1,000 แทน 1,000.82) หรือโอนจากบัญชีอื่น ระบบจะจับคู่อัตโนมัติไม่ได้ และรายการจะหมดเวลา ต้องแก้ด้วยการยืนยันสลิป (ด้านล่าง)

เวลา

เรื่อง	ค่า
เวลาชำระ	ค่าเริ่มต้น 15 นาทีนับจากสร้างรายการ ผู้ให้บริการอาจกำหนดค่าอื่นสำหรับบัญชีของคุณ
ระยะเวลาที่ระบบตรวจรายการหมดเวลา	ทุกประมาณ 10 วินาที
รายการที่สร้างช่วง 00:00–07:00 น. (เวลาประเทศไทย)	จะเปลี่ยนเป็นหมดเวลาหลัง 07:00 น. ระหว่างนั้นยังจับคู่ได้ถ้ามีเงินเข้า
รายการรอชำระต่อผู้ชำระเงิน	ครั้งละหนึ่งรายการ สร้างใหม่ได้เมื่อรายการเดิมจบแล้ว

เมื่อโอนแล้วแต่รายการหมดเวลา

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

1. ขอ สลิปการโอน จากผู้ชำระเงิน (รูปจากแอปธนาคารที่มี QR สำหรับตรวจสอบ)
2. ส่งสลิปเข้าระบบด้วยวิธีใดวิธีหนึ่ง
   • หน้าเว็บจัดการ: ผู้ใช้บทบาท เจ้าหน้าที่พาร์ทเนอร์ กด ยืนยันยอดบางส่วน ที่รายการนั้น ดู ยืนยันยอดด้วยสลิป
   • API: POST /v1/payins/{id}/slip ดู ตรวจสลิป
3. ระบบตรวจสลิปกับธนาคาร ถ้าผ่าน รายการจะเป็น สำเร็จ และส่ง webhook payin.succeeded ตามปกติ

ระบบตรวจว่า

• อ่าน QR บนสลิปได้ และสลิปนี้ยังไม่เคยใช้กับรายการอื่น
• บัญชีผู้รับบนสลิปเป็นบัญชีที่ระบบให้ผู้ชำระเงินโอนเข้า
• ยอดเต็มบาท ตรงกับรายการ (ไม่นับเศษสตางค์)
• ผู้โอนบนสลิปตรงกับผู้ชำระเงินของรายการ

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

ยกเลิกรายการ

ยกเลิกได้เมื่อรายการเป็น สร้างใหม่ หรือ หมดเวลา ผ่าน POST /v1/payins/{id}/cancel หรือปุ่ม ยกเลิก ในหน้า รับเงิน ยกเลิกแล้วรายการจะจับคู่ไม่ได้อีก

• ยกเลิกผ่านหน้าเว็บจัดการ ระบบจะส่ง webhook
• ยกเลิกผ่าน API ไม่ส่ง webhook เพราะคุณได้ผลจาก response แล้ว

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

ข้อผิดพลาดที่พบบ่อยตอนสร้างรายการ

รหัสใน API	สาเหตุ	ทำอย่างไร
pending_payin_exists	ผู้ชำระเงินมีรายการรอชำระอยู่	รอรายการเดิมจบ หรือยกเลิกก่อน
amount_below_minimum / amount_above_maximum	ยอดนอกวงเงินต่อรายการของบัญชี	ปรับยอด หรือขอเปลี่ยนวงเงิน
payer_inactive	ผู้ชำระเงินถูกปิดใช้งาน	เปิดใช้งานในหน้า ผู้ชำระเงิน
payer_blocked	ผู้ชำระเงินอยู่ในรายชื่อระงับ	ติดต่อฝ่ายสนับสนุน
maintenance	ระบบหรือธนาคารปิดปรับปรุง	ลองใหม่ภายหลัง
payins_disabled	บัญชีของคุณปิดการรับเงิน	ติดต่อฝ่ายสนับสนุน

รายการทั้งหมดอยู่ที่ ข้อผิดพลาด