Introduction

API Reference Guide

Understand Razorpay APIs

Authentication

Sandbox Setup

Install CLI

Best Practices

Glossary

Payments

Orders

Payments

Settlements

Refunds

Customers

Payment Links

Invoices

Subscriptions

Route

Api

Bills

Bill Payments

Fetch Billers

API Test Keys

Fetch Billers

GET
/v1/bill_payments/billers

Click to copy

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.

Is this page helpful?

Curl

1
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2
-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"

Success

Failure

1
{
2
  "entity": "collection",
3
  "count": 1,
4
  "items": [
5
    {
6
      "id": "biller_001",
7
      "entity": "bill_payment.biller",
8
      "gateway": "bbps",
9
      "created_at": 1609459200,
10
      "gateway_updated_at": 1689459200,
11
      "gateway_biller_id": "TPOW00000MUM01",
12
      "name": "Electricity Bill Payment",
13
      "alias_name": "Electricity BP",
14
      "category": "electricity",
15
      "status": "active",
16
      "supported_channels": ["online"],
17
      "logo_url": "https://example.com/logos/electricity.png",
18
      "effective_from": 1689459200,
19
      "effective_to": 1735689600,
20
      "geo_coverage": {
21
        "country": "IND",
22
        "state": "MH",
23
        "city": "Mumbai"
24
      },
25
      "gateway_data": {
26
        "biller_ownership_type": "Private",
27
        "payment_config": {
28
          "amount_exactness": "Exact",
29
          "bill_request_required": "mandatory",
30
          "support_pending_status": "true",
31
          "biller_timeout_period": 21600,
32
          "methods": [
33
            {
34
              "method": "cash",
35
              "min_limit": 100,
36
              "max_limit": null,
37
              "support_pending_status": false
38
            },
39
            {
40
              "method": "upi",
41
              "min_limit": 1,
42
              "max_limit": null,
43
              "support_pending_status": true
44
            },
45
            {
46
              "method": "card",
47
              "type": "credit",
48
              "min_limit": 1,
49
              "max_limit": null,
50
              "support_pending_status": true
51
            }
52
          ],
53
          "channels": [
54
            {
55
              "channel": "AGT",
56
              "max_limit": 100000,
57
              "min_limit": 100,
58
              "support_pending_status": false
59
            },
60
            {
61
              "channel": "BNKBRNCH",
62
              "max_limit": 500000,
63
              "min_limit": 1000,
64
              "support_pending_status": true
65
            }
66
          ],
67
          "amount_type": [
68
            {
69
              "name": "base_bill_amount",
70
              "optional": false,
71
              "data_type": "string",
72
              "min_length": 2,
73
              "max_length": 12,
74
              "regex": "<regex_pattern>",
75
              "values": "string",
76
              "visibility": true
77
            },
78
            {
79
              "name": "fixed_charges",
80
              "optional": true,
81
              "data_type": "string",
82
              "min_length": 2,
83
              "max_length": 12,
84
              "regex": "<regex_pattern>",
85
              "values": "string",
86
              "visibility": true
87
            }
88
          ],
89
          "amount_groups": [
90
            {
91
              "components": ["base_bill_amount", "fixed_charges"]
92
            },
93
            {
94
              "components": ["base_bill_amount"]
95
            }
96
          ]
97
        },
98
        "bill_request_config": {
99
          "upms_supported": null,
100
          "bill_response_type": "single/multiple",
101
          "bill_request_required": "mandatory/optional/not_supported",
102
          "plan_fetch_required": "mandatory/optional/not_supported"
103
        },
104
        "additional_info_config": {
105
          "params": [
106
            {
107
              "name": "Customer Mobile Number",
108
              "data_type": "numeric",
109
              "optional": true,
110
              "min_length": 10,
111
              "max_length": 10,
112
              "regex": "^[6-9]{1}[0-9]{9}$",
113
              "values": ["Vehicle Finance", "Home Finance"],
114
              "visibility": true
115
            },
116
            {
117
              "name": "accountNumber",
118
              "data_type": "string",
119
              "optional": false,
120
              "min_length": 9,
121
              "max_length": 12,
122
              "values": ["Vehicle Finance", "Home Finance"],
123
              "visibility": true
124
            }
125
          ]
126
        },
127
        "fee_config": {
128
          "fee_types": [
129
            {
130
              "fee_code": "CCF1",
131
              "fee_description": "Customer Convenience Fee",
132
              "fee_payer": "customer",
133
              "fee_details": {
134
                "min_amount": 100,
135
                "max_amount": 10000,
136
                "percentage": 0.5,
137
                "flat_amount": 2,
138
                "effective_from": 1689459200,
139
                "effective_to": 1735689600
140
              }
141
            }
142
          ],
143
          "fee_rules": [
144
            {
145
              "transaction_type": "payment",
146
              "response_code": "00",
147
              "method": "card",
148
              "type": "credit",
149
              "channel": "AGT",
150
              "fee_code": ["PFB", "CCF1"],
151
              "default_fee": false,
152
              "effective_from": 1689459200,
153
              "effective_to": 1735689600
154
            },
155
            {
156
              "transaction_type": "payment",
157
              "response_code": "00",
158
              "method": "upi",
159
              "channel": "AGT",
160
              "fee_code": ["CCF1", "CCF2"],
161
              "default_fee": true,
162
              "effective_from": 1689459200,
163
              "effective_to": 1735689600
164
            }
165
          ]
166
        },
167
        "account_holder_config": {
168
          "params": [
169
            {
170
              "name": "Customer Mobile Number",
171
              "data_type": "numeric",
172
              "optional": true,
173
              "min_length": 10,
174
              "max_length": 10,
175
              "regex": "^[6-9]{1}[0-9]{9}$",
176
              "values": ["Vehicle Finance", "Home Finance"]
177
            }
178
          ],
179
          "input_groups": {
180
            "step": 1,
181
            "group_name": "Group1",
182
            "input_params_required": ["accountNumber"],
183
            "required_input_count": 1,
184
            "depends_on_step": null
185
          }
186
        }
187
      }
188
    }
189
  ]
190
}
Query Parameters
id
string

