—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 7 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)

Optionally, you can also register the customer with this biller simultaneously to receive future bills as and when they are generated (See UPMS Integration Guide). If you include the mandate object in the request, a registration will be initiated for the customer with the biller.

Sample Request


{
  "customer": {
    "mobile": "9505987798",
    "customerParams": [
      {
        "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"
  },
  "mandate": {
    "registrationType": "VIEW_N_PAY",
    "billPeriod": "ASPRESENTED"
  }
}

You get a refId in the response, a unique identifier that can be further used to check the status of the bill fetch. If a UPMS registration was requested, the response will also include upmsRegistration.refId and upmsRegistration.status.

Sample Response


{
    "data": {
        "refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689",
        "upmsRegistration": {
            "status": "PENDING", 
            "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
        }
    },
    "success": true,
    "traceId": "C3SFG0O6N88R6UI7EQ" 
}

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

Sample Request


{
    "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"
					}
				],
				"bills": [
                    {
                        "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", 
				"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—

#Managing Customer Registrations

These APIs allow you to manage the lifecycle of UPMS (Unified Presentment Management Service) registrations for your customers. Refer to the UPMS Integration Guide for detailed flows and callback handling.

#Viewing Registration Details

To retrieve the current status and details of a specific, existing UPMS registration.

API Reference: GET /api/v2/upms/registrations/{upmsRegistrationRefID}

Sample Success Response


{
    "data": {
        "biller": {
        "id": "ABLP01000ANP03"
        },
        "createdAt": "2025-04-24T14:38:46.377Z",
        "customer": {
        "customerParams": [
            {
            "name": "Roll No",
            "value": "27257063"
            }
        ],
        "mobile": "9039403265",
        "name": "Priya Shukla"
        },
        "mandate": {
        "billPeriod": "ASPRESENTED",
        "billerParams": [
            {
            "name": "Low Balance Threshold",
            "value": "500"
            }
        ],
        "debitInfo": {
            "amount": 999999999,
            "currency": 356, 
            "debitDate": "10-Feb",
            "paymentMode": "Internet Banking",
            "type": "FIXED_AMOUNT"
        },
        "registrationType": "AUTO_PAY",
        "toDate": "2025-12-22"
        },
        "refId": "D054PTM52FL7R8CJPQ90GZ2ORTG51142008",
        "status": "SUCCESS",
        "updatedAt": "2025-04-24T14:38:47.389Z" 
    },
    "success": true,
    "traceId": "D055CNT3GMB863CND9LG"
}

#Updating a Registration

To modify specific details of an existing, active UPMS registration. This is an asynchronous operation; the final result is delivered via the Update UPMS Registration webhook.

API Reference: PATCH /api/v2/upms/registrations/{upmsRegistrationRefID}

Sample Request Body


{
    "mandate": {
        "toDate": "2025-12-31",
        "debitInfo": {
            "amount": 750000 
        }
    }
}

Sample Success Response


{
    "success": true,
    "traceId": "CV4PE82LTNJE9O014OE0"
}

#Cancelling a Registration

To permanently cancel an existing UPMS registration. This is an asynchronous operation; confirmation comes via the Cancel UPMS Registration webhook.

API Reference: DELETE /api/v2/upms/registrations/{upmsRegistrationRefID}

Sample Success Response


{
    "success": true,
    "traceId": "CV4PE82LTNJE9O014OE0"
}

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