—
–
/

to search

Reading time — 9 minutes

Edit this page ↗

#Lifecyle and events

#QR flow

A QR starts off its lifecycle by being in an active state when it is successfully created by a merchant using the Create TPV QR API.

  • The QR moves to a paid terminal state if a payment is accepted
  • If a payment is rejected, the payment is recorded as a failure, but nothing happens to the QR, it will remain in an active state
  • If a QR expires, it moves to a closed terminal state

StatusDescription
activeThe QR is active and the customer can still scan and make a payment
paidA payment is accepted successfully on the QR and no new payment will be accepted on the QR. The details about the successful payment can be found in the paymentDetails object
closedThe QR has expired, payments will not be accepted if a customer tries to pay

Sample paymentDetails object—

{
      "paymentDetails": {
         "customerAccountType": "SAVINGS",
         "customerVpa": "ram@icici",
         "paymentId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
         "paymentStatus": "success",
         "rrn": "124068997913",
         "txnId": "SETmBZkQOV0M7wyyP1V4PIFhRSzW5eSjmYI"
      }
}

#Payment notification flow

  • Every payment has a unique txnId
  • Every time a customer tries to make a payment, a payment.initiated notification is sent to the merchant followed by a success or failure
  • A payment.success notification will be sent only once, but payment.failure notifications can happen every time a customer tries to make a payment and fails


Payment statusDescription
payment.initiatedPayment has been attempted by a customer — when a customer tries to make a payment by scanning a QR or clicking on a shortlink and entering his UPI pin on a Payer PSP
payment.pendingPayment is currently being processed — when the UPI network takes a while to process the payment or when the beneficiary bank is down
payment.successPayment has been successfully completed — when all participants involved in the payment have acknowledged and accepted the payment
payment.failedPayment could not be processed, you can find more about why it failed with the reason object in the notification payload

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


Sample TPV object in the notification payload—

{
   //  TPV attributes
   “tpv”: {
      "customerAccount": {
         "ifsc": "HDFC00123",
         "accountNumber": "**** **** **** 1234",
         "accountName": "M*N* T*O*M*A*S",
      }
   }
}

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"
  }
}