Razorpay's internal biller entity id. Use to retrieve a specific biller by Razorpay id. For example, biller_001.

category
string

Filter billers by pre-defined BBPS biller category. Case-insensitive. For example, electricity, loan_repayment, mobile_postpaid.

gateway_biller_id
string

BBPS-specific biller id assigned by NPCI. Use to retrieve a specific biller by NPCI id. For example, TPOW00000MUM01.

biller_id
string

Fetch a specific biller by Razorpay biller id. For example, biller_001.

geo_coverage.country
string

Filter billers by country. Defaults to IN.

geo_coverage.state
string

Filter billers by state code. For example, MH, DL.

geo_coverage.city
string

Filter billers by city. For example, Bengaluru, Mumbai.

updated_since
integer

Unix timestamp in seconds. Returns only billers updated after this time. Use for incremental sync of your local biller catalogue.

status
string

Filter billers by operational status. Values: active, deactivated.

count
integer

Number of billers per page. Default is 10. Maximum is 100.

skip
integer

Number of biller records to skip for pagination. Default is 0.

Response Parameters
entity
string

Entity type identifier. Here, collection.

count
integer

Number of biller records returned.

items
array

Array of biller objects.

items[].id
string

Razorpay biller entity id. Format: biller_xxx. Use this when creating a bill request or payment.

items[].entity
string

Entity type. Always bill_payment.biller.

items[].gateway
string

Payment gateway. Defaults to bbps.

items[].created_at
integer

Biller creation timestamp in Razorpay records (Unix seconds).

items[].gateway_updated_at
integer

Last update timestamp from the gateway (Unix seconds). Use for data freshness checks.

items[].gateway_biller_id
string

NPCI/BBPS provided biller id (max 20 characters). Use for NPCI reconciliation and audit trail.

items[].name
string

Biller display name. Show this on the biller selection UI.

items[].alias_name
string

Biller alias or nickname shared in biller MDM. Optionally show alongside name for search and selection.

items[].category
string

Biller category. Use for grouping and filtering on the UI.

items[].status
string

Biller operational status. Values: active, inactive. Show inactive billers with a deactivated tag on the UI.

items[].supported_channels
array

Biller support type. Values: online, offline. Use to make channel routing decisions.

items[].logo_url
string

Biller logo image URL. Not in NPCI standard - sourced by Razorpay for UI display.

items[].effective_from
integer

Start date timestamp when biller becomes active on NPCI (Unix seconds).

items[].effective_to
integer

End date timestamp when biller is deprecated on NPCI (Unix seconds). null if currently active.

items[].geo_coverage
object

Geographic coverage area for the biller.

items[].geo_coverage.country
string

Country code. For example, IND.

items[].geo_coverage.state
string

State code. For example, MH.

items[].geo_coverage.city
string

City name. For example, Mumbai.

