ข้ามไปยังเนื้อหาหลัก
ศูนย์ช่วยเหลือ

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. 1เข้าสู่ระบบ Merchant Dashboard
  2. 2ไปที่เมนู Developer → API Keys
  3. 3คลิก "สร้าง API Key" เลือก scope ที่ระบบของคุณต้องใช้ (เช่น payment_links:write) แล้วคัดลอกคีย์ — คีย์แสดงเพียงครั้งเดียว
  4. 4เก็บ Key ไว้อย่างปลอดภัย ห้ามนำใส่ Source Code

การตั้งค่า Webhook

  1. 1ไปที่เมนู Developer → Webhooks
  2. 2คลิก "เพิ่ม Endpoint" ระบุ URL แบบ HTTPS
  3. 3เลือก Events ที่ต้องการรับ
  4. 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รหัสฟิลด์หมายความว่าอะไรแก้อย่างไร
400BAD_REQUESTerror.codeคำขอผิดรูปแบบ หรือมีฟิลด์ที่ไม่ผ่านการตรวจ error.message จะระบุกฎที่ไม่ผ่านทุกข้อแก้ฟิลด์ตามที่ error.message ระบุ แล้วส่งใหม่
401UNAUTHORIZEDerror.codeไม่มีข้อมูลยืนยันตัวตนที่ใช้ได้ เช่น ไม่มี header Authorization หรือคีย์หรือเซสชันใช้ไม่ได้อ่าน error.details.code เพื่อดูสาเหตุที่แน่ชัด (แถว API_KEY_… ด้านล่าง)
403FORBIDDENerror.codeข้อมูลยืนยันตัวตนถูกต้อง แต่ไม่มีสิทธิ์ทำสิ่งนี้ เช่น คีย์ไม่มี scope ที่ต้องใช้ ผูกกับร้านอื่น หรือบทบาทในทีมของคุณเรียก route นี้ไม่ได้อ่าน error.details.code · ถ้าเป็นเรื่องบทบาท ให้เจ้าของบัญชีเปลี่ยนให้ในหน้าตั้งค่าทีม
404NOT_FOUNDerror.codeไม่มี id นี้ หรือเป็นของร้านอื่นตรวจ ULID และยืนยันว่าเรียกในสภาพแวดล้อมเดียวกับที่สร้างมัน
409CONFLICTerror.codeทรัพยากรอยู่ในสถานะที่ทำคำสั่งนี้ไม่ได้ หรือเป็นคำขอซ้ำกับที่ทำไปแล้วอ่าน error.details.code ดึงข้อมูลทรัพยากร แล้วทำต่อตามสถานะปัจจุบัน
410GONEerror.codeendpoint หรือทรัพยากรนี้ถูกยกเลิกแล้วและจะไม่กลับมาใช้ทางแทนที่ error.message ระบุ
422VALIDATION_ERRORerror.codeคำขอรูปแบบถูกต้อง แต่ API ประมวลผลตามที่ส่งมาไม่ได้อ่าน error.message และ error.details ว่าต้องแก้อะไร
429RATE_LIMITEDerror.codeIP หรือผู้ใช้ของคุณส่งคำขอเกินโควตาของช่วงเวลานั้นหยุดรอพร้อมสุ่มระยะเวลา (jitter) แล้วลองใหม่
500INTERNAL_ERRORerror.codeเกิดข้อผิดพลาดฝั่งเรา · รหัส HTTP อื่นที่ไม่อยู่ในตารางนี้ก็ได้ INTERNAL_ERROR เช่นกันลองใหม่ด้วย Idempotency-Key เดิมแบบ exponential backoff และแจ้ง meta.path กับ meta.timestamp ให้ฝ่ายสนับสนุน
503SERVICE_UNAVAILABLEerror.codeสิ่งที่คำขอต้องใช้ยังไม่ได้ตั้งค่าหรือใช้งานไม่ได้ เช่น การส่ง SMS หรือพาร์ทเนอร์ชำระเงินอ่าน error.details.code แล้วลองใหม่ภายหลัง หรือให้เจ้าของบัญชีตั้งค่าส่วนที่ระบุให้เสร็จ
400IDEMPOTENCY_KEY_INVALIDerror.codeIdempotency-Key ไม่ได้อยู่ในรูป 8–64 ตัวอักษรของ [a-zA-Z0-9_-:]สร้างคีย์จาก ULID หรือ UUID โดยไม่มีวงเล็บหรือช่องว่าง
409IDEMPOTENCY_KEY_REUSEDerror.codeIdempotency-Key นี้เคยใช้กับเนื้อหาคำขอที่ต่างออกไปแล้วคำขอใหม่ให้ใช้คีย์ใหม่ · ถ้าส่งเนื้อหาเดิมทุกตัวอักษร จะได้คำตอบเดิมกลับมา
409IDEMPOTENCY_KEY_IN_FLIGHTerror.codeคำขอเดียวกันที่ใช้คีย์นี้ยังประมวลผลไม่เสร็จรอสักครู่ แล้วลองใหม่ด้วยคีย์เดิม
401API_KEY_INVALIDerror.details.codeค่า bearer ไม่ใช่คีย์ของ PAYDY (epk_test_… หรือ epk_live_…) หรือไม่ตรงกับคีย์ใดเลยคัดลอกคีย์ทั้งหมดใหม่ — คีย์แสดงเพียงครั้งเดียวตอนสร้าง
401API_KEY_REVOKEDerror.details.codeคีย์ถูกยกเลิกแล้ว โดยทีมของคุณ หรือโดย PAYDY เพราะเป็นคีย์ที่สร้างก่อนระบบมี scope และไม่เคยใช้งานได้สร้างคีย์ใหม่พร้อม scope ที่ต้องใช้
401API_KEY_EXPIREDerror.details.codeคีย์เลยวันหมดอายุแล้วสร้างคีย์ใหม่ คีย์ที่หมดอายุไม่ถูกเปิดใช้ซ้ำ
401API_KEY_UNVERIFIABLEerror.details.codeระบบนี้ตรวจคีย์ไม่ได้ในขณะนี้ลองใหม่ภายหลัง ถ้ายังเป็นอยู่ ให้ติดต่อฝ่ายสนับสนุนพร้อม meta.path และ meta.timestamp
401API_KEY_NOT_ACCEPTED_HEREerror.details.coderoute นี้ไม่รับ API key · รับเฉพาะ route ที่อยู่ในเอกสารนี้เรียก route ที่มีในเอกสาร หรือทำรายการนี้จากแดชบอร์ด
403MERCHANT_SUSPENDEDerror.details.codeบัญชีร้านค้าถูกระงับติดต่อฝ่ายสนับสนุนของ PAYDY
403API_KEY_MODE_MISMATCHerror.details.codeส่งคีย์ทดสอบไปที่ระบบจริง หรือส่งคีย์จริงไปที่ Sandboxส่งคีย์ epk_test_… ไปที่ api-sandbox.paydy.ai และคีย์ epk_live_… ไปที่ api.paydy.ai
403API_KEY_GATEWAY_MODE_MISMATCHerror.details.codeโหมดของคีย์ไม่ตรงกับเกตเวย์ชำระเงินที่เปิดใช้อยู่ในระบบนี้ติดต่อฝ่ายสนับสนุน เกตเวย์ของระบบนี้ต้องตั้งเป็นโหมดเดียวกัน
403API_KEY_SCOPE_MISSINGerror.details.codeคีย์ไม่มี scope ที่ route นี้ต้องใช้สร้างคีย์ที่มี scope นั้น — แต่ละ endpoint แสดง scope ที่ต้องใช้ไว้
403API_KEY_STORE_BOUNDerror.details.codeใช้คีย์ที่ผูกกับร้านเดียว เรียก route ที่ทำงานกับทั้งบัญชีร้านค้าใช้คีย์แบบทั้งบัญชีสำหรับ route นี้
403API_KEY_STORE_MISMATCHerror.details.codeคีย์ที่ผูกกับร้านหนึ่ง อ้างถึงข้อมูลของร้านอื่นใช้คีย์ของร้านนั้น หรือคีย์แบบทั้งบัญชี
403API_KEY_CREATOR_INACTIVEerror.details.codeสมาชิกทีมที่สร้างคีย์นี้ไม่ได้เป็นเจ้าของหรือผู้จัดการที่ยังใช้งานอยู่แล้วสร้างคีย์ใหม่ขณะเข้าสู่ระบบด้วยบัญชีเจ้าของหรือผู้จัดการที่ยังใช้งานอยู่
429RATE_LIMIT_EXCEEDEDerror.details.codeคีย์นี้ส่งคำขอเกินโควตาของช่วงเวลานั้นรอตามจำนวนวินาทีใน header Retry-After แล้วลองใหม่พร้อมสุ่มระยะเวลา
409AMOUNT_MISMATCHerror.details.codeยอดที่ส่งมาไม่ตรงกับยอดที่รายการนี้แบ่งได้ คือยอดสุทธิหักเงินคืนที่ยืนยันแล้วไม่ต้องส่ง amount หรือส่งค่าตาม error.details.expected_amount
409REFUND_IN_PROGRESSerror.details.codeรายการนี้มีการคืนเงินที่รอดำเนินการอยู่ หรือมีการคืนเงินบางส่วนจากคำสั่งซื้อแล้วคืนเงินส่วนที่เหลือจากคำสั่งซื้อ หรือรอให้การคืนเงินที่ค้างอยู่เสร็จก่อน
409REFUND_EXCEEDS_AMOUNTerror.details.codeยอดคืนเงินมากกว่ายอดที่ยังคืนได้ของรายการนี้คืนเงินได้ไม่เกินยอดคงเหลือที่ error.message ระบุ
400WEBHOOK_URL_NOT_ALLOWEDerror.details.codeURL ของ webhook ชี้ไปยังที่อยู่ภายในหรือเครือข่ายส่วนตัวใช้ URL แบบ HTTPS ที่เข้าถึงได้สาธารณะ error.details.reason บอกเหตุผลที่ถูกปฏิเสธ
409PAYMENT_ALREADY_PAIDerror.details.codeรายการนี้ได้รับเงินแล้ว จึงยกเลิกไม่ได้ error.details มี intent_id และ statusห้ามทิ้งรายการนี้ ให้ส่งมอบสินค้า หรือคืนเงินผ่าน POST /v1/platform/payments/:id/refund
409PAYMENT_IN_PROGRESSerror.details.codeพาร์ตเนอร์กำลังดำเนินการชำระเงินนี้อยู่ หรือ PAYDY กันรายการไว้ตรวจสอบ จึงยังยกเลิกไม่ได้ยังไม่ต้องทำอะไร รอ webhook payment.paid, payment.failed หรือ payment.expired บอกผล
409PAYMENT_DISPUTEDerror.details.codeรายการนี้มีข้อพิพาทหรือการเรียกเงินคืน (chargeback) ที่ยังเปิดอยู่ จึงยังคืนเงินไม่ได้ error.details มี intent_id และ dispute_idรอ webhook payment.dispute_closed ถ้าแพ้ข้อพิพาท PAYDY จะบันทึกเงินที่ออกไปเป็นการคืนเงินและส่ง payment.refunded (reason chargeback)
API & Integration — ศูนย์ช่วยเหลือ PAYDY.ai · PAYDY.ai