API Reference

The public REST API for connecting your system (POS / ERP / bot) to SlipBolt. Authenticate with an API key (sk_live_… / sk_test_…) — see Authentication

Base URL

https://api.slip-bolt.com/api/v1

Every request needs the header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /api/v1/verify

Verify one transfer slip — 5 ways to send it: raw bytes (recommended) · multipart/form-data · JSON image (base64) · JSON url · JSON qr

Request

A JSON body takes exactly one of image / url / qr · the examples below use raw bytes · every other way, in every language, is in Recipes

curl -X POST https://api.slip-bolt.com/api/v1/verify \
  -H "Authorization: Bearer $SLIPBOLT_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@slip.jpg"

// Node.js 18+ — no extra packages needed
import { readFile } from 'node:fs/promises';

const res = await fetch('https://api.slip-bolt.com/api/v1/verify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SLIPBOLT_API_KEY}`,
    'Content-Type': 'application/octet-stream',
  },
  body: await readFile('slip.jpg'),
});
const body = await res.json();

if (!res.ok) {
  // 402 quota used up · 429 too many requests (wait for Retry-After) · 401/403 key or permission
  throw new Error(`${res.status} ${body.code ?? body.error}: ${body.message}`);
}

const slip = body.data; // the result is always under data
if (slip.verified && !slip.duplicate) {
  console.log(`Received ${slip.amount} THB from ${slip.senderName} · ref ${slip.transRef}`);
} else {
  console.log(`Not passed: ${slip.status}`, slip.errorMessage ?? '');
}

# pip install requests
import os
import requests

with open("slip.jpg", "rb") as f:
    res = requests.post(
        "https://api.slip-bolt.com/api/v1/verify",
        headers={
            "Authorization": f"Bearer {os.environ['SLIPBOLT_API_KEY']}",
            "Content-Type": "application/octet-stream",
        },
        data=f.read(),
        timeout=30,
    )

body = res.json()
if not res.ok:
    # 402 quota used up · 429 too many requests (wait for Retry-After) · 401/403 key or permission
    raise RuntimeError(f"{res.status_code} {body.get('code') or body.get('error')}: {body.get('message')}")

slip = body["data"]  # the result is always under data
if slip["verified"] and not slip["duplicate"]:
    print(f"Received {slip['amount']} THB from {slip['senderName']} · ref {slip['transRef']}")
else:
    print("Not passed:", slip["status"], slip.get("errorMessage") or "")

<?php
// Uses ext-curl, available on almost every host — no Composer needed
$ch = curl_init('https://api.slip-bolt.com/api/v1/verify');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('SLIPBOLT_API_KEY'),
        'Content-Type: application/octet-stream',
    ],
    CURLOPT_POSTFIELDS     => file_get_contents('slip.jpg'),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$raw    = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($raw === false) {
    throw new RuntimeException('Connection failed: ' . curl_error($ch));
}

$body = json_decode($raw, true);
if ($status !== 200) {
    // 402 quota used up · 429 too many requests (wait for Retry-After) · 401/403 key or permission
    throw new RuntimeException("$status " . ($body['code'] ?? $body['error']) . ': ' . $body['message']);
}

$slip = $body['data']; // the result is always under data
if ($slip['verified'] && !$slip['duplicate']) {
    echo "Received {$slip['amount']} THB from {$slip['senderName']} · ref {$slip['transRef']}\n";
} else {
    echo "Not passed: {$slip['status']} " . ($slip['errorMessage'] ?? '') . "\n";
}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "8f3c…",
    "status": "SUCCESS",
    "verified": true,
    "source": "API",
    "transRef": "015170106978META…",
    "amount": 250.0,
    "bankCode": "002",
    "bankName": "ธนาคารกรุงเทพ",
    "senderName": "นาย ก. …",
    "senderAccount": "xxx-x-x1234-x",
    "receiverName": "ร้าน ข.",
    "receiverAccount": "xxx-x-x5678-x",
    "receiverBankCode": "014",
    "receiverBankName": "ธนาคารไทยพาณิชย์",
    "transDate": "2026-06-17T03:21:05.000Z",
    "errorCode": null,
    "errorMessage": null,
    "createdAt": "2026-06-17T03:21:06.412Z",
    "receipt": { "code": "SB-7K2F-9QX4", "checkUrl": "https://slip-bolt.com/c/PyuMHlp9Tp-wwdLj9KW2xzQ1dGhVb2xr" },
    "duplicate": false,
    "cached": false,
    "latencyMs": 480,
    "environment": "live",
    "quota": { "used": 132, "limit": 500, "remaining": 368 }
  },
  "meta": { "requestId": "3b1f0c9e-6a2d-4f5e-8b7c-1d2e3f4a5b6c", "timestamp": "2026-06-17T03:21:06.412Z" }
}