items[].gateway_data
object

Gateway-specific biller configuration.

items[].gateway_data.biller_ownership_type
string

Biller ownership. Values: Government, PSU, Private. Use to know whether the biller is private or government for audit trail.

items[].gateway_data.payment_config
object

Payment configuration supported by the biller.

items[].gateway_data.payment_config.amount_exactness
string

Payment amount flexibility. Values:

  • Exact - user must pay the exact amount fetched.
  • Exact and above - user can pay exact amount or more.
  • Exact and below - user can pay exact amount or less.
  • Any - user can pay any amount.

items[].gateway_data.payment_config.bill_request_required
string

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.

items[].gateway_data.payment_config.support_pending_status
string

Whether the biller supports a pending payment state. Values: true, false. Use for async payment confirmation handling.

items[].gateway_data.payment_config.biller_timeout_period
integer

Timeout period in seconds supported by the biller when support_pending_status is true.

items[].gateway_data.payment_config.methods
array

Payment methods accepted by the biller as per Razorpay nomenclature. Use to filter payment options for the customer.

items[].gateway_data.payment_config.methods[].method
string

Payment method code. Values: netbanking, upi, card, wallet.

items[].gateway_data.payment_config.methods[].type
string

For card method, sub-type such as credit, debit, prepaid.

items[].gateway_data.payment_config.methods[].min_limit
integer

Minimum transaction amount in paise for this method.

items[].gateway_data.payment_config.methods[].max_limit
integer

Maximum transaction amount in paise for this method. null for cash payments.

items[].gateway_data.payment_config.methods[].support_pending_status
boolean

Whether this method supports pending status.

items[].gateway_data.payment_config.channels
array

Initiating channels supported by the biller.

items[].gateway_data.payment_config.channels[].channel
string

Initiating channel code as per NPCI terminology. Values: INT, MOB, MOBB, INTB, KIOSK, ATM, BNKBRNCH, AGT, BSC.

items[].gateway_data.payment_config.channels[].min_limit
integer

Minimum transaction amount in paise for this channel.

items[].gateway_data.payment_config.channels[].max_limit
integer

Maximum transaction amount in paise for this channel.

items[].gateway_data.payment_config.channels[].support_pending_status
boolean

Whether this channel supports pending status.

items[].gateway_data.payment_config.amount_type
array

Amount breakup types supported in bill request response. Use to parse the bill retrieval response structure.

items[].gateway_data.payment_config.amount_groups
array

Allowed combinations of amount components. Each item contains a components array listing valid breakup combinations.

items[].gateway_data.bill_request_config
object

Bill request configuration supported by the biller.

items[].gateway_data.bill_request_config.bill_response_type
string

Type of bill response. Values: single, multiple.

items[].gateway_data.bill_request_config.bill_request_required
string

Whether bill retrieval is required before payment. Values: mandatory, optional, not_supported.

items[].gateway_data.bill_request_config.plan_fetch_required
string

Whether plan fetch is required. Values: mandatory, optional, not_supported.

items[].gateway_data.additional_info_config
object

Additional information configuration supported by the biller.

items[].gateway_data.additional_info_config.params
array

Additional information parameters required from the customer.

items[].gateway_data.additional_info_config.params[].name
string

Parameter display name. For example, Customer Mobile Number.

items[].gateway_data.additional_info_config.params[].data_type
string

Parameter data type. Values: numeric, alphanumeric, alpha, date.

items[].gateway_data.additional_info_config.params[].optional
boolean

Whether the parameter is optional.

items[].gateway_data.additional_info_config.params[].min_length
integer

Minimum character length.

items[].gateway_data.additional_info_config.params[].max_length
integer

Maximum character length.

items[].gateway_data.additional_info_config.params[].regex
string

Validation regex pattern.

items[].gateway_data.additional_info_config.params[].values
array

Allowed enum values for the parameter.

items[].gateway_data.additional_info_config.params[].visibility
boolean

Whether the parameter should be shown to the customer.

items[].gateway_data.fee_config
object

Fee configuration supported by the biller.

items[].gateway_data.fee_config.fee_types
array

Fee types applicable.

items[].gateway_data.fee_config.fee_types[].fee_code
string

Fee identifier. Values:

  • PFB - Physical Biller Fee
  • EBF - Electronic Biller Fee
  • CCF1 / CCF2 - Customer Convenience Fee
  • AGSC - Agent Service Charge

items[].gateway_data.fee_config.fee_types[].fee_description
string

