เชื่อมต่อการตรวจสลิป
เข้ากับระบบของคุณ

01 / QUICKSTART

จากสลิป สู่ผลตรวจที่นำไปใช้งานได้

สมัครบัญชีและยืนยันข้อมูล จากนั้นสร้าง API Key ใน Merchant Portal ทุกตัวอย่างใช้ Production API และคำขอตรวจสลิปอาจใช้เครดิตจริง ค่าตัวอย่างในเอกสารเป็นข้อมูลสมมติ ให้แทนด้วยสลิปที่คุณมีสิทธิ์ใช้งาน

1. เตรียม CredentialsApp ID · API Key · Webhook Secret
2. ส่งสลิปรับ transactionId แล้วบันทึกไว้
3. ติดตามผลPolling หรือ Signed Webhook
4. เทียบคำสั่งซื้อยอดเงิน · สกุลเงิน · ผู้รับ · เวลาโอน

https://api.slipmatrix.com/api

Base URL มี /api แล้ว ต่อ path ในเอกสารได้เลย

# ตั้ง APP_ID และ API_KEY ใน environment ของเซิร์ฟเวอร์ก่อน
curl --fail-with-body --max-time 30 \
  'https://api.slipmatrix.com/api/verify/image/upload' \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -F 'file=@./slip.png'

{
  "success": true,
  "data": {
    "transactionId": "0199d720-0000-7000-8000-000000000001",
    "status": "PENDING",
    "message": "Verification request submitted"
  },
  "timestamp": "2026-10-10T12:00:00+07:00"
}

curl --fail-with-body --max-time 30 \
  "https://api.slipmatrix.com/api/verify/$TRANSACTION_ID" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY"

02 / AUTHENTICATION

ยืนยันตัวตนจากเซิร์ฟเวอร์ของคุณ

ส่ง headers ทั้งสองรายการในทุก Merchant API ยกเว้น GET /verify/banks ไม่ใช้ JWT ของหน้า Portal มาแทน API Key

เก็บค่าลับใน environment หรือระบบจัดการ secrets ฝั่งเซิร์ฟเวอร์ ห้ามใส่ใน JavaScript ของหน้าเว็บ, URL, Git หรือ log หากหมุนเวียนกุญแจให้ปรับค่าในระบบที่เชื่อมต่อด้วย

03 / API REFERENCE

เลือกวิธีส่งสลิปที่เหมาะกับระบบ

ทุก path ต่อจาก Base URL ด้านบน ผลตอบกลับที่สำเร็จอยู่ใน data และมี success, timestamp ครอบไว้

แสดง 10 จาก 10 endpoints

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "transRef": "EXAMPLE_TRANS_REF_001",
  "sendingBank": "014"
}'

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify?page=1&limit=20&status=VERIFIED" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY"

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify/qr" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "qrData": "REPLACE_WITH_THE_FULL_QR_TEXT_FROM_YOUR_REAL_PAYMENT_SLIP"
}'

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify/image" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "imageBase64": "REPLACE_WITH_BASE64_OR_DATA_URI_OF_YOUR_SLIP"
}'

# ตั้ง APP_ID และ API_KEY ใน environment ของเซิร์ฟเวอร์ก่อน
curl --fail-with-body --max-time 30 \
  'https://api.slipmatrix.com/api/verify/image/upload' \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -F 'file=@./slip.png'

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify/batch" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "transRef": "EXAMPLE_TRANS_REF_001",
      "sendingBank": "014",
      "referenceId": "order-001"
    }
  ]
}'

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify/batch/images" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "images": [
    {
      "imageBase64": "REPLACE_WITH_BASE64_OR_DATA_URI_OF_YOUR_SLIP",
      "referenceId": "order-001"
    }
  ]
}'

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify/batch/images/upload" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -F 'files=@./slip-001.png' \
  -F 'files=@./slip-002.png' \
  -F 'referenceIds=order-001,order-002'

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify/$TRANSACTION_ID" \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY"

curl --fail-with-body --max-time 30 "https://api.slipmatrix.com/api/verify/banks"

QR และ Base64 ในตัวอย่างเป็น placeholder ต้องแทนด้วยข้อมูลจริง ภาพต้องอ่าน QR ได้ชัดเจน ไม่เกิน 12 ล้านพิกเซล JSON ทั้งคำขอไม่เกิน 10 MiB; multipart แต่ละไฟล์ไม่เกิน 5 MiB

04 / RESULTS

อ่านสถานะและข้อมูลชำระเงิน

