Bill payment
A QR printed on an invoice, statement, utility bill, traffic fine, or parking ticket. The customer scans, confirms, pays.
Bill payment is the pattern for charging once-off amounts that are presented to the customer on a printed or emailed document — invoices, monthly statements, utility bills, insurance premiums, municipal accounts, traffic fines, parking tickets, school fees. You generate one QR per bill, with the exact amount and a unique reference. The customer scans, confirms, and pays.
This is one of the highest-volume use cases on the platform. Implementation-wise, it's a specialised flavour of Dynamic QR — same POST /code/create endpoint, same response shape, same webhook. The differences are in the parameters you set and how you render the QR.
Wallet providersThis page is for merchants and billers who issue bills. If you run a wallet and want your customers to pay bills, buy airtime or donate from a biller menu inside your app (natively, or with the Scan to Pay hosted bill menu in a webview), see Bill payments and VAS.
When to use bill payment
| ✅ Good fit | ❌ Wrong fit |
|---|---|
| Customer receives a document (paper or email) with the amount owed | Real-time POS purchases (use Dynamic QR instead) |
| Single transaction per document, predictable amount | Subscriptions and recurring payments — use Pay-for-Me from the wallet side instead |
| Multi-day or multi-week payment window (until bill is due) | "Pay within 30 seconds" interactive checkouts |
| Reference number is critical for reconciliation (account number, invoice number) | Generic merchandise where any reference works |
The flow
Your billing system Scan to Pay Customer
─────────────────── ─────────── ────────
│ │ │
│ for each new bill: │ │
│ POST /code/create │ │
├───────────────────────────►│ │
│ │ │
│◄──── code ─────────────────┤ │
│ │
│ render QR on the bill │
│ (PDF, paper, email) │
│ │
│ ─────────── deliver bill to customer ─────────►│
│ │
│ │ (customer pays
│ │ any time before
│ │ the code expires)
│ │
│ │ webhook (CB) │
│ │◄───────────────────┤
│ │ ack 200 │
│ ├───────────────────►│
│ │
│◄────── reconcile bill ──── webhook ─────────────│
│ as paid │
Two things make this pattern distinctive:
- The customer pays asynchronously, possibly days or weeks after you generate the code. The code's expiry must be set to match the bill due date.
- Your
merchantReferenceis meaningful — typically the account number, invoice number, or bill identifier from your billing system. You use it to reconcile the webhook against the customer's account.
Generate the code
curl -X POST "https://qa.scantopay.io/pluto/code/create" \
-u "$USERNAME:$PASSWORD" \
-H 'Content-Type: application/json' \
-d '{
"merchantReference": "ACC-12345678-INV-2025-04",
"amount": 487.50,
"useOnce": true,
"shortDescription": "Acme Utilities — April account",
"expiryDate": 1748908800000
}'| Field | Notes |
|---|---|
merchantReference | Your bill's unique reference — account number + invoice number is a common pattern. The platform enforces uniqueness per merchant. |
amount | The exact amount owed in your merchant's currency. |
useOnce: true | The bill can only be paid once. Default. |
shortDescription | Shown to the customer in their wallet when they scan. 5–45 characters. Make it recognisable — the customer should immediately understand which bill they're paying. |
expiryDate | Set to the bill's last-payable date (in epoch milliseconds). Default of 30 minutes is wrong for bill payment — always set this explicitly to a date in the future. |
If useOnce: true and the customer accidentally scans the same printed QR twice, the second scan returns 455 CODE_USED rather than charging them twice.
Render the QR on the bill
Two options, same as for any QR payment:
Option A — Scan to Pay-rendered PNG. Pull the styled QR from /public/stpqr/{code} and embed it into your PDF bill template, your email template, or your printed statement run. See Rendering the QR.
For print-quality, use the unstyled variant:
GET https://qa.scantopay.io/pluto/public/stpqr/0123456789?plain=true
Then render your own scheme branding around it on the bill template.
Option B — render the QR yourself. Generate a QR encoding the 10-digit code value using any library. Suitable for high-volume print runs where you want full control over layout and minimum API calls.
Print at high resolution (at least 300 DPI), minimum 4 cm × 4 cm physical size. Include a quiet zone around the QR — the styled stpqr template does this automatically.
Reconcile the payment
When the customer pays, your webhook handler receives the standard transaction notification payload. The key fields:
reference— matches themerchantReferenceyou set (e.g.ACC-12345678-INV-2025-04)amount— what the customer paid (will match the bill amount, sinceuseOnce: truecodes can't be modified by the customer)status—SUCCESSis the only positive valuetransactionId— Scan to Pay's internal ID, useful for your reconciliation reports
Match reference to your billing system's bill record. Mark the bill as paid. Notify your downstream systems (account-credit posting, statement generation, etc.).
For full webhook handling, see Webhooks.
Bill not yet paid?
Two ways to check:
| You have | Action |
|---|---|
| The 10-digit code | GET /code/{code} — returns the current state. Available means unpaid; Used means paid; Deleted means cancelled. |
Only the merchantReference | POST /code/queryRef — returns the transaction state once the bill has been paid. Returns N/A if the customer hasn't paid yet. |
See Managing QR codes and Querying transactions.
Cancelling a bill
If the bill is corrected, void, or the customer pays through another channel, cancel the code so the QR can no longer be paid:
curl -X DELETE "https://qa.scantopay.io/pluto/code/0123456789" \
-u "$USERNAME:$PASSWORD"The code transitions to Deleted and scans against the printed QR return an error. You cannot un-delete — if you need to re-issue the bill, generate a new code with a fresh merchantReference.
Long expiry windows — security note
Bill payment codes typically have weeks-long expiries to match billing cycles. Two consequences:
- Lost or photographed bills can be paid by anyone who has the QR image. That's by design — a QR is a bearer instrument. But if you receive a customer query about a "stolen bill" payment, you'll need to handle it as a refund rather than a fraud reversal.
- Stale codes accumulate. Build a job that periodically lists codes older than your retention policy and deletes them.
What's next
- Render the QR for print or email → Rendering the QR
- Manage codes after creation → Managing QR codes
- Receive the payment notification → Webhooks
- Check status from your side → Querying transactions
- Refund if the customer overpaid or the bill was wrong → Refunds and reversals
- Sandbox test the bill flow → Sandbox and test cards
Updated 15 days ago
