PayRadar Dev API

รับเงินผ่าน PromptPay แล้วยืนยันยอดให้อัตโนมัติ — ไม่ต้องตรวจสลิป ไม่ต้องกระทบยอดเอง

Accept PromptPay payments and get them auto-confirmed — no slip checking, no manual reconciliation.

เรียก API เพียงครั้งเดียวเพื่อ สร้างบิลที่ล็อกยอดเงินไว้ แล้ว PayRadar จะส่งหน้าชำระเงิน แบรนด์ PayRadar กลับมาให้ (พร้อม QR payload แบบดิบ) ลูกค้าสแกนแล้วโอนได้ทันที จากนั้น มือถือ Android ที่ร้านผูกไว้จะได้ยินการแจ้งเตือนเงินเข้าจากธนาคาร PayRadar จะจับคู่กับบิล จากยอดที่ตรงเป๊ะบวกกับเศษสตางค์เฉพาะของบิลนั้น แล้วทำเครื่องหมายว่าจ่ายแล้ว พร้อม ยิง webhook ที่เซ็นลายเซ็น มาที่เซิร์ฟเวอร์ของคุณ ทำให้ยืนยันออเดอร์ได้โดยไม่ต้องเปิดดูสลิปเลย ส่วนกรณีหายากที่ listener ออฟไลน์ ยังมีช่องทางสำรองให้อัปโหลดสลิปรองรับไว้

With one API call you create a bill with a locked amount, and PayRadar returns a hosted, branded pay page (and the raw QR payload). Your customer scans and transfers. The merchant's paired Android phone hears the bank's money-in notification, PayRadar matches it to the bill by the exact amount plus a unique satang, marks it paid, and fires a signed webhook to your server. You confirm orders without ever looking at a slip — and a slip-upload fallback covers the rare case the listener is offline.

Aเริ่มต้นใช้งานGetting started

ทำตาม 4 ขั้นตอนนี้ก่อนเรียก API ครั้งแรก

Four quick steps before your first API call:

1. สมัครบัญชีร้านค้า ที่ cosmixon.com/api/payradar/app
2. ตั้งหมายเลข PromptPay ในแดชบอร์ด นี่คือบัญชีที่จะรับเงินโอนทุกบิล
3. ติดตั้งแอป Android แล้วเข้าสู่ระบบ บนมือถือที่จะวางประจำไว้ที่ร้าน การเข้าสู่ระบบจะผูกมือถือเครื่องนั้นเป็น listener ทำหน้าที่อ่านการแจ้งเตือนเงินเข้าจากธนาคารแล้วรายงานผลการจับคู่กลับมาที่ PayRadar
4. คัดลอก API key จากแดชบอร์ด (จะตั้งค่า webhook_url ในหน้านี้ด้วยเลยก็ได้)

1. Sign up for a merchant account at cosmixon.com/api/payradar/app.
2. Set your PromptPay number in the dashboard — this is the account that will receive every transfer.
3. Install the Android app & log in on the phone that will stay at the shop. Logging in pairs that phone as your listener — it reads incoming bank notifications and reports matches back to PayRadar.
4. Grab your API key from the dashboard (and optionally set your webhook_url there too).

Bการยืนยันตัวตน (Authentication)Authentication

ทุก request ของ v1 ต้องยืนยันตัวตนด้วย API key ลับของคุณ โดยส่งผ่าน request header

Every v1 call is authenticated with your secret API key in a request header:

X-Api-Key: pr_live_xxxxxxxxxxxxxxxxxxxxxxxx

