Skip to main content
POST
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). 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 API or listen to webhooks until the status reaches a terminal state (success or failed).
PrerequisiteCall 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.
IdempotencyPass 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. 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.

​
Request Parameters

​
string
Bill request id returned by Create a 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.
​
string
Razorpay’s internal biller id. Required for Direct Pay if gateway_biller_id is not provided.
​
string
NPCI’s biller id. Required for Direct Pay if biller_id is not provided. For example, TPOW00000MUM01.
​
integer
required
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.
​
string
required
Currency in which the bill payment is initiated. Defaults to INR.
​
object
required
Fee breakdown. Pass 0 for components that do not apply.
​
integer
required
Merchant/app convenience fee charged to the customer, in paise. Not part of NPCI standard. Platform-specific. Pass 0 if not applicable.
​
integer
required
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.
​
array
required
Payment details collected via the Razorpay PG. Use multiple objects for split payments across methods.
​
string
required
Razorpay payment id received from the Razorpay PA post Payment Create. Required as per NPCI guidelines. For example, pay_MbJ5AvwNpAkfLB.
​
string
required
Payment provider. Hardcode to razorpay when the payment is processed via the Razorpay gateway.
​
integer
required
Amount paid via the selected method, in paise. Must match the payment amount captured through the PG.
​
string
required
ISO 4217 currency code. Only INR is supported currently.
​
string
required
Payment method. Maps to NPCI paymentMode. Supported values: card, upi, netbanking, wallet.
​
object
Required when method is card.
​
string
required
Card type. Values: credit, debit, prepaid.
​
string
required
Last 4 digits of the card.
​
string
required
Hardcode to Card as per NPCI guidelines.
​
object
Required when method is upi.
​
string
required
Customer’s actual UPI VPA if available; otherwise pass the Razorpay payment id.
​
object
Required when method is netbanking.
​
string
required
Customer’s account number if available; otherwise hardcode to PG.
​
string
required
IFSC code if available; otherwise pass the Razorpay payment id.
​
object
Required when method is wallet.
​
string
required
Name of the actual wallet used. For example, amazon_pay, payzapp.
​
array
required
Bills being paid. Minimum 1 bill required for Normal Pay. Pass an empty array [] for Direct Pay (no bill was retrieved).
​
string
bills[].bill_number received in the Fetch Bill Request response. Required when a bill was retrieved.
​
integer
required
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.
​
string
required
Currency code. Hardcode to INR.
​
object
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.
​
string
Dynamic key-value pair holding your customer reference. Not validated by Razorpay.
​
string
Dynamic key-value pair holding the customer name. Not validated by Razorpay.
​
string
required
Customer’s mobile number with country code. For example, 919000090000.
​
string
Dynamic key-value pair holding the customer email. Not validated by Razorpay.
​
object
Bill account holder details. Mandatory if bill_request_id is not provided.
​
object
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 API. Razorpay does not control the keys nor the values - pass them exactly as defined by the biller.
​
object
Info about the device initiating the bill payment. Mandatory if bill_request_id is not provided.
​
enum
required
Channel from which the bill payment is initiated. Values:
  • internet - Web
  • mobile - Mobile App
  • pos - Point of Sale
  • mpos - Mobile Point of Sale
​
string
End agent’s mobile number (10 digits) for offline channels. Required for pos, mpos channels.
​
string
Latitude, Longitude. Required for internet, mobile, pos, mpos channels. For example, 12.9667,77.5667.
​
string
IPv4 or IPv6 address. Required for internet, mobile channels.
​
string
MAC address. Required for internet channels. For example, 00-0D-60-07-2A-F0.
​
string
Operating system. Required for mobile, mpos channels. For example, android, iOS.
​
string
Application name. Required for mobile, mpos channels. For example, amazon_pay.
​
string
Device IMEI number. Required for the mobile initiating channel.

​
Response Parameters

​
string
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.
​
string
Entity type. Always bill_payment.payment.
​
string
Initial payment status. processing on the create response. Poll Fetch Bill Payment for the final state. Possible final values: success (NPCI responseCode=000), pending (NPCI responseCode=091) or failed (any other NPCI responseCode).
​
object
Customer who made the payment. Echoed from the request.
​
string
Razorpay biller entity id. Use for internal biller identification, reporting and analytics.
​
string
NPCI biller id.
​
string
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.
​
string
Bill payment gateway used. Defaults to bbps.
​
integer
UNIX timestamp when the bill payment was created at Razorpay.

​
Errors

Code: 400ref_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: 400Invalid or expired ref_id.Solution: Use a bill_request_id from a successful bill request that has not yet expired (expiry_at).
Code: 400Payment 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: 400Customer parameters do not match fetch/validate request.Solution: Pass the same customer parameters used during the bill request.
Code: 400Payment method not supported for this biller.Solution: Check the biller’s supported payment_config.methods and retry with a supported method.
Code: 400Payment 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: 400Required payment instrument details missing for {payment_mode}.Solution: Include the appropriate sub-object (card, upi, netbanking, wallet) with all mandatory fields.
Code: 400Payment authorisation not found from PA.Solution: Ensure the Razorpay PG payment is in a captured state before calling this API.
Code: 400The 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: 502The biller rejected the bill payment.Solution: Check metadata.payment_id and initiate a refund on the PG payment if money was collected.
Code: 502Bill payment failed at biller because of a duplicate payment.Solution: Poll Fetch Bill Payment for the original payment status before retrying.
Code: 502NPCI 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: 502The biller is temporarily unavailable for payments.Solution: Retry the request after a short interval.
Code: 401The 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.
Last modified on October 8, 2026