Setu
UPI Setu

Create

API Playground

Notifications and alerts for creation of mandate

The first step to start utilising mandates is to create a mandate. Here is a quick view of how the status moves from mandate.initiated to mandate.live or mandate.rejected—

This indicates that a mandate creation request has been initiated by a customer by clicking on the intent link / scanning the qr code and entering the mPIN. The following param values indicate this state—

  • operation will be create

  • eventType will be mandate_operation.create.initiated

  • status will be initiated

{
  "eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae",                                              // Unique event identifier, generated using UUID
  "eventType": "mandate_operation.create.initiated",  
  "eventTs": "2025-06-29T19:12:35+05:30",                                                         // Event timestamp
  "resource": "mandate_operation",                    
  "id": "01JYXYSV8B19XAWSFRPARXY35E",                                                             // Mandate ID
  "operation": "create",                              
  "status": "initiated",                              
  // Empty reason object for initiated status
  "reason": {},
  // Merchant and Reference Information
  "merchantId": "01JYXYSV8B19XAWSFRPARXY35E",                                                     // Merchant ID
  "merchantReferenceId": "mandate_123456789",                                                     // mandate referenceId
  "txnId": "HDF10e4ab8a07f447eea54581383d92b507",                                                 // NPCI Txn.id
  "txnTs": "2025-06-29T19:12:35+05:30",                                                           // NPCI Txn.ts
  "rrn": "123456789012",                                                                          // NPCI Txn.custRef
  "umn": "c27f5fc30d344e9594fce0afa34f8859@mypsp",                                                // Unique Mandate Number from NPCI
  "mandateId": "01JYXYSV8B19XAWSFRPARXY35E",                                                      // Same as id field
  // Amount Information
  "amount": 1000,                                                                                 // Mandate amount in paise
  "amountLimit": 1000,                                                                            // Mandate amount in paise
  "endDate": "20032025",                                                                          // Mandate end date in DDMMYYYY format
  // TPV Specific Information (empty object for non-TPV mandates)
  "customerAccount": {                                                                            // Payer account details, empty object for non-TPV mandates
    "encryptedAccountNumber": "fhDBZ4fC2RtNyiW5rB-jDnzzs_YpYwPGerwAwDTd",                         // Encrypted account number
    "hashedAccountNumber": "d49f354241572a261cfd3a7f210f1919c79fa9993b29e34c5511c3ecefc9f3ea",    // Hashed account number
    "maskedAccountNumber": "**** **** **** 1234",                                                 // Masked account number
    "hashedAccountName": "cceaad99aec841a21be45f02368d0d332493a5a62fdda20c3d85bfb617ef176b",      // Hashed account name
    "maskedAccountName": "M*N* T*O*M*A*S",                                                        // Masked account name
    "encryptedAccountName": "n6MUSW1KXaSWh1E38zxhh1amv9E6rPmZ2Tw=",                               // Encrypted account name
    "ifsc": "HDFC0000053",                                                                        // IFSC code
    "accountType": "SAVINGS"                                                                      // Account type
  }
}

In addition to mandate_operation.create.initiated, a mandate.initiated event is also sent if no validation errors are encountered on UPI Setu during mandate creation after the customer has entered the mPIN post clicking on the intent link / scanning the qr code.