• API key เป็นแบบ หนึ่งคีย์ต่อหนึ่งบัญชี ให้เก็บ pr_live_… เป็นความลับ อย่าใส่ไว้ในโค้ดฝั่ง client และอย่า commit ลง repo
• API key หมุนเปลี่ยนได้ เรียก POST /api/payradar/apikey/rotate (พร้อม Bearer token ของร้าน) เพื่อออกคีย์ใหม่และยกเลิกคีย์เดิมทันที
• ค่าคีย์เดียวกันนี้ยังถูกใช้เป็น HMAC secret สำหรับตรวจลายเซ็นของ webhook (ดู Webhooks) ดังนั้นเมื่อหมุน API key ตัว webhook secret จะเปลี่ยนตามไปด้วย

• Keys are per account. Treat pr_live_… as a secret — never expose it in client-side code or commit it to a repo.
• Keys are rotatable: POST /api/payradar/apikey/rotate (with your merchant Bearer token) issues a fresh key and invalidates the old one.
• The same key value is reused as the HMAC secret for verifying webhook signatures (see Webhooks). Rotating the key rotates the webhook secret too.

1สร้างบิลCreate a bill

สร้างคำขอชำระเงินที่ล็อกยอดไว้ พร้อมเศษสตางค์เฉพาะสำหรับใช้จับคู่ บิลมีอายุ 15 นาที

Creates a payment request with a locked amount and a unique matching satang, valid for a 15-minute window.

Request bodyRequest body

{
  "amount": 250.00,
  "ref": "ORDER-10231",
  "thank_you_url": "https://yourshop.com/thanks"
}

ResponseResponse

{
  "ok": true,
  "token": "bil_7Qx2k9ZrA4",
  "amount_full": 250.37,
  "satang": 37,
  "qr_payload": "00020101021229370016A0000006770101110213...",
  "pay_url": "https://payradar.cosmixon.com/pay/bil_7Qx2k9ZrA4",
  "expires_at": "2026-06-20T08:45:00Z",
  "window_min": 15
}

การนำ response ไปใช้Using the response

• วิธีที่ง่ายที่สุด: redirect หรือแสดง pay_url ให้ลูกค้า หน้านี้จะ render QR แสดงยอดที่ต้องจ่ายแบบเป๊ะ ๆ (พร้อมไฮไลต์เศษสตางค์ที่ใช้จับคู่) poll สถานะให้อัตโนมัติ และ redirect ไป thank_you_url เมื่อจ่ายสำเร็จ ทั้งหมดอยู่ในดีไซน์แบรนด์ PayRadar
• โฮสต์ QR เอง: นำ qr_payload ไป render เป็น QR ในระบบของคุณเอง เหมาะถ้าต้องการให้ขั้นตอนชำระเงินอยู่ภายใน UI ของคุณ
• amount_full = amount ของคุณ + เศษสตางค์เฉพาะ (.01–.99) ลูกค้าต้องโอนยอดนี้ให้ตรง เป๊ะ เพราะ listener ใช้ค่านี้แยกแยะบิลใบนี้ออกจากบิลอื่นที่มียอดบาทเท่ากัน
• บิลมีอายุ 15 นาที (window_min) เมื่อเลย expires_at สถานะจะเปลี่ยนเป็น expired

• Easiest: redirect or show the customer the pay_url. It renders the QR, shows the exact amount (with the matching satang highlighted), polls status, and redirects to your thank_you_url on success — all branded by PayRadar.
• Self-hosted QR: render qr_payload yourself as a QR code if you want the payment inside your own UI.
• amount_full = your amount + a unique satang (.01–.99). This is the value the customer must transfer exactly; it's how the listener distinguishes this bill from any other at the same baht amount.
• The bill is valid for 15 minutes (window_min); after expires_at it becomes expired.

2เช็กสถานะCheck status

Poll สถานะล่าสุดของบิล ต้องส่ง header X-Api-Key ตัวเดียวกัน ใช้ endpoint นี้เป็นแหล่งข้อมูลหลักที่เชื่อถือได้ และเป็น fallback ของ webhook

Poll a bill's current state. Requires the same X-Api-Key header. Use this as your reliable source of truth (and as a fallback to webhooks).