Customer-facing fee label. For example, Customer Convenience Fee.

items[].gateway_data.fee_config.fee_types[].fee_payer
string

Who pays the fee. Values: B2C (biller), C2B (customer).

items[].gateway_data.fee_config.fee_types[].fee_details
object

Fee calculation parameters.

items[].gateway_data.fee_config.fee_types[].fee_details.min_amount
integer

Minimum transaction amount for this fee tier in paise.

items[].gateway_data.fee_config.fee_types[].fee_details.max_amount
integer

Maximum transaction amount for this fee tier in paise.

items[].gateway_data.fee_config.fee_types[].fee_details.percentage
decimal

Percentage fee component. For example, 0.5 represents 0.5%.

items[].gateway_data.fee_config.fee_types[].fee_details.flat_amount
integer

Fixed fee component in paise.

items[].gateway_data.fee_config.fee_types[].fee_details.effective_from
integer

Fee validity start timestamp (Unix seconds).

items[].gateway_data.fee_config.fee_types[].fee_details.effective_to
integer

Fee validity end timestamp (Unix seconds). null if ongoing.

items[].gateway_data.fee_config.fee_rules
array

Rules determining which fee applies for a given transaction.

items[].gateway_data.fee_config.fee_rules[].transaction_type
string

Transaction type. Values: payment, fetch, validate. Defaults to payment.

items[].gateway_data.fee_config.fee_rules[].response_code
string

NPCI response code when fee applies. 00 represents success.

items[].gateway_data.fee_config.fee_rules[].method
string

Payment method for this rule. For example, Internet banking, upi, card.

items[].gateway_data.fee_config.fee_rules[].type
string

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.

items[].gateway_data.fee_config.fee_rules[].channel
string

Initiating channel for this rule. For example, AGT, INT, MOB.

items[].gateway_data.fee_config.fee_rules[].fee_code
array

Array of fee codes applicable. Apply multiple fees if listed.

items[].gateway_data.fee_config.fee_rules[].default_fee
boolean

Whether this is the default fee configuration. Used when no specific match is found.

items[].gateway_data.fee_config.fee_rules[].effective_from
integer

Rule validity start timestamp (Unix seconds).

items[].gateway_data.fee_config.fee_rules[].effective_to
integer

Rule validity end timestamp (Unix seconds).

items[].gateway_data.account_holder_config
object

Account holder configuration supported by the biller.

items[].gateway_data.account_holder_config.params
array

Customer input parameters required for bill retrieval. Use to build the bill retrieval input form.

items[].gateway_data.account_holder_config.params[].name
string

Parameter display name. For example, Customer Mobile Number.

items[].gateway_data.account_holder_config.params[].data_type
string

Input data type. Values: numeric, alphanumeric, alpha, date.

items[].gateway_data.account_holder_config.params[].optional
boolean

Whether the parameter is optional.

items[].gateway_data.account_holder_config.params[].min_length
integer

Minimum character length.

items[].gateway_data.account_holder_config.params[].max_length
integer

Maximum character length.

items[].gateway_data.account_holder_config.params[].regex
string

Validation regex pattern.

items[].gateway_data.account_holder_config.params[].values
array

Allowed enum values for the parameter.

items[].gateway_data.account_holder_config.input_groups
object

Combination and sequence of input parameters required for bill retrieval.

items[].gateway_data.account_holder_config.input_groups.step
integer

Sequence number of the input required from the customer.

items[].gateway_data.account_holder_config.input_groups.group_name
string

NPCI group level identifier. Use to render multi-step forms with progressive disclosure.

items[].gateway_data.account_holder_config.input_groups.input_params_required
array

List of field names the customer must provide in this step.

items[].gateway_data.account_holder_config.input_groups.required_input_count
integer

Minimum count of inputs required mandatorily from this step. Convert to string to render UI accordingly.

items[].gateway_data.account_holder_config.input_groups.depends_on_step
integer

Which prior step must be completed. null if there is no dependency on a previous step.

Errors

The category value is not a valid BBPS category.

Error Status: 400

The category provided does not match any BBPS category.

Solution

The biller_id is invalid.

Error Status: 400

The biller id provided does not correspond to a valid biller.

Solution

The count exceeds the maximum limit.

Error Status: 400

Count exceeds maximum limit of 100.

Solution

The geo_coverage.state is invalid.

Error Status: 400

Invalid state. Possible values - state, city, country.

Solution

Unable to fetch biller information from NPCI MDM.

Error Status: 502

NPCI did not respond within the timeout window.

