ข้ามไปยังเนื้อหาหลัก

API v1 — เสถียร

คู่มือ REST API

Base URL เดียว ยืนยันตัวตนแบบ bearer โครงสร้างผลลัพธ์แบบเดียว และ endpoint เก้าตัวที่ครอบคลุมลิงก์ การเรียกเก็บเงิน การเคลื่อนเงิน ลูกค้า และการแบ่งเงิน ทุกอย่างในหน้านี้สร้างจากแคตาล็อกชุดเดียวกับคอนโซลใน sandbox

คีย์และสิทธิ์

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

marketing.docs.api.auth.keyIntro
HTTP
Authorization: Bearer epk_test_…   # https://api-sandbox.paydy.ai/v1
Authorization: Bearer epk_live_…   # https://api.paydy.ai/v1

Sandbox (ทดสอบ)

https://api-sandbox.paydy.ai/v1epk_test_…

Production (ใช้งานจริง)

https://api.paydy.ai/v1epk_live_…
  • คีย์ทดสอบขึ้นต้นด้วย epk_test_ ใช้ได้เฉพาะกับ sandbox base URL (ข้อมูล sandbox และ gateway sandbox ไม่มีเงินจริง) คีย์ใช้งานจริงขึ้นต้นด้วย epk_live_ ใช้ได้เฉพาะ production คีย์ที่ส่งไปผิดสภาพแวดล้อมจะได้ 403 API_KEY_MODE_MISMATCH
  • คีย์แต่ละตัวมี scope หนึ่งตัวต่อกลุ่ม endpoint ได้แก่ payment_links:write, transactions:read, refunds:write, customers:write, settlements:read, subscriptions:write, split_payments:write, webhooks:write ทุก endpoint ด้านล่างแสดง scope ที่ต้องใช้ คีย์ที่ไม่มี scope นั้นจะได้ 403 API_KEY_SCOPE_MISSING
  • คีย์เป็นของบัญชีร้านค้าของคุณ และผูกกับร้านใดร้านหนึ่งได้ คีย์ที่ผูกกับร้านเรียกได้เฉพาะลิงก์ชำระเงินและรายการของร้านนั้น ส่วน endpoint ที่ทำงานกับทั้งบัญชี (ลูกค้า การโอนเงิน สมาชิกรายรอบ การส่ง webhook ซ้ำ) จะปฏิเสธด้วย 403 API_KEY_STORE_BOUND
  • การเรียกด้วยคีย์ถือว่าทำในนามสมาชิกทีมที่สร้างคีย์ หากคนนั้นถูกระงับ หรือไม่ได้เป็นเจ้าของหรือผู้จัดการแล้ว คีย์จะใช้ไม่ได้ (403 API_KEY_CREATOR_INACTIVE)
  • จำกัดอัตราการเรียกนับแยกตามคีย์ คือ 100 ครั้งต่อ 60 วินาที ทุกคำตอบมี X-RateLimit-Limit และ X-RateLimit-Remaining เมื่อเกินจะได้ 429 พร้อม Retry-After
  • คีย์ที่ถูกเพิกถอนหรือหมดอายุจะได้ 401 คอนโซลแสดงเวลาและ IP ที่ใช้คีย์ล่าสุด หากต้องการเปลี่ยนคีย์ ให้สร้างคีย์ใหม่ นำไปใช้งาน แล้วจึงเพิกถอนคีย์เดิม
  • มีเฉพาะ endpoint ในเอกสารนี้ที่รับ API key route อื่นของ API คอนโซลยังรับเฉพาะ session ที่เข้าสู่ระบบ และปฏิเสธคีย์ด้วย 401 API_KEY_NOT_ACCEPTED_HERE
  • คีย์เป็นความลับฝั่งเซิร์ฟเวอร์ คีย์ที่หลุดไปอยู่ในเบราว์เซอร์ แอป หรือ repository สาธารณะถือว่ารั่วแล้ว ให้เพิกถอนทันที
สร้างคีย์ในคอนโซล

ส่ง Idempotency-Key ทุกคำขอที่เคลื่อนเงิน

Idempotency-Key ต้องยาว 8–64 ตัวอักษร ผลลัพธ์ครั้งแรกถูกแคช 24 ชั่วโมง และจะถูกส่งกลับเหมือนเดิมหากคุณส่งคีย์เดิมอีกครั้ง ดูกฎแบบละเอียด →

