UPI Setu - Notifications and alerts - Payments

Reading time — 9 minutes

#Payment notification

Most of the products on our platform end up creating a payment event when a customer interacts with it from a Payer PSP. We provide consistent and transparent payment statuses for a merchant, to be able to track the life-cycle of a payment request. These statuses are shown in the diagram below.

Any UPI Setu product relies on creating and presenting payment request to a customer. Setu's UPI Setu stack provides consistent and transparent payment statuses for a merchant, to be able to track the life-cycle of a payment request. These statuses are shown in the diagram below.

Payment statuses	Description
`payment.initiated`	Payment has been attempted by a customer
`payment.pending`	Payment is currently being processed by UPI Setu
`payment.success`	Payment has been successfully completed
`payment.failed`	Payment could not be processed

The order of the payment notifications cannot be guaranteed. For example, a client might receive a payment.success notification before a payment.initiated is sent.

For the same payment transaction the txnId value will always be the same, you can use this to correlate different events to a unique payment

Payment events are common for products like sqr, dqr, tpv and collect, any product which is intended to collect funds from a customer will result in a payment event on customer interaction.

While most of the attributes in the notificiation payload are the same for all products, there are some that are conditional.

productInstanceType - depends on the product type, allowed values — collect, pay_single, pay_multi and pay_single_tpv
bin — when the customerAccountType is CREDIT
txnType - all intent based payments will be of type pay, the rest will be collect
tpv — conditional, this object is populated only when the productInstanceType is pay_single_tpv

{
   // Payment context
   "productInstanceType": "pay_single_tpv",
   //  TPV attributes
   "tpv": {
      "customerAccount": {
         "ifsc": "HDFC00123",
         "accountNumber": "**** **** **** 1234",
         "accountName": "M*N* T*O*M*A*S",
      }
   }
}

tpvPlus — conditional, this object is populated only when the productInstanceType is pay_single_tpv_plus

{
   // Payment context
   "productInstanceType": "pay_single_tpv_plus",
   //  TPV attributes
   "tpvPlus": {
      "customerAccount": {
         "payerApp": "GPay",
         "payerBank": "HDFC",
         "payerVpa": "customer@upi"
      }
   }
}

A payment.initiated event is raised when a customer tries to make a payment to an intent link or QR either by clicking on a shortlink or by scanning the QR code

{
  "eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae",                                              // Unique event identifier, generated using UUID
  "eventType": "payment.initiated",                     
  "eventTs": "2025-06-29T19:12:35+05:30",                                                         // Event timestamp
  "resource": "payment",                               
  "id": "01JYXYSV8B19XAWSFRPARXY35E",                                                             // Payment ID
  "status": "initiated",                              
  "merchantId": "01JYXYSV8B19XAWSFRPARXY35E",                                                     // Merchant ID
  "merchantReferenceId": "order_123456789",                                                       // dqr / sqr / oqr / tpv / tpv-plus referenceId
  "productInstanceId": "01JYXYSV8B19XAWSFRPARXY35E",                                              // dqr / sqr / oqr / tpv / tpv-plus id
  "productInstanceType": "pay_single",                                                            // Type of product instance (pay_single, pay_multi, pay_single_tpv, pay_single_tpv_plus, offline_qr)
  "txnId": "HDF10e4ab8a07f447eea54581383d92b507",                                                 // NPCI Txn.id
  "txnType": "pay",                                   
  "txnTs": "2025-06-29T19:12:35+05:30",                                                           // NPCI Txn.ts
  "refId": "SU01JYXYSV8B19XAWSFRPARXY35E",                                                        // NPCI Txn.refId; intent link tr param value
  "rrn": "123456789012",                                                                          // NPCI Txn.custRef
  "amount": 1000,                                                                                 // Transaction amount in paise
  "currency": "INR",                                                                              // Transaction currency
  "customerVpa": "9650974246@ybl",                                                                // Payer VPA address
  "merchantVpa": "setu.merchant@pineaxis",                                                        // Payee VPA address
  "customerAccountType": "SAVINGS",                                                               // Type of payer account (SAVINGS, CURRENT, CREDIT, etc.)
  "txnNote": "Payment for order 123456789",                                                       // NPCI Txn.note
  "bin": "123456",                                                                                // First 6 digits of card number, Populated only when the customerAccountType is CREDIT
  // TPV Specific Information (only present if productInstanceType is pay_single_tpv)
  "tpv": {
    "customerAccount": {}                                                                         // Empty object for payment.initiated notifications
  },
  // TPV Plus Specific Information (only present if productInstanceType is pay_single_tpv_plus)
  "tpvPlus": {
    "customerAccount": {}                                                                         // Empty object for payment.initiated notifications
  },
  // Information about payment failure reason
  "reason": {},                                                                                   // Empty object for payment.initiated notifications
  // Additional Information
  "metadata": {                                                                                   // Optional metadata, only present for pay_single product instance type
    "key1": "value1",
    "key2": "value2"
  }
}

—

–

#Payment notification