# BBPS

**Bharat Bill Payment System is a Reserve Bank of India (RBI) conceptualised system driven by National Payments Corporation of India (NPCI) which offers integrated,accessible and interoperable recurring payment services to consumers across geographies with certainty, reliability and safety of transactions.**

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2FIoHIdJupiB5BMtsdEIjK%2FScreenshot%20from%202023-06-06%2014-34-49.png?alt=media&amp;token=775fc9ff-4767-45cb-a9a8-255b5f26703a" alt=""><figcaption></figcaption></figure>

&#x20;       Bharat BillPay is an ecosystem that provides one-stop interoperable bill payment solution for recurring payments and enables the consumers of banks and non-banks across India to make bill payment via their preferred mode of channel like Mobile App, Mobile Banking, Website/Pre-login, Internet Banking, ATM, KIOSK Physical centres like Agent, Bank-Branch, Business Correspondents BBPOU Bank/Non-bank entity facing Customer BBPOU Bank/Non- bank entity connected with Biller. Consumers 3 | P a g e Bharat Bill Payment System created a network through interoperability thereby extending the reach of a traditional utility bill payment system giving customer access through multiple payment channels and methods.

**Key features that are unique to BBPS are highlighted below**

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2FM256ux6vYBwmeDarv0l5%2Fimage.png?alt=media&amp;token=ac3ac95d-b85d-40c7-8f4d-57900e7a259f" alt=""><figcaption></figcaption></figure>

{% tabs %}
{% tab title="AGENT INTEGRATION" %}
{% content-ref url="/pages/bDWOXdXNJuxezA6BngkX" %}
[BBPS Agent Integration](/untitled/bbps/bbps-agent-integration)
{% endcontent-ref %}
{% endtab %}

{% tab title="BILLER  INTEGRATION" %}
{% content-ref url="/pages/ziO5utCKCrHB4VXuayn0" %}
[BBPS Biller Integration](/untitled/bbps/bbps-biller-integration)
{% endcontent-ref %}
{% endtab %}
{% endtabs %}


# BBPS Agent Integration

**This document provides the overview of BBPS Agent integration and the APIs used for the same. The document also provides a list of frequently asked questions and steps to register with Bank and NPCI**

Overview of bill payment using BBPS

* BBPS allows the customer to pay the bills in the following ways based on the biller types.
* Apart from paying bills, customers can raise grievances using the complaint registering mechanism.

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2FIoHIdJupiB5BMtsdEIjK%2FScreenshot%20from%202023-06-06%2014-34-49.png?alt=media&amp;token=775fc9ff-4767-45cb-a9a8-255b5f26703a" alt=""><figcaption></figcaption></figure>

The above picture provides a high level overview of the BBPS system. BBPOUs (Bharat Bill Pay Operating Units ) are the entities directly connected to NPCI.

**Broadly there are three major entities apart from billers and agents**

* Customer BBPOU - The entities where agents are connected. Eg: agent. Google Pay , a banking correspondent
* Biller BBPOU : The entities where billers are connected. Eg: Electricity board, Netflix.
* CU : NPCI who does the central switching.

Consumers are connected to agents , agents are connected to banks (Customer BBPOOUs) , BBPOUs are connected to NPCI, NPCI is connected to BIller BBPOUs and Biller BBPOU is connected to billers.


# Broad examples of bill payments

<mark style="color:blue;">Bill payments could be broadly classified into</mark>

* Payments with bills.
* Payments without bills but by validating the customer data.
* Quick payments with out validating customer information.
* Payments for subscription.
* Payments for invoices.
* Payments with standing instructions.
* Etc

To understand the above scenarios in detail we will take the first three cases with examples .

1. The scenarios where we have a bill the customer will want to see the bill and then make a decision to pay the bill . Example , fetching an electricity bill and then making the payment.Such scenarios are called “Fetch and Pay” type of bill payment . It is called “Fetch and Pay” because , first the bill is fetched and then the payment is made.
2. In scenarios where there is no bill but the biller wants to validate customer data , the customer will input customer data and make the payment. Example , a DTH payment where the payment is in advance and there is no bill .Such scenarios are called “Validate and Pay” type of bill payment . It is called “Validate and Pay” because , first the customer details are validated and then the payment is made.
3. If a customer wants to pay money quickly to a biller , one could use quick pay.
4. If Fetch and Validation is not supported , biller supports only QuickPay.
5. The above concepts relates a biller to a specific workflow of paying the bills.

One needs to understand about payment of bill amount in relation to the exactness of the bill amount .

* A biller which supports adhoc payment can accept any amount .
* Another parameter which should be considered is paymentAmountExactness .
* This parameter denotes how the biller collects the amount for a bill.
* If paymentAmountExactness is Exact will collect only exact amount
* If paymentAmountExactness is “Exact and above” biller will collect only an exact amount or more. In this scenario GUI should provide an option of editing the amount .
* If paymentAmountExactness is “Exact and below” biller will collect only an exact amount or less. In this scenario GUI should provide an option of editing the amount .
* If the biller support ad hoc mode of bill payment , the parameter paymentAmountExactness does not have an effect . The biller can take any amount of money.

<br>


# How a bill is presented

<mark style="color:blue;">**A bill is presented with the help of following properties**</mark>

* Biller response{billerResponse} and additional information .
* BIller response contains summary of the bill and amount options .
* Amount Options explains the line items of a bill.Detailed items will be present if amountOption is set to true in the bill JSON. The property tagList contains the various line items.

<pre class="language-json" data-overflow="wrap"><code class="lang-json">// Given below is an example of the bill.

{
 	"genericResponse": null,
 	"billId": "c884a1a7-6824-499d-849c-acbb853f3cc6",
 	"refId": "118GQ1X2ndXcIXVkJTMRARlrLln23261125",
 	"billerId": "OTOE00005XXZ43",
 	"status": "BILL_FETCH_SUCCESS",
 	"actionType": "BILL_FETCH",
 	"userId": "FE41FE42BNK519012345",
 	"billerResponse": {
 	"billId": "c884a1a7-6824-499d-849c-acbb853f3cc6",
 	"amount": "100000",
 	"billDate": "2015-06-14",
 	"billNumber": "12303",
 	"billPeriod": "june",
 	"custConvFee": "0",
 	"couCustConvFee": "0",
 	"dueDate": "2015-06-20",
 	"customerName": "BBPS",
 	"amountOption": true,
 	"tagList": [
 	{
 	"name": "Late Payment Fee",
 	"value": "40"
 	},
 	{
 	"name": "Fixed Charges",
 	"value": "50"
 	},
 	{
 	"name": "Additional Charges",
 	"value": "60"
 	},
 	{
 	"name": "BASE_BILL_AMOUNT",
 	"value": "100000"
 	}
 	]
 	},
 	"additionalInfo": [
 	{
<strong>         "additionalInfoId": null,
</strong>         "name": "a",
         "value": "10"
         },
         {
         "additionalInfoId": null,
         "name": "a b",
         "value": "20"
         },
         {
         "additionalInfoId": null,
         "name": "a b c",
         "value": "30"
         },
         {
         "additionalInfoId": null,
         "name": "a b c d",
         "value": "40"
         }
         ],
         "customerParams": [
         {
         "name": "a",
         "value": "10",
         "type": null
         },
         {
         "name": "a b",
         "value": "20",
         "type": null
         },
         {
         "name": "a b c",
         "value": "30",
         "type": null
         },
         {
         "name": "a b c d",
         "value": "40",
         "type": null
         },
         {
         "name": "a b c d e",
         "value": "50",
         "type": null
         }
         ],
         "creationDate": "2022-11-22T11:25:14.807217",
         "modifiedDate": "2022-11-22T11:25:15.424531",
         "createdEpochDate": 1669096514,
         "modifiedEpochDate": 1669096515
}

</code></pre>

### The above example contains following line items

* **Late Payment Fee**
* **Fixed Charges**
* **Additional Charges**
* **BASE\_BILL\_AMOUNT**<br>

The tag BASE\_BILL\_AMOUNT is a special one which points to amount property in billerResponse

property of bill JSON.

If amount option is present , then the application needs to call master API and get AmountBreakUp Set.

Suggested method is before each presentation , the application should fetch AmountBreakUpSet.

additionalInfo is another property in Bill JSON. additionalInfo provides additional information

about the bill. This is for providing additional information to the user . Property additionalInfo does not have an impact on bill payment. Application can display the content of additionalInfo to the user.

Property customerParams is used by the biller to identify the bill for a customer.

An application should create the GUI dynamically making use of the parameters in the bill and with master data of the biller ,irrespective of biller type or any other parameters . In this way the application need not be re-written for any present or future biller in the BBPS ecosystem.

<br>


# FETCH AND PAY

Fetch the bill for a customer and make the payment

<mark style="color:blue;">Example: Fetch and pay flow diagram.</mark>

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2FhdUg4pd55MptVyLdHVbr%2Fimage.png?alt=media&amp;token=73f3c7b0-628e-4a81-b715-c83d97da3da1" alt=""><figcaption></figcaption></figure>


# Bill fetch api

API for fetching a Customer Bill, based on Biller Category, Customer Parameters etc.

Endpoint: \
Request: POST /couapp/bills/fetch

#### Request body&#x20;

<table><thead><tr><th width="140">Parent Property/Element</th><th width="228">Property/Element Name</th><th width="121">Mandatory</th><th width="172">Data Type</th><th width="278">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>tenantId</td><td>M</td><td>Alphanumeric</td><td>Fixed Length – 4</td></tr><tr><td></td><td>billerId</td><td>M</td><td>Alphanumeric</td><td>Unique ID assigned to the Biller by NPCI Eg: BSNL00000NATHL</td></tr><tr><td></td><td>billerName</td><td>M</td><td>String</td><td>Name of the biller</td></tr><tr><td></td><td>billerCategory</td><td>M</td><td>String</td><td>Category of biller</td></tr><tr><td></td><td>clientReqId</td><td>C</td><td>String</td><td>A unique id which the client has to provide</td></tr><tr><td></td><td>macAdress</td><td>C</td><td>Alphanumeric</td><td>MAC Address of the Agent Server</td></tr><tr><td></td><td>customerMobNo</td><td>M</td><td>String</td><td>Mobile of the Customer, on whose behalf the Agent is paying the Bill</td></tr><tr><td></td><td>paymentChannel</td><td>M</td><td>String</td><td>Payment Channel of Agent</td></tr><tr><td></td><td>deviceBlockTags</td><td>M</td><td>Array of tags</td><td>Device block tags of Agent</td></tr><tr><td></td><td>customerParamsRequest</td><td>M</td><td>Object</td><td>Unique parameters used for identifying a Customer Bill</td></tr><tr><td>customerParamsRequest</td><td>tags</td><td>M</td><td>List</td><td>List of customer params</td></tr><tr><td>tags</td><td>name</td><td>M</td><td>String</td><td>Name of customer param</td></tr><tr><td>tags</td><td>value</td><td>M</td><td>String</td><td>Value of customer param</td></tr></tbody></table>

<pre class="language-json"><code class="lang-json">{
    "tenantId": "FE41",
    "billerId": "DKAFEE000PUN01"
    "customerParamsRequest": {
        "tags": [
            {
                "name": "Admission No/Application No/GR No",
                "value": "LF3130"
            },
            {
                "name": "Date Of Birth (DD-MM-YYYY)"
            },
            {
                "name": "Mobile No"
            }
        ]
    },
    "billerName": "Little Flower Convent School",
    "billerCategory": "Education Fees",
    "macAdress": null,
    "customerMobNo": "8281970522”,
<strong>    "paymentChannel": "Agent",
</strong>    "deviceBlockTags": [
        {
            "name": "MOBILE",
            "value": "9591810218"
        },
        {
            "name": "GEOCODE",
            "value": "28.6139,78.5555"
        },
        {
            "name": "POSTAL_CODE",
            "value": "600001"
        },
        {
            "name": "TERMINAL_ID",
            "value": "333001"
        }
    ]
}
</code></pre>

#### Response body

<table><thead><tr><th width="236">Parent Property/Element</th><th width="221">Property/Element Name</th><th>Mandatory</th><th width="87">Data Type</th><th width="205">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billId</td><td>C</td><td>UUID</td><td>Machine-generated Unique ID for a Bill, used internally</td></tr><tr><td></td><td>refId</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>billerId</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>status</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>actionType</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>billerResponse</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>additionalInfo</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>customerParams</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>creationDate</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>modifiedDate</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>createdEpochDate</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>modifiedEpochDate</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td>generalResp</td><td>statusCode</td><td>M</td><td>Numeric</td><td>200- SUCCESS Other than 200-Failure</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>It is either “Success” or failure</td></tr><tr><td></td><td>message</td><td>M</td><td>String</td><td>Contains the reason message for failure / success</td></tr><tr><td></td><td>remarks</td><td>C</td><td>String</td><td></td></tr></tbody></table>

```json
{
    "genericResponse": {
        "statusCode": "200",
        "status": "success",
        "message": "Bill Fetch Initiated",
        "remarks": ""
    },
    "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684",
    "refId": null,
    "billerId": null,
    "status": null,
    "actionType": null,
    "userId": null,
    "billerResponse": null,
    "additionalInfo": null,
    "customerParams": null,
    "creationDate": null,
    "modifiedDate": null,
    "createdEpochDate": 0,
    "modifiedEpochDate": 0
}
```


# Bill Fetch by bill id api

API for fetching a Customer Bill, based on bill id.

Endpoint:\
Request: GET /couapp/bills/fetch/byId?billId=1ced7566-1add-4e01-9ed6-04cd67ac9684

#### Request body

<table><thead><tr><th width="242">Parent Property/Element</th><th width="218">Property/Element Name</th><th width="127">Mandatory</th><th width="117">Data Type</th><th width="248">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billId</td><td>M</td><td>UUID</td><td>Bill id is unique id which is generated while initiating the bill fetch request, it can be get from the bill fetch response.</td></tr></tbody></table>

#### Response body

<table><thead><tr><th width="242">Parent Property/Element</th><th width="225">Property/Element Name</th><th width="151">Mandatory</th><th width="151">Data Type</th><th width="230">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billId</td><td>M</td><td>UUID</td><td>Machine-generated Unique ID for a Bill, used internally</td></tr><tr><td></td><td>refId</td><td>M</td><td>Alphanumeric</td><td>Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages</td></tr><tr><td></td><td>billerId</td><td>M</td><td>String</td><td>Unique ID assigned to the Biller by NPCI Fixed length - 14</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>Status of the Operation</td></tr><tr><td></td><td>actionType</td><td>C</td><td>String</td><td>Type of Bill Payment. Possible Values: BILL_FETCH QUICKPAY BILL_VALIDATE</td></tr><tr><td></td><td>userId</td><td>M</td><td>Alphanumeric</td><td>Agent id Fixed length - 20</td></tr><tr><td></td><td>creationDate</td><td>M</td><td>String</td><td>ISO 8601 Timestamp for the Bill Creation date</td></tr><tr><td></td><td>modifiedDate</td><td>M</td><td>String</td><td>ISO 8601 Timestamp for the Bill Modification date</td></tr><tr><td></td><td>createdEpochDate</td><td>M</td><td>Numeric</td><td>UNIX Epoch Timestamp for the Bill Creation date</td></tr><tr><td></td><td>modifiedEpochDate</td><td>M</td><td>Numeric</td><td>UNIX Epoch Timestamp for the Bill Modification date</td></tr><tr><td>billerResponse</td><td>billId</td><td>M</td><td>String</td><td>Machine-generated Unique ID for a Bill, used internally</td></tr><tr><td></td><td>amount</td><td>M</td><td>String</td><td>Actual bill amount inclusive of all charges</td></tr><tr><td></td><td>billDate</td><td>M</td><td>String</td><td>This field denotes generation date of the bill</td></tr><tr><td></td><td>billNumber</td><td>M</td><td>String</td><td>This field denotes the bill number of the bill fetch / payment message requested</td></tr><tr><td></td><td>billPeriod</td><td>M</td><td>String</td><td>The bill period of the bill fetch / payment requested</td></tr><tr><td></td><td>custConvFee</td><td>M</td><td>String</td><td>Customer convenience fee (CCF1) paid by the Customer Operating Unit</td></tr><tr><td></td><td>couCustConvFee</td><td>M</td><td>String</td><td>Customer convenience fee (CCF2), paid by the Customer to Customer Operating Unit</td></tr><tr><td></td><td>dueDate</td><td>M</td><td>String</td><td>This field denotes due date of the bill</td></tr><tr><td></td><td>customerName</td><td>M</td><td>String</td><td>This field denotes customer name</td></tr><tr><td></td><td>amountOption</td><td>M</td><td>Boolean</td><td>A flag indicating if the Biller supports Amount Options</td></tr><tr><td></td><td>tagList</td><td>M</td><td>String</td><td>Amount Breakup Options eg:{"name": "Additional Charges", "value": "500"}</td></tr><tr><td>additionalInfo</td><td>name</td><td>C</td><td>String</td><td>Name of the Additional Info Parameter</td></tr><tr><td></td><td>value</td><td>C</td><td>String</td><td>Value of the Additional Info Parameter</td></tr><tr><td>customerParams</td><td>name</td><td>C</td><td>String</td><td>Name of the Customer Parameter attribute</td></tr><tr><td></td><td>value</td><td>C</td><td>String</td><td>Value of the Customer Parameter attribute</td></tr><tr><td>generalResp</td><td>statusCode</td><td>M</td><td>Numeric</td><td>200- SUCCESS Other than 200-Failure</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>It is either “Success” or failure</td></tr><tr><td></td><td>message</td><td>M</td><td>String</td><td>Contains the reason message for failure / success</td></tr><tr><td></td><td>remarks</td><td>C</td><td>String</td><td>Remarks</td></tr></tbody></table>

#### Success response

```json
{
    "genericResponse": {
        "message": "",
        "remarks": "",
        "status": "Success",
        "statusCode": "200"
    },
    "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684",
    "refId": "BlgcYxtJCrLU18BDm8rVDHQl0Hqf9x2XONi",
    "billerId": "DKAFEE000PUN01",
    "status": "BILL_FETCH_SUCCESS",
    "actionType": "BILL_FETCH",
    "userId": "FE41FE42BNK519012345",
    "billerResponse": {
        "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684",
        "amount": "1142000",
        "billDate": "2021-12-09",
        "billNumber": "59",
        "billPeriod": "NA",
        "custConvFee": "0",
        "couCustConvFee": "0",
        "dueDate": "2022-01-31",
        "customerName": "AGAMJOT TEST ",
        "amountOption": false,
        "tagList": null
    },
    "additionalInfo": [
        {
            "additionalInfoId": null,
            "name": "Student Name",
            "value": "AGAMJOT TEST "
        },
        {
            "additionalInfoId": null,
            "name": "Father Name",
            "value": "VIRENDER SINGH"
        },
        {
            "additionalInfoId": null,
            "name": "Class",
            "value": "STD I"
        },
        {
            "additionalInfoId": null,
            "name": "Section",
            "value": "A"
        },
        {
            "additionalInfoId": null,
            "name": "TUITION FEE",
            "value": "8670"
        },
        {
            "additionalInfoId": null,
            "name": "E-CARE FEE",
            "value": "900"
        },
        {
            "additionalInfoId": null,
            "name": "COMPUTER FEE",
            "value": "1350"
        },
        {
            "additionalInfoId": null,
            "name": "EXAM FEE",
            "value": "500"
        }
    ],
    "customerParams": [
        {
            "name": "Admission No/Application No/GR No",
            "value": "LF3130",
            "type": null
        },
        {
            "name": "Date Of Birth (DD-MM-YYYY)",
            "value": null,
            "type": null
        },
        {
            "name": "Mobile No",
            "value": null,
            "type": null
        }
    ],
    "creationDate": "2021-12-09T08:37:40.082462",
    "modifiedDate": "2021-12-09T08:37:42.303627",
    "createdEpochDate": 1639039060,
    "modifiedEpochDate": 1639039062
}
```

#### Failure response

```json
{
    "genericResponse": {
        "message": "",
        "remarks": "Fetch Request not supported, only QuickPay permitted",
        "status": "Failure",
        "statusCode": "500"
    },
    "billId": "XXXXXXXX-7d79-4e3c-bd2d-382276669ba9",
    "refId": "xxXXXxxxxxS4VZlr9bUF2lCCzFc4823081150",
    "billerId": "XXXXXXXXXXXXXX",
    "status": "BILL_FETCH_FAILED",
    "actionType": "BILL_FETCH",
    "userId": "FE41XXXXXXXXXXXXXX",
    "billerResponse": null,
    "customerParams": [
        {}
    ],
    "creationDate": "2022-11-04T11:50:50+05:30",
    "modifiedDate": "2022-11-04T11:50:50.460818",
    "createdEpochDate": 1667542850,
    "modifiedEpochDate": 1667542850
}
```


# Bill Fetch by client request id api

API for fetching a Customer Bill, based on Client Request ID.

Endpoint:\
Request: GET /couapp/bills/fetch/byClientId?clientReqId=vgRdasd248

#### Request body

<table><thead><tr><th width="248">Parent Property/Element</th><th width="219">Property/Element Name</th><th width="121">Mandatory</th><th width="172">Data Type</th><th width="373">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>clientReqId</td><td>M</td><td>Alphanumeric</td><td>Fixed Length – 10</td></tr></tbody></table>

#### Response body

<table><thead><tr><th width="241">Parent Property/Element</th><th width="215">Property/Element Name</th><th width="129">Mandatory</th><th width="152">Data Type</th><th width="295">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billId</td><td>M</td><td>UUID</td><td>Machine-generated Unique ID for a Bill, used internally</td></tr><tr><td></td><td>refId</td><td>M</td><td>Alphanumeric</td><td>Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages</td></tr><tr><td></td><td>billerId</td><td>M</td><td>String</td><td>Unique ID assigned to the Biller by NPCI Fixed length - 14</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>Status of the Operation</td></tr><tr><td></td><td>actionType</td><td>C</td><td>String</td><td>Type of Bill Payment. Possible Values: BILL_FETCH QUICKPAY BILL_VALIDATE</td></tr><tr><td></td><td>userId</td><td>M</td><td>Alphanumeric</td><td>Agent id Fixed length - 20</td></tr><tr><td></td><td>creationDate</td><td>M</td><td>String</td><td>ISO 8601 Timestamp for the Bill Creation date</td></tr><tr><td></td><td>modifiedDate</td><td>M</td><td>String</td><td>ISO 8601 Timestamp for the Bill Modification date</td></tr><tr><td></td><td>createdEpochDate</td><td>M</td><td>Numeric</td><td>UNIX Epoch Timestamp for the Bill Creation date</td></tr><tr><td></td><td>modifiedEpochDate</td><td>M</td><td>Numeric</td><td>UNIX Epoch Timestamp for the Bill Modification date</td></tr><tr><td>billerResponse</td><td>billId</td><td>M</td><td>String</td><td>Machine-generated Unique ID for a Bill, used internally</td></tr><tr><td></td><td>amount</td><td>M</td><td>String</td><td>Actual bill amount inclusive of all charges</td></tr><tr><td></td><td>billDate</td><td>M</td><td>String</td><td>This field denotes generation date of the bill</td></tr><tr><td></td><td>billNumber</td><td>M</td><td>String</td><td>This field denotes the bill number of the bill fetch / payment message requested</td></tr><tr><td></td><td>billPeriod</td><td>M</td><td>String</td><td>The bill period of the bill fetch / payment requested</td></tr><tr><td></td><td>custConvFee</td><td>M</td><td>String</td><td>Customer convenience fee (CCF1) paid by the Customer Operating Unit</td></tr><tr><td></td><td>couCustConvFee</td><td>M</td><td>String</td><td>Customer convenience fee (CCF2), paid by the Customer to Customer Operating Unit</td></tr><tr><td></td><td>dueDate</td><td>M</td><td>String</td><td>This field denotes due date of the bill</td></tr><tr><td></td><td>customerName</td><td>M</td><td>String</td><td>This field denotes due date of the bill</td></tr><tr><td></td><td>amountOption</td><td>M</td><td>Boolean</td><td>A flag indicating if the Biller supports Amount Options</td></tr><tr><td></td><td>tagList</td><td>M</td><td>String</td><td>Amount Breakup Options eg:{"name": "Additional Charges", "value": "500"}</td></tr><tr><td>additionalInfo</td><td>name</td><td>C</td><td>String</td><td>Name of the Additional Info Parameter</td></tr><tr><td></td><td>value</td><td>C</td><td>String</td><td>Value of the Additional Info Parameter</td></tr><tr><td>customerParams</td><td>name</td><td>C</td><td>String</td><td>Name of the Customer Parameter attribute</td></tr><tr><td></td><td>value</td><td>C</td><td>String</td><td>Value of the Customer Parameter attribute</td></tr><tr><td></td><td>statusCode</td><td>M</td><td>Numeric</td><td>200- SUCCESS Other than 200-Failure</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>It is either “Success” or failure</td></tr><tr><td></td><td>message</td><td>M</td><td>String</td><td>Contains the reason message for failure / success</td></tr><tr><td></td><td>remarks</td><td>C</td><td>String</td><td>Remarks</td></tr></tbody></table>

#### Success response

```json
{
    "genericResponse": {
        "message": "",
        "remarks": "",
        "status": "Success",
        "statusCode": "200"
    },
    "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684",
    "refId": "BlgcYxtJCrLU18BDm8rVDHQl0Hqf9x2XONi",
    "billerId": "DKAFEE000PUN01",
    "status": "BILL_FETCH_SUCCESS",
    "actionType": "BILL_FETCH",
    "userId": "FE41FE42BNK519012345",
    "billerResponse": {
        "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684",
        "amount": "1142000",
        "billDate": "2021-12-09",
        "billNumber": "59",
        "billPeriod": "NA",
        "custConvFee": "0",
        "couCustConvFee": "0",
        "dueDate": "2022-01-31",
        "customerName": "AGAMJOT TEST ",
        "amountOption": false,
        "tagList": null
    },
    "additionalInfo": [
        {
            "additionalInfoId": null,
            "name": "Student Name",
            "value": "AGAMJOT TEST "
        },
        {
            "additionalInfoId": null,
            "name": "Father Name",
            "value": "VIRENDER SINGH"
        },
        {
            "additionalInfoId": null,
            "name": "Class",
            "value": "STD I"
        },
        {
            "additionalInfoId": null,
            "name": "Section",
            "value": "A"
        },
        {
            "additionalInfoId": null,
            "name": "TUITION FEE",
            "value": "8670"
        },
        {
            "additionalInfoId": null,
            "name": "E-CARE FEE",
            "value": "900"
        },
        {
            "additionalInfoId": null,
            "name": "COMPUTER FEE",
            "value": "1350"
        },
        {
            "additionalInfoId": null,
            "name": "EXAM FEE",
            "value": "500"
        }
    ],
    "customerParams": [
        {
            "name": "Admission No/Application No/GR No",
            "value": "LF3130",
            "type": null
        },
        {
            "name": "Date Of Birth (DD-MM-YYYY)",
            "value": null,
            "type": null
        },
        {
            "name": "Mobile No",
            "value": null,
            "type": null
        }
    ],
    "creationDate": "2021-12-09T08:37:40.082462",
    "modifiedDate": "2021-12-09T08:37:42.303627",
    "createdEpochDate": 1639039060,
    "modifiedEpochDate": 1639039062
}
```

