BBPS API SPECIFICATIONS

Munisekhar Udavalapati — Thu, 09 Jan 2025 13:33:36 +0000

1. Bill Fetch Request (BBPCU to Biller BBPOU)

This API is used to fetch the bill details for a customer.

{
  "Head": {
    "ver": "1.0",
    "ts": "2021-01-10T22:02:45+05:30",
    "origInst": "BBPCU",
    "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "Txn": {
    "txnReferenceId": "BBPCU0001FET000123456",
    "ts": "2021-01-10T22:02:45+05:30",
    "type": "BILL FETCH REQUEST",
    "msgId": "8ENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "Customer": {
    "mobile": "9505987798",
    "Tags": [
      {"name": "EMAIL", "value": "manoj.chekuri@npci.org.in"},
      {"name": "AADHAAR", "value": "123456789012"},
      {"name": "PAN", "value": "BXXCG7754K"}
    ]
  },
  "Agent": {
    "id": "BBPCUAGENT001",
    "Device": {
      "Tags": [
        {"name": "MOBILE", "value": "9830098300"},
        {"name": "POSTAL_CODE", "value": "400063"},
        {"name": "IP", "value": "124.170.23.22"}
      ]
    }
  },
  "BillDetails": {
    "Biller": {"id": "VODA00000MUM03"},
    "CustomerParams": {
      "Tags": [
        {"name": "RefFld1", "value": "XX1234ABCD"}
      ]
    }
  }
}

2. Bill Fetch Response (Biller BBPOU to BBPCU)

The response from the biller will return the details of the bill, including customer details, amount, bill period, etc.

{
  "Head": {
    "ver": "1.0",
    "ts": "2021-01-10T22:02:50+05:30",
    "origInst": "BBPOU",
    "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "Reason": {
    "responseCode": "000/200",
    "responseReason": "Successful"
  },
  "Txn": {
    "txnReferenceId": "BBPCU0001FET000123456",
    "ts": "2021-01-10T22:02:45+05:30",
    "type": "BILL FETCH RESPONSE",
    "msgId": "8ENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "BillerResponse": {
    "customerName": "Manoj Chekuri",
    "amount": "120000",
    "dueDate": "2021-09-24",
    "billDate": "2021-01-02",
    "billNumber": "1232332",
    "billPeriod": "ONETIME"
  },
  "AdditionalInfo": {
    "Tags": [
      {"name": "BillFetchField1", "value": "Additional data if any"}
    ]
  }
}

3. Bill Payment Request (BBPCU to Biller BBPOU)

This is the request sent from BBPCU to the biller (BBPOU) for initiating a bill payment.

{
  "Head": {
    "ver": "1.0",
    "ts": "2021-01-10T22:02:45+05:30",
    "origInst": "BBPCU",
    "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "Txn": {
    "txnReferenceId": "BBPCU0001PAY000123456",
    "ts": "2021-01-10T22:02:45+05:30",
    "type": "BILL PAYMENT REQUEST",
    "msgId": "8ENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "Customer": {
    "mobile": "9505987798",
    "Tags": [
      {"name": "EMAIL", "value": "manoj.chekuri@npci.org.in"},
      {"name": "AADHAAR", "value": "123456789012"},
      {"name": "PAN", "value": "BXXCG7754K"}
    ]
  },
  "Agent": {
    "id": "BBPCUAGENT001",
    "Device": {
      "Tags": [
        {"name": "MOBILE", "value": "9830098300"},
        {"name": "POSTAL_CODE", "value": "400063"},
        {"name": "IP", "value": "124.170.23.22"}
      ]
    }
  },
  "BillDetails": {
    "Biller": {"id": "VODA00000MUM03"},
    "CustomerParams": {
      "Tags": [
        {"name": "RefFld1", "value": "XX1234ABCD"}
      ]
    }
  },
  "Amount": {
    "Amt": {
      "amount": "120000",
      "custConvFee": "1000",
      "currency": "356"
    }
  },
  "PaymentInformation": {
    "Tags": [
      {"name": "Remarks", "value": "Cash Payment"},
      {"name": "CardNum|AuthCode", "value": "4386280020697301|123456"}
    ]
  }
}

4. Bill Payment Response (Biller BBPOU to BBPCU)

This is the response from the biller acknowledging the bill payment.

{
  "Head": {
    "ver": "1.0",
    "ts": "2021-01-10T22:02:50+05:30",
    "origInst": "BBPOU",
    "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "Reason": {
    "approvalRefNum": "AB123456",
    "responseCode": "000/200",
    "responseReason": "Successful"
  },
  "Txn": {
    "txnReferenceId": "BBPCU0001PAY000123456",
    "ts": "2021-01-10T22:02:45+05:30",
    "type": "BILL PAYMENT RESPONSE",
    "msgId": "8ENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "BillerResponse": {
    "customerName": "Manoj Chekuri",
    "amount": "120000",
    "dueDate": "2021-09-24",
    "billDate": "2021-01-02",
    "billNumber": "1232332",
    "billPeriod": "ONETIME"
  },
  "AdditionalInfo": {
    "Tags": [
      {"name": "PaymentBlRspFld1", "value": "Successfully Paid"}
    ]
  }
}

Summary of Structure: