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.

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"

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",
  "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" }

Status values

Terminal states never change again, so you can stop polling once you see one.

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.

Webhooks

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

Request headers we send

Payload fields

{
  "id": "AbC123xyz789",
  "reference": "order-778",
  "amount": "1.00",
  "currency": "USD",
  "status": "approved",
  "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);
}