{
  "token": "bil_7Qx2k9ZrA4",
  "ref": "ORDER-10231",
  "amount": 250.37,
  "satang": 37,
  "status": "paid",        // pending | paid | expired
  "paid_at": "2026-06-20T08:33:12Z",
  "expires_at": "2026-06-20T08:45:00Z"
}

3Webhooks

ตั้งค่า webhook_url ในแดชบอร์ดร้านค้า ทันทีที่บิลถูกจ่าย PayRadar จะส่ง HTTP POST ไปยัง URL นั้น

Set your webhook_url in the merchant dashboard. The moment a bill is paid, PayRadar sends an HTTP POST to that URL:

// Header sent by PayRadar:
X-PayRadar-Signature: sha256=4f3b...e91a   // hex HMAC of the raw body

// Body:
{
  "event": "payment.paid",
  "token": "bil_7Qx2k9ZrA4",
  "ref": "ORDER-10231",
  "amount": 250.37,
  "via": "auto"          // "auto" (noti match) | "slip" (manual fallback)
}

การตรวจสอบลายเซ็น (signature)Verifying the signature

คำนวณ HMAC-SHA256 ของ raw request body ที่ยังไม่ได้ parse โดยใช้ API key เป็น secret เข้ารหัสผลลัพธ์เป็น hex แล้วนำไปเทียบกับค่า hex ที่อยู่หลัง sha256= ใน header X-PayRadar-Signature และควรเทียบแบบ constant-time เพื่อป้องกัน timing leak ข้อสำคัญคือต้องอ่าน raw body เป็น byte ก่อน parse JSON เพราะการ serialize JSON ที่ parse แล้วใหม่อาจทำให้ byte เปลี่ยน จนลายเซ็นไม่ตรง

Compute the HMAC-SHA256 of the raw, unparsed request body using your API key as the secret, hex-encode it, and compare it to the hex after sha256= in the X-PayRadar-Signature header. Use a constant-time comparison to avoid timing leaks. Read the raw body bytes before any JSON parsing — re-serializing parsed JSON can change bytes and break the match.

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

ตัวอย่างการสร้างบิลและตรวจสอบ webhook ที่ส่งเข้ามา เปลี่ยน pr_live_xxx เป็น API key ของคุณ

Create a bill, then verify an incoming webhook. Replace pr_live_xxx with your key.

# Create a bill
curl -X POST https://payradar.cosmixon.com/api/payradar/v1/bill \
  -H "X-Api-Key: pr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount":250.00,"ref":"ORDER-10231","thank_you_url":"https://yourshop.com/thanks"}'

# Poll status
curl https://payradar.cosmixon.com/api/payradar/v1/status/bil_7Qx2k9ZrA4 \
  -H "X-Api-Key: pr_live_xxx"

import crypto from 'node:crypto';
import express from 'express';

const API_KEY = process.env.PAYRADAR_API_KEY; // "pr_live_xxx"
const BASE = 'https://payradar.cosmixon.com/api/payradar';

// 1) Create a bill
async function createBill() {
  const res = await fetch(`${BASE}/v1/bill`, {
    method: 'POST',
    headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: 250.0, ref: 'ORDER-10231', thank_you_url: 'https://yourshop.com/thanks' }),
  });
  return res.json(); // { ok, token, amount_full, pay_url, ... }
}

// 2) Verify the webhook (raw body required!)
const app = express();
app.post('/payradar/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const raw = req.body; // Buffer of the exact bytes received
  const got = (req.get('X-PayRadar-Signature') || '').replace('sha256=', '');
  const want = crypto.createHmac('sha256', API_KEY).update(raw).digest('hex');

  const a = Buffer.from(got, 'hex'), b = Buffer.from(want, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('bad signature');
  }
  const evt = JSON.parse(raw.toString('utf8'));
  if (evt.event === 'payment.paid') {
    // idempotent: mark evt.ref / evt.token as paid
  }
  res.sendStatus(200);
});

