API Documentation

PlernPay Payment API — รับชำระเงินผ่าน PromptPay & TrueMoney Wallet อัตโนมัติ

NEW FEATURE2026-09-28

รองรับ TrueMoney Voucher (ซองของขวัญ / อั่งเปา)

เปิดตัว API ใหม่ POST /v1/topup/truemoney ให้ระบบสามารถดึงเงินจากซองของขวัญ TrueMoney เข้ากระเป๋าอัตโนมัติ พร้อมระบบป้องกันการใช้ซองซ้ำและข้าม Cloudflare WAF สมบูรณ์แบบ

Endpoint: POST /v1/topup/truemoney ส่งแค่ voucher_url ก็ขึ้นเงินได้ทันที
ตั้งค่าเบอร์ปลายทาง: กำหนดได้ผ่านฟิลด์ phone หรือตั้งค่าเบอร์ TrueMoney เริ่มต้นของ Application ในระบบ PlernPay Admin
Error Code ครอบคลุม: รองรับ Error 1040–1049 สำหรับแจ้งสถานะซองหมดอายุ, ซองถูกใช้แล้ว, ซองไม่ถูกต้อง ฯลฯ

Base URL

https://api.plernpay.com

Authentication

ใช้ 2 key — Client ID + Client Secret

Client ID (pi_xxx)

เปิดเผยได้ — ใช้ฝั่ง frontend (SSE stream)

Client Secret (ps_xxx)

ห้ามเปิดเผย — ใช้ฝั่ง server เท่านั้น

ตัวอย่างการเรียก API PromptPay:

curl -X POST https://api.plernpay.com/v1/topup/create \
  -H "X-Client-ID: pi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Client-Secret: ps_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "memo": "order:12345"}'

สถานะ

pendingรอชำระเงิน

confirmedชำระเงินสำเร็จ

expiredหมดอายุ

cancelledถูกยกเลิก

Rate Limit

30 requests / นาที ต่อ API Key (เริ่มต้น) — ติดต่อแอดมินเพื่อเพิ่ม limit

หากเกิน rate limit แอปจะถูก deactivate อัตโนมัติ ทันที — ต้องติดต่อแอดมินเพื่อเปิดใช้งานอีกครั้ง

Endpoints

PromptPay API

รายการ API สำหรับสร้าง QR Code รับชำระเงิน และตรวจสอบการโอนเงินเข้า PromptPay

สร้าง QR Code สำหรับรับชำระเงินผ่านระบบ PromptPay

Headers

X-Client-ID: pi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Client-Secret: ps_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Parameters

Field	Type	Required	Description
`amount`	number	required	จำนวนเงิน (1 - 999,999)
`memo`	string	optional	หมายเหตุ เช่น username, order_id (สูงสุด 255 ตัวอักษร)

Request Body Example

{
  "amount": 100,
  "memo": "user:john_doe"
}

Response Fields

Field	Type	Description
`code`	number	200
`ref`	string	Reference ID สำหรับเช็คสถานะ
`amount`	number	จำนวนเงินที่ขอ
`unique_amount`	number	ยอดจริงที่ต้องโอน (เพิ่มสตางค์สุ่ม)
`qr_code`	string	PromptPay QR payload สำหรับสร้าง QR
`promptpay_id`	string	หมายเลข PromptPay ปลายทาง
`memo`	string \| null	หมายเหตุที่ส่งมา
`status`	string	"pending"
`expires_at`	string	เวลาหมดอายุ 15 นาทีหลังสร้างรายการ (ISO 8601)
`expires_in`	number	วินาทีที่เหลือก่อนหมดอายุ (เริ่มต้น 900 วินาที)

Response Example

{
  "code": 200,
  "ref": "PLERNPAY-20260403-A001-7F2B",
  "amount": 100,
  "unique_amount": 100.47,
  "qr_code": "00020101021129370016...",
  "promptpay_id": "0891234567",
  "memo": "user:john_doe",
  "status": "pending",
  "expires_at": "2026-04-03T10:15:00.000Z",
  "expires_in": 900
}

Error Codes

PromptPay Errors (13)

ทุก error response ส่งรูปแบบ code + error

ตัวอย่าง Error Response:

{
  "code": 1012,
  "error": "Insufficient balance",
  "balance": 0.00
}

Code	HTTP	Message & Explanation
`1000`	401	Missing credentials (ไม่ได้ส่ง X-Client-ID หรือ X-Client-Secret)
`1001`	401	Invalid credentials (Client ID หรือ Secret ไม่ถูกต้อง)
`1002`	403	Application inactive (แอปพลิเคชันถูกระงับการใช้งาน)
`1003`	403	Account inactive (บัญชีผู้ใช้ถูกระงับ)
`1010`	400	Invalid amount (จำนวนเงินไม่ถูกต้อง ต้องอยู่ระหว่าง 1 - 999,999)
`1011`	400	PromptPay ID not configured (ยังไม่ได้ตั้งค่าเบอร์ PromptPay ในระบบ)
`1012`	402	Insufficient balance (ยอดเงินเครดิตในระบบไม่พอหักค่าบริการ)
`1013`	400	No unique amount available (ยอดเศษสตางค์ไม่ว่างชั่วคราว — กรุณาลองใหม่อีกครั้ง)
`1020`	404	Topup not found (ไม่พบรายการชำระเงิน)
`1021`	400	Topup not pending (สถานะรายการไม่ใช่ pending เช่น หมดอายุแล้ว หรือ ได้รับเงินแล้ว)
`1022`	503	Bot not connected (บอทตรวจจับยอดเงินไม่ได้เชื่อมต่อ — กรุณาเริ่มบอทก่อนสร้าง QR)
`1030`	429	Rate limit exceeded (เกิน 30 requests/นาที แอปจะถูกระงับอัตโนมัติ)
`2001`	500	Internal error (ข้อผิดพลาดภายในระบบ)

Quick Start Guide

ตัวอย่างการเชื่อมต่อ PromptPay QR & Real-time Stream

// ========================================================
// ตัวอย่าง: รับชำระผ่าน PromptPay QR + Real-time Stream
// ========================================================

// 1. ฝั่ง Server (Node.js): สร้าง QR Code
const res = await fetch("https://api.plernpay.com/v1/topup/create", {
  method: "POST",
  headers: {
    "X-Client-ID": "pi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "X-Client-Secret": "ps_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 100, memo: "user:john_doe" }),
});
const { ref, qr_code, unique_amount } = await res.json();

// 2. ฝั่ง Frontend (Browser): ดักฟังผลการชำระเงิน Real-time
const events = new EventSource(
  `https://api.plernpay.com/v1/topup/${ref}/stream?client_id=pi_xxx`
);

events.onmessage = (e) => {
  const data = JSON.parse(e.data);

  if (data.status === "confirmed") {
    // จ่ายเงินสำเร็จ!
    console.log(`ชำระสำเร็จ ${data.amount} บาท ผ่าน ${data.bank}`);
    events.close();
  }

  if (data.status === "expired") {
    // หมดอายุ — ให้ลูกค้าสร้าง QR ใหม่
    events.close();
  }
};