#### Failure response

```json
{
    "genericResponse": {
        "message": "",
        "remarks": "Fetch Request not supported, only QuickPay permitted",
        "status": "Failure",
        "statusCode": "500"
    },
    "billId": "XXXXXXXX-7d79-4e3c-bd2d-382276669ba9",
    "refId": "xxXXXxxxxxS4VZlr9bUF2lCCzFc4823081150",
    "billerId": "XXXXXXXXXXXXXX",
    "status": "BILL_FETCH_FAILED",
    "actionType": "BILL_FETCH",
    "userId": "FE41XXXXXXXXXXXXXX",
    "billerResponse": null,
    "customerParams": [
        {}
    ],
    "creationDate": "2022-11-04T11:50:50+05:30",
    "modifiedDate": "2022-11-04T11:50:50.460818",
    "createdEpochDate": 1667542850,
    "modifiedEpochDate": 1667542850
}
```


# VALIDATE AND PAY

Validate the customer details and make the payment

<mark style="color:blue;">Example: Bill details are taken from user and validated, if validation is success procced for payment.</mark>

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2FaLOMotcypp4YWZdyeiZt%2Fimage.png?alt=media&amp;token=799679f1-cac0-4474-b3f9-7a69d5becdda" alt=""><figcaption></figcaption></figure>


# Bill validate api

API for validating a Customer Bill, based on Biller Category, Customer Parameters etc.

Endpoint:\
Request: POST /couapp/bills/validate

#### Request body

<table><thead><tr><th width="243">Parent Property/Element</th><th width="235">Property/Element Name</th><th width="124">Mandatory</th><th width="157">Data Type</th><th width="232">Description</th></tr></thead><tbody><tr><td>[ROOT](No parent property / element)</td><td>tenantId</td><td>M</td><td>Alphanumeric</td><td>Fixed Length – 4</td></tr><tr><td></td><td>billerId</td><td>M</td><td>Alphanumeric</td><td>Unique ID assigned to the Biller by NPCI Eg: BSNL00000NATHL</td></tr><tr><td></td><td>billerName</td><td>M</td><td>String</td><td>Name of the biller</td></tr><tr><td></td><td>billerCategory</td><td>M</td><td>String</td><td>Category of biler</td></tr><tr><td></td><td>macAdress</td><td>C</td><td>Alphanumeric</td><td>MAC Address of the Agent Server</td></tr><tr><td></td><td>customerMobNo</td><td>M</td><td>String</td><td>Mobile of the Customer, on whose behalf the Agent is paying the Bill</td></tr><tr><td></td><td>clientReqId</td><td>C</td><td>String</td><td>A unique id which the client has to provide</td></tr><tr><td></td><td>customerParamsRequest</td><td>M</td><td>Object</td><td>Unique parameters used for identifying a Customer Bill</td></tr><tr><td>customerParamsRequest</td><td>tags</td><td>M</td><td>List</td><td>List of customer params</td></tr><tr><td>tags</td><td>name</td><td>M</td><td>String</td><td>Name of customer param</td></tr><tr><td></td><td>value</td><td>M</td><td>String</td><td>Value of customer param</td></tr></tbody></table>

```json
{
    "billerCategory": "Mobile Prepaid",
    "billerId": "FE1112000NAT01",
    "billerName": "Prepaid Biller1",
    "customerMobNo": "8281970523",
    "clientReqId": "",
    "customerParamsRequest": {
        "tags": [
            {
                "name": "Mobile Number",
                "value": "8900000010"
            },
            {
                "name": "Circle",
                "value": "circle10"
            }
        ]
    },
    "macAdress": null
}
```

#### Response body

<table><thead><tr><th width="247">Parent Property/Element</th><th width="219">Property/Element Name</th><th width="140">Mandatory</th><th width="141">Data type</th><th width="294">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billId</td><td>C</td><td>UUID</td><td>Machine-generated Unique ID for a Bill, used internally</td></tr><tr><td></td><td>refId</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>billerId</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>status</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>actionType</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>billerResponse</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>additionalInfo</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>customerParams</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>planInfoDaos</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>creationDate</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>modifiedDate</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>createdEpochDate</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td></td><td>modifiedEpochDate</td><td>C</td><td>String</td><td>Will be null</td></tr><tr><td>generalResp</td><td>statusCode</td><td>M</td><td>Numeric</td><td>200- SUCCESS Other than 200-Failure</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>It is either “Success” or failure</td></tr><tr><td></td><td>message</td><td>M</td><td>String</td><td>Contains the reason message for failure / success</td></tr><tr><td></td><td>remarks</td><td>C</td><td>String</td><td>Remarks</td></tr></tbody></table>

```json
{
    "genericResponse": {
        "statusCode": "200",
        "status": "success",
        "message": "Bill Validate Initiated",
        "remarks": ""
    },
    "billId": "c9670952-ebd7-487a-b6ea-49f2b4d4a718",
    "refId": null,
    "billerId": null,
    "status": null,
    "actionType": null,
    "userId": null,
    "billerResponse": null,
    "additionalInfo": null,
    "customerParams": null,
    "planInfoDaos": null,
    "creationDate": null,
    "modifiedDate": null,
    "createdEpochDate": 0,
    "modifiedEpochDate": 0
}
```


# Bill Validation response by client request id api

API for getting validation response, based on Client Request ID.

Endpoint:\
Request: GET /couapp/bills/validate/byClientId?clientReqId=vgRdasd248

#### Request body

<table><thead><tr><th width="244">Parent Property/Element</th><th width="224">Property/Element Name</th><th width="147">Mandatory</th><th width="161">Data Type</th><th width="280">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>clientReqId</td><td>M</td><td>Alphanumeric</td><td>Fixed Length – 10</td></tr></tbody></table>

#### Response body

<table><thead><tr><th width="244">Parent Property/Element</th><th width="225">Property/Element Name</th><th width="156">Mandatory</th><th width="144">Data Type</th><th width="284">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billId</td><td>M</td><td>UUID</td><td>Machine-generated Unique ID for a Bill, used internally</td></tr><tr><td></td><td>refId</td><td>M</td><td>Alphanumeric</td><td>Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages</td></tr><tr><td></td><td>billerId</td><td>M</td><td>String</td><td>Unique ID assigned to the Biller by NPCI Fixed length - 14</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>Status of the Operation Possible values : BILL_FETCH_REQUESTED, BILL_FETCH_INITIATED, BILL_FETCH_SUCCESS, BILL_FETCH_FAILED</td></tr><tr><td></td><td>actionType</td><td>C</td><td>String</td><td>Type of Bill Payment. Possible Values: BILL_FETCH QUICKPAY BILL_VALIDATE</td></tr><tr><td></td><td>userId</td><td>M</td><td>Alphanumeric</td><td>Agent id Fixed length - 20</td></tr><tr><td></td><td>creationDate</td><td>M</td><td>String</td><td>ISO 8601 Timestamp for the Bill Creation date</td></tr><tr><td></td><td>modifiedDate</td><td>M</td><td>String</td><td>ISO 8601 Timestamp for the Bill Modification date</td></tr><tr><td></td><td>createdEpochDate</td><td>M</td><td>Numeric</td><td>UNIX Epoch Timestamp for the Bill Creation date</td></tr><tr><td></td><td>modifiedEpochDate</td><td>M</td><td>Numeric</td><td>UNIX Epoch Timestamp for the Bill Modification date</td></tr><tr><td></td><td>billId</td><td>M</td><td>String</td><td>Machine-generated Unique ID for a Bill, used internally</td></tr><tr><td></td><td>amount</td><td>M</td><td>String</td><td>Actual bill amount inclusive of all charges</td></tr><tr><td></td><td>billDate</td><td>M</td><td>String</td><td>This field denotes generation date of the bill</td></tr><tr><td></td><td>billNumber</td><td>M</td><td>String</td><td>This field denotes the bill number of the bill fetch / payment message requested</td></tr><tr><td></td><td>billPeriod</td><td>M</td><td>String</td><td>The bill period of the bill fetch / payment requested</td></tr><tr><td></td><td>custConvFee</td><td>M</td><td>String</td><td>Customer convenience fee (CCF1) paid by the Customer Operating Unit</td></tr><tr><td></td><td>couCustConvFee</td><td>M</td><td>String</td><td>Customer convenience fee (CCF2), paid by the Customer to Customer Operating Unit</td></tr><tr><td></td><td>dueDate</td><td>M</td><td>String</td><td>This field denotes due date of the bill</td></tr><tr><td></td><td>customerName</td><td>M</td><td>String</td><td>This field denotes due date of the bill</td></tr><tr><td></td><td>amountOption</td><td>M</td><td>Boolean</td><td>A flag indicating if the Biller supports Amount Options</td></tr><tr><td></td><td>tagList</td><td>M</td><td>String</td><td>Amount Breakup Options eg:{"name": "Additional Charges", "value": "500"}</td></tr><tr><td>additionalInfo</td><td>name</td><td>C</td><td>String</td><td>Name of the Additional Info Parameter</td></tr><tr><td></td><td>value</td><td>C</td><td>String</td><td>Value of the Additional Info Parameter</td></tr><tr><td>customerParams</td><td>name</td><td>C</td><td>String</td><td>Name of the Customer Parameter attribute</td></tr><tr><td></td><td>value</td><td>C</td><td>String</td><td>Value of the Customer Parameter attribute</td></tr></tbody></table>

```json
{
    "genericResponse": null,
    "billId": "c9670952-ebd7-487a-b6ea-49f2b4d4a718",
    "refId": "ukpeZdOmtQCK4ByLFatdrWhtIiucPIXigYF",
    "billerId": "HUNG00000NATJL",
    "status": "BILL_VALIDATE_SUCCESS",
    "actionType": "VALIDATE_PAY",
    "userId": "FE41FE42BNK519012345",
    "billerResponse": null,
    "additionalInfo": [],
    "customerParams": [
        {
            "name": "Mobile Number",
            "value": "8281970522",
            "type": null
        },
        {
            "name": "Email ID",
            "value": "jithesh@digiledge.in",
            "type": null
        },
        {
            "name": "Id",
            "value": "2862",
            "type": null
        }
    ],
    "planInfoDaos": [],
    "creationDate": "2021-12-09T10:27:57.889640",
    "modifiedDate": "2021-12-09T10:28:02.775484",
    "createdEpochDate": 1639045677,
    "modifiedEpochDate": 1639045682
}
```


# Bill validation response by bill id api

API for getting validation response, based on Bill id.

Endpoint:\
Request: GET /couapp/bills/validate/byId?billId=c9670952-ebd7-487a-b6ea-49f2b4d4a718

#### Request body

<table><thead><tr><th width="242">Parent Property/Element</th><th width="214">Property/Element Name</th><th width="131">Mandatory</th><th width="160">Data type</th><th width="276">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>clientReqId</td><td>M</td><td>Alphanumeric</td><td>Fixed Length – 10</td></tr><tr><td></td><td></td><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td><td></td></tr></tbody></table>


# QUICK PAY

Make Quick payments

<mark style="color:blue;">**Example:Quick recharges**</mark>

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2Fm8jfxvh1ydawZzsGcNRj%2Fimage.png?alt=media&amp;token=5501178c-6362-44eb-9207-67178697f3ec" alt=""><figcaption></figcaption></figure>


# COMPLAINT RAISING

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2F7blKCqFpp0SnouWSnVJa%2Fimage.png?alt=media&amp;token=4ccd6529-cfa6-42ff-afb6-75db0055dda4" alt=""><figcaption></figcaption></figure>


# AGENT APPLICATION

Board steps to create an agent application

Example of an agent application is the application you are building or another prominent example is google pay .Broad functions of an agent application is

1. **To help the users to fetch the bill by displaying the details needed by the biller to identify the customer and fetch the bill .**
2. **Collect payment for the bill depending on the scenarios .**
3. **Help customer to track transitions and raise complaints**

<br>

To achieve the above the agent application should be able to create screens dynamically for a biller. This could be achieved with the help of Biller MDM data.Biller MDM is the master data about all the billers enrolled in the BBPS system .This could be done with the help of BBPS master data API .

One of the critical aspects of an agent application is to build the screen for each biller dynamically . This could be achieved with the help of two important parameters the Biller parameters and Customer Parameters

<details>

<summary>BILLER AND CUSTOMER PARAMETERS</summary>

Two important concepts to be understood are Biller Parameters and Customer Parameters. Biller Parameters - A set of parameters used to define the characteristics of of a biller Customer Parameters - A set of parameters used by the biller to identify a specific bill . Customer parameters will have a name, type and possible values accepted by the biller .For example an electricity board will use “consumer id” as a parameter to identify the customer. Now electricity board can identity a specific bill using a tuple *<mark style="color:blue;"><“consumer id”, “34561856”></mark> .* Another example can be that of a DTH company . Now DTH company can identity a specific customer using a tuple *<mark style="color:blue;"><“subscriber id”, “<561856@kk.com>”></mark>*

</details>

<details>

<summary>How agent applications can build screens dynamically</summary>

* Broad steps for creating an agent application will be .
* Fetch the BBPS master data .
* Create screen dynamically using biller parameter.
* Validate the input for a bill based on the customer parameter.
* Based on biller parameters, decide to use either fetch and pay OR validate and pay OR quick pay.
* Invoke the workflow

</details>


# BBPS Master Data API

<mark style="color:blue;">**List Amount option api**</mark>

API for listing Amount Breakup options such as Fixed Charges, Late Payment Fee, Tuition Fee etc. for various Billers.

| ENDPOINT                                                                                                  |
| --------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /masters/amountOptions?billerId=FE1160007XXA63**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below**

<table data-full-width="true"><thead><tr><th>Parent Property/Element</th><th>PropAerty/Element Name</th><th>Mandatory</th><th>Data Type</th><th>Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billerId</td><td>M</td><td>Alphanumeric Fixed Length – 14</td><td>NPCI identifier of the biller</td></tr></tbody></table>

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below**

| Parent Property/Element                | PropAerty/Element Name | Mandatory | Data Type        | Description                                                               |
| -------------------------------------- | ---------------------- | --------- | ---------------- | ------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | amountOptions          | M         | Boolean          | A boolean which tells if amount breakupset is present or not              |
| **amountOptionDAOS**                   | amountOptionId         | M         | UUID             | Unique ID associated with a specific Amount Breakup Set                   |
|                                        | amountBreakupSets      | M         | Array of strings | Lists all combinations of Amount Breakup Options configured by the Biller |
| **generalResp**                        | statusCode             | M         | Numeric          | 200- SUCCESS Other than 200-Failure                                       |
|                                        | status                 | M         | String           | It is either “Success” or failure                                         |
|                                        | message                | M         | String           | Contains the reason message for failure / success                         |

*<mark style="color:blue;">**Json Formatted Response Example**</mark>*

{% code overflow="wrap" fullWidth="true" %}

```json
{
"amountOptions": true, "amountOptionDAOS": [
{
"amountOptionId": "5b6e4ab4-6ae1-42cd-b7c4-0030daf77575", "amountBreakupSets": [
"BASE_BILL_AMOUNT"
]
}
],
"generalResp": { "statusCode": "200",
"status": "success",
"message": "Amount options retrieved", "remarks": ""
}
}
```

{% endcode %}


# List Billers API

**API for listing all the Billers onboarded in BBPS**

| Endpoint                                                                                                      |
| ------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /masters/billers?category=DTH\&page=0\&pagesize=10**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description                             |
| ------------------------------------------ | --------------------- | --------- | --------- | --------------------------------------- |
| **\[ROOT]** (No parent property / element) | billerName            | M         | String    | Name of the Biller                      |
|                                            | category              | M         | String    | Category of the Biller                  |
|                                            | page                  | C         | Numeric   | Page number for API Response Pagination |
|                                            | pageSize              | C         | Numeric   | Page Size for API Response Pagination   |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below**

| Parent Property/Element                    | Property/Element Name   | Mandatory | Data Type | Description                                                                                                      |
| ------------------------------------------ | ----------------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | pageNo                  | M         | Numeric   | Name of the Biller                                                                                               |
|                                            | pageSize                | M         | Numeric   | Category of the Biller                                                                                           |
|                                            | totalElements           | M         | Numeric   | Page number for API Response Pagination                                                                          |
|                                            | totalPages              | M         | Numeric   | Page Size for API Response Pagination                                                                            |
| **billerResp** (will be a list of objects) | billerId                | M         | String    | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                       |
|                                            | billerName              | M         | String    | Name of the Biller                                                                                               |
|                                            | billerType              | M         | String    | Lists the Payment Modes applicable to the Biller (FETCH\_PAY, VALIDATE\_PAY, QUICKPAY)                           |
|                                            | billerCategory          | M         | String    | Category of the biller                                                                                           |
|                                            | billerCoverage          | M         | String    | Coverage of the biller                                                                                           |
|                                            | billerResponseType      | M         | String    |                                                                                                                  |
|                                            | billerDescription       | M         | String    | Description of the biller                                                                                        |
|                                            | planMDMRequirement      | M         | String    | Indicates if the Biller support Plan MDM functionality – possible values are MANDATORY, OPTIONAL, NOT\_SUPPORTED |
|                                            | adhocBiller             | M         | Numeric   | Flag indicating if the Biller accepts adhoc payment                                                              |
|                                            | paymentAmountExactn ess | M         | String    | possible values are : Exact, Exact and above, Exact and below                                                    |
| **generalResp**                            | statusCode              | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                                                              |
|                                            | status                  | M         | String    | It is either “Success” or failure                                                                                |
|                                            | message                 | M         | String    | Contains the reason message for failure / success                                                                |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
        {
        "billerResp": [
        {
        "billerId": "AT4160007XXA63",
        "billerName": "APB BOU", "billerType": "VALIDATE_PAY", "billerCategory": "DTH", "billerCoverage": "IND", "billerResponseType": "SINGLE", "billerDescription": null,
        "planMDMRequirement": "NOT_SUPPORTED", "adhocBiller": true, "paymentAmountExactness": "Exact"
        },
        {
        "billerId": "AT4180007UPA63",
        "billerName": "APB BOU", "billerType": "FETCH_PAY", "billerCategory": "DTH", "billerCoverage": "IND", "billerResponseType": "SINGLE", "billerDescription": null,
        "planMDMRequirement": "NOT_SUPPORTED",
        "adhocBiller": false, "paymentAmountExactness": "Exact and above"
        },
        {
        "billerId": "AT4170007XXA63",
        "billerName": "APB BOU", "billerType": "FETCH_PAY", "billerCategory": "DTH", "billerCoverage": "IND", "billerResponseType": "SINGLE", "billerDescription": null,
        "planMDMRequirement": "NOT_SUPPORTED", "adhocBiller": true, "paymentAmountExactness": "Exact"
        }
        ],
        "pageNo": 0,
        "pageSize": 10,
        "totalElements": 3,
        "totalPages": 1, "generalResp": {
        "statusCode": "200",
        "status": "success",
        "message": "Billers retrieved successfully", "remarks": ""
        }
        }
