Reading time — 4 minutes

#Quickstart—API integration

Below is a quick summary of the APIs you need to start integrating with for testing out the BBPS COU product.

The primary actions you will take as an agent of the BBPS system, is to let your customers fetch bills from any business listed on BBPS, and let them pay said business.

For this, the core fetch, pay and dispute APIs are asynchronous. Each API has a request endpoint and a response endpoint. The request endpoint registers the call and the response endpoint is used to retrieve the status of the registered call.

#Fetch bill

The Fetch bill API with endpoint /bbps/bills/fetch/request is used to get bill details for a customer. You need to pass the details of the customer and also the business they want to fetch their bill from.

For e.g., if your customer wants to pay their phone bill for Vodafone Postpaid, you will need to provide—

the customer’s identifier (mobile number in this case)
the business’s identifier (BBPS ID for Vodafone, in this case)

Detailed sample request body

		{
		"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"
		}
		}
		

You get a refId in the response, a unique identifier that can be further used to check the status of the bill fetch.

{
    "data": {
        "refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689",
    },
    "success": true,
    "error": null
}

You may also use the /bbps/bills/fetch/response endpoint with above refId to check status of the bill fetch—

{
    "refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}

In the response you either get the bill details, or “Processing” status if the bill fetch is still in progress.

Sample response

		{
			"data": {
				"additionalInfo": [
					{
						"name": "Distributor Contact",
						"value": "Cockatoojelly"
					},
					{
						"name": "Distributor Name",
						"value": "Frightstripe"
					},
					{
						"name": "Consumer Number",
						"value": "105"
					},
					{
						"name": "Consumer Address",
						"value": "Samuraipsychadelic"
					}
				],
				"bill": { // optional - selective present for SINGLE billers
					"amount": 300000,
					"billDate": "2021-09-13",
					"billNumber": "8394852342371080869",
					"billPeriod": "Monthly",
					"customerName": "William Miller",
					"dueDate": "2021-09-26",
					"paymentOptions": [
						{
							"name": "3 month EMI",
							"amount": 900000,
							"minAmount": 300000,
							"maxAmount": 1500000,
							"amountMultiple": 10000
						},
						{
							"name": "6 month EMI",
							"amount": 1800000,
							"minAmount": 600000,
							"maxAmount": 3000000,
							"amountMultiple": 10000
						}
					]
				},
				"billerResponseType": "SINGLE",
				"billerSelectionType": null,
				"billerRefId": "4047076513",
				"exactness": "Exact",
				"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"
		}
		

#Pay bill

The Pay bill API is used to send details of a payment done by a user on your app/website to Setu. Setu uses this information to confirm payment with the biller.

#Raise dispute

The Raise Dispute API is used to Raise a compliant for a payment done by a user on your app/website to Setu. Setu uses this information and raises a compliant on the BBPS Platform.

#List data in bulk

For your convenience, Setu also provides actions to list data in bulk, that can come in handy for keeping your systems up to date with the latest data. The following APIs are available—

List categories—lists all categories on BBPS.
List billers—lists all billers on BBPS.
List disputes—lists all the raised disputes using the Dispute API.
List fetched Bills—lists all the fetched bills that were fetched using Fetch API.
List paid bills—lists all the bill pay transactions paid using Pay API.

#Check server health

The health check API tells you the health of the Setu BillPay server.

Aside from the above, there are other APIs which are also vital for a complete customer payment experience. See the full API reference for more details.