Sirasupa Payment Relay API

01ภาพรวมระบบ

สายงาน: SMS เข้า iPhone → Shortcuts ยิง POST /api/sms/relay (x-api-key) → Sirasupa จับคู่กฎ → POST Webhook URL พร้อม x-sirasupa-signature → ปลายทางตรวจด้วย Secret key

1. SMS จากธนาคารเข้าเครื่อง
2. Shortcuts ส่งเข้า relay
3. Sirasupa จับคู่และ forward webhook
4. ปลายทางยืนยัน HMAC แล้วประมวลผล

023 ความลับที่ต้องเข้าใจ

{
  "Authorization": "Bearer …"
}

03เริ่มใช้งานใน 5 นาที

1. /portal/ — สร้าง API Key (srs_…) และแสดง Secret key
2. วางทั้งคู่ที่เว็บรับชำระของคุณ (ช่องตั้งค่าที่เอกสารของระบบนั้นระบุ)
3. สร้างกฎ: Webhook URL ตามที่ปลายทางให้มา เช่น https://your-domain.example/api/sirasupa/webhook
4. ตั้ง Shortcuts ตาม หัวข้อ 9 — ยิง POST /api/sms/relay + x-api-key
5. ทดสอบโอน → เช็กบันทึกในพอร์ทัล

04POST/api/sms/relay

ส่งข้อความ SMS เข้าระบบเพื่อจับคู่กฎและส่งต่อ webhook

Request Headers

Request Body

{
  "message": "บช X-1234 เงินเข้า 100.00 บาท คงเหลือ 1,234.56 บาท"
}

รองรับคีย์ text แทน message ได้ หากสะดวกในคำสั่งลัด

cURL

curl -sS -X POST "https://payment.sirasupa.com/api/sms/relay" \
  -H "Content-Type: application/json" \
  -H "x-api-key: srs_YOUR_KEY" \
  -d '{"message":"บช X-1234 เงินเข้า 100.00 บาท"}'

ตัวเลขใน SMS และ JSON

หัวข้อนี้เกี่ยวกับการอ่านเลขจากข้อความ SMSและ body JSON — ไม่ใช่หลักการคำนวณยอดบน QR พร้อมเพย์ (ดูหัวข้อ PromptPay QR)

• JSON / API — ใช้จุด (.) เป็นทศนิยมแบบมาตรฐาน JSON เช่น 123.45 ไม่ใส่ comma คั่นหลักพันใน JSON
• ข้อความใน message — ตัว parse ลบ , ออกจากทั้งข้อความก่อน จึงรองรับยอดแบบ 1,234.56 บาท (comma = หลักพัน + จุด = ทศนิยม)
• ยอดที่ดึงได้ (parsed_amount_baht) — มักเป็น ทศนิยม 2 ตำแหน่ง หรือ null ถ้าอ่านไม่ได้
• ข้อควรระวัง — รูปแบบทศนิยมด้วยจุลภาค เช่น 100,50 บาท ไม่รองรับ (comma ถูกลบแล้วค่าผิด)

05รูปแบบการตอบกลับ

{
  "ok": true,
  "id": "ad8c1e3b-…",                    // log id (ตรงกับ x-sirasupa-delivery)
  "parsed_amount_baht": 100,             // null = parse ยอดไม่ได้
  "matched_count": 1,                    // กฎที่ match ทั้งหมด
  "forwarded_count": 1,                  // กฎที่ส่งต่อจริง (พ้นยอดขั้นต่ำ ฯลฯ)
  "results": [
    {
      "translationId": "rule_doc_id",
      "status": 200,                     // HTTP จากปลายทาง
      "webhook": "https://your-domain.example/api/sirasupa/webhook"
    }
  ]
}

06Webhook callback

เมื่อจับคู่กฎสำเร็จ Sirasupa จะ POST ไปยัง Webhook URL ที่คุณตั้งในกฎ

Headers ที่ Sirasupa ส่ง

Body ที่ Sirasupa ส่ง

{
  "event": "sms.bank_inbound",
  "raw_message": "บช X-1234 เงินเข้า 100.00 บาท …",
  "parsed_amount_baht": 100,
  "translation": { "id": "rule_doc_id", "name": "ชื่อกฎ" },
  "received_at": "2026-05-04T12:00:00.000Z",
  "relay": { "auth": "api_key", "profile_id": "firebase_uid" }
}

ระบบปลายทางควรตอบ HTTP 2xx เมื่อประมวลผลเสร็จ — Sirasupa ไม่ retry อัตโนมัติ

07วิธีตรวจ HMAC ฝั่งคุณ

ใช้ raw body bytes ที่รับมาเทียบ HMAC-SHA256 กับ Secret — ตัด prefix sha256= ใน header แบบ timing-safe · ห้าม stringify JSON ใหม่ก่อนคำนวณ

