Bill Fetch

Biller will provide a bill fetch API to Cashfree and using this API Cashfree will fulfill any bill fetch request that Cashfree receives from end users. This is triggered when a customer requests for the latest bill data that they are supposed to pay.

API flow for Bill Fetch

API flow for Bill Fetch

Request Parameters

Request ParametersTypeDescriptionOptional/Mandatory
customerObjectcustomer details object - will contain detail which assist to fetch the bill.Mandatory
customer.mobileStringcustomer mobile number -will be passed if the payment app sends it.Optional
customer.attributesList of ObjectList of customer attributes to fetch bill.Mandatory
customer.attributes.keyStringName of attribute which biller needs to fetch bill.
This parameters will be fixed during onboarding.

There can be more than 1 parameter which are allowed to be configured. That call is to be taken by the biller.
customer.attributes.valueStringValue of attribute which biller needs to fetch bill. This will be corresponding to each key.Mandatory

Once Cashfree calls Bill fetch APIs with the above request body, Biller needs to respond with bill details in the below prescribed format. This data will be shown to the consumer on the payment app they are using.

Response Parameters

Response ParametersTypeDescriptionOptional/Mandatory
statusStringSignifies if the bill fetch has given a successful result or not.
Allowed values - ‘success’, ‘failed’
response_codeStringResponse code for failed bill fetch. Allowed Values -
- invalid_attribute
- no_pending_dues
- unknown

When to use the following codes -
- ‘invalid_attribute’ to be used when biller can’t identify the customer from the entered attributes.

- ‘no_pending_dues’ to be used when there are no pending bills for the customer.

- ‘unknown’ to be used when any other issue occurs while making a request.
Mandatory in case the status field is “failed”.

Not to be included for ‘success’ status.
response_messageStringThis will be shown to the customer on the payment app when the bill fetch fails.Mandatory in case the status field is “failed”.

Not to be included for ‘success’ status.
customer_nameStringCustomer Name as per the biller.Mandatory
bill_dateStringDate on which the bill is generated.
bill_date must not be future date wrt date of fetching the bill and must always be less then or equal to due_date.

Format: dd-mm–yyyy.
bill_numberStringBill id generated by biller. Users will see this on the payment app.Mandatory
bill_periodStringFrequency of such bill being generated
Allowed values -
- daily
- weekly
- monthly
- yearly
- ad hoc
due_dateStringDate on which the bill is due.
Format: dd-mm–yyyy.
bill_reference_numberStringUnique reference number generated by biller for a bill. This won’t be exposed to user.
This needs to be unique as payment posting calls will refer to this.
additional_InfoObjectUse this object in case you want to pass any additional details to your customer.

This object will be configured during onboarding depending on what extra information the biller wants to pass to their customer.

It is structured as a key-value pair. Max 4 additional info parameters are allowed.
amount_detailsObjectThis object contains details about total amount due (mandatory) and breakup (optional) of that.Mandatory
amount_details.total_amountDecimal to 2 digitsTotal bill amount as per biller. Please put precision up to 2 digits of decimal. The currency is assumed as ‘inr’.Mandatory
amount_details.break_up[]List of objectsList of object containing amount break details. Each object is structured as type, value, sale.Optional
amount_details.break_up[].typeStringType defines what category of breakup it falls in.
The following fixed values are allowed -
- base
- tax
- late_fees
- discount
- prev_credits, adjustments
amount_details.break_up[].valueDecimal to 2 digitsValue corresponding to type. Please put precision up to 2 digits of decimal. The currency is assumed as ‘inr’.Optional
amount_details.break_up[].saleStringWhether the value adds up positively or negatively to define the total.
The following fixed values are allowed -
- positive
- negative
Error Response Codes
typeStringMandatoryError type values:
- connection_error
- internal_error
- authentication_error
- rate_limit_error
- validation_error
messageStringMandatoryThis will be used for debugging or shown to the customer.
Click Try It! to start a request and see the response here!