About BBPS Integration
Integrate Bharat Bill Payment System (BBPS) with Razorpay to enable customers to pay utility bills, recharges, insurance, and more on your platform.
Razorpay is a licensed Customer Operating Unit (COU) on the
, India's centralised, interoperable bill payment platform managed by NPCI. Using Razorpay's BBPS integration, your platform can let customers discover billers, fetch bill amounts, and make payments across hundreds of utility categories.BBPS bill payments follow an asynchronous, multi-step flow:
- Fetch Biller Categories - retrieve all available bill categories (electricity, water, gas, broadband, insurance, etc.).
- Fetch Billers - list billers within a chosen category.
- Fetch Biller Plans(optional) - retrieve plans offered by a biller where applicable (e.g. prepaid recharges).
- Create a Bill Request - submit the customer's biller-specific identifiers (account number, consumer ID, etc.) to fetch the outstanding bill amount from the biller.
- Poll Bill Request - poll the Fetch Bill Request API until the status becomes
successorfailed. - Create a Bill Payment - initiate payment for the fetched bill amount.
- Poll Bill Payment - poll the Fetch Bill Payment API until the status becomes
successorfailed.
Watch Out!
Bill Request and Bill Payment APIs are asynchronous. After creating a resource, always poll the corresponding Fetch API at regular intervals until the status reaches a terminal state (success or failed). Do not assume success based on the creation response alone.
Before you begin:
- Complete on the Razorpay Dashboard.
- Ensure your account has BBPS access enabled. Contact if you need it activated.
- Use your Test API Keys during development. Payments made with test keys are not processed on the live BBPS network.
Use the
API to retrieve all supported bill categories. Present these to your customer so they can choose the type of bill they want to pay. Use the returnedid in Step 2.Use the
API with the selectedcategory to retrieve all billers within that category. Each biller includes a gateway_data.account_holder_config.params list describing the customer inputs (for example, consumer number, account number) needed to identify the customer's account on the biller. Use gateway_data.bill_request_config.bill_request_required to decide whether bill fetch is mandatory, optional, or unsupported.For billers that offer plans (such as prepaid recharges), use the
API to retrieve available plans. Skip this step if the biller does not offer plans.Use the
API to fetch the outstanding bill amount for your customer from the biller's system. This API returns immediately with aprocessing status - move to Step 5 to poll for the result.Use the
API with theid returned in Step 4. Poll at regular intervals until status is success or failed. On success, use the returned bills[].amount and bills[].bill_number in Step 6.Watch Out!
Always wait for the Bill Request status to reach success before creating a Bill Payment. A failed status means the biller could not retrieve the bill - surface an appropriate error to the customer.
Use the
API with thebill_request_id from the successful bill request and the bills[].amount returned. Pass a unique X-Bill-Payments-Idempotency header (4-36 characters, alphanumeric with hyphens, underscores, or spaces; UUID v4 recommended) on every request to safely retry without creating duplicate payments. This API is asynchronous - move to Step 7 to poll for the result.Use the
API with theid returned in Step 6. Poll until status is success or failed, then display the result to your customer.BBPS supports a wide range of bill categories, including but not limited to:
Was this page helpful?