get https://biller-base-url.com/billfetch
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
Request Parameters
| Request Parameters | Type | Description | Optional/Mandatory |
|---|---|---|---|
| customer | Object | customer details object - will contain detail which assist to fetch the bill. | Mandatory |
| customer.mobile | String | customer mobile number -will be passed if the payment app sends it. | Optional |
| customer.attributes | List of Object | List of customer attributes to fetch bill. | Mandatory |
| customer.attributes.key | String | Name 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. | Mandatory |
| customer.attributes.value | String | Value 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 Parameters | Type | Description | Optional/Mandatory |
|---|---|---|---|
| status | String | Signifies if the bill fetch has given a successful result or not. Allowed values - ‘success’, ‘failed’ | Mandatory |
| response_code | String | Response 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_message | String | This 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_name | String | Customer Name as per the biller. | Mandatory |
| bill_date | String | Date 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. | Mandatory |
| bill_number | String | Bill id generated by biller. Users will see this on the payment app. | Mandatory |
| bill_period | String | Frequency of such bill being generated Allowed values - - daily - weekly - monthly - yearly - ad hoc | Optional |
| due_date | String | Date on which the bill is due. Format: dd-mm–yyyy. | Optional |
| bill_reference_number | String | Unique 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. | Mandatory |
| additional_Info | Object | Use 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. | Optional |
| amount_details | Object | This object contains details about total amount due (mandatory) and breakup (optional) of that. | Mandatory |
| amount_details.total_amount | Decimal to 2 digits | Total 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 objects | List of object containing amount break details. Each object is structured as type, value, sale. | Optional |
| amount_details.break_up[].type | String | Type defines what category of breakup it falls in. The following fixed values are allowed - - base - tax - late_fees - discount - prev_credits, adjustments | Optional |
| amount_details.break_up[].value | Decimal to 2 digits | Value corresponding to type. Please put precision up to 2 digits of decimal. The currency is assumed as ‘inr’. | Optional |
| amount_details.break_up[].sale | String | Whether the value adds up positively or negatively to define the total. The following fixed values are allowed - - positive - negative | Optional |
Error Response Codes
| Parameter | Type | Mandatory/Optional | Description |
|---|---|---|---|
| type | String | Mandatory | Error type values: - connection_error - internal_error - authentication_error - rate_limit_error - validation_error |
| code | String | Mandatory | |
| message | String | Mandatory | This will be used for debugging or shown to the customer. |