คู่มือ API

Authorization: Bearer ppk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -X POST https://ppay-slip.com/api/v1/verify \
  -H "Authorization: Bearer ppk_xxxxxxxx" \
  -F "file=@slip.jpg"

{
  "ok": true,
  "queued": true,
  "jobId": "job_1f3a9c...",
  "status": "queued",
  "reference": null,
  "statusUrl": "/api/v1/jobs/job_1f3a9c..."
}

curl -X POST https://ppay-slip.com/api/v1/verify/async \
  -H "Authorization: Bearer ppk_xxxxxxxx" \
  -F "file=@slip.jpg" -F "reference=ORDER-1001"

curl -X POST https://ppay-slip.com/api/v1/verify/batch \
  -H "Authorization: Bearer ppk_xxxxxxxx" \
  -F "file=@a.jpg" -F "file=@b.jpg" -F "file=@c.jpg" \
  -F "reference=A-1" -F "reference=A-2" -F "reference=A-3"

{
  "ok": true,
  "accepted": 2,
  "rejected": 1,
  "jobs": [
    { "index": 0, "ok": true,  "jobId": "job_aa...", "reference": "A-1" },
    { "index": 1, "ok": false, "code": "INVALID_FILE", "error": "file must be a valid PNG/JPG up to 5MB" },
    { "index": 2, "ok": true,  "jobId": "job_bb...", "reference": "A-3" }
  ]
}

curl https://ppay-slip.com/api/v1/jobs/job_1f3a9c... \
  -H "Authorization: Bearer ppk_xxxxxxxx"

{
  "ok": true,
  "jobId": "job_1f3a9c...",
  "reference": "ORDER-1001",
  "status": "done",                 // queued | processing | done
  "createdAt": "2026-10-12T07:31:58.120Z",
  "finishedAt": "2026-10-12T07:32:00.904Z",
  "result": { /* เมื่อ status = done: รูปแบบเดียวกับผลตรวจสลิป ดูหัวข้อถัดไป + jobId, reference */ }
}

{
  "ok": true,
  "id": "b1c2d3e4-...",
  "valid": true,
  "result": "valid",
  "code": "VALID",
  "message": "สลิปถูกต้อง",
  "messageEn": "The slip is valid.",
  "slip": {
    "reference": "0158...9421",
    "amount": 1250.00,
    "currency": "THB",
    "transferredAt": "2026-10-12T07:32:00.000Z",
    "sender":   { "name": "นาย สมชาย ใจดี", "bank": "ธนาคารกสิกรไทย" },
    "receiver": { "name": "ร้านตัวอย่าง", "bank": "ธนาคารไทยพาณิชย์", "account": "xxx-x-x1234-x" }
  },
  "billing": { "paidWith": "quota", "refunded": false, "creditsLeft": 120, "quotaLeft": 480 }
}

POST /webhooks/ppay HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: PPaySlip-Webhook/1.0
X-PPay-Event: verification.completed
X-PPay-Delivery: evt_9b1c2d...
X-PPay-Attempt: 1
X-PPay-Signature: t=1760254320,v1=5d41402abc4b2a76b9719d911017c592...

{
  "id": "evt_9b1c2d...",
  "type": "verification.completed",
  "apiVersion": "1",
  "createdAt": "2026-10-12T07:32:00.904Z",
  "data": {
    "jobId": "job_1f3a9c...",
    "reference": "ORDER-1001",
    "ok": true,
    "valid": true,
    "result": "valid",
    "code": "VALID",
    "message": "สลิปถูกต้อง",
    "slip": { "reference": "0158...9421", "amount": 1250.00, "currency": "THB", "...": "..." },
    "billing": { "paidWith": "quota", "refunded": false, "creditsLeft": 120, "quotaLeft": 480 }
  }
}

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.PPAY_WEBHOOK_SECRET; // whsec_...
const app = express();

function verify(raw, header, secret) {
  const parts = Object.fromEntries(String(header).split(",").map((p) => p.split("=")));
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;       // replay protection
  const expected = createHmac("sha256", secret).update(parts.t + "." + raw).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

// express.raw keeps the body exactly as received
app.post("/webhooks/ppay", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body.toString("utf8"), req.get("x-ppay-signature"), SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200);                                   // acknowledge first, then work
  if (event.type === "verification.completed") {
    // event.data.reference = your order number, event.data.valid = true/false
  }
});

<?php
$secret = getenv("PPAY_WEBHOOK_SECRET");
$raw    = file_get_contents("php://input");
$header = $_SERVER["HTTP_X_PPAY_SIGNATURE"] ?? "";

parse_str(str_replace(",", "&", $header), $p);           // t=...&v1=...
$expected = hash_hmac("sha256", ($p["t"] ?? "") . "." . $raw, $secret);

if (!isset($p["t"], $p["v1"]) || !hash_equals($expected, $p["v1"]) || abs(time() - (int)$p["t"]) > 300) {
    http_response_code(400);
    exit;
}
http_response_code(200);
$event = json_decode($raw, true);

