> ## 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`.
| Biller Configuration | NBBL Request Sent | Flow in Response |
|---|---|---|
| `fetch_requirement` = MANDATORY or OPTIONAL | BillFetchRequest | `FETCH_AND_PAY` |
| `support_bill_validation` = MANDATORY or OPTIONAL | BillValidationRequest | `VALIDATE_AND_PAY` |
| Both `NOT_SUPPORTED` | Error | Use Payment API directly |
Store the `flow` field from the response. It determines which fields to expect in the Bill Fetch Response.
## 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, 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/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`.
| Biller Configuration | NBBL Request Sent | Flow in Response |
|---|---|---|
| `fetch_requirement` = MANDATORY or OPTIONAL | BillFetchRequest |
`FETCH_AND_PAY` |
| `support_bill_validation` = MANDATORY or OPTIONAL |
BillValidationRequest | `VALIDATE_AND_PAY` |
| Both `NOT_SUPPORTED` | Error | Use Payment API directly |
Store the `flow` field from the response. It determines which fields to
expect in the Bill Fetch Response.
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
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
example: ACCEPTED
message:
type: string
example: Bill fetch request accepted for processing
data:
type: object
properties:
ref_id:
type: string
description: >-
Unique reference ID. Use this to poll the Bill Fetch
Response API.
example: HENSVVR4QOS7X1UGPY7JGUV444P10102202
status:
type: string
description: Always "PROCESSING".
example: PROCESSING
flow:
type: string
description: >-
Indicates the bill flow. Store this value for
downstream logic.
enum:
- FETCH_AND_PAY
- VALIDATE_AND_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'
'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).
````