> ## 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. The `bill_fetch_ref_id` is not required for the direct pay flow. ## 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. The `bill_fetch_ref_id` is not required for the direct pay flow. operationId: billPaymentRequest parameters: - $ref: '#/components/parameters/apiVersionHeader' 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: - 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. Not required for the direct pay flow, which has no prior 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 rupees as returned by the biller. example: '1200.00' 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 rupees. Pass the same value returned in the Bill Fetch Response. example: '1200.00' cust_conv_fee: type: string description: Customer convenience fee (CCF1) in rupees. example: '10.00' cou_cust_conv_fee: type: string description: COU convenience fee (CCF2) in rupees. example: '15.00' 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: '1200.00' 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: '1200.00' cust_conv_fee: '10.00' cou_cust_conv_fee: '15.00' currency: '356' payment_information: tag: - name: VPA value: account@provider responses: '202': description: Success response for initiating a bill payment request. headers: x-api-version: $ref: '#/components/headers/x-api-version' 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: parameters: apiVersionHeader: in: header name: x-api-version required: true description: API version to be used. Format is YYYY-MM-DD. schema: type: string default: '2025-01-01' example: '2025-01-01' x-ignore: true headers: x-api-version: schema: type: string format: YYYY-MM-DD enum: - '2025-01-01' description: >- The API version used to process the request. The current version is `2025-01-01`. 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). ````