SetuBot
—
–
/

to search

Introducing Setu API playground Check it out ↗

Reading time — 6 minutes

Edit this page ↗

#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 - 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"
		}
Auto-fetch bills

You may also choose to enable automatic fetches for customer bills. Once you have provided the customer identifier and the business’s BBPS identifier, Setu has the information needed to fetch bill details automatically for every subsequent payment cycle. Once a bill is fetched automatically, the response is posted to the callback URL provided by you.

To enable auto-fetch for a bill, simply set the autoFetch field to true, while making Fetch bill API request to /bbps/bills/fetch/request. This flag value will be honoured once a bill fetch is done successfully.



{
+   "autoFetch": true,
    "customer": { ... },
    "agent": { ... },
    "biller": { ... }
}

Note that you would also need to tell Setu that you would like to auto fetch bills for customers, when you are setting up your agent, so that Setu can enable this feature for you.


The response stays the same, with an additional field autoFetchHash. This hash is used as an identifier for the bill fetch. It can be used to check the last auto-fetched date, whether the auto-fetch is still active or disable auto-fetch for the bill in Manage auto-fetch for bills section.



{
+   "autofetchHash": "d28ca210e0267a13fa0db18ee96a349dc4578f032e5902192af762763224204a",
    "data": { ... },
    "success": true,
    "traceId": "C51JQCUD608P36RN28H0"
}

When you set autoFetch flag to true, the response for Fetch bill will contain a autofetchHash. You can use this to—

  • Hit the /list endpoint to check if the bill autofetch is active, along with last date for bill fetch
  • Disable auto fetch by hitting the /delete endpoint

Note that you can also create an auto-fetch request for multiple bills at a time, using the /bbps/autofetches endpoint>.


Specify auto-fetch for multiple bills—A POST request to /bbps/autofetches lets you register multiple bills to be fetched automatically, at their respective payment cycles.


List auto-fetch details for multiple bills—A GET request to /bbps/autofetches returns list of bills registered for autofetch. Each entry has

  • lastFetchDate which is the date of the last bill fetch
  • isActive which specifies if bill has auto fetch enabled

Disable auto-fetch—A DELETE request to /bbps/autofetches/{autofetchHash} disable auto fetch for a bill on your app/website

#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—

#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.