ศูนย์ช่วยเหลือ
API และการเชื่อมต่อ
คู่มือเริ่มต้น การตั้งค่า API Key, Webhook, Rate Limits และ Error Codes
เริ่มต้นอย่างรวดเร็ว
cURL
curl -X POST https://api-sandbox.paydy.ai/v1/merchant/payment-links \
-H "Authorization: Bearer $PAYDY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: idem_createpaymentlink_001" \
-d '{
"store_id": "01JQ8V0STORE00000000000001",
"title": "WINMAX Order #10428",
"amount": 1290,
"channels_enabled": [
"promptpay",
"visa",
"mastercard"
],
"expires_in_hours": 24,
"reference": "ORD-2026-10428"
}'Node.js
// PAYDY_API_KEY=epk_test_YOUR_TEST_KEY
const res = await fetch('https://api-sandbox.paydy.ai/v1/merchant/payment-links', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PAYDY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'idem_createpaymentlink_001',
},
body: JSON.stringify({
"store_id": "01JQ8V0STORE00000000000001",
"title": "WINMAX Order #10428",
"amount": 1290,
"channels_enabled": [
"promptpay",
"visa",
"mastercard"
],
"expires_in_hours": 24,
"reference": "ORD-2026-10428"
}),
});
const json = await res.json();
if (!json.success) throw new Error(`${res.status} ${json.error.code}: ${json.error.message}`);
console.log(json.data);PHP
<?php
// PAYDY_API_KEY=epk_test_YOUR_TEST_KEY
$ch = curl_init('https://api-sandbox.paydy.ai/v1/merchant/payment-links');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PAYDY_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: idem_createpaymentlink_001',
],
CURLOPT_POSTFIELDS => json_encode([
'store_id' => '01JQ8V0STORE00000000000001',
'title' => 'WINMAX Order #10428',
'amount' => 1290,
'channels_enabled' => [
'promptpay',
'visa',
'mastercard',
],
'expires_in_hours' => 24,
'reference' => 'ORD-2026-10428',
]),
]);
$res = json_decode(curl_exec($ch), true);
print_r($res['data'] ?? $res['error']);การตั้งค่า API Key
- 1เข้าสู่ระบบ Merchant Dashboard
- 2ไปที่เมนู Developer → API Keys
- 3คลิก "สร้าง API Key" เลือก scope ที่ระบบของคุณต้องใช้ (เช่น payment_links:write) แล้วคัดลอกคีย์ — คีย์แสดงเพียงครั้งเดียว
- 4เก็บ Key ไว้อย่างปลอดภัย ห้ามนำใส่ Source Code
การตั้งค่า Webhook
- 1ไปที่เมนู Developer → Webhooks
- 2คลิก "เพิ่ม Endpoint" ระบุ URL แบบ HTTPS
- 3เลือก Events ที่ต้องการรับ
- 4คัดลอก Webhook Secret เพื่อใช้ Verify Signature
ขีดจำกัดการเรียก API
100 คำขอต่อ 60 วินาที ต่อหนึ่ง API key ส่วน endpoint ยืนยันตัวตนเข้มกว่าที่ 5 ครั้งในช่วงเวลาเดียวกัน เพื่อสกัดการสุ่มรหัส
เมื่อได้ 429 ให้รอตามวินาทีใน Retry-After และบวก jitter เล็กน้อย การลองใหม่ทันทีจะเผาโควตาของช่วงถัดไปไปด้วย
รหัสข้อผิดพลาด
ความผิดพลาดทุกแบบใช้โครงสร้างเดียวกัน ตัวจัดการข้อผิดพลาดชุดเดียวจึงครอบคลุมทั้ง API · error.code คือประเภทตามรหัส HTTP ส่วน error.details.code (ถ้ามี) บอกสาเหตุที่แน่ชัด ให้แยกกรณีด้วยสองค่านี้ อย่าแยกด้วยข้อความ · ตารางนี้แสดงเฉพาะรหัสที่ API ส่งจริง
| HTTP | รหัส | ฟิลด์ | หมายความว่าอะไร | แก้อย่างไร |
|---|---|---|---|---|
| 400 | BAD_REQUEST | error.code | คำขอผิดรูปแบบ หรือมีฟิลด์ที่ไม่ผ่านการตรวจ error.message จะระบุกฎที่ไม่ผ่านทุกข้อ | แก้ฟิลด์ตามที่ error.message ระบุ แล้วส่งใหม่ |
| 401 | UNAUTHORIZED | error.code | ไม่มีข้อมูลยืนยันตัวตนที่ใช้ได้ เช่น ไม่มี header Authorization หรือคีย์หรือเซสชันใช้ไม่ได้ | อ่าน error.details.code เพื่อดูสาเหตุที่แน่ชัด (แถว API_KEY_… ด้านล่าง) |
| 403 | FORBIDDEN | error.code | ข้อมูลยืนยันตัวตนถูกต้อง แต่ไม่มีสิทธิ์ทำสิ่งนี้ เช่น คีย์ไม่มี scope ที่ต้องใช้ ผูกกับร้านอื่น หรือบทบาทในทีมของคุณเรียก route นี้ไม่ได้ | อ่าน error.details.code · ถ้าเป็นเรื่องบทบาท ให้เจ้าของบัญชีเปลี่ยนให้ในหน้าตั้งค่าทีม |
| 404 | NOT_FOUND | error.code | ไม่มี id นี้ หรือเป็นของร้านอื่น | ตรวจ ULID และยืนยันว่าเรียกในสภาพแวดล้อมเดียวกับที่สร้างมัน |
| 409 | CONFLICT | error.code | ทรัพยากรอยู่ในสถานะที่ทำคำสั่งนี้ไม่ได้ หรือเป็นคำขอซ้ำกับที่ทำไปแล้ว | อ่าน error.details.code ดึงข้อมูลทรัพยากร แล้วทำต่อตามสถานะปัจจุบัน |
| 410 | GONE | error.code | endpoint หรือทรัพยากรนี้ถูกยกเลิกแล้วและจะไม่กลับมา | ใช้ทางแทนที่ error.message ระบุ |
| 422 | VALIDATION_ERROR | error.code | คำขอรูปแบบถูกต้อง แต่ API ประมวลผลตามที่ส่งมาไม่ได้ | อ่าน error.message และ error.details ว่าต้องแก้อะไร |
| 429 | RATE_LIMITED | error.code | IP หรือผู้ใช้ของคุณส่งคำขอเกินโควตาของช่วงเวลานั้น | หยุดรอพร้อมสุ่มระยะเวลา (jitter) แล้วลองใหม่ |
| 500 | INTERNAL_ERROR | error.code | เกิดข้อผิดพลาดฝั่งเรา · รหัส HTTP อื่นที่ไม่อยู่ในตารางนี้ก็ได้ INTERNAL_ERROR เช่นกัน | ลองใหม่ด้วย Idempotency-Key เดิมแบบ exponential backoff และแจ้ง meta.path กับ meta.timestamp ให้ฝ่ายสนับสนุน |
| 503 | SERVICE_UNAVAILABLE | error.code | สิ่งที่คำขอต้องใช้ยังไม่ได้ตั้งค่าหรือใช้งานไม่ได้ เช่น การส่ง SMS หรือพาร์ทเนอร์ชำระเงิน | อ่าน error.details.code แล้วลองใหม่ภายหลัง หรือให้เจ้าของบัญชีตั้งค่าส่วนที่ระบุให้เสร็จ |
| 400 | IDEMPOTENCY_KEY_INVALID | error.code | Idempotency-Key ไม่ได้อยู่ในรูป 8–64 ตัวอักษรของ [a-zA-Z0-9_-:] | สร้างคีย์จาก ULID หรือ UUID โดยไม่มีวงเล็บหรือช่องว่าง |
| 409 | IDEMPOTENCY_KEY_REUSED | error.code | Idempotency-Key นี้เคยใช้กับเนื้อหาคำขอที่ต่างออกไปแล้ว | คำขอใหม่ให้ใช้คีย์ใหม่ · ถ้าส่งเนื้อหาเดิมทุกตัวอักษร จะได้คำตอบเดิมกลับมา |
| 409 | IDEMPOTENCY_KEY_IN_FLIGHT | error.code | คำขอเดียวกันที่ใช้คีย์นี้ยังประมวลผลไม่เสร็จ | รอสักครู่ แล้วลองใหม่ด้วยคีย์เดิม |
| 401 | API_KEY_INVALID | error.details.code | ค่า bearer ไม่ใช่คีย์ของ PAYDY (epk_test_… หรือ epk_live_…) หรือไม่ตรงกับคีย์ใดเลย | คัดลอกคีย์ทั้งหมดใหม่ — คีย์แสดงเพียงครั้งเดียวตอนสร้าง |
| 401 | API_KEY_REVOKED | error.details.code | คีย์ถูกยกเลิกแล้ว โดยทีมของคุณ หรือโดย PAYDY เพราะเป็นคีย์ที่สร้างก่อนระบบมี scope และไม่เคยใช้งานได้ | สร้างคีย์ใหม่พร้อม scope ที่ต้องใช้ |
| 401 | API_KEY_EXPIRED | error.details.code | คีย์เลยวันหมดอายุแล้ว | สร้างคีย์ใหม่ คีย์ที่หมดอายุไม่ถูกเปิดใช้ซ้ำ |
| 401 | API_KEY_UNVERIFIABLE | error.details.code | ระบบนี้ตรวจคีย์ไม่ได้ในขณะนี้ | ลองใหม่ภายหลัง ถ้ายังเป็นอยู่ ให้ติดต่อฝ่ายสนับสนุนพร้อม meta.path และ meta.timestamp |
| 401 | API_KEY_NOT_ACCEPTED_HERE | error.details.code | route นี้ไม่รับ API key · รับเฉพาะ route ที่อยู่ในเอกสารนี้ | เรียก route ที่มีในเอกสาร หรือทำรายการนี้จากแดชบอร์ด |
| 403 | MERCHANT_SUSPENDED | error.details.code | บัญชีร้านค้าถูกระงับ | ติดต่อฝ่ายสนับสนุนของ PAYDY |
| 403 | API_KEY_MODE_MISMATCH | error.details.code | ส่งคีย์ทดสอบไปที่ระบบจริง หรือส่งคีย์จริงไปที่ Sandbox | ส่งคีย์ epk_test_… ไปที่ api-sandbox.paydy.ai และคีย์ epk_live_… ไปที่ api.paydy.ai |
| 403 | API_KEY_GATEWAY_MODE_MISMATCH | error.details.code | โหมดของคีย์ไม่ตรงกับเกตเวย์ชำระเงินที่เปิดใช้อยู่ในระบบนี้ | ติดต่อฝ่ายสนับสนุน เกตเวย์ของระบบนี้ต้องตั้งเป็นโหมดเดียวกัน |
| 403 | API_KEY_SCOPE_MISSING | error.details.code | คีย์ไม่มี scope ที่ route นี้ต้องใช้ | สร้างคีย์ที่มี scope นั้น — แต่ละ endpoint แสดง scope ที่ต้องใช้ไว้ |
| 403 | API_KEY_STORE_BOUND | error.details.code | ใช้คีย์ที่ผูกกับร้านเดียว เรียก route ที่ทำงานกับทั้งบัญชีร้านค้า | ใช้คีย์แบบทั้งบัญชีสำหรับ route นี้ |
| 403 | API_KEY_STORE_MISMATCH | error.details.code | คีย์ที่ผูกกับร้านหนึ่ง อ้างถึงข้อมูลของร้านอื่น | ใช้คีย์ของร้านนั้น หรือคีย์แบบทั้งบัญชี |
| 403 | API_KEY_CREATOR_INACTIVE | error.details.code | สมาชิกทีมที่สร้างคีย์นี้ไม่ได้เป็นเจ้าของหรือผู้จัดการที่ยังใช้งานอยู่แล้ว | สร้างคีย์ใหม่ขณะเข้าสู่ระบบด้วยบัญชีเจ้าของหรือผู้จัดการที่ยังใช้งานอยู่ |
| 429 | RATE_LIMIT_EXCEEDED | error.details.code | คีย์นี้ส่งคำขอเกินโควตาของช่วงเวลานั้น | รอตามจำนวนวินาทีใน header Retry-After แล้วลองใหม่พร้อมสุ่มระยะเวลา |
| 409 | AMOUNT_MISMATCH | error.details.code | ยอดที่ส่งมาไม่ตรงกับยอดที่รายการนี้แบ่งได้ คือยอดสุทธิหักเงินคืนที่ยืนยันแล้ว | ไม่ต้องส่ง amount หรือส่งค่าตาม error.details.expected_amount |
| 409 | REFUND_IN_PROGRESS | error.details.code | รายการนี้มีการคืนเงินที่รอดำเนินการอยู่ หรือมีการคืนเงินบางส่วนจากคำสั่งซื้อแล้ว | คืนเงินส่วนที่เหลือจากคำสั่งซื้อ หรือรอให้การคืนเงินที่ค้างอยู่เสร็จก่อน |
| 409 | REFUND_EXCEEDS_AMOUNT | error.details.code | ยอดคืนเงินมากกว่ายอดที่ยังคืนได้ของรายการนี้ | คืนเงินได้ไม่เกินยอดคงเหลือที่ error.message ระบุ |
| 400 | WEBHOOK_URL_NOT_ALLOWED | error.details.code | URL ของ webhook ชี้ไปยังที่อยู่ภายในหรือเครือข่ายส่วนตัว | ใช้ URL แบบ HTTPS ที่เข้าถึงได้สาธารณะ error.details.reason บอกเหตุผลที่ถูกปฏิเสธ |
| 409 | PAYMENT_ALREADY_PAID | error.details.code | รายการนี้ได้รับเงินแล้ว จึงยกเลิกไม่ได้ error.details มี intent_id และ status | ห้ามทิ้งรายการนี้ ให้ส่งมอบสินค้า หรือคืนเงินผ่าน POST /v1/platform/payments/:id/refund |
| 409 | PAYMENT_IN_PROGRESS | error.details.code | พาร์ตเนอร์กำลังดำเนินการชำระเงินนี้อยู่ หรือ PAYDY กันรายการไว้ตรวจสอบ จึงยังยกเลิกไม่ได้ | ยังไม่ต้องทำอะไร รอ webhook payment.paid, payment.failed หรือ payment.expired บอกผล |
| 409 | PAYMENT_DISPUTED | error.details.code | รายการนี้มีข้อพิพาทหรือการเรียกเงินคืน (chargeback) ที่ยังเปิดอยู่ จึงยังคืนเงินไม่ได้ error.details มี intent_id และ dispute_id | รอ webhook payment.dispute_closed ถ้าแพ้ข้อพิพาท PAYDY จะบันทึกเงินที่ออกไปเป็นการคืนเงินและส่ง payment.refunded (reason chargeback) |