Bill Fetch API

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


Test Environment .
Production EnvironmentContact your Account Manager to get access to the production environment



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>"
    "IP": "xx.xx.xx.xx",
    "MAC": "”}
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'
Response parameters
Field NameDescription
codeThis 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
statusThe status of the API command and can be any of the following:

payloadThis parameter contains the bill fetch transaction data.
refIdThis parameter contains the Reference Identification Number. The length of refID will be between 34 to 35.
timeStampThis parameter contains the current time stamp of the server.
amountThis parameter contains the amount to be paid.
accountHolderNameThis parameter contains the account holder name as on the bill.
dueDateThis parameter contains the due date of the bill.
billDateThis parameter contains the billing date of bill.
billerIdThis parameter contains the biller Identification ID that is unique number for each customer given by the operator.
amountDetailsThis parameter contains breakup details of total payable amount. (this details may not be available).
billNumberUnique identifier of the bill.
billPeriodBilling period of the bill. Most possible values are as mentioned below.
additionalParamsThis 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"
    "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

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