> ## Documentation Index > Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Bill Payment Request > Use this API to initiate a bill payment against a previously fetched or validated bill. This is an **async** API. It returns only an acknowledgement with a `transaction_ref_id`. Poll the Bill Payment Response API using both `bill_fetch_ref_id` and `transaction_ref_id` to get the final payment status. ## OpenAPI ````yaml openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/request/bill-payment openapi: 3.0.3 info: title: BBPS for Customers (Customer Operating Unit) version: 1.0.0 description: > APIs for Agent Institutions to integrate with the Bharat Bill Payment System (BBPS) as a Customer Operating Unit (COU). These APIs enable bill discovery, bill fetch, bill payment, ticket management, and wallet operations. servers: - url: https://sandbox.cashfree.com description: Sandbox (Testing) environment. - url: https://api.cashfree.com description: Production environment. security: - XClientID: [] XClientSecret: [] paths: /bbps/cou/v1/billers/request/bill-payment: post: tags: - Bill Payment summary: Bill Payment Request description: > Use this API to initiate a bill payment against a previously fetched or validated bill. This is an **async** API. It returns only an acknowledgement with a `transaction_ref_id`. Poll the Bill Payment Response API using both `bill_fetch_ref_id` and `transaction_ref_id` to get the final payment status. operationId: billPaymentRequest requestBody: description: Request parameters to initiate a bill payment request. required: true content: application/json: schema: type: object required: - bill_payment_request properties: bill_payment_request: type: object required: - head - customer - agent - bill_details - payment_method - amount - payment_information properties: head: type: object description: >- Header block containing reference IDs that link this payment to the prior bill fetch. required: - bill_fetch_ref_id - pg_reference_id properties: bill_fetch_ref_id: type: string description: >- The ref_id received from the Bill Fetch Request API, used to link this payment to the corresponding bill fetch. example: HENSVVR4QOS7X1UGPY7JGUV444P10102202 pg_reference_id: type: string description: >- Unique reference ID generated by the Agent Institution's payment gateway for this transaction. example: PG_REF_001 customer: type: object description: Details of the customer initiating the payment. required: - mobile properties: mobile: type: string description: >- Mobile number of the customer initiating the payment. example: '9505987798' tag: type: array description: >- Optional additional customer identifier tags such as email, Aadhaar, or PAN. items: type: object properties: name: type: string description: >- Identifier type. Supported values are EMAIL, AADHAAR, and PAN. enum: - EMAIL - AADHAAR - PAN value: type: string description: Value corresponding to the identifier type. agent: type: object description: >- Details of the agent institution and the device initiating the payment. required: - id - device properties: id: type: string description: >- Unique ID of the Agent Institution as registered on the BBPS network. example: OU01AI34INT001123456 device: type: object description: >- Device metadata for the terminal or channel initiating the payment. required: - tag properties: tag: type: array minItems: 1 description: >- List of device metadata tags. At least one tag is required. Supported tag names are INITIATING_CHANNEL, IP, MOBILE, GEOCODE, POSTAL_CODE, TERMINAL_ID, IMEI, IFSC, MAC, OS, and APP. items: type: object required: - name - value properties: name: type: string description: Device metadata tag name. example: INITIATING_CHANNEL value: type: string description: >- Value corresponding to the device metadata tag name. example: INT bill_details: type: object description: >- Biller and customer reference details identifying the bill being paid. required: - biller - customer_params properties: biller: type: object description: Biller identification details. required: - id properties: id: type: string description: >- Unique biller ID as returned by the Fetch Billers Info API. example: VODA00000MUM03 customer_params: type: object description: >- Customer reference parameters used to identify the bill. Must match the biller's customer parameter configuration. required: - tag properties: tag: type: array minItems: 1 description: >- List of name-value pairs representing customer identifiers for the biller. items: type: object required: - name - value properties: name: type: string description: >- Parameter name matching the biller's customer param config. example: RefFld1 value: type: string description: >- Value for the corresponding parameter, such as the consumer number or mobile number. example: XX1234ABCD biller_response: type: object nullable: true description: >- Bill details received from the Bill Fetch Response. Optional for most billers, but all fields become mandatory for categories such as Electricity, DTH, and Gas. properties: customer_name: type: string description: Name of the customer as registered with the biller. example: Manoj Chekuri amount: type: string description: >- Total bill amount in paise as returned by the biller. example: '120000' due_date: type: string description: Bill due date in yyyy-MM-dd format. example: '2021-09-24' bill_date: type: string description: Date the bill was generated in yyyy-MM-dd format. example: '2021-01-02' bill_number: type: string description: Unique bill number issued by the biller. example: '1232332' bill_period: type: string description: >- Billing cycle period. Example values are MONTHLY, QUARTERLY, and ONETIME. example: MONTHLY additional_info: type: object nullable: true description: >- Additional biller-specific information received from the Bill Fetch Response. Pass these fields back as received. properties: tag: type: array description: >- List of name-value pairs containing biller-specific metadata from the fetch response. items: type: object properties: name: type: string description: >- Field name as defined in the biller's MDM configuration. value: type: string description: Corresponding field value. payment_method: type: object required: - quick_pay - split_pay - off_us_pay - payment_mode properties: quick_pay: type: string enum: - 'Yes' - 'No' description: >- Indicates whether payment is made without a prior bill fetch. example: 'No' split_pay: type: string enum: - 'Yes' - 'No' description: >- Indicates whether the payment is split across two modes. example: 'No' off_us_pay: type: string enum: - 'Yes' - 'No' description: >- Indicates if this is an off-us payment made from a different bank's customer. example: 'No' payment_mode: type: string description: >- Supported payment modes are UPI, Internet Banking, Debit Card, Credit Card, IMPS, Cash, Wallet, NEFT, AEPS, and Bharat QR. example: UPI amount: type: object required: - amt properties: amt: type: object required: - amount - cust_conv_fee - cou_cust_conv_fee - currency properties: amount: type: string description: Total amount in paise. example: '120000' cust_conv_fee: type: string description: Customer convenience fee (CCF1) in paise. example: '1000' cou_cust_conv_fee: type: string description: COU convenience fee (CCF2) in paise. example: '1500' currency: type: string description: Currency code. Use 356 for INR. example: '356' payment_information: type: object required: - tag description: > Payment instrument details specific to the selected payment mode. At least one tag is required. Required tags by payment mode: UPI requires VPA; Card requires CardNum and AuthCode; Bank transfer requires IFSC and AccountNo; Wallet requires WalletName and MobileNo; AEPS requires Aadhaar and IIN. properties: tag: type: array minItems: 1 description: >- List of name-value pairs representing payment instrument details for the selected payment mode. items: type: object required: - name - value properties: name: type: string description: >- Payment instrument field name, such as VPA, CardNum, IFSC, or WalletName. example: VPA value: type: string description: >- Value for the corresponding payment instrument field. example: account@provider example: bill_payment_request: head: bill_fetch_ref_id: HENSVVR4QOS7X1UGPY7JGUV444P10102202 pg_reference_id: PG_REF_001 customer: mobile: '9505987798' tag: - name: EMAIL value: customer@example.com agent: id: OU01AI34INT001123456 device: tag: - name: INITIATING_CHANNEL value: INT - name: IP value: 124.170.23.22 bill_details: biller: id: VODA00000MUM03 customer_params: tag: - name: RefFld1 value: XX1234ABCD biller_response: customer_name: Manoj Chekuri amount: '120000' due_date: '2021-09-24' bill_date: '2021-01-02' bill_number: '1232332' bill_period: MONTHLY payment_method: quick_pay: 'No' split_pay: 'No' off_us_pay: 'No' payment_mode: UPI amount: amt: amount: '120000' cust_conv_fee: '1000' cou_cust_conv_fee: '1500' currency: '356' payment_information: tag: - name: VPA value: account@provider responses: '202': description: Success response for initiating a bill payment request. content: application/json: schema: type: object properties: status: type: string description: >- Always "ACCEPTED" when the payment request is successfully queued. example: ACCEPTED message: type: string description: >- Human-readable confirmation that the payment request has been accepted for async processing. example: Bill payment request accepted for processing data: type: object description: >- Acknowledgement data returned immediately upon request acceptance. properties: bill_fetch_ref_id: type: string description: >- The ref_id from the Bill Fetch Request, echoed back for correlation. example: HENSVVR4QOS7X1UGPY7JGUV444P10102202 transaction_ref_id: type: string description: >- Unique transaction reference ID for this payment. Use this along with bill_fetch_ref_id to poll the Bill Payment Response API. example: OU011010ABCD12345678 status: type: string description: >- Processing status of the payment request. Always "PROCESSING" at this stage. example: PROCESSING '400': description: Bad request error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '429': description: Rate Limit Error. content: application/json: schema: $ref: '#/components/schemas/RateLimitResponse' '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' components: schemas: ErrorResponse: type: object properties: message: type: string description: Human-readable description of the validation or request error. example: >- bill_fetch_request.agent_id : is missing in the request. Value received: code: type: string description: >- Machine-readable error code identifying the specific validation failure. example: bill_fetch_request.agent_id_missing type: type: string description: Category of the error, indicating the error class. example: invalid_request_error UnauthorizedResponse: type: object properties: message: type: string description: Human-readable description of the authentication failure. example: authentication Failed code: type: string description: Machine-readable error code identifying the failure reason. example: request_failed type: type: string description: Category of the error, indicating the error class. example: authentication_error RateLimitResponse: type: object properties: message: type: string description: Human-readable description of the rate limit breach. example: Too many requests from IP. Check headers code: type: string description: Machine-readable error code identifying the failure reason. example: request_failed type: type: string description: Category of the error, indicating the error class. example: rate_limit_error InternalServerErrorResponse: type: object properties: message: type: string description: Human-readable description of the server-side error. example: internal Server Error code: type: string description: Machine-readable error code identifying the failure reason. example: internal_error type: type: string description: Category of the error, indicating the error class. example: api_error securitySchemes: XClientID: type: apiKey in: header name: x-client-id description: >- Your unique client identifier issued by Cashfree. You can find this in your [Merchant Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys). XClientSecret: type: apiKey in: header name: x-client-secret description: >- Your unique client secret issued by Cashfree. Keep this confidential and never expose it in client-side code. You can find this in your [Merchant Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys). ````