รู้จัก API ตรวจสลิปสำหรับนักพัฒนา เชื่อมกับระบบหลังบ้านของร้าน

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

ภาพรวม flow การรับชำระผ่านใบแจ้งหนี้

รูปแบบที่ PPay รองรับและปลั๊กอินสำเร็จรูปใช้อยู่คือ ระบบของร้านสร้างรายการรับชำระ (ใบแจ้งหนี้) ผ่าน POST /api/v1/invoices โดยส่งข้อมูลอย่างร้านค้า ยอดเงิน รหัสอ้างอิงของออเดอร์ ชื่อรายการ เวลาหมดอายุ และ returnUrl จากนั้นพาลูกค้าไปยังลิงก์ชำระเงินที่ได้กลับมา ลูกค้าโอนเงินและอัปโหลดสลิปบนหน้านั้น เมื่อผ่านการตรวจแล้วจึงกลับมายังร้าน

1. ร้านสร้างใบแจ้งหนี้ด้วย API key
2. ลูกค้าไปที่หน้าชำระเงินและอัปโหลดสลิป
3. ระบบตรวจสลิปและอัปเดตสถานะใบแจ้งหนี้
4. ร้านรับรู้ผลผ่าน webhook หรือเรียกอ่านสถานะ

สามวิธีรู้ว่าจ่ายแล้ว

Webhook

PPay ส่งเหตุการณ์ invoice.paid มายัง URL ที่ร้านตั้งไว้ พร้อมลายเซ็นแบบ HMAC ในเฮดเดอร์ ฝั่งร้านควรตรวจลายเซ็นและตรวจว่าเวลาของคำขอไม่เก่าเกินไป เพื่อกันการยิงซ้ำจากผู้ไม่หวังดี

เรียกอ่านสถานะ

ใช้ GET /api/v1/invoices/{code} เพื่ออ่านสถานะล่าสุดของใบแจ้งหนี้ เหมาะสำหรับตอนที่ลูกค้ากลับมาที่ร้าน

ตรวจเป็นรอบ

เพิ่มงานตรวจตามเวลา (cron) เพื่อรับมือกรณี webhook ไม่ถึง ปลั๊กอินของ PPay ใช้วิธีตรวจทุก 5 นาทีเป็นตัวสำรอง

หลักการออกแบบที่ควรยึด

• อย่าเชื่อค่าจากเบราว์เซอร์ การที่ลูกค้ากลับมาที่ returnUrl ไม่ได้แปลว่าจ่ายแล้ว ให้ฝั่งเซิร์ฟเวอร์ถามสถานะจาก API เสมอ
• เทียบยอดเอง ตรวจว่ายอดที่ชำระไม่น้อยกว่ายอดออเดอร์ก่อนเปลี่ยนสถานะ
• ทำให้ idempotent webhook อาจมาซ้ำ ควรมีตัวกันการประมวลผลซ้ำ เช่นล็อกตามออเดอร์
• ตั้ง reference ที่แยกระบบได้ เช่นใส่คำนำหน้า เพื่อไม่ให้ชนกับรายการอื่นในบัญชีเดียวกัน
• เก็บ API key เป็นความลับ ไว้ฝั่งเซิร์ฟเวอร์เท่านั้น ห้ามฝังในโค้ดหน้าเว็บหรือแอปมือถือ

ข้อควรรู้เรื่องข้อจำกัด

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

ถ้าไม่อยากเขียนเอง

ร้านที่ใช้ WooCommerce, WHMCS หรือ Magento 2 สามารถใช้ ปลั๊กอินสำเร็จรูป ที่ใช้ flow เดียวกันนี้ ช่วยลดงานพัฒนาลงมาก แต่ควรทดสอบบนระบบทดสอบของคุณก่อนใช้งานจริงเสมอ

เช็กลิสต์ก่อนขึ้นระบบจริง

1. สร้างและเก็บ API key อย่างปลอดภัย
2. ตรวจลายเซ็นและเวลา webhook
3. มีตัวกันประมวลผลซ้ำ
4. มีงานสำรองตรวจสถานะเป็นรอบ
5. ทดสอบกรณีโอนขาด โอนซ้ำ และสลิปไม่ผ่าน

เมื่อพร้อมแล้ว สมัครใช้งานได้ที่ หน้าสมัครสมาชิก และอ่านเอกสารฉบับเต็มที่ เอกสาร API