{
  "eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae",                                              // Unique event identifier, generated using UUID
  "eventType": "mandate.initiated",                   
  "eventTs": "2025-06-29T19:12:35+05:30",                                                         // Event timestamp
  "resource": "mandate",                              
  "id": "01JYXYSV8B19XAWSFRPARXY35E",                                                             // Mandate ID
  "status": "initiated",                              
  // Empty reason object for initiated status
  "reason": {},
  // Merchant and Reference Information
  "merchantId": "01JYXYSV8B19XAWSFRPARXY35E",                                                     // Merchant ID
  "merchantReferenceId": "mandate_123456789",                                                     // mandate referenceId
  "txnId": "HDF10e4ab8a07f447eea54581383d92b507",                                                 // NPCI Txn.id
  "txnTs": "2025-06-29T19:12:35+05:30",                                                           // NPCI Txn.ts
  "rrn": "123456789012",                                                                          // NPCI Txn.custRef
  "umn": "c27f5fc30d344e9594fce0afa34f8859@mypsp",                                                // Unique Mandate Number from NPCI
  "mandateId": "01JYXYSV8B19XAWSFRPARXY35E",                                                      // Same as id field
  // Amount Information
  "amount": 1000,                                                                                 // Mandate amount in paise
  "amountLimit": 1000,                                                                            // Mandate amount in paise
  "endDate": "20032025",                                                                          // Mandate end date in DDMMYYYY format
  // TPV Specific Information (empty object for non-TPV mandates)
  "customerAccount": {                                                                            // Payer account details, empty object for non-TPV mandates
    "encryptedAccountNumber": "fhDBZ4fC2RtNyiW5rB-jDnzzs_YpYwPGerwAwDTd",                         // Encrypted account number
    "hashedAccountNumber": "d49f354241572a261cfd3a7f210f1919c79fa9993b29e34c5511c3ecefc9f3ea",    // Hashed account number
    "maskedAccountNumber": "**** **** **** 1234",                                                 // Masked account number
    "hashedAccountName": "cceaad99aec841a21be45f02368d0d332493a5a62fdda20c3d85bfb617ef176b",      // Hashed account name
    "maskedAccountName": "M*N* T*O*M*A*S",                                                        // Masked account name
    "encryptedAccountName": "n6MUSW1KXaSWh1E38zxhh1amv9E6rPmZ2Tw=",                               // Encrypted account name
    "ifsc": "HDFC0000053",                                                                        // IFSC code
    "accountType": "SAVINGS"                                                                      // Account type
  }
}

This indicates that the customer has received and authorised the mandate request, so the mandate is now active and will be used to collect payments from the customer accordingly to the rules of the mandate. The following param values indicate this state—

  • operation will be create

  • eventType will be mandate_operation.create.success

  • status will be success

{
  "eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae",                                              // Unique event identifier, generated using UUID
  "eventType": "mandate_operation.create.success",    
  "eventTs": "2025-06-29T19:12:35+05:30",                                                         // Event timestamp
  "resource": "mandate_operation",                    
  "id": "01JYXYSV8B19XAWSFRPARXY35E",                                                             // Mandate ID
  "operation": "create",                              
  "status": "success",                                
  "reason": {
    "code": "mandate-live",                                                                       // Reason code
    "desc": "mandate is live",                                                                    // Reason description
    "npciErrCode": "00",                                                                          // NPCI error code
    "npciErrDesc": "SUCCESS",                                                                     // NPCI error code description
    "npciErrCategory": "NA",                                                                      // NPCI error category (can only be NA, TD, or BD)
    "npciRespCode": "00",                                                                         // NPCI response code
    "npciRespDesc": "SUCCESS",                                                                    // NPCI response code description
    "setuDescription": "",                                                                        // User-friendly description
    "suggestedAction": ""                                                                         // Suggested action for the user
  },
  // Merchant and Reference Information
  "merchantId": "01JYXYSV8B19XAWSFRPARXY35E",                                                     // Merchant ID
  "merchantReferenceId": "mandate_123456789",                                                     // mandate referenceId
  "txnId": "HDF10e4ab8a07f447eea54581383d92b507",                                                 // NPCI Txn.id
  "txnTs": "2025-06-29T19:12:35+05:30",                                                           // NPCI Txn.ts
  "rrn": "123456789012",                                                                          // NPCI Txn.custRef
  "umn": "c27f5fc30d344e9594fce0afa34f8859@mypsp",                                                // Unique Mandate Number from NPCI
  "mandateId": "01JYXYSV8B19XAWSFRPARXY35E",                                                      // Same as id field
  // Amount Information
  "amount": 1000,                                                                                 // Mandate amount in paise
  "amountLimit": 1000,                                                                            // Mandate amount in paise
  "endDate": "20032025",                                                                          // Mandate end date in DDMMYYYY format
  // TPV Specific Information (empty object for non-TPV mandates)
  "customerAccount": {                                                                            // Payer account details, empty object for non-TPV mandates
    "encryptedAccountNumber": "fhDBZ4fC2RtNyiW5rB-jDnzzs_YpYwPGerwAwDTd",                         // Encrypted account number
    "hashedAccountNumber": "d49f354241572a261cfd3a7f210f1919c79fa9993b29e34c5511c3ecefc9f3ea",    // Hashed account number
    "maskedAccountNumber": "**** **** **** 1234",                                                 // Masked account number
    "hashedAccountName": "cceaad99aec841a21be45f02368d0d332493a5a62fdda20c3d85bfb617ef176b",      // Hashed account name
    "maskedAccountName": "M*N* T*O*M*A*S",                                                        // Masked account name
    "encryptedAccountName": "n6MUSW1KXaSWh1E38zxhh1amv9E6rPmZ2Tw=",                               // Encrypted account name
    "ifsc": "HDFC0000053",                                                                        // IFSC code
    "accountType": "SAVINGS"                                                                      // Account type
  }
}