import hmac, hashlib, time, os
from flask import Flask, request, abort

SECRET = os.environ["PPAY_WEBHOOK_SECRET"]
app = Flask(__name__)

def verify(raw: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", "")) and abs(time.time() - int(parts["t"])) <= 300

@app.post("/webhooks/ppay")
def hook():
    raw = request.get_data()                              # raw bytes, before JSON parsing
    if not verify(raw, request.headers.get("X-PPay-Signature", ""), SECRET):
        abort(400)
    event = request.get_json()
    return "", 200

import { readFile } from "node:fs/promises";

async function verifySlip(path) {
  const form = new FormData();
  form.append("file", new Blob([await readFile(path)], { type: "image/jpeg" }), "slip.jpg");

  const res = await fetch("https://ppay-slip.com/api/v1/verify", {
    method: "POST",
    headers: { Authorization: "Bearer " + process.env.PPAY_API_KEY },
    body: form,
  });
  const data = await res.json();

  if (res.status === 202) return { pending: true, jobId: data.jobId };   // busy: wait for the webhook / poll the job
  if (!res.ok) throw new Error(data.code + ": " + data.error);          // 401, 402, 429 ...
  return { pending: false, valid: data.valid, code: data.code, slip: data.slip };
}

async function queueSlip(path, orderNo) {
  const form = new FormData();
  form.append("file", new Blob([await readFile(path)], { type: "image/jpeg" }), "slip.jpg");
  form.append("reference", orderNo);                                     // comes back in the webhook

  const res = await fetch("https://ppay-slip.com/api/v1/verify/async", {
    method: "POST",
    headers: { Authorization: "Bearer " + process.env.PPAY_API_KEY },
    body: form,
  });
  if (res.status !== 202) throw new Error((await res.json()).code);
  return (await res.json()).jobId;                                       // store it next to the order
}

<?php
$ch = curl_init("https://ppay-slip.com/api/v1/verify");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer " . getenv("PPAY_API_KEY")],
    CURLOPT_POSTFIELDS     => ["file" => new CURLFile("slip.jpg", "image/jpeg", "slip.jpg")],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data   = json_decode($body, true);

if ($status === 202) { /* queued: use $data["jobId"] */ }
elseif ($status === 200 && $data["valid"]) { echo $data["slip"]["amount"]; }

import os, requests

r = requests.post(
    "https://ppay-slip.com/api/v1/verify",
    headers={"Authorization": "Bearer " + os.environ["PPAY_API_KEY"]},
    files={"file": ("slip.jpg", open("slip.jpg", "rb"), "image/jpeg")},
    timeout=30,
)
data = r.json()
if r.status_code == 202:
    job_id = data["jobId"]            # queued
elif r.ok and data["valid"]:
    print(data["slip"]["amount"])

curl -X POST https://ppay-slip.com/api/v1/verify \
  -H "Authorization: Bearer ppk_xxxxxxxx" \
  -F "file=@slip.jpg" \
  -F "shop=my-shop"

"shop": {
  "id": "7c1f...",
  "name": "ร้านของฉัน",
  "matched": true,          // true = โอนเข้าบัญชีของร้าน · false = โอนเข้าที่อื่น · null = ยังบอกไม่ได้
  "account": { "id": "a91c...", "label": "ธนาคารกสิกรไทย" }
}

curl -X POST https://ppay-slip.com/api/v1/invoices \
  -H "Authorization: Bearer ppk_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"shop":"my-shop","amount":590,"reference":"ORDER-1001","title":"สั่งซื้อสินค้า"}'

{
  "ok": true,
  "invoice": {
    "code": "k3n8xq2m7vbt4h9d",
    "status": "pending",
    "amount": 590,
    "currency": "THB",
    "reference": "ORDER-1001",
    "payUrl": "https://ppay-slip.com/pay/k3n8xq2m7vbt4h9d",
    "expiresAt": "2026-10-13T08:00:00.000Z",
    "paidAt": null
  }
}

{
  "id": "evt_...", "type": "invoice.paid", "apiVersion": "1", "createdAt": "...",
  "data": {
    "invoice": { "code": "k3n8xq2m7vbt4h9d", "reference": "ORDER-1001", "amount": 590, "paidAt": "..." },
    "shop": { "id": "7c1f...", "name": "ร้านของฉัน" },
    "slip": { "reference": "0158...", "amount": 590, "transferredAt": "...", "sender": {...}, "receiver": {...} }
  }
}

curl -X POST https://ppay-slip.com/api/v1/promptpay \
  -H "Authorization: Bearer ppk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"target":"081-234-5678","amount":100.50}'

{
  "ok": true,
  "payload": "00020101021229370016A0000006770101110113006681234567853037645406100.505802TH6304XXXX",
  "amount": 100.5,
  "currency": "THB",
  "target": { "type": "phone", "masked": "081xxxx678" },
  "qr": { "svg": "<svg ...>", "dataUrl": "data:image/svg+xml;base64,..." }
}