#API integration

Setu BillPay allows you to register as an agent on the BBPS network and enable BBPS bill payments on your app or website. All approvals are done by Setu, our bank partner and BBPS.

This page covers how you can integrate with our APIs, develop corresponding screen flows and go live with BBPS payments.

#How to integrate

Use provided API reference to start integration. Request for a detailed API run through from Setu team, if needed. Contact us at Setu Support, should you need any help during integration.

A summary of the integration process—

1. Get your API keys
2. Provide details to set up agent
3. Start API integration
4. Share screens for NPCI approval
5. Run and submit test cases
6. Get production credentials and go live

Each of these steps are described in detail below.

#Step 1 — Get your API keys

You have to use X-PARTNER-ID in the auth header and clientID and secret as the bearer token. Get these values by reaching out to the Setu team at onboarding@setu.co.

Once you have the credentials, get the token by making a POST request to https://sandbox-coudc.setu.co/api/v1/auth/token.

{
  "clientID": "james-bond",
  "secret": "5ja0077m-55e0-47s9-9bo7-ndaa18a7c0f7"
}

You then get a token which can be used to make Authenticated requests to BillPay APIs.

{
  "expiresIn": 600,
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImxEUXBadm5xRmtTdlRaMDV6NFdjTjl0My0zY0JSVWo5di1rYnVNX2dpQkEifQ.eyJleHAiOjE2NTgzMTUwMDcsImlhdCI6MTY1ODMxMjAwNywianRpIjoiMjQzMTAwN2MtODAwNy00MDA3LWI5ZWUtZTQ4MmY2YTU3ZGViIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLWRldi5zZXR1LmNvL2F1dGgvcmVhbG1zL2NvdS1kYy1qYW1lcy1ib25kLXVhdCIsImF1ZCI6WyJqYW1lcy1ib25kIiwiYWNjb3VudCJdLCJzdWIiOiI0ZDhkMDY1Mi1kMmY2LTQyMWYtODNkMi0xYWUxYjc5ZTI1ZGIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJqYW1lcy1ib25kIiwic2Vzc2lvbl9zdGF0ZSI6ImExOThkMDA3LWViOWQtNDAwNy05NGRjLTNlMjJmYTEzYTAwNyIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiaHR0cHM6Ly9qYW1lcy1ib25kLWNvdWRjLnNldHUuY28iXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlNlY3JldF9JbnRlbGxpZ2VuY2VfU2VydmljZSJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImphbWVzLWJvbmQiOnsicm9sZXMiOlsiU2VjcmV0X0ludGVsbGlnZW5jZV9TZXJ2aWNlIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbImNvdW50ZXItdGVycm9yaXNtIiwiY291bnRlci1wcm9saWZlcmF0aW9uIl19fSwic2NvcGUiOiJiYnBzOmJvbmQiLCJjbGllbnRJZCI6ImphbWVzLWJvbmQiLCJjbGllbnRIb3N0IjoiMDA3LjAwNy4wMDcuMDA3IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtamFtZXMtYm9uZCIsImNsaWVudEFkZHJlc3MiOiIwMDcuMDA3LjAwNy4wMDcifQ.svjuDXhx71uur_XYDCYLlObPBWctPHCDn1DtAAS-xMvnAvPdgqqVIUbGXdBxePE-blJPUDWH9J4ZXj5-kvi3onGdnmQxZcckW7dmIRrfTtUMCBj_4iefqiDV1D58Fblf9hCGjVGVWL9fuatNFvV46IaVREfaUTKuSbqwzhMpSGICJWhOM1Jt1Z2pB0x3e55dgmqhjeThZrstOwsJ2GTQ5N9gFennpmqmK_HVXU-rFwJzD44EMsN5GeH6Hh8zSC35NYkagrrlOkiuPGukoOMC9xFeGKGMSML3ve8_NmPVdhM6BaOwsau4wEJ-VV4oRY7TEl7d-IXmZqCVE0vyV2GZjQ",
  "success": true,
  "traceId": "C3SFG0O6N88R6UI7EQ"
}

#Step 2 — Provide details to set up agent

To reiterate, an agent is an entity on BBPS, that enables its customers to pay any business that is listed on BBPS. For this, you need to use your details registered on BBPS, with an agent ID, to fetch bills for customers, from BBPS-listed businesses.

Share business details

Reach out to onboarding@setu.co to get a list of business details you need to provide to set up your BBPS agent ID(s).

Share callback URL

It is recommended that you set up a callback URL to receive notifications for various types of events, while using—

• APIs to fetch bill for a customer
• APIs to validate customer identifier with a biller
• APIs to for completing a bill payment
• APIs to raise disputes against a payment
• APIs to receive an automatic bill due notification

When this is enabled by you, any successful fetch, validate, payment or dispute event gets posted to your callback URL.

You may specify only one callback URL. This should be a valid URI string that starts with either https:// or http:// scheme.. For e.g., https://my-billpay-callback.com.

Setu will append the following default paths to this callback URL, to alert your on specific events—

There are also other events that are not related to the core BillPay APIs, but are updates about the businesses on BBPS.

This would include alerts on businesses that may be delisted from BBPS, or if a business updates the type of identifier they accept to fetch a customer’s bill. If you maintain a database of BBPS businesses, you may want to use such events to stay up-to-date. Find the full list of events here.

#Step 3 — Start API integration

Once you have received your API keys and agent ID for testing, you can integration with our APIs and start testing out different scenarios for fetching/paying bills or for raising disputes and managing its resolution.

#Step 4 — Share screens for NPCI approval

The screens you build as part of your app needs to conform to BBPS guidelines. You should submit a document with screenshots for the following screens—

• Category list screen, on which all BBPS categories are listed.
• Biller list screen, on which all billers under a selected category are listed.
• Customer input screen, where a customer enters identifiers specific to a selected biller, before their bill can be fetched.
• Payment confirmation screen, on which the customer confirms bill amount and proceeds with payment.
• Payment status screen, when payment is being processed and is finally either successful or failed.
• Confirmation SMS, this is the text that is sent after a payment is successful or failed.
• Bill receipt screen, through which a customer can view and download receipt for a successful transaction.
• Raise complaint screen, where a customer can raise complaint. Complaints are raised against specific transaction IDs.
• Complaint status screen, where a customer can see the latest status associated with registered complaint.

Here is a BBPS-compliant UX flow and a quick summary of BBPS guidelines to keep in mind—

• The app / website UI must contain a button for “Pay bills” with the BBPS logo shown.
• BBPS logo must be present on top right corner of all screens used by customer during search of biller or bill and also for screens relating to payment of bill.
• BBPS assured logo must always be shown on the payment sucessful and payment receipt pages. The regular BBPS logo can be removed from these.

#Step 5 — Run and submit test cases

Copy the below table in an Excel or Google sheet and run all test cases. Submit documented results in the same format. The results will verified by Setu and the bank to generate production credentials.

#Step 6 — Get production credentials and go live

You will receive production credentials once all the approvals and agreements are done. On receiving the production credentials, you can verify your integration and go live.