In addition to mandate_operation.create.success, a mandate.live event is also sent.

{
  "eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae",                                              // Unique event identifier, generated using UUID
  "eventType": "mandate.live",                        
  "eventTs": "2025-06-29T19:12:35+05:30",                                                         // Event timestamp
  "resource": "mandate",                              
  "id": "01JYXYSV8B19XAWSFRPARXY35E",                                                             // Mandate ID
  "status": "live",                                   
  "reason": {
    "code": "mandate-live",                                                                       // Reason code
    "desc": "mandate is live",                                                                    // Reason description
    "npciErrCode": "00",                                                                          // NPCI error code
    "npciErrDesc": "SUCCESS",                                                                     // NPCI error code description
    "npciErrCategory": "NA",                                                                      // NPCI error category (can only be NA, TD, or BD)
    "npciRespCode": "00",                                                                         // NPCI response code
    "npciRespDesc": "SUCCESS",                                                                    // NPCI response code description
    "setuDescription": "",                                                                        // Setu description
    "suggestedAction": ""                                                                         // Suggested action for the user
  },
  // Merchant and Reference Information
  "merchantId": "01JYXYSV8B19XAWSFRPARXY35E",                                                     // Merchant ID
  "merchantReferenceId": "mandate_123456789",                                                     // mandate referenceId
  "txnId": "HDF10e4ab8a07f447eea54581383d92b507",                                                 // NPCI Txn.id
  "txnTs": "2025-06-29T19:12:35+05:30",                                                           // NPCI Txn.ts
  "rrn": "123456789012",                                                                          // NPCI Txn.custRef
  "umn": "c27f5fc30d344e9594fce0afa34f8859@mypsp",                                                // Unique Mandate Number from NPCI
  "mandateId": "01JYXYSV8B19XAWSFRPARXY35E",                                                      // Same as id field
  // Amount Information
  "amount": 1000,                                                                                 // Mandate amount in paise
  "amountLimit": 1000,                                                                            // Mandate amount in paise
  "endDate": "20032025",                                                                          // Mandate end date in DDMMYYYY format
  // TPV Specific Information (empty object for non-TPV mandates)
  "customerAccount": {                                                                            // Payer account details, empty object for non-TPV mandates
    "encryptedAccountNumber": "fhDBZ4fC2RtNyiW5rB-jDnzzs_YpYwPGerwAwDTd",                         // Encrypted account number
    "hashedAccountNumber": "d49f354241572a261cfd3a7f210f1919c79fa9993b29e34c5511c3ecefc9f3ea",    // Hashed account number
    "maskedAccountNumber": "**** **** **** 1234",                                                 // Masked account number
    "hashedAccountName": "cceaad99aec841a21be45f02368d0d332493a5a62fdda20c3d85bfb617ef176b",      // Hashed account name
    "maskedAccountName": "M*N* T*O*M*A*S",                                                        // Masked account name
    "encryptedAccountName": "n6MUSW1KXaSWh1E38zxhh1amv9E6rPmZ2Tw=",                               // Encrypted account name
    "ifsc": "HDFC0000053",                                                                        // IFSC code
    "accountType": "SAVINGS"                                                                      // Account type
  }
}