verified is true only when status === "SUCCESS" — see the status table below. Bank and account names are returned as printed on the slip (usually Thai script); error messages are in Thai. meta.requestId matches the response's X-Request-Id header — log it for when you contact support.

Examples of a slip that did not pass

Every case below is HTTP 200 — the request succeeded, the verdict on the slip is "not passed" (only the fields that differ from the example above are shown)

{
  "id": "8f3c2a1e-…",
  "status": "DUPLICATE",
  "verified": false,
  "transRef": "015170106978META…",
  "amount": 250.0,
  "errorCode": null,
  "errorMessage": null,
  "duplicate": true,
  "cached": false
}

{
  "id": "5d21b7c4-…",
  "status": "RECEIVER_MISMATCH",
  "verified": false,
  "transRef": "015170106978META…",
  "amount": 250.0,
  "receiverName": "นาย ค. …",
  "receiverAccount": "xxx-x-x9999-x",
  "errorCode": null,
  "errorMessage": null,
  "duplicate": false,
  "cached": false
}

{
  "id": "a41f0e63-…",
  "status": "INVALID",
  "verified": false,
  "transRef": null,
  "amount": 0,
  "bankCode": null,
  "senderName": null,
  "receiverName": null,
  "transDate": null,
  "errorCode": "INVALID",
  "errorMessage": "…",
  "duplicate": false,
  "cached": false
}

{
  "id": "c7e9d250-…",
  "status": "FRAUD",
  "verified": false,
  "transRef": null,
  "amount": 0,
  "bankCode": null,
  "senderName": null,
  "receiverName": null,
  "transDate": null,
  "errorCode": "FRAUD",
  "errorMessage": "…",
  "duplicate": false,
  "cached": false
}

• DUPLICATE returns the original transaction's data (id · transRef · amount are from the first verification) — use transRef to find which order already used this slip
• RECEIVER_MISMATCH · AMOUNT_MISMATCH were read in full, so transRef / amount / receiver are there to show where the money went · errorCode is null — branch on status
• INVALID · FRAUD carry no slip data you can trust — transRef is null and amount is 0

Fields in data

The first group (through createdAt) is the same shape GET /transactions returns — one parser handles both

Quota — one pool with LINE slips

API calls use the same monthly quota as the shop's LINE slips (one pool, counted together) — not a separate quota; whichever channel is used draws from the same pool

Every response (including GET /api/v1/quota) carries headers with the balance:

{ "success": false, "statusCode": 402, "error": "Payment Required",
  "message": "โควตาสลิปรายเดือนและเครดิตของร้านถูกใช้หมดแล้ว — ซื้อเครดิต อัปเกรดแพ็ก หรือรอรอบบิลถัดไป",
  "code": "QUOTA_EXCEEDED", "quota": { "used": 500, "limit": 500, "remaining": 0 } }

GET /api/v1/quota

Read the remaining quota without spending a verify — good for polling before a big batch

curl "https://api.slip-bolt.com/api/v1/quota" \
  -H "Authorization: Bearer $SLIPBOLT_API_KEY"