import os, hmac, hashlib, json, requests
from flask import Flask, request, abort

API_KEY = os.environ["PAYRADAR_API_KEY"]  # "pr_live_xxx"
BASE = "https://payradar.cosmixon.com/api/payradar"

# 1) Create a bill
def create_bill():
    r = requests.post(
        f"{BASE}/v1/bill",
        headers={"X-Api-Key": API_KEY},
        json={"amount": 250.00, "ref": "ORDER-10231",
              "thank_you_url": "https://yourshop.com/thanks"},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()  # {"ok": True, "token": ..., "pay_url": ..., ...}

# 2) Verify the webhook (use the RAW body!)
app = Flask(__name__)

@app.post("/payradar/webhook")
def webhook():
    raw = request.get_data()  # exact bytes, before JSON parsing
    got = request.headers.get("X-PayRadar-Signature", "").removeprefix("sha256=")
    want = hmac.new(API_KEY.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(got, want):
        abort(401)
    evt = json.loads(raw)
    if evt.get("event") == "payment.paid":
        pass  # idempotent: mark evt["ref"] / evt["token"] paid
    return "", 200

5ข้อจำกัด & หมายเหตุLimits & notes

• อายุของบิล: 15 นาทีต่อหนึ่งบิล หลังจากนั้นสถานะจะเป็น expired และเงินที่โอนเข้ามาจะไม่จับคู่ให้อัตโนมัติ
• เศษสตางค์ต้องไม่ซ้ำกัน: การจับคู่ใช้เศษสตางค์เฉพาะในช่วง .01–.99 ดังนั้นในยอดบาทเดียวกันจะมีบิลที่ยังไม่จ่ายพร้อมกันได้สูงสุด ประมาณ 99 บิลต่อช่วงเวลา หากมีปริมาณสูงกว่านี้ ให้ปรับยอดให้ต่างกันหรือทยอยออกบิล PayRadar ออกแบบมาสำหรับร้านขนาดเล็กถึงกลาง ไม่ได้รองรับ flash sale ที่มีลูกค้าหลักพันจ่ายราคาเดียวกันพร้อมกัน
• ต้องโอนยอดให้ตรงเป๊ะ: ลูกค้าต้องโอน amount_full ให้ตรงถึงหลักสตางค์ หากจ่ายเกินหรือขาดแม้เพียงสตางค์เดียว ระบบจะไม่ยืนยันอัตโนมัติ
• listener ต้องออนไลน์: มือถือ Android ที่ผูกไว้ต้องเปิดเครื่อง ต่ออินเทอร์เน็ต และเปิดการแจ้งเตือนของแอปธนาคาร หากออฟไลน์ การยืนยันอัตโนมัติจะหยุด แล้วช่องทางสำรองอัปโหลดสลิปจะรองรับการชำระเงินแทน (webhook จะระบุ via:"slip")
• รองรับ HTTPS เท่านั้น: webhook URL ต้องเป็น http(s) ที่เข้าถึงได้จากภายนอก ส่วน IP ภายในหรือ IP ส่วนตัวจะถูกบล็อก

• Payment window: 15 minutes per bill. After that, status becomes expired and a transfer won't auto-match.
• Satang uniqueness: matching uses a unique satang .01–.99, so there can be at most ~99 concurrent unpaid bills at the identical baht amount within one window. Vary your amounts or stagger bills for high volume — PayRadar is built for small-to-medium shops, not thousand-customer flash sales at one price.
• Exact transfer required: the customer must transfer amount_full to the satang. Over- or under-paying (even by a satang) won't auto-confirm.
• Listener must be online: the paired Android phone needs power, internet, and bank notifications enabled. If it's offline, auto-confirm pauses and the slip-upload fallback covers payments (via:"slip" in the webhook).
• HTTPS only. Webhook URLs must be public http(s); private/internal IPs are blocked.