Reference

Tola Saint API

The Tola Saint API lets you accept KHQR payments and track their status. It's a small, predictable REST API — all requests use HTTPS and all responses are JSON.

Base URL

https://api.tolasaint.com

Amounts are always strings, never numbers — that keeps floating point out of money.

Payment rails

Payments can run over two rails: bakong (KHQR issued by the National Bank of Cambodia) or aba (an ABA PayWay hosted merchant link). The endpoints, request shape and webhooks are identical. What differs is the statuses each one can report.

// treat either success value as paid
if (res.status === "approved" || res.status === "paid") {
  fulfilOrder(res.id)
}

How they compare

Which rail a payment uses

Each rail has its own endpoint, so the simplest approach is to call the one you want: /v1/bakong for Bakong, /v1/payment for ABA. Either way the answer comes back in the provider field.

Authentication

Authenticate every request with your secret key in the x-api-key header.

curl https://api.tolasaint.com/v1/payment/status?id=AbC123 \
  -H "x-api-key: sk_live_your_key_here"

Health check

GET /health needs no key and is exempt from rate limiting — point an uptime monitor at it. It answers { "status": "ok" } when the service is up.

curl https://api.tolasaint.com/health

Errors & limits

Every error uses the same shape:

{ "error": "bad_request", "message": "Invalid amount" }

Status codes

Rate limits

120 requests per minute, counted per API key rather than per IP — one busy key can't spend another's budget. Request bodies are capped at 64 KB. Every response carries the current budget:

Create a KHQR payment. Returns a QR string, a hosted QR link, and an expiry.

Body parameters

curl -X POST https://api.tolasaint.com/v1/payment \
  -H "x-api-key: sk_live_..." \
  -H "content-type: application/json" \
  -d '{"amount":"1.00","currency":"USD","reference":"order-778"}'

Response fields

// 201 Created
{
  "id": "AbC123xyz789",
  "status": "pending",
  "provider": "bakong",
  "amount": "1.00",
  "currency": "USD",
  "qr_link": "https://api.tolasaint.com/qr/uQH8rR0AIv0djTnPLJ3N",
  "qr_string": "00020101021230510016abaakhppxxx...",
  "expires_at": "2026-01-01T00:03:00.000Z",
  "reference": "order-778"
}

Check a transaction by id.

Query parameters

curl "https://api.tolasaint.com/v1/payment/status?id=AbC123xyz789" \
  -H "x-api-key: sk_live_..."

Response fields

// 200 OK
{ "id": "AbC123xyz789", "amount": "1.00", "currency": "USD", "status": "approved", "provider": "aba" }

Status values

Terminal states never change again, so you can stop polling once you see one. Which statuses you'll actually see depends on the rail — see Payment rails.

// 200 OK — note "paid", not "approved"
{ "id": "AbC123xyz789", "amount": "1.00", "currency": "USD", "status": "paid", "provider": "bakong" }

Page through your payments, newest first. Every parameter is optional, so a bare call returns the 20 most recent.

Query parameters

curl "https://api.tolasaint.com/v1/payments?limit=20&status=approved" \
  -H "x-api-key: sk_live_..."

Response fields

Each item in data

// 200 OK
{
  "data": [
    {
      "id": "AbC123xyz789",
      "status": "approved",
      "provider": "aba",
      "amount": "1.00",
      "currency": "USD",
      "reference": "order-778",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:01:12.000Z",
      "paid_at": "2026-01-01T00:01:12.000Z",
      "expires_at": "2026-01-01T00:03:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

The qr_link renders the KHQR as a scannable image. It's a public capability URL protected by an unguessable token — embed it directly.

Path parameters

<img src="https://api.tolasaint.com/qr/uQH8rR0AIv0djTnPLJ3N" alt="KHQR" />

An <img> or Markdown embed gets a bare 300×300 SVG with a transparent background. Opening the link in a browser tab instead gets a centred page around the same image. Neither is cached.

The link stops working once the QR is dead

Create a KHQR payment on Bakong. Same job as /v1/payment, except the rail is fixed by the route — so there is no provider field, and you know exactly which statuses to expect.

The QR is built on our server rather than fetched from a bank, so this call makes no upstream request and cannot fail because Bakong is having a bad day. One Bakong account ID covers both USD and KHR.

Body parameters

curl -X POST https://api.tolasaint.com/v1/bakong \
  -H "x-api-key: sk_live_your_key_here" \
  -H "content-type: application/json" \
  -d '{"amount":"1.00","currency":"USD","reference":"order-778"}'

Response fields

// 201 Created
{
  "id": "AbC123xyz789",
  "status": "pending",
  "provider": "bakong",
  "amount": "1.00",
  "currency": "USD",
  "qr_link": "https://api.tolasaint.com/qr/uQH8rR0AIv0djTnPLJ3N",
  "qr_string": "00020101021229190015your_name@aclb...",
  "expires_at": "2026-01-01T00:03:00.000Z",
  "reference": "order-778"
}

Check a Bakong payment by id. Refuses ABA payments with 400 wrong_provider, so a caller integrating against this route only ever sees the three statuses below.

Query parameters

curl "https://api.tolasaint.com/v1/bakong/status?id=AbC123xyz789" \
  -H "x-api-key: sk_live_your_key_here"

Response fields

// 200 OK
{
  "id": "AbC123xyz789",
  "amount": "1.00",
  "currency": "USD",
  "status": "paid",
  "provider": "bakong"
}

Status values

That's the whole set. Bakong has no scanned, processing or failed: a transaction is either in the ledger or it isn't, so there is nothing in between to report.

Lifetime totals for your account — the same figures the dashboard Overview shows. Takes no parameters.

curl https://api.tolasaint.com/v1/stats \
  -H "x-api-key: sk_live_..."

Response fields

// 200 OK
{
  "total": 181,
  "by_status": {
    "pending": 0,
    "scanned": 0,
    "processing": 0,
    "approved": 9,
    "paid": 4,
    "failed": 2,
    "expired": 170
  },
  "pending_now": 0,
  "approved_volume": { "USD": "4.12", "KHR": "0" },
  "success_rate": 0.07
}

success_rate is a fraction, so multiply by 100 for a percentage. Expired payments count as settled, which is why an expiring QR drags the rate down. approved_volume and success_rate both count approved and paid, so the figures already cover both rails.

Webhooks

When a payment changes status, Tola Saint sends a signed POST to your webhook URL for scanned, processing, approved, paid, failed, and expired. Nothing is sent for pending.

A Bakong payment only ever fires two of those: paid or expired. So a handler that keys off approved alone will never hear about a Bakong sale.

Request headers we send

Payload fields

{
  "id": "AbC123xyz789",
  "reference": "order-778",
  "amount": "1.00",
  "currency": "USD",
  "status": "approved",
  "provider": "aba",
  "paid_at": "2026-01-01T00:01:12.000Z",
  "occurred_at": "2026-01-01T00:01:13.000Z"
}

Delivery

Verify signatures

Recompute HMAC-SHA256(secret, timestamp + "." + rawBody) and compare to the x-webhook-signature header.

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

function verify(headers, rawBody, secret) {
  const ts = headers["x-webhook-timestamp"];
  const sig = headers["x-webhook-signature"] || "";
  const expected =
    "sha256=" + createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  const a = Buffer.from(sig), b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}