Solution

The API <key/secret> provided is invalid.

Error Status: 401

The API credentials passed in the request differ from the ones generated on the Dashboard.

Solution

Fetch Billers

GET
/v1/bill_payments/billers

Click to copy

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.

Is this page helpful?

Query Parameters
id
string

Razorpay's internal biller entity id. Use to retrieve a specific biller by Razorpay id. For example, biller_001.

category
string

Filter billers by pre-defined BBPS biller category. Case-insensitive. For example, electricity, loan_repayment, mobile_postpaid.

gateway_biller_id
string

BBPS-specific biller id assigned by NPCI. Use to retrieve a specific biller by NPCI id. For example, TPOW00000MUM01.

biller_id
string

Fetch a specific biller by Razorpay biller id. For example, biller_001.

geo_coverage.country
string

Filter billers by country. Defaults to IN.

geo_coverage.state
string

Filter billers by state code. For example, MH, DL.

geo_coverage.city
string

Filter billers by city. For example, Bengaluru, Mumbai.

updated_since
integer

Unix timestamp in seconds. Returns only billers updated after this time. Use for incremental sync of your local biller catalogue.

status
string

Filter billers by operational status. Values: active, deactivated.

count
integer

Number of billers per page. Default is 10. Maximum is 100.

skip
integer

Number of biller records to skip for pagination. Default is 0.

Response Parameters
entity
string

Entity type identifier. Here, collection.

count
integer

Number of biller records returned.

items
array

Array of biller objects.

items[].id
string

Razorpay biller entity id. Format: biller_xxx. Use this when creating a bill request or payment.

items[].entity
string

Entity type. Always bill_payment.biller.

items[].gateway
string

Payment gateway. Defaults to bbps.

items[].created_at
integer

Biller creation timestamp in Razorpay records (Unix seconds).

items[].gateway_updated_at
integer

Last update timestamp from the gateway (Unix seconds). Use for data freshness checks.

items[].gateway_biller_id
string

NPCI/BBPS provided biller id (max 20 characters). Use for NPCI reconciliation and audit trail.

items[].name
string

Biller display name. Show this on the biller selection UI.

items[].alias_name
string

Biller alias or nickname shared in biller MDM. Optionally show alongside name for search and selection.

items[].category
string

Biller category. Use for grouping and filtering on the UI.

items[].status
string

Biller operational status. Values: active, inactive. Show inactive billers with a deactivated tag on the UI.

items[].supported_channels
array

Biller support type. Values: online, offline. Use to make channel routing decisions.

items[].logo_url
string

Biller logo image URL. Not in NPCI standard - sourced by Razorpay for UI display.

items[].effective_from
integer

Start date timestamp when biller becomes active on NPCI (Unix seconds).

items[].effective_to
integer

End date timestamp when biller is deprecated on NPCI (Unix seconds). null if currently active.

items[].geo_coverage
object

Geographic coverage area for the biller.

items[].geo_coverage.country
string

Country code. For example, IND.

items[].geo_coverage.state
string

State code. For example, MH.

items[].geo_coverage.city
string

City name. For example, Mumbai.

items[].gateway_data
object

Gateway-specific biller configuration.

items[].gateway_data.biller_ownership_type
string

Biller ownership. Values: Government, PSU, Private. Use to know whether the biller is private or government for audit trail.

items[].gateway_data.payment_config
object

Payment configuration supported by the biller.

items[].gateway_data.payment_config.amount_exactness
string

Payment amount flexibility. Values:

  • Exact - user must pay the exact amount fetched.
  • Exact and above - user can pay exact amount or more.
  • Exact and below - user can pay exact amount or less.
  • Any - user can pay any amount.

items[].gateway_data.payment_config.bill_request_required
string

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.

items[].gateway_data.payment_config.support_pending_status
string

Whether the biller supports a pending payment state. Values: true, false. Use for async payment confirmation handling.

items[].gateway_data.payment_config.biller_timeout_period
integer

Timeout period in seconds supported by the biller when support_pending_status is true.

items[].gateway_data.payment_config.methods
array

Payment methods accepted by the biller as per Razorpay nomenclature. Use to filter payment options for the customer.

items[].gateway_data.payment_config.methods[].method
string

Payment method code. Values: netbanking, upi, card, wallet.

items[].gateway_data.payment_config.methods[].type
string

For card method, sub-type such as credit, debit, prepaid.

items[].gateway_data.payment_config.methods[].min_limit
integer

