BBPS Bill Payment API on Bharat Connect

What the BBPS API does

Bharat Connect is the current name of the Bharat Bill Payment System (BBPS), the interoperable bill payment network run by NPCI Bharat BillPay Ltd. A payment made through Bharat Connect reaches the biller through a standard process. The customer gets a Bharat Connect transaction reference, and a complaint can be raised through the same network if something goes wrong.

The Payonclick BBPS API puts that network behind a single REST interface. Your application can:

• list the live bill categories and search billers inside each one
• read the exact input fields a biller needs (consumer number, K number, subscriber ID and so on)
• fetch the customer's current bill and show the amount, due date and name before payment
• pay the bill from your prepaid wallet and receive the Bharat Connect transaction ID
• check status, pull payment history and raise or track complaints

Every call uses the same API key, request signature and response format as our verification API. One integration therefore covers more than one product.

Bill categories you can offer

The API currently exposes 30 categories. Availability is returned live on every catalogue call. If an operator switches a category off for a while, is_available comes back false with a reason you can show your user.

How a bill payment flows

Billers come in two kinds, and the API tells you which one you are dealing with:

• Fetch billers (most electricity, water and gas boards) must be fetched first. If the biller has no bill for that customer, the fetch fails with BILL_FETCH_FAILED and no token is issued. A blind payment is therefore not possible.
• Ad-hoc billers (for example most DTH operators) do not support fetch. They still issue a bill_token, marked allow_manual_amount: true, so your user can enter the recharge amount.

Always echo each field name from GET /biller/{id} exactly as returned. Bharat Connect rejects a fetch whose parameter names don't match the biller's definition.

Built so a bill is never paid twice

Payment APIs fail in two expensive ways: a customer charged twice, or a payment wrongly marked as failed. The API is designed around both.

Idempotency. Every payment carries your client_reference. If your request times out, send it again with the same reference. The API returns the original transaction with duplicate: true instead of paying again. Using a new reference for the same intent is the only way to create a second payment.

Honest status. Bharat Connect does not always confirm a payment the instant it is submitted, so a payment can return PENDING.

Automatic refunds. If the biller reports a failure, the amount goes back to your wallet before the status response says FAILED. Nothing is left for you to reverse by hand.

One payment at a time. While a payment on your account is still in flight, a second one returns PAYMENT_IN_PROGRESS. Retry it with the same reference.

Security and authentication

The API is meant to be called server to server:

• API key sent as a Bearer token, issued as poc_live_ followed by 64 hex characters. Only a hash is stored on our side.
• Timestamp on every call, accepted within five minutes of server time.
• HMAC-SHA256 signature on every POST and DELETE. It is computed over the method, the full path, the timestamp and the SHA-256 of the exact body bytes, so a tampered payload is rejected before it reaches Bharat Connect.
• Scopes, IP whitelist and rate limit per key. A key needs the bills permission to pay, only whitelisted server IPs are accepted, and the default quota is 60 requests a minute.
• TPIN on each payment. It locks after five wrong attempts.

message   = "POST\n/ext/v1/bbps/bill/pay\n{timestamp}\n{sha256(body)}"
signature = HMAC-SHA256(key = api_key, msg = message)

Webhooks, history and complaints

You do not have to poll for every result. Register an HTTPS endpoint and the platform pushes bill.success, bill.failed and bill.pending events. Each delivery is signed in the X-POC-Signature header, so you can check it came from us.

For reconciliation and support, the API also provides:

• GET /transaction/{reference_id} and a lookup by your own client_reference
• GET /transactions, paginated history filtered by status and date range
• POST /complaint to raise a Bharat Connect complaint on a successful payment. Complaint types: amount not adjusted, duplicate payment, wrong amount, wrong account, service not received, service disconnected.
• GET /complaint/{complaint_id} to track the complaint to resolution

Wallet, limits and going live

Payments are debited from your prepaid MAIN wallet. Each payment can be between ₹1 and ₹2,00,000. GET /balance returns your balance with the limits currently in force, so you can validate an amount before sending it.

There is no separate sandbox host: keys are issued live. Build and test against the read-only endpoints first (/balance, /categories, /billers, /biller/{id}). They move no money. Then run your first real payment with a small bill.

Onboarding and commercial terms depend on your use case and volume. Share a few details in the form below and our team will send them.