Payout Fintech APIs are organised around REST. Our API has predictable resource-oriented URLs, accepts JSON requests and returns JSON responses, and uses standard HTTP response codes and verbs.
Pass API content-type for all the requests in the header.
Following options are optional but highly recommended.
Client(Biller) has to develop the API based on the specification, Payout Fintech consumes the API. To secure the API from unauthorised access, we recommend using any of the following authentication methods in your API. We support bearer authentication and basic authentication. We recommend developing your API with any one of the authentication methods and share the credentials with us so our system will invoke your API with the authentication method and credentials.
Our system will invoke your API from the predefined IPs, for security reasons we recommend whitelisting our IPs.
Fetch API will be invoked by our system, when a customer fetches from third-party PSP Apps or Bank Apps. It is a real time API call, your API should respond in a timely manner to fulfil the Fetch API request. If your system does not respond with the expected response within the agreed timeframe our system will consider it as failure. Due to the nature of the API call retry is not possible. For the API call your system has to return invoice dues as per the below specification.
| Parameters | Datatype | Required | Description |
|---|---|---|---|
| key | string | Y | Unique identifier to fetch the invoices Ex: Consumer No., Customer ID |
| billerId | string | Y | BBPS Biller ID assigned to the client by the BBPS while onboarding. |
| Parameters | Datatype | Description |
|---|---|---|
| key | string | Unique identifier to fetch the invoices Ex: Consumer No., Customer ID |
| billerId | string | BBPS Biller ID assigned to the client by the BBPS while onboarding. |
| customerName | string | Name of the customer |
| invoices | array | It contains the list of unpaid invoices for the customer. refer to the below table for fields. |
Invoices Array
| invoiceNo | string | Invoice number |
| date | string | invoice date / bill date |
| dueDate | string | Due date for the invoice |
| amount | string | Amount due for the invoice |
{
"key" : "C700845",
"billerId" : "BBPSBILLERIDXXX"
}
{
"code" : "SUCCESS",
"data" : {
"key" : "C700845",
"billerId" : "BBPSBILLERIDXXX",
"customerName" : "Rama Enterprises",
"invoices" : [
{
"invoiceNo" : "INV2022083017",
"date" : "17-Aug-2022",
"dueDate" : "10-Sep-2022",
"amount" : 5900
},
{
"invoiceNo" : "INV2022083056",
"date" : "17-Aug-2022",
"dueDate" : "10-Sep-2022",
"amount" : 11800
},
{
"invoiceNo" : "INV2022083088",
"date" : "17-Aug-2022",
"dueDate" : "10-Sep-2022",
"amount" : 29500
},
{
"invoiceNo" : "INV2022083094",
"date" : "17-Aug-2022",
"dueDate" : "10-Sep-2022",
"amount" : 42000
}
]
}
}
{
"code" : "NOT_FOUND"
}
{
"code" : "NO_DUES"
}
{
"code" : "FAILURE"
}
After the successful customer payment, our system will invoke your Payment Notification API. It means a customer has made the payment which was acknowledged by the BBPS system. Our system will send the payment confirmation details including invoice numbers so your API has to update the payment information and acknowledge as per the below specification.
| Parameters | Datatype | Description |
|---|---|---|
| key | string | Unique identifier to fetch the invoices Ex: Consumer No., Customer ID |
| bbpsRefNo | string | bbpsRefNo is an unique reference number issued by BBPS system for the transaction |
| paysharpReferenceNo | string | Unique Payment reference number issued by Payout Fintech for the transaction |
| customerName | string | Name of the customer |
| mode | string | Mode for the transaction |
| amount | number | Total amount for the transaction |
| fee | number | Returns the fee for the transaction |
| tax | number | Returns the tax for the fee for the transaction |
| totalFee | number | Returns the sum of fee and tax for the transaction |
| netAmount | number | Actual amount after deducting fee and tax. |
| transactionDate | datetime | Transaction date |
| attemptCount | number | Number of times retried |
| invoices | Array | It contains the list of invoices, refer to the below table. |
Invoices Array
| invoiceNo | string | For the invoice number the amount paid |
| amount | number | Amount paid for the invoice |
| paid | boolean | Payment status of the invoice |
| Parameters | Datatype | Description |
|---|---|---|
| message | string | Message for the transaction |
| code | string | code for the transaction |
This request will be provided by Payout Fintech
{
"key" : "7358435990",
"bbpsRefNo" : "ab99464D2",
"paysharpReferenceNo" : "pbb_df10bf9dm0e0ldBnlBe446",
"customerName" : "Rama Enterprises",
"mode" : "UPI",
"amount" : 5900,
"fee" : 12.00,
"tax" : 2.16,
"totalFee" : 14.16,
"netAmount" : 5885.84,
"transactionDate" : "2022-11-24T13:25:29.250Z",
"invoices" : [
{
"invoiceNo" : "INV2022083017",
"amount" : 5900,
"paid" : true
}
],
"attemptCount" : 1
}
{
."message" : "success",
"code" : 200
}
This request will be provided by Payout Fintech.
{
"key" : "7358435990",
"bbpsRefNo" : "ab99464D2",
"paysharpReferenceNo" : "pbb_df10bf9dm0e0ldBnlBe446",
"customerName" : "Rama Enterprises",
"mode" : "Internet Banking",
"amount" : 17700,
"fee" : 18.00,
"tax" : 3.24,
"totalFee" : 21.24,
"netAmount" : 17678.76,
"transactionDate" : "2022-11-24T13:25:29.250Z",
"invoices" : [
{
"invoiceNo" : "INV2022083017",
"amount" : 5900,
"paid" : true
},
{
"invoiceNo" : "INV2022083056",
"amount" : 11800,
"paid" : true
}
],
"attemptCount" : 1
}
{
."message" : "success",
"code" : 200
}