const res = await fetch('https://api.slip-bolt.com/api/v1/quota', {
  headers: { Authorization: `Bearer ${process.env.SLIPBOLT_API_KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.message}`);

const q = body.data;
console.log(`${q.remaining}/${q.limit} slips left · resets in ${q.daysUntilReset} days`);

import os
import requests

res = requests.get(
    "https://api.slip-bolt.com/api/v1/quota",
    headers={"Authorization": f"Bearer {os.environ['SLIPBOLT_API_KEY']}"},
    timeout=15,
)
res.raise_for_status()
data = res.json()["data"]
print(f"{data['remaining']}/{data['limit']} slips left · resets in {data['daysUntilReset']} days")

<?php
$ch = curl_init('https://api.slip-bolt.com/api/v1/quota');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('SLIPBOLT_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
]);
$body = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
    throw new RuntimeException($body['message'] ?? 'request failed');
}
$q = $body['data'];
echo "{$q['remaining']}/{$q['limit']} slips left · resets in {$q['daysUntilReset']} days\n";

{
  "success": true,
  "data": {
    "used": 132,
    "limit": 500,
    "remaining": 368,
    "percentUsed": 26,
    "allowOverage": false,
    "planCode": "STARTER",
    "periodMonth": "2026-06",
    "daysUntilReset": 13,
    "creditsAvailable": 0
  }
}

creditsAvailable = remaining slip credits (pay as you go) — used once the plan quota runs out, before any overage is charged. A shop with no monthly plan but with credits can still verify slips · remaining is still the plan quota only ⇒ total slips you can still verify ≈ remaining + creditsAvailable

GET /api/v1/me

Shop · key · plan · remaining quota — uses no quota; good to call when your system boots to check the key belongs to the right shop, has the scopes it needs, how many slips are left, and which receiving account the receiver check compares against (the number-one cause of RECEIVER_MISMATCH is a shop that hasn't added the account customers pay into)

During the 7-day trial plan.code is "TRIAL" and quota.limit is always 50, even if the shop picked the Pro/Business card at signup — paid-plan entitlements start only after payment

curl "https://api.slip-bolt.com/api/v1/me" \
  -H "Authorization: Bearer $SLIPBOLT_API_KEY"

const res = await fetch('https://api.slip-bolt.com/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.SLIPBOLT_API_KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.message}`);

const me = body.data;
console.log(me.shop.name, me.plan.code, me.apiKey.scopes, me.quota.remaining);

import os
import requests

res = requests.get(
    "https://api.slip-bolt.com/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['SLIPBOLT_API_KEY']}"},
    timeout=15,
)
res.raise_for_status()
data = res.json()["data"]
print(data["shop"]["name"], data["plan"]["code"], data["apiKey"]["scopes"], data["quota"]["remaining"])

<?php
$ch = curl_init('https://api.slip-bolt.com/api/v1/me');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('SLIPBOLT_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
]);
$body = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
    throw new RuntimeException($body['message'] ?? 'request failed');
}
$me = $body['data'];
echo $me['shop']['name'], ' ', $me['plan']['code'], ' ', $me['quota']['remaining'], "\n";

{
  "success": true,
  "data": {
    "shop": { "id": "8f3c…", "name": "ร้าน ข." },
    "apiKey": {
      "name": "POS หน้าร้าน",
      "prefix": "sk_live_a1b2c3",
      "environment": "live",
      "scopes": ["verify", "read"],
      "lastUsedAt": "2026-06-17T03:21:06.000Z",
      "createdAt": "2026-05-01T00:00:00.000Z"
    },
    "plan": { "code": "STARTER", "name": "Starter" },
    "quota": { "used": 132, "limit": 500, "remaining": 368, "percentUsed": 26,
      "overage": 0, "allowOverage": false, "planCode": "STARTER",
      "periodMonth": "2026-06", "daysUntilReset": 13 },
    "credits": { "available": 0, "usedThisMonth": 0, "nextExpiry": null },
    "testQuota": { "used": 12, "limit": 200, "remaining": 188 },
    "rateLimit": { "perKeyPerMinute": 120, "verifyPerMinute": 240 },
    "payeeAccounts": [
      { "bankCode": "kbank", "kind": "BANK", "holder": "ร้าน ข.", "accountLast4": "5678", "isPrimary": true, "status": "ACTIVE" }
    ]
  }
}