This is sent if mandate could not be created, due to some error or no authorisation from customer. The following param values indicate this state—

  • operation will be create

  • eventType will be mandate_operation.create.success

  • status will be success

{
  "eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae",                                              // Unique event identifier, generated using UUID
  "eventType": "mandate_operation.create.failed",     
  "eventTs": "2025-06-29T19:12:35+05:30",                                                         // Event timestamp
  "resource": "mandate_operation",                    
  "id": "01JYXYSV8B19XAWSFRPARXY35E",                                                             // Mandate ID
  "operation": "create",                              
  "status": "failed",                                
  // Failure reason
  "reason": {
    "code": "mandate-rejected",                                                                   // Reason code
    "desc": "INVALID / INCORRECT MPIN",                                                           // Reason description
    "npciErrCode": "UM8",                                                                         // NPCI error code
    "npciErrDesc": "RESPMANDATE DECLINED BY REMITTER BANK",                                       // NPCI error code description
    "npciErrCategory": "BD",                                                                      // NPCI error category
    "npciRespCode": "ZM",                                                                         // NPCI response code
    "npciRespDesc": "INVALID / INCORRECT MPIN",                                                   // NPCI response code description
    "setuDescription": "",                                                                        // Setu description
    "suggestedAction": ""                                                                         // Suggested action for the user
  },
  // Merchant and Reference Information
  "merchantId": "01JYXYSV8B19XAWSFRPARXY35E",                                                     // Merchant ID
  "merchantReferenceId": "mandate_123456789",                                                     // mandate referenceId
  "txnId": "HDF10e4ab8a07f447eea54581383d92b507",                                                 // NPCI Txn.id
  "txnTs": "2025-06-29T19:12:35+05:30",                                                           // NPCI Txn.ts
  "rrn": "123456789012",                                                                          // NPCI Txn.custRef
  "umn": "c27f5fc30d344e9594fce0afa34f8859@mypsp",                                                // Unique Mandate Number from NPCI
  "mandateId": "01JYXYSV8B19XAWSFRPARXY35E",                                                      // Same as id field
  // Amount Information
  "amount": 1000,                                                                                 // Mandate amount in paise
  "amountLimit": 1000,                                                                            // Mandate amount in paise
  "endDate": "20032025",                                                                          // Mandate end date in DDMMYYYY format
  // TPV Specific Information (empty object for non-TPV mandates)
  "customerAccount": {                                                                            // Payer account details, empty object for non-TPV mandates
    "encryptedAccountNumber": "fhDBZ4fC2RtNyiW5rB-jDnzzs_YpYwPGerwAwDTd",                         // Encrypted account number
    "hashedAccountNumber": "d49f354241572a261cfd3a7f210f1919c79fa9993b29e34c5511c3ecefc9f3ea",    // Hashed account number
    "maskedAccountNumber": "**** **** **** 1234",                                                 // Masked account number
    "hashedAccountName": "cceaad99aec841a21be45f02368d0d332493a5a62fdda20c3d85bfb617ef176b",      // Hashed account name
    "maskedAccountName": "M*N* T*O*M*A*S",                                                        // Masked account name
    "encryptedAccountName": "n6MUSW1KXaSWh1E38zxhh1amv9E6rPmZ2Tw=",                               // Encrypted account name
    "ifsc": "HDFC0000053",                                                                        // IFSC code
    "accountType": "SAVINGS"                                                                      // Account type
  }
}