โครงสร้าง

โครงสร้างผลลัพธ์

มีแค่สามรูปแบบ: ทรัพยากรเดี่ยว คอลเล็กชันที่มี meta หรือข้อผิดพลาด ให้ตรวจ success ก่อน แล้วอ่าน data หรือ error.code
application/json
// single resource
{ "success": true, "data": { /* … */ } }

// collection
{
  "success": true,
  "data": [ /* … */ ],
  "meta": { "page": 1, "per_page": 20, "total": 142, "total_pages": 8 }
}

// error
{ "success": false, "error": { "code": "NOT_FOUND", "message": "…" } }

คอลเล็กชัน

การแบ่งหน้าและการกรอง

Endpoint แบบรายการใช้การแบ่งหน้าและคืน meta ที่มียอดรวม คุณจึงสร้างตัวแบ่งหน้าได้โดยไม่ต้องเรียกซ้ำ
HTTP
GET https://api-sandbox.paydy.ai/v1/merchant/transactions
  ?status=succeeded
  &from=2026-10-01
  &to=2026-10-14
  &page=2
  &per_page=50
  &sort=-created_at
page
เลขหน้าเริ่มจาก 1 ค่าเริ่มต้นคือ 1
per_page
จำนวนรายการต่อหน้า สูงสุด 100 ค่าเริ่มต้น 20
sort
ชื่อฟิลด์ ใส่ “-” นำหน้าเพื่อเรียงจากมากไปน้อย
from / to
ช่วงวันที่แบบ ISO 8601 รวมปลายทั้งสองข้าง อิงจาก created_at

คู่มือ Endpoint

การรับชำระเงิน

สร้างลิงก์ชำระเงินแล้วส่ง URL ให้ผู้ซื้อ — ผู้ซื้อเลือกช่องทางชำระบนหน้า checkout

คู่มือ Endpoint

การเคลื่อนเงิน

ดูว่าเกิดอะไรขึ้น คืนเงินได้ และตรวจว่ามีเงินเข้าบัญชีเท่าไร
GET

/merchant/transactions/{id}

owner · manager · cashier · viewerสิทธิ์ (scope) ของ API key: transactions:read

ดึงข้อมูลธุรกรรม

อ่านธุรกรรมหนึ่งรายการของคุณ พร้อมค่าธรรมเนียม ยอดสุทธิ ช่องทางชำระ ไทม์ไลน์ และรายการคืนเงินผ่านพาร์ตเนอร์ของธุรกรรมนั้น

API key ที่ผูกกับร้านเดียวเรียกได้เฉพาะข้อมูลของร้านนั้น

พารามิเตอร์

GET /merchant/transactions/{id} — พารามิเตอร์
ชื่อตำแหน่งชนิดจำเป็นคำอธิบาย
idpathstringจำเป็นTransaction ULID.

ตัวอย่างโค้ด

cURL
curl -X GET https://api-sandbox.paydy.ai/v1/merchant/transactions/01JQ8W4M3K1L2N5P6Q7R8S9T0U \
  -H "Authorization: Bearer $PAYDY_API_KEY" \

ตัวอย่างผลลัพธ์200

application/json
{
  "success": true,
  "data": {
    "id": "01JQ8W4M3K1L2N5P6Q7R8S9T0U",
    "ref": "TXN-2026-0001842",
    "amount": 1290,
    "fee": 19.35,
    "net": 1270.65,
    "payment_method": "promptpay",
    "status": "success",
    "settled_at": "2026-10-14T09:14:02.000Z",
    "metadata": {},
    "refund_reserved_amount": 0,
    "refunds": []
  }
}
POST

/merchant/transactions/{id}/refund

Idempotentowner · managerสิทธิ์ (scope) ของ API key: refunds:write

คืนเงินธุรกรรม

คืนเงินทั้งจำนวนหรือบางส่วนผ่านพาร์ตเนอร์ที่รับเงินไว้ สถานะจะเป็น pending จนกว่าพาร์ตเนอร์ยืนยัน และรายการที่พาร์ตเนอร์คืนไม่ได้จะถูกปฏิเสธ

API key ที่ผูกกับร้านเดียวเรียกได้เฉพาะข้อมูลของร้านนั้น

พารามิเตอร์

