Overview

This API initiates a bill fetch request from a BOU through NPCI to (Biller) and gets a response from the biller for the concerned bill

This is sent by Setu system to biller system. Biller needs to handle 4 scenarios as given below :

1. 1. Successful Fetch
2. 2. Customer Not Found / Invalid identifier
3. 3. No Amount Due / Payment already made
4. 4. API Error / All other error scenarios

For loan cateogory some mandatory parameters include :

1. 1. Customer Name
2. 2. Amount
3. 3. Bill Date
4. 4. Due Date
5. 5. Bill Period

Other parameters can also be added as Additional Info eg. Interest, Penalty etc.

These parameters listed above must be a part of a successful fetch response (excluding additional info).

Sample Request

Request is made based on unique identifier selected by biller, in this case it can be Loan Number.

This is a sample POST request to some endpoint given by the biller's technical team. This can also be a simple GET request with loan_number as a Parameter.

{
  "loan_number": "123456789"
  // any other identifier can be added here
}

Note: loan_number is as per business use case and can be changed

Success Response

{
  "status": "SUCCESS",
  "errorCode": "00",
  "customerName": "Ashok Kumar",
  "amountDue": "1290.20",
  "billDate": "2021-07-15",
  "dueDate": "2021-07-30",
  "billNumber": "TUVW1234",
  "billPeriod": "MONTHLY",
  "additionalInfo": {
    "interest": "value1", // Optional
    "penalty": "value2" // Optional
    // ... MAX 4
  }
}

Points to consider :

1. billDate must not be future date ( wrt date of fetching the bill ) and must always be less then or equal to dueDate
2. Max 4 additional info parameters are allowed

Customer Not Found

Triggered when invalid credentials are entered. In this case when incorrect loan_number is entered by customer.

{
  "status": "FAILURE",
  "errorCode": "01"
}

No Amount Due

Triggered when payment has already been made for this particular set of identifiers.

{
  "status": "FAILURE",
  "errorCode": "02"
}

API Error

Triggered when any other issue occurs while making a request.

{
  "status": "FAILURE",
  "errorCode": "03"
}