```


# Billers By ID API

**API for listing all the Billers onboarded in BBPS**

| Endpoint                                                                                                |
| ------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /masters/billersById?billerId=KIFS00000NATST**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description             |
| -------------------------------------- | --------------------- | --------- | --------- | ----------------------- |
| \[ROOT] (No parent property / element) | billerId              | M         | String    | Biller ID of the biller |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                             | Property/Element Name           | Mandatory | Data Type        | Description                                                                                                   |
| --------------------------------------------------- | ------------------------------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
| **billerDAO (will be an object)**                   | billerId                        | M         | String           | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                    |
|                                                     | billerName                      | M         | String           | Name of the Biller                                                                                            |
|                                                     | billerAliasName                 | M         | String           | Alias Name of the Biller                                                                                      |
|                                                     | billerCategoryName              | M         | String           | Category Name of the Biller                                                                                   |
|                                                     | billerMode                      | M         | String           | Biller Mode of the Biller - Possible values are ONLINE,OFFLINEA,OFFLINEB                                      |
|                                                     | billerAcceptsAdhoc              | M         | Boolean          | Whether the biller accepts any amount or not                                                                  |
|                                                     | parentBiller                    | M         | Boolean          | Parent Biller Flag                                                                                            |
|                                                     | parentBillerId                  | M         | String           | Parent Biller ID                                                                                              |
|                                                     | billerOwnerShp                  | M         | String           | Biller Ownership - Possible values are PSU and Private                                                        |
|                                                     | billerCoverage                  | M         | String           | Coverage in IND-STATE-DISTRICT format                                                                         |
|                                                     | fetchRequirement                | M         | String           | Fetch Requirement - Possible values are MANDATORY, OPTIONAL and NOT\_SUPPORTED                                |
|                                                     | paymentAmountExactn ess         | M         | String           | Payment Amount Exactness - Possible values are Exact, Exact and above, Exact and below                        |
|                                                     | supportBillValidation           | M         | String           | Validation Requirement - Possible values are MANDATORY, OPTIONAL and NOT\_SUPPORTED                           |
|                                                     | billerEffctvFrom                | M         | String           | Biller effective from date                                                                                    |
|                                                     | billerEffctvTo                  | M         | String           | Biller effective to date                                                                                      |
|                                                     | billerTempDeactivation Start    | M         | String           | Biller Temporary Deactivation Start Date                                                                      |
|                                                     | billerTempDeactivation End      | M         | String           | Biller Temporary Deactivation End Date                                                                        |
|                                                     | billerDescription               | M         | String           | Biller description to display to user                                                                         |
|                                                     | billerResponseType              | M         | String           | Possible values - SINGLE, SELECTIVE (For Plan MDM)                                                            |
|                                                     | planMDMRequirement              | M         | String           | Indicates whether the biller supports Plan MDM or not. Possible values are MANDATORY,OPTIONAL,NOT\_SUPPORTE D |
|                                                     | interchangeFeeConves            | O         | Array            | Array of interchange fee convenience fees details                                                             |
|                                                     | interchangeFees                 | O         | Integer          | Interchange fees null if not present                                                                          |
|                                                     | status                          | M         | String           | Biller status, can be “ACTIVE" or “INACTIVE”.                                                                 |
|                                                     | supportDeemed                   | M         | String           | Support deemed, can be “Yes” or “No”                                                                          |
|                                                     | supportPendingStatus            | M         | String           | Support pending status, can be “Yes” or “No”                                                                  |
|                                                     | billerTimeOut                   | M         | String           | Biller time out value in numeric string. Eg: “10”                                                             |
|                                                     | routeUrl                        | O         | String           | Route url                                                                                                     |
| **billerPlanResponseP arams**                       | billerPlanResponseId            | M         | String           | Unique Id                                                                                                     |
|                                                     | params (Array of object)        | M         | Array of object  | Biller plan response param details                                                                            |
|                                                     | amountOptions (Array of object) | M         | Array of object  | Biller amount options                                                                                         |
| **params (Array of object)**                        | paramConfigId                   | M         | String           | Unique Id                                                                                                     |
|                                                     | paramName                       | M         | String           | Parameter name                                                                                                |
|                                                     | dataTypeDAO                     | M         | String           | Parameter data type                                                                                           |
|                                                     | optional                        | M         | Boolean          | Parameter optional                                                                                            |
|                                                     | visibility                      | M         | Boolean          | Parameter visibility                                                                                          |
| **amountOptions (Array of object**                  | amountOptionId                  | M         | Array            | Unique Id                                                                                                     |
|                                                     | amountBreakupSets               | M         | Array            | Array of amount option names                                                                                  |
| **billerPaymentModes (Array of object)**            | paymentMode                     | M         | String           | Payment Mode supported by the Biller                                                                          |
|                                                     | maxLimit                        | O         | Integer          | Maximum Limit supported by the Payment Mode. If the tag is not there, maximum limit need not be checked.      |
|                                                     | minLimit                        | O         | Integer          | Minimum Limit supported by the Payment Mode. If the tag is not there, maximum limit need not be checked.      |
| **billerPaymentChann els (Array of object)**        | paymentChannel                  | M         | String           | Payment Channel supported by the Biller                                                                       |
|                                                     | maxLimit                        | O         | Integer          | Maximum Limit supported by the Payment Channel. If the tag is not there, maximum limit need not be checked.   |
|                                                     | minLimit                        | O         | Integer          | Minimum Limit supported by the Payment Channel. If the tag is not there, maximum limit need not be checked.   |
| **billerCustomerPara ms**                           | paramName                       | M         | String           | <p>Name of the </p><p>customer parameter</p>                                                                  |
| **(Object)**                                        | dataTypeDAO                     | M         | String           | Datatype of the customer parameter - Possible values are NUMERIC and ALPHANUMERIC                             |
|                                                     | optional                        | M         | Boolean          | Flag indicating whether the parameter is optional or not                                                      |
|                                                     | minLength                       | O         | Integer          | Minimum length of the customer parameter value                                                                |
|                                                     | maxLength                       | O         | Integer          | Maximum length of the customer parameter value                                                                |
|                                                     | visibility                      | M         | Boolean          | Flag indicating whether the customer parameter should be visible to / entered manually by customers or not.   |
|                                                     | values                          | O         | String           | Possible default values for the customer parameter                                                            |
| **customerParamGrou ps (Object)**                   | groups                          | O         | Array            | Customer parameter groups information                                                                         |
| **groups (Array of object)**                        | name                            | M         | String           | Name of the group                                                                                             |
|                                                     | input                           | M         | String           | Input value of group                                                                                          |
|                                                     | params                          | M         | List             | List of string containing the combination                                                                     |
|                                                     | groups                          | M         | Object           | Inner Group with same model as the outer Group                                                                |
| **billerResponsePara ms**                           | billerResponseId                | M         | String           | Unique ID assigned                                                                                            |
|                                                     | params                          | O         | Array            | Array of parameter name can also be empty                                                                     |
|                                                     | amountOptions                   | M         | Array of Objects | Amount option details                                                                                         |
| **amountOptions (Array of objects)**                | amountOptionId                  | M         | String           | Unique ID assigned                                                                                            |
|                                                     | amountBreakupSets               | M         | Array of Objects | Consists of names of amount breakup set names                                                                 |
| **billerAdditionalInfos (Array of Object)**         | paramName                       | M         | String           | Name of the additional info                                                                                   |
|                                                     | dataTypeDAO                     | M         | String           | Datatype of the additional info - Possible values are NUMERIC and ALPHANUMERIC                                |
|                                                     | optional                        | M         | Boolean          | Flag indicating whether the parameter is optional or not                                                      |
| **billerAdditionalInfoP ayments (Array of Object)** | paramName                       | M         | String           | Name of the additional info                                                                                   |
|                                                     | dataTypeDAO                     | M         | String           | Datatype of the additional info - Possible values are NUMERIC and ALPHANUMERIC                                |
|                                                     | optional                        | M         | Boolean          | Flag indicating whether the parameter is optional or not                                                      |
| **generalResp**                                     | statusCode                      | M         | Numeric          | 200- SUCCESS Other than 200-Failure                                                                           |
|                                                     | status                          | M         | String           | It is either “success” or failure                                                                             |
|                                                     | message                         | M         | String           | Contains the reason message for failure / success                                                             |
|                                                     | remarks                         | O         | String           | Suggestion for improvement                                                                                    |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
    
    {
    "billerDAO": {
    "billerId": "KIFS00000NATST",
    "billerName": "KIFS Housing Finance Ltd", 
    "billerAliasName": "KIFS", 
    "billerCategoryName": "Loan Repayment", 
    "billerMode": "OFFLINEA", 
    "billerAcceptsAdhoc": true,
    "parentBiller": false, 
    "parentBillerId": "", 
    "billerOwnerShp": "Private", 
    "billerCoverage": "IND",
    "fetchRequirement": "MANDATORY", 
    "paymentAmountExactness": "Exact", 
    "supportBillValidation": "NOT_SUPPORTED", 
    "billerEffctvFrom": "2022-01-14",
    "billerEffctvTo": "2027-01-14", 
    "billerTempDeactivationStart": "", 
    "billerTempDeactivationEnd": "", 
    "billerPaymentModes": [
    {
    "paymentModelLimitId": "6c0d0056-a9dc-4d39-82f0-68de6bb67d37", 
    "paymentMode": "Internet Banking",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentModelLimitId": "e5293ec8-be67-4972-9bf7-c2c6c4c2a961", 
    "paymentMode": "Debit Card",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    "paymentMode": "Bharat QR", 
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentModelLimitId": "67d00ef8-817c-4987-9136-5055cb4be599", 
    "paymentMode": "USSD",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    }
    ],
    "billerPaymentChannels": [
    {
    "paymentChannelLimitId": "36934eb4-2341-4cde-8833-78195cc92c7b", 
    "paymentChannel": "BSC",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "a692239d-847c-44d2-9f6a-22f1490a8607", 
    "paymentChannel": "INT",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "f90d3052-444e-4514-aa07-57cde994af0d", 
    "paymentChannel": "INTB",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "2ad7cd2e-d0e0-4c0a-b0a7-b10f6237532e", 
    "paymentChannel": "MOB",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "c2bf4ee9-4128-4121-8a29-d4d423d40cba", 
    "paymentChannel": "MOBB",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "77542075-b4e6-4f6a-91fa-d4e261a8b271",
    "paymentChannel": "POS", 
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "7cfd4bb8-8d78-4e0b-9388-1302356e6db1", 
    "paymentChannel": "MPOS",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "3ddcaad0-35bc-4c2f-bb40-12c421d2549a", 
    "paymentChannel": "ATM",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "08535682-6366-4148-9d0b-860d8d1017f2", 
    "paymentChannel": "BNKBRNCH",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "8ae1b88a-1aff-453e-ac20-4ca0b5e7d006", 
    "paymentChannel": "KIOSK",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    },
    {
    "paymentChannelLimitId": "8e93c7de-4f08-4551-b61b-cd5bc85216d7", 
    "paymentChannel": "AGT",
    "maxLimit": 100000000,
    "minLimit": 1, 
    "supportPendingStatus": "Yes"
    }
    ],
    "billerCustomerParams": [
    {
    "paramConfigId": "",
    "paramName": "APPLICATION NUMBER", 
    "dataTypeDAO": "NUMERIC",
    "dataTypeModel": "NUMERIC", 
    "optional": false,
    "minLength": 5,
    "maxLength": 10, 
    "visibility": true
    }
    ],
    "customerParamGroups": { "groups": []
    },
    "billerResponseParams": {
    "billerResponseId": "338499e5-4c19-404b-bc80-d720bc0147be", 
    "params": [],
    "amountOptions": [
    {
    "amountOptionId": "c5a8266a-7b4c-4464-bac1-1a797cf8af41", 
    "amountBreakupSets": [
    "BASE_BILL_AMOUNT"
    ]
    }
    ]
    },
    "billerAdditionalInfos": [
    {
    "paramConfigId": "6f7bc0a5-8bf8-4092-8c90-a993f64035e1", 
    "paramName": "Loan Account Number",
    "dataTypeDAO": "ALPHANUMERIC",
    "dataTypeModel": "ALPHANUMERIC", 
    "optional": true,
    "visibility": false
    }
    ],
    "billerAdditionalInfoPayments": [], 
    "interchangeFeeConves": [
    {
    "interChangeFeeConfId": "133b0675-b527-4c69-b0aa-50aaed39213a", 
    "mti": "PAYMENT",
    "paymentMode": "", 
    "paymentChannel": "AGT", 
    "responseCode": "000", 
    "fees": [
    "CCF1", "PBF"
    ],
    "defaultFee": false, 
    "effctvFrom": "20210226", 
    "effctvTo": ""
    },
    {
    "interChangeFeeConfId": "630188cd-382d-49cf-b6af-6571816dd90e", 
    "mti": "PAYMENT",
    "paymentMode": "", 
    "paymentChannel": "BNKBRNCH", 
    "responseCode": "000",
    "fees": [
    "CCF1",
    "PBF"
    ],
    "defaultFee": false, 
    "effctvFrom": "20210226", 
    "effctvTo": ""
    },
    {
    "interChangeFeeConfId": "b63e2838-7a66-46e8-9521-4f2550f03368", 
    "mti": "PAYMENT",
    "paymentMode": "", 
    "paymentChannel": "BSC", "responseCode": "000", "fees": [
    "CCF1", "PBF"
    ],
    "defaultFee": false, "effctvFrom": "20210226", "effctvTo": ""
    },
    {
    "interChangeFeeConfId": "704eaf4a-addd-488e-bb28-19427d5ad57b", "mti": "PAYMENT",
    "paymentMode": "", "paymentChannel": "", "responseCode": "000", "fees": [
    "CCF1", "EBF"
    ],
    "defaultFee": true, "effctvFrom": "20210226", "effctvTo": ""
    }
    ],
    "interchangeFees": [
    {
    "interchangeFeeId": "597b52ba-024f-4075-b772-bde05c37dae9", "feeCode": "CCF1",
    "feeDesc": "Customer_Convenience_Fee", "feeDirection": "C_2_B", "interchangeFeeDetails": [
    {
    "interchangeFeeDetId": "dae2a937-18e5-439e-8af1-30128bc40c31", "tranAmtRangeMax": 9999999999,
    "tranAmtRangeMin": 1,
    "percentFee": 0,
    "flatFee": 0,
    "effctvFrom": "2019-11-28"
    }
    ]
    },
    {
    "interchangeFeeId": "00a941f6-145f-4bb8-adc2-d3727c3599dd", 
    "feeCode": "PBF",
    "feeDesc": "Physical_Biller_Fee", 
    "feeDirection": "B_2_C", 
    "interchangeFeeDetails": [
    {
    "interchangeFeeDetId": "df4cc8c7-f0e5-4b3f-8c99-5e3056b60547", 
    "tranAmtRangeMax": 166700,
    "tranAmtRangeMin": 1,
    "percentFee": 0,
    "flatFee": 500,
    "effctvFrom": "2020-07-01"
    },
    {
    "interchangeFeeDetId": "89924926-3de1-4940-a5c2-676270d48585", 
    "tranAmtRangeMax": 9999999999,
    "tranAmtRangeMin": 166701,
    "percentFee": 0.3,
    "flatFee": 0,
    "effctvFrom": "2020-07-01"
    }
    ]
    },
    {
    "interchangeFeeId": "79ca83bf-b521-4f31-b201-8c856a01a5f0", 
    "feeCode": "EBF",
    "feeDesc": "Electronic_Biller_Fee", 
    "feeDirection": "B_2_C", 
    "interchangeFeeDetails": [
    {
    "interchangeFeeDetId": "b91f831e-007f-417e-a074-71ff1a3caddd", 
    "tranAmtRangeMax": 9999999999,
    "tranAmtRangeMin": 1,
    "percentFee": 0,
    "flatFee": 500,
    "effctvFrom": "2019-11-28"
    }
    ]
    }
    ],
    "status": "ACTIVE", 
    "billerDescription": "", 
    "supportDeemed": "Yes", 
    "supportPendingStatus": "Yes", 
    "billerTimeOut": "30", 
    "routeUrl": "", 
    "billerResponseType": "SINGLE", 
    "billerPlanResponseParams": {
    "billerPlanResponseId": "830fb128-c798-46df-8ab8-8be14730d81b",
    "params": [], 
    "amountOptions": []
    },
    "planMDMRequirement": "NOT_SUPPORTED", 
    "planAdditionalInfos": []
    },
    "generalResp": { "statusCode": "200",
    "status": "success",
    "message": "Biller details retrieved successfully", 
    "remarks": ""
    }
    }
    
    
    
```


# Categories Master Data API

**API for listing all Biller Categories in the BBPS application.**

| Endpoint                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET https\://\<master\_server\_url>/agent/cou-master/masters/categories-master**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description              |
| ------------------------------------------ | --------------------- | --------- | --------- | ------------------------ |
| **\[ROOT]** (No parent property / element) | category              | C         | String    | Name of the category     |
| **\[ROOT]** (No parent property / element) | tenantId              | M         | String    | Tenant ID of the OU/Bank |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type             | Description                                   |
| ------------------------------------------ | --------------------- | --------- | --------------------- | --------------------------------------------- |
| **\[ROOT]** (No parent property / element) | categoryRespList      | M         | Array of categoryresp | List of category masters                      |
| **categoryRespListA**                      | categoryId            | M         | UUID                  | Unique ID associated with a specific category |
|                                            | categoryName          | M         | String                |                                               |
|                                            | categoryIcon          | M         | String                |                                               |
|                                            | categoryDomain        | M         | String                |                                               |
|                                            | buttonName            | M         | String                |                                               |
|                                            | textArea              | M         | String                |                                               |
|                                            | faqDetailsList        | M         | Array of FAQ          |                                               |
| **faqDetailsList**                         | name                  | C         | String                |                                               |
|                                            | value                 | C         | String                |                                               |
| **generalResp**                            | statusCode            | M         | Numeric               |                                               |
|                                            | status                | M         | String                |                                               |
|                                            | message               | M         | String                |                                               |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
    {
    "generalResp": { "statusCode": "200",
    "status": "success",
    "message": "Categories retrieved successfully", 
    "remarks": ""
    },
    "categoryRespList": [
    {
    "categoryId": "a00957d8-67e5-456a-ae55-fa3ef420fc3b", 
    "categoryName": "Insurance",
    "categoryIcon": "data:image/png;base64,", 
    "categoryDomain": "Insurance", 
    "buttonName": "Insurance",
    "textArea": "dGVzdA==", 
    "faqDetailsList": [
    {
    "name": "test",
    "value": "test"
    }
    ]
    },
    {
    "categoryId": "725c74e2-c68e-4269-9bb3-4eff5ac861a2", 
    "categoryName": "Broadband Postpaid",
    "categoryIcon": "data:image/png;base64,", 
    "categoryDomain": "Utilities", 
    "buttonName": "Broadband Postpaid", 
    "textArea": "dGVzdA==",
    "faqDetailsList": [
    {
    "name": "test",
    "value": "test"
    }
    ]
    },
    {
    "categoryId": "e03adf60-7c1e-47a9-b4c5-31ded125af6f", 
    "categoryName": "Landline Postpaid",
    "categoryIcon": "data:image/png;base64,", 
    "categoryDomain": "Utilities", 
    "buttonName": "Landline Postpaid", 
    "textArea": "dGVzdA==",
    "faqDetailsList": [
    {
    "name": "test",
    "value": "test"
    }
    ]
    }
    ]
    }
```


# Contact Master Data API

**API for getting helpline numbers**

| Endpoint                                                                                            |
| --------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /agent/cou-master/masters/contact-master**</mark> |

**Request Parameters**

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description              |
| -------------------------------------- | --------------------- | --------- | --------- | ------------------------ |
| \[ROOT] (No parent property / element) | category              | C         | String    | Name of the category     |
| \[ROOT] (No parent property / element) | tenantId              | M         | String    | Tenant ID of the OU/Bank |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                                  |
| -------------------------------------- | --------------------- | --------- | --------- | ------------------------------------------------------------ |
| \[ROOT] (No parent property / element) | contactMasterList     | M         | List      | A boolean which tells if amount breakupset is present or not |
| contactMasterList                      | mobNo                 | M         | String    | It will be the contact details                               |
| generalResp                            | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                          |
|                                        | status                | M         | String    | It is either “Success” or failure                            |
|                                        | message               | M         | String    | Contains the reason message for failure / success            |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
 {
 "generalResp": { "statusCode": "200",
 "status": "success",
 "message": "contact master retrieved successfully",
  "remarks": ""
 },
 "contactMasterList": [
 {
 "mobNo": "8891604640"
 }
 ]
 }
```


# Customer Parameters API

**API for listing Customer Parameter details of a specific Biller, by using the Biller ID.**

| Endpoint                                                                                            |
| --------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /agent/cou-master/masters/contact-master**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description              |
| ------------------------------------------ | --------------------- | --------- | --------- | ------------------------ |
| **\[ROOT]** (No parent property / element) | category              | C         | String    | Name of the category     |
| \[ROOT] (No parent property / element)     | tenantId              | M         | String    | Tenant ID of the OU/Bank |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description                                                  |
| ------------------------------------------ | --------------------- | --------- | --------- | ------------------------------------------------------------ |
| **\[ROOT]** (No parent property / element) | contactMasterList     | M         | List      | A boolean which tells if amount breakupset is present or not |
| contactMasterList                          | mobNo                 | M         | String    | It will be the contact details                               |
| **generalResp**                            | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                          |
|                                            | status                | M         | String    | It is either “Success” or failure                            |
|                                            | message               | M         | String    | Contains the reason message for failure / success            |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json

    {
    "generalResp": { "statusCode": "200",
    "status": "success",
    "message": "contact master retrieved successfully", 
    "remarks": ""
    },
    "contactMasterList": [
    {
    "mobNo": "8891604640"
    }
    ]
    }
```


# Customer Parameters API

**API for listing Customer Parameter details of a specific Biller, by using the Biller ID.**

| Endpoint                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /agent/cou-master/masters/customerParam?billerId=BSNL00000NATHL**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type    | Description       |
| ------------------------------------------ | --------------------- | --------- | ------------ | ----------------- |
| **\[ROOT]** (No parent property / element) | billerId              | C         | Alphanumeric | Fixed Length – 14 |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

<table data-full-width="true"><thead><tr><th width="147">Parent Property/Element</th><th width="179">Property/Element Name</th><th width="121">Mandatory</th><th width="126">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>customParamResp</td><td>M</td><td>List</td><td>List of customer params</td></tr><tr><td>customParamResp</td><td>customParamName</td><td>M</td><td>UUID</td><td>Unique ID associated with a specific Amount Breakup Set</td></tr><tr><td></td><td>dataType</td><td>M</td><td>String</td><td>Lists all combinations of Amount Breakup Options configured by the Biller</td></tr><tr><td></td><td>optional</td><td>M</td><td>Boolean</td><td></td></tr><tr><td></td><td>minLength</td><td>M</td><td>Numeric</td><td></td></tr><tr><td></td><td>maxLength</td><td>M</td><td>Numeric</td><td></td></tr><tr><td></td><td>regex</td><td>M</td><td>Alphanumeric</td><td></td></tr><tr><td>generalResp</td><td>visibility</td><td>M</td><td>Boolean</td><td></td></tr><tr><td></td><td>statusCode</td><td>M</td><td>Numeric</td><td>200- SUCCESS Other than 200-Failure</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>It is either “Success” or failure</td></tr><tr><td></td><td>message</td><td>M</td><td>String</td><td>Contains the reason message for failure / success</td></tr></tbody></table>

**Json Formatted Response Example**

```json
    {
    "generalResp": { "statusCode": "200",
    "status": "success",
    "message": "Customer param retrieved successfully", 
    "remarks": ""
    },
    "customParamResp": [
    {
    "customParamName": "Mobile Number", 
    "dataType": "NUMERIC",
    "optional": false, 
    "minLength": 10,
    "maxLength": 10,
    "regex": "^[6-9]{1}[0-9]{9}$",
    "visibility": true
    },
    {
    "customParamName": "Circle", 
    "dataType": "ALPHANUMERIC",
    "optional": false, 
    "minLength": 1,
    "maxLength": 50, 
    "regex": null, 
    "visibility": true
    },
    {
    "customParamName": "Id", 
    "dataType": "ALPHANUMERIC",
    "optional": false, 
    "minLength": 1,
    "maxLength": 50, 
    "regex": null, 
    "visibility": false
    }
    ]
    }
```


# Customer Parameters Groups API

**API for listing Customer Parameter groups of a specific Biller, by using the Biller ID.It returns combination of customer params that customer can use**

| Endpoint                                                                                                       |
| -------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /masters/customerParamGroup?billerId=DKAFEE000KER06**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type    | Description       |
| ------------------------------------------ | --------------------- | --------- | ------------ | ----------------- |
| **\[ROOT]** (No parent property / element) | billerId              | M         | Alphanumeric | Fixed Length – 14 |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name   | Mandatory | Data Type | Description                                       |
| -------------------------------------- | ----------------------- | --------- | --------- | ------------------------------------------------- |
| \[ROOT] (No parent property / element) | customerParamGroupR esp |           |           |                                                   |
| **groups**                             | name                    | M         | String    | Name of the group                                 |
|                                        | input                   | M         | String    | Input value of group                              |
|                                        | params                  | M         | List      | List of string containing the combination         |
|                                        | groups                  | M         | Object    | Inner Group with same model as the outer Group    |
| **generalResp**                        | statusCode              | M         | Numeric   | 200- SUCCESS Other than 200-Failure               |
|                                        | status                  | M         | String    | It is either “Success” or failure                 |
|                                        | message                 | M         | String    | Contains the reason message for failure / success |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

<pre class="language-json"><code class="lang-json"><strong>    {
</strong>    "generalResp": { "statusCode": "200",
    "status": "success",
    "message": "Customer param group retrieved successfully", "remarks": ""
    },
    "customerParamGroupResp": { "groups": [
    {
    "groupId": "e7a1daac-4d64-4dc0-9f4b-c07c631d5f67", "params": [
    "Admission No/Application No/GR No"
    ],
    "groups": [
    {
    "groupId": "4cde9c57-3f0c-4293-84a3-b8f3c834f23d", "params": [
    "Date Of Birth (DD-MM-YYYY)", "Mobile No"
    ],
    "groups": [],
    "name": "Group1",
    "input": "2"
    }
    ],
    "name": "Group1.1",
    "input": "1"
    }
    ]
    }
    }
</code></pre>


# Disposition API

<mark style="color:blue;">**API for listing Complaint Disposition reasons for raising complaints for transactions.**</mark>

| Endpoint                                                                        |
| ------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /masters/disposition**</mark> |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description                                                               |
| ------------------------------------------ | --------------------- | --------- | --------- | ------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | dispositionsList      | M         | List      | List of dispositions                                                      |
| **dispositionsList**                       | dispositionId         | M         | UUID      | Unique ID associated with a specific Amount Breakup Set                   |
|                                            | dispositionDescr      | M         | List      | Lists all combinations of Amount Breakup Options configured by the Biller |
| generalResp                                | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                       |
|                                            | status                | M         | String    | It is either “Success” or failure                                         |
|                                            | message               | M         | String    | Contains the reason message for failure / success                         |
|                                            | remarks               | C         | String    |                                                                           |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
        {
        "dispositionsList": [
        {
        "dispositionId": "90fd3ed3-620d-42c5-bb54-35ff4644d61b", 
        "dispositionDescr": "Transaction Successful, account not updated"
        },
        {
        "dispositionId": "5f93f8d0-ce90-490f-a743-a8e813256fed",
        "dispositionDescr": "Amount deducted, biller account credited but transaction ID not received"
        },
        {
        "dispositionId": "74c0ef51-09e4-4f83-a440-aa0329d49287",
        "dispositionDescr": "Amount deducted, biller account not credited & transaction ID not received"
        },
        {
        "dispositionId": "3637a1a4-5fb8-48c9-915d-ba2fcb41d0a6", 
        "dispositionDescr": "Amount deducted multiple times"
        },
        {
        "dispositionId": "e08b5a71-4df1-4688-ad59-347768911d22", 
        "dispositionDescr": "Double payment updated"
        },
        {
        "dispositionId": "4c5b2748-6d8b-464d-8fec-8225aca3cf82", 
        "dispositionDescr": "Erroneously paid in wrong account"
        }
        ],
        "generalResp": 
        { 
        "statusCode": "200",
        "status": "success",
        "message": "dispositions retrieved successfully", 
        "remarks": ""
        }
        }
```


# Initiating Channel API

#### **API for listing Initiating Channel details in the BBPS application.**

| Endpoint                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint Request:&#x20;**<mark style="color:blue;">**GET https\://\<master\_server\_url>/masters/initiatingChannel**</mark> |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description                                                               |
| ------------------------------------------ | --------------------- | --------- | --------- | ------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | channelsList          | M         | List      | A boolean which tells if amount breakupset is present or not              |
| **channelsList**                           | channelId             | M         | UUID      | Machine-generated Unique ID assigned to Initiating Channels internally    |
|                                            | channelName           | M         | String    | Lists all combinations of Amount Breakup Options configured by the Biller |
| **generalResp**                            | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                       |
|                                            | status                | M         | String    | It is either “Success” or failure                                         |
|                                            | message               | M         | String    | Contains the reason message for failure / success                         |
|                                            | remarks               | C         | String    | Empty string                                                              |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
    {
    "channelsList": 
    [
    {
    "channelId": "5de064f0-dd9b-4a0b-8ff7-54f72b5a4ea9", 
    "channelName": "Internet"
    },
    {
    "channelId": "3652cbd8-83c6-4e5d-a651-5c46a570bc82", 
    "channelName": "Internet_Banking"
    },
    {
    "channelId": "3027b91c-36da-4b93-8bad-165fc4ca0491", 
    "channelName": "Cable TV"
    },
    {
    "channelId": "2121b315-c78e-45a6-81e8-0ca345981784",
    "channelName": "Mobile"
    },
    {
    "channelId": "b8c0030f-6011-4617-b5e8-1bd3e0aecb0e", 
    "channelName": "POS"
    },
    {
    "channelId": "d07b7b49-5bfc-48dc-a6b1-4c382dcb8b07", 
    "channelName": "MPOS"
    },
    {
    "channelId": "66bcb3db-1cf0-4f24-ac78-ee920c5f65ee", 
    "channelName": "ATM"
    }
    ],
    "generalResp": 
    { 
    "statusCode": "200",
    "status": "success",
    "message": "channels retrieved successfully", 
    "remarks": ""
    }
    }
```


# BBPS Agent API

<mark style="color:blue;">**Bill Fetch API**</mark>

**API for fetching a Customer Bill, based on Biller Category, Customer Parameters etc.**

| Endpoint                                                                        |
| ------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**POST /couapp/bills/fetch**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name  | Mandatory | Data Type     | Description                                                          |
| ------------------------------------------ | ---------------------- | --------- | ------------- | -------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | tenantId               | M         | Alphanumeric  | Fixed Length – 4                                                     |
|                                            | billerId               | M         | Alphanumeric  | Unique ID assigned to the Biller by NPCI Eg: BSNL00000NATHL          |
|                                            | billerName             | M         | String        | Name of the biller                                                   |
|                                            | billerCategory         | M         | String        | Category of biler                                                    |
|                                            | clientReqId            | C         | String        | A unique id which the client has to provide                          |
|                                            | macAdress              | C         | Alphanumeric  | MAC Address of the Agent Server                                      |
|                                            | customerMobNo          | M         | String        | Mobile of the Customer, on whose behalf the Agent is paying the Bill |
|                                            | paymentChannel         | M         | String        | Payment Channel of Agent                                             |
|                                            | deviceBlockTags        | M         | Array of tags | Device block tags of Agent                                           |
|                                            | customerParamsReques t | M         | Object        | Unique parameters used for identifying a Customer Bill               |
| **customerParamsReq uest**                 | tags                   | M         | List          | List of customer params                                              |
| **tags**                                   | name                   | M         | String        | Name of customer param                                               |
| **tags**                                   | value                  | M         | String        | Value of customer param                                              |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description                                             |
| ------------------------------------------ | --------------------- | --------- | --------- | ------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | billId                | C         | UUID      | Machine-generated Unique ID for a Bill, used internally |
|                                            | refId                 | C         | String    | Will be null                                            |
|                                            | billerId              | C         | String    | Will be null                                            |
|                                            | status                | C         | String    | Will be null                                            |
|                                            | actionType            | C         | String    | Will be null                                            |
|                                            | billerResponse        | C         | String    | Will be null                                            |
|                                            | additionalInfo        | C         | String    | Will be null                                            |
|                                            | customerParams        | C         | String    | Will be null                                            |
|                                            | creationDate          | C         | String    | Will be null                                            |
|                                            | modifiedDate          | C         | String    | Will be null                                            |
|                                            | createdEpochDate      | C         | String    | Will be null                                            |
|                                            | modifiedEpochDate     | C         | String    | Will be null                                            |
| generalResp                                | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                     |
|                                            | status                | M         | String    | It is either “Success” or failure                       |
|                                            | message               | M         | String    | Contains the reason message for failure / success       |
|                                            | remarks               | C         | String    |                                                         |

<mark style="color:blue;">**Json Formatted Request Example**</mark>

```json
    "tenantId": "FE41",
    "billerId": "DKAFEE000PUN01"
    "customerParamsRequest":
     { "tags": 
     [
    {
    "name": "Admission No/Application No/GR No", 
    "value": "LF3130"
    },
    {
    "name": "Date Of Birth (DD-MM-YYYY)"
    },
    {
    "name": "Mobile No"
    }
    ]
    },
    "billerName": "Little Flower Convent School", 
    "billerCategory": "Education Fees", 
    "macAdress": null,
    "customerMobNo": "8281970522”, 
    "paymentChannel": "Agent", 
    "deviceBlockTags": 
    [
    {
    "name": "MOBILE", 
    "value": "9591810218"
    },
    {
    "name": "GEOCODE",
    "value": "28.6139,78.5555"
    },
    {
    "name": "POSTAL_CODE",
    "value": "600001"
    },
    {
    "name": "TERMINAL_ID",
    "value": "333001"
    }
    ]
    }