POST /merchant/transactions/{id}/refund — พารามิเตอร์
ชื่อตำแหน่งชนิดจำเป็นคำอธิบาย
idpathstringจำเป็นTransaction ULID to refund.
amountbodynumberไม่บังคับBaht to refund, up to 2 decimals. Omit for a full refund.
reasonbodystringไม่บังคับFree text, max 500 chars, kept on the audit trail.
confirm_externalbodybooleanไม่บังคับOnly for money PAYDY never collected (POS cash, slip transfer): you state you returned it yourself.

ตัวอย่างโค้ด

cURL
curl -X POST https://api-sandbox.paydy.ai/v1/merchant/transactions/01JQ8W4M3K1L2N5P6Q7R8S9T0U/refund \
  -H "Authorization: Bearer $PAYDY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_refundtransaction_001" \
  -d '{
       "amount": 290,
       "reason": "Customer returned 1 of 2 items"
     }'

ตัวอย่างผลลัพธ์201

application/json
{
  "success": true,
  "data": {
    "id": "01JQ8W4M3K1L2N5P6Q7R8S9T0U",
    "amount": 1290,
    "status": "success",
    "refund": {
      "status": "pending",
      "amount": 290
    },
    "replayed": false
  }
}
GET

/merchant/settlement

owner · manager · cashier · viewerสิทธิ์ (scope) ของ API key: settlements:read

รายการ Settlement

แสดงรอบ settlement ล่าสุดของคุณ พร้อมยอดรวม MDR ค่าธรรมเนียม ยอดสุทธิ และผลกระทบยอดของแต่ละรอบ — ตัวเลขที่ฝ่ายบัญชีใช้เทียบกับ statement

ทำงานกับทั้งบัญชีร้านค้า — API key ที่ผูกกับร้านเดียวจะถูกปฏิเสธ

พารามิเตอร์

GET /merchant/settlement — พารามิเตอร์
ชื่อตำแหน่งชนิดจำเป็นคำอธิบาย
statusquerystringไม่บังคับpending | processing | completed | failed

ตัวอย่างโค้ด

cURL
curl -X GET https://api-sandbox.paydy.ai/v1/merchant/settlement \
  -H "Authorization: Bearer $PAYDY_API_KEY" \

ตัวอย่างผลลัพธ์200

application/json
{
  "success": true,
  "data": [
    {
      "id": "01JQ8X9ZTTMN4P5Q6R7S8T9U0V",
      "settle_ref": "STL-2026-10-13-0001",
      "cycle": "T1",
      "txn_count": 184,
      "gross_amount": 48215,
      "mdr_total": 723.22,
      "fee_total": 0,
      "net_amount": 47491.78,
      "bank_code": "KBANK",
      "status": "completed",
      "scheduled_at": "2026-10-14T03:00:00.000Z",
      "processed_at": "2026-10-14T03:00:12.000Z"
    }
  ]
}

คู่มือ Endpoint

ลูกค้า

ทำให้สมุดลูกค้าตรงกับระบบของคุณเอง
POST

/merchant/customers

Idempotentowner · manager · cashier · viewerสิทธิ์ (scope) ของ API key: customers:write

สร้างลูกค้า

เพิ่มลูกค้าเข้าสมุดลูกค้าของคุณ — ชื่อ อีเมล เบอร์โทร ช่องทางที่มา และแท็กของคุณเอง

ทำงานกับทั้งบัญชีร้านค้า — API key ที่ผูกกับร้านเดียวจะถูกปฏิเสธ

พารามิเตอร์

POST /merchant/customers — พารามิเตอร์
ชื่อตำแหน่งชนิดจำเป็นคำอธิบาย
namebodystringไม่บังคับDisplay name, max 255 chars.
emailbodystringไม่บังคับA valid e-mail address.
phonebodystringไม่บังคับMax 20 chars, e.g. 0812345678.
channel_sourcebodystringไม่บังคับline | facebook | tiktok | instagram | web | pos | import. Default web.
tagsbodystring[]ไม่บังคับYour own labels.

ตัวอย่างโค้ด

cURL
curl -X POST https://api-sandbox.paydy.ai/v1/merchant/customers \
  -H "Authorization: Bearer $PAYDY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_createcustomer_001" \
  -d '{
       "name": "สมชาย ใจดี",
       "email": "somchai@example.com",
       "phone": "0812345678",
       "tags": [
         "vip"
       ]
     }'

ตัวอย่างผลลัพธ์201

