The primary entity on the BBPS network is called a “biller”. Go to the list of products offered by Setu, and select one of the product cards under Payments > Collect BBPS.
You will see multiple Collect BBPS cards, each by a different bank provider. While the underlying bank might differ, the product experience itself remains consistent across providers. Click on one of those cards, and you should see the full profile page with more details about the product. Click on the “Create a biller” button.
Here, enter the name of the biller. This is what your customers will see and search for in the payment apps, so make sure it has no errors.
Below that, select the category this biller belongs to. Right now Setu supports only two categories, but should begin adding more soon. Now click on the “Create biller” button.
And done! The biller has been created, and you can proceed to the biller dashboard.
Step 2 — Add product configuration
Please note, any changes made to the Production configuration, will require approval from a Setu admin. Until approved, the changes will not be made live. This maker-checker process exists to ensure that there are no accidental updates to the configurations of live products.
The following explanation is done keeping in mind you’re in the Sandbox environment.
After the biller creation step, we should be on the biller profile. Here, you will see four tabs—Dashboard, which is an overview page, Configuration has all the integration details for this biller, Transactions where you can see test payments made to this biller, and Copy to Production, to copy the same config to Production later.
Click on the Configuration tab to begin setting up your biller. For a configuration to be complete, you need to—
Add at least one customer identifier, which helps the payment app identify a specific customer, in order to pull their bills from the biller system. For example, a customer’s loan number might be used to retrieve their EMI payment.
Setup URLs to tell Setu where to fetch the bills from the your system, and the auth mechanism. You can also optionally setup a callback URL to receive notifications.
Add settlement accounts, for receiving funds from Setu once customers make a successful payment. In Sandbox, these would be only mock transactions.
Add customer identifier(s)
Begin by defining at least one identifier. An app like PhonePe or GPay will ask your customer to fill in a value against this identifier—that would be unique to that customer and help them fetch their own bill.
You can add up to 4 identifiers—mark them as mandatory or not mandatory, depending on the customer experience you want to give and APIs you build to support this. If you mark all identifiers as optional, the customer can enter any one of them in order to be identified and see the relevant bill.
Attribute name is what your system recognises as the identifier to uniquely identify a customer.
Displayed as is what the user would see in an app like PhonePe or GPay.
Length denotes the minimum and maximum characters the customer can enter for the identifier.
Regex / pattern helps to check if the identifier entered by the customer is valid or not.
Once you enter these values, you can save it, and add another if you wish.
You can test customer identifiers that you configure, on Bridge. A sample app is available at the bottom-right of the screen on your configuration page, to test the integration.
Add URL endpoints
The baseURL is from where Setu can fetch bills and receipts from the biller system.
Setu will add /bills/fetch/ or /bills/fetchReceipt at the end of this URL.
The following web APIs need to be exposed by a Setu biller—
If your system cannot accept or process payment due to some use case or validation related error or business requirement or Technical error on biller server (such as server down, bad gateway, unavailable, etc), you respond with a 500 response -
"detail":"An error occured while processing this request.",
During Payment request, when your system fails to respond to Setu in 30 secs or responds with an error, the request to /fetchReceipt
will be reattempted with the same request body as the first attempt.
You must implement a Duplicate check against uniquePaymentRefID
If the uniquePaymentRefID doesn't exist for that Transaction, you must update the same and return a 200 Success response
If the same uniquePaymentRefID exists in your system for that Transaction, you can return a 200 Success response
The API should work from only whitelisted IPs (on production)
HTTPS is mandatory
Authentication mechanism is required. Supported
methods—Basic auth, JWT, OAuth.
This API immediately changes the status of an unpaid link to BILL_EXPIRED. The customer would not be able to pay using the link or the associated VPA, but even if they are somehow able to do that (due to app caching or similar issues) the amount would automatically be refunded.
platformBillID is a unique identifier for a bill on Setu's system and has to be provided to expire the bill. This is made available in the Create Payment Link API's response.
Authorization: Bearer (insert_token_here). Read about how to generate this token here.
In case the platformBillID provided is incorrect, Setu will respond with 400 bill not found error—
"detail":"Bill with ID [<platformBillID>] not found.",
If a bill has been expired, ideally, a payment by a customer would not be allowed, if verify VPA call returns an error on a payment app.
But if the verify VPA call was not made and the customer makes a payment, payment will go through but will be refunded in the settlement flow.