the customer’s identifier (mobile number in this case)
+the business’s identifier (BBPS ID for Vodafone, in this case)
++ 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 UAT credentials and start integration +2. Share screens for NPCI approval +3. Run and submit test cases +4. Submit details for agent ID creation +5. Get production credentials and go live + +Each of these steps are described in detail below. + ++ 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. + +| Category | +Category Code | +
|---|---|
| Electricity | +1 | +
| Mobile Postpaid | +6 | +
| Landline Postpaid | +7 | +
| Water | +8 | +
| DTH | +9 | +
| Loan Repayment | +12 | +
| Fastag | +13 | +
| Parameter | +Description | +
|---|---|
+ limit
+ |
+ + Limit the number of billers you get in the result, to use for pagination + | +
+ offset
+ |
+ + Number of values to skip. Value = (Offset x Limit). The resulting list + will show from (Offset x Limit) till (Offset x Limit) + Limit + | +
+ search
+ |
+ Search biller code or name by passing a string value. | +
| Biller Id | +Category Code | +
|---|---|
| NDMC00000DEL02 | +1 | +
| BESCOM000KAR01 | +1 | +
| AVVNL0000RAJ01 | +1 | +
| APDCL0000ASM01 | +1 | +
| SBPDCL000BHI01 | +1 | +
| SKPR00000SIK01 | +1 | +
| WESCO0000ODI01 | +1 | +
| BSESRAJPLDEL01 | +1 | +
| JIO000000NAT01 | +6 | +
| ATLLI0000NAT02 | +7 | +
| JALK00000UTP0P | +8 | +
| AIRT00000NAT87 | +9 | +
| MAHI00000NATIC | +12 | +
| AXIS00000NATSN | +13 | +
| Biller Id | +Category Code | +
|---|---|
| NDMC00000DEL02 | +1 | +
| BESCOM000KAR01 | +1 | +
| AVVNL0000RAJ01 | +1 | +
| APDCL0000ASM01 | +1 | +
| SBPDCL000BHI01 | +1 | +
| SKPR00000SIK01 | +1 | +
| WESCO0000ODI01 | +1 | +
| BSESRAJPLDEL01 | +1 | +
| JIO000000NAT01 | +6 | +
| ATLLI0000NAT02 | +7 | +
| JALK00000UTP0P | +8 | +
| AIRT00000NAT87 | +9 | +
| MAHI00000NATIC | +12 | +
| AXIS00000NATSN | +13 | +
bill-fetch-request and get-fetched-bill
+ make-payment and get-payment-status
+ 
+ bill-fetch-request or get-fetched-bill{" "}
+ has an error/timeout and does NOT give a response, you can retry the APIs
+ with the same request body.
+make-payment API errors/timeouts and does NOT give a
+ response you can pass the context used in the{" "}
+ make-payment request body as the context for{" "}
+ get-payment-status request.
+ make-payment API multiple times for the same
+ context as it may result in your account getting debitted multiple times.
++ 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. + +fetch/validate/payment/
+ dispute events too.{" "}
+
+ The URL may be relative (a path, without a host) or absolute (starting with
+ a scheme)
+
+ .
+ callbackURL value. If you specify a URL, it will simply override
+ the callback URL value for that particular event.
++ 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. + ++ This gives an overview of how the payment flow works when a customer + is interacting with Setu’s pre-built screen solution— +
+
+ unload function can also be used for dismissing the webview and redirecting a user back to your native app once a bill payment journey is completed (i.e. payment is successful) via a CTA from the Setu webview. Please let our team know if you would like to enable this use case for your app.
+unload function can also be used for dismissing the webview and redirecting a user back to your native app once a bill payment journey is completed (i.e. payment is successful) via a CTA from the Setu webview. Please let our team know if you would like to enable this use case for your app.
+onDownloadStartRequest (or a similar function as per your webview plugin). Our sample below uses the flutter_downloader and path_provider plugins for downloading and saving transaction receipts. Please follow the plugin specific documentation for implementation. Make sure you have added necessary permissions in your AndroidManifest.xml and Info.plist files for downloading and saving files.
+React native Please bear with us for a while.
+unload function can also be used for dismissing the webview and redirecting a user back to your native app once a bill payment journey is completed (i.e. payment is successful) via a CTA from the Setu webview. Please let our team know if you would like to enable this use case for your app.
+ViewController relating to the payment flow, will
+ need to set the property isModalInPresentation as{" "}
+ true—to prevent user from scrolling back to the previous screen
+ while the transfer of control is in process.
+/COU_WL_custom_payment_web_(1).gif)
+
+unload function can also be used for dismissing the webview and redirecting a user back to your native app once a bill payment journey is completed (i.e. payment is successful) via a CTA from the Setu webview. Please let our team know if you would like to enable this use case for your app.
++ Use provided{" "} + + API reference + {" "} + to start integration. Request for a detailed API run through from Setu team, + if needed. Contact us at billpay.support@setu.co, should you + need any help during integration. +
+ +A summary of the integration process— + +1. Get UAT credentials and start integration +2. Share screens for NPCI approval +3. Run and submit test cases +4. Submit details for agent ID creation +5. Get production credentials and go live + +Each of these steps are described in detail below. + ++ 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. + +unload function can also be used for dismissing the webview and redirecting a user back to your native app once a bill payment journey is completed (i.e. payment is successful) via a CTA from the Setu webview. Please let our team know if you would like to enable this use case for your app.
+unload function can also be used for dismissing the webview and redirecting a user back to your native app once a bill payment journey is completed (i.e. payment is successful) via a CTA from the Setu webview. Please let our team know if you would like to enable this use case for your app.
+bill_fetch_success — Notification when bill-fetch
+ request is successful
+ | Parameter | +Data Type | +Description | +Example | +
| mobileNumber | +String (Number) | +Mobile number used to generate the bill-fetch request | +
+ 9481773053
+ |
+
| status | +String | +Status of the bill-fetch request | +
+ FETCH_SUCCESS
+ |
+
| billId | +String | ++ Unique identifier for the bill. It is generated by the + biller. Not applicable where + there is no bill. + | +
+ 490a8940-886e-45ed-bfd1-21dbed064373
+ |
+
| billNumber | +String | ++ Unique identifier for the bill as sent by NPCI. Not applicable where + there is no bill. + | +
+ 490a8940-886e-45ed-bfd1-21dbed064373
+ |
+
| billerId | +String | ++ Unique identifier (Biller ID in BBPS) allocated to the + Biller + | +
+ MAHI00000NATIC
+ |
+
| billerName | +String | +Name of the biller as registered with BBPS | +
+ Mahindra Rural Housing Finance Ltd
+ |
+
| billerCategory | +String | ++ Category of the biller as registered with BBPS. There are + more than 25 biller categories. + | +
+
+ Loan-Repayment; Electricity; Landline-Postpaid etc.
+
+ |
+
| billAmount | +String (Number) | +Amount of the bill in rupees (INR) | +
+ 101.55
+ |
+
| billDate | +String (Date) | +Date of bill generation. Format is YYYY-MM-DD. | +
+ 2023-05-02
+ |
+
| dueDate | +String (Date) | +Due date of the bill. Format is YYYY-MM-DD. | +
+ 2023-05-20
+ |
+
| customerId | +String | +Unique identifier for the customerId used for this session | +
+ cust@1234
+ |
+
| sessionId | +String | +Unique identifier for the session used for this request | +
+ 7f6de02a-0061-403f-bd65-47d4b5f72c87
+ |
+
| event | +String | +Name of the event to identify this user event | +
+ bill_fetch_success
+ |
+
| additionalInfo | +String | ++ Additional info available to Agent Institutions basis the + additional info passed by the biller. + | +
+ name:"example" value:"ABC"
+ |
+
| refId | +String | +BBPS Reference ID | +
+ CMA0I65RCU2I32C3L0H0KNYQYAG40021831
+ |
+
| billDetails | +Array of Objects | ++ Contains details of bills fetched. For 'SINGLE' billers, this array will have 0 or 1 element. For 'LIST' billers, it may contain multiple elements. + | +
+ [{"billAmount": "101.0", "billNumber": "6657801290", "billDate": "2024-03-01", "customerName": "Ram Charan", "dueDate": "2024-03-20"}]
+ |
+
+ Note: The billDetails array is now the primary source for bill details, replacing individual bill fields (billAmount, billNumber, billDate, customerName, dueDate). These individual fields are deprecated and will be removed in future versions. Always use billDetails for accessing bill information.
+ |
+ |||
bill_fetch_failure — Notification when bill-fetch
+ request is not successful
+ | Parameter | +Data Type | +Description | +Example | +
| mobileNumber | +String (Number) | +Mobile number used to generate the bill-fetch request | +
+ 9481773053
+ |
+
| status | +String | +Status of the bill-fetch request | +
+ FETCH_FAILURE
+ |
+
| billId | +String | ++ Unique identifier for the bill. It is generated by the + biller. Also called as billNumber. Not applicable where + there is no bill. + | +
+ 69a1fbc0-b5d1-4cbf-ac6d-c4244e3e7e0c
+ |
+
| billerId | +String | ++ Unique identifier (Biller ID in BBPS) allocated to the + Biller + | +
+ MAHI00000NATIC
+ |
+
| billerName | +String | +Name of the biller as registered with BBPS | +
+ Mahindra Rural Housing Finance Ltd
+ |
+
| billerCategory | +String | ++ Category of the biller as registered with BBPS. There are + more than 25 biller categories. + | +
+ Loan-Repayment
+ |
+
| sessionId | +String | +Unique identifier for the session used for this request | +
+ 7f6de02a-0061-403f-bd65-47d4b5f72c87
+ |
+
| customerId | +String | +Unique identifier for the customerId used for this session | +
+ cust@1234
+ |
+
| event | +String | +Name of the event to identify this user event | +
+ bill_fetch_failure
+ |
+
| fetchErrorCode | +String | +Error codes for the failure | +
+ ERR001
+ |
+
| error | ++ | Error array containing details of the error | ++ |
| code | +String | +Error code | +
+ ERR001
+ |
+
| message | +String | +Error description | +
+ Unable to get details
+ |
+
| refId | +String | +BBPS Reference ID | +
+ CMA0I65RCU2I32C3L0H0KNYQYAG40021831
+ |
+
bill_payment_success — Notification when
+ bill-payment request is successful
+ | Parameter | +Data Type | +Description | +Example | +
| txnId | +String | ++ Unique identifier for the transaction generated by COU, here + Setu. Also known as BBPS transaction ID. + | +
+ AXO101557980
+ |
+
| mobileNumber | +String (Number) | +Mobile number used to generate the bill-payment request | +
+ 9481773053
+ |
+
| status | +String | +Status of the bill-payment request | +
+ PAYMENT_SUCCESS
+ |
+
| billId | +String | ++ Unique identifier for the bill. It is generated by the + biller. Also called as billNumber. Not applicable where + there is no bill. + | +
+ dfeeaf14-e43a-4196-90d0-41089e979ad5
+ |
+
| billerId | +String | ++ Unique identifier (Biller ID in BBPS) allocated to the + Biller + | +
+ MAHI00000NATIC
+ |
+
| billerName | +String | +Name of the biller as registered with BBPS | +
+ Mahindra Rural Housing Finance Ltd
+ |
+
| billerCategory | +String | ++ Category of the biller as registered with BBPS. There are + more than 25 biller categories. + | +
+ Loan-Repayment
+ |
+
| sessionId | +String | +Unique identifier for the session used for this request | +
+ 7f6de02a-0061-403f-bd65-47d4b5f72c87
+ |
+
| customerId | +String | +Unique identifier for the customerId used for this session | +
+ cust@1234
+ |
+
| billAmount | +String (Number) | +Amount of the bill in rupees (INR) | +
+ 601.75
+ |
+
| dueDate | +String (Date) | +Due date of the bill. Format is YYYY-MM-DD. | +
+ 2023-05-02
+ |
+
| amountPaid | +String (Number) | ++ Amount paid by the user in rupees (INR). This is especially + applicable for billers where there is no billAmount, eg. + Fastag + | +
+ 601.75
+ |
+
| orderId | +String | ++ Unique identifier for a payment request. Generated by Setu. + | +
+ H001234566666
+ |
+
| event | +String | +Name of the event to identify this user event | +
+ bill_payment_success
+ |
+
| paidOn | +String (DateTime) | +Time of transaction | +
+ 02-01-2006 15:04:05
+ |
+
| refId | +String | +BBPS Reference ID | +
+ CMA0I65RCU2I32C3L0H0KNYQYAG40021831
+ |
+
| billDetails | +Array of Objects | ++ Contains details of bills paid. For 'SINGLE' billers, this array will have 0 or 1 element. For 'LIST' billers, it may contain multiple elements. + | +
+ [{"billAmount": "101.0", "billNumber": "6657801290", "billDate": "2024-03-01", "customerName": "Ram Charan", "dueDate": "2024-03-20"}]
+ |
+
+ Note: The billDetails array is now the primary source for bill details, replacing individual bill fields (billAmount, billNumber, billDate, customerName, dueDate). These individual fields are deprecated and will be removed in future versions. Always use billDetails for accessing bill information.
+ |
+ |||
bill_payment_failure — Notification when
+ bill-payment request is not successful
+ | Parameter | +Data Type | +Description | +Example | +
| txnId | +String | ++ Unique identifier for the transaction generated by COU, here + Setu. Also known as BBPS transaction ID. + | +
+ AX0101557980
+ |
+
| mobileNumber | +String (Number) | +Mobile number used to generate the bill-payment request | +
+ 9481773053
+ |
+
| status | +String | +Status of the bill-payment request | +
+ PAYMENT_FAILED
+ |
+
| billId | +String | ++ Unique identifier for the bill. It is generated by the + biller. Also called as billNumber. Not applicable where + there is no bill. + | +
+ dfeeaf14-e43a-4196-90d0-41089e979ad5
+ |
+
| billerId | +String | ++ Unique identifier (Biller ID in BBPS) allocated to the + Biller + | +
+ MAHI00000NATIC
+ |
+
| billerName | +String | +Name of the biller as registered with BBPS | +
+ Mahindra Rural Housing Finance Ltd
+ |
+
| billerCategory | +String | ++ Category of the biller as registered with BBPS. There are + more than 25 biller categories. + | +
+ Loan-Repayment
+ |
+
| sessionId | +String | +Unique identifier for the session used for this request | +
+ 7f6de02a-0061-403f-bd65-47d4b5f72c87
+ |
+
| customerId | +String | +Unique identifier for the customerId used for this session | +
+ cust@1234
+ |
+
| orderId | +String | ++ Unique identifier for a payment request. Generated by Setu. + | +
+ Q00ABCDEFGHZOQ
+ |
+
| billAmount | +String (Number) | +Amount of the bill in rupees (INR) | +
+ 101.55
+ |
+
| dueDate | +String (Date) | +Due date of the bill. Format is YYYY-MM-DD. | +
+ 2023-05-02
+ |
+
| amountPaid | +String (Number) | ++ Amount paid by the user in rupees (INR). This is applicable + for billers where there is no bill generated, eg. Fastag + | +
+ 601.75
+ |
+
| event | +String | +Name of the event to identify this user event | +
+ bill_payment_failure
+ |
+
| refId | +String | +BBPS Reference ID | +
+ CMA0I65RCU2I32C3L0H0KNYQYAG40021831
+ |
+
bill_collection_failure — Notification when
+ bill-collection from the user's account is not successful
+ | Parameter | +Data Type | +Description | +Example | +
| txnId | ++ | + Unique identifier for the transaction generated by COU. Not + generated here because Setu does not post the bill-payment + request to BBPS. + | +
+ null
+ |
+
| mobileNumber | +String (Number) | +Mobile number used to generate the bill-payment request | +
+ 9481773053
+ |
+
| status | +String | +Status of the bill-payment request | +
+ COLLECTION_FAILURE
+ |
+
| billId | +String | ++ Unique identifier for the bill. It is generated by the + biller. Also called as billNumber. Not applicable where + there is no bill. + | +
+ dfeeaf14-e43a-4196-90d0-41089e979ad5
+ |
+
| billerId | +String | ++ Unique identifier (Biller ID in BBPS) allocated to the + Biller + | +
+ MAHI00000NATIC
+ |
+
| billerName | +String | +Name of the biller as registered with BBPS | +
+ Mahindra Rural Housing Finance Ltd
+ |
+
| billerCategory | +String | ++ Category of the biller as registered with BBPS. There are + more than 25 biller categories. + | +
+ Loan-Repayment
+ |
+
| billAmount | +String (Number) | +Amount of the bill in rupees (INR) | +
+ 101.55
+ |
+
| dueDate | +String (Date) | +Due date of the bill. Format is YYYY-MM-DD. | +
+ 2023-05-02
+ |
+
| sessionId | +String | +Unique identifier for the session used for this request | +
+ 7f6de02a-0061-403f-bd65-47d4b5f72c87
+ |
+
| customerId | +String | +Unique identifier for the customerId used for this session | +
+ cust@1234
+ |
+
| amountPaid | +String (Number) | ++ Amount paid by the user in rupees (INR). This is applicable + for billers where there is no bill generated, eg. Fastag. + Will be null for this event. + | +
+ 601.75
+ |
+
| amount | ++ | + |
+ null
+ |
+
| event | +String | +Name of the event to identify this user event | +
+ bill_collection_failure
+ |
+
| refId | +String | +BBPS Reference ID | +
+ CMA0I65RCU2I32C3L0H0KNYQYAG40021831
+ |
+
bill_payment_refunded — Notification when
+ bill-payment has to be refunded. This event is invoked when
+ bill-payment request to BBPS has failed, after collection of
+ funds from the user.
+ | Parameter | +Data Type | +Description | +Example | +
| txnId | +String | +Unique identifier for the transaction generated by COU. | +
+ AX0101557980
+ |
+
| mobileNumber | +String (Number) | +Mobile number used to generate the bill-payment request | +
+ 9481773053
+ |
+
| status | +String | +Status of the bill-payment request | +
+ PAYMENT_REFUNDED
+ |
+
| billId | +String | ++ Unique identifier for the bill. It is generated by the + biller. Also called as billNumber + | +
+ dfeeaf14-e43a-4196-90d0-41089e979ad5
+ |
+
| billerId | +String | ++ Unique identifier (Biller ID in BBPS) allocated to the + Biller + | +
+ MAHI00000NATIC
+ |
+
| billerName | +String | +Name of the biller as registered with BBPS | +
+ Mahindra Rural Housing Finance Ltd
+ |
+
| billerCategory | +String | ++ Category of the biller as registered with BBPS. There are + more than 25 biller categories. + | +
+ Loan-Repayment
+ |
+
| sessionId | +String | +Unique identifier for the session used for this request | +
+ 7f6de02a-0061-403f-bd65-47d4b5f72c87
+ |
+
| customerId | +String | +Unique identifier for the customerId used for this session | +
+ cust@1234
+ |
+
| billAmount | +String (Number) | +Amount of the bill in rupees (INR) | +
+ 601.75
+ |
+
| dueDate | +String (Date) | +Due date of the bill. Format is YYYY-MM-DD. | +
+ 2023-05-02
+ |
+
| orderId | +String | ++ Unique identifier for a payment request. Generated by Setu. + | +
+ H001234566666
+ |
+
| amountPaid | +String (Number) | ++ Amount paid by the user in rupees (INR). This is applicable + for billers where there is no bill generated, eg. Fastag + | +
+ 601.75
+ |
+
| event | +String | +Status to identify this user event | +
+ bill_payment_refunded
+ |
+
| refId | +String | +BBPS Reference ID | +
+ CMA0I65RCU2I32C3L0H0KNYQYAG40021831
+ |
+
dispute_raised — Notification when
+ dispute/complaint is raised from the user
+ | Parameter | +Data Type | +Description | +Example | +
| txnId | +String | ++ Unique identifier for the transaction generated by COU, here + Setu. Also known as BBPS transaction ID. + | +
+ AX0198058515
+ |
+
| txnDate | +String (Date) | +Date of the transaction. Format is YYYY-MM-DD. | +
+ 2021-06-24
+ |
+
| issueType | +String | ++ |
+ 1
+ |
+
| description | +String | +Description as entered by the user. | +
+ Message entered by the user
+ |
+
| mobileNumber | +String (Number) | +Mobile number used to generate the dispute | +
+ 8971302465
+ |
+
| referenceId | +String | ++ Unique identifer for the dispute raised, generated by Setu. + | +
+ ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24
+ |
+
| status | +String | +Status of the dispute | +
+ submitted
+ |
+
| event | +String | +Status to identify this user event | +
+ dispute_raised
+ |
+
| refId | +String | +BBPS Reference ID | +
+ CMA0I65RCU2I32C3L0H0KNYQYAG40021831
+ |
+
dispute_status_change — Notification when the
+ status of a dispute has changed
+ | Parameter | +Data Type | +Description | +Example | +
| txnId | +String | ++ Unique identifier for the transaction generated by COU, here + Setu. Also known as BBPS transaction ID. + | +
+ AX0198058515
+ |
+
| txnDate | +String (Date) | +Date of the transaction. Format is YYYY-MM-DD. | +
+ 2023-05-02
+ |
+
| issueType | +String | ++ |
+ 1
+ |
+
| description | +String | +Description as entered by the user. | +
+ Message entered by the user
+ |
+
| mobileNumber | +String (Number) | +Mobile number used to generate the dispute | +
+ 8971302465
+ |
+
| referenceId | +String | ++ Unique identifer for the dispute raised, generated by Setu. + | +
+ ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24
+ |
+
| status | +String | +Status of the dispute | +
+ closed/unknown
+ |
+
| event | +String | +Status to identify this user event | +
+ dispute_status_change
+ |
+
| refId | +String | +BBPS Reference ID | +
+ CMA0I65RCU2I32C3L0H0KNYQYAG40021831
+ |
+