In addition to mandate_operation.create.failed, a mandate.rejected event is also sent for collect flow based mandate registration failures and for intent / qr based mandate registration failure due to intent / qr expiry

{
  "eventId": "1c94fdeb-2167-443d-99f4-f5fe21d079ae",                                              // Unique event identifier, generated using UUID
  "eventType": "mandate.rejected",     
  "eventTs": "2025-06-29T19:12:35+05:30",                                                         // Event timestamp
  "resource": "mandate",                    
  "id": "01JYXYSV8B19XAWSFRPARXY35E",                                                             // Mandate ID
  "status": "rejected",                                
  // Failure reason
  "reason": {
    "code": "mandate-rejected",                                                                   // Reason code
    "desc": "INVALID / INCORRECT MPIN",                                                           // Reason description
    "npciErrCode": "UM8",                                                                         // NPCI error code
    "npciErrDesc": "RESPMANDATE DECLINED BY REMITTER BANK",                                       // NPCI error code description
    "npciErrCategory": "BD",                                                                      // NPCI error category
    "npciRespCode": "ZM",                                                                         // NPCI response code
    "npciRespDesc": "INVALID / INCORRECT MPIN",                                                   // NPCI response code description
    "setuDescription": "",                                                                        // Setu description
    "suggestedAction": ""                                                                         // Suggested action for the user
  },
  // Merchant and Reference Information
  "merchantId": "01JYXYSV8B19XAWSFRPARXY35E",                                                     // Merchant ID
  "merchantReferenceId": "mandate_123456789",                                                     // mandate referenceId
  "txnId": "HDF10e4ab8a07f447eea54581383d92b507",                                                 // NPCI Txn.id
  "txnTs": "2025-06-29T19:12:35+05:30",                                                           // NPCI Txn.ts
  "rrn": "123456789012",                                                                          // NPCI Txn.custRef
  "umn": "c27f5fc30d344e9594fce0afa34f8859@mypsp",                                                // Unique Mandate Number from NPCI
  "mandateId": "01JYXYSV8B19XAWSFRPARXY35E",                                                      // Same as id field
  // Amount Information
  "amount": 1000,                                                                                 // Mandate amount in paise
  "amountLimit": 1000,                                                                            // Mandate amount in paise
  "endDate": "20032025",                                                                          // Mandate end date in DDMMYYYY format
  // TPV Specific Information (empty object for non-TPV mandates)
  "customerAccount": {                                                                            // Payer account details, empty object for non-TPV mandates
    "encryptedAccountNumber": "fhDBZ4fC2RtNyiW5rB-jDnzzs_YpYwPGerwAwDTd",                         // Encrypted account number
    "hashedAccountNumber": "d49f354241572a261cfd3a7f210f1919c79fa9993b29e34c5511c3ecefc9f3ea",    // Hashed account number
    "maskedAccountNumber": "**** **** **** 1234",                                                 // Masked account number
    "hashedAccountName": "cceaad99aec841a21be45f02368d0d332493a5a62fdda20c3d85bfb617ef176b",      // Hashed account name
    "maskedAccountName": "M*N* T*O*M*A*S",                                                        // Masked account name
    "encryptedAccountName": "n6MUSW1KXaSWh1E38zxhh1amv9E6rPmZ2Tw=",                               // Encrypted account name
    "ifsc": "HDFC0000053",                                                                        // IFSC code
    "accountType": "SAVINGS"                                                                      // Account type
  }
}

Mandates

UPI Setu - Notifications and alerts - Mandates

Update

UPI Setu - Notifications and alerts - Updating mandate

On this page

Notifications and alerts for creation of mandate