UPI Deeplinks Notifications

Reading time — 9 minutes

#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.

List of all payment attempt failed notification statuses

NPCI status code	NPCI status reason	Setu Description	Next Steps for merchants
U30	DEBIT HAS BEEN FAILED	The customer's debit attempt failed.	Inform the customer and ask them to try again or use a different payment method.
U09	REQAUTH TIME OUT FOR PAY	Payment authorization took too long.	Ask the customer to try again. If it continues, reach out to Setu support.
U90	REMITTER BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE	The customer's bank is taking too long to respond.	Ask the customer to contact their bank or try a different payment method.
U67	DEBIT TIMEOUT	The debit process took too long.	Ask the customer to try again or use a different payment method.
U88	CONNECTION TIMEOUT IN REQPAY CREDIT	Connection timed out during the credit request process.	Try processing the transaction again. If the issue persists, contact Setu support.
U16	RISK THRESHOLD EXCEEDED	The transaction exceeds the risk threshold.	Review the transaction for potential issues or ask the customer to use a different payment method.
U28	REMITTER BANK NOT AVAILABLE	The customer's bank is unavailable.	Inform the customer and suggest trying again later or using a different bank or payment method.
XQ	Transaction not permitted to cardholder (beneficiary)	This transaction isn't permitted for the beneficiary.	Inform the customer and suggest using a different payment method.
U85	CONNECTION TIMEOUT IN REQPAY DEBIT	Connection timed out during the debit request process.	Try processing the transaction again. If the issue persists, contact Setu support.
HS3	HSM communication error	A communication error occurred with the security module.	Retry the transaction or contact Setu support if the problem persists.
U66	DEVICE FINGERPRINT MISMATCH	Device fingerprint mismatch detected.	Inform the customer, ask them to verify their device, and retry the transaction.
U91	BENEFICIARY BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE	Beneficiary bank response time is too high.	Inform the customer and suggest they contact their bank or use a different payment method.
U03	NET DEBIT CAP IS EXCEEDED	The total debit amount exceeded the set limit.	Ask the customer to try a different payment method or contact their bank.
U54	TRANSACTION ID OR AMOUNT IN CREDENTIAL BLOCK DOES NOT MATCH WITH THAT IN REQPAY	Transaction details mismatch.	Verify the transaction details and retry, or contact Setu support if needed.
U86	REMITTER BANK THROTTLING DECLINE	The customer's bank declined due to throttling.	Inform the customer and ask them to contact their bank or use a different payment method.
XK	REQUESTED FUNCTION NOT SUPPORTED (BENEFICIARY)	The requested function is not supported for the beneficiary.	Ask the customer to try a different payment method.
U14	ENCRYPTION ERROR	An encryption error occurred in the transaction.	Retry the transaction or contact Setu support if the problem persists.
XC	INVALID TRANSACTION OR IF MEMBER IS NOT ABLE TO FIND ANY APPROPRIATE RESPONSE CODE (BENEFICIARY)	Invalid transaction or response code issue.	Contact Setu support for assistance.
U47	REQUEST DEBIT IS NOT FOUND	The debit request was not found.	Retry the transaction or contact Setu support if needed.
BT	ACQUIRER/BENEFICIARY UNAVAILABLE(TIMEOUT)	Receiver/beneficiary is not available, causing a timeout.	Inform the customer and suggest trying again later or using a different payment method.
94	Unknown Error	An unknown error occurred.	Retry the transaction or contact Setu support if the problem persists.
U53	PSP REQUEST PAY DEBIT ACKNOWLEDGEMENT NOT RECEIVED	The debit acknowledgement was not received.	Retry the transaction or contact Setu support if needed.
HS2	HSM Time out	A timeout occurred with the security module.	Retry the transaction or contact Setu support if the problem persists.
S99	Graceful decline	The transaction was stopped without a specific reason.	Ask the customer to try a different payment method or contact Setu support if needed.
U01	THE REQUEST IS DUPLICATE	Duplicate transaction request.	Confirm that the transaction was processed only once and contact Setu support if necessary.

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.

Was this page helpful?