payeeAccounts[].bankCode is a slug (kbank), not the 3-digit code used in slip results (004) — map them with the Bank codes table

GET /api/v1/transactions

List the shop's slip results — newest first, cursor-paginated, across every channel (API / LINE / Dashboard). Useful when a POST /verify dropped mid-flight (timeout / network cut) and you want the real result without resending the slip

curl "https://api.slip-bolt.com/api/v1/transactions?status=SUCCESS&limit=20" \
  -H "Authorization: Bearer $SLIPBOLT_API_KEY"

// Fetch every passed slip this month — page until nextCursor is null
// Use Thai time (+07:00) — a bare date = midnight UTC = misses the first 7 hours of the 1st
const now = new Date();
const from = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-01T00:00:00+07:00`;
let cursor = null;
do {
  const url = new URL('https://api.slip-bolt.com/api/v1/transactions');
  url.searchParams.set('status', 'SUCCESS');
  url.searchParams.set('from', from);
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.SLIPBOLT_API_KEY}` },
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status}: ${body.message}`);

  for (const tx of body.data.items) console.log(tx.transRef, tx.amount, tx.senderName);
  cursor = body.data.nextCursor;
} while (cursor);

import os
from datetime import date
import requests

# Use Thai time (+07:00) — a bare date = midnight UTC = misses the first 7 hours of the 1st
month_start = date.today().replace(day=1).isoformat() + "T00:00:00+07:00"
params = {"status": "SUCCESS", "from": month_start, "limit": 100}
while True:
    res = requests.get(
        "https://api.slip-bolt.com/api/v1/transactions",
        headers={"Authorization": f"Bearer {os.environ['SLIPBOLT_API_KEY']}"},
        params=params,
        timeout=15,
    )
    res.raise_for_status()
    page = res.json()["data"]
    for tx in page["items"]:
        print(tx["transRef"], tx["amount"], tx["senderName"])
    if not page["nextCursor"]:
        break
    params["cursor"] = page["nextCursor"]

<?php
// Use Thai time (+07:00) — a bare date = midnight UTC = misses the first 7 hours of the 1st
$params = ['status' => 'SUCCESS', 'from' => date('Y-m-01') . 'T00:00:00+07:00', 'limit' => 100];
do {
    $ch = curl_init('https://api.slip-bolt.com/api/v1/transactions?' . http_build_query($params));
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('SLIPBOLT_API_KEY')],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
    ]);
    $body = json_decode(curl_exec($ch), true);
    if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
        throw new RuntimeException($body['message'] ?? 'request failed');
    }
    foreach ($body['data']['items'] as $tx) {
        echo $tx['transRef'], ' ', $tx['amount'], ' ', $tx['senderName'], "\n";
    }
    $params['cursor'] = $body['data']['nextCursor'];
} while ($params['cursor']);

{
  "success": true,
  "data": {
    "items": [ { "id": "8f3c…", "status": "SUCCESS", "verified": true, "…": "…" } ],
    "nextCursor": "7ab1…"
  }
}

Send nextCursor back as cursor to fetch the next page · null = no more pages

GET /api/v1/transactions/:id

Fetch one slip result — pair it with webhooks (take data.transactionId from the event, then fetch the full details). Another shop's transaction and a non-existent id both return 404 (we don't confirm whether the id exists)

curl https://api.slip-bolt.com/api/v1/transactions/8f3c2a1e-… \
  -H "Authorization: Bearer $SLIPBOLT_API_KEY"

GET /api/v1/transactions/:id/receipt.png · receipt.pdf

The verification receipt for a passed slip — the same image customers get from the LINE bot / LIFF ("Verified · genuine slip" header · amount · sender → receiver · reference · QR + confirmation code) Hand it to your own customers as-is (chat · email · order page)

• The QR opens a check page at slip-bolt.com/c/… — anyone holding the image can scan it to confirm SlipBolt really issued it (that page shows partly-masked details) · the same link and code are in data.receipt of the result
• The receipt cannot be used in place of a transfer slip, and says so on its face — it proves "this slip passed verification", not the transfer itself
• ?maskSender=true — masks the sender's name ("สมชาย ใจ***") and leaves out the sender's account number · use it when the image will be posted where many people see it
• Rendered on every request; we keep no file — store the image yourself if you need it again · PNG is 784px wide · the PDF is one page the size of the receipt
• A slip that didn't pass (status ≠ SUCCESS) or whose details were deleted under the shop's retention period → 409 · another shop's / unknown id → 404 · limit 30 requests/minute per IP

curl https://api.slip-bolt.com/api/v1/transactions/8f3c2a1e-…/receipt.png \
  -H "Authorization: Bearer $SLIPBOLT_API_KEY" \
  -o receipt.png

POST /api/v1/verify/async

Verify a slip without waiting — answers 202 within milliseconds and keeps checking in the background. Good for shops that send slips in batches or don't want a request held open while the bank answers · body/headers/scope are identical to POST /verify (including Idempotency-Key)

curl -i -X POST https://api.slip-bolt.com/api/v1/verify/async \
  -H "Authorization: Bearer $SLIPBOLT_API_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @slip.jpg

HTTP/1.1 202 Accepted
Location: /api/v1/verifications/vrf_3f9a1c0b7e2d4a6f8b1c2d3e

{
  "success": true,
  "data": {
    "id": "vrf_3f9a1c0b7e2d4a6f8b1c2d3e",
    "status": "PENDING",
    "createdAt": "2026-10-22T03:21:06.412Z",
    "completedAt": null,
    "statusUrl": "/api/v1/verifications/vrf_3f9a1c0b7e2d4a6f8b1c2d3e",
    "result": null,
    "error": null
  },
  "meta": { "requestId": "…", "timestamp": "…" }
}

Two ways to get the result (use both if you like):

1. Webhook verification.completed — tick this event on your endpoint in Settings → Webhooks (payload)
2. Poll GET /api/v1/verifications/{id} every 1–2 seconds (does not spend a verify)

GET /api/v1/verifications/:id

error.code on FAILED (error.httpStatus = the status POST /verify would have returned in the same case):

• Results are kept for 24 h, then 404 — the permanent record is GET /transactions/{result.id}
• An id from another shop / a key of the other environment (sk_live_ vs sk_test_) → 404
• Same Idempotency-Key + same slip = the same 202 (same id · Idempotent-Replayed: true), no new job · async keys are separate from POST /verify (the same value on both routes does not collide)
• Pending jobs per shop are capped (50 by default) — when full you get 429 code: "ASYNC_QUEUE_FULL" + Retry-After
• Our queue is temporarily unavailable → 503 code: "ASYNC_UNAVAILABLE" — send to POST /verify instead

Scopes

A key can hold several scopes — an endpoint requires every scope it lists (configure them at Settings → API Keys)

Missing scope → 403 Forbidden · message: "API key missing scope(s): verify" (no code — full shape in Error envelope). A revoked key gets 401 from the very next request — there is no cache window

Health check

No key needed · doesn't use your quota or the key's rate limit · Cache-Control: no-store · limited to 120 requests/minute per IP

{ "status": "degraded", "checks": { "database": "ok", "queue": "ok", "verification": "degraded" }, "timestamp": "2026-10-21T08:00:00.000Z" }

• degraded = still verifying, but on the fallback path (may be slower) · down = can't verify right now — pause sending and retry
• Point your uptime monitor at /api/v1/ready · overall status and incident history are on the status page

Rate limit

120 req/min per key (same on every plan) + a combined ceiling of 240 req/min on POST /api/v1/verify. Over the limit → 429 Too Many Requests + a Retry-After header + code: "RATE_LIMITED" (tell it apart from SPEND_CAP_EXCEEDED / ASYNC_QUEUE_FULL by code) · see Authentication

Headers on every response:

Transaction status

• Only SUCCESS counts against quota — every non-pass outcome, duplicates, cached: true and sk_test_ keys cost the shop no quota or credits · quotaCharged tells you for each request
• GET /transactions?status= accepts all 8 values in this table (anything else → 400)
• A request answered with cached: true does not fire the webhook again — the event is sent once, on the first verification

errorCode in a slip result

There are two places a code appears, and they are different sets — data.errorCode (a successful 200 request · explains the verdict) and code in the error envelope (4xx)

data.errorCode — inside a slip result (POST /verify · GET /transactions)

code — inside the error envelope (Error envelope) · only these three cases have it; other errors carry no code field

Stale slip

A genuine slip reused on a new order still passes the bank check (the bank confirms the transfer exists, not that it "just happened"). So we compare the transfer time (transDate) with the time it was submitted — older than 24 hours, or future-dated, gets the STALE_SLIP flag · checked only on passing slips — a slip that fails for another reason (e.g. RECEIVER_MISMATCH) carries no STALE_SLIP even when old, since it did not pass anyway

{
  "status": "SUCCESS",
  "verified": true,
  "transDate": "2026-06-15T03:21:05.000Z",
  "errorCode": "STALE_SLIP",
  "errorMessage": "สลิปลงวันที่ย้อนหลังเกิน 24 ชม. (เก่า 48 ชม.)",
  "warnings": [{ "code": "STALE_SLIP", "message": "สลิปลงวันที่ย้อนหลังเกิน 24 ชม. (เก่า 48 ชม.)" }]
}

Idempotency

Deduplication is automatic — three different cases:

• The "same image" sent again within 24 hours → cached: true · status/verified are the real result of the original transaction (safe to retry after a network cut/timeout — not re-verified, no quota used)
• The same transRef already verified (a different image file / re-shot photo) → duplicate: true and status is always "DUPLICATE" in this response (verified: false) — whatever the first verification's result was
• Resending the image of a slip that already answered DUPLICATE → still DUPLICATE (duplicate: true together with cached: true) — the cached replay of the original result only applies to an image the API itself verified first · a slip that came in through LINE or the Dashboard earlier is DUPLICATE every time it is sent to the API

Idempotency-Key — retry the same request with no side effects

cached only covers "the same image, byte for byte, already verified" · if your system retries on a timeout while the first request is still running, or you want the exact same answer back (including the first call's quotaCharged), send an Idempotency-Key header — a value unique per request, such as a UUID or your order id

curl -X POST https://api.slip-bolt.com/api/v1/verify \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @slip.jpg

• Kept for 24 hours per shop (sk_live_ and sk_test_ keys are separate · other shops can use the same value without colliding)
• "The same slip" is compared on the decoded image — a fresh multipart body (new boundary) still counts as the same request
• The envelope's meta.requestId/timestamp belong to the current request · the X-Slipbolt-Quota-* headers show the current balance
• No header = exactly the old behaviour (optional)

Error envelope

Every error has the same shape:

{
  "success": false,
  "error": "Forbidden",
  "message": "API key missing scope(s): read",
  "statusCode": 403,
  "path": "/api/v1/quota",
  "requestId": "3b1f0c9e-6a2d-4f5e-8b7c-1d2e3f4a5b6c",
  "timestamp": "2026-06-17T03:30:45.120Z"
}

code is present only on some errors (both 402s · the plan 403 · the IDEMPOTENCY_* codes on 400/409/422 · METHOD_NOT_ALLOWED on 405 — see the code table) · other errors have no such field, so branch on statusCode · message is a string, except a validation 400 with several problems, where it is an array of strings · requestId matches that response's X-Request-Id header — quote it when contacting support

Branch on statusCode and code — never match on the message text (wording may change without counting as a breaking change). A client that already retries per this table is in Recipes

Bank codes

bankCode / receiverBankCode in a slip result (and in webhooks) are the 3-digit bank code as returned by the banking network. payeeAccounts[].bankCode in GET /me is the slug the shop picked when adding its receiving account — the two formats don't compare directly; map them with this table

Slugs with no 3-digit code (not banks): promptpay (kind: "PROMPTPAY") · truemoney (kind: "WALLET") · other (a bank the shop typed in)

Next

• Webhooks — receive slip.verified / slip.duplicate / slip.fraud / slip.failed events, HMAC-signed, instead of polling
• Authentication — key details · quota per plan · rate limit