```

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
    {
    "genericResponse": 
    { "statusCode": "200",
    "status": "success",
    "message": "Bill Fetch Initiated", 
    "remarks": ""
    },
    "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684", 
    "refId": null,
    "billerId": null,
    "status": null, "actionType": null,
    "userId": null, "billerResponse": null, 
    "additionalInfo": null, 
    "customerParams": null, 
    "creationDate": null, 
    "modifiedDate": null, 
    "createdEpochDate": 0,
    "modifiedEpochDate": 0
    }
```

<mark style="color:blue;">**Initiating Channel Vs Device Block Parameters**</mark>

| Initiating Channel                | Device Block Tags                           |
| --------------------------------- | ------------------------------------------- |
| Bank Branch                       | IFSC, MOBILE, GEOCODE, POSTAL\_CODE         |
| Mobile (Pre-login)                | IP, IMEI, OS, APP                           |
| Mobile Banking(Post-login)        | IP, IMEI, OS, APP                           |
| Internet (Pre-login)              | IP, MAC                                     |
| Internet Banking (Post-login) ATM | <p>IP, MAC</p><p>TERMINAL\_ID</p>           |
| Kiosk                             | TERMINAL\_ID                                |
| Agent                             | TERMINAL\_ID, MOBILE, GEOCODE, POSTAL\_CODE |
| Business Correspondent            | TERMINAL\_ID, MOBILE, GEOCODE, POSTAL\_CODE |


# Bill Fetch by bill id

<mark style="color:blue;">**API for fetching a Customer Bill, based on Bill id**</mark>

| Endpoint                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /couapp/bills/fetch/byId?billId=1ced7566-1add-4e01-9ed6-04cd67ac9684**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description                                                                                                                  |
| ------------------------------------------ | --------------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | billId                | M         | UUID      | Bill id is unique id which is generated while initiating the bill fetch request, it can be get from the bill fetch response. |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type    | Description                                                                                                                                    |
| ------------------------------------------ | --------------------- | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | billId                | M         | UUID         | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                            | refId                 | M         | Alphanumeric | Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages |
|                                            | billerId              | M         | String       | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                                                     |
|                                            | status                | M         | String       | Status of the Operation                                                                                                                        |
|                                            | actionType            | C         | String       | Type of Bill Payment. Possible Values: BILL\_FETCH QUICKPAY BILL\_VALIDATE                                                                     |
|                                            | userId                | M         | Alphanumeric | Agent id Fixed length - 20                                                                                                                     |
|                                            | creationDate          | M         | String       | ISO 8601 Timestamp for the Bill Creation date                                                                                                  |
|                                            | modifiedDate          | M         | String       | ISO 8601 Timestamp for the Bill Modification date                                                                                              |
|                                            | createdEpochDate      | M         | Numeric      | UNIX Epoch Timestamp for the Bill Creation date                                                                                                |
| **billerResponse**                         | modifiedEpochDate     | M         | Numeric      | UNIX Epoch Timestamp for the Bill Modification date                                                                                            |
|                                            | billId                | MM        | String       | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                            | amount                | M         | String       | Actual bill amount inclusive of all charges                                                                                                    |
|                                            | billDate              | M         | String       | This field denotes generation date of the bill                                                                                                 |
|                                            | billNumber            | M         | String       | This field denotes the bill number of the bill fetch / payment message requested                                                               |
|                                            | billPeriod            | M         | String       | The bill period of the bill fetch / payment requested                                                                                          |
|                                            | custConvFee           | M         | String       | Customer convenience fee (CCF1) paid by the Customer Operating Unit                                                                            |
|                                            | couCustConvFee        | M         | String       | Customer convenience fee (CCF2), paid by the Customer to Customer Operating Unit                                                               |
|                                            | dueDate               | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                            | customerName          | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                            | amountOption          | M         | Boolean      | A flag indicating if the Biller supports Amount Options                                                                                        |
|                                            | tagList               | M         | String       | Amount Breakup Options eg:{"name": "Additional Charges", "value": "500"}                                                                       |
| **additionalInfo**                         | name                  | C         | String       | Name of the Additional Info Parameter                                                                                                          |
|                                            | value                 | C         | String       | Value of the Additional Info Parameter                                                                                                         |
| **customerParams**                         | name                  | C         | String       | Name of the Customer Parameter attribute                                                                                                       |
|                                            | value                 | C         | String       | Value of the Customer Parameter attribute                                                                                                      |
| **generalResp**                            | statusCode            | M         | Numeric      | 200- SUCCESS Other than 200-Failure                                                                                                            |
|                                            | status                | M         | String       | It is either “Success” or failure                                                                                                              |
|                                            | message               | M         | String       | Contains the reason message for failure / success                                                                                              |
|                                            | remarks               | C         | String       |                                                                                                                                                |

<mark style="color:blue;">**Json Formatted Response Example (success response)**</mark>

```json
  
  {
  "genericResponse": {
   "message": "",
  "remarks": "",
  "status": "Success", 
  "statusCode": "200"
  },
  "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684", 
  "refId": "BlgcYxtJCrLU18BDm8rVDHQl0Hqf9x2XONi", 
  "billerId": "DKAFEE000PUN01",
  "status": "BILL_FETCH_SUCCESS",
  "actionType": "BILL_FETCH", 
  "userId": "FE41FE42BNK519012345",
  "billerResponse": {
  "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684", 
  "amount": "1142000",
  "billDate": "2021-12-09",    
  "billNumber": "59",
  "billPeriod": "NA",
  "custConvFee": "0",
  "couCustConvFee": "0",
  "dueDate": "2022-01-31",
  "customerName": "AGAMJOT TEST ", 
  "amountOption": false,
  "tagList": null
  },
  "additionalInfo": [
  {
  "additionalInfoId": null, 
  "name": "Student Name", 
  "value": "AGAMJOT TEST "
  },
  {
  "additionalInfoId": null, 
  "name": "Father Name", 
  "value": "VIRENDER SINGH"
  },
  {
  "additionalInfoId": null, 
  "name": "Class",
  "value": "STD I"
  },
  {
  "additionalInfoId": null, 
  "name": "Section",
  "value": "A"
  },
  {
  "additionalInfoId": null, 
  "name": "TUITION FEE",
  "value": "8670"
  },
  {
  "additionalInfoId": null, 
  "name": "E-CARE FEE",
  "value": "900"
  },
  {
  "additionalInfoId": null, 
  "name": "COMPUTER FEE",
  "value": "1350"
  },
  {
  "additionalInfoId": null, 
  "name": "EXAM FEE",
  "value": "500"
  }
  ],          
  "customerParams": [
  {
  "name": "Admission No/Application No/GR No", 
  "value": "LF3130",
  "type": null
  },
  {
  "name": "Date Of Birth (DD-MM-YYYY)", 
  "value": null,
  "type": null
  },
  {
  "name": "Mobile No", 
  "value": null,
  "type": null
  }
  ],
  "creationDate": "2021-12-09T08:37:40.082462", 
  "modifiedDate": "2021-12-09T08:37:42.303627",
  "createdEpochDate": 1639039060,
  "modifiedEpochDate": 1639039062
  }                                              
```

<mark style="color:blue;">**Json Formatted Response Example (failure response)**</mark>

<pre class="language-json"><code class="lang-json">    {
<strong>    "genericResponse": { 
</strong>    "message": "",
    "remarks": "Fetch Request not supported, only QuickPay permitted", 
    "status": "Failure",
    "statusCode": "500"
    },
    "billId": "XXXXXXXX-7d79-4e3c-bd2d-382276669ba9",
    "refId": "xxXXXxxxxxS4VZlr9bUF2lCCzFc4823081150", 
    "billerId": "XXXXXXXXXXXXXX",
    "status": "BILL_FETCH_FAILED",
    "actionType": "BILL_FETCH", 
    "userId": "FE41XXXXXXXXXXXXXX",
    "billerResponse": null, 
    "customerParams": [
    {}
    ],
    "creationDate": "2022-11-04T11:50:50+05:30", 
    "modifiedDate": "2022-11-04T11:50:50.460818",
    "createdEpochDate": 1667542850,
    "modifiedEpochDate": 1667542850
    }
</code></pre>


# Bill Fetch by Client Request ID API

#### <mark style="color:blue;">**API for fetching a Customer Bill, based on Client Request ID**</mark>

| Endpoint                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /couapp/bills/fetch/byClientId?clientReqId=vgRdasd248**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type    | Description       |
| ------------------------------------------ | --------------------- | --------- | ------------ | ----------------- |
| **\[ROOT]** (No parent property / element) | clientReqId           | M         | Alphanumeric | Fixed Length – 10 |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type    | Description                                                                                                                                    |
| ------------------------------------------ | --------------------- | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | billId                | M         | UUID         | Fixed LenMachine-generated Unique ID for a Bill, used internallygth – 10                                                                       |
|                                            | refId                 | M         | Alphanumeric | Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages |
|                                            | billerId              | M         | String       | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                                                     |
|                                            | status                | M         | String       | Status of the Operation                                                                                                                        |
|                                            | actionType            | C         | String       | Type of Bill Payment. Possible Values: BILL\_FETCH QUICKPAY BILL\_VALIDATE                                                                     |
|                                            | userId                | M         | Alphanumeric | Agent id Fixed length - 20                                                                                                                     |
|                                            | creationDate          | M         | String       | ISO 8601 Timestamp for the Bill Creation date                                                                                                  |
|                                            | modifiedDate          | M         | String       | ISO 8601 Timestamp for the Bill Modification date                                                                                              |
|                                            | createdEpochDate      | M         | Nuemric      | UNIX Epoch Timestamp for the Bill Creation date                                                                                                |
|                                            | modifiedEpochDate     | M         | Numeric      | UNIX Epoch Timestamp for the Bill Modification date                                                                                            |
| **billerResponse**                         | billId                | M         | String       | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                            | amount                | M         | String       | Actual bill amount inclusive of all charges                                                                                                    |
|                                            | billDate              | M         | String       | This field denotes generation date of the bill                                                                                                 |
|                                            | billNumber            | M         | String       | This field denotes the bill number of the bill fetch / payment message requested                                                               |
|                                            | billPeriod            | M         | String       | The bill period of the bill fetch / payment requested                                                                                          |
|                                            | custConvFee           | M         | String       | Customer convenience fee (CCF1) paid by the Customer Operating Unit                                                                            |
|                                            | couCustConvFee        | M         | String       | Customer convenience fee (CCF2), paid by the Customer to Customer Operating Unit                                                               |
|                                            | dueDate               | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                            | customerName          | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                            | amountOption          | M         | Boolean      | A flag indicating if the Biller supports Amount Options                                                                                        |
|                                            | tagList               | M         | String       | Amount Breakup Options eg:{"name": "Additional Charges", "value": "500"}                                                                       |
| **additionalInfo**                         | name                  | C         | String       | Name of the Additional Info Parameter                                                                                                          |
|                                            | value                 | C         | String       | Value of the Additional Info Parameter                                                                                                         |
| **customerParams**                         | name                  | C         | String       | Name of the Customer Parameter attribute                                                                                                       |
|                                            | value                 | C         | String       | Value of the Customer Parameter attribute                                                                                                      |
| **generalResp**                            | statusCode            | M         | Numeric      | 200- SUCCESS Other than 200-Failure                                                                                                            |
|                                            | status                | M         | String       | It is either “Success” or failure                                                                                                              |
|                                            | message               | M         | String       | Contains the reason message for failure / success                                                                                              |
|                                            | remarks               | C         | String       |                                                                                                                                                |

<mark style="color:blue;">**Json Formatted Response Example (success response)**</mark>

```json
{
"genericResponse": { 
"message": "",
"remarks": "",
"status": "Success", 
"statusCode": "200"
},
"billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684", 
"refId": "BlgcYxtJCrLU18BDm8rVDHQl0Hqf9x2XONi", 
"billerId": "DKAFEE000PUN01",
"status": "BILL_FETCH_SUCCESS",
"actionType": "BILL_FETCH", 
"userId": "FE41FE42BNK519012345",
"billerResponse": {
"billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684", 
"amount": "1142000",
"billDate": "2021-12-09",
"billNumber": "59",
"billPeriod": "NA",
"custConvFee": "0",
"couCustConvFee": "0",
"dueDate": "2022-01-31",
"customerName": "AGAMJOT TEST ", 
"amountOption": false,
"tagList": null
},
"additionalInfo": [
{
"additionalInfoId": null, 
"name": "Student Name", 
"value": "AGAMJOT TEST "
},
{
"additionalInfoId": null, 
"name": "Father Name", 
"value": "VIRENDER SINGH"
},
{
"additionalInfoId": null, 
"name": "Class",
"value": "STD I"
},
{
"additionalInfoId": null,
"name": "Section",
"value": "A"
},
{
"additionalInfoId": null, 
"name": "TUITION FEE",
"value": "8670"
},
{
"additionalInfoId": null, 
"name": "E-CARE FEE",
"value": "900"
},
{
"additionalInfoId": null, 
"name": "COMPUTER FEE",
"value": "1350"
},
{
"additionalInfoId": null, 
"name": "EXAM FEE",
"value": "500"
}
],
"customerParams": [
{
"name": "Admission No/Application No/GR No", 
"value": "LF3130",
"type": null
},
{
"name": "Date Of Birth (DD-MM-YYYY)", 
"value": null,
"type": null
},
{
"name": "Mobile No", 
"value": null,
"type": null
}
],
"creationDate": "2021-12-09T08:37:40.082462", 
"modifiedDate": "2021-12-09T08:37:42.303627",
"createdEpochDate": 1639039060,
"modifiedEpochDate": 1639039062
}    
```

<mark style="color:blue;">**Json Formatted Response Example (failure response)**</mark>

```json
{
"genericResponse": { 
"message": "",
"remarks": "Fetch Request not supported, only QuickPay permitted", 
"status": "Failure",
"statusCode": "500"
},
"billId": "XXXXXXXX-7d79-4e3c-bd2d-382276669ba9",
"refId": "xxXXXxxxxxS4VZlr9bUF2lCCzFc4823081150", 
"billerId": "XXXXXXXXXXXXXX",
"status": "BILL_FETCH_FAILED",
"actionType": "BILL_FETCH", 
"userId": "FE41XXXXXXXXXXXXXX",
"billerResponse": null, 
"customerParams": [
{}
],
"creationDate": "2022-11-04T11:50:50+05:30", 
"modifiedDate": "2022-11-04T11:50:50.460818",
"createdEpochDate": 1667542850,
"modifiedEpochDate": 1667542850
}
```


# Get all Plan categories

<mark style="color:blue;">**API for getting plan categories for a specific biller.This api has to be invoked if planMDM requirement is mandatory for the biller, it will return the plan categories**</mark>

| Endpoint                                                                                                |
| ------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /masters/planCategories?billerId=HUNG00000NA**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type    | Description       |
| -------------------------------------- | --------------------- | --------- | ------------ | ----------------- |
| \[ROOT] (No parent property / element) | billerId              | M         | Alphanumeric | Fixed Length – 14 |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                       |
| -------------------------------------- | --------------------- | --------- | --------- | ------------------------------------------------- |
| \[ROOT] (No parent property / element) | categoryRespList      | M         | List      | List of categories                                |
| generalResp                            | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure               |
|                                        | status                | M         | String    | It is either “Success” or failure                 |
|                                        | message               | M         | String    | Contains the reason message for failure / success |
|                                        | remarks               | C         | String    |                                                   |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

<pre class="language-json"><code class="lang-json">    {
<strong>    "generalResp": { 
</strong>    "statusCode": "200",
    "status": "success",
    "message": "Categories retrieved successfully", 
    "remarks": ""
    },
    "categoryRespList": 
    [ "Music"
    ]
    }
</code></pre>


# Get all Plans

<mark style="color:blue;">**API for getting list of plans for a specific biller.This api has to be invoked if planMDM requirement is mandatory for the biller, it will return the list of plans**</mark>

| Endpoint                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /masters/plans?billerId=HUNG00000NATJL\&category=Music\&page=0\&pagesize=10**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type    | Description                             |
| -------------------------------------- | --------------------- | --------- | ------------ | --------------------------------------- |
| \[ROOT] (No parent property / element) | billerId              | M         | Alphanumeric | Fixed Length – 14                       |
|                                        | category              | C         | String       | Category of the Plan                    |
|                                        | amountInRupees        | C         | String       | Amount of the Plan                      |
|                                        | circle                | C         | String       | Circle of the Plan                      |
|                                        | page                  | C         | Numeric      | Page number for API Response Pagination |
|                                        | pagesize              | C         | Numeric      | Page Size for API Response Pagination   |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                                                                                                               |
| -------------------------------------- | --------------------- | --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| plans                                  | planId                | M         | String    | A unique id to identify the plans                                                                                                         |
|                                        | description           | M         | String    | Description of the plan                                                                                                                   |
|                                        | billerId              | M         | String    | Biller id of fixed lenght                                                                                                                 |
|                                        | categoryType          | M         | String    |                                                                                                                                           |
|                                        | categorySubType       | M         | String    |                                                                                                                                           |
|                                        | amountInRupees        | M         | String    |                                                                                                                                           |
|                                        | effctvFrom            | M         | String    |                                                                                                                                           |
|                                        | effctvTo              | M         | String    |                                                                                                                                           |
|                                        | status                | M         | String    |                                                                                                                                           |
| additionalInfo                         | planAdditionalInfoId  | M         | UUID      |                                                                                                                                           |
|                                        | tags                  | M         | List      | Will be a list of additional ifos Eg: { "tagId":"d55aa58e-bf83-4273-80ee- 7bc8e7c4f1a2", "name": "Package Duration", "value": "1 Month" } |
| \[Root] (No parent property / element) | pageNo                | M         | Numeric   | Page number for API Response Pagination                                                                                                   |
|                                        | pageSize              | M         | Numeric   | Page Size for API Response Pagination                                                                                                     |
|                                        | totalElements         | M         | Numeric   |                                                                                                                                           |
|                                        | totalPages            | M         | Numeric   |                                                                                                                                           |
| generalResp                            | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                                                                                       |
|                                        | status                | M         | String    | It is either “Success” or failure                                                                                                         |
|                                        | message               | M         | String    | Contains the reason message for failure / success                                                                                         |
|                                        | remarks               | C         | String    |                                                                                                                                           |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
    {
    "plansList": {
    "plans": [
    {
    "planId": "2862",
    "description": "Listen trending & popular Music, download songs, create your own playlist!", 
    "billerId": "HUNG00000NATJL",
    "categoryType": "Music", 
    "categorySubType": [], 
    "amountInRupees": 99, 
    "additionalInfo": {
    "planAdditionalInfoId": "cca72e87-e994-4409-87cb-a25b2a4598ba", 
    "tags": [
    {
    "tagId": "d55aa58e-bf83-4273-80ee-7bc8e7c4f1a2", 
    "name": "Package Duration",
    "value": "1 Month"
    }
    ]
    },
    "effctvFrom": "2021-10-26",
    "effctvTo": "2022-10-26",
    "status": "ACTIVE"
    },
    {
    "planId": "2863",
    "description": "Listen trending & popular Music, download songs, create your own playlist!", 
    "billerId": "HUNG00000NATJL",
    "categoryType": "Music",
    "categorySubType": [],
    "amountInRupees": 499, 
    "additionalInfo": {
    "planAdditionalInfoId": "cd5fb9d3-afc6-488f-a354-863241d0fae3", 
    "tags": [
    {
    "tagId": "ccf2d727-5081-46d4-9ff1-58caae26894a", 
    "name": "Package Duration",
    "value": "12 Months"
    }
    ]
    },
    "effctvFrom": "2021-10-26",
    "effctvTo": "2022-10-26",
    "status": "ACTIVE"
    }
    ]
    },
    "generalResp": { "statusCode": "200",
    "status": "success",
    "message": "Plans retrieved successfully", 
    "remarks": ""
    },
    "pageNo": 0,
    "pageSize": 10,
    "totalElements": 2,
    "totalPages": 1
    }    
```


# Bill Validate API

<mark style="color:blue;">**API for validating a Customer Bill, based on Biller Category, Customer Parameters etc.**</mark>

| Endpoint                                                                           |
| ---------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**POST /couapp/bills/validate**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name  | Mandatory | Data Type    | Description                                                          |
| ------------------------------------------ | ---------------------- | --------- | ------------ | -------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | tenantId               | M         | Alphanumeric | Fixed Length – 14                                                    |
|                                            | billerId               | M         | Alphanumeric | Unique ID assigned to the Biller by NPCI Eg: BSNL00000NATHL          |
|                                            | billerName             | M         | String       | Name of the biller                                                   |
|                                            | billerCategory         | M         | String       | Category of biler                                                    |
|                                            | macAdress              | C         | Alphanumeric | MAC Address of the Agent Server                                      |
|                                            | customerMobNo          | M         | String       | Mobile of the Customer, on whose behalf the Agent is paying the Bill |
|                                            | clientReqId            | C         | String       | A unique id which the client has to provide                          |
|                                            | customerParamsReques t | M         | Object       | Unique parameters used for identifying a Customer Bill               |
| **customerParamsReq uest**                 | tags                   | M         | List         | List of customer params                                              |
| **tags**                                   | name                   | M         | String       | Name of customer param                                               |
| **tags**                                   | value                  | M         | String       | Value of customer param                                              |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type | Description                                             |
| ------------------------------------------ | --------------------- | --------- | --------- | ------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | billId                | C         | UUID      | Machine-generated Unique ID for a Bill, used internally |
|                                            | refId                 | C         | String    | Will be null                                            |
|                                            | billerId              | C         | String    | Will be null                                            |
|                                            | status                | C         | String    | Will be null                                            |
|                                            | actionType            | C         | String    | Will be null                                            |
|                                            | billerResponse        | C         | String    | Will be null                                            |
|                                            | additionalInfo        | C         | String    | Will be null                                            |
|                                            | customerParams        | C         | String    | Will be null                                            |
|                                            | planInfoDaos          | C         | String    | Will be null                                            |
|                                            | creationDate          | C         | String    | Will be null                                            |
|                                            | modifiedDate          | C         | String    | Will be null                                            |
|                                            | createdEpochDate      | C         | String    | Will be null                                            |
|                                            | modifiedEpochDate     | C         | String    | Will be null                                            |
| **generalResp**                            | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                     |
|                                            | status                | M         | String    | It is either “Success” or failure                       |
|                                            | message               | M         | String    | Contains the reason message for failure / success       |
|                                            | remarks               | C         | String    |                                                         |

<mark style="color:blue;">**Json Formatted Request Example**</mark>

```json
{
"tenantId": "FE41",
"billerId": "HUNG00000NATJL",
"customerParamsRequest": 
{ "tags": [
{
"name": "Mobile Number", 
"value": "8281970522"
},
{
"name": "Email ID",
"value": "jithesh@digiledge.in"
},
{
"name": "Id",
"value": "2862"
}
]
},
"billerName": "Hungama Music", 
"billerCategory": "Subscription", 
"macAdress": null, 
"customerMobNo": "8281970523"
}
```

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"genericResponse": { 
"statusCode": "200",
"status": "success",
"message": "Bill Validate Initiated", 
"remarks": ""
},
"billId": "c9670952-ebd7-487a-b6ea-49f2b4d4a718", 
"refId": null,
"billerId": null, 
"status": null, "actionType": null, 
"userId": null, "billerResponse": null, 
"additionalInfo": null,
"customerParams": null, 
"planInfoDaos": null, 
"creationDate": null, 
"modifiedDate": null, 
"createdEpochDate": 0,
"modifiedEpochDate": 0
}
```


# Bill Validation response by Client Request ID API

<mark style="color:blue;">**API for getting validation response, based on Client Request ID**</mark>

