> ## 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 Fetch Response
> Use this API to poll the result of a previously initiated Bill Fetch or Bill Validation request.
Use the `ref_id` from the Bill Fetch Request API to retrieve the status and bill details.
Poll at increasing intervals until `message` is no longer `"Request is still being processed"`:
| Attempt | Wait before this poll |
|---|---|
| 1 | 5 seconds |
| 2 | 15 seconds |
| 3 | 30 seconds |
| 4 | 1 minute |
| 5+ | 3 minutes |
Stop polling when `message` is `"Bill details fetched successfully"` or `"Bill request failed"`. If the request remains in a processing state beyond your retry limit, treat it as a timeout and raise a support ticket.
- `bill_fetch_response` is present in every response, including success, failure, and pending states.
- For `FETCH_AND_PAY` success, the response includes `bill_fetch_response`, `bill_details`, `biller_response`, and `additional_info`.
- For `FETCH_AND_PAY` failure, the response includes only `bill_fetch_response`.
- For `VALIDATE_AND_PAY` success, the response includes `bill_fetch_response` and `additional_info`.
- For `VALIDATE_AND_PAY` failure, the response includes only `bill_fetch_response`.
- While the request is pending, the response includes only `bill_fetch_response`, with the processing status.
## OpenAPI
````yaml openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/response/bill-fetch
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-fetch:
post:
tags:
- Bill Fetch
summary: Bill Fetch Response (Polling)
description: >-
Use this API to poll the result of a previously initiated Bill Fetch or
Bill Validation request.
Use the `ref_id` from the Bill Fetch Request API to retrieve the status
and bill details.
Poll at increasing intervals until `message` is no longer `"Request is
still being processed"`:
| Attempt | Wait before this poll |
|---|---|
| 1 | 5 seconds |
| 2 | 15 seconds |
| 3 | 30 seconds |
| 4 | 1 minute |
| 5+ | 3 minutes |
Stop polling when `message` is `"Bill details fetched successfully"` or
`"Bill request failed"`. If the request remains in a processing state
beyond your retry limit, treat it as a timeout and raise a support
ticket.
- `bill_fetch_response` is present in every response, including success,
failure, and pending states.
- For `FETCH_AND_PAY` success, the response includes
`bill_fetch_response`, `bill_details`, `biller_response`, and
`additional_info`.
- For `FETCH_AND_PAY` failure, the response includes only
`bill_fetch_response`.
- For `VALIDATE_AND_PAY` success, the response includes
`bill_fetch_response` and `additional_info`.
- For `VALIDATE_AND_PAY` failure, the response includes only
`bill_fetch_response`.
- While the request is pending, the response includes only
`bill_fetch_response`, with the processing status.
operationId: getBillFetchStatus
requestBody:
description: Request parameters to poll a bill fetch or bill validation request.
required: true
content:
application/json:
schema:
type: object
required:
- ref_id
properties:
ref_id:
type: string
description: >-
The reference ID received from the Bill Fetch Request API.
Used to identify and retrieve the result of the
corresponding async request.
example: HENSVVR4QOS7X1UGPY7JGUV444P10102202
example:
ref_id: HENSVVR4QOS7X1UGPY7JGUV444P10102202
responses:
'200':
description: >-
Success response for polling a bill fetch or bill validation
request.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: >-
Always "OK" for all poll responses, regardless of the bill
fetch outcome.
example: OK
message:
type: string
description: >-
Terminal or in-progress status of the bill fetch
operation. Continue polling while this is "Request is
still being processed".
enum:
- Bill details fetched successfully
- Request is still being processed
- Bill request failed
data:
type: object
description: >-
Response payload. Always contains bill_fetch_response;
other fields depend on the flow and outcome.
properties:
bill_fetch_response:
type: object
description: >-
Core response block present in all poll responses,
including pending, success, and failure states.
properties:
ref_id:
type: string
description: >-
Reference ID echoed back from the Bill Fetch
Request, used to correlate the polling response
with the original request.
example: HENSVVR4QOS7X1UGPY7JGUV444P10102202
approval_ref_num:
type: string
nullable: true
description: >-
Internal reference number assigned by the biller
on success. Present only on successful responses.
example: AB123456
response_code:
type: string
nullable: true
description: >-
Response code from the biller. "000" indicates
success, "PENDING" indicates the request is still
being processed, and any other value indicates a
failure.
example: '000'
response_reason:
type: string
nullable: true
description: Human-readable description of the response code.
example: Successful
compliance_resp_cd:
type: string
nullable: true
description: >-
Compliance failure code returned by the biller.
Present only on failure.
example: BFR001
compliance_reason:
type: string
nullable: true
description: >-
Human-readable description of the compliance
failure code. Present only on failure.
example: Incorrect / invalid customer account
bill_details:
type: object
nullable: true
description: >-
Customer reference parameters echoed back from the
request. Present only for FETCH_AND_PAY SUCCESS.
properties:
customer_params:
type: object
description: Wrapper for the list of customer identifier tags.
properties:
tag:
type: array
description: >-
List of name-value pairs representing customer
identifiers, such as consumer number and
mobile.
items:
type: object
properties:
name:
type: string
description: >-
Parameter name matching the biller's
customer param config.
value:
type: string
description: >-
Corresponding value provided by the
customer.
biller_response:
type: object
nullable: true
description: >-
Bill details returned by the biller. Present only for
FETCH_AND_PAY SUCCESS.
properties:
customer_name:
type: string
nullable: true
description: >-
Name of the customer as registered with the
biller.
amount:
type: string
description: Total payable amount in paise.
example: '120000'
due_date:
type: string
nullable: true
description: Bill due date in yyyy-MM-dd format.
example: '2021-09-24'
bill_date:
type: string
nullable: true
description: Date the bill was generated in yyyy-MM-dd format.
example: '2021-01-02'
bill_number:
type: string
nullable: true
description: Unique bill number issued by the biller.
example: '1232332'
bill_period:
type: string
nullable: true
description: >-
Billing cycle period. Example values are MONTHLY
and QUARTERLY.
example: MONTHLY
tag:
type: array
nullable: true
description: >-
Additional biller-specific amount breakup fields,
such as base amount and late charges.
items:
type: object
properties:
name:
type: string
description: Breakup field name.
value:
type: string
description: Breakup field value in paise.
additional_info:
type: object
nullable: true
description: >-
Biller-specific additional fields. Present for
FETCH_AND_PAY SUCCESS and all VALIDATE_AND_PAY
responses.
properties:
tag:
type: array
description: >-
List of name-value pairs with biller-specific
metadata.
items:
type: object
properties:
name:
type: string
description: >-
Field name as defined by the biller's MDM
config.
value:
type: string
description: Corresponding field value.
examples:
pending:
summary: Pending (both flows)
value:
status: OK
message: Request is still being processed
data:
bill_fetch_response:
ref_id: HENSVVR4QOS7X1UGPY7JGUV444P10102202
response_code: PENDING
response_reason: Processing
success_fetch_and_pay:
summary: Success for FETCH_AND_PAY
value:
status: OK
message: Bill details fetched successfully
data:
bill_fetch_response:
ref_id: HENSVVR4QOS7X1UGPY7JGUV444P10102202
approval_ref_num: AB123456
response_code: '000'
response_reason: Successful
bill_details:
customer_params:
tag:
- name: RefFld1
value: '9876543210'
biller_response:
customer_name: Manoj Chekuri
amount: '120000'
due_date: '2021-09-24'
bill_date: '2021-01-02'
bill_number: '1232332'
bill_period: MONTHLY
additional_info:
tag:
- name: BlRspFld1
value: someValue
success_validate_and_pay:
summary: Success for VALIDATE_AND_PAY
value:
status: OK
message: Bill details fetched successfully
data:
bill_fetch_response:
ref_id: HENSVVR4QOS7X1UGPY7JGUV444P10102202
approval_ref_num: AB123456
response_code: '000'
response_reason: Successful
additional_info:
tag:
- name: BlRspFld1
value: ''
failed:
summary: Failed (both flows)
value:
status: OK
message: Bill request failed
data:
bill_fetch_response:
ref_id: HENSVVR4QOS7X1UGPY7JGUV444P10102202
response_code: '500'
response_reason: Failure
compliance_resp_cd: BFR001
compliance_reason: Incorrect / invalid customer account
'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).
````