Bill Fetch API

The Bill Fetch API will fetch data from the biller and provide responses with pending amounts and other useful information.

📘

Note:

Send the scope of the Get Token API as read_billers to obtain the access_token for this request. For more information, refer to Get Token API - BBPS.

Sample request
curl --location --request POST 'https://<hostName>/payu-nbc/v1/nbc/billfetchrequest?agentId=`{agentId}`&billerId=`{billerId}`&customerName=`{customerName}`&customerPhoneNumber=`{customerPhoneNumber}`&timeStamp=`{timestamp in yyyy-MM-dd HH:mm:ss}`&refId=`{Reference Id}`&customerParams={
"<paramName>": "<paramValue>"
}&deviceDetails={
    "INITIATING_CHANNEL": "INT/MOB",
    "IP": "xx.xx.xx.xx",
    "MAC": "xx.xxx.xxx.xx”}
 \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'
Response parameters

Field Name

Description

code

This field contains the global response code and can be any of the following:

  • 0: If web service call failed
  • 1: if web service call succeeded

status

The status of the API command and can be any of the following:

  • SUCCESS
  • FAILURE

payload

This parameter contains the bill fetch transaction data.

refId

This parameter contains the Reference Identification Number. The length of refID will be between 34 to 35.

timeStamp

This parameter contains the current time stamp of the server.

amount

This parameter contains the amount to be paid.

accountHolderName

This parameter contains the account holder name as on the bill.

dueDate

This parameter contains the due date of the bill.

billDate

This parameter contains the billing date of bill.

billerId

This parameter contains the biller Identification ID that is unique number for each customer given by the operator.

amountDetails

This parameter contains breakup details of total payable amount. (this details may not be available).

billNumber

Unique identifier of the bill.

billPeriod

Billing period of the bill. Most possible values are as mentioned below.

additionalParams

This parameter contains the additional information if any available from the biller side for both BBPS and Non BBPS billers.
For example, if there is any additional information like early payment fee, late payment fee, early payment date ,late payment due date, DTC code etc. has been mentioned in any biller MDM, additional parameters will contain those values as in key value pairs:\

"additionalParams":{  
"Early Pay Date":" \< date1 > ",  
"Early Payment Fee":" \< fee1 > ",  
"Late Payment Date":" \< date2 > ",  
"Late Payment Fee":"",  
"DTC code":" \< code > ",  
"Base Bill Amount":""  
}

Similarly, in case of Non BBPS biller wants to share any additional information, it will be sent to agent in additional parameters itself.

Sample response

Success scenario

{
  "code": 200,
  "status": "SUCCESS",
  "payload": {
    "refId": "<reference ID>",
    "timeStamp": "<yyyy-MM-dd hh:mm:ss>",
    "amount": "<amount to be paid>",
    "accountHolderName": "<account customer name>",
    "dueDate": "<yyyy-MM-dd>",
    "billDate": "<yyyy-MM-dd>",
    "billerId": "<Biller-Id>",
    "amountDetails": [
      {
        "<paramName>": "<paramNameValue>"
      }
    ],
    "additionalParams": {
      "Key1": "value1",
      "Key2": "value2",
      "Key3": "value3"
    },
    "billNumber":"<billNumber>",
    "billPeriod":"<Period of bill>",
    "approvalRefNum":"<bbps biller approval Ref Number>"
  }
}

Failure scenario

{
  "code": 600,
  "status": "failure",
  "payload": {
    "errors": [
      {
        "reason": "<Error Message>",
        "errorCode": "<Error Code>"
      }
    ],
    "refId": "<referenceID>",
    "type": "fetch",
    "message": "fetch_request_failed",
    "additionalParams": {
      "Key1": "value1",
      "Key2": "value2",
      "Key3": "value3"
    }
  }
}

Request parameters

Language
Credentials
Bearer
Click Try It! to start a request and see the response here!