Minimum transaction amount in paise for this method.

items[].gateway_data.payment_config.methods[].max_limit
integer

Maximum transaction amount in paise for this method. null for cash payments.

items[].gateway_data.payment_config.methods[].support_pending_status
boolean

Whether this method supports pending status.

items[].gateway_data.payment_config.channels
array

Initiating channels supported by the biller.

items[].gateway_data.payment_config.channels[].channel
string

Initiating channel code as per NPCI terminology. Values: INT, MOB, MOBB, INTB, KIOSK, ATM, BNKBRNCH, AGT, BSC.

items[].gateway_data.payment_config.channels[].min_limit
integer

Minimum transaction amount in paise for this channel.

items[].gateway_data.payment_config.channels[].max_limit
integer

Maximum transaction amount in paise for this channel.

items[].gateway_data.payment_config.channels[].support_pending_status
boolean

Whether this channel supports pending status.

items[].gateway_data.payment_config.amount_type
array

Amount breakup types supported in bill request response. Use to parse the bill retrieval response structure.

items[].gateway_data.payment_config.amount_groups
array

Allowed combinations of amount components. Each item contains a components array listing valid breakup combinations.

items[].gateway_data.bill_request_config
object

Bill request configuration supported by the biller.

items[].gateway_data.bill_request_config.bill_response_type
string

Type of bill response. Values: single, multiple.

items[].gateway_data.bill_request_config.bill_request_required
string

Whether bill retrieval is required before payment. Values: mandatory, optional, not_supported.

items[].gateway_data.bill_request_config.plan_fetch_required
string

Whether plan fetch is required. Values: mandatory, optional, not_supported.

items[].gateway_data.additional_info_config
object

Additional information configuration supported by the biller.

items[].gateway_data.additional_info_config.params
array

Additional information parameters required from the customer.

items[].gateway_data.additional_info_config.params[].name
string

Parameter display name. For example, Customer Mobile Number.

items[].gateway_data.additional_info_config.params[].data_type
string

Parameter data type. Values: numeric, alphanumeric, alpha, date.

items[].gateway_data.additional_info_config.params[].optional
boolean

Whether the parameter is optional.

items[].gateway_data.additional_info_config.params[].min_length
integer

Minimum character length.

items[].gateway_data.additional_info_config.params[].max_length
integer

Maximum character length.

items[].gateway_data.additional_info_config.params[].regex
string

Validation regex pattern.

items[].gateway_data.additional_info_config.params[].values
array

Allowed enum values for the parameter.

items[].gateway_data.additional_info_config.params[].visibility
boolean

Whether the parameter should be shown to the customer.

items[].gateway_data.fee_config
object

Fee configuration supported by the biller.

items[].gateway_data.fee_config.fee_types
array

Fee types applicable.

items[].gateway_data.fee_config.fee_types[].fee_code
string

Fee identifier. Values:

  • PFB - Physical Biller Fee
  • EBF - Electronic Biller Fee
  • CCF1 / CCF2 - Customer Convenience Fee
  • AGSC - Agent Service Charge

items[].gateway_data.fee_config.fee_types[].fee_description
string

Customer-facing fee label. For example, Customer Convenience Fee.

items[].gateway_data.fee_config.fee_types[].fee_payer
string

Who pays the fee. Values: B2C (biller), C2B (customer).

items[].gateway_data.fee_config.fee_types[].fee_details
object

Fee calculation parameters.

items[].gateway_data.fee_config.fee_types[].fee_details.min_amount
integer

Minimum transaction amount for this fee tier in paise.

items[].gateway_data.fee_config.fee_types[].fee_details.max_amount
integer

Maximum transaction amount for this fee tier in paise.

items[].gateway_data.fee_config.fee_types[].fee_details.percentage
decimal

Percentage fee component. For example, 0.5 represents 0.5%.

items[].gateway_data.fee_config.fee_types[].fee_details.flat_amount
integer

Fixed fee component in paise.

items[].gateway_data.fee_config.fee_types[].fee_details.effective_from
integer

Fee validity start timestamp (Unix seconds).

items[].gateway_data.fee_config.fee_types[].fee_details.effective_to
integer

Fee validity end timestamp (Unix seconds). null if ongoing.

items[].gateway_data.fee_config.fee_rules
array

Rules determining which fee applies for a given transaction.

items[].gateway_data.fee_config.fee_rules[].transaction_type
string

Transaction type. Values: payment, fetch, validate. Defaults to payment.

items[].gateway_data.fee_config.fee_rules[].response_code
string

