Merchant Integration · v1

Gateway API Reference

คู่มือเชื่อมต่อระบบรับชำระเงินสำหรับร้านค้า — สร้างรายการ รับ QR PromptPay และรับแจ้งผลผ่าน webhook

1. การยืนยันตัวตน

ทุก request ที่ขึ้นต้นด้วย /v1/ ต้องแนบ API key ของร้านใน header:

X-Api-Key: gw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. ภาพรวมการทำงาน

• ร้านเรียก POST /v1/payments ระบุยอดเงิน → ได้ checkout_url (หน้าจ่ายเงินพร้อม QR) และ qr_data_url (รูป QR)
• พาลูกค้าไปที่ checkout_url หรือฝัง QR เอง — ลูกค้าสแกนจ่ายด้วยแอปธนาคาร (PromptPay)
• เมื่อจ่ายสำเร็จ ระบบส่ง webhook payment.paid มาที่ URL ที่ร้านตั้งไว้ (เซ็นด้วย HMAC)
• ร้านตรวจลายเซ็น → อัปเดตออร์เดอร์ฝั่งตัวเอง

3. สร้างรายการชำระเงิน

Headers

Body

ตัวอย่าง

curl -X POST https://gateway.alphaquestcom.com/v1/payments \
  -H "X-Api-Key: gw_live_xxxxxxxx" \
  -H "Idempotency-Key: ORDER-10023" \
  -H "Content-Type: application/json" \
  -d '{"amount": 300.00, "merchant_ref": "ORDER-10023"}'

Response 201 Created (ยิงซ้ำ key เดิม = 200)

{
  "payment_id": "pay_01M1J9...",
  "status": "pending",
  "amount": 300,
  "currency": "THB",
  "checkout_url": "https://gateway.alphaquestcom.com/p/pay_01M1J9...",
  "qr_data_url": "data:image/png;base64,iVBOR...",
  "fee_amount": null,
  "net_amount": null
}

fee_amount / net_amount เป็น null จนกว่าจะชำระสำเร็จ (ค่าธรรมเนียมคำนวณตอนจ่ายจริง)

4. ดูสถานะรายการ

curl https://gateway.alphaquestcom.com/v1/payments/pay_01M1J9... \
  -H "X-Api-Key: gw_live_xxxxxxxx"

คืน object เดียวกับตอนสร้าง โดย status เป็นค่าใดค่าหนึ่ง:

pending รอชำระ · paid ชำระแล้ว · cancelled ยกเลิก · expired หมดอายุ (ไม่จ่ายใน 60 นาที)

5. ยกเลิกรายการ

ยกเลิกได้เฉพาะรายการที่ยังไม่ชำระ — ถ้าจ่ายไปแล้วจะได้ 409 already_paid

curl -X POST https://gateway.alphaquestcom.com/v1/payments/pay_01M1J9.../cancel \
  -H "X-Api-Key: gw_live_xxxxxxxx"

6. ดูยอดคงเหลือ

ยอดสุทธิสะสมของร้าน (หลังหักค่าธรรมเนียม)

{ "balance": 1782.50, "currency": "THB" }

7. Webhook (แจ้งผล)

เมื่อสถานะรายการเปลี่ยน ระบบยิง POST ไปที่ webhook URL ของร้าน (ตั้งค่าตอนสมัคร) พร้อม headers:

Payload — payment.paid

{
  "event": "payment.paid",
  "payment_id": "pay_01M1J9...",
  "merchant_ref": "ORDER-10023",
  "amount": 300,
  "paid_amount": 300,
  "fee_amount": 3,
  "net_amount": 297,
  "currency": "THB",
  "paid_at": "2026-09-03T09:42:09.382Z"
}

Payload — payment.cancelled

{
  "event": "payment.cancelled",
  "payment_id": "pay_01M1J9...",
  "merchant_ref": "ORDER-10023",
  "amount": 300,
  "status": "cancelled"  // หรือ "expired"
}

ตรวจลายเซ็น (Node.js)

const crypto = require('crypto')

// rawBody = ตัว body ดิบ (Buffer/string) ก่อน JSON.parse
function verify(rawBody, signatureHeader, webhookSecret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', webhookSecret)
          .update(rawBody, 'utf8').digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signatureHeader))
}

8. รหัสข้อผิดพลาด

ข้อผิดพลาดคืน JSON รูปแบบ { "error": "...", "code": "..." }