> ## 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 Request
> Use this API to initiate a bill fetch or bill validation request for a customer.
This is an **async** API. It returns only an acknowledgement with a `ref_id`.
The actual bill details must be retrieved separately by polling the Bill Fetch Response API using this `ref_id`.
This API is only applicable for billers whose `fetch_requirement` or `support_bill_validation` is `MANDATORY` or `OPTIONAL`. For billers where both are `NOT_SUPPORTED` (i.e., `DIRECT_PAY` flow), calling this API will return a validation error. Proceed directly to the Bill Payment Request API for those billers.
The flow is determined using `fetch_requirement` and `support_bill_validation` from the Fetch Billers Info API response, evaluated in the following priority order:
| Priority | `fetch_requirement` | `support_bill_validation` | Flow |
|---|---|---|---|
| 1 | `MANDATORY` | Any | `FETCH_AND_PAY` |
| 2 | `NOT_SUPPORTED` | `MANDATORY` or `OPTIONAL` | `VALIDATE_AND_PAY` |
| 3 | `NOT_SUPPORTED` | `NOT_SUPPORTED` | `DIRECT_PAY` |
| 4 | `OPTIONAL` | `MANDATORY` | `VALIDATE_AND_PAY` |
| 5 | `OPTIONAL` | Any other | `FETCH_AND_PAY` |
For `DIRECT_PAY`, skip the bill fetch step and proceed directly to the Bill Payment Request API.
Store the `flow` field from the response. It determines which fields to expect in the Bill Fetch Response and whether a bill payment can proceed without a prior fetch.
## OpenAPI
````yaml openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/request/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/request/bill-fetch:
post:
tags:
- Bill Fetch
summary: Bill Fetch Request
description: >-
Use this API to initiate a bill fetch or bill validation request for a
customer.
This is an **async** API. It returns only an acknowledgement with a
`ref_id`.
The actual bill details must be retrieved separately by polling the Bill
Fetch Response API using this `ref_id`.
This API is only applicable for billers whose `fetch_requirement` or
`support_bill_validation` is `MANDATORY` or `OPTIONAL`. For billers
where both are `NOT_SUPPORTED` (i.e., `DIRECT_PAY` flow), calling this
API will return a validation error. Proceed directly to the Bill Payment
Request API for those billers.
The flow is determined using `fetch_requirement` and
`support_bill_validation` from the Fetch Billers Info API response,
evaluated in the following priority order:
| Priority | `fetch_requirement` | `support_bill_validation` | Flow |
|---|---|---|---|
| 1 | `MANDATORY` | Any | `FETCH_AND_PAY` |
| 2 | `NOT_SUPPORTED` | `MANDATORY` or `OPTIONAL` | `VALIDATE_AND_PAY` |
| 3 | `NOT_SUPPORTED` | `NOT_SUPPORTED` | `DIRECT_PAY` |
| 4 | `OPTIONAL` | `MANDATORY` | `VALIDATE_AND_PAY` |
| 5 | `OPTIONAL` | Any other | `FETCH_AND_PAY` |
For `DIRECT_PAY`, skip the bill fetch step and proceed directly to the
Bill Payment Request API.
Store the `flow` field from the response. It determines which fields to
expect in the Bill Fetch Response and whether a bill payment can proceed
without a prior fetch.
operationId: billFetchRequest
requestBody:
description: >-
Request parameters to initiate a bill fetch or bill validation
request.
required: true
content:
application/json:
schema:
type: object
required:
- bill_fetch_request
properties:
bill_fetch_request:
type: object
required:
- agent_id
- biller_id
- input_params
properties:
agent_id:
type: string
description: Unique ID of the Agent Institution.
example: OU01XXXXINT001123456
biller_id:
type: string
description: Biller ID as returned by the Fetch Billers Info API.
example: VODA00000MUM03
agent_device_info:
type: object
description: >
Device metadata. Mandatory for FETCH_AND_PAY; optional
for VALIDATE_AND_PAY. At least one sub-field must be
non-null.
properties:
init_channel:
type: string
description: 'Initiating channel. Example: INT, MOB, ATM.'
example: INT
ip:
type: string
description: IP address of the device initiating the request.
example: 124.170.23.22
mobile:
type: string
description: Mobile number of the agent device.
example: '9830098300'
geo_code:
type: string
description: >-
GPS coordinates of the device in
"latitude,longitude" format.
example: 12.9667,77.5667
postal_code:
type: string
description: Postal code of the device location.
example: '400063'
terminal_id:
type: string
description: Unique terminal identifier for the agent device.
example: '1234556'
imei:
type: string
description: IMEI number of the mobile device.
example: '123456789012345'
ifsc:
type: string
description: IFSC code of the agent's bank branch.
example: ABCD0001234
mac:
type: string
description: MAC address of the device.
example: 00-0D-60-07-2A-F0
os:
type: string
description: >-
Operating system of the device. Example values are
iOS and Android.
example: iOS
app:
type: string
description: >-
Name of the agent application initiating the
request.
example: AGENTAPP
customer_info:
type: object
description: Customer details. Mandatory for FETCH_AND_PAY.
required:
- customer_mobile
properties:
customer_mobile:
type: string
description: >-
Mobile number of the customer initiating the bill
fetch.
example: 9505XXXX98
customer_email:
type: string
description: Customer's email address.
example: customer@example.com
aadhaar:
type: string
description: Customer's 12-digit Aadhaar number.
example: '123456789012'
pan:
type: string
description: Customer's PAN card number.
example: BXXCG7754K
input_params:
type: object
required:
- input
description: Customer identifiers matching the biller configuration.
properties:
input:
type: array
minItems: 1
items:
type: object
required:
- param_name
- param_value
properties:
param_name:
type: string
description: Must match the biller config param name.
example: RefFld1
param_value:
type: string
description: >-
Value for the corresponding param_name, such
as the customer's mobile number or consumer
ID.
example: '9876543210'
example:
bill_fetch_request:
agent_id: OU01XXXXINT001123456
biller_id: VODA00000MUM03
agent_device_info:
init_channel: INT
ip: 124.170.23.22
mobile: '9830098300'
geo_code: 12.9667,77.5667
postal_code: '400063'
customer_info:
customer_mobile: 9505XXXX98
customer_email: customer@example.com
input_params:
input:
- param_name: RefFld1
param_value: '9876543210'
- param_name: RefFld2
param_value: ABCD123
responses:
'202':
description: >-
Success response for initiating a bill fetch or bill validation
request.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Always "ACCEPTED" when the request is successfully queued.
example: ACCEPTED
message:
type: string
description: >-
Human-readable confirmation that the request has been
accepted for async processing.
example: Bill fetch request accepted for processing
data:
type: object
description: >-
Acknowledgement data returned immediately upon request
acceptance.
properties:
ref_id:
type: string
description: >-
Unique reference ID for this request. Use this to poll
the Bill Fetch Response API.
example: HENSVVR4QOS7X1UGPY7JGUV444P10102202
status:
type: string
description: >-
Processing status of the request. Always "PROCESSING"
at this stage.
example: PROCESSING
flow:
type: string
description: >-
Payment flow determined by the biller configuration.
For FETCH_AND_PAY and VALIDATE_AND_PAY, store this
value to know which fields to expect in the Bill Fetch
Response. For DIRECT_PAY, skip the bill fetch step
entirely and proceed directly to the Bill Payment
Request API.
enum:
- FETCH_AND_PAY
- VALIDATE_AND_PAY
- DIRECT_PAY
example: FETCH_AND_PAY
'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).
````