Payments
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_multiandpay_single_tpv -
bin— when thecustomerAccountTypeisCREDIT -
txnType- all intent based payments will be of typepay, the rest will becollect -
tpv— conditional, this object is populated only when the productInstanceType ispay_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 ispay_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"
}
}{
"eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae", // Unique event identifier, generated using UUID
"eventType": "payment.pending",
"eventTs": "2025-06-29T19:12:35+05:30", // Event timestamp
"resource": "payment",
"id": "01JYXYSV8B19XAWSFRPARXY35E", // Payment ID
"status": "pending",
"reason": {
"code": "payment-pending", // Reason code
"desc": "payment is pending", // Reason description
"npciErrCode": "XY", // NPCI error code
"npciErrDesc": "Transaction is pending", // NPCI error code description
"npciErrCategory": "TD", // NPCI error category (NA, TD, or BD)
"npciRespCode": "XY", // NPCI response code
"npciRespDesc": "Transaction is under process", // NPCI response code description
"setuDescription": "Transaction is being processed", // Setu description
"suggestedAction": "Please wait for final confirmation" // Suggested action for the user
},
"merchantId": "01JYXYSV8B19XAWSFRPARXY35E", // Merchant ID
"merchantReferenceId": "order_123456789", // dqr / sqr / oqr / tpv / tpv-plus / collect referenceId
"productInstanceId": "01JYXYSV8B19XAWSFRPARXY35E", // dqr / sqr / oqr / tpv / tpv-plus / collect id
"productInstanceType": "pay_single", // Type of product instance (pay_single, pay_multi, pay_single_tpv, pay_single_tpv_plus, offline_qr, collect)
"txnId": "HDF10e4ab8a07f447eea54581383d92b507", // NPCI Txn.id
"txnType": "pay", // "pay" for pay flow payments, "collect" for collect flow payments
"txnTs": "2025-06-29T19:12:35+05:30", // NPCI Txn.ts
"refId": "SU01JYXYSV8B19XAWSFRPARXY35E", // NPCI Txn.refId
"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 (populated only if productInstanceType is pay_single_tpv otherwise populated as "tpv": {"customerAccount": {}})
"tpv": {
"customerAccount": {
"ifsc": "HDFC00123",
"accountNumber": "**** **** **** 1234", // Masked payer account number
"accountName": "M*N* T*O*M*A*S" // Masked payer account name
}
},
// TPV Plus Specific Information (populated only if productInstanceType is pay_single_tpv_plus otherwise populated as "tpvPlus": {"customerAccount": {}})
"tpvPlus": {
"customerAccount": {
"payerApp": "GPay",
"payerBank": "HDFC", // First 4 chars of payer account ifsc
"payerVpa": "9650974246@ybl"
}
},
// Additional Information (only for pay_single product instance type)
"metadata": { // Optional metadata from payment record
"key1": "value1",
"key2": "value2"
}
}{
"eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae", // Unique event identifier, generated using UUID
"eventType": "payment.success",
"eventTs": "2025-06-29T19:12:35+05:30", // Event timestamp
"resource": "payment",
"id": "01JYXYSV8B19XAWSFRPARXY35E", // Payment ID
"status": "success",
"reason": {
"code": "payment-success", // Reason code
"desc": "payment is success", // Reason description
"npciErrCode": "00", // NPCI error code
"npciErrDesc": "SUCCESS", // NPCI error code description
"npciErrCategory": "NA", // NPCI error category (NA, TD, or BD)
"npciRespCode": "00", // NPCI response code
"npciRespDesc": "SUCCESS", // NPCI response code description
"setuDescription": "", // Setu description
"suggestedAction": "" // Suggested action for the user
},
"merchantId": "01JYXYSV8B19XAWSFRPARXY35E", // Merchant ID
"merchantReferenceId": "order_123456789", // dqr / sqr / oqr / tpv / tpv-plus / collect referenceId
"productInstanceId": "01JYXYSV8B19XAWSFRPARXY35E", // dqr / sqr / oqr / tpv / tpv-plus / collect id
"productInstanceType": "pay_single", // Type of product instance (pay_single, pay_multi, pay_single_tpv, pay_single_tpv_plus, offline_qr, collect)
"txnId": "HDF10e4ab8a07f447eea54581383d92b507", // NPCI Txn.id
"txnType": "pay", // "pay" for pay flow payments, "collect" for collect flow payments
"txnTs": "2025-06-29T19:12:35+05:30", // NPCI Txn.ts
"refId": "SU01JYXYSV8B19XAWSFRPARXY35E", // NPCI Txn.refId
"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 (populated only if productInstanceType is pay_single_tpv otherwise populated as "tpv": {"customerAccount": {}})
"tpv": {
"customerAccount": {
"ifsc": "HDFC00123",
"accountNumber": "**** **** **** 1234", // Masked payer account number
"accountName": "M*N* T*O*M*A*S" // Masked payer account name
}
},
// TPV Plus Specific Information (populated only if productInstanceType is pay_single_tpv_plus otherwise populated as "tpvPlus": {"customerAccount": {}})
"tpvPlus": {
"customerAccount": {
"payerApp": "GPay",
"payerBank": "HDFC", // First 4 chars of payer account ifsc
"payerVpa": "9650974246@ybl"
}
},
// Additional Information (only for pay_single product instance type)
"metadata": { // Optional metadata from payment record
"key1": "value1",
"key2": "value2"
}
}A payment.failed event is raised when a payment is rejected, the reason for rejection is populated in the reason object
{
"eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae", // Unique event identifier, generated using UUID
"eventType": "payment.failed",
"eventTs": "2025-06-29T19:12:35+05:30", // Event timestamp
"resource": "payment",
"id": "01JYXYSV8B19XAWSFRPARXY35E", // Payment ID
"status": "failed",
"reason": {
"code": "payment-failed", // Reason code
"desc": "INVALID / INCORRECT MPIN", // Reason description
"npciErrCode": "U30", // NPCI error code
"npciErrDesc": "DEBIT HAS BEEN FAILED", // NPCI error code description
"npciErrCategory": "BD", // NPCI error category (NA, TD, or BD)
"npciRespCode": "ZM", // NPCI response code
"npciRespDesc": "INVALID / INCORRECT MPIN", // NPCI response code description
"setuDescription": "", // Setu description
"suggestedAction": "" // Suggested action for the user
},
"merchantId": "01JYXYSV8B19XAWSFRPARXY35E", // Merchant ID
"merchantReferenceId": "order_123456789", // dqr / sqr / oqr / tpv / tpv-plus / collect referenceId
"productInstanceId": "01JYXYSV8B19XAWSFRPARXY35E", // dqr / sqr / oqr / tpv / tpv-plus / collect id
"productInstanceType": "pay_single", // Type of product instance (pay_single, pay_multi, pay_single_tpv, pay_single_tpv_plus, offline_qr, collect)
"txnId": "HDF10e4ab8a07f447eea54581383d92b507", // NPCI Txn.id
"txnType": "pay", // "pay" for pay flow payments, "collect" for collect flow payments
"txnTs": "2025-06-29T19:12:35+05:30", // NPCI Txn.ts
"refId": "SU01JYXYSV8B19XAWSFRPARXY35E", // NPCI Txn.refId
"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 (populated only if productInstanceType is pay_single_tpv otherwise populated as "tpv": {"customerAccount": {}})
"tpv": {
"customerAccount": {
"ifsc": "HDFC00123",
"accountNumber": "**** **** **** 1234", // Masked payer account number
"accountName": "M*N* T*O*M*A*S" // Masked payer account name
}
},
// TPV Plus Specific Information (populated only if productInstanceType is pay_single_tpv_plus otherwise populated as "tpvPlus": {"customerAccount": {}})
"tpvPlus": {
"customerAccount": {
"payerApp": "GPay",
"payerBank": "HDFC", // First 4 chars of payer account ifsc
"payerVpa": "9650974246@ybl"
}
},
// Additional Information (only for pay_single product instance type)
"metadata": { // Optional metadata from payment record
"key1": "value1",
"key2": "value2"
}
}