application/json
{
  "success": true,
  "data": {
    "id": "01JQ8XB7N8P9Q0R1S2T3U4V5W6",
    "name": "สมชาย ใจดี",
    "email": "somchai@example.com",
    "phone": "0812345678",
    "channel_source": "web",
    "rfm_segment": "new",
    "total_orders": 0,
    "total_spent": 0,
    "ltv": 0,
    "tags": [
      "vip"
    ],
    "marketing_consent": false,
    "created_at": "2026-10-14T09:33:02.000Z"
  }
}

คู่มือ Endpoint

ขั้นสูง

เรียกเก็บตามรอบ แบ่งยอดเงิน และส่ง webhook ซ้ำ — endpoint ที่คุณจะใช้เมื่อพื้นฐานขึ้นระบบแล้ว
POST

/merchant/subscriptions

Idempotentowner · manager · cashier · viewerสิทธิ์ (scope) ของ API key: subscriptions:write

สร้าง Subscription

เริ่มการเรียกเก็บตามรอบให้ลูกค้าของคุณ โทเคนบัตรจะถูกแลกเป็นบัตรที่บันทึกไว้ที่ Omise ก่อนสร้าง subscription และกำหนดช่วงทดลองเพื่อเลื่อนการตัดเงินครั้งแรกได้

ทำงานกับทั้งบัญชีร้านค้า — API key ที่ผูกกับร้านเดียวจะถูกปฏิเสธ

พารามิเตอร์

POST /merchant/subscriptions — พารามิเตอร์
ชื่อตำแหน่งชนิดจำเป็นคำอธิบาย
customer_idbodystringจำเป็นYour customer (ULID).
namebodystringจำเป็นWhat the customer sees, max 255 chars.
amountbodynumberจำเป็นBaht per period, up to 2 decimals, at least 1.
intervalbodystringจำเป็นdaily | weekly | monthly | yearly
interval_countbodyintegerไม่บังคับEvery N intervals. Default 1.
card_tokenbodystringจำเป็นOne-time Omise.js card token (tokn_…), exchanged for a saved card before the subscription exists.
trial_daysbodyintegerไม่บังคับDays with no charge.
plan_slugbodystringไม่บังคับLinks to a plan you defined under subscriptions/plan-definitions.

ตัวอย่างโค้ด

cURL
curl -X POST https://api-sandbox.paydy.ai/v1/merchant/subscriptions \
  -H "Authorization: Bearer $PAYDY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_createsubscription_001" \
  -d '{
       "customer_id": "01JQ8XB7N8P9Q0R1S2T3U4V5W6",
       "name": "Growth plan",
       "amount": 890,
       "interval": "monthly",
       "card_token": "tokn_test_5xyz",
       "trial_days": 14
     }'

ตัวอย่างผลลัพธ์201

application/json
{
  "success": true,
  "data": {
    "id": "01JQ8XC2D3E4F5G6H7J8K9L0M1",
    "customer_id": "01JQ8XB7N8P9Q0R1S2T3U4V5W6",
    "name": "Growth plan",
    "amount": 890,
    "interval": "monthly",
    "interval_count": 1,
    "status": "active",
    "trial_end": "2026-10-28T09:35:00.000Z",
    "next_billing_at": "2026-10-28T09:35:00.000Z",
    "created_at": "2026-10-14T09:35:00.000Z"
  }
}
POST

/merchant/split-payments/execute

Idempotentowner · manager · cashier · viewerสิทธิ์ (scope) ของ API key: split_payments:write

แบ่งยอดเงิน

แบ่งยอดเงินตามกฎที่บันทึกไว้ หรือตามรายการแบบยอดคงที่/เปอร์เซ็นต์สูงสุด 50 รายการ และบันทึกผูกกับธุรกรรมของคุณได้

API key ที่ผูกกับร้านเดียวเรียกได้เฉพาะข้อมูลของร้านนั้น

พารามิเตอร์

POST /merchant/split-payments/execute — พารามิเตอร์
ชื่อตำแหน่งชนิดจำเป็นคำอธิบาย
transaction_idbodystringจำเป็นOne of YOUR transactions in status success or partially_refunded; another merchant’s id answers like an unknown one.
amountbodynumberไม่บังคับOptional cross-check. The server splits the transaction’s own amount; a different value is refused with 409 AMOUNT_MISMATCH and nothing is written.
rule_idbodystringไม่บังคับA split rule you saved under split-payments/rules.
itemsbodyobject[]ไม่บังคับInstead of rule_id: 1–50 of { account_label, account_type: merchant|bank_account|platform|vendor, account_ref?, split_type: fixed|percentage, split_value }.

