SetuBot

Introducing Setu API playground Check it out ↗

#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_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"
}
]
}

ParameterData TypeDescriptionExample
mobileNumberString (Number)Mobile number used to generate the bill-fetch request9481773053
statusStringStatus of the bill-fetch requestFETCH_SUCCESS
billIdStringUnique 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
billerIdStringUnique identifier (Biller ID in BBPS) allocated to the BillerMAHI00000NATIC
billerNameStringName of the biller as registered with BBPSMahindra Rural Housing Finance Ltd
billerCategoryStringCategory of the biller as registered with BBPS. There are more than 25 biller categories.Loan-Repayment; Electricity; Landline-Postpaid etc.
billAmountString (Number)Amount of the bill in rupees (INR)101.55
dueDateString (Date)Due date of the bill. Format is YYYY-MM-DD.
sessionIdStringUnique identifier for the session used for this request7f6de02a-0061-403f-bd65-47d4b5f72c87
eventStringName of the event to identify this user eventbill_fetch_success
additionalInfoStringAdditional 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"
}
}

ParameterData TypeDescriptionExample
mobileNumberString (Number)Mobile number used to generate the bill-fetch request9481773053
statusStringStatus of the bill-fetch requestFETCH_FAILURE
billIdStringUnique 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
billerIdStringUnique identifier (Biller ID in BBPS) allocated to the BillerMAHI00000NATIC
billerNameStringName of the biller as registered with BBPSMahindra Rural Housing Finance Ltd
billerCategoryStringCategory of the biller as registered with BBPS. There are more than 25 biller categories.Loan-Repayment
sessionIdStringUnique identifier for the session used for this request7f6de02a-0061-403f-bd65-47d4b5f72c87
eventStringName of the event to identify this user eventbill_fetch_failure
fetchErrorCodeStringError codes for the failureERR001
errorError array containing details of the error
codeStringError codeERR001
messageStringError descriptionUnable 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"
}

ParameterData TypeDescriptionExample
txnIdStringUnique identifier for the transaction generated by COU, here Setu. Also known as BBPS transaction ID.AXO101557980
mobileNumberString (Number)Mobile number used to generate the bill-payment request9481773053
statusStringStatus of the bill-payment requestPAYMENT_SUCCESS
billIdStringUnique 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
billerIdStringUnique identifier (Biller ID in BBPS) allocated to the BillerMAHI00000NATIC
billerNameStringName of the biller as registered with BBPSMahindra Rural Housing Finance Ltd
billerCategoryStringCategory of the biller as registered with BBPS. There are more than 25 biller categories.Loan-Repayment
sessionIdStringUnique identifier for the session used for this request7f6de02a-0061-403f-bd65-47d4b5f72c87
billAmountString (Number)Amount of the bill in rupees (INR)601.75
dueDateString (Date)Due date of the bill. Format is YYYY-MM-DD.44339
amountPaidString (Number)Amount paid by the user in rupees (INR). This is especially applicable for billers where there is no billAmount, eg. Fastag601.75
orderIdStringUnique identifier for a payment request. Generated by Setu.H001234566666
eventStringName of the event to identify this user eventbill_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"
}

ParameterData TypeDescriptionExample
txnIdStringUnique identifier for the transaction generated by COU, here Setu. Also known as BBPS transaction ID.AX0101557980
mobileNumberString (Number)Mobile number used to generate the bill-payment request9481773053
statusStringStatus of the bill-payment requestPAYMENT_FAILED
billIdStringUnique 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
billerIdStringUnique identifier (Biller ID in BBPS) allocated to the BillerMAHI00000NATIC
billerNameStringName of the biller as registered with BBPSMahindra Rural Housing Finance Ltd
billerCategoryStringCategory of the biller as registered with BBPS. There are more than 25 biller categories.Loan-Repayment
sessionIdStringUnique identifier for the session used for this request7f6de02a-0061-403f-bd65-47d4b5f72c87
orderIdStringUnique identifier for a payment request. Generated by Setu.Q00ABCDEFGHZOQ
billAmountString (Number)Amount of the bill in rupees (INR)101.55
dueDateString (Date)Due date of the bill. Format is YYYY-MM-DD.44339
amountPaidString (Number)Amount paid by the user in rupees (INR). This is applicable for billers where there is no bill generated, eg. Fastag601.75
eventStringName of the event to identify this user eventbill_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"
}

