> ## 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, complaint 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 required: - bill_fetch_ref_id - pg_reference_id properties: bill_fetch_ref_id: type: string description: ref_id received from the Bill Fetch API. example: HENSVVR4QOS7X1UGPY7JGUV444P10102202 pg_reference_id: type: string description: Internal PG reference ID. example: PG_REF_001 customer: type: object required: - mobile properties: mobile: type: string example: '9505987798' tag: type: array description: >- Optional customer identifier tags. Supported values are EMAIL, AADHAAR, and PAN. items: type: object properties: name: type: string enum: - EMAIL - AADHAAR - PAN value: type: string agent: type: object required: - id - device properties: id: type: string description: Agent Institution ID. example: OU01AI34INT001123456 device: type: object required: - tag properties: tag: type: array minItems: 1 description: At least one device tag is required. items: type: object required: - name - value properties: name: type: string description: >- Supported tag names are INITIATING_CHANNEL, IP, MOBILE, GEOCODE, POSTAL_CODE, TERMINAL_ID, IMEI, IFSC, MAC, OS, and APP. example: INITIATING_CHANNEL value: type: string example: INT bill_details: type: object required: - biller - customer_params properties: biller: type: object required: - id properties: id: type: string description: Biller ID. example: VODA00000MUM03 customer_params: type: object required: - tag properties: tag: type: array minItems: 1 items: type: object required: - name - value properties: name: type: string example: RefFld1 value: type: string example: XX1234ABCD biller_response: type: object nullable: true description: > Optional. For categories such as Electricity, DTH, and Gas, all fields become mandatory if this object is included. properties: customer_name: type: string example: Manoj Chekuri amount: type: string description: Amount in paise example: '120000' due_date: type: string example: '2021-09-24' bill_date: type: string example: '2021-01-02' bill_number: type: string example: '1232332' bill_period: type: string example: MONTHLY additional_info: type: object nullable: true properties: tag: type: array items: type: object properties: name: type: string value: type: string 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: > At least one tag is required. Examples by payment mode: UPI requires VPA; Card requires CardNum and AuthCode; Bank requires IFSC and AccountNo; Wallet requires WalletName and MobileNo; AEPS requires Aadhaar and IIN. properties: tag: type: array minItems: 1 items: type: object required: - name - value properties: name: type: string example: VPA value: type: string 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 example: ACCEPTED message: type: string example: Bill payment request accepted for processing data: type: object properties: bill_fetch_ref_id: type: string example: HENSVVR4QOS7X1UGPY7JGUV444P10102202 transaction_ref_id: type: string description: >- Unique transaction ID. Use this along with bill_fetch_ref_id to poll the Payment Response API. example: OU011010ABCD12345678 status: type: string description: Always "PROCESSING". 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' '500': description: API related Error. components: schemas: ErrorResponse: type: object properties: status: type: string example: BAD_REQUEST message: type: string example: Validation error description data: nullable: true example: null UnauthorizedResponse: type: object properties: message: type: string example: Unauthorized 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). ````