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 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 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
Creates a QR payment and returns it with a QR string and checkout URL.
| amount | number, required | Amount to charge, in USD. Minimum 0.01. |
| reference_id | string, optional | Your own order id (≤ 255 chars). Echoed back and included in webhooks. |
| metadata | object, optional | Arbitrary JSON, returned as-is on the payment. |
| idempotency_key | string, optional | Safely retry without creating duplicates (≤ 255). May also be sent as the Idempotency-Key header. |
Response · 201 Created (or 200 on an idempotent replay)
{
"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
Fetch the current state of a single payment — poll this if you’re not using webhooks.
curl https://tospay.com/v1/payments/PUETcMUOKStjZsCb6zAl8kg9fMRGM85x \ -H "Authorization: Bearer tp_live_..."
List payments
Returns your store’s payments, newest first, under a data array.
| status | string, optional | Filter by status (e.g. paid). |
| limit | number, optional | How many to return (default 20, max 100). |
curl "https://tospay.com/v1/payments?status=paid&limit=20" \ -H "Authorization: Bearer tp_live_..."
Check 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.
{
"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
| id | string | Unique payment id (used in checkout_url and lookups). |
| status | string | One of pending, scanned, paid, expired, failed. |
| amount | string | Decimal string, e.g. "1.50". |
| currency | string | Always "USD". |
| reference_id | string | null | The reference you supplied. |
| qr_string | string | Raw QR (EMV) payload. On create/list. |
| checkout_url | string | Hosted branded checkout page. On create/list. |
| metadata | object | null | Metadata you attached. On retrieve. |
| approved_at | string | null | ISO 8601 time the payment was paid. |
| created_at | string | ISO 8601 creation time. |
| expires_at | string | ISO 8601 expiry (~5 minutes after creation). |
Payment statuses
| Status | Terminal | Meaning |
|---|---|---|
| pending | no | Created; waiting for the customer to scan and pay. |
| scanned | no | The QR was scanned; the customer is confirming in their banking app. |
| paid | yes | Paid successfully. Counts toward quota and fires payment.completed. |
| expired | yes | The QR expired unpaid (~5 minutes). |
| failed | yes | The payment failed. |
QR image (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.
<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.
| Event | Fires when | Status |
|---|---|---|
| payment.completed | A payment is paid | paid |
| payment.scanned | The QR is scanned | scanned |
| payment.expired | A payment expires unpaid | expired |
| payment.failed | A payment fails | failed |
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
{
"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.
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.
{ "error": "amount_too_low", "message": "Minimum amount is 0.01" }| Code | HTTP | When |
|---|---|---|
| unauthorized | 401 | Missing or invalid API key. |
| quota_exceeded | 402 | Transaction limit for the current period reached. |
| rate_limited | 429 | Too many requests — back off and retry. |
| invalid_request | 400 | The request body failed validation. |
| invalid_amount | 400 | Amount has more than 2 decimal places. |
| amount_too_low | 400 | Amount is below 0.01. |
| amount_too_high | 400 | Amount is above the link’s maximum. |
| payment_link_disabled | 400 | The store’s payment link is disabled. |
| payment_not_found | 404 | No such payment for your store. |
| payment_provider_error | 502 | The 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.
| Plan | Included / month | Stores | Price |
|---|---|---|---|
| Free | 50 transactions | 3 | $0 |
| Starter | 1,000 transactions | 10 | $9 / mo |
| Pro | 5,000 transactions | 25 | $29 / mo |
| Scale | 15,000 transactions | 100 | $59 / mo |
| Enterprise | 100,000 transactions | 500 | $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.