PayNex API Documentation

ติดตั้งระบบรับชำระเงิน PromptPay, Credit Card, e-Wallet ผ่าน API ของ PayNex — รองรับมาตรฐาน EMVCo และ ธปท.

สภาพแวดล้อม (Environments)

ระบบเปิด/ปิดโหมด Sandbox ผ่านตัวแปร SANDBOX_MODE — ตรวจสอบได้จาก GET /api/v1/config (คืน is_sandbox, charge_ttl_ms, promptpay_proxy)

Authentication

การสร้าง Charge ใช้ header X-Merchant-Id: {merchant_id} เพื่อระบุร้านค้า (เช่น mer_demo) — ไม่ใช้ Bearer Token

Webhook Secret สำหรับตรวจสอบ Signature เป็นคนละค่ากับ API Key — สร้างอัตโนมัติตอนกำหนด Webhook URL และดูได้จาก GET /api/v1/merchants/:id

Charges API — สร้างรายการชำระเงิน

สร้าง Dynamic QR Code สำหรับ PromptPay, รับชำระผ่าน Credit Card, หรือ e-Wallet

POST /api/v1/charges

สร้างรายการชำระเงินใหม่ — รองรับ PromptPay, Credit Card, Mobile Banking (ต้องส่ง header X-Merchant-Id)

Request Body

Response (201 Created)

curl https:///api/v1/charges \
  -H "X-Merchant-Id: mer_demo" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 350.00,
    "currency": "THB",
    "payment_method": "promptpay",
    "description": "Order #1234"
  }'

const axios = require('axios');

const { data } = await axios.post(
  'https:///api/v1/charges',
  { amount: 350.00, currency: 'THB', payment_method: 'promptpay' },
  { headers: { 'X-Merchant-Id': 'mer_demo' } }
);
console.log(data.id, data.status);

import requests

resp = requests.post(
    "https:///api/v1/charges",
    json={"amount": 350.00, "currency": "THB", "payment_method": "promptpay"},
    headers={"X-Merchant-Id": "mer_demo"}
)
print(resp.json()["id"])

$ch = curl_init("https:///api/v1/charges");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["X-Merchant-Id: mer_demo", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["amount" => 350.00, "currency" => "THB", "payment_method" => "promptpay"])
]);
$resp = curl_exec($ch);
curl_close($ch);

JSON Response

{
  "id": "chg_abc123...",
  "status": "PENDING",
  "amount": 350,
  "hosted_checkout_url": "/checkout.html?id=chg_abc123",
  "qr": { "emvco": "000201010212...", "expires_at": 1786000000000 },
  "qr_image_url": "/api/v1/charges/chg_abc123/qr-image",
  "fee_satang": 0,
  "mdr_rate_bps": 150
}

GET /api/v1/charges/:id

ตรวจสอบสถานะคำสั่งซื้อตาม Charge ID

curl https:///api/v1/charges/chg_abc123 \
  -H "X-Merchant-Id: mer_demo"

Webhooks & Event Notifications

ระบบจะส่ง HTTP POST ไปยัง Webhook URL เมื่อสถานะการชำระเงินเปลี่ยนแปลง — Event: charge.succeeded (ชำระสำเร็จ) และ charge.failed (ชำระไม่สำเร็จ)

Event Payload

POST https://your-server.com/webhook
X-Paynex-Timestamp: 1786000000000
X-Paynex-Signature: 5f4dcc3b5aa765d61d8327deb882cf99...

{
  "id": "chg_abc123",
  "event": "charge.succeeded",
  "charge_id": "chg_abc123",
  "status": "SUCCEEDED",
  "amount": 350,
  "currency": "THB",
  "reference": "order-1234",
  "ref_no": "TXN-20260808-001",
  "paid_at": "2026-08-08T07:23:45Z"
}

Signature Verification (HMAC SHA-256)

// Node.js — timestamp (epoch ms) + "." + raw body
const crypto = require('crypto');
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');
if (expected !== signature) throw new Error('Invalid signature');

Code Examples

ตัวอย่างโค้ดยิง API สร้าง PromptPay QR แบบหลายภาษา

curl -X POST https:///api/v1/charges \
  -H "X-Merchant-Id: mer_demo" \
  -H "Content-Type: application/json" \
  -d '{"amount":350,"currency":"THB","payment_method":"promptpay","description":"Order #1234"}'

const axios = require('axios');
const { data } = await axios.post('https:///api/v1/charges', {
  amount: 350.00,
  currency: 'THB',
  payment_method: 'promptpay',
  description: 'Order #1234',
}, { headers: { 'X-Merchant-Id': 'mer_demo' } });
console.log(`Charge: ${data.id}`);

import requests

r = requests.post("https:///api/v1/charges",
    json={"amount": 350.00, "currency": "THB", "payment_method": "promptpay"},
    headers={"X-Merchant-Id": "mer_demo"})
print(r.json())

$data = ['amount' => 350.00, 'currency' => 'THB', 'payment_method' => 'promptpay'];
$ch = curl_init('https:///api/v1/charges');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-Merchant-Id: mer_demo', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);

Error Codes

คำถามที่พบบ่อย (FAQ)

คำถามยอดนิยมเกี่ยวกับการใช้งานระบบ PayNex