| Endpoint                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /couapp/bills/validate/byClientId?clientReqId=vgRdasd248**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type    | Description       |
| ------------------------------------------ | --------------------- | --------- | ------------ | ----------------- |
| **\[ROOT]** (No parent property / element) | clientReqId           | M         | Alphanumeric | Fixed Length – 10 |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type    | Description                                                                                                                                    |
| ------------------------------------------ | --------------------- | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | billId                | M         | UUID         | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                            | refId                 | M         | Alphanumeric | Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages |
|                                            | billerId              | M         | String       | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                                                     |
|                                            | status                | M         | String       | Status of the Operation Possible values : BILL\_FETCH\_REQUESTED, BILL\_FETCH\_INITIATED, BILL\_FETCH\_SUCCESS, BILL\_FETCH\_FAILED            |
|                                            | actionType            | C         | String       | Type of Bill Payment. Possible Values: BILL\_FETCH QUICKPAY BILL\_VALIDATE                                                                     |
|                                            | userId                | M         | Alphanumeric | Agent id Fixed length - 20                                                                                                                     |
|                                            | creationDate          | M         | String       | ISO 8601 Timestamp for the Bill Creation date                                                                                                  |
|                                            | modifiedDate          | M         | String       | ISO 8601 Timestamp for the Bill Modification date                                                                                              |
|                                            | createdEpochDate      | M         | Numeric      | UNIX Epoch Timestamp for the Bill Creation date                                                                                                |
|                                            | modifiedEpochDate     | M         | Numeric      | UNIX Epoch Timestamp for the Bill Modification date                                                                                            |
| **billerResponse**                         | billId                | M         | String       | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                            | amount                | M         | String       | Actual bill amount inclusive of all charges                                                                                                    |
|                                            | billDate              | M         | String       | This field denotes generation date of the bill                                                                                                 |
|                                            | billNumber            | M         | Numeric      | This field denotes the bill number of the bill fetch / payment message requested                                                               |
|                                            | billPeriod            | M         | String       | The bill period of the bill fetch / payment requested                                                                                          |
|                                            | custConvFee           | M         | String       | Customer convenience fee (CCF1) paid by the Customer Operating Unit                                                                            |
|                                            | couCustConvFee        | M         | String       | Customer convenience fee (CCF2), paid by the Customer to Customer Operating Unit                                                               |
|                                            | dueDate               | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                            | customerName          | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                            | amountOption          | M         | Boolean      | A flag indicating if the Biller supports Amount Options                                                                                        |
|                                            | tagList               | M         | String       | Amount Breakup Options eg:{"name": "Additional Charges", "value": "500"}                                                                       |
| **additionalInfo**                         | name                  | C         | String       | Name of the Additional Info Parameter                                                                                                          |
|                                            | value                 | C         | String       | Value of the Additional Info Parameter                                                                                                         |
| **customerParams**                         | name                  | C         | String       | Name of the Customer Parameter attribute                                                                                                       |
|                                            | value                 | C         | String       | Value of the Customer Parameter attribute                                                                                                      |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"genericResponse": null,
"billId": "c9670952-ebd7-487a-b6ea-49f2b4d4a718", 
"refId": "ukpeZdOmtQCK4ByLFatdrWhtIiucPIXigYF", 
"billerId": "HUNG00000NATJL",
"status": "BILL_VALIDATE_SUCCESS",
"actionType": "VALIDATE_PAY", 
"userId": "FE41FE42BNK519012345",
"billerResponse": null, 
"additionalInfo": [], 
"customerParams": [
{
"name": "Mobile Number", 
"value": "8281970522",
"type": null
},
{
"name": "Email ID",
"value": "jithesh@digiledge.in", 
"type": null
},
{
"name": "Id",
"value": "2862", 
"type": null
}
],
"planInfoDaos": [],
"creationDate": "2021-12-09T10:27:57.889640",
"modifiedDate": "2021-12-09T10:28:02.775484",
"createdEpochDate": 1639045677,
"modifiedEpochDate": 1639045682
}
```


# Bill validation response by bill id

#### <mark style="color:blue;">API for getting validation response, based on Bill id</mark>&#x20;

| Endpoint                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------- |
| **Request:**<mark style="color:blue;">**GET /couapp/bills/validate/byId?billId=c9670952-ebd7-487a-b6ea-49f2b4d4a718**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                         |
| -------------------------------------- | --------------------- | --------- | --------- | --------------------------------------------------- |
| \[ROOT] (No parent property / element) | billid                | M         | UUID      | Bill id can be get from the bill validate response. |

<mark style="color:blue;">**Response Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type    | Description                                                                                                                                    |
| ------------------------------------------ | --------------------- | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | billId                | M         | UUID         | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                            | refId                 | M         | Alphanumeric | Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages |
|                                            | billerId              | M         | String       | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                                                     |
|                                            | status                | M         | String       | Status of the Operation Possible values : BILL\_FETCH\_REQUESTED, BILL\_FETCH\_INITIATED, BILL\_FETCH\_SUCCESS, BILL\_FETCH\_FAILED            |
|                                            | actionType            | C         | String       | Type of Bill Payment. Possible Values: BILL\_FETCH QUICKPAY BILL\_VALIDATE                                                                     |
|                                            | userId                | M         | Alphanumeric | Agent id Fixed length - 20                                                                                                                     |
|                                            | creationDate          | M         | String       | ISO 8601 Timestamp for the Bill Creation date                                                                                                  |
|                                            | modifiedDate          | M         | String       | ISO 8601 Timestamp for the Bill Modification date                                                                                              |
|                                            | createdEpochDate      | M         | Numeric      | UNIX Epoch Timestamp for the Bill Creation date                                                                                                |
|                                            | modifiedEpochDate     | M         | Numeric      | UNIX Epoch Timestamp for the Bill Modification date                                                                                            |
| **billerResponse**                         | billId                | M         | String       | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                            | amount                | M         | String       | Actual bill amount inclusive of all charges                                                                                                    |
|                                            | billDate              | M         | String       | This field denotes generation date of the bill                                                                                                 |
|                                            | billNumber            | M         | Numeric      | This field denotes the bill number of the bill fetch / payment message requested                                                               |
|                                            | billPeriod            | M         | String       | The bill period of the bill fetch / payment requested                                                                                          |
|                                            | custConvFee           | M         | String       | Customer convenience fee (CCF1) paid by the Customer Operating Unit                                                                            |
|                                            | couCustConvFee        | M         | String       | Customer convenience fee (CCF2), paid by the Customer to Customer Operating Unit                                                               |
|                                            | dueDate               | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                            | customerName          | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                            | amountOption          | M         | Boolean      | A flag indicating if the Biller supports Amount Options                                                                                        |
|                                            | tagList               | M         | String       | Amount Breakup Options eg:{"name": "Additional Charges", "value": "500"}                                                                       |
| **additionalInfo**                         | name                  | C         | String       | Name of the Additional Info Parameter                                                                                                          |
|                                            | value                 | C         | String       | Value of the Additional Info Parameter                                                                                                         |
| **customerParams**                         | name                  | C         | String       | Name of the Customer Parameter attribute                                                                                                       |
|                                            | value                 | C         | String       | Value of the Customer Parameter attribute                                                                                                      |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"genericResponse": null,
"billId": "c9670952-ebd7-487a-b6ea-49f2b4d4a718", 
"refId": "ukpeZdOmtQCK4ByLFatdrWhtIiucPIXigYF", 
"billerId": "HUNG00000NATJL",
"status": "BILL_VALIDATE_SUCCESS",
"actionType": "VALIDATE_PAY", 
"userId": "FE41FE42BNK519012345",
"billerResponse": null, 
"additionalInfo": [], 
"customerParams": [
{
"name": "Mobile Number", 
"value": "8281970522",
"type": null
},
{
"name": "Email ID",
"value": "jithesh@digiledge.in", 
"type": null
},
{
"name": "Id",
"value": "2862", 
"type": null
}
],
"planInfoDaos": [],
"creationDate": "2021-12-09T10:27:57.889640", 
"modifiedDate": "2021-12-09T10:28:02.775484",
"createdEpochDate": 1639045677,
"modifiedEpochDate": 1639045682
}
```


# Bill Payment API

<mark style="color:blue;">**API for paying a Customer Bill, based on Biller Category, Customer Parameters etc.**</mark>

| Endpoint                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Request:**<mark style="color:blue;">**POST**</mark><mark style="color:blue;">**&#x20;**</mark>*<mark style="color:blue;">**/couapp/agent/bills/payment**</mark>* |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name  | Mandatory | Data Type    | Description                                                          |
| ------------------------------------------ | ---------------------- | --------- | ------------ | -------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | tenantId               | M         | Alphanumeric | Fixed Length – 4                                                     |
|                                            | refId                  | M         | Alphanumeric | 35-character Alphanumeric ID Unique to each transaction.             |
|                                            | billId                 | M         | Alphanumeric | Generated when a bill fetch or bill validation is initiated          |
|                                            | amountBreakSet         | C         | List         |                                                                      |
|                                            | paymentMode            | M         | String       |                                                                      |
|                                            | paymentInformation     | M         | String       |                                                                      |
|                                            | amountOptions          | M         | Boolean      |                                                                      |
|                                            | billerId               | M         | Alphanumeric | Unique ID assigned to the Biller by NPCI Eg: BSNL00000NATHL          |
|                                            | billerName             | M         | String       | Name of the biller                                                   |
|                                            | billerCategory         | M         | String       | Category of biler                                                    |
|                                            | macAdress              | C         | Alphanumeric | MAC Address of the Agent Server                                      |
|                                            | customerMobNo          | M         | String       | Mobile of the Customer, on whose behalf the Agent is paying the Bill |
|                                            | txnAmount              | M         | Int          | Transaction amount                                                   |
|                                            | paymentChannel         | M         | String       | Payment Channel of Agent                                             |
|                                            | deviceBlockTags        | M         | List         | Device block tags of Agent                                           |
|                                            | customerParamsReques t | M         | Object       | Unique parameters used for identifying a Customer Bill               |
| **customerParamsReq uest**                 | tags                   | M         | List         | List of customer params                                              |
| **tags**                                   | name                   | M         | String       | Name of customer param                                               |
| **tags**                                   | value                  | M         | String       | Value of customer param                                              |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                   | Property/Element Name | Mandatory | Data Type | Description                                             |
| ----------------------------------------- | --------------------- | --------- | --------- | ------------------------------------------------------- |
| **\[ROOT]**(No parent property / element) | billid                | C         | UUID      | Machine-generated Unique ID for a Bill, used internally |
|                                           | refId                 | C         | String    | Will be null                                            |
|                                           | billerId              | C         | String    | Will be null                                            |
|                                           | status                | C         | String    | Will be null                                            |
|                                           | actionType            | C         | String    | Will be null                                            |
|                                           | billerResponse        | C         | String    | Will be null                                            |
|                                           | additionalInfo        | C         | String    | Will be null                                            |
|                                           | customerParams        | C         | String    | Will be null                                            |
|                                           | creationDate          | C         | String    | Will be null                                            |
|                                           | modifiedDate          | C         | String    | Will be null                                            |
|                                           | createdEpochDate      | C         | String    | Will be null                                            |
|                                           | modifiedEpochDate     | C         | String    | Will be null                                            |
| generalResp                               | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                     |
|                                           | status                | M         | String    | It is either “Success” or failure                       |
|                                           | message               | M         | String    | Contains the reason message for failure / success       |
|                                           | remarks               | C         | String    |                                                         |

<mark style="color:blue;">**Json Formatted Request Example**</mark>

```json
{
"tenantId": "FE41", "actionType": "FETCH_PAY", 
"amountBreakSet": null, 
"amountOptions": false,
"billId": "5947f973-b595-484d-a19c-24a7668b058e",
"billerCategory": "Loan Repayment", 
"billerId": "KIFS00000NATST",
"billerName": "KIFS Housing Finance Ltd", 
"customerMobNo": "8281970522", 
"customerParams": [
{
"name": "APPLICATION NUMBER",
"value": "7710485"
}
],
"paymentMode": "UPI", "paymentChannel": "Agent", 
"paymentInformation": "xxxxxxxx@abc", 
"deviceBlockTags": [
{
"name": "MOBILE", 
"value": "9591810218"
},
{
"name": "GEOCODE",
"value": "28.6139,78.5555"
},
{
"name": "POSTAL_CODE",
"value": "600001"
},
{
"name": "TERMINAL_ID",
"value": "333001"
}
],
"refId": "vkL5Q79lukhzL4dSHatditBwzin20751743", 
"txnAmount": 5600
}
```

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"txnId": "fdd28ccc-90bd-4719-8adf-26e085d18d54", 
"refId": null,
"actionType": null, 
"userType": null, 
"userId": null, 
"txnAmount": 0.0, 
"billerId": null, 
"billerCategory": null, 
"offUsPay": null, 
"splitPay": null, 
"quickPay": null, 
"paymentMode": null, 
"custConvFee": null,
"currency": null,
"status": "BILL_PAYMENT_INITIATED",
"genericResponse": { 
"statusCode": "200",
"status": "success",
"message": "Bill Payment Initiated", 
"remarks": ""
}
}
```

**Initiating Channel Vs Device Block Parameters**

| Initiating Channel                | Device Block Tags                           |
| --------------------------------- | ------------------------------------------- |
| Bank Branch                       | IFSC, MOBILE, GEOCODE, POSTAL\_CODE         |
| Mobile (Pre-login)                | IP, IMEI, OS, APP                           |
| Mobile Banking(Post-login)        | IP, IMEI, OS, APP                           |
| Internet (Pre-login)              | IP, MAC                                     |
| Internet Banking (Post-login) ATM | <p>IP, MAC</p><p>TERMINAL\_ID</p>           |
| Kiosk                             | TERMINAL\_ID                                |
| Agent                             | TERMINAL\_ID, MOBILE, GEOCODE, POSTAL\_CODE |
| Business Correspondent            | TERMINAL\_ID, MOBILE, GEOCODE, POSTAL\_CODE |

**Payment Mode Vs Payment Info Parameters**

| Payment Mode     | Payment Information Tag |
| ---------------- | ----------------------- |
| Cash             | Remarks                 |
| Internet Banking | IFSC\|AccountNo         |
| Credit Card      | CardNum\|AuthCode       |
| DEbit Card       | CardNum\|AuthCode       |
| Prepaid Card     | CardNum\|AuthCode       |
| IMPS             | MMID\|MobileNo          |
| NEFT             | IFSC\|AccountNo         |
| UPI              | VPA                     |
| Wallet           | WalletName\|MobileNo    |
| AEPS             | Aadhaar\|IIN            |
| Account Transfer | IFSC\|AccountNo         |
| Bharat QR        | IFSC\|AccountNo         |
| USSD             | Remarks                 |


# Transaction Status txnId API

<mark style="color:blue;">**API for checking the transaction status using txn id**</mark>

| Endpoint                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------ |
| **Request:**<mark style="color:blue;">**GET /couapp/transactions/payment/byTxnId?txnId=fdd28ccc-90bd-4719-8adf-26e085d18d54**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                                                                                                    |
| -------------------------------------- | --------------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| \[ROOT] (No parent property / element) | txnId                 | M         | UUID      | Txn id is unique id which is generated while initiating the bill payment request, it can be get from the bill paymentresponse. |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name  | Mandatory | Data Type                                                                                                                                  | Description                                                    |
| -------------------------------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | txnId                  | M         | UUID                                                                                                                                       | Machine-generated Unique ID for a transaction, used internally |
|                                        | refId                  | M         | Alphanumeric                                                                                                                               |                                                                |
|                                        | txnNpciId              | C         | Alphanumeric                                                                                                                               |                                                                |
|                                        | orderId                | M         | String                                                                                                                                     |                                                                |
|                                        | billId                 | M         |                                                                                                                                            |                                                                |
|                                        | userType               | M         |                                                                                                                                            |                                                                |
|                                        | userId                 | M         | Unique ID assigned to the Agent by NPCI                                                                                                    |                                                                |
|                                        | txnAmount              | M         | Total Transaction Amount for the Bill                                                                                                      |                                                                |
|                                        | totalTxnAmount         | M         | Actual bill amount inclusive of all charges                                                                                                |                                                                |
|                                        | billerName             | M         | Name of the Biller assigned by NPCI                                                                                                        |                                                                |
|                                        | billerCategory         | M         | Category of the Biller                                                                                                                     |                                                                |
|                                        | billerId               | M         | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                                                 |                                                                |
|                                        | clientReqId            | M         | Unique ID assigned for each transaction, to be used internally                                                                             |                                                                |
|                                        | offUsPay               | M         | Flag indicating if it is an electronic ON-US or OFF-US transaction                                                                         |                                                                |
|                                        | splitPay               | M         | Flag indicating if the bill is paid using two different payment modes                                                                      |                                                                |
|                                        | quickPay               | M         | Flag indicating if the payment is initiated without a fetch or not                                                                         |                                                                |
|                                        | paymentMode            | M         |                                                                                                                                            |                                                                |
|                                        | custConvFee            | M         |                                                                                                                                            |                                                                |
|                                        | currency               | M         | Defines the currency in which the payment is initiated. 356 stands for INR                                                                 |                                                                |
|                                        | requestedIp            | M         | IP address of the initiating Server                                                                                                        |                                                                |
|                                        | customerMobNo          | M         |                                                                                                                                            |                                                                |
|                                        | macAddress             | M         |                                                                                                                                            |                                                                |
|                                        | splitPayAmount         | M         |                                                                                                                                            |                                                                |
|                                        | couCustConvFee         | M         |                                                                                                                                            |                                                                |
|                                        | settlementVerification | M         | Flag indicating if Settlement Verification is enabled for the transaction                                                                  |                                                                |
|                                        | fundTxnType            | M         |                                                                                                                                            |                                                                |
|                                        | reason                 | M         |                                                                                                                                            |                                                                |
|                                        | amountTags             | M         |                                                                                                                                            |                                                                |
|                                        | customerParamsDAOS     | M         |                                                                                                                                            |                                                                |
|                                        | paymentInformation     | M         |                                                                                                                                            |                                                                |
|                                        | customerParamsDAO      | M         |                                                                                                                                            |                                                                |
|                                        | planId                 | M         |                                                                                                                                            |                                                                |
|                                        | planType               | M         |                                                                                                                                            |                                                                |
|                                        | status                 | M         | Status of the Operation Posible values : BILL\_PAYMENT\_REQUESTED, BILL\_PAYMENT\_INITIATED, BILL\_PAYMENT\_SUCCESS, BILL\_PAYMENT\_FAILED |                                                                |
|                                        | actionType             | C         | Type of Bill Payment. Possible Values: BILL\_FETCH QUICKPAY BILL\_VALIDATE                                                                 |                                                                |
|                                        | userId                 | M         | Agent id Fixed length - 20                                                                                                                 |                                                                |
|                                        | creationDate           | M         | ISO 8601 Timestamp for the Bill Creation date                                                                                              |                                                                |
|                                        | modifiedDate           | M         | ISO 8601 Timestamp for the Bill Modification date                                                                                          |                                                                |
|                                        | createdEpochDate       | M         | UNIX Epoch Timestamp for the Bill Creation date                                                                                            |                                                                |
|                                        | modifiedEpochDate      | M         | UNIX Epoch Timestamp for the Bill Modification date                                                                                        |                                                                |
| agentFundTransfer                      | fundTxnReferenceId     | M         |                                                                                                                                            |                                                                |
|                                        | fundTxnRemarks         | M         |                                                                                                                                            |                                                                |
|                                        | fundTxnDate            | M         |                                                                                                                                            |                                                                |
|                                        | fundUTR                | M         |                                                                                                                                            |                                                                |
|                                        | fundRespRemarks        | M         |                                                                                                                                            |                                                                |
|                                        | agentNpciId            | M         |                                                                                                                                            |                                                                |
|                                        | txnRefId               | M         |                                                                                                                                            |                                                                |
|                                        | fundStatus             | M         | Status of fund transfer Possible values: FUND\_TRANSFER\_SUCCESS, FUND\_TRANSFER\_FAILED                                                   |                                                                |
| generalResp                            | statusCode             | M         | 200- SUCCESS Other than 200-Failure                                                                                                        |                                                                |
|                                        | status                 | M         | String                                                                                                                                     | It is either “Success” or failure                              |
|                                        | message                | M         | String                                                                                                                                     | Contains the reason message for failure / success              |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"transactionDAO": {
"txnId": "fdd28ccc-90bd-4719-8adf-26e085d18d54", 
"refId": "ukpeZdOmtQCK4ByLFatdrWhtIiucPIXigYF", 
"txnNpciId": "FE411343V3mFjMC0aqOp",
"orderId": "DFW9GM5B65WV88XMKG9815KQ",
"actionType": "VALIDATE_PAY",
"billId": "c9670952-ebd7-487a-b6ea-49f2b4d4a718", 
"userType": "organization",
"userId": "FE41FE42BNK519012345",
"txnAmount": 9900,
"totalTxnAmount": 9900, 
"billerId": "HUNG00000NATJL",
"billerCategory": "Subscription", 
"billerName": "Hungama Music", 
"clientReqId": null,
"offUsPay": "NO",
"splitPay": "NO",
"quickPay": "NO", 
"paymentMode": "Cash", 
"custConvFee": 0,
"currency": "356",
"status": "BILL_PAYMENT_SUCCESS",
"requestedIp": "10.11.2.4",
"customerMobNo": "8281970523", 
"macAddress": null, 
"splitPayAmount": 0,
"couCustConvFee": 0, 
"settlementVerification": false, 
"fundTxnType": "WALLET_TRANSFER", 
"reason": null,
"amountTags": [], 
"customerParamsDAOS": [], 
"paymentInformation": [], 
"customerParamsDAO": [
{
"paramsId": "78dd4417-726f-4f45-a671-4ead120417e2", 
"name": "Mobile Number",
"value": "8281970522",
"type": null
},
{
"paramsId": "0bc3c1b3-019a-4cf3-863b-4455d0eac80c", 
"name": "Email ID",
"value": "jithesh@digiledge.in", 
"type": null
},
{
"paramsId": "8a810c5c-d8ad-4092-98a5-a98e20b6e7d2", 
"name": "Id",
"value": "2862", 
"type": null
}
],
"creationDate": "2021-12-09T10:51:08.278329", 
"modifiedDate": "2021-12-09T10:51:15.040695",
"createdEpochDate": 1639047068,
"modifiedEpochDate": 1639047075, 
"planId": null,
"planType": null
},
"agentFundTransfer": {
"fundTxnReferenceId": "DFW9GM5B65WV88XMKG9815KQ", 
"fundTxnRemarks": "BBPS-AGENT/fdd28ccc-90bd-4719-8adf-26e085d18d54", 
"fundTxnDate": "2018-04-10 14:36:09.404068",
"fundTxnAmt": 9900,
"fundUTR": "801218794476",
"fundRespRemarks": "SUCCESS", 
"agentNpciId": "FE41FE42BNK519012345",
"txnRefId": "fdd28ccc-90bd-4719-8adf-26e085d18d54", 
"fundStatus": "FUND_TRANSFER_SUCCESS"
},
"generalResp": { 
"statusCode": "200",
"status": "success",
"message": "Successfully transaction retrieved by txnId", 
"remarks": ""
}
}
```


# Transaction Status ClientReqId API

<mark style="color:blue;">**API for checking the transaction status using ClientReqId.**</mark>

| Endpoint                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------ |
| **Request:**<mark style="color:blue;">**GET /couapp/transactions/payment/byClientId?clientReqId=vgRdasd24**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                | Property/Element Name        | Mandatory | Data Type                      | Description                         |
| -------------------------------------- | ---------------------------- | --------- | ------------------------------ | ----------------------------------- |
| \[ROOT] (No parent property / element) | <p><br></p><p>byClientId</p> | M         | <p><br></p><p>Alphanumeric</p> | <p><br></p><p>Fixed Length – 10</p> |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name  | Mandatory | Data Type              | Description                                                                                                                                    |
| -------------------------------------- | ---------------------- | --------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | txnId                  | M         | <p><br></p><p>UUID</p> | Machine-generated Unique ID for a transaction, used internally                                                                                 |
|                                        | refId                  | M         | Alphanumeric           | Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages |
|                                        | txnNpciId              | C         | Alphanumeric           | Unique Transaction ID assigned by NPCI                                                                                                         |
|                                        | orderId                | M         | String                 |                                                                                                                                                |
|                                        | billId                 | M         | String                 |                                                                                                                                                |
|                                        | userType               | M         | String                 |                                                                                                                                                |
|                                        | userId                 | M         | String                 | Unique ID assigned to the Agent by NPCI                                                                                                        |
|                                        | txnAmount              | M         | String                 | Total Transaction Amount for the Bill                                                                                                          |
|                                        | totalTxnAmount         |           | String                 | Actual bill amount inclusive of all charges                                                                                                    |
|                                        | billerName             | M         | String                 | Name of the Biller assigned by NPCI                                                                                                            |
|                                        | billerCategory         | M         | String                 | Category of the Biller                                                                                                                         |
|                                        | billerId               | M         | String                 | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                                                     |
|                                        | clientReqId            | M         | String                 | Unique ID assigned for each transaction, to be used internally                                                                                 |
|                                        | offUsPay               | M         | String                 | Flag indicating if it is an electronic ON-US or OFF-US transaction                                                                             |
|                                        | splitPay               | M         | String                 | Flag indicating if the bill is paid using two different payment modes                                                                          |
|                                        | quickPay               | M         | String                 | Flag indicating if the payment is initiated without a fetch or not                                                                             |
|                                        | paymentMode            | M         | String                 |                                                                                                                                                |
|                                        | custConvFee            | M         | String                 |                                                                                                                                                |
|                                        | currency               | M         | String                 | Defines the currency in which the payment is initiated. 356 stands for INR                                                                     |
|                                        | requestedIp            | M         | String                 | IP address of the initiating Server                                                                                                            |
|                                        | customerMobNo          | M         | Numeric                |                                                                                                                                                |
|                                        | macAddress             | M         | Alphanumeric           |                                                                                                                                                |
|                                        | splitPayAmount         | M         | String                 |                                                                                                                                                |
|                                        | couCustConvFee         | M         | String                 |                                                                                                                                                |
|                                        | settlementVerification | M         | String                 | Flag indicating if Settlement Verification is enabled for the transaction                                                                      |
|                                        | fundTxnType            | M         | String                 |                                                                                                                                                |
|                                        | reason                 | M         | String                 |                                                                                                                                                |
|                                        | amountTags             | M         | String                 |                                                                                                                                                |
|                                        | customerParamsDAOS     | M         | String                 |                                                                                                                                                |
|                                        | paymentInformation     | M         | String                 |                                                                                                                                                |
|                                        | customerParamsDAO      | M         | String                 |                                                                                                                                                |
|                                        | planId                 | M         | String                 |                                                                                                                                                |
|                                        | planType               | M         | String                 |                                                                                                                                                |
|                                        | status                 | M         | String                 | Status of the Operation                                                                                                                        |
|                                        | actionType             | C         | String                 | Type of Bill Payment. Possible Values: BILL\_FETCH QUICKPAY BILL\_VALIDATE                                                                     |
|                                        | userId                 | M         | Alphanumeric           | Agent id Fixed length - 20                                                                                                                     |
|                                        | creationDate           | M         | String                 | ISO 8601 Timestamp for the Bill Creation date                                                                                                  |
|                                        | modifiedDate           | M         | String                 | ISO 8601 Timestamp for the Bill Modification date                                                                                              |
|                                        | createdEpochDate       | M         | Numeric                | UNIX Epoch Timestamp for the Bill Creation date                                                                                                |
|                                        | modifiedEpochDate      | M         | Numeric                | UNIX Epoch Timestamp for the Bill Modification date                                                                                            |
| agentFundTransfer                      | fundTxnReferenceId     | M         | String                 |                                                                                                                                                |
|                                        | fundTxnRemarks         | M         | String                 |                                                                                                                                                |
|                                        | fundTxnDate            | M         | String                 |                                                                                                                                                |
|                                        | fundUTR                | M         | String                 |                                                                                                                                                |
|                                        | fundRespRemarks        | M         | String                 |                                                                                                                                                |
|                                        | agentNpciId            | M         | String                 |                                                                                                                                                |
|                                        | txnRefId               | M         | String                 |                                                                                                                                                |
|                                        | fundStatus             | M         | String                 | Status of the fund transfer Possible values:                                                                                                   |
| customerParamsDAO                      | name                   | C         | String                 | Name of the Customer Parameter attribute                                                                                                       |
|                                        | value                  | C         | String                 | Value of the Customer Parameter attribute                                                                                                      |
|                                        | paramsId               | C         | UUID                   |                                                                                                                                                |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"transactionDAO": {
"txnId": "fdd28ccc-90bd-4719-8adf-26e085d18d54", 
"refId": "ukpeZdOmtQCK4ByLFatdrWhtIiucPIXigYF", 
"txnNpciId": "FE411343V3mFjMC0aqOp",
"orderId": "DFW9GM5B65WV88XMKG9815KQ",
"actionType": "VALIDATE_PAY",
"billId": "c9670952-ebd7-487a-b6ea-49f2b4d4a718", 
"userType": "organization",
"userId": "FE41FE42BNK519012345",
"txnAmount": 9900,
"totalTxnAmount": 9900, 
"billerId": "HUNG00000NATJL",
"billerCategory": "Subscription",
"billerName": "Hungama Music", 
"clientReqId": null,
"offUsPay": "NO",
"splitPay": "NO",
"quickPay": "NO", 
"paymentMode": "Cash", 
"custConvFee": 0,
"currency": "356",
"status": "BILL_PAYMENT_SUCCESS",
"requestedIp": "10.11.2.4",
"customerMobNo": "8281970523", 
"macAddress": null, 
"splitPayAmount": 0,
"couCustConvFee": 0, 
"settlementVerification": false, 
"fundTxnType": "WALLET_TRANSFER", 
"reason": null,
"amountTags": [], 
"customerParamsDAOS": [], 
"paymentInformation": [], 
"customerParamsDAO": [
{
"paramsId": "78dd4417-726f-4f45-a671-4ead120417e2", 
"name": "Mobile Number",
"value": "8281970522",
"type": null
},
{
"paramsId": "0bc3c1b3-019a-4cf3-863b-4455d0eac80c", 
"name": "Email ID",
"value": "jithesh@digiledge.in", 
"type": null
},
{
"paramsId": "8a810c5c-d8ad-4092-98a5-a98e20b6e7d2", 
"name": "Id",
"value": "2862", 
"type": null
}
],
"creationDate": "2021-12-09T10:51:08.278329", 
"modifiedDate": "2021-12-09T10:51:15.040695",
"createdEpochDate": 1639047068,
"modifiedEpochDate": 1639047075, 
"planId": null,
"planType": null
},
"agentFundTransfer": {
"fundTxnReferenceId": "DFW9GM5B65WV88XMKG9815KQ", 
"fundTxnRemarks": "BBPS-AGENT/fdd28ccc-90bd-4719-8adf-26e085d18d54", 
"fundTxnDate": "2018-04-10 14:36:09.404068",
"fundTxnAmt": 9900,
"fundUTR": "801218794476",
"fundRespRemarks": "SUCCESS", 
"agentNpciId": "FE41FE42BNK519012345",
"txnRefId": "fdd28ccc-90bd-4719-8adf-26e085d18d54", 
"fundStatus": "FUND_TRANSFER_SUCCESS"
},
"generalResp": { 
"statusCode": "200",
"status": "success",
"message": "Successfully transaction retrieved by txnId", 
"remarks": ""
}
}

