Order และลิงก์จ่าย

Order คือการซื้อ 1 ครั้ง เซิร์ฟเวอร์เกมสร้างเมื่อผู้เล่นกดซื้อ

Base URL: https://api.ez2pay.gg

ทุก request ใช้ API key ของเกม:

Authorization: Bearer ez2_live_...

เรียก API จากเซิร์ฟเวอร์เท่านั้น error เป็น JSON รูปแบบ {"error":"CODE"} ดูข้อผิดพลาดและวิธีแก้ body ของ request จำกัด 16 KiB

สร้าง Order

curl -X POST https://api.ez2pay.gg/v1/orders \
  -H "Authorization: Bearer $EZ2PAY_API_KEY" \
  -H "Idempotency-Key: purchase-7f3a9c" \
  -H "Content-Type: application/json" \
  -d '{"sku":"gem_pack_100","buyer":"p_123","customer_email":"[email protected]","return_url":"https://game.example/topup/result"}'

ช่อง	ความหมาย	กติกา
`sku`	รหัส SKU	ยาว 1-100 ต้องเป็น SKU ที่ `active` ในเกมนี้
`buyer`	รหัสผู้เล่นในเกม	ยาว 1-200 ใช้ระบุว่าส่งของให้ใคร
`customer_email`	อีเมลผู้เล่นสำหรับใบเสร็จ	อีเมลถูกต้อง ยาวไม่เกิน 254 ไม่ส่งให้ AI ผ่าน MCP
`return_url`	หน้าผลลัพธ์ของเกม	HTTPS ยาวไม่เกิน 2048 ห้ามมี username หรือ password

ไม่มีช่องราคา EZ2Pay ดึงราคาจาก SKU เสมอ ช่องอื่นนอกตารางนี้จะได้ 400

เกมต้องเป็น approved ไม่เช่นนั้นได้ 409 GAME_APPROVAL_REQUIRED

Idempotency-Key

header นี้บังคับ ใช้กันการสร้าง Order ซ้ำเมื่อเซิร์ฟเวอร์ลองใหม่

key เดิม ข้อมูลเดิม: ได้ Order เดิมกลับมาพร้อม 200
key เดิม ข้อมูลเปลี่ยน: 409 IDEMPOTENCY_CONFLICT
การซื้อครั้งใหม่ต้องใช้ key ใหม่
รูปแบบ: ตัวอักษร ASCII ที่พิมพ์ได้ 1-200 ตัว ห้ามมีช่องว่าง

คำตอบ

Order ใหม่ตอบ 201 การส่งซ้ำด้วย key เดิมตอบ 200

{
  "order_id": "ord_00000000-0000-4000-8000-000000000001",
  "sku": "gem_pack_100",
  "buyer": "p_123",
  "status": "CREATED",
  "amount": "100.00",
  "currency": "THB",
  "checkout_url": "https://pay.ez2pay.gg/my-fantasy-town?t=Xk29fQ...",
  "expires_at": "2026-11-09T05:10:00.000Z",
  "paid_at": null,
  "delivered_at": null,
  "paid_channel": null,
  "unlock_at": null,
  "void_reason": null
}

ช่อง	ความหมาย
`order_id`	`ord_` ตามด้วย UUID
`amount`	ราคาเต็มที่ผู้เล่นจ่ายให้ EZ2Pay เป็นสตริงทศนิยม 2 ตำแหน่ง ไม่ใช่เงินที่คุณได้รับ
`currency`	`THB` เสมอ
`checkout_url`	พาผู้เล่นมาที่นี่
`expires_at`	เวลาที่ Order หยุดรับการจ่ายใหม่ เป็น UTC
`paid_at`	เวลาที่ยืนยันเงินเข้าครั้งแรก เป็น UTC แก้ไม่ได้
`delivered_at`	เวลาที่คุณแจ้งส่งของแล้ว เป็น UTC
`paid_channel`	`promptpay` หรือ `card` เมื่อจ่ายแล้ว
`unlock_at`	วันที่รับเงินค่าสินค้าของรายการนี้ได้ เป็น UTC
`void_reason`	เหตุผลที่ยกเลิก ถ้ามี

ใช้ลิงก์จ่าย

พาผู้เล่นไปที่ checkout_url
หน้าจ่ายแสดงชื่อเกม ของ ราคา และ ผู้ขาย: EZ2Pay
ผู้เล่นจ่าย ตอนนี้เปิด PromptPay QR ส่วนบัตรเครดิตแสดง "เร็วๆ นี้" จนกว่าจะเปิด

Order รับการจ่ายใหม่ได้ 10 นาที QR มีอายุ 10 นาทีนับจากตอนออก ผู้เล่นที่เริ่มจ่ายก่อน expires_at เล็กน้อยจึงจ่ายต่อจนจบได้ สถานะจะเป็น EXPIRED แล้วเปลี่ยนเป็น PAID ให้ถือว่า Webhook นั้นเป็นการขายปกติ

หลัง expires_at ให้สร้าง Order ใหม่ด้วย Idempotency-Key ใหม่ ถ้าใช้ key เดิมจะได้ Order ที่หมดอายุกลับมา

return_url คือหน้าที่ผู้เล่นกลับมาหลังจ่าย ใช้แสดงผลเท่านั้น การมาถึงหน้านี้ไม่พิสูจน์อะไร ห้ามส่งของจากหน้านี้

อ่าน Order

curl https://api.ez2pay.gg/v1/orders/ord_00000000-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $EZ2PAY_API_KEY"

ตอบช่องเดียวกับด้านบน Order ของเกมอื่นได้ 404 ORDER_NOT_FOUND

สถานะ Order

สถานะ	ความหมาย
`CREATED`	สร้างแล้ว ผู้เล่นยังไม่เริ่มจ่าย
`PENDING_PAYMENT`	ออกรายการจ่ายแล้ว รอผู้เล่น
`PAID`	ยืนยันเงินเข้าแล้ว
`NOTIFYING`	กำลังส่ง Webhook ไปที่เซิร์ฟเวอร์เกม
`NOTIFIED`	เซิร์ฟเวอร์เกมตอบ `200` แล้ว
`DELIVERED`	เซิร์ฟเวอร์เกมตอบ `200` และแจ้งส่งของแล้ว
`EXPIRED`	หมดเวลาจ่าย
`NOTIFY_FAILED`	ส่ง Webhook ไม่สำเร็จทุกรอบ Order ยังถือว่าจ่ายแล้ว กดส่งซ้ำใน Dashboard ได้
`MISMATCH`	ข้อมูลการจ่ายไม่ตรง ทีม EZ2Pay ตรวจเอง ห้ามส่งของ
`VOIDED`	EZ2Pay ยกเลิกแล้ว
`FAILED`	สร้างรายการจ่ายไม่สำเร็จ

สถานะที่ถือว่าจ่ายแล้วมีเท่านี้: PAID, NOTIFYING, NOTIFIED, NOTIFY_FAILED, DELIVERED

การยกเลิกและส่งแจ้งซ้ำ

API ไม่มี endpoint สำหรับยกเลิก Order หรือส่ง Webhook ซ้ำ ให้ทำใน Dashboard: ค้น Order ด้วย Order ID หรือ Player ID แล้วกดส่งแจ้งซ้ำ หรือส่งเรื่องให้ EZ2Pay

ต่อไป: Webhook และการส่งมอบของ