ใช้ GET /verify/{transactionId} พร้อม Credentials เดิม กำหนดระยะห่างในการ polling เช่นเริ่มที่ 3–5 วินาที เพิ่มระยะห่างเมื่อรอนาน และตั้งเวลารอสูงสุดในระบบของคุณ ผล data: null พร้อม HTTP 200 หมายถึงไม่พบรายการในบัญชีของคุณ

{
  "success": true,
  "data": {
    "transactionId": "0199d720-0000-7000-8000-000000000001",
    "transRef": "EXAMPLE_TRANS_REF_001",
    "status": "VERIFIED",
    "statusText": "Passed",
    "amount": "100.00",
    "paidLocalCurrency": "764",
    "currencyName": "THB",
    "receiverAccount": "xxx-x-x0000-x",
    "sendingBank": "004",
    "receivingBank": "014",
    "transferDate": "2026-10-10T11:59:00+07:00"
  },
  "timestamp": "2026-10-10T12:00:03+07:00"
}

ประวัติ GET /verify ใช้ data.data เป็นรายการ, data.total เป็นจำนวนรวม แต่ละแถวใช้ id และ verifiedAmount ส่วนตัวกรอง startDate/endDate กรองวันที่สร้างรายการ ไม่ใช่เวลาโอน

05 / BATCH

ตรวจผลรับคำขอทีละรายการ

เลขอ้างอิงส่งได้ 1–50 รายการ ภาพส่งได้ 1–20 ภาพ ระบบอาจรับเพียงบางรายการ จึงต้องอ่าน data.results ทุกแถว ใช้ index หรือ referenceId จับคู่กับคำขอเดิม และติดตาม transactionId ของแต่ละรายการที่รับเข้าคิว

{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "referenceId": "order-001",
        "transactionId": "0199d720-0000-7000-8000-000000000001",
        "status": "PENDING",
        "message": "Submitted"
      },
      {
        "index": 1,
        "referenceId": "order-002",
        "status": "DUPLICATE",
        "message": "Slip already exists"
      }
    ],
    "submitted": 1,
    "errors": 1
  },
  "timestamp": "2026-10-10T12:00:00+07:00"
}

สถานะผล batch: PENDING, DUPLICATE, INSUFFICIENT_CREDIT, INVALID_QR หรือ ERROR เป็นผลรับคำขอ ไม่ใช่ผลตรวจสุดท้าย หาก ERROR มี transactionId ให้ตรวจรายการเดิมก่อนลองใหม่

ระบบสำรอง 1 เครดิตต่อรายการที่รับเข้าคิว ตรวจผ่านจึงหักเครดิต และคืนเครดิตที่สำรองเมื่อไม่ผ่าน referenceId เป็นค่าอ้างอิงที่ส่งกลับ ไม่ได้ป้องกันคำขอซ้ำ

06 / ERRORS & LIMITS

จัดการข้อผิดพลาดโดยไม่สร้างรายการซ้ำ

{
  "success": false,
  "statusCode": 400,
  "code": "DUPLICATE_SLIP",
  "message": "This slip has already been verified",
  "timestamp": "2026-10-10T12:00:00+07:00"
}

message อาจเป็นข้อความ, array หรือ object และบางข้อผิดพลาดไม่มี code ให้ตรวจ HTTP status ร่วมด้วย หาก proxy หรือ firewall ตอบกลับเป็น HTML ให้ตรวจ Content-Type ก่อนอ่าน JSON

Rate limits

การส่งตรวจมีค่าเริ่มต้น 10 คำขอต่อนาที และ 100 คำขอต่อชั่วโมงต่อร้านค้า รวม API Keys ของร้านค้านั้น ตรวจ X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (epoch วินาที) และ Retry-After (วินาที) เมื่อส่งกลับ ระบบยังมีขีดจำกัดรวม จึงอาจได้รับ 429 จากการ polling หรือเรียกถี่เกินไปด้วย

07 / SIGNED WEBHOOK

รับผลตรวจโดยไม่ต้อง polling ตลอดเวลา

ตั้ง Callback URL ในเมนูตั้งค่าของ Merchant Portal และใช้ Webhook Secret ที่ได้รับเมื่อสมัคร (แสดงในหน้าสมัครสำเร็จและอีเมลต้อนรับ) หากไม่มีค่าดังกล่าวให้ติดต่อทีมงาน ใช้ HTTPS ที่เข้าถึงได้จากอินเทอร์เน็ต ปลายทาง localhost, private network และ URL ที่ฝัง username/password ใช้งานไม่ได้ ระบบไม่ติดตาม redirect

