> ## 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.
Poll at increasing intervals until `data.status` is no longer `"PROCESSING"`:
| Attempt | Wait before this poll |
|---|---|
| 1 | 5 seconds |
| 2 | 15 seconds |
| 3 | 30 seconds |
| 4 | 1 minute |
| 5+ | 3 minutes |
Stop polling when `data.status` is `"SUCCESS"` or `"FAILED"`. If the payment remains in a processing state beyond your retry limit, treat it as a timeout and raise a support ticket.
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, 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/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.
Poll at increasing intervals until `data.status` is no longer
`"PROCESSING"`:
| Attempt | Wait before this poll |
|---|---|
| 1 | 5 seconds |
| 2 | 15 seconds |
| 3 | 30 seconds |
| 4 | 1 minute |
| 5+ | 3 minutes |
Stop polling when `data.status` is `"SUCCESS"` or `"FAILED"`. If the
payment remains in a processing state beyond your retry limit, treat it
as a timeout and raise a support ticket.
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: >-
The bill_fetch_ref_id received in the Bill Payment Request
API response (data.bill_fetch_ref_id). Used to identify the
original bill fetch.
example: REF20240501ABC123
transaction_ref_id:
type: string
description: >-
The transaction_ref_id received in the Bill Payment Request
API response (data.transaction_ref_id). Used to identify
this specific payment transaction.
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: >-
Always "OK" for all poll responses, regardless of the
payment outcome.
example: OK
message:
type: string
description: Human-readable description of the current payment state.
example: Payment successful
data:
type: object
description: >-
Response payload containing the payment status and full
transaction details.
properties:
status:
type: string
description: >-
Actual payment outcome. Poll until this is no longer
"PROCESSING". Terminal states are "SUCCESS" and
"FAILED".
enum:
- PROCESSING
- SUCCESS
- FAILED
example: SUCCESS
response:
type: object
description: >-
Full transaction response returned by the BBPS
network.
properties:
bill_payment_response:
type: object
description: >-
Core payment response block containing transaction
identifiers, result codes, and bill details.
properties:
head:
type: object
description: >-
Header block echoing back the reference IDs
from the payment request.
properties:
bill_fetch_ref_id:
type: string
description: >-
The bill_fetch_ref_id from the original
Bill Fetch Request, echoed back for
correlation.
reason:
type: object
description: >-
Result codes and descriptions returned by the
biller for this transaction.
properties:
approval_ref_num:
type: string
nullable: true
description: >-
Internal approval reference number
assigned by the biller on success. Null on
failure or while processing.
example: APPR123456
response_code:
type: string
description: >-
Response code from the biller. "000"
indicates success, "PENDING" indicates the
payment is still processing, and any other
value indicates failure.
example: '000'
response_reason:
type: string
description: >-
Human-readable description of the response
code.
example: Approved
compliance_resp_cd:
type: string
nullable: true
description: >-
Compliance failure code returned by the
biller. Present only on failure.
compliance_reason:
type: string
nullable: true
description: >-
Human-readable description of the
compliance failure code. Present only on
failure.
txn:
type: object
description: Transaction identifier block.
properties:
transaction_ref_id:
type: string
description: >-
The transaction_ref_id from the Bill
Payment Request, echoed back for
correlation.
bill_details:
type: object
nullable: true
description: >-
Customer reference parameters echoed back from
the payment request. Present only on success.
properties:
customer_params:
type: array
description: >-
List of name-value pairs representing the
customer identifiers used in the payment.
items:
type: object
properties:
name:
type: string
description: >-
Parameter name matching the biller's
customer param config.
value:
type: string
description: >-
Value for the corresponding customer
parameter.
biller_response:
type: object
nullable: true
description: >-
Bill details confirmed by the biller after
payment. Present only on success.
properties:
customer_name:
type: string
nullable: true
description: >-
Name of the customer as registered with
the biller.
amount:
type: string
description: Total bill amount settled in paise.
due_date:
type: string
nullable: true
description: Bill due date in yyyy-MM-dd format.
bill_date:
type: string
nullable: true
description: >-
Date the bill was generated in yyyy-MM-dd
format.
bill_number:
type: string
nullable: true
description: Unique bill number issued by the biller.
bill_period:
type: string
nullable: true
description: Billing cycle period for the settled bill.
cust_conv_fee:
type: string
nullable: true
description: >-
Customer convenience fee charged for this
transaction in paise.
additional_info:
type: object
nullable: true
description: >-
Additional biller-specific metadata returned
after payment. Present only on success.
properties:
info:
type: array
description: >-
List of name-value pairs containing
biller-specific payment metadata.
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.
examples:
pending:
summary: Pending
value:
status: OK
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: OK
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: OK
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'
'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).
````