ParameterData TypeDescriptionExample
txnIdUnique identifier for the transaction generated by COU. Not generated here because Setu does not post the bill-payment request to BBPS.null
mobileNumberString (Number)Mobile number used to generate the bill-payment request9481773053
statusStringStatus of the bill-payment requestCOLLECTION_FAILURE
billIdStringUnique 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
billerIdStringUnique identifier (Biller ID in BBPS) allocated to the BillerMAHI00000NATIC
billerNameStringName of the biller as registered with BBPSMahindra Rural Housing Finance Ltd
billerCategoryStringCategory of the biller as registered with BBPS. There are more than 25 biller categories.Loan-Repayment
customerIdStringSetu's customer reference ID9CBV4C9MSURWXRM54Q3DY8WEE
billAmountString (Number)Amount of the bill in rupees (INR)101.55
dueDateString (Date)Due date of the bill. Format is YYYY-MM-DD.44339
sessionIdStringUnique identifier for the session used for this request7f6de02a-0061-403f-bd65-47d4b5f72c87
amountPaidString (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
amountnull
eventStringName of the event to identify this user eventbill_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"
}

ParameterData TypeDescriptionExample
txnIdStringUnique identifier for the transaction generated by COU.AX0101557980
mobileNumberString (Number)Mobile number used to generate the bill-payment request9481773053
statusStringStatus of the bill-payment requestPAYMENT_REFUNDED
billIdStringUnique identifier for the bill. It is generated by the biller. Also called as billNumberdfeeaf14-e43a-4196-90d0-41089e979ad5
billerIdStringUnique identifier (Biller ID in BBPS) allocated to the BillerMAHI00000NATIC
billerNameStringName of the biller as registered with BBPSMahindra Rural Housing Finance Ltd
billerCategoryStringCategory of the biller as registered with BBPS. There are more than 25 biller categories.Loan-Repayment
sessionIdStringUnique identifier for the session used for this request7f6de02a-0061-403f-bd65-47d4b5f72c87
billAmountString (Number)Amount of the bill in rupees (INR)601.75
dueDateString (Date)Due date of the bill. Format is YYYY-MM-DD.44339
orderIdStringUnique identifier for a payment request. Generated by Setu.H001234566666
amountPaidString (Number)Amount paid by the user in rupees (INR). This is applicable for billers where there is no bill generated, eg. Fastag601.75
eventStringStatus to identify this user eventbill_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"
}

ParameterData TypeDescriptionExample
txnIdStringUnique identifier for the transaction generated by COU, here Setu. Also known as BBPS transaction ID.AX0198058515
txnDateString (Date)Date of the transaction. Format is YYYY-MM-DD.44371
issueTypeString1
descriptionStringDescription as entered by the user.Message entered by the user
mobileNumberString (Number)Mobile number used to generate the dispute8971302465
referenceIdStringUnique identifer for the dispute raised, generated by Setu.ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24
statusStringStatus of the disputesubmitted
eventStringStatus to identify this user eventdispute_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"
}

ParameterData TypeDescriptionExample
txnIdStringUnique identifier for the transaction generated by COU, here Setu. Also known as BBPS transaction ID.AX0198058515
txnDateString (Date)Date of the transaction. Format is YYYY-MM-DD.44371
issueTypeString1
descriptionStringDescription as entered by the user.Message entered by the user
mobileNumberString (Number)Mobile number used to generate the dispute8971302465
referenceIdStringUnique identifer for the dispute raised, generated by Setu.ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24
statusStringStatus of the disputeclosed/unknown
eventStringStatus to identify this user eventdispute_status_change

Was this page helpful?