```


# Adding complaint by txnId

<mark style="color:blue;">**Api used to raise complaint against a transaction**</mark>

| Endpoint                                                                 |
| ------------------------------------------------------------------------ |
| **Request:**<mark style="color:blue;">**POST /couapp/complaints**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                              |
| -------------------------------------- | --------------------- | --------- | --------- | -------------------------------------------------------- |
| \[ROOT] (No parent property / element) | complaintDescription  | M         | String    | Complaint description that the user enters               |
|                                        | complaintDisposition  | M         | String    | Complaint disposition                                    |
|                                        | complaintType         | M         | String    | The type of complaint                                    |
|                                        | txnId                 | O         | UUID      | Transaction id for which the complaint is raised against |
|                                        | clientReqId           | O         | String    | Client req id for which the complaint is raised against  |

<mark style="color:blue;">**Response Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element | Property/Element Name | Mandatory | Data Type | Description                                              |
| ----------------------- | --------------------- | --------- | --------- | -------------------------------------------------------- |
| complaints              | complaintId           | M         | UUID      | Id for the complaint disposion                           |
|                         | complaintDescr        | M         | String    | Complaint description                                    |
|                         | complaintDispos       | M         | String    | Complaint disposition                                    |
|                         | complaintType         | M         | String    | Type of the complaint                                    |
|                         | txnId                 | M         | String    | Transaction id for which the complaint is raised agains  |
|                         | txnNpciId             | M         | String    | Transaction id for which the complaint is raised agains  |
|                         | assignedTo            | M         | String    | To Whom the complaint is assigned                        |
|                         | complaintNpciId       | M         | String    | Npci id of the complaint                                 |
|                         | complaintRaisedFrom   | M         | String    | Who raised the complaint                                 |
|                         | userId                | M         | String    | User id of the one who raised the complaint              |
|                         | status                | M         | String    | Status of the complaint                                  |
|                         | refId                 | M         | String    | Reference id                                             |
|                         | estimated\_TAT        | M         | String    |                                                          |
|                         | creationDate          | M         | String    | ISO 8601 Timestamp for the Complaint Creation date       |
|                         | modifiedDate          | M         | String    | ISO 8601 Timestamp for the Complaint Modification date   |
|                         | createdEpochDate      | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Creation date     |
|                         | modifiedEpochDate     | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Modification date |
| generalResp             | statusCode            | M         | String    | 200- SUCCESS Other than 200-Failure                      |
|                         | status                | M         | String    | It is either “Success” or failure                        |
|                         | message               | M         | String    | Contains the reason message for failure / success        |

<mark style="color:blue;">**Json Formatted RequestExample**</mark>

```json
{
"complaintDescription": "Testing",
"complaintDisposition": "Transaction Successful, account nAot updated", 
"complaintType": "transaction",
"txnId": "6f5c45bb-03f7-46c2-88a8-7c1ac9f83714", 
"tenantId": "FE41"
}
```

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"complaints": { 
"complaintDescr": "Testing",
"complaintDispos": "Transaction Successful, account not updated", 
"complaintId": "5383c03b-28e7-4d9c-ac4c-3d19e6ec9e61", 
"complaintRaisedFrom": "agent",
"complaintType": "npciComplaint", 
"createdEpochDate": 1682315434, 
"creationDate": "2023-04-24T11:20:34.937317Z", 
"modifiedDate": "2023-04-24T11:20:35.105937Z",
"modifiedEpochDate": 1682315435,
"refId": "wpTw4UDGDS23mSPYK7vmub2X8uX31141120", 
"status": "COMPLAINT_REQUEST_SUCCESS",
"tenantId": "FE41",
"txnId": "6f5c45bb-03f7-46c2-88a8-7c1ac9f83714", 
"txnNpciId": "FE413102sViuzlGJFbCy",
"userId": "FE41FE42BNK519012345", 
"agentId": "FE41FE42BNK519012345"
},
"generalResp": {
"message": "Complaint raising requested", 
"remarks": "",
"status": "success", 
"statusCode": "200"
}
}
```


# View Complaints by id

<mark style="color:blue;">**Api used to view complaint by id**</mark>

| Endpoint                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------- |
| **Request:**<mark style="color:blue;">**GET /couapp/complaints/byId?complaintId=4576768b-0f43-4056-b0dd-2c2d285c6455**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description  |
| -------------------------------------- | --------------------- | --------- | --------- | ------------ |
| \[ROOT] (No parent property / element) | complaintId           | M         | String    | Complaint id |

<mark style="color:blue;">**Response Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element | Property/Element Name | Mandatory | Data Type | Description                                                        |
| ----------------------- | --------------------- | --------- | --------- | ------------------------------------------------------------------ |
| complaintsList          | complaintId           | M         | UUID      | Id for the complaint disposion                                     |
|                         | complaintDescr        | M         | String    | Complaint description                                              |
|                         | complaintDispos       | M         | String    | Complaint disposition                                              |
|                         | complaintType         | M         | String    | Type of the complaint                                              |
|                         | txnId                 | M         | String    | Transaction id for which the complaint is raised agains            |
|                         | complaintStatus       | M         | String    | Complaint Status from NPCI                                         |
|                         | assignedTo            | M         | String    | To Whom the complaint is assigned                                  |
|                         | complaintNpciId       | M         | String    | Npci id of the complaint                                           |
|                         | complaintRaisedFrom   | M         | String    | Who raised the complaint                                           |
|                         | userId                | M         | String    | User id of the one who raised the complaint                        |
|                         | status                | M         | String    | Status of the complaint                                            |
|                         | refId                 | M         | String    | Reference id                                                       |
|                         | estimated\_TAT        | M         | String    |                                                                    |
|                         | creationDate          | M         | String    | ISO 8601 Timestamp for the Complaint Creation date                 |
|                         | modifiedDate          | M         | String    | ISO 8601 Timestamp for the Complaint Modification date             |
|                         | billerName            | M         | String    | Biller Name                                                        |
|                         | txnAmount             | M         | String    | Txn Amount                                                         |
|                         | superLevelEsc         | M         | String    | Super Escalation (True/False)                                      |
|                         | openComplaint         | M         | String    | Flag indicating whether complaint is already open or not (Y/N)     |
|                         | reopenComplaint       | M         | String    | Flag indicating whether complaint is already reopened or not (Y/N) |
|                         | remarks               | M         | String    | Remarks                                                            |
|                         | agentId               | M         | String    | Agent ID                                                           |
|                         | category              | M         | String    | Category of the biller                                             |
|                         | createdEpochDate      | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Creation date               |
|                         | modifiedEpochDate     | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Modification date           |
| generalResp             | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                |
|                         | status                | M         | String    | It is either “Success” or failure                                  |
|                         | message               | M         | String    | Contains the reason message for failure / success                  |

*<mark style="color:blue;">**Json Formatted Response Example**</mark>*

```json
{
"complaintsList": [
{
"assignedTo": "",
"comment": "",
"complaintDescr": "Testing complaint",
"complaintDispos": "Transaction Successful, account not updated", 
"complaintId": "2dfecc3c-9114-4094-9aa8-ff26f03a9bfd", 
"complaintNpciId": "FE4123109489834",
"complaintRaisedFrom": "agent", 
"complaintType": "npciComplaint", 
"createdEpochDate": 1681905485, 
"creationDate": "2023-04-19T17:28:05.508679Z",
"estimated_TAT": "",
"modifiedDate": "2023-04-24T10:07:51.756969Z",
"modifiedEpochDate": 1682311071,
"refId": "mqcXfZs2XMkRKQfpIwoSYQDnIr231091728", 
"status": "COMPLAINT_OPEN_SUCCESS",
"txnId": "24fe190c-42c9-4cb5-9d36-965839b0cb5f", 
"userId": "FE41FE42BNK519012345",
"category": "Education Fees",
"billerName": "Meerut Institute Of Technology test", 
"txnAmount": 50000,
"totalTxnAmount": 50000, 
"complaintStatus": "", 
"superLevelEsc": "",
"openComplaint": "", 
"reopenComplaint": "", 
"remarks": "",
"agentId": "FE41FE42BNK519012345"
}
],
"generalResp": {
"message": "Complaints retrieved successfully", 
"remarks": "",
"status": "success", 
ead"statusCode": "200"
},
"pageNo": 0,
"pageSize": 1,
"totalPages": 1,
"totalElements": 1
}
```


# View All Complaints

<mark style="color:blue;">**Api used to view all complaints**</mark>

| Endpoint                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------- |
| **Request:**<mark style="color:blue;">**GET /couapp/complaints/all?pageNo=0\&pageSize=5\&statusType= COMPLAINT\_OPEN\_SUCCESS**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------- | --------------------- | --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | statusType            | M         | String    | Status of the complaint, possible values are - COMPLAINT\_OPEN\_SUCCESS COMPLAINT\_OPEN\_FAILED COMPLAINT\_CLOSURE\_SUCCESS COMPLAINT\_CLOSURE\_FAILED COMPLAINT\_REOPEN\_SUCCESS COMPLAINT\_REOPEN\_FAILED COMPLAINT\_STATUS\_UPDATE COMPLAINT\_REQUEST\_INITIATED COMPLAINT\_REQUEST\_SUCCESS COMPLAINT\_REQUEST\_FAILED COMPLAINT\_CLOSURE\_REQUEST\_SUCCE SS COMPLAINT\_CLOSURE\_REQUEST\_FAILE D COMPLAINT\_REOPEN\_REQUEST\_SUCCES S COMPLAINT\_REOPEN\_REQUEST\_FAILED COMPLAINT\_REASSIGN\_REQUEST\_SUCC ESS- COMPLAINT\_REASSIGN\_REQUEST\_FAILE D COMPLAINT\_REASSIGN\_SUCCESS COMPLAINT\_REASSIGN\_FAILED |
|                                        | page                  | C         | Numeric   | Page number for API Response Pagination                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|                                        | pagesize              | C         | Numeric   | Page Size for API Response Pagination                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

#### <mark style="color:blue;">Response Parameters</mark>

**The various parameters are explained below:**

| Parent Property/Element | Property/Element Name | Mandatory | Data Type | Description                                                        |
| ----------------------- | --------------------- | --------- | --------- | ------------------------------------------------------------------ |
| complaintsList          | complaintId           | M         | UUID      | Id for the complaint disposion                                     |
|                         | complaintDescr        | M         | String    | Complaint description                                              |
|                         | complaintDispos       | M         | String    | Complaint disposition                                              |
|                         | complaintType         | M         | String    | Type of the complaint                                              |
|                         | txnId                 | M         | String    | Transaction id for which the complaint is raised agains            |
|                         | complaintStatus       | M         | String    | Complaint Status from NPCI                                         |
|                         | assignedTo            | M         | String    | To Whom the complaint is assigned                                  |
|                         | complaintNpciId       | M         | String    | Npci id of the complaint                                           |
|                         | complaintRaisedFrom   | M         | String    | Who raised the complaint                                           |
|                         | userId                | M         | String    | User id of the one who raised the complaint                        |
|                         | status                | M         | String    | Status of the complaint                                            |
|                         | refId                 | M         | String    | Reference id                                                       |
|                         | estimated\_TAT        | M         | String    |                                                                    |
|                         | creationDate          | M         | String    | ISO 8601 Timestamp for the Complaint Creation date                 |
|                         | modifiedDate          | M         | String    | ISO 8601 Timestamp for the Complaint Modification date             |
|                         | billerName            | M         | String    | Biller Name                                                        |
|                         | txnAmount             | M         | String    | Txn Amount                                                         |
|                         | superLevelEsc         | M         | String    | Super Escalation (True/False)                                      |
|                         | openComplaint         | M         | String    | Flag indicating whether complaint is already open or not (Y/N)     |
|                         | reopenComplaint       | M         | String    | Flag indicating whether complaint is already reopened or not (Y/N) |
|                         | remarks               | M         | String    | Remarks                                                            |
|                         | agentId               | M         | String    | Agent ID                                                           |
|                         | category              | M         | String    | Category of the biller                                             |
|                         | createdEpochDate      | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Creation date               |
|                         | modifiedEpochDate     | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Modification date           |
| generalResp             | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                |
|                         | status                | M         | String    | It is either “Success” or failure                                  |
|                         | message               | M         | String    | Contains the reason message for failure / success                  |

```json
{
"complaintsList": [
{
"assignedTo": "",
"comment": "",
"complaintDescr": "Testing complaint",\
"complaintDispos": "Transaction Successful, account not updated", 
"complaintId": "2dfecc3c-9114-4094-9aa8-ff26f03a9bfd", 
"complaintNpciId": "FE4123109489834",
"complaintRaisedFrom": "agent", 
"complaintType": "npciComplaint", 
"createdEpochDate": 1681905485, 
"creationDate": "2023-04-19T17:28:05.508679Z",
"estimated_TAT": "",
"modifiedDate": "2023-04-24T10:07:51.756969Z",
"modifiedEpochDate": 1682311071,
"refId": "mqcXfZs2XMkRKQfpIwoSYQDnIr231091728", 
"status": "COMPLAINT_OPEN_SUCCESS",
"txnId": "24fe190c-42c9-4cb5-9d36-965839b0cb5f", 
"userId": "FE41FE42BNK519012345",
"category": "Education Fees",
"billerName": "Meerut Institute Of Technology test", 
"txnAmount": 50000,
"totalTxnAmount": 50000, 
"complaintStatus": "", 
"superLevelEsc": "",
"openComplaint": "", 
"reopenComplaint": "", 
"remarks": "",
"agentId": "FE41FE42BNK519012345"
}
],
"generalResp": {
"message": "Complaints retrieved successfully", 
"remarks": "",
"status": "success", 
"statusCode": "200"
},
"pageNo": 0,
"pageSize": 1,
"totalPages": 1,
"totalElements": 1
}


```

**Status and its meaning :-**

Open Complaint - COMPLAINT\_OPEN\_SUCCESS Failed Complaint - COMPLAINT\_OPEN\_FAILED Closed Complaint - COMPLAINT\_CLOSURE\_SUCCESS Closure Failed Complaint - COMPLAINT\_CLOSURE\_FAILED ReOpened Complaints - COMPLAINT\_REOPEN\_SUCCESS ReOpen Failed Complaints - COMPLAINT\_REOPEN\_FAILED Status Updated Complaints (508 Alert) - COMPLAINT\_STATUS\_UPDATE Complaint Request Initiated from Biller/Agent - COMPLAINT\_REQUEST\_INITIATED Complaint Requested from Biller/Agent - COMPLAINT\_REQUEST\_SUCCESS Failed Complaint Request from Biller/Agent - COMPLAINT\_REQUEST\_FAILED Successful Complaint Closure Request - COMPLAINT\_CLOSURE\_REQUEST\_SUCCESS Failed Complaint Closure Request - COMPLAINT\_CLOSURE\_REQUEST\_FAILED Successful Complaint Reopen Request - COMPLAINT\_REOPEN\_REQUEST\_SUCCESS Failed Complaint Reopen Request - COMPLAINT\_REOPEN\_REQUEST\_FAILED Successful Complaint Reassign request from COU - COMPLAINT\_REASSIGN\_REQUEST\_SUCCESS Failed Complaint Reassign request from COU -COMPLAINT\_REASSIGN\_REQUEST\_FAILED ReAssigned Complaints - COMPLAINT\_REASSIGN\_SUCCESS ReAssign Failed Complaints - COMPLAINT\_REASSIGN\_FAILED


# Txn Status Check API (401)

<mark style="color:blue;">**API for checking the txn status at NPCI (401 API) by providing either refId or NPCI Txn Ref ID**</mark>

| Endpoint                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Request:**<mark style="color:blue;">**POST**</mark><mark style="color:blue;">**&#x20;**</mark>*<mark style="color:blue;">**/couapp/transactions/status**</mark>* |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name    | Mandatory | Data Type    | Description                                                                                |
| -------------------------------------- | ------------------------ | --------- | ------------ | ------------------------------------------------------------------------------------------ |
| \[ROOT] (No parent property / element) | tenantId                 | M         | Alphanumeric | Fixed Length – 4                                                                           |
|                                        | id                       | M         | Alphanumeric | 35 in case of refId and 12/20 in case of NPCI Txn Ref ID                                   |
|                                        | <p><br></p><p>idType</p> | M         | Alphanumeric | Specifies whether RefId or TxnNpci ID is provided. Possible values are ‘txnId’ and ‘refId’ |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                                           |
| -------------------------------------- | --------------------- | --------- | --------- | --------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | txnStatusReqRefId     | C         | String    | <p></p><p>Ref ID of the 401 Txn Status Check Request sent to NPCI</p> |
|                                        | agentId               | C         | String    | Masked Agent ID of the agent via which transaction was done           |
|                                        | billerId              | C         | String    | Biller ID of the biller for which transaction has happened            |
|                                        | approvalRefNum        | C         | String    | Approval Ref Number of the transaction                                |
|                                        | txnRefId              | C         | String    | 12/20 characters Txn NPCI ID                                          |
|                                        | mti                   | C         | String    | Message Type Indicator - Value will be PAYMENT                        |
|                                        | txnDate               | C         | String    | Txn Date in RFC3339 format                                            |
|                                        | amount                | C         | String    | Txn Amount in Paise                                                   |
|                                        | txnStatus             | C         | String    | Status of the transaction. Possible values are SUCCESS and FAILED     |
|                                        | customerMobile        | C         | String    | Mobile number of the customer who initiated the transaction           |
| generalResp                            | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                   |
|                                        | status                | M         | String    | It is either “Success” or Failure                                     |
|                                        | message               | M         | String    | Contains the reason message for failure / success                     |
|                                        | remarks               | C         | String    | Contains the reason message for failure / success                     |

***Json Formatted Request Example***

<pre class="language-json"><code class="lang-json"><strong>{
</strong>"id": "FE413037ar3R7jo3LwxN",
"idType" : "txnId", 
"tenantId" : "FE41"
}
</code></pre>

***Json Formatted Response Example***

```json
{
"txnStatusReqRefId": "Uwn3Ots72IwcRXWLueCJBzTsCT930391051", 
"agentId": "FE41XXXXBNK519012345",
"billerId": "KIFS00000NATST",
"approvalRefNum": "076e716e-a5ea-11ed-837a-0242ac130016", 
"txnRefId": "FE413037ar3R7jo3LwxN",
"mti": "PAYMENT",
"txnDate": "2023-02-06T12:16:47+05:30",
"amount": "10000", 
"txnStatus": "SUCCESS",
"customerMobile": "8891604640", 
"generalResp": {
"message": "Txn status response retrieved",
"remarks": "Txn status response retrieved",
"status": "Success", 
"statusCode": "200"
}
}
```


# View Complaints History by id

<mark style="color:blue;">**Api used to view complaint history by complaint id**</mark>

| Endpoint                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**/couapp/complaints/history/byId?complaintId= 809ec4c7-d81b-4d2b-9c66- 3011a6fae714**</mark> |

<mark style="color:blue;">**Request Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description  |
| -------------------------------------- | --------------------- | --------- | --------- | ------------ |
| \[ROOT] (No parent property / element) | complaintId           | M         | String    | Complaint id |

