--- # System prepended metadata title: BBPS COU Specs to be exposed to Partners (Draft) --- **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) # 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