> ## 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.
# Create a Bill Payment | BBPS API | Razorpay
> Confirm a BBPS bill payment on the NPCI network after collecting money via the Razorpay Payment Gateway. Returns processing status with a bill payment id to poll for the final outcome.
Available in
🇮🇳 India
Use this endpoint to confirm a bill payment on the BBPS network after you have collected payment from the customer via the [Razorpay Payment Gateway (PG)](/docs/payments/payment-gateway). Razorpay acts as both the Payment Aggregator (PA) and the Customer Operating Unit (COU). You, the Agent Institution, orchestrate two steps: collect money via the PG, then call this API to confirm the bill settlement.
This is an asynchronous API. The response immediately returns a `processing` status with a bill payment `id`. Poll the [Fetch Bill Payment](/docs/api/bills/bill-payments/fetch-bill-payment) API or listen to webhooks until the status reaches a terminal state (`success` or `failed`).
**Prerequisite**
Call this API only after the Razorpay PG payment is captured. The `payments[].id` field must be a valid Razorpay payment id with a `captured` status. Calling this API before the PG payment is captured will result in a failed bill settlement.
**Idempotency**
Pass a unique `X-Bill-Payments-Idempotency` header (4–36 characters, alphanumeric with hyphens, underscores or spaces) to safely retry requests without creating duplicate payments. A UUID v4 is recommended. The request body on retries must match the original request, else it is rejected as a `BAD_REQUEST_ERROR`.
**Normal Pay vs Direct Pay**
* **Normal Pay** - used when a bill is retrieved first via [Create a Bill Request](/docs/api/bills/bill-payments/create-bill-request). Pass `bill_request_id`.
* **Direct Pay** - used when the biller's `bill_request_required` flag is `optional` or `not_supported` and you skip the bill retrieval step. Pass `biller_id` (or `gateway_biller_id`), `biller_data.account_holder` and `device` instead.
```bash Normal Pay theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/bill_payments/payments \
-H "Content-Type: application/json" \
-H "X-Bill-Payments-Idempotency: 53cda91c-8f81-4e77-bbb9-7388f4ac6bf4" \
-d '{
"bill_request_id": "billreq_ERNEungCtXpZqM",
"bill_pay_amount": 1015,
"currency": "INR",
"fees": {
"app_convenience_fee": 10,
"biller_convenience_fee": 5
},
"payments": [
{
"id": "pay_MbJ5AvwNpAkfLB",
"amount": 600,
"currency": "INR",
"provider": "razorpay",
"method": "card",
"card": {
"type": "credit",
"last4": "0153",
"auth_code": "Card"
}
},
{
"id": "pay_MbJ5AvwNpAkfLA",
"amount": 430,
"currency": "INR",
"provider": "razorpay",
"method": "upi",
"upi": {
"vpa": "gaurav.kumar@okhdfc.com"
}
}
],
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR"
}
]
}'
```
```bash Direct Pay theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/bill_payments/payments \
-H "Content-Type: application/json" \
-H "X-Bill-Payments-Idempotency: 53cda91c-8f81-4e77-bbb9-7388f4ac6bf4" \
-d '{
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"biller_data": {
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
}
},
"device": {
"initiating_channel": "mobile",
"mobile": "9999999999",
"geocode": "12.9667,77.5667",
"ip": "198.1.1.1",
"mac": "00-0D-60-07-2A-F0",
"os": "android",
"imei": "490154203237518",
"app": "amazon_pay"
},
"bill_pay_amount": 1015,
"currency": "INR",
"fees": {
"app_convenience_fee": 10,
"biller_convenience_fee": 5
},
"payments": [
{
"id": "pay_MbJ5AvwNpAkfLA",
"amount": 600,
"currency": "INR",
"provider": "razorpay",
"method": "card",
"card": {
"type": "credit",
"last4": "0153",
"auth_code": "Card"
}
},
{
"id": "pay_MbJ5AvwNpAkfLB",
"amount": 430,
"currency": "INR",
"provider": "razorpay",
"method": "upi",
"upi": {
"vpa": "gaurav.kumar@okhdfc.com"
}
}
],
"bills": []
}'
```
```json Success theme={null}
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "processing",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"gateway_transaction_id": "bbps_txn_id",
"gateway": "bbps",
"created_at": 1609459200
}
```
```json Failure theme={null}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The payment method used is not supported by this biller.",
"source": "biller",
"step": "bill_payment",
"reason": "biller_unavailable",
"metadata": {}
}
}
```
## Request Parameters
Bill request id returned by [Create a Bill Request](/docs/api/bills/bill-payments/create-bill-request). Mandatory for Normal Pay. When omitted, the request is treated as Direct Pay and `device` and `biller_data.account_holder` become mandatory. For example, `billreq_ERNEungCtXpZqM`.
Razorpay's internal biller id. Required for Direct Pay if `gateway_biller_id` is not provided.
NPCI's biller id. Required for Direct Pay if `biller_id` is not provided. For example, `TPOW00000MUM01`.
Actual bill amount for which the bill payment is raised, in paise. Excludes fees. Must satisfy the biller's `payment_config.amount_exactness` rule (`exact`, `exact_or_above`, `exact_or_below` or `any`). This value can be less or more than an individual bill amount. For example, `1015` represents ₹10.15.
Currency in which the bill payment is initiated. Defaults to `INR`.
Fee breakdown. Pass `0` for components that do not apply.
Merchant/app convenience fee charged to the customer, in paise. Not part of NPCI standard. Platform-specific. Pass `0` if not applicable.
Customer Convenience Fee charged by the biller, in paise. Maps to the biller's `fee_config.fee_types[].fee_code=CCF1` returned by the Fetch Billers API and to NPCI's `custConvFee`. Pass `0` if the biller charges no CCF.
Payment details collected via the Razorpay PG. Use multiple objects for split payments across methods.
Razorpay payment id received from the Razorpay PA post Payment Create. Required as per NPCI guidelines. For example, `pay_MbJ5AvwNpAkfLB`.
Payment provider. Hardcode to `razorpay` when the payment is processed via the Razorpay gateway.
Amount paid via the selected method, in paise. Must match the payment amount captured through the PG.
ISO 4217 currency code. Only `INR` is supported currently.
Payment method. Maps to NPCI `paymentMode`. Supported values: `card`, `upi`, `netbanking`, `wallet`.
Required when `method` is `card`.
Card type. Values: `credit`, `debit`, `prepaid`.
Last 4 digits of the card.
Hardcode to `Card` as per NPCI guidelines.
Required when `method` is `upi`.
Customer's actual UPI VPA if available; otherwise pass the Razorpay payment id.
Required when `method` is `netbanking`.
Customer's account number if available; otherwise hardcode to `PG`.
IFSC code if available; otherwise pass the Razorpay payment id.
Required when `method` is `wallet`.
Name of the actual wallet used. For example, `amazon_pay`, `payzapp`.
Bills being paid. Minimum 1 bill required for Normal Pay. Pass an empty array `[]` for Direct Pay (no bill was retrieved).
`bills[].bill_number` received in the Fetch Bill Request response. Required when a bill was retrieved.
Bill amount in paise. Must match the bill amount returned by the Fetch Bill Request API or satisfy the biller's `payment_config.amount_exactness` rules.
Currency code. Hardcode to `INR`.
Customer information passed as dynamic key-value pairs. Free-form metadata for your own tracking and reconciliation. Razorpay echoes these back on responses and webhooks without validation.
Dynamic key-value pair holding your customer reference. Not validated by Razorpay.
Dynamic key-value pair holding the customer name. Not validated by Razorpay.
Customer's mobile number with country code. For example, `919000090000`.
Dynamic key-value pair holding the customer email. Not validated by Razorpay.
Bill account holder details. Mandatory if `bill_request_id` is not provided.
Dynamic key-value pairs that identify the customer's account at the biller. The keys and values are dictated by the biller's `account_holder_config` returned by the [Fetch Billers](/docs/api/bills/bill-payments/fetch-billers) API. Razorpay does not control the keys nor the values - pass them exactly as defined by the biller.
Info about the device initiating the bill payment. Mandatory if `bill_request_id` is not provided.
Channel from which the bill payment is initiated. Values:
* `internet` - Web
* `mobile` - Mobile App
* `pos` - Point of Sale
* `mpos` - Mobile Point of Sale
End agent's mobile number (10 digits) for offline channels. Required for `pos`, `mpos` channels.
Latitude, Longitude. Required for `internet`, `mobile`, `pos`, `mpos` channels. For example, `12.9667,77.5667`.
IPv4 or IPv6 address. Required for `internet`, `mobile` channels.
MAC address. Required for `internet` channels. For example, `00-0D-60-07-2A-F0`.
Operating system. Required for `mobile`, `mpos` channels. For example, `android`, `iOS`.
Application name. Required for `mobile`, `mpos` channels. For example, `amazon_pay`.
Device IMEI number. Required for the `mobile` initiating channel.
## Response Parameters
Razorpay's unique bill payment transaction id. Use this for internal tracking, refund reference, reconciliation and to poll for the final status. For example, `bill_pay_xxxx`.
Entity type. Always `bill_payment.payment`.
Initial payment status. `processing` on the create response. Poll [Fetch Bill Payment](/docs/api/bills/bill-payments/fetch-bill-payment) for the final state. Possible final values: `success` (NPCI `responseCode=000`), `pending` (NPCI `responseCode=091`) or `failed` (any other NPCI `responseCode`).
Customer who made the payment. Echoed from the request.
Razorpay biller entity id. Use for internal biller identification, reporting and analytics.
NPCI biller id.
BBPS/NPCI transaction reference number. Fixed length of 12 or 20 characters. Maps to NPCI `txnReferenceId`. Store for NPCI reconciliation, settlement tracking and dispute resolution.
Bill payment gateway used. Defaults to `bbps`.
UNIX timestamp when the bill payment was created at Razorpay.
## Errors
**Code:** `400`
`ref_id` is required.
**Solution:** Pass either a valid `bill_request_id` (Normal Pay) or the Direct Pay fields (`biller_id`, `biller_data.account_holder`, `device`).
**Code:** `400`
Invalid or expired `ref_id`.
**Solution:** Use a `bill_request_id` from a successful bill request that has not yet expired (`expiry_at`).
**Code:** `400`
Payment amount does not match fetch/validate amount.
**Solution:** Use the `bill.amount` returned in the successful bill request or pass a value that satisfies the biller's `amount_exactness` rules.
**Code:** `400`
Customer parameters do not match fetch/validate request.
**Solution:** Pass the same customer parameters used during the bill request.
**Code:** `400`
Payment method not supported for this biller.
**Solution:** Check the biller's supported `payment_config.methods` and retry with a supported method.
**Code:** `400`
Payment amount exceeds maximum limit of `{max_amount}` for `{payment_mode}`.
**Solution:** Pass an amount within the biller's `payment_config.methods[].max_limit` or split across methods.
**Code:** `400`
Required payment instrument details missing for `{payment_mode}`.
**Solution:** Include the appropriate sub-object (`card`, `upi`, `netbanking`, `wallet`) with all mandatory fields.
**Code:** `400`
Payment authorisation not found from PA.
**Solution:** Ensure the Razorpay PG payment is in a `captured` state before calling this API.
**Code:** `400`
The idempotency key must be 4-36 characters and contain only alphanumeric characters, hyphens, underscores or spaces.
**Solution:** Provide a unique idempotency key. A UUID v4 is recommended.
**Code:** `502`
The biller rejected the bill payment.
**Solution:** Check `metadata.payment_id` and initiate a refund on the PG payment if money was collected.
**Code:** `502`
Bill payment failed at biller because of a duplicate payment.
**Solution:** Poll Fetch Bill Payment for the original payment status before retrying.
**Code:** `502`
NPCI did not respond within the timeout window.
**Solution:** Poll Fetch Bill Payment for the final state. Do not retry until status reaches `success` or `failed`.
**Code:** `502`
The biller is temporarily unavailable for payments.
**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.