Node.js (Express + raw body)

import express from "express";
import crypto from "crypto";

const app = express();
const SECRET = process.env.SIRASUPA_WEBHOOK_SECRET; // คัดลอกจาก /portal/

app.post(
  "/api/sirasupa/webhook",
  express.raw({ type: "application/json", limit: "256kb" }),
  (req, res) => {
    const raw = req.body; // Buffer
    const headerSig = String(req.header("x-sirasupa-signature") || "");
    const m = /^sha256=([a-f0-9]+)$/i.exec(headerSig.trim());
    if (!m) return res.status(400).json({ error: "missing_signature" });

    const expected = crypto.createHmac("sha256", SECRET).update(raw).digest("hex");
    const a = Buffer.from(m[1].toLowerCase(), "hex");
    const b = Buffer.from(expected, "hex");
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(400).json({ error: "invalid_signature" });
    }

    const payload = JSON.parse(raw.toString("utf8"));
    // … processing payload …
    return res.status(200).json({ ok: true });
  }
);

Python (FastAPI / Flask)

import hmac, hashlib, os
SECRET = os.environ["SIRASUPA_WEBHOOK_SECRET"].encode()

def verify(raw_body: bytes, header_value: str) -> bool:
    if not header_value or not header_value.lower().startswith("sha256="):
        return False
    received = bytes.fromhex(header_value.split("=", 1)[1])
    expected = hmac.new(SECRET, raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(received, expected)

08PromptPay QR

สร้าง QR ใน Portal/Admin — ระบบคำนวณยอดโอนจริงบน QR เพื่อลดโอกาสจับคู่ SMS ชนกันเมื่อหลายคนสร้าง QR ยอดฐานเดียวกันในช่วง timeout 5 / 10 นาที → SMS เข้า relay → จับคู่ตามยอด + เวลา → webhook

ยอดเต็ม (100.00) เมื่อไหร่

ใช้โหมด whole เมื่อก่อนสร้างรายการใหม่:

• ไม่มีรายการ pending อื่นที่ใช้ เลขพร้อมเพย์เดียวกันและยอดฐาน (baseBaht) เดียวกัน
• ใน session (sessionSlug) เดียวกัน มี QR ค้างไม่เกิน 2 รายการ

ผลคือ QR ขอให้โอน จำนวนเต็มบาท เช่น base 100 → 100.00 บาท

เศษสตางค์ (กันชน) — ไม่เกินยอดฐาน

ถ้ามีอย่างน้อยหนึ่งข้อ: มี pending เดิมที่เลขพร้อมเพย์ + ยอดฐานซ้ำ (เช่น คนที่สองสร้าง 100 บาทขณะคนแรกยังค้าง) หรือ ใน session มี pending มากกว่า 2 แล้ว — ระบบจะเพิ่มเศษเฉพาะแบบหักจากยอดจำนวนเต็ม สุ่ม 0.01–0.20 บาท — เช่น base 100 → โอนได้เฉพาะช่วง 99.80 … 99.99 (20 ช่อง) จะไม่ใช้ยอดเกิน 100

API ตอบ HTTP 409 คีย์ ppay_queue_full เมื่อมี pending ยอดฐานเดียวกันครบ 20 รายการแล้ว หรือช่องเศษถูกใช้หมด — ต้องรอให้มีรายการสำเร็จหรือหมดเวลา แล้วสร้าง QR ใหม่

• decimalMode: whole — โอนตรงยอดจำนวนเต็ม เช่น 100.00
• decimalMode: under_minus_01_20 — โอนใต้ยอดเต็ม 99.80 … 99.99 (กรณี base 100)

ยอดสุดท้ายอยู่ใน exactAmountBaht และถูกเก็บใน Firestore (ppay_test_transactions) เมื่อ SMS มียอดตรงทุกสตางค์ ระบบจับคู่กับรายการค้างภายในหน้าต่างเวลาที่ตั้งใน Cloud Functions

ขอบเขต

• สูงสุด 20 รายการ pending ต่อชุดเลขพร้อมเพย์ + ยอดฐานเดียวกัน — เกินจะได้ 409 ppay_queue_full
• สูงสุด 20 รายการ pending ต่อ session — เกินจะได้ข้อผิดพลาด too_many_session_pending
• Timeout ต่อ QR: 5 หรือ 10 นาที (เลือกตอนสร้าง)

09ตั้งค่า iOS Shortcuts

สร้างคำสั่งลัดที่มี Action «รับเนื้อหาของ URL» (POST + x-api-key) ก่อน จากนั้นค่อยตั้ง Automation ให้รันลัดนั้นเมื่อมี SMS ตรงคีย์เวิร์ด

ตัวอย่างที่ถูกต้อง — คัดลอกได้

// ใน Shortcut → "รับเนื้อหาของ URL"
URL:     https://payment.sirasupa.com/api/sms/relay
Method:  POST

Headers:
  Content-Type: application/json
  x-api-key: srs_XXXXXXXXXXXXXXXXXXXXXXXX

Request Body (JSON):
  {
    "message": "[ข้อความ SMS จาก Get Contents of input ของ Shortcut]",
    "received_at": "[ISO timestamp ถ้ามี]"
  }

10แอป Android (APK)

แอป SRSP SMS Gateway ทำหน้าที่เดียวกับ iOS Shortcut — ฟัง SMS เข้า แล้ว POST ไปยัง /api/sms/relay พร้อม x-api-key ใช้ API Key เดียวกัน และกฎเดียวกันที่ตั้งใน /portal/

ภาพตัวอย่างหน้าจอ

ขั้นตอนติดตั้ง (5 นาที)

1. บนมือถือ Android เปิด URL https://payment.sirasupa.com/downloads/sirasupa-sms-relay.apk เพื่อโหลด APK โดยตรง (หรือกดปุ่ม «ดาวน์โหลด APK» ด้านบนจากเครื่องที่จะติดตั้ง)
2. เปิดไฟล์ APK → อนุญาต «ติดตั้งแอปจากแหล่งที่ไม่รู้จัก» สำหรับแอปที่ใช้เปิดไฟล์ (เช่น Chrome / ตัวจัดการไฟล์)
3. เปิดแอป SRSP SMS Gateway → แตะโลโก้บนหน้า splash → กด «เข้าสู่ระบบด้วย Google» ใช้บัญชีเดียวกับเว็บ
4. เข้าครั้งแรก: ระบบจะออก API Key ให้อัตโนมัติ · มีคีย์อยู่แล้ว: กด «วางคีย์ srs_… ที่มีอยู่» และวางคีย์เดิม · ต้องการคีย์ใหม่: กด «หมุน API key ใหม่» (ยืนยัน warning จะทำลายคีย์เดิม)
5. ในการ์ด «สถานะ» — กด «ขอสิทธิ์ SMS / การแจ้งเตือน» และอนุญาตทุกข้อ
6. (เลือก) ใส่ คำที่ต้องมีใน SMS เช่น บช X-1234 เพื่อกรองฝั่งเครื่อง (กฎจริงตั้งในพอร์ทัลเว็บ) บรรทัดละ 1 คำ — เว้นว่างจะส่งทุกข้อความเข้า relay
7. เปิดสวิตช์ «เปิด relay เมื่อมี SMS เข้า» → กด «บันทึก» → กด «ทดสอบส่ง» เพื่อดูว่ากฎใน Sirasupa Portal จับคู่ได้

Meta Quest / Horizon OS (โหมด companion)

Quest ไม่มี SMS และไม่มี Google Play Services — ใช้แอปเป็นเครื่องมือ ทดสอบ relay และจัดการคีย์เท่านั้น (SMS จริงยังต้องใช้มือถือที่มีซิม)

1. Sideload APK บน Quest (หรือ hzdb app install … จากเครื่อง dev)
2. หน้า login → «ใช้ API key จากพอร์ทัล»
3. วาง srs_… จาก /portal/
4. กด «ทดสอบส่ง» แล้วดู log ในแอปและใน Portal

11ตัวอย่างเว็บรับ webhook

สมมติเว็บรับชำระของคุณมีหน้าตั้งค่าให้ใส่ API Key / Secret สำหรับลายเซ็น webhook และกำหนด Webhook URL ที่ Sirasupa จะยิงเข้ามา — ขั้นตอนโดยรวมอาจเป็นแบบนี้ (แทนที่ URL ด้วยของจริงตามเอกสารของระบบคุณ):

1. เข้าแดชบอร์ด / หน้าตั้งค่ารับชำระของเว็บคุณ (ตัวอย่าง URL: https://your-domain.example/admin/payments)
2. ในช่องที่ให้ใส่คีย์จากผู้ให้บริการ relay → วาง srs_… จาก Sirasupa Portal
3. เปิดส่วนขยายถ้ามี → ในช่อง «Secret key / Webhook signing secret» (หรือชื่อเทียบเท่า) วางค่าจากพาเนล «Secret key» ใน Portal — ไม่ใช่ค่า srs_…
4. กดบันทึก → ใน Sirasupa Portal สร้างกฎ โดย Webhook URL = https://your-domain.example/api/sirasupa/webhook · หัวเพิ่มเติม {} ถ้าไม่ต้องการส่ง Bearer เพิ่ม

12แก้ปัญหา (HTTP 400 / 401)