Invoices, utility bills and fees¶

On this page

What: have an invoice that is valid for several days (SMS, e-mail, a QR on paper) paid with Gerege App — without double payment. Time: ~2 hours. You need: the backend from web checkout.

1. Why not send `pay_url` directly¶

An intent's expires_in is at most 1800 s (30 min), and pay_url is the claim's bearer secret. Send pay_url by SMS/e-mail for an invoice that waits several days, and by the time the person opens it it has already expired — and anyone it was forwarded to can claim it. Until long-lived intents arrive («coming soon»), send your own link.

2. The pattern — your link, an intent at the moment it is opened¶

SMS / e-mail / paper QR:  https://bills.example.mn/pay/inv_2026_10_0042     ← your URL, not a secret, no amount
        │ the person opens it
        ▼
your backend:  is the invoice paid? → yes: a «Төлөгдсөн» ("Paid") page
               no: is the current attempt's intent open?
                     yes: create with the same Idempotency-Key + same body → THAT pay_url (200)
                     no:  attempt+1, a new redirect intent (expires_in 900)
               → 303 pay_url

reference = the invoice number; Idempotency-Key = <invoice>-<attempt>.
A repeated POST with the same key + the same body returns the same intent and the same pay_url — so store each attempt's body (amount, description, return_url, expires_in) and send exactly that (a different body → 409 idempotency_conflict).
To protect your URL: a hard-to-guess number (a random ID), or a signed token; the page may show the amount and the payee's name — it is not a payment secret.

3. Preventing double payment¶

Before creating a new attempt, GET /payment-intents?reference=<invoice>&status=succeeded — if it is paid, do not create another.
If it was opened on two devices at once, both attempts may get paid — detect it from the webhook/reconciliation and refund the extra one with POST …/refunds.
For an invoice that can be paid in parts, work out each attempt's amount from the remaining balance.

4. Paper invoices and QR¶

The QR's content = your link (above), ≥ 25 mm, error correction M. Print the invoice number in human-readable form.
description = something like «Нэхэмжлэх №0042 · 2026-10» ("Invoice No. 0042 · 2026-10") — it appears on the person's wallet statement.
Utility bills (monthly) — a new invoice every month, a new reference.

5. Implementation status¶

Part	Status
Your link → a `redirect` intent at the moment it is opened (the pattern above)	✓
Intents valid for several days (long `expires_in`), a link to Gerege's own invoice	«coming soon»