> ## 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 Response
> Use this API to poll for the result of a previously submitted bill payment request. Call this using both `bill_fetch_ref_id` and `transaction_ref_id` from the Bill Payment Request API.
Continue polling until `data.status` is no longer `"processing"`. Terminal states are `"success"` and `"failed"`.
processing: Payment is still in progress. Continue polling.success: Payment completed successfully.failed: Payment failed.
## OpenAPI
````yaml /openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/response/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/response/bill-payment:
post:
tags:
- Bill Payment
summary: Bill Payment Response (Polling)
description: >
Use this API to poll for the result of a previously submitted bill
payment request. Call this using both `bill_fetch_ref_id` and
`transaction_ref_id` from the Bill Payment Request API.
Continue polling until `data.status` is no longer `"processing"`.
Terminal states are `"success"` and `"failed"`.
processing: Payment is still in progress. Continue polling.success: Payment completed successfully.failed: Payment failed.
operationId: getBillPaymentStatus
requestBody:
description: Request parameters to poll a bill payment request.
required: true
content:
application/json:
schema:
type: object
required:
- bill_fetch_ref_id
- transaction_ref_id
properties:
bill_fetch_ref_id:
type: string
description: >-
Ref ID from the Bill Payment Request API
(data.bill_fetch_ref_id).
example: REF20240501ABC123
transaction_ref_id:
type: string
description: >-
Transaction ref ID from the Bill Payment Request API
(data.transaction_ref_id).
example: TXN20240501XYZ789
example:
bill_fetch_ref_id: REF20240501ABC123
transaction_ref_id: TXN20240501XYZ789
responses:
'200':
description: Success response for polling a bill payment request.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: API call status. This is always "success".
example: success
message:
type: string
example: Payment successful
data:
type: object
properties:
status:
type: string
description: Actual payment outcome.
enum:
- processing
- success
- failed
example: success
response:
type: object
properties:
bill_payment_response:
type: object
properties:
head:
type: object
properties:
bill_fetch_ref_id:
type: string
reason:
type: object
properties:
approval_ref_num:
type: string
nullable: true
example: APPR123456
response_code:
type: string
description: >-
"000" on success, "PENDING" while
processing, or an error code on failure.
example: '000'
response_reason:
type: string
example: Approved
compliance_resp_cd:
type: string
nullable: true
description: Present only on failure.
compliance_reason:
type: string
nullable: true
description: Present only on failure.
txn:
type: object
properties:
transaction_ref_id:
type: string
bill_details:
type: object
nullable: true
description: Present only on SUCCESS.
properties:
customer_params:
type: array
items:
type: object
properties:
name:
type: string
value:
type: string
biller_response:
type: object
nullable: true
description: Present only on SUCCESS.
properties:
customer_name:
type: string
nullable: true
amount:
type: string
description: Amount in paise.
due_date:
type: string
nullable: true
bill_date:
type: string
nullable: true
bill_number:
type: string
nullable: true
bill_period:
type: string
nullable: true
cust_conv_fee:
type: string
nullable: true
description: Convenience fee in paise.
additional_info:
type: object
nullable: true
description: Present only on SUCCESS.
properties:
info:
type: array
items:
type: object
properties:
name:
type: string
value:
type: string
examples:
pending:
summary: Pending
value:
status: success
message: Payment is still being processed
data:
status: processing
response:
bill_payment_response:
head:
bill_fetch_ref_id: REF20240501ABC123
reason:
response_code: PENDING
response_reason: Processing
txn:
transaction_ref_id: TXN20240501XYZ789
success:
summary: Success
value:
status: success
message: Payment successful
data:
status: success
response:
bill_payment_response:
head:
bill_fetch_ref_id: REF20240501ABC123
reason:
approval_ref_num: APPR123456
response_code: '000'
response_reason: Approved
txn:
transaction_ref_id: TXN20240501XYZ789
biller_response:
customer_name: John Doe
amount: '150000'
due_date: 30/06/2024
bill_date: 01/06/2024
bill_number: BILL20240601
bill_period: June 2024
cust_conv_fee: '100'
failed:
summary: Failed
value:
status: success
message: Payment failed
data:
status: failed
response:
bill_payment_response:
head:
bill_fetch_ref_id: REF20240501ABC123
reason:
approval_ref_num: null
response_code: BM001
response_reason: Biller unavailable
compliance_resp_cd: C001
compliance_reason: Transaction declined by biller
txn:
transaction_ref_id: TXN20240501XYZ789
'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).
````