<mark style="color:blue;">**Response Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element | Property/Element Name | Mandatory | Data Type | Description                                              |
| ----------------------- | --------------------- | --------- | --------- | -------------------------------------------------------- |
| complaintsHistories     | complaintId           | M         | String    | Id for the complaint disposion                           |
|                         | complaintDescr        | M         | String    | Complaint description                                    |
|                         | complaintDispos       | M         | String    | Complaint disposition                                    |
|                         | txnId                 | M         | String    | Transaction id for which the complaint is raised agains  |
|                         | complaintHistoryId    | M         | String    | Complaint History ID                                     |
|                         | assignedTo            | M         | String    | To Whom the complaint is assigned                        |
|                         | complaintNpciId       | M         | String    | Npci id of the complaint                                 |
|                         | complaintRaisedFrom   | M         | String    | Who raised the complaint                                 |
|                         | userId                | M         | String    | User id of the one who raised the complaint              |
|                         | status                | M         | String    | Status of the complaint                                  |
|                         | refId                 | M         | String    | Reference id                                             |
|                         | complaintType         | M         | String    | Complaint Type (internalComplaint,npciComplaint)         |
|                         | modifiedDate          | M         | String    | ISO 8601 Timestamp for the Complaint Modification date   |
|                         | modifiedEpochDate     | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Modification date |
| generalResp             | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                      |
|                         | status                | M         | String    | It is either “Success” or failure                        |
|                         | message               | M         | String    | Contains the reason message for failure / success        |

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"complaintsHistories": [
{
"complaintHistoryId": "26dd6ae7-235f-425a-9c10-b546bb10fffc", 
"complaintId": "809ec4c7-d81b-4d2b-9c66-3011a6fae714", 
"complaintDescr": "Issue reassigning",
"complaintDispos": "Transaction Successful, account not updated", 
"txnId": "155a4a71-141f-40fd-b772-9d0e020963e8",
"assignedTo": "Federal Bank", 
"complaintNpciId": "FE4123109776644", 
"complaintType": "npciComplaint", 
"complaintRaisedFrom": "agent", 
"userId": "FE41FE42BNK519012345",
"status": "COMPLAINT_REASSIGN_REQUEST_SUCCESS", 
"modifiedDate": "2023-04-20T18:24:20.408824Z",
"modifiedEpochDate": 1681995260, 
"tenantId": "FE41"
}
],
"generalResp": {
"message": "Complaints retrieved successfully",
"remarks": "",
"status": "success", 
"statusCode": "200"
},
"pageNo": 0,
"pageSize": 1,
"totalPages": 1,
"totalElements": 1
}
```


# Close Complaint

<mark style="color:blue;">**API for closing raised complaint.**</mark>

**Complaint can be closed only if the complaint status are the following COMPLAINT\_OPEN\_SUCCESS COMPLAINT\_REOPEN\_SUCCESS COMPLAINT\_CLOSURE\_REQUEST\_FAILED COMPLAINT\_CLOSURE\_REQUEST\_SUCCESS**

| Endpoint                                                                       |
| ------------------------------------------------------------------------------ |
| **Request:** *<mark style="color:blue;">**/couapp/complaints/closure**</mark>* |

<mark style="color:blue;">**Request Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type    | Description                       |
| -------------------------------------- | --------------------- | --------- | ------------ | --------------------------------- |
| \[ROOT] (No parent property / element) | tenantId              | M         | Alphanumeric | Fixed Length – 4                  |
|                                        | complaintDescr        | M         | Alphanumeric | Description for closing complaint |
|                                        | complaintId           | M         | UUID         | Complaint UUID                    |

<mark style="color:blue;">**Response Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element | Property/Element Name | Mandatory | Data Type | Description                                                        |
| ----------------------- | --------------------- | --------- | --------- | ------------------------------------------------------------------ |
| complaints              | complaintId           | M         | UUID      | Id for the complaint disposion                                     |
|                         | complaintDescr        | M         | String    | Complaint description                                              |
|                         | complaintDispos       | M         | String    | Complaint disposition                                              |
|                         | complaintType         | M         | String    | Type of the complaint                                              |
|                         | txnId                 | M         | String    | Transaction id for which the complaint is raised agains            |
|                         | complaintStatus       | M         | String    | Complaint Status from NPCI                                         |
|                         | assignedTo            | M         | String    | To Whom the complaint is assigned                                  |
|                         | complaintNpciId       | M         | String    | Npci id of the complaint                                           |
|                         | complaintRaisedFrom   | M         | String    | Who raised the complaint                                           |
|                         | userId                | M         | String    | User id of the one who raised the complaint                        |
|                         | status                | M         | String    | Status of the complaint                                            |
|                         | refId                 | M         | String    | Reference id                                                       |
|                         | estimated\_TAT        | M         | String    |                                                                    |
|                         | creationDate          | M         | String    | ISO 8601 Timestamp for the Complaint Creation date                 |
|                         | modifiedDate          | M         | String    | ISO 8601 Timestamp for the Complaint Modification date             |
|                         | billerName            | M         | String    | Biller Name                                                        |
|                         | txnAmount             | M         | String    | Txn Amount                                                         |
|                         | superLevelEsc         | M         | String    | Super Escalation (True/False)                                      |
|                         | openComplaint         | M         | String    | Flag indicating whether complaint is already open or not (Y/N)     |
|                         | reopenComplaint       | M         | String    | Flag indicating whether complaint is already reopened or not (Y/N) |
|                         | remarks               | M         | String    | Remarks                                                            |
|                         | agentId               | M         | String    | Agent ID                                                           |
|                         | category              | M         | String    | Category of the biller                                             |
|                         | createdEpochDate      | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Creation date               |
|                         | modifiedEpochDate     | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Modification date           |
| generalResp             | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                |
|                         | status                | M         | String    | It is either “Success” or failure                                  |
|                         | message               | M         | String    | Contains the reason message for failure / success                  |

#### *<mark style="color:blue;">**Json Formatted Request Example**</mark>*

```json
{
"complaintDescr" : "Closing complaint Issue resolved", "complaintId" : "809ec4c7-d81b-4d2b-9c66-3011a6fae714", "tenantId" : "FE41"
}
```

#### *<mark style="color:blue;">**Json Formatted Response Example**</mark>*

```json
{
"complaints": {
"complaintDescr": "Closing complaint Issue resolved",
"complaintDispos": "Transaction Successful, account not updated", 
"complaintId": "809ec4c7-d81b-4d2b-9c66-3011a6fae714", 
"complaintNpciId": "FE4123109776644",
"complaintRaisedFrom": "agent", 
"complaintType": "npciComplaint", 
"createdEpochDate": 1681893776, 
"creationDate": "2023-04-19T14:12:56.329935Z", 
"modifiedDate": "2023-04-19T14:13:32.25255Z",
"modifiedEpochDate": 1681893812,
"refId": "hHfEKYZExIpxNEV65HMQZ2Lh0DA31091413", 
"status": " COMPLAINT_CLOSURE_REQUEST_SUCCESS ",
"tenantId": "FE41",
"txnId": "155a4a71-141f-40fd-b772-9d0e020963e8", 
"txnNpciId": "FE413045Hl3L90ZWg59o",
"userId": "FE41FE42BNK519012345", 
"agentId": "FE41FE42BNK519012345"
},
"generalResp": {
"message": "Complaint closure requested", 
"remarks": "",
"status": "success", 
"statusCode": "200"
}
}
```


# Reopen Complaint

#### <mark style="color:blue;">**API for reopening closed complaint. Complaint can be reopened only if the**</mark>&#x20;

**Complaint status are the following**

**COMPLAINT\_CLOSURE\_SUCCESS COMPLAINT\_CLOSURE\_FAILED COMPLAINT\_REOPEN\_REQUEST\_FAILED COMPLAINT\_REOPEN\_REQUEST\_SUCCESS**

| Endpoint                                                                      |
| ----------------------------------------------------------------------------- |
| **Request:** *<mark style="color:blue;">**/couapp/complaints/reopen**</mark>* |

<mark style="color:blue;">**Request Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                                              | Property/Element Name | Mandatory | Data Type    | Description                       |
| -------------------------------------------------------------------- | --------------------- | --------- | ------------ | --------------------------------- |
| <p><br></p><p>\[ROOT]</p><p>(No parent property</p><p>/ element)</p> | tenantId              | M         | Alphanumeric | Fixed Length – 4                  |
|                                                                      | complaintDescr        | M         | Alphanumeric | Description for closing complaint |
|                                                                      | complaintId           | M         | UUID         | Complaint UUID                    |

<mark style="color:blue;">**Response Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element | Property/Element Name | Mandatory | Data Type | Description                                                        |
| ----------------------- | --------------------- | --------- | --------- | ------------------------------------------------------------------ |
| complaints              | complaintId           | M         | UUID      | Id for the complaint disposion                                     |
|                         | complaintDescr        | M         | String    | Complaint description                                              |
|                         | complaintDispos       | M         | String    | Complaint disposition                                              |
|                         | complaintType         | M         | String    | Type of the complaint                                              |
|                         | txnId                 | M         | String    | Transaction id for which the complaint is raised agains            |
|                         | complaintStatus       | M         | String    | Complaint Status from NPCI                                         |
|                         | assignedTo            | M         | String    | To Whom the complaint is assigned                                  |
|                         | complaintNpciId       | M         | String    | Npci id of the complaint                                           |
|                         | complaintRaisedFrom   | M         | String    | Who raised the complaint                                           |
|                         | userId                | M         | String    | User id of the one who raised the complaint                        |
|                         | status                | M         | String    | Status of the complaint                                            |
|                         | refId                 | M         | String    | Reference id                                                       |
|                         | estimated\_TAT        | M         | String    |                                                                    |
|                         | creationDate          | M         | String    | ISO 8601 Timestamp for the Complaint Creation date                 |
|                         | modifiedDate          | M         | String    | ISO 8601 Timestamp for the Complaint Modification date             |
|                         | billerName            | M         | String    | Biller Name                                                        |
|                         | txnAmount             | M         | String    | Txn Amount                                                         |
|                         | superLevelEsc         | M         | String    | Super Escalation (True/False)                                      |
|                         | openComplaint         | M         | String    | Flag indicating whether complaint is already open or not (Y/N)     |
|                         | reopenComplaint       | M         | String    | Flag indicating whether complaint is already reopened or not (Y/N) |
|                         | remarks               | M         | String    | Remarks                                                            |
|                         | agentId               | M         | String    | Agent ID                                                           |
|                         | category              | M         | String    | Category of the biller                                             |
|                         | createdEpochDate      | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Creation date               |
|                         | modifiedEpochDate     | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Modification date           |
| generalResp             | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                |
|                         | status                | M         | String    | It is either “Success” or failure                                  |
|                         | message               | M         | String    | Contains the reason message for failure / success                  |

#### *<mark style="color:blue;">**Json Formatted Request Example**</mark>*

```json
{
"complaintDescr" : "Issue not yet solved - reopening", 
"complaintId" : "809ec4c7-d81b-4d2b-9c66-3011a6fae714", 
"tenantId" : "FE41"
}
```

#### *<mark style="color:blue;">**Json Formatted Response Example**</mark>*

```json
{
"complaints": {
"assignedTo": "Federal Bank",
"complaintDescr": "Issue not yet solved - reopening", 
"complaintDispos": "Transaction Successful, account not updated", 
"complaintId": "809ec4c7-d81b-4d2b-9c66-3011a6fae714", 
"complaintNpciId": "FE4123109776644",
"complaintRaisedFrom": "agent", 
"complaintType": "npciComplaint", 
"createdEpochDate": 1681893776, 
"creationDate": "2023-04-19T14:12:56.329935Z", 
"modifiedDate": "2023-04-19T14:19:44.891423Z",
"modifiedEpochDate": 1681894184,
"refId": "7sQwBamvWFyLxhK84dYgGmV24r831091419", 
"status": "COMPLAINT_REOPEN_SUCCESS",
"tenantId": "FE41",
"txnId": "155a4a71-141f-40fd-b772-9d0e020963e8", 
"txnNpciId": "FE413045Hl3L90ZWg59o",
"userId": "FE41FE42BNK519012345", 
"agentId": "FE41FE42BNK519012345"
},
"generalResp": {
"message": "Complaint reopening requested", 
"remarks": "",
"status": "success", 
"statusCode": "200"
}
}
```


# Complaint Status

<mark style="color:blue;">**API for fetching latest status of the complaint from NPCI. The API can be invoked only if complaintType is npciComplaint.**</mark>

| Endpoint                                                                      |
| ----------------------------------------------------------------------------- |
| **Request:** *<mark style="color:blue;">**/couapp/complaints/status**</mark>* |

<mark style="color:blue;">**Request Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element                                              | Property/Element Name | Mandatory | Data Type    | Description      |
| -------------------------------------------------------------------- | --------------------- | --------- | ------------ | ---------------- |
| <p><br></p><p>\[ROOT]</p><p>(No parent property</p><p>/ element)</p> | tenantId              | M         | Alphanumeric | Fixed Length – 4 |
|                                                                      | complaintId           | M         | UUID         | Complaint UUID   |

<mark style="color:blue;">**Response Parameters**</mark>

***The various parameters are explained below:***

| Parent Property/Element | Property/Element Name | Mandatory | Data Type | Description                                                        |
| ----------------------- | --------------------- | --------- | --------- | ------------------------------------------------------------------ |
| complaints              | complaintId           | M         | UUID      | Id for the complaint disposion                                     |
|                         | complaintDescr        | M         | String    | Complaint description                                              |
|                         | complaintDispos       | M         | String    | Complaint disposition                                              |
|                         | complaintType         | M         | String    | Type of the complaint                                              |
|                         | txnId                 | M         | String    | Transaction id for which the complaint is raised agains            |
|                         | complaintStatus       | M         | String    | Complaint Status from NPCI                                         |
|                         | assignedTo            | M         | String    | To Whom the complaint is assigned                                  |
|                         | complaintNpciId       | M         | String    | Npci id of the complaint                                           |
|                         | complaintRaisedFrom   | M         | String    | Who raised the complaint                                           |
|                         | userId                | M         | String    | User id of the one who raised the complaint                        |
|                         | status                | M         | String    | Status of the complaint                                            |
|                         | refId                 | M         | String    | Reference id                                                       |
|                         | estimated\_TAT        | M         | String    |                                                                    |
|                         | creationDate          | M         | String    | ISO 8601 Timestamp for the Complaint Creation date                 |
|                         | modifiedDate          | M         | String    | ISO 8601 Timestamp for the Complaint Modification date             |
|                         | billerName            | M         | String    | Biller Name                                                        |
|                         | txnAmount             | M         | String    | Txn Amount                                                         |
|                         | superLevelEsc         | M         | String    | Super Escalation (True/False)                                      |
|                         | openComplaint         | M         | String    | Flag indicating whether complaint is already open or not (Y/N)     |
|                         | reopenComplaint       | M         | String    | Flag indicating whether complaint is already reopened or not (Y/N) |
|                         | remarks               | M         | String    | Remarks                                                            |
|                         | agentId               | M         | String    | Agent ID                                                           |
|                         | category              | M         | String    | Category of the biller                                             |
|                         | createdEpochDate      | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Creation date               |
|                         | modifiedEpochDate     | M         | Numeric   | UNIX Epoch Timestamp for the Complaint Modification date           |
| generalResp             | statusCode            | M         | Numeric   | 200- SUCCESS Other than 200-Failure                                |
|                         | status                | M         | String    | It is either “Success” or failure                                  |
|                         | message               | M         | String    | Contains the reason message for failure / success                  |

#### *<mark style="color:blue;">**Json Formatted Request Example**</mark>*

```json
{
"complaintId" : "2dfecc3c-9114-4094-9aa8-ff26f03a9bfd", 
"tenantId" : "FE41"
}
```

#### *<mark style="color:blue;">**Json Formatted Response Example**</mark>*

```json
{
"complaints": { "assignedTo": "XYZ Bank",
"complaintDescr": "Testing complaint",
"complaintDispos": "Transaction Successful, account not updated", 
"complaintId": "2dfecc3c-9114-4094-9aa8-ff26f03a9bfd", 
"complaintNpciId": "FE4123109489834",
"complaintRaisedFrom": "agent", 
"complaintType": "npciComplaint", 
"createdEpochDate": 1681905485, 
"creationDate": "2023-04-19T17:28:05.508679Z",
"modifiedDate": "2023-04-19T17:28:10.001432Z",
"modifiedEpochDate": 1681905490,
"refId": "mqcXfZs2XMkRKQfpIwoSYQDnIr231091728", 
"status": "COMPLAINT_OPEN_SUCCESS",
"tenantId": "FE41",
"txnId": "24fe190c-42c9-4cb5-9d36-965839b0cb5f", 
"txnNpciId": "FE4131090DAI26Y0mAxl",
"userId": "FE41FE42BNK519012345", 
"agentId": "FE41FE42BNK519012345"
},
"generalResp": {
"message": "Successfully requested complaint status", 
"remarks": "",
"status": "success", 
"statusCode": "200"
}
}
```


# Get all Plan categories

API for getting plan categories for a specific biller. This api has to be invoked if planMDM requirement is mandatory for the biller, it will return the plan categories.

Endpint:\
Request: GET /masters/planCategories?billerId=HUNG00000NA

#### Request body

<table><thead><tr><th width="244">Parent Property/Element</th><th width="216">Property/Element Name</th><th width="121">Mandatory</th><th width="166">Data type</th><th width="168">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billerId</td><td>M</td><td>Alphanumeric</td><td>Fixed Length – 14</td></tr></tbody></table>

#### Response body

<table><thead><tr><th width="235">Parent Property/Element</th><th width="232">Property/Element Name</th><th width="146">Mandatory</th><th width="122">Data Type</th><th width="341">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>categoryRespList</td><td>M</td><td>List</td><td>List of categories</td></tr><tr><td>generalResp</td><td>statusCode</td><td>M</td><td>Numeric</td><td>200- SUCCESS Other than 200-Failure</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>It is either “Success” or failure</td></tr><tr><td></td><td>message</td><td>M</td><td>String</td><td>Contains the reason message for failure / success</td></tr><tr><td></td><td>remarks</td><td>C</td><td>String</td><td></td></tr></tbody></table>

```json
{
    "generalResp": {
        "statusCode": "200",
        "status": "success",
        "message": "Categories retrieved successfully",
        "remarks": ""
    },
    "categoryRespList": [
        "Music"
    ]
}
```


# Get all Plans

API for getting list of plans for a specific biller.This api has to be invoked if planMDM requirement is mandatory for the biller, it will return the list of plans.

Endpoint:\
Request: GET /masters/plans?billerId=HUNG00000NATJL\&category=Music\&page=0\&pagesize=10

#### Request body

<table><thead><tr><th width="236">Parent Property/Element</th><th width="231">Property/Element Name</th><th width="124">Mandatory</th><th width="148">Data Type</th><th width="340">Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>billerId</td><td>M</td><td>Alphanumeric</td><td>Fixed Length – 14</td></tr><tr><td></td><td>category</td><td>C</td><td>String</td><td>Category of the Plan</td></tr><tr><td></td><td>amountInRupees</td><td>C</td><td>String</td><td>Amount of the Plan</td></tr><tr><td></td><td>circle</td><td>C</td><td>String</td><td>Circle of the Plan</td></tr><tr><td></td><td>page</td><td>C</td><td>Numeric</td><td>Page number for API Response Pagination</td></tr><tr><td></td><td>pagesize</td><td>C</td><td>Numeric</td><td>Page Size for API Response Pagination</td></tr></tbody></table>

#### Response body

<table><thead><tr><th width="243">Parent Property/Element</th><th width="222">Property/Element Name</th><th>Mandatory</th><th>Data Type</th><th width="294">Description</th></tr></thead><tbody><tr><td>plans</td><td>planId</td><td>M</td><td>String</td><td>A unique id to identify the plans</td></tr><tr><td></td><td>description</td><td>M</td><td>String</td><td>Description of the plan</td></tr><tr><td></td><td>billerId</td><td>M</td><td>String</td><td>Biller id of fixed lenght</td></tr><tr><td></td><td>categoryType</td><td>M</td><td>String</td><td>Category type of biller</td></tr><tr><td></td><td>categorySubType</td><td>M</td><td>String</td><td>Category sub type of biller</td></tr><tr><td></td><td>amountInRupees</td><td>M</td><td>String</td><td>Amount in rupees. eg: "100"</td></tr><tr><td></td><td>effctvFrom</td><td>M</td><td>String</td><td>Effective from date</td></tr><tr><td></td><td>effctvTo</td><td>M</td><td>String</td><td>Effective to date</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>It is either “Success” or failure</td></tr><tr><td>additionalInfo</td><td>planAdditionalInfoId</td><td>M</td><td>UUID</td><td>Plan additional info id</td></tr><tr><td></td><td>tags</td><td>M</td><td>List</td><td>Will be a list of additional ifos Eg: { "tagId":"d55aa58e-bf83-4273-80ee- 7bc8e7c4f1a2", "name": "Package Duration", "value": "1 Month" }</td></tr><tr><td>[ROOT](No parent property / element)</td><td>pageNo</td><td>M</td><td>Numeric</td><td>Page number for API Response Pagination</td></tr><tr><td></td><td>pageSize</td><td>M</td><td>Numeric</td><td>Page Size for API Response Pagination</td></tr><tr><td></td><td>totalElements</td><td>M</td><td>Numeric</td><td>Total elements</td></tr><tr><td></td><td>totalPages</td><td>M</td><td>Numeric</td><td>Total number of pages</td></tr><tr><td>generalResp</td><td>statusCode</td><td>M</td><td>Numeric</td><td>200- SUCCESS Other than 200-Failure</td></tr><tr><td></td><td>status</td><td>M</td><td>String</td><td>It is either “Success” or failure</td></tr><tr><td></td><td>message</td><td>M</td><td>String</td><td>Contains the reason message for failure / success</td></tr><tr><td></td><td>remarks</td><td>C</td><td>String</td><td>Remark</td></tr></tbody></table>

#### Response body

```json
{
    "plansList": {
        "plans": [
            {
                "planId": "2862",
                "description": "Listen trending & popular Music, download songs, create your own playlist!",
                "billerId": "HUNG00000NATJL",
                "categoryType": "Music",
                "categorySubType": [],
                "amountInRupees": 99,
                "additionalInfo": {
                    "planAdditionalInfoId": "cca72e87-e994-4409-87cb-a25b2a4598ba",
                    "tags": [
                        {
                            "tagId": "d55aa58e-bf83-4273-80ee-7bc8e7c4f1a2",
                            "name": "Package Duration",
                            "value": "1 Month"
                        }
                    ]
                },
                "effctvFrom": "2021-10-26",
                "effctvTo": "2022-10-26",
                "status": "ACTIVE"
            },
            {
                "planId": "2863",
                "description": "Listen trending & popular Music, download songs, create your own playlist!",
                "billerId": "HUNG00000NATJL",
                "categoryType": "Music",
                "categorySubType": [],
                "amountInRupees": 499,
                "additionalInfo": {
                    "planAdditionalInfoId": "cd5fb9d3-afc6-488f-a354-863241d0fae3",
                    "tags": [
                        {
                            "tagId": "ccf2d727-5081-46d4-9ff1-58caae26894a",
                            "name": "Package Duration",
                            "value": "12 Months"
                        }
                    ]
                },
                "effctvFrom": "2021-10-26",
                "effctvTo": "2022-10-26",
                "status": "ACTIVE"
            }
        ]
    },
    "generalResp": {
        "statusCode": "200",
        "status": "success",
        "message": "Plans retrieved successfully",
        "remarks": ""
    },
    "pageNo": 0,
    "pageSize": 10,
    "totalElements": 2,
    "totalPages": 1
}
```


# BBPS Biller Integration

This document explains the APIs to be implemented by the billers to integrate with the BBPS system.

Billers need to integrate the following APIs and endpoints. The APIs are asynchronous, meaning once an API is triggered, BBPS BOU servers will expect an Acknowledgement from the server immediately, before receiving the Response after processing. The actual response will be sent from biller systems as a follow on HTTP request .

In this case, whenever the BBPS Protocol system sends a request to the Biller server, the Biller server needs to send the Acknowledgement. Once the request is processed at the biller server, the Biller server will send the Response back to the Protocol server aka Bank server.

<table data-full-width="true"><thead><tr><th> API</th><th> Biller Server Endpoints</th><th> Purpose</th></tr></thead><tbody><tr><td><p><br></p><p>BILL FETCH API</p></td><td><p><br></p><p>{Biller domain name}/fetch</p></td><td><p><br></p><p>To fetch the bill details from the biller</p></td></tr><tr><td><p><br></p><p>BILL PAY API</p></td><td><p><br></p><p>{Biller domain name}/payment</p></td><td><p><br></p><p>To initiate bill payment</p></td></tr><tr><td><p><br></p><p>BILL VALIDATE API</p></td><td><p><br></p><p>{Biller domain name}/validation</p></td><td><p><br></p><p>To validate the bill</p></td></tr><tr><td><p><br></p><p>STATUS 402</p></td><td><p><br></p><p>{Biller domain name}/TxnStatus402</p></td><td><p><br></p><p>To check the status of the transaction</p></td></tr></tbody></table>


# BBPS API Workflow

This diagram shows the API workflow for BBPS

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2FhGZslELbQcKz20EGySK8%2FBOU%20API%20DOCUMENT%20V2.2%20(1)_final_html_9dcacb1393952cb7.png?alt=media&amp;token=927b36cd-8ae4-4c8b-ae66-2c30f6a4031b" alt=""><figcaption><p>BBPS API Workflow</p></figcaption></figure>


# BBPS API List

The list of API that perform BBPS bill fetch

#### BILL FETCH API WORKFLOW

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2FpMBxQMGOywCBRmnteOhG%2FBOU%20API%20DOCUMENT%20V2.2%20(1)_final_html_b3f9914d00148e3.png?alt=media&amp;token=cfff7f69-aba7-4805-8f85-030eeeb5af29" alt=""><figcaption></figcaption></figure>

* NPCI sends the Bill Fetch Request to BOU.
* BOU forwards the Bill Fetch Request to Biller.
* Biller sends the Bill Fetch Request Acknowledgement to BOU, immediately upon receiving the request.
* After Biller processes the request, the resulting Bill Fetch Response is sent to BOU.
* Once BOU receives the Bill Fetch Response, an Bill Fetch Response Acknowledgement is sent to Biller.


# BILL FETCH API

Bill Fetch API is a request which will be sent from NPCI through BOU to the biller portal in order to retrieve bill related details from the biller.

#### <mark style="color:blue;">REQUEST PARAMETERS</mark>

The various parameters are explained below:

<table data-full-width="true"><thead><tr><th width="151">Parent Property/Element</th><th width="149">Property Name</th><th width="125">Mandatory</th><th width="121">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>[ROOT] (No parent property / element)</td><td>refId</td><td>M</td><td>Alphanumeric Format: Fixed Length – 35</td><td>Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages</td></tr><tr><td></td><td>billerId</td><td>M</td><td>String Fixed Length – 14</td><td>Unique identification code allocated to the Biller (by NPCI)</td></tr><tr><td></td><td>customerParams</td><td>M</td><td>Array of name value pairs</td><td>Customer bill fetch related reference field tag</td></tr><tr><td></td><td>tenantId</td><td>M</td><td>String Fixed length - 4</td><td>OU ID of the BOU</td></tr><tr><td></td><td>name</td><td>M</td><td>String Min Length – 1, Max Length – 100</td><td><p>Customer bill fetch related reference field.</p><p>Name of the reference field as</p><p>configured for the Biller</p></td></tr><tr><td></td><td>value</td><td>M</td><td>String Min Length – 1, Max Length – 100</td><td>Value of the reference field which uniquely identifies the customer for the Biller</td></tr></tbody></table>

<mark style="color:blue;">**Expected Acknowledgement Parameters**</mark>

*The various parameters are explained below:*

| Parent Property/Element                | Property Name | Mandatory | Data Type                               |                             |
| -------------------------------------- | ------------- | --------- | --------------------------------------- | --------------------------- |
| \[ROOT] (No parent property / element) | reason        | M         | String Min Length – 1, Max Length – 100 | Reason of the Status        |
|                                        | code          | M         | String Fixed Length 3                   | Response code for a request |
|                                        | status        | M         | String Min Length – 1, Max Length – 100 | Status of given request     |

<details>

<summary><mark style="color:blue;">Json Formatted Request Example</mark></summary>

{

&#x20;"refId": "String", "billerId:": "String", "customerParams": \[ { "name": "String", "value": "String" } ], "tenantId" : "String"&#x20;

}

</details>

<details>

<summary><mark style="color:blue;">Json Formatted Response Example</mark></summary>

{

&#x20;"reason":"String", "code":"Integer", "status":"String"

}

</details>


# Bill Fetch Response Endpoint

<mark style="color:blue;">**Biller server to Biller Protocol**</mark>

| Endpoint                                                              |
| --------------------------------------------------------------------- |
| <mark style="color:blue;">**Request**</mark>: POST /BillFetchResponse |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element\`                  | Property/Element Name   | Mandatory | Data Type                                                  | Description                                                                                                                                                                                                                 |
| ------------------------------------------ | ----------------------- | --------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | refId                   | M         | String                                                     | <p>Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the</p><p>Fetch and Payment messages</p> |
|                                            | errorCode               | M         | String Fixed Length – 6                                    | <p>Carries the compliance code indicating the reason for a failed</p><p>transaction – not required for a successful transaction</p>                                                                                         |
|                                            | errorDescription        | M         | String Min Length – 1, Max Length – 100                    | <p>Description of the compliance code – not required for a</p><p>successful transaction</p>                                                                                                                                 |
|                                            | status                  | M         | String Format: Successful / Failure                        | Status of the bill fetch response Successful/Failure                                                                                                                                                                        |
|                                            | billNumber              | M         | String Min Length – 1, Max Length – 100                    | Unique Id of the Bill                                                                                                                                                                                                       |
|                                            | customerName            | M         | String Min Length – 1, Max Length – 100                    | Name of the Customer                                                                                                                                                                                                        |
|                                            | amount                  | M         | String Min Length – 1, Max Length – 18                     | Total amount of the bill                                                                                                                                                                                                    |
|                                            | billPeriod              | M         | String Min Length – 1, Max Length – 50                     | Bill Period set by the biller                                                                                                                                                                                               |
|                                            | billDate                | M         | String Fixed Length – 10                                   | Bill Date set by the biller                                                                                                                                                                                                 |
|                                            | dueDate                 | M         | String Fixed Length – 10                                   | DueDate Set by the biller                                                                                                                                                                                                   |
|                                            | billerResponseTags      | M         | Array of name value pairs                                  | <p>Biller response related tag indicating the various amount options</p><p>provided by the Biller</p>                                                                                                                       |
|                                            | name                    | M         | String Min Length – 1, Max Length – 100                    | Name of the amount field assigned by the Biller                                                                                                                                                                             |
|                                            | value                   | M         | String Min Length – 1, Max Length – 100                    | Value of the amount field                                                                                                                                                                                                   |
|                                            | additionalInfo          | M         | Array of name value pairs Min Length – 1, Max Length – 100 | <p>Additional information parameters sent by the Biller supporting</p><p>fetch is copied in the payment request "as-is" – not applicable for</p><p>payment only Billers</p>                                                 |
|                                            | <p><br></p><p>Value</p> | M         | String Min Length – 1, Max Length – 100                    | Value of the field                                                                                                                                                                                                          |
|                                            | tenantId                | M         | String Fixed length - 4                                    | OU ID of the BOU                                                                                                                                                                                                            |

**Json Formatted Response Example**

```json


    {
    "refId": "String", "errorCode": "String", "errorDescription": "String", "status": "String", "billNumber": "String", "customerName": "String", "amount": "String", "billPeriod": "String", "billDate": "String", "dueDate": "String", "billerResponseTags": [
    {
    "name": "String",
    "value": "String"
    }
    ],
    "additionalInfo": [
    {
    "name": "String",
    "value": "String"
    }
    ],
    "tenantId" : "String"
    }