NPCI response code when fee applies. 00 represents success.

items[].gateway_data.fee_config.fee_rules[].method
string

Payment method for this rule. For example, Internet banking, upi, card.

items[].gateway_data.fee_config.fee_rules[].type
string

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.

items[].gateway_data.fee_config.fee_rules[].channel
string

Initiating channel for this rule. For example, AGT, INT, MOB.

items[].gateway_data.fee_config.fee_rules[].fee_code
array

Array of fee codes applicable. Apply multiple fees if listed.

items[].gateway_data.fee_config.fee_rules[].default_fee
boolean

Whether this is the default fee configuration. Used when no specific match is found.

items[].gateway_data.fee_config.fee_rules[].effective_from
integer

Rule validity start timestamp (Unix seconds).

items[].gateway_data.fee_config.fee_rules[].effective_to
integer

Rule validity end timestamp (Unix seconds).

items[].gateway_data.account_holder_config
object

Account holder configuration supported by the biller.

items[].gateway_data.account_holder_config.params
array

Customer input parameters required for bill retrieval. Use to build the bill retrieval input form.

items[].gateway_data.account_holder_config.params[].name
string

Parameter display name. For example, Customer Mobile Number.

items[].gateway_data.account_holder_config.params[].data_type
string

Input data type. Values: numeric, alphanumeric, alpha, date.

items[].gateway_data.account_holder_config.params[].optional
boolean

Whether the parameter is optional.

items[].gateway_data.account_holder_config.params[].min_length
integer

Minimum character length.

items[].gateway_data.account_holder_config.params[].max_length
integer

Maximum character length.

items[].gateway_data.account_holder_config.params[].regex
string

Validation regex pattern.

items[].gateway_data.account_holder_config.params[].values
array

Allowed enum values for the parameter.

items[].gateway_data.account_holder_config.input_groups
object

Combination and sequence of input parameters required for bill retrieval.

items[].gateway_data.account_holder_config.input_groups.step
integer

Sequence number of the input required from the customer.

items[].gateway_data.account_holder_config.input_groups.group_name
string

NPCI group level identifier. Use to render multi-step forms with progressive disclosure.

items[].gateway_data.account_holder_config.input_groups.input_params_required
array

List of field names the customer must provide in this step.

items[].gateway_data.account_holder_config.input_groups.required_input_count
integer

Minimum count of inputs required mandatorily from this step. Convert to string to render UI accordingly.

items[].gateway_data.account_holder_config.input_groups.depends_on_step
integer

Which prior step must be completed. null if there is no dependency on a previous step.

Errors

The category value is not a valid BBPS category.

Error Status: 400

The category provided does not match any BBPS category.

Solution

The biller_id is invalid.

Error Status: 400

The biller id provided does not correspond to a valid biller.

Solution

The count exceeds the maximum limit.

Error Status: 400

Count exceeds maximum limit of 100.

Solution

The geo_coverage.state is invalid.

Error Status: 400

Invalid state. Possible values - state, city, country.

Solution

Unable to fetch biller information from NPCI MDM.

Error Status: 502

NPCI did not respond within the timeout window.

Solution

The API <key/secret> provided is invalid.

Error Status: 401

The API credentials passed in the request differ from the ones generated on the Dashboard.

Solution

Curl

1
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2
-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"

Success

Failure