{
  "event": "slip.verified",
  "transactionId": "0199d720-0000-7000-8000-000000000001",
  "transRef": "EXAMPLE_TRANS_REF_001",
  "status": "VERIFIED",
  "statusText": "Passed",
  "amount": "100.00",
  "currencyName": "THB",
  "paidLocalCurrency": "764",
  "receiverAccount": "xxx-x-x0000-x",
  "transferDate": "2026-10-10T11:59:00+07:00",
  "verifiedAt": "2026-10-10T12:00:03+07:00"
}

ตรวจ HMAC จาก bytes ของ body ก่อน JSON parsing ห้าม stringify JSON ที่ parse แล้วมาคำนวณใหม่ เพราะ whitespace และลำดับ field อาจเปลี่ยน หากใช้ middleware ให้เก็บ raw body ก่อน JSON parser

// © 2026 ByteMatrix Co., Ltd. — Node.js 22+, no external dependencies.
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody must be the exact UTF-8 bytes received, before JSON parsing.
// signature is X-Gateway-Signature (64 hex characters, no "sha256=" prefix).
export function verifyWebhook(rawBody, signature, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/i.test(signature)) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const supplied = Buffer.from(signature, 'hex');
  return supplied.length === expected.length && timingSafeEqual(expected, supplied);
}

// After verification:
// 1. Parse and validate the signed JSON body (use its event, not the event header).
// 2. Persist to a durable inbox / database with duplicate detection.
// 3. Respond 2xx only after persistence succeeds; otherwise respond 5xx for retry.
// 4. Process orders idempotently; reconcile amount, currency, receiver and transferDate.
// X-Gateway-Timestamp is not covered by the signature. It is not replay protection.

อ้างอิง Node.js crypto: timingSafeEqual ↗

1. ตรวจลายเซ็น แล้วตรวจ event/status ใน body
2. บันทึกลงฐานข้อมูลหรือ durable inbox พร้อมป้องกันรายการซ้ำ เช่น unique transactionId + event
3. ตอบ 2xx หลังบันทึกสำเร็จ หากยังบันทึกไม่ได้ให้ตอบ 5xx เพื่อให้ลองส่งใหม่
4. ประมวลผลคำสั่งซื้อแบบ idempotent และเทียบยอด ผู้รับ สกุลเงิน เวลาโอนก่อนให้สิทธิ์

ปลายทางต้องตอบภายใน 10 วินาที ระบบพยายามส่งรวมสูงสุด 5 ครั้งด้วย exponential backoff Webhook อาจมาซ้ำหรือมาหลังจาก polling ได้ผลแล้ว จึงต้องป้องกันการอนุมัติคำสั่งซื้อซ้ำ อย่าคาดว่าทุก HTTP 400 จะมี callback ให้

verifiedAt คือเวลาที่เตรียมผลส่ง Webhook ไม่ใช่เวลาโอน ใช้ transferDate สำหรับเทียบเวลาชำระเงิน

08 / CODE EXAMPLES

เริ่มจากภาษาที่คุณใช้

ตัวอย่างอัปโหลดรูปสำหรับฝั่งเซิร์ฟเวอร์ ตั้ง APP_ID และ API_KEY ใน environment ก่อนรัน เมื่อได้รับ transactionId ให้เก็บไว้และติดตามผลตามขั้นตอนด้านบน

# ตั้ง APP_ID และ API_KEY ใน environment ของเซิร์ฟเวอร์ก่อน
curl --fail-with-body --max-time 30 \
  'https://api.slipmatrix.com/api/verify/image/upload' \
  -H "x-app-id: $APP_ID" \
  -H "x-api-key: $API_KEY" \
  -F 'file=@./slip.png'

สัญญาไฟล์ดาวน์โหลดใช้ OpenAPI 3.0.3 ระบุเฉพาะ Merchant API และ schema ของ Webhook

09 / GO LIVE

ตรวจให้ครบก่อนยืนยันชำระเงินอัตโนมัติ

• ทดสอบผลผ่าน, ยอดไม่ตรง, ผู้รับไม่ตรง และข้อมูลผู้รับที่ถูกปิดบัง
• ทดสอบสลิปซ้ำ, QR อ่านไม่ได้, เครดิตไม่พอ และ batch ที่รับได้บางส่วน
• ทดสอบ timeout / 429 และค้นประวัติก่อนส่งซ้ำ
• ทดสอบลายเซ็นไม่ถูกต้อง, Webhook ส่งซ้ำ และกรณีฐานข้อมูลปลายทางไม่พร้อม
• เก็บ Credentials ฝั่งเซิร์ฟเวอร์ และป้องกันข้อมูลสลิปหรือกุญแจหลุดผ่าน log