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.

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.

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

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

---

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 a payment with the biller.

FX Retail (Val Add + Mandate flows): When the payment is being initiated as part of the FX mandate journey, include paymentType: "MANDATE_AND_PAY" in the request body of the Pay bill API. The rest of the Pay bill payload remains the same. See the FX Retail integration guide for details.

---

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.
  FX Retail fields (present on every biller):

  • valAddFlag (boolean) — indicates if value-added services are enabled for the biller.
  • valAddCustParams (ValAddCustParamSpec[]) — customer parameters required for value-added service flows. Each entry includes requestType (e.g. MANDATE_AND_PAY for FX Retail mandate+pay) and the corresponding customerParams specs.
  • mandateRequirement (string) — mandate requirement for the biller (e.g. MANDATORY). For FX Retail billers, use this to decide whether mandate+pay flow is required.
  • pseudoBiller (boolean) — indicates if the biller is a pseudo biller.

  See the FX Retail integration guide for details.

• List plans—lists all plans for billers on BBPS.

• List disputes—lists all the raised disputes using the Dispute API.

---

Managing Customer Registrations via UPMS

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}

---

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}

---

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}

---

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.