#User events
A webhook can be configured to listen to users’ events and log them for analytics and re-engagement purposes.
This feature is opt-in and is configured only when a partner requests for it to be enabled. This supports use cases like getting real-time payment status and related details after bill payment is done by customer.
#Pre-requisites
You need to do the following to configure a Setu provided webhook—
- Share the webhook URL. A URL that can accept
JSON
data overPOST
. - API Key (optional)—It can also be generated by Setu, for you.
- Take steps to handle the notification
Share the webhook URL
This step requires setting up and sharing a webhook URL to Setu which is capable of receiving the transaction notifications. The URL to setup this webhook must be shared with Setu via email to billpay.support@setu.co.
Handle the notification
The notification consists of body an authentication header as well as a body/payload. The authentication header will be sent as X-BILL-WEBHOOK-API-KEY
. The value for the same shall be communicated over email.
#List of notifications
The following events are supported in the bill payment journey—
bill_fetch_success
bill_fetch_failure
bill_payment_success
bill_payment_failure
bill_collection_failure
bill_payment_refunded
dispute_raised
dispute_status_change
Below are the parameter tables and sample payloads for the listed events. Note that we may add additional parameters at a later stage. However, we will ensure backwards compatibility and no keys will be removed.
All the values in the response payload are strings
bill_fetch_success
— Notification when bill-fetch request is successful
Sample payload
{"mobileNumber": "9481773053","status": "FETCH_SUCCESS","billId": "490a8940-886e-45ed-bfd1-21dbed064373","billerId": "MAHI00000NATIC","billerName": "Mahindra Rural Housing Finance Ltd","billerCategory": "Loan-Repayment","billAmount": "101.0","dueDate": "2021-05-23","sessionId": "7f6de02a-0061-403f-bd65-47d4b5f72c87","event": "bill_fetch_success","additionalInfo": [{"name":"example","value":"ABC"}]}
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. Also called as billNumber. 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 |
dueDate | String (Date) | Due date of the bill. Format is YYYY-MM-DD. | |
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" |
bill_fetch_failure
— Notification when bill-fetch request is not successful
Sample payload
{"mobileNumber": "9481773053","status": "FETCH_FAILURE","billId": "69a1fbc0-b5d1-4cbf-ac6d-c4244e3e7e0c","billerId": "MAHI00000NATIC","billerName": "Mahindra Rural Housing Finance Ltd","billerCategory": "Loan-Repayment","sessionId": "7f6de02a-0061-403f-bd65-47d4b5f72c87","event": "bill_fetch_failure","fetchErrorCode": "ERR001","error": {"code": "ERR001","message": "Unable to get details"}}
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 |
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 |
bill_payment_success
— Notification when bill-payment request is successful
Sample payload
{"txnId": "AXO101557980","mobileNumber": "9481773053","status": "PAYMENT_SUCCESS","billId": "dfeeaf14-e43a-4196-90d0-41089e979ad5","billerId": "MAHI00000NATIC","billerName": "Mahindra Rural Housing Finance Ltd","billerCategory": "Loan-Repayment","sessionId": "7f6de02a-0061-403f-bd65-47d4b5f72c87","billAmount": "105.0","dueDate": "2021-05-23","amountPaid": "601.00","orderId": "H001234566666","event": "bill_payment_success"}
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 |
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. | 44339 |
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 |
bill_payment_failure
— Notification when bill-payment request is not successful
Sample payload
{"txnId": "AXO101557980","mobileNumber": "9481773053","status": "PAYMENT_FAILED","billId": "dfeeaf14-e43a-4196-90d0-41089e979ad5","billerId": "MAHI00000NATIC","billerName": "Mahindra Rural Housing Finance Ltd","billerCategory": "Loan-Repayment","sessionId": "7f6de02a-0061-403f-bd65-47d4b5f72c87","orderId": "Q00ABCDEFGHZOQ","billAmount": "105.0","dueDate": "2021-05-23","amountPaid": "601.00","event": "bill_payment_failure"}
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 |
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. | 44339 |
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 |
bill_collection_failure
— Notification when bill-collection from the user's account is not successful
Sample payload
{"txnId": null,"mobileNumber": "9481773053","status": "COLLECTION_FAILURE","billId": "dfeeaf14-e43a-4196-90d0-41089e979ad5","billerId": "MAHI00000NATIC","billerName": "Mahindra Rural Housing Finance Ltd","billerCategory": "Loan-Repayment","customerId": "9CBV4C9MSURWXRM54Q3DY8WEE","billAmount": "105.0","dueDate": "2021-05-23","sessionId": "7f6de02a-0061-403f-bd65-47d4b5f72c87","amountPaid": 601.00,"amount": null,"event": "bill_collection_failure"}
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 |
customerId | String | Setu's customer reference ID | 9CBV4C9MSURWXRM54Q3DY8WEE |
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. | 44339 |
sessionId | String | Unique identifier for the session used for this request | 7f6de02a-0061-403f-bd65-47d4b5f72c87 |
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 |
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.
Sample payload
{"txnId": "AXO101557980","mobileNumber": "9481773053","status": "PAYMENT_REFUNDED","billId": "dfeeaf14-e43a-4196-90d0-41089e979ad5","billerId": "MAHI00000NATIC","billerName": "Mahindra Rural Housing Finance Ltd","billerCategory": "Loan-Repayment","sessionId": "7f6de02a-0061-403f-bd65-47d4b5f72c87","billAmount": "105.0","dueDate": "2021-05-23","orderId": "H001234566666","amountPaid": "601.00","event": "bill_payment_refunded"}
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 |
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. | 44339 |
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 |
dispute_raised
— Notification when dispute/complaint is raised from the user
Sample payload
{"txnId": "AXO198058515","txnDate": "2021-06-24","issueType": "1","description": "What the customer tells the issue is","mobileNumber": "8971302465","referenceId": "ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24","status": "submitted","event": "dispute_raised"}
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. | 44371 |
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 |
dispute_status_change
— Notification when the status of a dispute has changed
Sample payload
{"txnId": "AXO198058515","txnDate": "2021-06-24","issueType": "1","description": "What the customer tells the issue is","mobileNumber": "8971302465","referenceId": "ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24","status": "closed/unknown","event": "dispute_status_change"}
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. | 44371 |
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 |
Was this page helpful?