Global2Pay APIเอกสารสำหรับนักพัฒนาฝั่ง Merchant

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

ต่อให้เสร็จใน 15 นาที

ภาพรวมระบบ

State machine ทั้งหมด

ต้องแจ้งบัญชีผู้โอนตอนสร้างรายการ

ไม่ส่ง sender หรือ sender_id ⇒ 422 sender_required สร้างรายการไม่ได้เลย เพราะเงินเข้าบัญชีบุคคลโดยตรง ระบบจึงต้องรู้ว่าสลิปใบไหนเป็นของรายการไหน · ผู้ใช้โอนจากบัญชีอื่นจะเข้าคิวเจ้าหน้าที่ ไม่ใช่ถูกปฏิเสธ

อ่านกฎบัญชีผู้โอน

durable intake ของสลิปสำเร็จตอบ 202

POST /v1/pay/deposits/{id}/slip ไม่ตอบ 409 duplicate_slip แบบทันที ระบบรับไฟล์ด้วย order-scoped token และตรวจทีหลัง ผลตรวจมาทาง webhook/status; storage/queue ที่ยังยืนยันไม่ครบตอบ retryable 503 ด้วย key เดิม

ทำไมถึงเป็น 202

รายการถอนหนึ่งใบรับได้จากหลายรายการฝาก

ถอน 10,000 อาจถูกเติมเป็น 4,000 + 6,000 จากผู้ฝากคนละคน ⇒ webhook withdrawal.filled มาหลายครั้ง ไม่ใช่ครั้งเดียวตอนจบ · ปิดรายการได้เมื่อ status = settled และ remaining_minor = 0 เท่านั้น

วิธีรับ fill หลายก้อน

Webhook เซ็นด้วยคู่กุญแจ ไม่ใช่ shared secret

เราถือ private key คุณถือ public key ที่ดึงจาก GET /v1/webhooks/signing-keys โดยไม่ต้อง auth ⇒ ฐานข้อมูลฝั่งเราหลุดก็ปลอม webhook ไม่ได้ · ลายเซ็น Ed25519 ผูกกับ timestamp และ event_id เพื่อบล็อก replay และการสลับ body

โค้ดตรวจลายเซ็น

Payload ครบใบ ไม่ต้องยิง API ซ้ำ

ทุก event ส่ง data.object เต็มใบ ณ ขณะนั้นพร้อม version ⇒ อัปเดตด้วย UPDATE เดียวที่มี WHERE version < ใหม่ ไม่ต้อง GET กลับมาถาม · ลำดับ event ไม่การันตี version guard คือสิ่งที่กันไม่ให้ event เก่ามาทับของใหม่

version guard ที่ถูกต้อง

เงินเป็นสตางค์ เวลาเป็น UTC เสมอ

ทุกฟิลด์เงินเป็น integer หน่วยสตางค์และลงท้าย _minor (5,000.00 บาท = 500000) · ทุกเวลาเป็น RFC3339 UTC ลงท้าย Z มิลลิวินาที 3 หลัก · เครดิตผู้ใช้ปลายทางด้วย amount_received_minor ส่วนกระเป๋า merchant ขยับด้วย credited_amount_minor คนละตัวกัน

พจนานุกรม field

เริ่มจากตรงไหน

คุณกำลังจะทำอะไร	ไปที่
ต่อครั้งแรก อยากเห็นรายการฝากใบแรกวิ่งจนจบ	ต่อให้เสร็จใน 15 นาที
เซ็น request ขาเข้า (HMAC-SHA256) ไม่ผ่าน ได้ 401	การยืนยันตัวตนของ request
อยากรู้ว่าสถานะไหนแปลว่าเครดิตได้	สถานะรายการฝาก
ตรวจลายเซ็น webhook ไม่ผ่าน	ตรวจลายเซ็น Ed25519
ยอดถอนแสดงผิดเพราะ event สลับลำดับ	ลำดับไม่การันตี — version guard
ย้ายมาจาก gateway เจ้าอื่น	ย้ายจากผู้ให้บริการเดิม
กำลังจะขึ้น production	เช็กลิสต์ก่อน go-live

สามข้อที่พังบ่อยที่สุด

status = 'settled' เท่านั้นที่แปลว่าเครดิตได้ — slip_processing และ under_review แปลว่าเงินโอนแล้วแต่ยังตรวจไม่จบ ห้ามปล่อยของ
expired และ canceled ไม่ใช่จุดจบเสมอไป — ถ้ามี late_slip_accepted_until และ is_terminal เป็น false ผู้ใช้ยังอัปสลิปย้อนหลังได้ อย่าเพิ่งยกเลิกออร์เดอร์
202 ไม่ใช่ error — ตอนอัปสลิปจะได้ accepted + receipt_id; state เปลี่ยนเป็น slip_processing แบบ async ภายหลัง