> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch Billers | BBPS API | Razorpay
> Retrieve a list of BBPS billers with filtering by category, geography and status using Razorpay's Bill Payments API.
Available in
🇮🇳 India
Use this endpoint to retrieve a list of billers on the Bharat Bill Payment System (BBPS). Filter by `category`, geographic coverage or status. Fetch a specific biller by `biller_id` or `gateway_biller_id`. The response includes the biller's configuration for payment, fees, additional info and account holder inputs. Use these to render the bill retrieval and payment UI.
**Incremental Sync**
Pass `updated_since` (Unix timestamp) to fetch only billers updated after a specific time. This is the recommended way to keep your local biller catalogue in sync without re-fetching the entire list.
```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET "https://api.razorpay.com/v1/bill_payments/billers?category=electricity&geo_coverage.state=KA&geo_coverage.city=Bengaluru&geo_coverage.country=IN&status=active&count=10&skip=0"
```
```json Success theme={null}
{
"entity": "collection",
"count": 1,
"items": [
{
"id": "biller_001",
"entity": "bill_payment.biller",
"gateway": "bbps",
"created_at": 1609459200,
"gateway_updated_at": 1689459200,
"gateway_biller_id": "TPOW00000MUM01",
"name": "Electricity Bill Payment",
"alias_name": "Electricity BP",
"category": "electricity",
"status": "active",
"supported_channels": ["online"],
"logo_url": "https://example.com/logos/electricity.png",
"effective_from": 1689459200,
"effective_to": 1735689600,
"geo_coverage": {
"country": "IND",
"state": "MH",
"city": "Mumbai"
},
"gateway_data": {
"biller_ownership_type": "Private",
"payment_config": {
"amount_exactness": "exact",
"bill_request_required": "mandatory",
"support_pending_status": "true",
"pending_timeout_period": 21600,
"methods": [
{
"method": "cash",
"min_limit": 100,
"max_limit": null,
"support_pending_status": false
},
{
"method": "upi",
"min_limit": 1,
"max_limit": null,
"support_pending_status": true
},
{
"method": "card",
"type": "credit",
"min_limit": 1,
"max_limit": null,
"support_pending_status": true
}
],
"amount_type": [
{
"name": "base_bill_amount",
"optional": false,
"data_type": "string",
"min_length": 2,
"max_length": 12,
"regex": "",
"values": "string",
"visibility": true
},
{
"name": "fixed_charges",
"optional": true,
"data_type": "string",
"min_length": 2,
"max_length": 12,
"regex": "",
"values": "string",
"visibility": true
}
],
"amount_groups": [
{
"components": ["base_bill_amount", "fixed_charges"]
},
{
"components": ["base_bill_amount"]
}
]
},
"channels": [
{
"channel": "internet",
"max_limit": 100000,
"min_limit": 100,
"support_pending_status": false
},
{
"channel": "pos",
"max_limit": 500000,
"min_limit": 1000,
"support_pending_status": true
}
],
"bill_request_config": {
"upms_supported": null,
"bill_response_type": "single/multiple",
"bill_request_required": "mandatory/optional/not_supported",
"plan_fetch_required": "mandatory/optional/not_supported"
},
"additional_info_config": {
"params": [
{
"name": "Customer Mobile Number",
"data_type": "numeric",
"optional": true,
"min_length": 10,
"max_length": 10,
"regex": "^[6-9]{1}[0-9]{9}$",
"values": ["Vehicle Finance", "Home Finance"],
"visibility": true
},
{
"name": "accountNumber",
"data_type": "string",
"optional": false,
"min_length": 9,
"max_length": 12,
"values": ["Vehicle Finance", "Home Finance"],
"visibility": true
}
]
},
"fee_config": {
"fee_types": [
{
"fee_code": "CCF1",
"fee_description": "Customer Convenience Fee",
"fee_payer": "customer",
"fee_details": {
"min_amount": 100,
"max_amount": 10000,
"percentage": 0.5,
"flat_amount": 2,
"effective_from": 1689459200,
"effective_to": 1735689600
}
}
],
"fee_rules": [
{
"transaction_type": "payment",
"response_code": "00",
"method": "card",
"type": "credit",
"channel": "AGT",
"fee_code": ["PFB", "CCF1"],
"default_fee": false,
"effective_from": 1689459200,
"effective_to": 1735689600
},
{
"transaction_type": "payment",
"response_code": "00",
"method": "upi",
"channel": "AGT",
"fee_code": ["CCF1", "CCF2"],
"default_fee": true,
"effective_from": 1689459200,
"effective_to": 1735689600
}
]
},
"account_holder_config": {
"params": [
{
"name": "Customer Mobile Number",
"data_type": "numeric",
"optional": true,
"min_length": 10,
"max_length": 10,
"regex": "^[6-9]{1}[0-9]{9}$",
"values": ["Vehicle Finance", "Home Finance"]
}
],
"param_group": {
"step": 1,
"group_name": "Group1",
"input_params_required": ["accountNumber"],
"required_input_count": 1,
"depends_on_step": null
}
}
}
}
]
}
```
```json Failure theme={null}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The category 'amazon' is not a valid BBPS category.",
"field": "category",
"source": "business",
"step": "validation",
"reason": "invalid_category"
}
}
```
## Query Parameters
Razorpay's internal biller entity id. Use to retrieve a specific biller by Razorpay id. For example, `biller_001`.
Filter billers by pre-defined BBPS biller category. Case-insensitive. For example, `electricity`, `loan_repayment`, `mobile_postpaid`.
BBPS-specific biller id assigned by NPCI. Use to retrieve a specific biller by NPCI id. For example, `TPOW00000MUM01`.
Fetch a specific biller by Razorpay biller id. For example, `biller_001`.
Filter billers by country. Defaults to `IN`.
Filter billers by state code. For example, `MH`, `DL`.
Filter billers by city. For example, `Bengaluru`, `Mumbai`.
Unix timestamp in seconds. Returns only billers updated after this time. Use for incremental sync of your local biller catalogue.
Filter billers by operational status. Values: `active`, `inactive`, `deactivated`.
Number of billers per page. Default is `10`. Maximum is `100`.
Number of biller records to skip for pagination. Default is `0`.
## Response Parameters
Entity type identifier. Here, `collection`.
Number of biller records returned.
Array of biller objects.
Razorpay biller entity id. Format: `biller_xxx`. Use this when creating a bill request or payment.
Entity type. Always `bill_payment.biller`.
Payment gateway. Defaults to `bbps`.
Biller creation timestamp in Razorpay records (Unix seconds).
Last update timestamp from the gateway (Unix seconds). Use for data freshness checks.
NPCI/BBPS provided biller id (max 20 characters). Use for NPCI reconciliation and audit trail.
Biller display name. Show this on the biller selection UI.
Biller alias or nickname shared in biller MDM. Optionally show alongside `name` for search and selection.
Biller category. Use for grouping and filtering on the UI.
Biller operational status. Values: `active`, `inactive`, `deactivated`. Show deactivated billers with a `deactivated` tag on the UI.
Biller support type. Values: `online`, `offline`. Use to make channel routing decisions.
Biller logo image URL. Not in NPCI standard - sourced by Razorpay for UI display.
Start date timestamp when biller becomes active on NPCI (Unix seconds).
End date timestamp when biller is deprecated on NPCI (Unix seconds). `null` if currently active.
Geographic coverage area for the biller.
Country code. For example, `IND`.
State code. For example, `MH`.
City name. For example, `Mumbai`.
Gateway-specific biller configuration.
Biller ownership. Values: `Government`, `PSU`, `Private`. Use to know whether the biller is private or government for audit trail.
Payment configuration supported by the biller.
Payment amount flexibility. Values:
* `exact` - user must pay the exact amount fetched.
* `exact_or_above` - user can pay exact amount or more.
* `exact_or_below` - user can pay exact amount or less.
* `any` - user can pay any amount.
Whether biller supports direct payment without bill request. Values: `mandatory`, `optional`, `not_supported`. Use to enable or disable the quick pay flow on the UI.
Whether the biller supports a `pending` payment state. Values: `true`, `false`. Use for async payment confirmation handling.
Timeout period in seconds supported by the biller when `support_pending_status` is `true`.
Payment methods accepted by the biller as per Razorpay nomenclature. Use to filter payment options for the customer.
Payment method code. Values: `netbanking`, `upi`, `card`, `wallet`.
For `card` method, sub-type such as `credit`, `debit`, `prepaid`.
Minimum transaction amount in paise for this method.
Maximum transaction amount in paise for this method. `null` for cash payments.
Whether this method supports pending status.
Amount breakup types supported in bill request response. Use to parse the bill retrieval response structure.
Allowed combinations of amount components. Each item contains a `components` array listing valid breakup combinations.
Initiating channels supported by the biller.
Initiating channel code. Values: `internet`, `mobile`, `pos`, `mpos`.
Minimum transaction amount in paise for this channel.
Maximum transaction amount in paise for this channel.
Whether this channel supports pending status.
Bill request configuration supported by the biller.
Type of bill response. Values: `single`, `multiple`.
Whether bill retrieval is required before payment. Values: `mandatory`, `optional`, `not_supported`.
Whether plan fetch is required. Values: `mandatory`, `optional`, `not_supported`.
Additional information configuration supported by the biller.
Additional information parameters required from the customer.
Parameter display name. For example, `Customer Mobile Number`.
Parameter data type. Values: `numeric`, `alphanumeric`, `alpha`, `date`.
Whether the parameter is optional.
Minimum character length.
Maximum character length.
Validation regex pattern.
Allowed enum values for the parameter.
Whether the parameter should be shown to the customer.
Fee configuration supported by the biller.
Fee types applicable.
Fee identifier. Values:
* `PFB` - Physical Biller Fee
* `EBF` - Electronic Biller Fee
* `CCF1` / `CCF2` - Customer Convenience Fee
* `AGSC` - Agent Service Charge
Customer-facing fee label. For example, `Customer Convenience Fee`.
Who pays the fee. Values: `B2C` (biller), `C2B` (customer).
Fee calculation parameters.
Minimum transaction amount for this fee tier in paise.
Maximum transaction amount for this fee tier in paise.
Percentage fee component. For example, `0.5` represents 0.5%.
Fixed fee component in paise.
Fee validity start timestamp (Unix seconds).
Fee validity end timestamp (Unix seconds). `null` if ongoing.
Rules determining which fee applies for a given transaction.
Transaction type. Values: `payment`, `fetch`, `validate`. Defaults to `payment`.
NPCI response code when fee applies. `00` represents success.
Payment method for this rule. For example, `Internet banking`, `upi`, `card`.
Sub-type of the payment method. Applies only when `method` is `card`. Values: `credit`, `debit`, `prepaid`. Use this to apply different fee rules for credit vs debit card payments.
Initiating channel for this rule. For example, `AGT`, `INT`, `MOB`.
Array of fee codes applicable. Apply multiple fees if listed.
Whether this is the default fee configuration. Used when no specific match is found.
Rule validity start timestamp (Unix seconds).
Rule validity end timestamp (Unix seconds).
Account holder configuration supported by the biller.
Customer input parameters required for bill retrieval. Use to build the bill retrieval input form.
Parameter display name. For example, `Customer Mobile Number`.
Input data type. Values: `numeric`, `alphanumeric`, `alpha`, `date`.
Whether the parameter is optional.
Minimum character length.
Maximum character length.
Validation regex pattern.
Allowed enum values for the parameter.
Combination and sequence of input parameters required for bill retrieval.
Sequence number of the input required from the customer.
NPCI group level identifier. Use to render multi-step forms with progressive disclosure.
List of field names the customer must provide in this step.
Minimum count of inputs required mandatorily from this step. Convert to string to render UI accordingly.
Which prior step must be completed. `null` if there is no dependency on a previous step.
## Errors
**Code:** `400`
The category provided does not match any BBPS category.
**Solution:** Use a valid BBPS category. Case-insensitive matching is supported.
**Code:** `400`
The biller id provided does not correspond to a valid biller.
**Solution:** Use a valid biller id returned by the Fetch Billers API.
**Code:** `400`
Count exceeds maximum limit of 100.
**Solution:** Pass a `count` value between 1 and 100.
**Code:** `400`
Invalid state. Possible values - state, city, country.
**Solution:** Pass a valid state code.
**Code:** `502`
NPCI did not respond within the timeout window.
**Solution:** Retry the request after a short interval.
**Code:** `401`
The API credentials passed in the request differ from the ones generated on the Dashboard.
**Solution:** Ensure your API key and secret are correct and active.