—
–

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—

  1. Share the webhook URL. A URL that can accept JSON data over POST.
  2. API Key (optional)—It can also be generated by Setu, for you.
  3. 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_payment_refunded
  • dispute_raised
  • dispute_status_change
Sample payloads#

All the values in the response payload are strings

Here are some 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.

 

bill_fetch_success

{
  "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"
    }
  ]
}

 

bill_fetch_failure

{
  "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"
  }
}

 

bill_payment_success

{
  "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"
}

 

bill_payment_failure

{
  "txnId": "AXO101557980",
  "mobileNumber": "9481773053",
  "status": "PAYMENT_FAILURE",
  "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_failure"
}

 

bill_payment_refunded

{
  "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"
}

 

dispute_raised

{
  "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"
}

 

dispute_status_change

{
  "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"
}

Was this page helpful?