1
{
2
  "entity": "collection",
3
  "count": 1,
4
  "items": [
5
    {
6
      "id": "biller_001",
7
      "entity": "bill_payment.biller",
8
      "gateway": "bbps",
9
      "created_at": 1609459200,
10
      "gateway_updated_at": 1689459200,
11
      "gateway_biller_id": "TPOW00000MUM01",
12
      "name": "Electricity Bill Payment",
13
      "alias_name": "Electricity BP",
14
      "category": "electricity",
15
      "status": "active",
16
      "supported_channels": ["online"],
17
      "logo_url": "https://example.com/logos/electricity.png",
18
      "effective_from": 1689459200,
19
      "effective_to": 1735689600,
20
      "geo_coverage": {
21
        "country": "IND",
22
        "state": "MH",
23
        "city": "Mumbai"
24
      },
25
      "gateway_data": {
26
        "biller_ownership_type": "Private",
27
        "payment_config": {
28
          "amount_exactness": "Exact",
29
          "bill_request_required": "mandatory",
30
          "support_pending_status": "true",
31
          "biller_timeout_period": 21600,
32
          "methods": [
33
            {
34
              "method": "cash",
35
              "min_limit": 100,
36
              "max_limit": null,
37
              "support_pending_status": false
38
            },
39
            {
40
              "method": "upi",
41
              "min_limit": 1,
42
              "max_limit": null,
43
              "support_pending_status": true
44
            },
45
            {
46
              "method": "card",
47
              "type": "credit",
48
              "min_limit": 1,
49
              "max_limit": null,
50
              "support_pending_status": true
51
            }
52
          ],
53
          "channels": [
54
            {
55
              "channel": "AGT",
56
              "max_limit": 100000,
57
              "min_limit": 100,
58
              "support_pending_status": false
59
            },
60
            {
61
              "channel": "BNKBRNCH",
62
              "max_limit": 500000,
63
              "min_limit": 1000,
64
              "support_pending_status": true
65
            }
66
          ],
67
          "amount_type": [
68
            {
69
              "name": "base_bill_amount",
70
              "optional": false,
71
              "data_type": "string",
72
              "min_length": 2,
73
              "max_length": 12,
74
              "regex": "<regex_pattern>",
75
              "values": "string",
76
              "visibility": true
77
            },
78
            {
79
              "name": "fixed_charges",
80
              "optional": true,
81
              "data_type": "string",
82
              "min_length": 2,
83
              "max_length": 12,
84
              "regex": "<regex_pattern>",
85
              "values": "string",
86
              "visibility": true
87
            }
88
          ],
89
          "amount_groups": [
90
            {
91
              "components": ["base_bill_amount", "fixed_charges"]
92
            },
93
            {
94
              "components": ["base_bill_amount"]
95
            }
96
          ]
97
        },
98
        "bill_request_config": {
99
          "upms_supported": null,
100
          "bill_response_type": "single/multiple",
101
          "bill_request_required": "mandatory/optional/not_supported",
102
          "plan_fetch_required": "mandatory/optional/not_supported"
103
        },
104
        "additional_info_config": {
105
          "params": [
106
            {
107
              "name": "Customer Mobile Number",
108
              "data_type": "numeric",
109
              "optional": true,
110
              "min_length": 10,
111
              "max_length": 10,
112
              "regex": "^[6-9]{1}[0-9]{9}$",
113
              "values": ["Vehicle Finance", "Home Finance"],
114
              "visibility": true
115
            },
116
            {
117
              "name": "accountNumber",
118
              "data_type": "string",
119
              "optional": false,
120
              "min_length": 9,
121
              "max_length": 12,
122
              "values": ["Vehicle Finance", "Home Finance"],
123
              "visibility": true
124
            }
125
          ]
126
        },
127
        "fee_config": {
128
          "fee_types": [
129
            {
130
              "fee_code": "CCF1",
131
              "fee_description": "Customer Convenience Fee",
132
              "fee_payer": "customer",
133
              "fee_details": {
134
                "min_amount": 100,
135
                "max_amount": 10000,
136
                "percentage": 0.5,
137
                "flat_amount": 2,
138
                "effective_from": 1689459200,
139
                "effective_to": 1735689600
140
              }
141
            }
142
          ],
143
          "fee_rules": [
144
            {
145
              "transaction_type": "payment",
146
              "response_code": "00",
147
              "method": "card",
148
              "type": "credit",
149
              "channel": "AGT",
150
              "fee_code": ["PFB", "CCF1"],
151
              "default_fee": false,
152
              "effective_from": 1689459200,
153
              "effective_to": 1735689600
154
            },
155
            {
156
              "transaction_type": "payment",
157
              "response_code": "00",
158
              "method": "upi",
159
              "channel": "AGT",
160
              "fee_code": ["CCF1", "CCF2"],
161
              "default_fee": true,
162
              "effective_from": 1689459200,
163
              "effective_to": 1735689600
164
            }
165
          ]
166
        },
167
        "account_holder_config": {
168
          "params": [
169
            {
170
              "name": "Customer Mobile Number",
171
              "data_type": "numeric",
172
              "optional": true,
173
              "min_length": 10,
174
              "max_length": 10,
175
              "regex": "^[6-9]{1}[0-9]{9}$",
176
              "values": ["Vehicle Finance", "Home Finance"]
177
            }
178
          ],
179
          "input_groups": {
180
            "step": 1,
181
            "group_name": "Group1",
182
            "input_params_required": ["accountNumber"],
183
            "required_input_count": 1,
184
            "depends_on_step": null
185
          }
186
        }
187
      }
188
    }
189
  ]
190
}