The same rails, without the receipt paper.
Billers, bill fetch, payments and signed webhooks. Four endpoints deep enough to put a bill counter inside your own app or POS.
Overview
The counter UI is a thin client over five routes. These are the shapes an integration receives: biller metadata, a fetched bill, a payment with a URN, a ledger row.
All requests are JSON, all amounts are rupees as numbers (not paise), all timestamps are ISO 8601 in IST. Amounts use two decimal places in responses.
Authentication
Two headers identify the counter, one signs the body. Keys are issued per agent code; the secret stays on your server and never ships to a browser.
Authorization: Bearer sk_live_4471a2
X-Agent-Code: AGT-4471-2290
X-Timestamp: 1763363280
X-Signature: sha256=5c1f…e9b2
# signature = hex( HMAC-SHA256( secret, timestamp + "." + raw_body ) )
The signature is checked against the raw body — re-serialising the JSON on the way in breaks it. Requests older than five minutes are rejected with signature_expired.
Biller directory
{
"count": 1,
"items": [
{
"id": "bescom",
"name": "BESCOM",
"cat": "electricity",
"region": "Karnataka",
"consumerLabel": "Account ID (RR number)",
"sample": "4827 1190 33"
}
]
}
Categories are the eleven families the counter ships with: electricity, water, gas, dth, broadband, fastag, insurance, loan, municipal, housing, education. consumerLabel is what the UI prints above the input — do not invent your own wording, the bill itself uses these names.
Bill fetch
curl -X POST https://api.pratirupanatech.com/v1/bills/fetch \ -H "authorization: Bearer sk_live_4471a2" \ -H "content-type: application/json" \ -d '{"billerId":"bescom","consumerNumber":"4827119033"}'
{
"biller": { "id": "bescom", "name": "BESCOM", "cat": "electricity" },
"customerName": "Anitha Rao",
"consumerNumber": "4827119033",
"billNumber": "BE/2026/04471",
"billPeriod": "Oct 2026",
"amount": 1240,
"lateFee": 0,
"payable": 1240,
"dueDate": "2026-11-24T00:00:00.000Z",
"fee": { "convenience": 5, "gst": 0.9, "total": 5.9 },
"payableWithFee": 1245.9
}
Fetching never debits. If the biller is unreachable the route returns 502 biller_timeout with a retry hint, and the counter shows the retry control rather than a dead end.
Create a payment
{
"billerId": "bescom",
"consumerNumber": "4827119033",
"amount": 1240,
"method": "upi",
"detail": "anitha@okhdfc"
}
{
"status": "SUCCESS",
"urn": "BBPSBESC4471229088",
"txnId": "PC4471200",
"paidAt": "2026-11-17T06:38:04.118Z",
"amount": 1240,
"fee": { "convenience": 5, "gst": 0.9, "total": 5.9 },
"total": 1245.9
}
A PENDING response is not a failure. The biller has accepted the request, confirmation is asynchronous, and the webhook closes the loop.
Payments are idempotent on Idempotency-Key. Send one per attempt, and a retry after a timeout returns the original outcome instead of a second debit.
Receipt and URN
The URN is the receipt's spine: BBPS + the biller's four-character code + ten digits. It is what a customer quotes at the biller's office and what an agent's ledger row stores. The counter prints it on every receipt, including pending ones.
- Receipt fields: URN, transaction id, biller, consumer, customer, bill number, period, amount, convenience fee, GST, total, method, status, timestamp.
- Formats: 72mm thermal, A4 print, CSV export. The CSV is the reconciliation artefact for the day.
- Verification: a URN plus the biller id is enough to re-query the payment; the biller's own reference (
billerRef) is included for support calls.
Webhooks
Events arrive signed with the same secret as requests. Respond 200 within 8 seconds; anything else is retried at 1m, 5m, 30m, 2h, 6h, then parked for manual review.
POST https://your-app.example/hooks/pratirupana
X-Timestamp: 1763363280
X-Signature: sha256=9ad1…33c0
{
"event": "payment.success",
"urn": "BBPSBESC4471229088",
"txnId": "PC4471200",
"status": "SUCCESS",
"amount": 1240,
"commission": 14.26,
"agentCode": "AGT-4471-2290",
"occurredAt": "2026-11-17T06:38:04.118Z"
}
Events: payment.success, payment.pending, payment.failed, payment.refunded. Deliveries are at-least-once — dedupe on txnId plus status.
Error codes
Rate limits
Writes are limited to 30 a minute per agent code and reads to 600. Bursts are queued rather than dropped, up to ten seconds of outstanding work.
429 rate_limitedcarries aRetry-Afterheader in seconds — back off and retry, do not fan out.- Limits are per agent code and per key; a shared IP does not pool the budget.
- Ceilings rise with volume. Ask your account manager for a review before a festival or a new counter goes live.
Webhook endpoints are exempt from the write limit, but deliveries stop after six failed attempts and are parked for manual replay.