<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [BBPS COU Specs to be exposed to Partners (Draft)](#bbps-cou-specs-to-be-exposed-to-partners-draft)
- [General API response structure](#general-api-response-structure)
- [Generic error codes](#generic-error-codes)
- [Categories](#categories)
- [Biller list](#biller-list)
- [Biller list request](#biller-list-request)
- [Biller event webhook response](#biller-event-webhook-response)
- [Biller Details](#biller-details)
- [Biller Plans](#biller-plans)
- [Biller Plan request](#biller-plan-request)
- [Biller plan event webhook response](#biller-plan-event-webhook-response)
- [Get agent details](#get-agent-details)
- [Bill fetch](#bill-fetch)
- [Bill fetch request API](#bill-fetch-request-api)
- [Bill fetch response API](#bill-fetch-response-api)
- [Bill payment](#bill-payment)
- [Bill payment request - for fetched bills](#bill-payment-request-for-fetched-bills)
- [Bill payment request - Direct bill payments](#bill-payment-request-direct-bill-payments)
- [Payment response API](#payment-response-api)
- [Transactions report](#transactions-report)
- [Dispute](#dispute)
- [Request API - Raise dispute](#request-api-raise-dispute)
- [Response API - dispute status](#response-api-dispute-status)
- [List disputes](#list-disputes)
- [Note](#note)
- [Partner configuration](#partner-configuration)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# BBPS COU Specs to be exposed to Partners (Draft)
## General API response structure
```json
{
"success": true,
"traceId": "C3SFG0O6N88R6UI7EQ",
"data": {},
"error": {}
}
```
1. `success` will determine if the API call has failed or succeeded
2. `data` will contain the api response data if API was successful
3. `error` will contain the error code and message if API was failure
4. `traceId` can be used by Setu to Debug an API call.
Error response will look like this
```json
{
"data": null,
"success": false,
"traceId": "C3SFG0O6N88R6UI7EQ",
"error": {
"code": "validation-error",
"message": "Input is invalid"
}
}
```
## Generic error codes
1. `authentication-failure` - 401
2. `method-not-allowed` - 405
3. `not-found` - 404
4. `validation-error` - 400
## Categories
GET request.
URL: `/api/v1/bbps/categories`
Response
```json
{
"data": {
"categories": [
{
"name": "Loan Repayment",
"billerCount": 100
},
{
"name": "Water",
"billerCount": 50
},
{
"name": "DTH",
"billerCount": 10
},
{
"name": "Electricity",
"billerCount": 146
}
]
},
"success": true,
"traceId": "C3SFG0O6N88R6UI7EQ",
"error": null
}
```
## Biller list
### Biller list request
GET request. Query params supported: search, CategoryName, city, state, pincode(?), agentType, paymentMode
URL: `/api/v1/bbps/billers?search=Aditya&CategoryName=Loan+Repayment&CategoryName=Insurance`
Response
```json
{
"data": {
"billers": [
{
"id": "ADIT00000NAT0T",
"name": "Aditya Birla Sun Life Insurance",
"categoryName": "Insurance"
},
{
"id": "ADIT00000NATRA",
"name": "Aditya Birla Housing Finance Limited",
"categoryName": "Loan Repayment"
}
],
"nextPage": "/api/bbps/billers?search=Aditya&CategoryName=Loan+Repayment&CategoryName=Insurance&after=ABCC00000PTNNS&limit=100"
},
"success": true,
"traceId": "C3SFG0O6N88R6UI7EQ",
"error": null
}
```
### Biller event webhook response
The URL is passed by the partner via config at `/partner`. The event is pushed to URL in `config.eventWebhookURL` in partner config.
Response:
```json
{
"id": "C3SFG0O6N88R6UI7EQ",
"timeStamp": 1633579653,
"event": "NEWBILLER",
"data": {
"billers": [
{
"id": "ADIT00000NAT0T",
"name": "Aditya Birla Sun Life Insurance",
"categoryName": "Insurance"
},
{
"id": "ADIT00000NATRA",
"name": "Aditya Birla Housing Finance Limited",
"categoryName": "Loan Repayment"
}
]
},
}
```
## Biller Details
GET request.
URL: `/api/v1/bbps/billers/:billerId`
```json
{
"data": {
"id": "ADIT00000NAT0T",
"name": "Aditya Birla Sun Life Insurance",
"categoryName": "loan-repayment",
"exactness": "ANY/EXACT/EXACT_DOWN/EXACT_UP",
"payWithoutFetchAllowed": true,
"fetchApiType": "FETCH/VALIDATE/None",
"billerMode": "OFFLINE/ONLINE",
"supportsPendingStatus": true,
"customerParams": [
{
"paramName": "Loan Account Number",
"dataType": "ALPHANUMERIC",
"optional": false,
"minLength": 7,
"maxLength": 15,
"minValue": null,
"maxValue": null,
"visibility": true,
"regex": null,
"values": null
},
{
"paramName": "Mobile or Vehicle Registration Number",
"dataType": "ALPHANUMERIC",
"optional": false,
"minLength": 5,
"maxLength": 20,
"minValue": null,
"maxValue": null,
"visibility": true,
"regex": null,
"values": null
}
],
"paymentModes": [
{
"paymentMode": "Internet_Banking",
"maxLimit": null,
"minLimit": 1
},
{
"paymentMode": "Debit_Card",
"maxLimit": null,
"minLimit": 1
},
{
"paymentMode": "Prepaid_Card",
"maxLimit": null,
"minLimit": 1
},
{
"paymentMode": "IMPS",
"maxLimit": null,
"minLimit": 1
},
{
"paymentMode": "Cash",
"maxLimit": null,
"minLimit": null
},
{
"paymentMode": "UPI",
"maxLimit": null,
"minLimit": 1
},
{
"paymentMode": "Wallet",
"maxLimit": null,
"minLimit": 1
},
{
"paymentMode": "NEFT",
"maxLimit": 500000000,
"minLimit": 10100
},
{
"paymentMode": "AEPS",
"maxLimit": 500000000,
"minLimit": 10100
},
{
"paymentMode": "Account_Transfer",
"maxLimit": 500000000,
"minLimit": 10100
}
],
"paymentChannels": [
{
"paymentChannel": "Internet",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": true
},
{
"paymentChannel": "Internet_Banking",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": true
},
{
"paymentChannel": "Mobile",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": true
},
{
"paymentChannel": "Mobile_Banking",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": true
},
{
"paymentChannel": "POS",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": true
},
{
"paymentChannel": "MPOS",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": true
},
{
"paymentChannel": "ATM",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": true
},
{
"paymentChannel": "Bank_Branch",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": false
},
{
"paymentChannel": "Kiosk",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": false
},
{
"paymentChannel": "Agent",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": false
},
{
"paymentChannel": "Business_Correspondent",
"maxLimit": 500000000,
"minLimit": 10100,
"supportsPendingStatus": false
}
]
},
"success": true,
"error": null
}
```
## Biller Plans
### Biller Plan request
GET request.
URL: `/api/v1/bbps/billers/:billerId/plans`
```json
{
"data": {
"plans": [
{
"id": "1",
"billerId": "ZEE500000NAT01",
"categoryType": "Premium",
"categorySubType": {
"subType": "1 Month"
},
"amountInRupees": "99.0",
"planDescription": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows,\nKids, Live TV, TV shows before telecast. Watch on 5 devices at a time",
"planAdditionalInfo": [
{
"paramName": "Package Name",
"paramValue": "ZEE5 Premium 1 Month Plan"
},
{
"paramName": "Package Duration",
"paramValue": "1 Month"
}
],
"effectiveFrom": "2021-01-01",
"effectiveTo": "2021-12-31",
"status": "ACTIVE"
},
{
"Id": "2",
"billerId": "ZEE500000NAT01",
"categoryType": "Premium",
"categorySubType": {
"subType": "3 Months"
},
"amountInRupees": "299.0",
"planDescription": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows,\nKids, Live TV, TV shows before telecast. Watch on 5 devices at a time",
"planAdditionalInfo": [
{
"paramName": "Package Name",
"paramValue": "ZEE5 Premiun 3 Months Plan"
},
{
"paramName": "Package Duration",
"paramValue": "3 Months"
}
],
"effectiveFrom": "2021-01-01",
"effectiveTo": "2021-12-31",
"status": "ACTIVE"
}
]
},
"success": true,
"error": null
}
```
Error codes
1. `invalid-biller-type`: If the biller does not support plans
### Biller plan event webhook response
The URL is passed by the partner via config at `/partner`. The event is pushed to URL in `config.eventWebhookURL` in partner config.
Response:
```json
{
"id": "C3SFG0O6N88R6UI7EQ",
"timeStamp": 1633579653,
"event": "NEWPLAN",
"data": {
"plans": [
{
"id": "1",
"billerId": "ZEE500000NAT01",
"categoryType": "Premium",
"categorySubType": {
"subType": "1 Month"
},
"amountInRupees": "99.0",
"planDescription": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows,\nKids, Live TV, TV shows before telecast. Watch on 5 devices at a time",
"planAdditionalInfo": [
{
"paramName": "Package Name",
"paramValue": "ZEE5 Premium 1 Month Plan"
},
{
"paramName": "Package Duration",
"paramValue": "1 Month"
}
],
"effectiveFrom": "2021-01-01",
"effectiveTo": "2021-12-31",
"status": "ACTIVE"
},
{
"Id": "2",
"billerId": "ZEE500000NAT01",
"categoryType": "Premium",
"categorySubType": {
"subType": "3 Months"
},
"amountInRupees": "299.0",
"planDescription": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows,\nKids, Live TV, TV shows before telecast. Watch on 5 devices at a time",
"planAdditionalInfo": [
{
"paramName": "Package Name",
"paramValue": "ZEE5 Premiun 3 Months Plan"
},
{
"paramName": "Package Duration",
"paramValue": "3 Months"
}
],
"effectiveFrom": "2021-01-01",
"effectiveTo": "2021-12-31",
"status": "ACTIVE"
}
]
}
}
```
## Get agent details
GET request `/api/v1/bbps/agent/:agentid`
```json
{
"success": true,
"traceId": "C3SFG0O6N88R6UI7EQ",
"data": {
"app": "SmartPay",
"channel": "INT",
"geocode": "19.0139,72.8254",
"id": "AX01AI06512391457204",
"ifsc": "ICIC0000152",
"imei": "123456789012345",
"ip": "124.170.23.24",
"mac": "48-4D-7E-CB-DB-6F",
"mobile": "9481773011",
"os": "iOS",
"postalCode": "600001",
"terminalId": "6000011234"
},
"error": null
}
```
## Bill fetch
### Bill fetch request API
POST request `/api/v1/bbps/bills/fetch/request`
```json
{
"customer": {
"mobile": "9505987798",
"billParameters": [
{
"name": "Parameter 1",
"value": "Value 1"
},
{
"name": "Parameter 2",
"value": "Value 2"
},
{
"name": "Parameter 3",
"value": "Value 3"
}
]
},
"agent": {
"app": "SmartPay",
"channel": "INT",
"geocode": "19.0139,72.8254",
"id": "AX01AI06512391457204",
"ifsc": "ICIC0000152",
"imei": "123456789012345",
"ip": "124.170.23.24",
"mac": "48-4D-7E-CB-DB-6F",
"mobile": "9481773011",
"os": "iOS",
"postalCode": "600001",
"terminalId": "6000011234"
},
"biller": {
"id": "VODA00000MUM03"
}
}
```
Response
```json
{
"data": {
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689",
},
"success": true,
"error": null
}
```
Error codes
1. `invalid-biller-id`
2. `invalid-customer-parameters`
### Bill fetch response API
POST request: `/api/v1/bbps/bills/fetch/response`
Sync Request/Async Response
```json
{
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}
```
Sync Response/Async Request
If status is PROCESSING, retry the API after 5 seconds
```json
{
"data": {
"additionalInfo": [
{
"name": "Distributor Contact",
"value": "Cockatoojelly"
},
{
"name": "Distributor Name",
"value": "Frightstripe"
},
{
"name": "Consumer Number",
"value": "105"
},
{
"name": "Consumer Address",
"value": "Samuraipsychadelic"
}
],
"bill": { // optional - not present if biller does not support it
"amount": 301500,
"billDate": "2021-09-13",
"billNumber": "8394852342371080869",
"billPeriod": "Monthly",
"customerName": "William Miller",
"dueDate": "2021-09-26"
},
"billerRefId": "4047076513",
"exactness": "ANY",
"paymentLimits": [
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "Internet Banking",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "Debit Card",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "Credit Card",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "Prepaid Card",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "IMPS",
"supportsPendingStatus": false
},
{
"maxLimit": 4999900,
"minLimit": 100,
"paymentMode": "Cash",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "UPI",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "Wallet",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "NEFT",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "AEPS",
"supportsPendingStatus": false
},
{
"maxLimit": 20000000,
"minLimit": 100,
"paymentMode": "Account Transfer",
"supportsPendingStatus": false
}
],
"refId": "C51JQ9ED608P36RN28GGM9L63RN12591837",
"status": "Success"
},
"success": true,
"traceId": "C51JQCUD608P36RN28H0"
}
```
Error codes
1. `invalid-ref-id`
2. `fetch-not-allowed`
## Bill payment
### Bill payment request - for fetched bills
POST request `/api/v1/bbps/bills/payment/request`
```json
{
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}
```
### Bill payment request - Direct bill payments
```json
{
"customer": {
"mobile": "9505987798",
"billParameters": [
{
"name": "Parameter 1",
"value": "Value 1"
},
{
"name": "Parameter 2",
"value": "Value 2"
},
{
"name": "Parameter 3",
"value": "Value 3"
}
]
},
"agent": {
"app": "SmartPay",
"channel": "INT",
"geocode": "19.0139,72.8254",
"id": "AX01AI06512391457204",
"ifsc": "ICIC0000152",
"imei": "123456789012345",
"ip": "124.170.23.24",
"mac": "48-4D-7E-CB-DB-6F",
"mobile": "9481773011",
"os": "iOS",
"postalCode": "600001",
"terminalId": "6000011234"
},
"biller": {
"id": "VODA00000MUM03"
},
"paymentDetails": {
"mode": "Internet Banking/Debit Card/Credit Card/IMPS/Cash/UPI/Wallet/NEFT/Prepaid Card/AEPS/Account Transfer/Bharat QR/USSD",
"paymentRefId": "N2001121212344",
"amount": "100.00",
"timestamp": "2020-12-12T13:12:00+05:30"
}
}
```
Response
```json
{
"data": {
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689",
},
"success": true,
"error": null
}
```
Error codes
1. `invalid-ref-id`
2. `direct-pay-not-allowed`
3. `insufficient-funds`
### Payment response API
Post request: POST request `/api/v1/bbps/bills/payment/response`
Sync Request/Async Response
```json
{
"refId": "C51JRCED608P36RN28M0WZKDDJ412591857"
}
```
Sync Response/Async Request
If status is PROCESSING, retry the API after 30 seconds
```json
{
"data": {
"refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status": "PROCESSING/SUCCESS/FAILURE",
"billerRefId": "ABC1235",
"transactionId": "AX01122999900001",
"failureReason": {
"code": "BRR005",
"message": "Biller not accepting payments at the moment"
},
"paymentDetails": {
"mode": "Internet Banking/Debit Card/Credit Card/IMPS/Cash/UPI/Wallet/NEFT/Prepaid Card/AEPS/Account Transfer/Bharat QR/USSD",
"paymentRefId": "N2001121212344",
"amount": 10000,
"timestamp": "2020-12-12T13:12:00+05:30"
},
"billerId": "VODA00000MUM03",
},
"success": true,
"traceId": "C3SFG0O6N88R6UI7EQ",
"error": null
}
```
## Transactions report
GET API `/api/v1/bbps/transactions`
Query params
- limit
- startDate
- endDate
- billerId
```json
{
"data": {
"nextPage": "/transactions?after=AX511229z200620zPTSW&limit=2",
"transactions": [
{
"amount": 488200,
"billerId": "AX5100000OUT01",
"partnerRefId": "N2001121212344",
"refId": "C4DSI5UD608GN14HFBP01B6I8CE12292003",
"status": "Processing",
"customerMobileNumber": "9481773011",
"transactionId": "AX511229z200515z64W9"
},
{
"amount": 588400,
"billerId": "AX5100000OUT01",
"partnerRefId": "N2001121212344",
"refId": "C4DSIMED608GN14HFC4GZE809LX12292009",
"status": "Processing",
"customerMobileNumber": "9481773011",
"transactionId": "AX511229z200620zPTSW"
}
]
},
"success": true,
"traceId": "C4DSM36D608UKCRLL28G"
}
```
## Dispute
These APIs are sync
#### Request API - Raise dispute
POST request `/api/v1/bbps/bills/complaint/request`
```json
{
"transactionId": "OP011034EYE7A8Z1T7FU",
"dispute-type": "account-not-updated", // TODO: define enums for these
"description": "I have paid but account is not updated"
}
```
Response
```json
{
"data": {
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
},
"success": true,
"traceId": "C3SFG0O6N88R6UI7EQ",
"error": null
}
```
#### Response API - dispute status
POST request `/api/v1/bbps/bills/complaint/response`
Sync Request/async response
```json
{
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}
```
Sync response/ async response
```json
{
"data": {
"refId": "JPMRPBOGGDTP1EFRZVXVESQVQIS10461642",
"complaintId": "OP0121046567755",
"status": "PROCESSING/OPEN/CLOSED",
"assignedTo": "AX39",
"remarks": "Resolved in favor of customer"
},
"success": true,
"error": null
}
```
#### List disputes
GET request. Query params supported: status
URL: `/api/v1/bbps/disputes?status=Initialized&status=ASSIGNED`
Response
```json
{
"data": {
"dispute": [
{
"Assigned": "OP One Two",
"ComplaintID": "1234",
"ComplaintStatus": "INITIALIZED",
"RefID": "C4J0G9ECIE6O3FHT2PG04RM536L12371445",
"Remarks": "Remarks",
"ResponseCode": "001",
"ResponseReason": "ResponseReason",
},
{
"Assigned": "OP Two Two",
"ComplaintID": "5678",
"ComplaintStatus": "ASSIGNED",
"RefID": "C4J0GDECIE6O3FHT2PH0GOLZ5CV12371401",
"Remarks": "Remarks",
"ResponseCode": "002",
"ResponseReason": "ResponseReason",
}
],
"nextPage": "/api/bbps/billers?status=Initialized&status=ASSIGNED&after=704429425982178385&limit=100"
},
"success": true,
"traceId": "C3SFG0O6N88R6UI7EQ",
"error": null
}
```
## Note
Fetch/Pay/Dispute/Validate APIs will be made available in sync and async for the agent - If the agent wants async version, the response is sent to them over webhooks.
# Partner configuration
[partner.md](./partner.md) contains all the partner configuration details
Sign in with Wallet
Connect another wallet