Notifications
Outgoing event alerts sent by Setu to partners.
Currently, there are two types of events — BILL_FULFILMENT_STATUS and BILL_SETTLEMENT_STATUS, which triggers a notification for the following events.
Bill fulfilment status
After Setu receives a callback from the bank for a particular payment, we send a PAYMENT_SUCCESSFUL or PAYMENT_FAILED or PAYMENT_ATTEMPT_FAILED notification to the merchant.
Payment successful notification
{
"partnerDetails": {
"appID": "861023031961584801",
"productInstanceID": "861023031961584801"
},
"events": [
{
"data": {
"Reason": "",
"amountPaid": {
"currencyCode": "INR",
"value": 100
},
"billerBillID": "918147077472",
"payerVpa": "saainithil97@icici",
"platformBillID": "896444053527201086",
"receiptId": "AXI7014352b4b3e4e2c9e9e62af311bf34",
"cardBIN": "XXXXXX" // this parameter will be only sent to RuPay Credit Card enabled merchants for UPI DeepLinks
"paymentMode": "Rupay Credit" // this parameter will be only sent to RuPay Credit Card enabled merchants for UPI DeepLinks
"sourceAccount": { // this is the account from which the payment was made and will only be sent for TPV-enabled merchants
"ifsc": "SETU0000012",
"name": "Noresh",
"number": "9009120939129"
},
"status": "PAYMENT_SUCCESSFUL",
"transactionId": "440542260498", //this is called as RRN in the UPI ecosystem, the customer will see this ID on UPI apps after every payment
"transactionNote": "Payment for 918147077472",
"additionalInfo" : { // same as values defined when creating the link
"UUID": "b6b6f173-8649-4b2e-9c22-f78e9195a23e",
"tags": "electricity"
},
},
"timeStamp": 1652772351636,
"type": "BILL_FULFILMENT_STATUS",
"id": "edead767-1584-4177-bd45-7ac9cd201c28"
}
]
}Payment failed notification
A payment can fail for multiple reasons as explained below:
| Reason | When does this happen? |
|---|---|
Amount validation failed | If the payment amount does not satisfy the amountExactness condition specified during payment link creation. |
Payment link has expired | If the payment was made after the expiryDate set during payment link creation. |
Missed credit alert | In rare scenarios, the bank system does not send us a credit alert in real time. But when we process all transactions in the following settlement cycle, and if delayed processing configuration is disabled for the merchant, the bill is marked as PAYMENT_FAILED and notification is sent. |
Payment address inactive | When a customer makes multiple payments using the same payment link, only the first one is honoured. For all others, a failure notification is sent. |
TPV check failed | If TPV check by Setu is enabled and account validation fails. Read more about TPV here. |
{
"partnerDetails": {
"appID": "861023031961584801",
"productInstanceID": "861023031961584801"
},
"events": [
{
"data": {
"Reason": "Amount validation failed",
"amountPaid": {
"currencyCode": "INR",
"value": 200
},
"billerBillID": "918147077472",
"payerVpa": "saainithil97@icici",
"platformBillID": "896445757228320073",
"receiptId": "AXI7014352b4b3e4e2c9e9e62af311bf34",
"status": "PAYMENT_FAILED",
"transactionId": "440542260498", //this is called as RRN in the UPI ecosystem, the customer will see this ID on UPI apps after every payment
"transactionNote": "Payment for 918147077472",
"cardBIN": "XXXXXX" // this parameter will be only sent to RuPay Credit Card enabled merchants for UPI DeepLinks
"paymentMode": "Rupay Credit" // this parameter will be only sent to RuPay Credit Card enabled merchants for UPI DeepLinks
"additionalInfo" : { // same as values defined when creating the link
"UUID": "b6b6f173-8649-4b2e-9c22-f78e9195a23e",
"tags": "electricity"
},
},
"timeStamp": 1652772555905,
"type": "BILL_FULFILMENT_STATUS",
"id": "e41d9f2a-eb66-4be0-8dec-f04806656274"
}
]
}
Payment attempt failed notification
Merchants receive notifications if a payment attempt fails due to incorrect UPI MPIN, insufficient balance, network errors, or other reasons. These failures are indicated by npciStatusCode and npciStatusReason. Full list of status codes, reasons and descriptions are provided below.
The bill created won’t expire, allowing customers to retry the payment.
{
"partnerDetails": {
"appID": "1115232834412348749",
"productInstanceID": "1115232834412348749"
},
"events": [
{
"data": {
"Reason": "",
"amountPaid": {
"currencyCode": "INR",
"value": 5000
},
"npciStatusCode": "U30",
"npciStatusReason": "DEBIT HAS BEEN FAILED",
"payeeVpa": "fortest@kaypay",
"payerVpa": "saainithil97@icici",
"paymentChannel": "UPI",
"paymentReferenceNumber": "AXI7014352b4b3e4e2c9e9e62af311bf34", // this value is identified as "receiptId" in payment successful/failed notification
"platformBillID": "1217499640581064416",
"setuDescription": "The customer's debit attempt failed.",
"status": "PAYMENT_ATTEMPT_FAILED",
"transactionDate": "2023-08-03 12:16:12",
"transactionId": "440542260498", //this is called as RRN in the UPI ecosystem, the customer will see this ID on UPI apps after every payment
},
"timeStamp": 1691045172577,
"type": "PAYMENT_ATTEMPT_FAILED",
"id": "e48bdd28-c34f-4237-bebd-ccb37f174b8a"
}
]
}Bill settlement status
Bill settled notification
A SETTLEMENT_SUCCESSFUL notification is sent to the merchant after successful payments from Setu to the merchant. This depends on the settlement frequency agreed upon between Setu and the merchant.
{
"partnerDetails": {
"appID": "string", // your unique app ID in Setu system, this is constant
"productInstanceID": "string" // your unique product instance ID in Setu system, this is constant
},
"events": [
{
"data": {
"amountSettled": {
// amount settled by Setu, in paisa
"currencyCode": "INR",
"value": 1084
},
"platformBillIds": [
// list of platform bill IDs that are processed in this settlement
405884202257482938,
...
],
"status": "SETTLEMENT_SUCCESSFUL",
"transactionId": "string" // bank utr number
},
"id": "f3b41c8f-72fc-485d-b39a-cf497787a039", // unique callback ID for every request, used for logging, debugging and tracking
"timeStamp": 1594293083984, // epoch timestamp
"type": "BILL_SETTLEMENT_STATUS"
}
]
}Refund status
Refund initiated notification
Refunds are initiated in batch, along with settlements. A batch notification is sent for all processed refunds, once our partner bank initiates refund of the amount, which can be determined by "type" : "REFUND_STATUS".
The refunds array in the notification provides the details of all transactions for which refund is initiated.
{
"partnerDetails": {
"appID": "799310436687152247",
"productInstanceID": "799310436687152247"
},
"events": [{
"data": {
"amountRefunded": {
"currencyCode": "INR",
"value": 1500
},
"refunds": {
"Initiated": [{
"amount": {
"currencyCode": "INR",
"value": 1500
},
"batchID": "cfq51rppcne0a46h51k0",
"billID": "1099309493419771390",
"reason": "Initiated by merchant",
"transactionID": "7019851224174158",
"type": "MerchantInitiated"
}],
"Pending": [{
"amount": {
"currencyCode": "INR",
"value": 3000
},
"batchID": "cfq51rppcne0a46h51k0",
"billID": "1099309092570138096",
"reason": "Initiated by merchant",
"transactionID": "8271601534619864",
"type": "MerchantInitiated"
}],
"Rejected": []
}
},
"timeStamp": 1676955892641,
"type": "REFUND_STATUS",
"id": "f042a983-d1d5-4ea6-9ef9-aa6826728839"
}]
}Refund successful notification
Setu does not have a refund successful notification yet, since this information is not available over APIs.
As next steps, you can start your internal reconciliation process or consume our Report APIs ↗ to get detailed settlement reports.