ตัวอย่างโค้ด

cURL
curl -X POST https://api-sandbox.paydy.ai/v1/merchant/split-payments/execute \
  -H "Authorization: Bearer $PAYDY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_splitpayment_001" \
  -d '{
       "transaction_id": "01JQ8W4M3K1L2N5P6Q7R8S9T0U",
       "items": [
         {
           "account_label": "Main shop",
           "account_type": "merchant",
           "split_type": "percentage",
           "split_value": 60
         },
         {
           "account_label": "Partner studio",
           "account_type": "vendor",
           "split_type": "percentage",
           "split_value": 30
         },
         {
           "account_label": "Courier",
           "account_type": "vendor",
           "split_type": "fixed",
           "split_value": 45
         }
       ]
     }'

ตัวอย่างผลลัพธ์201

application/json
{
  "success": true,
  "data": {
    "executions": 3,
    "amount": 1270.65,
    "replayed": false,
    "breakdown": [
      {
        "account_label": "Main shop",
        "account_type": "merchant",
        "split_type": "percentage",
        "split_value": 60,
        "amount": 735.39
      },
      {
        "account_label": "Partner studio",
        "account_type": "vendor",
        "split_type": "percentage",
        "split_value": 30,
        "amount": 367.7
      },
      {
        "account_label": "Courier",
        "account_type": "vendor",
        "split_type": "fixed",
        "split_value": 45,
        "amount": 45
      }
    ]
  }
}
POST

/merchant/webhooks/deliveries/{id}/retry

Idempotentowner · manager · cashier · viewerสิทธิ์ (scope) ของ API key: webhooks:write

ส่ง Webhook ซ้ำ

ส่งอีเวนต์ webhook ที่เก็บไว้เข้าคิวอีกครั้งไปยัง endpoint เดิม พร้อมลายเซ็นใหม่

ทำงานกับทั้งบัญชีร้านค้า — API key ที่ผูกกับร้านเดียวจะถูกปฏิเสธ

พารามิเตอร์

POST /merchant/webhooks/deliveries/{id}/retry — พารามิเตอร์
ชื่อตำแหน่งชนิดจำเป็นคำอธิบาย
idpathstringจำเป็นDelivery id from the webhook event log.

ตัวอย่างโค้ด

cURL
curl -X POST https://api-sandbox.paydy.ai/v1/merchant/webhooks/deliveries/01JQ8W4M3K1L2N5P6Q7R8S9T0U/retry \
  -H "Authorization: Bearer $PAYDY_API_KEY" \
  -H "Idempotency-Key: idem_replaywebhook_001" \

ตัวอย่างผลลัพธ์201

application/json
{
  "success": true,
  "data": {
    "queued": true,
    "delivery_id": "01JQ8XG1H2J3K4L5M6N7P8Q9R0"
  }
}

ความเสถียร

การกำหนดเวอร์ชัน

สัญญาที่คุณพัฒนาตามวันนี้จะยังใช้ได้ต่อไป นี่คือสิ่งที่เราจะเปลี่ยนและไม่เปลี่ยนใต้มือคุณ
  • เวอร์ชันอยู่ในเส้นทาง — ทุก endpoint อยู่ใต้ /v1 การเปลี่ยนที่กระทบจะออกเป็น /v2 ไม่ใช่แก้เงียบ ๆ
  • ฟิลด์ใหม่เพิ่มเข้ามาเท่านั้น — เราอาจเพิ่มฟิลด์ในผลลัพธ์ได้ตลอด ให้ parse อย่างปลอดภัยและข้ามฟิลด์ที่ไม่รู้จัก
  • การเลิกใช้จะแจ้งล่วงหน้า — ฟิลด์หรือ endpoint ที่จะเลิกใช้จะถูกทำเครื่องหมายในผลลัพธ์และ changelog ก่อนถูกถอด
  • ทุกอย่างมีบันทึก — การเปลี่ยนแปลงของ API ประกาศใน changelog ก่อนเผยแพร่
API Reference — เอกสารนักพัฒนา PAYDY.ai · PAYDY.ai