TosPay API

TosPay lets you accept QR payments in Cambodia with a simple REST API, real-time webhooks, and a hosted, branded checkout page. Create a payment, show the customer a QR code, and get notified the moment it’s paid.

The API is organized around a single resource — the payment. All requests use HTTPS, are authenticated with an API key, and return JSON. Amounts are in USD.

Authentication

Authenticate every request with your secret API key in the Authorization header as a bearer token. Create and manage keys under Dashboard → API keys. Each key belongs to one store; the key alone identifies which store (and payment link) a request acts on.

cURL
curl https://tospay.com/v1/payments/PUETcMUOKStjZsCb6zAl8kg9fMRGM85x \
  -H "Authorization: Bearer tp_live_..."

Keep secret keys (tp_live_…) on your server — never in client-side code. Missing or invalid keys return 401 unauthorized.

Quickstart

Create a payment for $1.50. You don’t need a payment-link id — TosPay uses your store’s link automatically.

cURL
curl https://tospay.com/v1/payments \
  -H "Authorization: Bearer tp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1.50, "reference_id": "order_1024" }'

Redirect the customer to checkout_url (a hosted, branded page) or render qr_string as a QR in your own UI. When they pay, the payment’s status becomes paid and a webhook fires.

Create a payment

POST/v1/payments

Creates a QR payment and returns it with a QR string and checkout URL.

amountnumber, requiredAmount to charge, in USD. Minimum 0.01.
reference_idstring, optionalYour own order id (≤ 255 chars). Echoed back and included in webhooks.
metadataobject, optionalArbitrary JSON, returned as-is on the payment.
idempotency_keystring, optionalSafely retry without creating duplicates (≤ 255). May also be sent as the Idempotency-Key header.

Response · 201 Created (or 200 on an idempotent replay)

json
{
  "id": "PUETcMUOKStjZsCb6zAl8kg9fMRGM85x",
  "status": "pending",
  "amount": "1.50",
  "currency": "USD",
  "reference_id": "order_1024",
  "qr_string": "00020101021229...6304AB12",
  "checkout_url": "https://tospay.com/pay/PUETcMUOKStjZsCb6zAl8kg9fMRGM85x",
  "approved_at": null,
  "created_at": "2026-07-09T12:00:00.000Z",
  "expires_at": "2026-07-09T12:05:00.000Z"
}

Retrieve a payment

GET/v1/payments/:id

Fetch the current state of a single payment — poll this if you’re not using webhooks.

cURL
curl https://tospay.com/v1/payments/PUETcMUOKStjZsCb6zAl8kg9fMRGM85x \
  -H "Authorization: Bearer tp_live_..."

List payments

GET/v1/payments

Returns your store’s payments, newest first, under a data array.

statusstring, optionalFilter by status (e.g. paid).
limitnumber, optionalHow many to return (default 20, max 100).
cURL
curl "https://tospay.com/v1/payments?status=paid&limit=20" \
  -H "Authorization: Bearer tp_live_..."

Check usage

GET/v1/usage

Where your account stands in the current period — the same numbers that decide whether a create call is accepted. Quota is per account and pooled across every store.

json
{
  "plan": "pro",
  "limit": 5000,
  "used": 1284,
  "remaining": 3716,
  "period_start": "2026-09-12T04:31:07.000Z",
  "period_end": "2026-10-12T04:31:07.000Z"
}

The payment object

idstringUnique payment id (used in checkout_url and lookups).
statusstringOne of pending, scanned, paid, expired, failed.
amountstringDecimal string, e.g. "1.50".
currencystringAlways "USD".
reference_idstring | nullThe reference you supplied.
qr_stringstringRaw QR (EMV) payload. On create/list.
checkout_urlstringHosted branded checkout page. On create/list.
metadataobject | nullMetadata you attached. On retrieve.
approved_atstring | nullISO 8601 time the payment was paid.
created_atstringISO 8601 creation time.
expires_atstringISO 8601 expiry (~5 minutes after creation).

Payment statuses

StatusTerminalMeaning
pendingnoCreated; waiting for the customer to scan and pay.
scannednoThe QR was scanned; the customer is confirming in their banking app.
paidyesPaid successfully. Counts toward quota and fires payment.completed.
expiredyesThe QR expired unpaid (~5 minutes).
failedyesThe payment failed.

QR image (SVG)

GET/api/render/khqr/:qr.svg

Put a QR string in a URL and get the finished QR back as an SVG. Free, no API key, and it works with any valid payment QR. :qr is the raw payload, percent-encoded.

html
<img
  src="https://tospay.com/api/render/khqr/00020101021229...6304AB12.svg"
  alt="Scan to pay 1.50 USD"
  width="360"
/>

Rendered at ECC level H. A corrupted string returns 400 invalid_khqr.

Webhooks

Add endpoints under Dashboard → Webhooks. TosPay POSTs a JSON event to each enabled endpoint when a payment changes state.

EventFires whenStatus
payment.completedA payment is paidpaid
payment.scannedThe QR is scannedscanned
payment.expiredA payment expires unpaidexpired
payment.failedA payment failsfailed

Each request carries an X-TosPay-Event header and an X-TosPay-Signature header. Respond with any 2xx to acknowledge; anything else is retried with exponential backoff up to 8 times.

Event payload

json
{
  "id": "b3f1c2a0-9e2d-4a1b-8c7f-1e2d3c4b5a6f",
  "type": "payment.completed",
  "created": "2026-07-09T12:03:11.000Z",
  "data": {
    "payment": {
      "id": "PUETcMUOKStjZsCb6zAl8kg9fMRGM85x",
      "status": "paid",
      "amount": "1.50",
      "currency": "USD",
      "reference_id": "order_1024",
      "metadata": null,
      "approved_at": "2026-07-09T12:03:10.000Z"
    }
  }
}

Verifying webhook signatures

The X-TosPay-Signature header looks like t=1720526591,v1=<hex>. Compute an HMAC-SHA256 of `${t}.${rawBody}` with your endpoint’s signing secret and compare to v1. Always use the raw body and compare in constant time.

Node.js
import crypto from "node:crypto"

const header = req.get("X-TosPay-Signature") ?? ""
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
const expected = crypto
  .createHmac("sha256", process.env.TOSPAY_WEBHOOK_SECRET)
  .update(`${parts.t}.${rawBody}`)
  .digest("hex")

const valid = crypto.timingSafeEqual(
  Buffer.from(parts.v1), Buffer.from(expected),
)

Errors

Errors return the right HTTP status and a JSON body with a machine-readable code and a human message.

json
{ "error": "amount_too_low", "message": "Minimum amount is 0.01" }
CodeHTTPWhen
unauthorized401Missing or invalid API key.
quota_exceeded402Transaction limit for the current period reached.
rate_limited429Too many requests — back off and retry.
invalid_request400The request body failed validation.
invalid_amount400Amount has more than 2 decimal places.
amount_too_low400Amount is below 0.01.
amount_too_high400Amount is above the link’s maximum.
payment_link_disabled400The store’s payment link is disabled.
payment_not_found404No such payment for your store.
payment_provider_error502The payment provider was unreachable — retry.

Rate limits & plans

A successful (paid) payment counts as one transaction. Quota covers a 30-day period and is shared across all stores on your account.

PlanIncluded / monthStoresPrice
Free50 transactions3$0
Starter1,000 transactions10$9 / mo
Pro5,000 transactions25$29 / mo
Scale15,000 transactions100$59 / mo
Enterprise100,000 transactions500$200 / mo

Separately, the API is rate limited per key: 60 payment creations per minute and 600 reads per minute. Need help? Email support@tospay.com.