BBPS Billpay webhooks

Reading time — 14 minutes

#Webhooks/Notifications

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 over POST.
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

{
    "mobileNumber": "9481773053",
    "status": "FETCH_SUCCESS",
    "billId": "490a8940-886e-45ed-bfd1-21dbed064373",
    "billNumber": "6657801290", // if available
    "billerId": "MAHI00000NATIC",
    "billerName": "Mahindra Rural Housing Finance Ltd",
    "billerCategory": "Loan-Repayment",
    "billAmount": "101.0",
    "billDate":"2024-03-01"   // if available
    "dueDate": "2024-03-20",  // if available
    "customerName": "Ram Charan", // if available
    "customerId": "cust@1234" // if available
    "sessionId": "1272707270496486911",
    "event": "bill_fetch_success",
    "refId": "CMA0I65RCU2I32C3L0H0KNYQYAG40021831",
    "additionalInfo": [
        {
            "name": "example",
            "value": "ABC"
        }
    ],
    "billDetails": [
        {
            "billAmount": "101.0",
            "billNumber": "6657801290",
            "billDate": "2024-03-01",
            "customerName": "Ram Charan",
            "dueDate": "2024-03-20"
        }
    ]
}

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	`1272707270496486911`
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

{
        "mobileNumber": "9481773053",
        "status": "FETCH_FAILURE",
        "billerId": "MAHI00000NATIC",
        "billerName": "Mahindra Rural Housing Finance Ltd",
        "billerCategory": "Loan-Repayment",
        "sessionId": "1272707270496486911",
        "customerId": "cust@1234", // if available
        "event": "bill_fetch_failure",
        "refId": "CMA0I65RCU2I32C3L0H0KNYQYAG40021831",
        "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`
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	`1272707270496486911`
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

{
    "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": "1272707270496486911",
    "customerId": "cust@1234" // if available
    "billAmount": "105.0",
    "dueDate": "2021-05-23", // if available
    "amountPaid": "601.00",
    "orderId": "H001234566666",
    "event": "bill_payment_success",
    "refId": "CMA0I65RCU2I32C3L0H0KNYQYAG40021831",
    "paidOn": "02-01-2006 15:04:05",
    "billDetails": [
        {
            "billAmount": "101.0",
            "billNumber": "6657801290",
            "billDate": "2024-03-01",
            "customerName": "Ram Charan",
            "dueDate": "2024-03-20"
        }
    ]
}

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	`1272707270496486911`
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

{
    "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": "1272707270496486911",
    "customerId": "cust@1234", // if available
    "orderId": "Q00ABCDEFGHZOQ",
    "amountPaid": "601.00",
    "event": "bill_payment_failure",
    "refId": "CMA0I65RCU2I32C3L0H0KNYQYAG40021831",
    "error": {
        "code": "insufficient-balance",
        "message": "Insufficient balance in the bank account. Please ensure sufficient funds are available before retrying.",
        "type": "FUND_TRANSFER"
    }
}

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	`1272707270496486911`
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`
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`
error	Object	Error details for failure of bill payment	`[{"code": "insufficient-balance", "message": "66578Insufficient balance in the bank account. Please ensure sufficient funds are available before retrying.01290", "type": "FUND_TRANSFER"]`

bill_collection_failure — Notification when bill-collection from the user's account is not successful

{
    "mobileNumber": "9481773053",
    "status": "COLLECTION_FAILURE",
    "billerId": "MAHI00000NATIC",
    "billerName": "Mahindra Rural Housing Finance Ltd",
    "billerCategory": "Loan-Repayment",
    "sessionId": "1272707270496486911",
    "customerId": "cust@1234", // if available
    "amountPaid": 601.0,
    "event": "bill_collection_failure",
    "refId": "CMA0I65RCU2I32C3L0H0KNYQYAG40021831"
}

Parameter	Data Type	Description	Example
mobileNumber	String (Number)	Mobile number used to generate the bill-payment request	`9481773053`
status	String	Status of the bill-payment request	`COLLECTION_FAILURE`
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	`1272707270496486911`
customerId	String	Unique identifier for the customerId used for this session (if available)	`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`
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.

{
    "txnId": "AXO101557980",
    "mobileNumber": "9481773053",
    "status": "PAYMENT_REFUNDED",
    "billerId": "MAHI00000NATIC",
    "billerName": "Mahindra Rural Housing Finance Ltd",
    "billerCategory": "Loan-Repayment",
    "sessionId": "1272707270496486911",
    "customerId": "cust@1234", // if available
    "orderId": "H001234566666",
    "amountPaid": "601.00",
    "event": "bill_payment_refunded",
    "refId": "CMA0I65RCU2I32C3L0H0KNYQYAG40021831"
}

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`
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	`1272707270496486911`
customerId	String	Unique identifier for the customerId used for this session (if available)	`cust@1234`
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

{
    "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",
    "refId": "CMA0I65RCU2I32C3L0H0KNYQYAG40021831"
}

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

{
    "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",
    "refId": "CMA0I65RCU2I32C3L0H0KNYQYAG40021831"
}

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`

Was this page helpful?

—

–

#Webhooks/Notifications

#Pre-requisites

Share the webhook URL

Handle the notification

#List of notifications