#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
JSONdata 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_successbill_fetch_failurebill_payment_successbill_payment_failurebill_collection_failurebill_payment_refundeddispute_raiseddispute_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","paidOn": "02-01-2006 15:04:05",}
| 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 | 2022-01-03 |
| 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" |
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?