```

**Json Formatted Acknowledgement Example**

```json

{
"reason":"String",
"code":"Integer", "status
}
```


# BILL PAY API

Bill Pay API is a request that will be sent to the biller portal which contains payment information that is sent from NPCI through the Biller Operating Unit

<br>

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2F14ZPDAVK1KdhNFjy6AHj%2Fimage.png?alt=media&amp;token=6b2dc844-76c9-465e-bb05-f01676e03f4b" alt=""><figcaption></figcaption></figure>

* NPCI sends the Bill Payment Request to BOU.
* BOU forwards the Bill Payment Request to Biller.
* Biller sends the Bill Payment Request Acknowledgement to BOU, immediately upon receiving the request.
* After Biller processes the request, the resulting Bill Payment Response is sent to BOU.
* Once BOU receives the Bill Payment Response, a Bill Payment Response Acknowledgement is sent to Biller.
* BOU forwards the Bill Payment Response to NPCI.
* On receiving the Bill Payment Response, NPCI sends Bill Payment Status to BOU.
* Once BOU receives the Status from NPCI, they send the corresponding notification to Biller.

Bill Pay API is a request that will be sent to the biller portal which contains payment information that is sent from NPCI through the Biller Operating Unit.

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                                              | Property/Element Name | Mandatory | Data Type | Description                                                                                                                                                                                                    |
| -------------------------------------------------------------------- | --------------------- | --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><strong>\[ROOT]</strong></p><p>(No parent property / element)</p> | refId                 | M         | String    | Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages |
|                                                                      | txn                   | M         | String    | Transaction information, passed throughout the system, visible to all entities of the ecosystem                                                                                                                |
|                                                                      | txnReferenceId        | M         | String    | Transaction reference number used by the Customer for referring to a Payment transaction                                                                                                                       |
|                                                                      | ts                    | M         | String    | Transaction reference number used by the Customer for referring to a Payment transaction                                                                                                                       |
|                                                                      | type                  | M         | String    | Type of the message (Forward or Reversal Type)                                                                                                                                                                 |
|                                                                      | billerId              | M         | String    | Unique identification code allocated to the Biller.                                                                                                                                                            |
|                                                                      | customerParams        | M         | Array     | Customer bill fetch related details                                                                                                                                                                            |
|                                                                      | additionalInfo        | M         | Array     | Additional information parameters sent by the Biller supporting fetch is copied in the payment request.                                                                                                        |
|                                                                      | paymentMethod         | M         | Object    | Payment methods opted by the Customer like quick pay, split pay, OFFUSpay and paymentmode.                                                                                                                     |
|                                                                      | amount                | M         | Object    | Amount related details for the payment                                                                                                                                                                         |
|                                                                      | amount.Amt            | M         | Object    | Details of the bill payment amount made by the Customer                                                                                                                                                        |
|                                                                      | amount.SplitPayAmount | M         | String    | Amount paid through the second payment mode                                                                                                                                                                    |
|                                                                      | amount.Tag            | M         | Array     | Amount paid by the customer indicating different amount option combinations                                                                                                                                    |
|                                                                      | tenantId              | M         | String    | OU ID of the request originating BOU                                                                                                                                                                           |
|                                                                      |                       |           |           |                                                                                                                                                                                                                |
|                                                                      |                       |           |           |                                                                                                                                                                                                                |

<mark style="color:blue;">**Expected Acknowledgement Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Mandatory                               | Description                 |
| -------------------------------------- | --------------------- | --------- | --------------------------------------- | --------------------------- |
| \[ROOT] (No parent property / element) | reason                | M         | String Min Length – 1, Max Length – 100 | Reason of the Status        |
|                                        | code                  | M         | String Fixed Length 3                   | Response code for a request |
|                                        | status                | M         | String Min Length – 1, Max Length – 100 | Status of given request     |

**Json Formatted Request Example**

```json

    {
    "refId": "String", "txn": {
    "txnReferenceId": "String", "ts": "String",
    "type": "String",
    },
    "billerId:": "String", "customerParams": [
    {
    ],
    "additionalInfo": [
    {
    "name": "String",
    "value": "String"
    }
    ],
    "paymentMethod": { "quickPay": "String", "splitPay": "String", "offusPay": "String", "paymentMode": "String"
    },
    "amount": {
    "amt": {
    "amount": "String", "custConvFee": "String", "currency": "String"
    },
    "splitPayAmount": "String", "tags": [
    {
    "name": "String",
    "value": "String"
    }
    ]
    },
    "billerResponse": { "customerName": "String", "amount": "String",
    "dueDate": "String", "custConvFee": "String", "billDate": "String", "billNumber": "String", "billPeriod": "String", "tags": [
    {
    "name": "String",
    "value": "String"
    }
    ]
    },
    "tenantId" : "String"
    }
```

####

**Json Formatted Response Example**

```json

    {
    "reason":"String",
    "code":"Integer", "status":"String"
    }
```


# BillPayment Response Endpoint

### **Biller server to Biller Protocol**

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type                               |                                                                                                                                     |
| -------------------------------------- | --------------------- | --------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | errorCode             | M         | String Fixed Length – 6                 | <p>Carries the compliance code indicating the reason for a failed</p><p>transaction – not required for a successful transaction</p> |
|                                        | errorDescription      | M         | String Min Length – 1, Max Length – 100 | <p>Description of the compliance code – not required for a</p><p>successful transaction</p>                                         |
|                                        | status                | M         | String Format: Successful/Failure       | Status of the bill fetch responseSuccessful/Failure                                                                                 |
|                                        | tenantId              | M         | String Fixed length - 4                 | OU ID of the BOU                                                                                                                    |

**Json Formatted Response Example**

```json
    {
    "reason":"String",
    "code":"Integer", "status":"String"
    }
```


# Payment Notification API

### **Biller Protocol to Biller**

After Sending the Payment response to Biller Protocol, The protocol server will send the Status of the Payment to Biller. Billers need to have one endpoint with below parameters. Then protocol will send the notification to that corresponding endpoint

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                                                                                                                                                                                    |
| -------------------------------------- | --------------------- | --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | refId                 | M         | String    | Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages |
|                                        | status                | M         | String    | Status of the bill fetch response Successful/Failure                                                                                                                                                           |
|                                        | reason                | M         | String    | In case of failure reason will be provided in this field                                                                                                                                                       |
|                                        | ack                   | M         | Object    | Acknowledgement from NPCI will be in this field                                                                                                                                                                |
| ack                                    | api                   | M         | String    | PAYMENT\_RESPONSE                                                                                                                                                                                              |
|                                        | refid                 | M         | String    | Refid of the transaction                                                                                                                                                                                       |
|                                        | msgId                 | M         | String    | Message id                                                                                                                                                                                                     |
|                                        | rspCd                 | M         | String    | Response code                                                                                                                                                                                                  |
|                                        | ts                    | M         | String    | Timestamp                                                                                                                                                                                                      |
|                                        | errorMessages         | M         | Object    | Contains the error message and error code                                                                                                                                                                      |
| errorMessages                          | errorCd               | C         | String    | <p>Carries the compliance code indicating the reason for a failed</p><p>transaction – not required for a successful transaction</p>                                                                            |
|                                        | errorDtl              | C         | String    | <p>Description of the compliance code – not required for a</p><p>successful transaction</p>                                                                                                                    |

<mark style="color:blue;">**Expected Acknowledgement Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type                                            | Description                 |
| -------------------------------------- | --------------------- | --------- | ---------------------------------------------------- | --------------------------- |
| \[ROOT] (No parent property / element) | reason                | M         | <p>String</p><p>Min Length – 1, Max Length – 100</p> | Reason of the Status        |
|                                        | code                  | M         | Integer Fixed Length 3                               | Response code for a request |
|                                        | status                | M         | String Min Length – 1, Max Length – 100              | Status of given request     |

**Json Formatted Request Example**

```json
   
     {
    "refId":"String",
    "status":"String",
    "reason":"String", "ack": {
    "api":"String",
    "refId":"String",
    "msgId":"String",
    "rspCd":"String",
    "ts":"String", "errorMessages": [
    {
    "errorCd":"String", "errorDtl":"String"
    }
```

**Json Formatted Response Example**

```json
{
"reason":"String",
"code":"Integer",
"status":"String"
}
```


# Payment Status API

<mark style="color:blue;">**Biller to Biller Protocol**</mark>

Biller can make use of this API to query the status of the Payment. The API returns the sameresponse as the Payment Notification API. In case if the biller misses Payment Notification, the biller can call this API to get the payment status.&#x20;

**Method: POST**

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                                                                                                                                                                                    |
| -------------------------------------- | --------------------- | --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | refId                 | M         | String    | Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages |
|                                        | billerId              | M         | String    | Biller ID of the Biller                                                                                                                                                                                        |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type                               | Description                                                                                                            |
| ------------------------------------------ | --------------------- | --------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | refId                 | M         | String Min Length – 1, Max Length – 100 | Reason of the Status                                                                                                   |
|                                            | reason                | M         | String                                  | In case of failure reason will be provided in this field                                                               |
|                                            | status                | M         | String                                  | Status of the bill fetch response Successful/Failure                                                                   |
|                                            | ack                   | M         | Object                                  | Acknowledgement from NPCI                                                                                              |
| **ack**                                    | api                   | M         | String                                  | PAYMENT\_RESPONSE                                                                                                      |
|                                            | refId                 | M         | String                                  | Refid of the transaction                                                                                               |
|                                            | msgId                 | M         | String                                  | Message Id                                                                                                             |
|                                            | rspCd                 | M         | String                                  | Response code                                                                                                          |
|                                            | ts                    | M         | String                                  | Timestamp                                                                                                              |
|                                            | errorMessages         | M         | Object                                  | Contains the error message and error code                                                                              |
| **errorMessages**                          | errorCd               | C         | String                                  | Carries the compliance code indicating the reason for a failed transaction – not required for a successful transaction |
|                                            |                       | C         | String                                  | Description of the compliance code – not required for a successful transaction                                         |

**Json Formatted Request Example**

```json
    {
    "refId":"String", 
    "billerId":"String",
    }
```

**Json Formatted Response Example**

```json
{
"refId":"String",
"status":"String",
"reason":"String", "ack": { "api":"String",
"refId":"String",
"msgId":"String"
"rspCd":"String",
"ts":"String", "errorMessages": [
{
"errorCd":"String", "errorDtl":"String"
}
]
}
```


# BILL VALIDATE API

Bill Validate API is a request which is sent from the NPCI through BOU to the biller portal in order to check if the bill exists or not.

#### <mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type               | Description                                                                                                                                                                                                                                                         |
| -------------------------------------- | --------------------- | --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | refID                 | M         | String                  | Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages Status of the bill fetch response Successful/Failure |
|                                        | billerId              | M         | String                  | Unique identification code allocated to the Biller                                                                                                                                                                                                                  |
|                                        | customerParams        | M         | Array                   | Customer bill fetch related details                                                                                                                                                                                                                                 |
|                                        | customerParams.tags   | M         | Object                  | Contains name and value pair which describes details about the customer to the biller                                                                                                                                                                               |
|                                        | tenantId              | M         | String Fixed length - 4 | OU ID of request originating BOU                                                                                                                                                                                                                                    |

#### <mark style="color:blue;">**Expected Acknowledgement Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type                               | Description                 |
| -------------------------------------- | --------------------- | --------- | --------------------------------------- | --------------------------- |
| \[ROOT] (No parent property / element) | reason                | M         | String Min Length – 1, Max Length – 100 | Reason of the Status        |
|                                        | code                  | M         | String Fixed Length 3                   | Response code for a request |
|                                        | status                | M         | String Min Length – 1, Max Length – 100 | Status of given request     |

<mark style="color:blue;">**Json Formatted Request Example**</mark>

```json
    {
    "refId": "String",
    "billerId:": "String", "customerParams": [
    {
    "name": "String",
    "value": "String"
    }
    ],
    "tenantId" : "String"
    }
```

<mark style="color:blue;">**Json Formatted Response Example**</mark>

<pre class="language-json"><code class="lang-json">    {
<strong>    "reason":"String",
</strong>    "code":"Integer", "status":"String"
    }
</code></pre>


# BillValidation Response Endpoint

<mark style="color:blue;">**Biller server to Biller Protocol**</mark>

**Request:** POST /BillValidationResponse

<mark style="color:blue;">**Request ParametersLE**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type                               | Description                                                                                                                                                                                                    |
| ------------------------------------------ | --------------------- | --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | refId                 | M         | String                                  | Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages |
|                                            | errorCode             | C         | String                                  | <p>Carries the compliance code indicating the reason for a failed</p><p>transaction – not required for a successful transaction</p>                                                                            |
|                                            | errorDescription      | C         | String                                  | <p>Description of the compliance code – not required for a</p><p>successful transaction</p>                                                                                                                    |
|                                            | status                | M         | String Min Length – 1, Max Length – 100 | Status of given request                                                                                                                                                                                        |
|                                            | additionalInfo        | M         | Array                                   | Additional information parameters sent by the Biller supporting fetch is copied in the payment request.                                                                                                        |
|                                            | tenantId              | M         | String Fixed length - 4                 | OU ID of request originating BOU                                                                                                                                                                               |

<mark style="color:blue;">**Expected Acknowledgement Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type                               | Description                 |
| ------------------------------------------ | --------------------- | --------- | --------------------------------------- | --------------------------- |
| **\[ROOT]** (No parent property / element) | reason                | M         | String Min Length – 1, Max Length – 100 | Reason of the Status        |
|                                            | code                  | M         | String Fixed Length 3                   | Response code for a request |
|                                            | status                | M         | String Min Length – 1, Max Length – 100 | Status of given request     |

<mark style="color:blue;">**Json Formatted ResponseExample**</mark>

```json
    
    {
    "refId":"String", "errorCode": "String", "errorDescription": "String", "status": "String", "additionalInfo": [
    {
    "name": "String",
    "value": "String"
    }
    ],
    "tenantId" : "String"
    }
```

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json

    {
    "reason":"String",
    "code":"Integer", "status":"String"
    }
```


# STATUS 402 API

<figure><img src="https://3406671578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdNFAKvIjsqw6Rq8EEAEB%2Fuploads%2Femvm1kSsn1kywvpsvjy6%2Fimage.png?alt=media&amp;token=40675330-79f5-4a05-a8eb-d78c1a557089" alt=""><figcaption></figcaption></figure>

* NPCI sends the Transaction Status Request to BOU.
* BOU forwards the Transaction Status Request to Biller.
* Biller sends the Transaction Status Request Acknowledgement to BOU, immediately upon receiving the request.
* After Biller processes the request, the resulting Transaction Status Request is sent to BOU.
* Once BOU receives the Transaction Status Response, a Transaction Status Response Acknowledgement is sent to Biller.
* BOU forwards the Transaction Status Response to NPCI.
* On receiving the Transaction Status Response, NPCI sends Transaction Status Response to BOU.
* Once BOU receives the Transaction Status Response from NPCI, they send the corresponding notification to Biller.

**STATUS 402 API is used to check the status of the bill transaction**

#### <mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name        | Mandatory | Data Type | Description                                                                                                                                                                                                     |
| -------------------------------------- | ---------------------------- | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | refId                        | M         | String    | Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end- to-end chain, binding the Fetch and Payment messages |
|                                        | txn                          | M         | String    | Transaction information passed throughout the system.                                                                                                                                                           |
|                                        | txn.ts                       | M         | String    | Transmission date and time of the transaction                                                                                                                                                                   |
|                                        | txn.xchange                  | M         | String    | Identification of the type of the request – transaction status (402)                                                                                                                                            |
|                                        | txnStatusReq                 | M         | String    | Information pertaining to transaction status request                                                                                                                                                            |
|                                        | txnStatusReq.msgId           | M         | String    | Unique identification assigned by the initiating BBPOU for chaining a request and response message                                                                                                              |
|                                        | txnStatusReq.txnRefere nceId | M         | String    | Transaction reference number used by the Customer for referring to a Payment transaction                                                                                                                        |
|                                        |                              |           |           |                                                                                                                                                                                                                 |

<mark style="color:blue;">**Expected Acknowledgement Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type                               | Description                 |
| -------------------------------------- | --------------------- | --------- | --------------------------------------- | --------------------------- |
| \[ROOT] (No parent property / element) | reason                | M         | String Min Length – 1, Max Length – 100 | Reason of the Status        |
|                                        | code                  | M         | String Fixed Length 3                   | Response code for a request |
|                                        | status                | M         | String Min Length – 1, Max Length – 100 | Status of given request     |

<mark style="color:blue;">**Json Formatted Request Example**</mark>

```json
   
     {
    "refId": "String", "txn": {
    "ts": "String",
    "xchangeId": "String"
    },
    "txnStatusReq": { "msgId": "String",
    "txnReferenceId": "String"
    },
    "tenantId" : "String"
    }
```

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json
{
"reason":"String",
"code":"Integer", "status":"String"
}
```


# TxnStatusResponse Endpoint

<mark style="color:blue;">**Biller server to Biller Protocol**</mark>

| Endpoint                                                              |
| --------------------------------------------------------------------- |
| <mark style="color:blue;">**Request:**</mark> POST /TxnStatusResponse |

<mark style="color:blue;">**Request Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type               | Description                                                                                                                                                                                                    |
| ------------------------------------------ | --------------------- | --------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\[ROOT]** (No parent property / element) | refId                 | M         | String                  | Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages |
|                                            | errorCode             | C         | String                  | Error disposition                                                                                                                                                                                              |
|                                            | errorDescription      | C         | String                  | Error description                                                                                                                                                                                              |
|                                            | status                | M         | String                  | Satus f the transaction                                                                                                                                                                                        |
|                                            | tenantId              | M         | String Fixed length - 4 | Tenant id                                                                                                                                                                                                      |

<mark style="color:blue;">**Expected Acknowledgement Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                    | Property/Element Name | Mandatory | Data Type                               | Description                 |
| ------------------------------------------ | --------------------- | --------- | --------------------------------------- | --------------------------- |
| **\[ROOT]** (No parent property / element) | reason                | M         | String Min Length – 1, Max Length – 100 | Reason of the Status        |
|                                            | code                  | M         | String Fixed Length 3                   | Response code for a request |
|                                            | status                | M         | String Min Length – 1, Max Length – 100 | Status of given request     |

<mark style="color:blue;">**Json Formatted Request Example**</mark>

```json

{
"refId": "String", 
"errorCode": "String", 
"errorDescription": "String", 
"status": "String", 
"tenantId" : "String"
}
```

<mark style="color:blue;">**Json Formatted Response Example**</mark>

```json

{
"reason":"String",
"code":"Integer", "status":"String"
}
```


# Bill Fetch by bill id

#### <mark style="color:blue;">**API for fetching a Customer Bill, based on Bill id**</mark>

| Endpoint                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------- |
| **Request:&#x20;**<mark style="color:blue;">**GET /couapp/bills/fetch/byClientId?clientReqId=vgRdasd248**</mark> |

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type | Description                                                                                                                  |
| -------------------------------------- | --------------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | billId                | M         | UUID      | Bill id is unique id which is generated while initiating the bill fetch request, it can be get from the bill fetch response. |
|                                        |                       |           |           |                                                                                                                              |
|                                        |                       |           |           |                                                                                                                              |

<mark style="color:blue;">**Response Parameters**</mark>

**The various parameters are explained below:**

| Parent Property/Element                | Property/Element Name | Mandatory | Data Type    | Description                                                                                                                                    |
| -------------------------------------- | --------------------- | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| \[ROOT] (No parent property / element) | billId                | M         | UUID         | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                        | refId                 | M         | Alphanumeric | Code generated by the Biller Operating Unit that acquires the customer for every bill fetch transaction initiated and used across all messages |
|                                        | billerId              | M         | String       | Unique ID assigned to the Biller by NPCI Fixed length - 14                                                                                     |
|                                        | status                |           | String       | Status of the Operation                                                                                                                        |
|                                        | actionType            | C         | String       | Type of Bill Payment. Possible Values: BILL\_FETCH QUICKPAY BILL\_VALIDATE                                                                     |
|                                        | userId                | M         | Alphanumeric | Agent id Fixed length - 20                                                                                                                     |
|                                        | creationDate          | M         | String       | ISO 8601 Timestamp for the Bill Creation date                                                                                                  |
|                                        | modifiedDate          | M         | String       | ISO 8601 Timestamp for the Bill Modification date                                                                                              |
|                                        | createdEpochDate      | M         | Numeric      | UNIX Epoch Timestamp for the Bill Creation date                                                                                                |
|                                        | modifiedEpochDate     | M         | Numeric      | UNIX Epoch Timestamp for the Bill Modification date                                                                                            |
| billerResponse                         | billId                | M         | String       | Machine-generated Unique ID for a Bill, used internally                                                                                        |
|                                        | amount                | M         | String       | Actual bill amount inclusive of all charges                                                                                                    |
|                                        | billDate              | M         | String       | This field denotes generation date of the bill                                                                                                 |
|                                        | billNumber            | M         | String       | This field denotes the bill number of the bill fetch / payment message requested                                                               |
|                                        | billPeriod            | M         | String       | The bill period of the bill fetch / payment requested                                                                                          |
|                                        | custConvFee           | M         | String       | Customer convenience fee (CCF1) paid by the Customer Operating Unit                                                                            |
|                                        | couCustConvFee        | M         | String       | Customer convenience fee (CCF2), paid by the Customer to Customer Operating Unit                                                               |
|                                        | dueDate               | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                        | customerName          | M         | String       | This field denotes due date of the bill                                                                                                        |
|                                        | amountOption          | M         | Boolean      | A flag indicating if the Biller supports Amount Options                                                                                        |
|                                        | tagList               | M         | String       | Amount Breakup Options eg:{"name": "Additional Charges", "value": "500"}                                                                       |
| additionalInfo                         | name                  | C         | String       | Name of the Additional Info Parameter                                                                                                          |
|                                        | value                 | C         | String       | Value of the Additional Info Parameter                                                                                                         |
| customerParams                         | name                  | C         | String       | Name of the Customer Parameter attribute                                                                                                       |
|                                        | value                 | C         | String       | Value of the Customer Parameter attribute                                                                                                      |
| generalResp                            | statusCode            | M         | Numeric      | 200- SUCCESS Other than 200-Failure                                                                                                            |
|                                        | status                | M         | String       | It is either “Success” or failure                                                                                                              |
|                                        | message               | M         | String       | Contains the reason message for failure / success                                                                                              |
|                                        | remarks               | C         | String       |                                                                                                                                                |

<mark style="color:blue;">**Json Formatted Response Example (success response)**</mark>

```json
    {
    "genericResponse": { 
    "message": "",
    "remarks": "",
    "status": "Success", 
    "statusCode": "200"
    },
    "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684", 
    "refId": "BlgcYxtJCrLU18BDm8rVDHQl0Hqf9x2XONi", 
    "billerId": "DKAFEE000PUN01",
    "status": "BILL_FETCH_SUCCESS",
    "actionType": "BILL_FETCH", 
    "userId": "FE41FE42BNK519012345",
    "billerResponse": {
    "billId": "1ced7566-1add-4e01-9ed6-04cd67ac9684", 
    "amount": "1142000",
    "billDate": "2021-12-09",
    "billNumber": "59",
    "billPeriod": "NA",
    "custConvFee": "0",
    "couCustConvFee": "0",
    "dueDate": "2022-01-31",
    "customerName": "AGAMJOT TEST ", 
    "amountOption": false,
    "tagList": null
    },
    "additionalInfo": [
    {
    "additionalInfoId": null, 
    "name": "Student Name", 
    "value": "AGAMJOT TEST "
    },
    {
    "additionalInfoId": null, 
    "name": "Father Name", 
    "value": "VIRENDER SINGH"
    },
    {
    "additionalInfoId": null, 
    "name": "Class",
    "value": "STD I"
    },
    {
    "additionalInfoId": null, 
    "name": "Section",
    "value": "A"
    },
    {
    "additionalInfoId": null, 
    "name": "TUITION FEE",
    "value": "8670"
    },
    {
    "additionalInfoId": null, 
    "name": "E-CARE FEE",
    "value": "900"
    },
    {
    "additionalInfoId": null, 
    "name": "COMPUTER FEE",
    "value": "1350"
    },
    {
    "additionalInfoId": null, 
    "name": "EXAM FEE",
    "value": "500"
    }
    ],
    "customerParams": [
    {
    "name": "Admission No/Application No/GR No", 
    "value": "LF3130",
    "type": null
    },
    {
    "name": "Date Of Birth (DD-MM-YYYY)", 
    "value": null,
    "type": null
    },
    {
    "name": "Mobile No", 
    "value": null,
    "type": null
    }
    ],
    "creationDate": "2021-12-09T08:37:40.082462", 
    "modifiedDate": "2021-12-09T08:37:42.303627",
    "createdEpochDate": 1639039060,
    "modifiedEpochDate": 1639039062
    }
```

<mark style="color:blue;">**Json Formatted Response Example (failure response)**</mark>

```json
    {
    "genericResponse": { "message": "",
    "remarks": "Fetch Request not supported, only QuickPay permitted", "status": "Failure",
    "statusCode": "500"
    },
    "billId": "XXXXXXXX-7d79-4e3c-bd2d-382276669ba9",
    "refId": "xxXXXxxxxxS4VZlr9bUF2lCCzFc4823081150", "billerId": "XXXXXXXXXXXXXX",
    "status": "BILL_FETCH_FAILED",
    "actionType": "BILL_FETCH", "userId": "FE41XXXXXXXXXXXXXX",
    "billerResponse": null, "customerParams": [
    {}
    ],
    "creationDate": "2022-11-04T11:50:50+05:30", "modifiedDate": "2022-11-04T11:50:50.460818",
    "createdEpochDate": 1667542850,
    "modifiedEpochDate": 1667542850
    }
```