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 providers

This 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 owedReal-time POS purchases (use Dynamic QR instead)
Single transaction per document, predictable amountSubscriptions 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:

  1. 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.
  2. Your merchantReference is 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
  }'
FieldNotes
merchantReferenceYour bill's unique reference — account number + invoice number is a common pattern. The platform enforces uniqueness per merchant.
amountThe exact amount owed in your merchant's currency.
useOnce: trueThe bill can only be paid once. Default.
shortDescriptionShown 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.
expiryDateSet 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 the merchantReference you set (e.g. ACC-12345678-INV-2025-04)
  • amount — what the customer paid (will match the bill amount, since useOnce: true codes can't be modified by the customer)
  • status — SUCCESS is the only positive value
  • transactionId — 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 haveAction
The 10-digit codeGET /code/{code} — returns the current state. Available means unpaid; Used means paid; Deleted means cancelled.
Only the merchantReferencePOST /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


Did this page help you?