Strictly Private and Confidential Technical Speecciiffiiccaattiion Document Document UPI - Online and Offline Acceptance Model v16.0 Strictly Private and Confidential Strictly Private and Confidential STATEMENT OF CONFIDENTIALITY AND DISCLAIMER The contents presented in this document are strictly confidential and proprietary to NPCI International Payments Limited (“NIPL”) and/or its affiliates. This document is intended solely for the recipient’s internal use and for evaluating the proposed transaction or arrangement with NIPL and does not constitute, nor should it be construed as, an offer, invitation, commitment or recommendation. This document does not support a complete description of the subject matter referred to herein. While the utmost care has been taken in preparing this document, NIPL and/or its affiliates claim no responsibility and make no representation, warranty (whether express or implied) for the accuracy, adequacy, reliability or completeness of the information contained herein. All the information contained in this document is provided on an ‘as is’ basis, without any warranty of merchantability, fitness for a particular purpose or non-infringement. All intellectual property rights in and to this document, including without limitation in its contents, design, structure, specifications, underlying know-how, and all related material therein, shall remain with NIPL and/or its affiliates, and no license or other rights (whether express or implied) are granted to the recipient except as provided under this document. The recipient shall not modify, alter, reproduce, distribute, publish, transmit, disclose, display, create derivative works of, or otherwise exploit this document, in whole or in part, without the prior written consent of NIPL. Any unauthorised use, disclosure or public dissemination of information contained herein is prohibited. Unless otherwise expressly agreed in writing, NIPL and/or its affiliates shall not be responsible for any reliance placed on the contents of this document, and the recipient shall use and evaluate the information contained herein at its own discretion and risk. To the fullest extent permitted by applicable law, NIPL and/or its affiliates shall not be liable for any direct, indirect, incidental, consequential, or special loss or damage arising from the use of, reliance on, or inability to use this document. Any suggestions, comments, feedback, enhancement requests, recommendations, or other inputs voluntarily provided by the recipient relating to this document may be freely used, adopted, modified, incorporated, disclosed, and otherwise exploited by NIPL and/or its affiliates without restriction and without any obligation of attribution, confidentiality, royalty, or compensation to the recipient. The information and contents shared in this document are subject to change at any time without notice. NIPL and/or its affiliates undertakes no obligation to update or revise the same. © NIPL 2026, All rights reserved. Strictly Private and Confidential VERSION CONTROL SUMMARY Version Created by Released Reviewed by Remarks Date Version 16 Kusuma 10/08/2026 Gaurav Lodha, Comprehensively revised Meruva Rishu Sinha, the TSD with the addition Dhruvi Monga, of Error Codes, a revamped document Sneha Agrawal structure, updated API specification tables, and refined language to enhance readability and usability. Version 15 Kusuma 29/01/2026 Rishu Sinha Revised TSD with Meruva Gaurav Lodha Restructured sections for better readability, added conditional tags, missing tags in the API tables. Updated the flow of diagrams, added Heartbeat API and digital signing, FAQ and certificates. Version 14 Dhruvi 09/04/2024 Anindita Updated acronyms, added Monga Joardar API tables, updated the flow of diagrams as per the testcase sheet (Refer 3); Appendix Table updated (Refer 6); Added missing tags in ChkTxn under ref tag and Payment Credit (Refer 5.3) Added reference to the docs (Refer 7) (See highlighted) Version 13 10/05/2023 Payee amount tag and orgTxnId description details Strictly Private and Confidential Version Created by Released Reviewed by Remarks Date Version 12 28/03/2023 Invoice tag definition added Version 23/03/2023 Reverse acceptance 11.6 model removed; Appendix – rules updated Version 09/11/2022 TxnConfirmation added to 11.4 sponsor Version 08/11/2022 Check transaction flow 11.3 added (optional); section 7.2 updated; section 4.5 added; new tag “baseCurr” added in ReqValQr API; Device tag updated (correction) Version 11 New model added under Section 4; API specification updated with section 7 Strictly Private and Confidential CONTENTS 1. INTRODUCTION .............................................................................................................. 2 1.1. Purpose ............................................................................................................... 2 1.2. Scope .................................................................................................................. 2 2. ACCEPTANCE ................................................................................................................. 3 2.1. User Journey ........................................................................................................ 3 2.2. Sample Use Cases ............................................................................................... 4 3. LIST OF APIs .................................................................................................................... 7 4. TRANSACTION FLOW ...................................................................................................... 8 4.1. QR Validation ...................................................................................................... 9 4.2. Financial Flow ................................................................................................... 10 5. ACCEPTANCE SCENARIOS AND TIMEOUTS ................................................................... 11 5.1. Scenario-1: IP Sends Failure Response For Credit Confirmation .......................... 12 5.2. Scenario-2: IP Sends Success Response For Reqchktxn ...................................... 13 5.3. Scenario-3: IP Sends Failure Response For Reqchktxn ........................................ 14 5.4. Scenario-4: IP Response For Reqpay Reversal (Success) ..................................... 15 5.5. Scenario-5: IP Response For Reqpay Reversal (Failure) ....................................... 16 5.6. Scenario-6: Transaction Timeout At IP’s End (Deemed) ....................................... 17 6. API SPECIFICATIONS ..................................................................................................... 18 6.1. Validation Of QR ................................................................................................ 18 6.1.1. QR Validation Request (ReqValQr) ...................................................................... 18 6.1.2. QR Validation Response (RespValQr) ................................................................. 25 6.2. International Credit Request/Response .............................................................. 49 6.2.1. International Credit Request (ReqPay) ................................................................ 49 6.3. Check Transaction Status .................................................................................. 87 6.3.1. Check Transaction Request (ReqChkTxn) ........................................................... 88 6.3.2. Check Transaction Response (RespChkTxn) ....................................................... 93 6.4. Heartbeat API ................................................................................................... 102 6.4.1. ReqHbt ............................................................................................................. 103 6.4.2. RespHbt ........................................................................................................... 106 7. API BRIEFLY .................................................................................................................... 111 7.1. API Protocol ...................................................................................................... 112 7.2. Message Security, Trust, And Authenticity ......................................................... 114 7.2.1 IP Whitelisting ................................................................................................... 114 7.2.2 Certificate Requirement .................................................................................... 114 Strictly Private and Confidential 7.2.3 Protection Against Phishing ............................................................................... 115 7.2.4 Security Considerations .................................................................................... 115 7.2.5 Digital Signature Guidelines (For Reference Only) ............................................... 116 8. ERROR CODES FOR ACCEPTANCE .................................................................................. 124 9. FREQUENTLY ASKED QUESTIONS .................................................................................... 145 API Description Tables Table 1: ReqValQr API ........................................................................................................... 20 Table 2: RespValQr API ......................................................................................................... 29 Table 3: ReqPay API .............................................................................................................. 53 Table 4: RespPay API ............................................................................................................ 77 Table 5: ReqChkTxn .............................................................................................................. 89 Table 6: RespChkTxn ............................................................................................................ 94 Table 7: ReqHbt API ............................................................................................................ 104 Table 8: RespHbt API .......................................................................................................... 107 Transaction Flow Diagrams Figure 1: Transaction flow ....................................................................................................... 8 Figure 2: QR validation flow .................................................................................................... 9 Figure 3: Financial flow ......................................................................................................... 10 Figure 4: Credit failure response from IP ................................................................................ 12 Figure 5: Transaction flow for credit success response to transaction status check ................. 13 Figure 6: Transaction flow for credit failure response to transaction status check.................... 14 Figure 7: Transaction flow for credit success response to credit reversal ................................ 15 Figure 8: Transaction flow for credit failure response for credit reversal .................................. 16 Figure 9: Transaction flow for deemed transaction ................................................................. 17 Strictly Private and Confidential TABLE OF ABBREVIATIONS Acceptance-UPI Reconciliation & Clearing System aURCS Acknowledgement ACK Application Programming Interface API Bharat Interface for Money BHIM Foreign Currency FCY Foreign Exchange FX Hypertext Transfer Protocol Secure HTTPS International Partner IP International UPI iUPI National Payments Corporation of India NPCI NPCI International Payments Limited NIPL Payment Service Provider PSP Person-to-Merchant P2M Person-to-Person P2P Point of Sale PoS Representational State Transfer REST Technical Specification Document TSD Unified Payments Interface UPI Universally Unique Identifier UUID Virtual Payment Address VPA 1 Strictly Private and Confidential 1. INTRODUCTION Unified Payments Interface (UPI) is a real-time digital payment system, developed by the National Payments Corporation of India (NPCI), that facilitates interbank Person-to- Merchant (P2M) and Person-to-Person (P2P) transfer of money. Along with domestic payments, UPI also supports foreign remittances and international merchant payments. The latter, known as Global UPI Acceptance, enables Indian users travelling overseas to make seamless payments at international merchants using their UPI apps. 1.1. Purpose The purpose of this document is to provide a comprehensive overview of the Global UPI Acceptance flow (P2M). It defines the end-to-end transaction journey, outlines the Application Programming Interface (API) specifications, and illustrates various transaction flow scenarios to support seamless cross-border UPI payments. 1.2. Scope The scope of this document is outlined below: 1. Customer journey for Acceptance flow: a. Online flow (e-commerce/intent): Indian customer scanning an international QR or making payment through the intent URL on an international merchant’s website. There are two models in this case: i. Foreign Currency (FCY) model: The transaction amount is displayed on the merchant’s website in the FCY. The amount is then converted to INR, and both FCY and INR values are presented to the customer. Payer currency: INR Payee currency: FCY ii. INR model: The transaction amount is displayed directly in INR on the merchant’s website. The transaction is processed entirely in INR with no currency conversion. Payer currency: INR Payee currency: INR b. Offline FCY flow (at merchant outlet): Indian customer scanning the international QR at merchant outlet. 2 Strictly Private and Confidential 2. API specifications and message structures of each API used in the Acceptance flow. 3. Certificate requirements and digital signing process applicable to IP integrations. 4. System uptime and monitoring requirements. 5. Purpose code: Scope Purpose Code Global offline QR Acceptance - Acceptance In-Person 11 International E-Commerce (FCY Direct) - Acceptance Online 62 International E-Commerce (INR Direct) - Acceptance Online 66 2. ACCEPTANCE The Acceptance model enables Indian customers to seamlessly make payments to international merchants by scanning QR at merchant outlets or through e-commerce websites/mobile apps. It ensures a smooth and secure transaction experience by allowing Indian customers to utilise their domestic UPI-enabled applications for cross- border payments. In online FCY flow and offline flow, baseCurr is FCY. The Foreign Exchange FX Rate and FX Markup will be fetched daily and added by iUPI. In online INR flow, baseCurr is INR. FX Rate = 1 and FX Markup = 0, will be added by iUPI. 2.1. User Journey The process to complete a UPI transaction at an international merchant across all supported corridors is as given below: Indian customers first activate the international transaction facility available on their UPI-enabled application to make payments to international merchants. 1. Customers then initiate payment to the international merchant by scanning the merchant presented QR or via the merchant’s app using their UPI-enabled application. 2. The UPI-enabled application will display merchant details such as merchant name and other transaction details. 3. After successful validation of the transaction details, including the amount in FCY and INR, customers can then enter their UPI PIN to authorise the transaction. 4. Once the transaction is authorised, the payment screen is displayed to the customers with success status. 3 Strictly Private and Confidential 5. The merchant then receives real-time confirmation of the payment and accordingly delivers goods or services to the customers. Note: UPI payments can be initiated or made only to the merchants belonging to the international corridors supported by NIPL. Types of QR 1. Dynamic QR: A dynamic QR code is uniquely generated for each transaction at the merchant’s end and the customer need not enter the amount after scanning it for making a payment. When a customer scans the dynamic QR, the UPI-enabled application displays the payable amount in INR and FCY along with the applicable FX Rate and FX Markup. These QR codes are time-bound and come with an expiry to ensure transactional integrity and prevent reuse. Once expired, the QR becomes invalid and a new QR code must be generated for any subsequent transactions. 2. Static QR: This is a fixed QR code that contains unchangeable information, typically used for receiving payments where the user manually enters the amount. When a customer scans the static QR, the UPI-enabled application only displays merchant information. The customer is then prompted to input the payable foreign amount. Based on the amount entered (payable amount in FCY), the application displays the subsequent INR amount with the applicable FX Rate and FX Markup. Secure vs. Unsecure QR code QR codes may be secure or unsecure. Secure QR codes are digitally signed to ensure authenticity and prevent tampering. Unsecure QR codes do not contain a digital signature. 2.2. Sample Use Cases Example 1: International payment at merchant’s location using dynamic QR. Case study: Priya is on a one-month trip to a foreign country and is standing at a grocery store to pay for her purchases. 1. Priya asks the vendor to initiate the payment through UPI. 2. She uses her bank-provided UPI-enabled application installed on her smartphone to scan the dynamic QR code generated by the international grocery Point of Sale (PoS) application. 4 Strictly Private and Confidential 3. The dynamic QR carries information about the merchant and the transaction amount. 4. The UPI-enabled application takes her straight to the pay screen with all values pre-populated from the QR. 5. The UPI-enabled application displays information containing FCY, FX rate, and payable INR value. 6. She verifies the information and authorises the payment by entering her UPI PIN. 7. Both the merchant and Priya receive the payment confirmation instantly. Example 2: International payment at merchant’s location using static QR of the international merchant. Case study: Dev is on vacation in a foreign country and wants to make payment for souvenirs that he has purchased at a gift shop. 1. Dev is exploring the local markets in a foreign country on the last day of his trip. He notices the decal of UPI at a local gift shop which has been acquired by the IP. 2. He picks the souvenir and scans the static QR of the international merchant through his UPI-enabled application. 3. On scanning the QR, the application shows him the merchant’s details and prompts him to enter the amount in FCY. 4. Dev verifies the details shown on the application with the merchant. 5. He enters the FCY amount. The UPI-enabled application displays information containing FCY, FX rate, and payable INR value. 6. Dev verifies the information and enters his UPI PIN to authorise the transaction. 7. Both the merchant and Dev receive payment confirmation instantly. Example 3: Payment to the international merchant via e-commerce site using dynamic QR. Case study: Neha is buying international goods/services online and needs to make an online payment on an international e-commerce website. 1. Neha browses an international e-commerce website and adds items to the cart. At checkout, she selects UPI as the payment method. 2. The dynamic QR code is generated and displayed, which carries information about the merchant and the transaction amount. 5 Strictly Private and Confidential 3. She uses the UPI enabled application installed on her smartphone to scan the generated dynamic QR code. 4. a. In the FCY model: The UPI-enabled application displays merchant information along with FCY, FX rate, and payable INR value b. In the INR model: The UPI-enabled application displays merchant information and the INR amount. 5. She verifies the information and authorises the payment by entering her UPI PIN. 6. Both the merchant and Neha receive payment confirmation instantly. Example 4: International payment on an international merchant’s mobile app using intent URL. Case study: Hari is buying international goods/services online and wants to make an online payment on an international merchant’s mobile app. 1. Hari browses through the international merchant’s mobile app and adds items to his cart. At checkout, he selects UPI as the payment method. 2. The intent URL is generated which carries information about the merchant and the transaction amount. a. For iOS devices: UPI-enabled applications are listed on the merchant’s app, allowing customers to choose their preferred app for payment. Once selected, an intent URL is generated specifically for that app, and customers are redirected to the app to complete the transaction. b. For Android devices: A common intent URL is generated and all UPI-enabled applications installed in the device will be invoked. Customers can select their preferred UPI-enabled application to complete the payment 3. a. In FCY model: The UPI-enabled application displays merchant information along with FCY, FX rate, and payable INR value. b. In INR model: The UPI-enabled application displays merchant information and the INR amount. 4. Hari verifies the information and authorises the payment by entering his UPI PIN. 5. Both the merchant and Hari receive confirmation instantly. 6 Strictly Private and Confidential 3. LIST OF APIs Sr.No. API Name Description of API Non-financial Leg 1. ReqValQr Request QR validation is sent by iUPI to validate the QR code or intent URL generated by the IP. 2. RespValQr Response QR validation is used by the IP after validating the QR to provide the merchant details in response. Financial Leg 3. ReqPay Request Pay is used for processing the payments Response Pay is used for payment response from the 4. RespPay respective IPs for debit, credit, and reversal. Request check transaction is used to enquire about the 5. ReqChkTxn payment status. In case of timeout, check transaction API is initiated by NIPL to know the payment status. Response check transaction is used by the IP to provide 6. RespChkTxn the response for the enquiry on the payment status. System Monitoring 7. ReqHbt Request Heartbeat and Response Heartbeat APIs are health check APIs and are used to check if the system is 8. RespHbt up and running. It can be initiated by both the IP and NIPL. 7 Strictly Private and Confidential 4. TRANSACTION FLOW Following is the flow for an international UPI transaction. All APIs are Representational State Transfer (REST) based and asynchronous in nature. This means that once the request is sent, Acknowledgement (ACK) response is expected for every request sent. For simplification, we have indicated ACK responses where there is interaction between NIPL and the IP in all the following flow diagrams. Figure 1: Transaction flow 1. Customer initiates UPI payment using the UPI enabled application. 2. Payer PSP initiates the QR validation request, i.e., ReqValQr along with the complete QR string/intent URL. 3. iUPI identifies the IP and forwards the validation request accordingly. 4. Post validation, the IP sends response with merchant details to iUPI using the QR validation response, i.e., RespValQr API. 5. iUPI will append the FX details and forward the RespValQr to the Payer PSP. In case of INR model, baseCurr will be INR, FX Rate= 1 and FX Markup= 0. 6. Payer PSP calculates the INR value based on the FX value and the FX Markup provided by iUPI in RespValQr. Payer PSP displays the merchant information and payable amount to the customer. 7. Customer validates the payable amount (FCY and INR) and authenticates the transaction by entering the UPI PIN. 8. Payer PSP initiates the request for payment, i.e., ReqPay to iUPI containing the merchant details, amount payable in INR, and the FX components. 8 Strictly Private and Confidential 9. iUPI initiates the request for debit, i.e., ReqPay Debit request to the remitter bank. 10. Remitter bank authorises the payment and sends successful debit response through the response for debit, i.e., RespPay Debit API. 11. Post securing the debit, iUPI sends the request for credit, i.e., ReqPay Credit request to the IP for crediting the merchant. 12. IP sends a response message to iUPI through the response for credit, i.e., RespPay Credit API. 13. iUPI will forward the final response to the Payer PSP. The transaction is closed as success. 4.1. QR Validation ReqValQr API is a non-financial API used to validate international QR codes scanned by UPI-enabled applications. It also facilitates the validation of intent URLs generated by international merchant applications for online transactions. There are three major types of international QRs that are supported within the UPI ecosystem: 1. UPI QR with international tags 2. EMVCo QR of the IP 3. Proprietary QR of the IP The validation flow will be the same for both QR and intent. Figure 2: QR validation flow 1. Customer initiates UPI payment using the UPI enabled application. 2. Payer PSP initiates ReqValQr along with the complete QR string/intent URL. 3. iUPI identifies the IP and forwards the validation request accordingly. 4. Post validation, the IP sends response to iUPI along with merchant details. 5. iUPI will append the FX details and forward the RespValQr to the Payer PSP. 9 Strictly Private and Confidential a. In case of FCY model, baseCurr will be FCY, FX Rate and FX Markup will be added by iUPI. b. In case of INR model, baseCurr will be INR, FX Rate= 1, and FX Markup = 0. 6. After successful validation, Payer PSP calculates the INR value based on the FX value and FX Markup provided by iUPI in the RespValQr. Payer PSP displays merchant information and the payable amount in both FCY and INR to customers. i. Static QR: Payer PSP prompts customers to enter the payable amount in FCY. PSP calculates equivalent INR value based on the FX value and FX Markup provided by UPI in RespValQr API. ii. Dynamic QR: Since dynamic QR already has the payable amount, Payer PSP calculates equivalent INR amount and displays amount payable in INR and FCY to the customers. 4.2. Financial Flow Figure 3: Financial flow 1. Customers validate the merchant payment information and the payable amount (FCY and INR) in the UPI-enabled application and authorise the transaction by entering the UPI PIN. UPI-enabled application initiates the payment request. 2. Payer PSP initiates ReqPay to iUPI containing the Payer details, merchant details, amount payable in INR, and the FX components. 3. iUPI sends a debit request to the remitter bank to debit the customer’s account. 4. Remitter bank sends the debit success response to the iUPI. 10 Strictly Private and Confidential 5. On successful debit, iUPI will send the credit request to the IP to provide confirmation to the international merchant. 6. IP sends a credit response to iUPI. 7. iUPI sends the transaction confirmation to the settlement bank. 8. Settlement bank sends the transaction confirmation response to iUPI. 9. iUPI sends the successful payment response to the Payer PSP with the transaction status. 10. UPI-enabled application will display successful status to the customer 5. ACCEPTANCE SCENARIOS AND TIMEOUTS In case of non-financial transactions, i.e., the validation process, there are three scenarios to consider: 1. Success: RespValQr is sent to the Payer PSP with merchant and transaction details. 2. Failure: Payer PSP will display error message received in RespValQr to the customer. 3. Timeout: Customer is expected to retry and the Payer PSP to reinitiate ReqValQr. For financial transactions, there are three statuses to consider: 1. Success: The payment is successful. Both the customer and the merchant are notified. 2. Failure: a. Debit failure: Payer PSP will display the error message received from the remitter bank to customer. b. Credit failure: The payment is declined by the IP, and the debited amount is reversed back to the customer’s account. 3. Deemed: No response is received from the IP. Hence, the transaction is closed as deemed approved. The final credit status is further updated by the IP in the back office. Below are the failure scenarios and the management of timeouts and failures in the UPI transaction lifecycle. 11 Strictly Private and Confidential 5.1. Scenario-1: IP Sends Failure Response For Credit Confirmation Figure 4: Credit failure response from IP 1. In step 11, iUPI initiates the credit request to IP post securing the debit. 2. The IP responds with status as “FAILURE”. 3. iUPI will forward the final response to the Payer PSP. The transaction is closed as failure. 12 Strictly Private and Confidential 5.2. Scenario-2: Ip Sends Success Response For Reqchktxn Figure 5: Transaction flow for credit success response to transaction status check 1. In step 11, i.e., ReqPay Credit, IP fails to send the response on international credit to iUPI within 15 seconds. 2. After 15 seconds, iUPI will initiate ReqChkTxn API to get the status of the credit from the IP. 3. IP responds with RespChkTxn with status as “SUCCESS”. 4. iUPI will forward the final response to the Payer PSP. The transaction is closed as success. 13 Strictly Private and Confidential 5.3. Scenario-3: Ip Sends Failure Response For Reqchktxn Figure 6: Transaction flow for credit failure response to transaction status check 1. In step 11, i.e., ReqPay Credit, IP fails to send the response on international credit to iUPI within 15 seconds. 2. After 15 seconds, iUPI will initiate ReqChkTxn API to get the status of the credit from the IP. 3. IP responds with RespChkTxn with status as “FAILURE” and the respective response codes. 4. iUPI initiates debit reversal to the remitter bank. 5. The remitter bank sends successful debit reversal response to iUPI. 6. iUPI will forward the final response to the Payer PSP. The transaction is closed as failure. 14 Strictly Private and Confidential 5.4. Scenario-4: Ip Response For Reqpay Reversal (Success) Figure 7: Transaction flow for credit success response to credit reversal 1. In step 11, i.e., ReqPay Credit, IP fails to send the response on international credit to iUPI within 15 seconds. 2. After 15 seconds, iUPI will initiate ReqChkTxn API to get the status of the credit from the IP. 3. IP fails to respond to ReqChkTxn to iUPI within 10 seconds. 4. iUPI shall initiate a ReqPay API with type=REVERSAL to the IP. 5. IP confirms the CREDIT success by populating response code “CS” (CREDIT SUCCESS). 6. iUPI will forward the success response to the Payer PSP. The transaction is closed as success. 15 Strictly Private and Confidential 5.5. Scenario-5: Ip Response For Reqpay Reversal (Failure) Figure 8: Transaction flow for credit failure response for credit reversal 1. In step 11, i.e., ReqPay Credit, IP fails to send the response on international credit to iUPI within 15 seconds. 2. After 15 seconds, iUPI will initiate ReqChkTxn API to get the status of the credit from the IP. 3. IP fails to respond to ReqChkTxn to iUPI within 10 seconds. 4. iUPI shall initiate a ReqPay with type=REVERSAL to the IP. 5. IP confirms the REVERSAL of credit with response code “00”. iUPI considers this as credit failure and continues to process online debit reversal to the customer. 6. iUPI will forward the final response to the Payer PSP. The transaction is closed as failure. 16 Strictly Private and Confidential 5.6. Scenario-6: Transaction Timeout At Ip’s End (Deemed) Figure 9: Transaction flow for deemed transaction 1. In step 11, i.e., ReqPay Credit, IP fails to send the response on international credit to iUPI within 15 seconds. 2. After 15 seconds, iUPI will initiate ReqChkTxn API to get the status of the credit from the IP. 3. IP fails to respond to ReqChkTxn to iUPI within 10 seconds. 4. After 10 seconds, iUPI will initiate ReqPay with type=REVERSAL to the IP. 5. IP fails to respond within 10 seconds. 6. iUPI will close the transaction as DEEMED. The final status will be updated offline during reconciliation in the back-office Acceptance-UPI Reconciliation & Clearing System (aURCS) portal. 17 Strictly Private and Confidential 6. API SPECIFICATIONS This section enlists the UPI API specifications to be used by the IP to get credit for their merchants via iUPI. Note: 1. The sub tags will be considered mandatory only if the parent tag is present in the API. 2. All UPI APIs are REST based and asynchronous in nature. This means that once the request is sent, the response is sent back separately via corresponding response API. An acknowledgment (ACK) must be sent for every request and response exchanged. 3. Occurrence of the API field: a. 0…1: It is an optional field but can be present only once b. 0…n: It is an optional field but can be present multiple times c. 1…1: It is a mandatory field but must be present only once d. 1…n: It is a mandatory field but can be present multiple times 6.1. Validation Of QR ReqValQr API is used to validate the QR or intent URL generated by the IP. 6.1.1. QR Validation Request (ReqValQr) NIPL will initiate the validation request to the IP and the IP is expected to validate the QR/intent URL and respond with the corresponding merchant details. Below is a sample request API message for the QR validation API. 18 Strictly Private and Confidential Table 1: ReqValQr API ReqValQr Tag Description Occurrence Data Type Length M/O/C Rules API Name ReqValQr 1..1 M API Schema xmlns 1..1 String Min:1 M namespace Max:255 Header 1..1 M This is a parent tag. Version of the API ver 1..1 Numeric Min:1 M Default = 2.0 Max:6 Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the API message Max:255 DDTHH:mm:ss.sssZ was generated where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. 20 Strictly Private and Confidential ReqValQr Tag Description Occurrence Data Type Length M/O/C Rules It changes with each leg of the transaction. Organisation ID of the orgId 1..1 Numeric Min:1 M ID of NIPL will be passed in this field message initiator Max:20 Message identifier msgId 1..1 Alphanumeric Min: 1 M It is unique to each transaction and Max: 35 each API request and response Meta data primarily for 0..1 O This is a parent tag. analytics purposes Meta data details 0..1 O This is a parent tag. Name of the meta name 1..n String Min:1 C Mandatory only if the parent tag is details Max:20 present in the API. List of values: 1. PAYREQSTART 2. PAYREQEND Value of the meta value 1..n ISODateTime Min:1 C Mandatory only if the parent tag is details Max:255 present in the API. Transaction 1..1 M This is a parent tag. information 21 Strictly Private and Confidential ReqValQr Tag Description Occurrence Data Type Length M/O/C Rules Unique identifier that id 1..1 Alphanumeric 35 M remains consistent across both the request and the response Remarks provided by note 1..1 String Min:1 M Permitted special characters are dot the Payer Max:50 ‘.’ and hyphen ‘-’ Website URL of NIPL refUrl 1..1 String Min:1 M Default = http://www.npci.org.in/ Max:35 Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the transaction Max:255 DDTHH:mm:ss.sssZ was initiated where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. Reference ID is refId 1..1 Alphanumeric 35 M It remains consistent across both generated and used by the request and the response. the Payer PSP for internal tracking. Type of transaction type 1..1 String Min:1 M Default = IntlQr Max :20 22 Strictly Private and Confidential ReqValQr Tag Description Occurrence Data Type Length M/O/C Rules Customer reference custRef 1..1 Numeric 12 M number provided by the Payer PSP remains consistent across both the request and the response Mode of initiating the initiationMode 1..1 Numeric 2 M List of values: transaction 00 = Default 01= Offline Static QR Code 02 = Offline Static Secure QR Code 04 = Intent 05 = Secure Intent 15 = Offline Dynamic QR Code 16 = Offline Dynamic Secure QR Code 22 = Online Dynamic QR Code 23 = Online Dynamic Secure QR Code Online/offline purpose 1..1 Numeric 2 M List of values: transaction identifier 11= Offline Acceptance 62 = Online FCY Acceptance 66 = Online INR Acceptance 23 Strictly Private and Confidential ReqValQr Tag Description Occurrence Data Type Length M/O/C Rules Payer details 1..1 M This is a parent tag. UPI ID of the Payer addr 1..1 String Min:1 M 1. UPI ID consists of the alias of the (alias/proxy ID) Max:255 Payer followed by the bank identifier. (Ex: abc.123@bank) 2. Permitted special characters are dot ‘.’ at ‘@’ and hyphen ‘-’ 3. Total length of the UPI ID is inclusive of the bank identifier. Name of the Payer name 1..1 String Min:1 M Permitted special characters are dot Max:99 ‘.’ and hyphen ‘-’ Number of times the seqNum 1..1 Numeric Min:1 M Default = 1 transaction is made Max:3 Type of the Payer type 1..1 String Fixed M Default = PERSON Value Payer Classification code 1..1 Numeric 4 M Default = 0000 Code Institution Block Merchant QR string QrPayLoad 1..1 String M 24 Strictly Private and Confidential ReqValQr Tag Description Occurrence Data Type Length M/O/C Rules Network institution ID netInstId 0..1 Alphanumeric 10 O is the unique network ID assigned by NIPL Currency code of the baseCurr 0..1 String 3 O It should have a 3-character merchant alphabetic value as defined by ISO4217. 6.1.2. QR Validation Response (RespValQr) The IP validates the QR string and subsequently sends the QR validation response along with merchant information. RespValQr xmlns=“http://npci.org/upi/schema/”>"> 25 Strictly Private and Confidential 26 Strictly Private and Confidential Below is a sample response structure for the QR validation API. 27 Strictly Private and Confidential 28 Strictly Private and Confidential Table 2: RespValQr API RespValQr Tag Description Occurrence Data Type Length M/O/C Rules API Name RespValQr 1..1 M API Schema namespace xmlns 1..1 String Min:1 M Max:255 Header 1..1 M This is a parent tag. Version of the API ver 1..1 Numeric Min:1 M Default = 2.0 Max:6 Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the API message Max:255 DDTHH:mm:ss.sssZ was generated where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. It changes with each leg of the transaction. Organisation ID of the orgId 1..1 Numeric Min:1 M During onboarding, NIPL assigns message initiator Max:20 the orgID to IP to pass the assigned ID here. 29 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Message identifier msgId 1..1 Alphanumeric Min:1 M It is unique to each transaction Max:35 and each API request and response Meta data primarily for 0..1 O This is a parent tag. analytics purposes Meta data details 0..1 O This is a parent tag. Name of the meta details name 1..n String Min:1 C Mandatory only if the parent tag Max:20 is present in the API. List of values: 1. PAYREQSTART 2. PAYREQEND Value of the meta details value 1..n ISODateTime Min:1 C Mandatory only if the parent tag Max:255 is present in the API. Transaction information 1..1 M This is a parent tag. Unique identifier that id 1..1 Alphanumeric 35 M IP to pass the values as received remains consistent in the ReqValQr. across both the request and the response for the validation leg 30 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Remarks provided by the note 1..1 String Min:1 M Permitted special characters are Payer Max:50 dot ‘.’and hyphen ‘-’ Reference ID is refId 1..1 Alphanumeric 35 M IP to pass the values as received generated and used by in the ReqValQr. the Payer PSP for internal tracking. Attachment/ website refUrl 1..1 String Min:1 M IP has the provision to pass the URL of IP Max:35 invoice attachment URL; else IPs can pass their website URL as default. Timestamp indicating ts 1..1 ISODateTime Min:1 M IP to pass the values as received when the transaction Max:255 in the ReqValQr. was initiated Type of transaction type 1..1 String Min:1 M Default = IntlQr Max:20 Customer reference custRef 1..1 Numeric 12 M IP to pass the values as received number provided by the in the ReqValQr. Payer PSP remains consistent across both 31 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules the request and the response Mode of initiating the initiationMode 1..1 Numeric 2 M List of values: transaction 00 = Default 01 = Offline Static QR Code 02 = Offline Static Secure QR Code 04 = Intent 05 = Secure Intent 15 = Offline Dynamic QR Code 16 = Offline Dynamic Secure QR Code 22 = Online Dynamic QR Code 23 = Online Dynamic Secure QR Code Online/offline purpose 1..1 Numeric 2 M List of values: transaction identifier 11 = Offline Acceptance 62 = Online FCY Acceptance 66 = Online INR Acceptance 32 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Reference category - to refCategory 1..n Numeric 2 O If the invoice attachment URL is identify the invoice available in the refurl field, then category of the value=02 transaction Else, default = 00 Qr Block 1..1 M This is a parent tag. Values to be passed as per the QR string generated by IP. Version of the QR qVer 1..1 Numeric Min:1 M Default = 01 Max:6 Timestamp indicating ts 0..1 ISODateTime Min:1 C Mandatory for dynamic QR when the QR was Max:255 Format: YYYY-MM- generated DDTHH:mm:ss.sssZ where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. It remains consistent across both the request and the response for the validation and financial legs 33 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Source channel, i.e., qrMedium 0..1 Numeric 2 O List of values: creation point of the QR 02 - APP 03 - POS 04 - PHYSICAL/ Share Intent mode 05 - ATM 06- WEB Validity of the QR which expireTs 0..1 ISODateTime Min:1 C Mandatory for dynamic QR is mapped to ‘QRexpire’ Max:255 Format: YYYY-MM- parameter in QR string DDTHH:mm:ss.sssZ where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. It remains consistent across both the request and the response for the validation and financial legs. Query query 0..1 String Max:20 O verToken 0..1 String O 34 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Verification token for QR Min:1 request. This will be Max:80 passed in the financial request to IP. System trace audit stan 0..1 Numeric 6 O number is present in the QR. It denotes the value generated and passed by IP. Response details 1..1 M This is a parent tag. Transaction error code errCode 1..1 Alphanumeric Min:1 C Mandatory if result = FAILURE Max:20 Refer to the error code provided by NIPL. Result of the transaction result 1..1 String Min:1 M List of values: Max:20 1. SUCCESS 2. FAILURE Message ID of the reqMsgId 1..1 Alphanumeric Min:1 M IP to pass the value from ‘msgId’ corresponding API Max:35 from the ReqValQr API. request Payer details 1..1 O This is a parent tag. 35 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules UPI ID of the Payer addr 1..1 String Min:1 C Mandatory only if the parent tag (alias/proxy ID) Max:255 is present in the API. IP to pass the values as received in the ReqValQr. Name of the Payer name 1..1 String Min:1 C Mandatory only if the parent tag Max:99 is present in the API. IP to pass the values as received in the ReqValQr. Number of times the seqNum 1..1 Numeric Min:1 C Mandatory only if the parent tag transaction is made Max:3 is present in the API. IP to pass the values as received in the ReqValQr. Type of the Payer type 1..1 String Fixed C Mandatory only if the parent tag Value is present in the API. IP to pass the values as received in the ReqValQr. Merchant Classification code 1..1 Numeric 4 C Mandatory only if the parent tag Code is present in the API. IP to pass the values as received in the ReqValQr. 36 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Details associated with 1..1 M This is a parent tag. the beneficiary Payee details 1..1 M This is a parent tag. UPI ID (alias/proxy) of the addr 1..1 String Min:1 M 1. UPI ID consists of the alias of Payee Max:255 the Payee followed by the bank identifier. (Ex: abc.123@bank) 2. Permitted special characters are dot ‘.’ at ‘@’ and hyphen ‘-’ 3. Total length of UPI ID is inclusive of the bank identifier. Name of the Payee name 1..1 String Min:1 M Permitted special characters are Max:99 dot ‘.’ and hyphen ‘-’ Merchant Classification code 1..1 Numeric 4 M Code Number of times the seqNum 1..1 Numeric Min:1 M Default = 1 transaction is made Max:3 Type of the Payee type 1..1 String Fixed M Default = ENTITY Value 37 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Payee information 1..1 O This is a parent tag. Payee identity is present in the API. Type of identifier type 1..1 String Fixed C Default = ACCOUNT Value Mandatory only if the parent tag is present in the API. Name as per identifier verifiedName 1..1 Alphanumeric Min:1 C Mandatory only if the parent tag Max:99 is present in the API. ID of the identifier id 1..1 Alphanumeric Min:1 C Mandatory only if the parent tag Max:99 is present in the API. Rating of the Payee Verification of address verifiedAddress 0..1 String Fixed O List of values: value 1. TRUE 2. FALSE Details of the device 1..1 O This is a parent tag. from which the transaction is initiated 38 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Details of the device tag is present in the API. Name of the device name 1..n String Fixed C List of values: details value 1. MOBILE 2. GEOCODE 3. LOCATION 4. IP 5. TYPE 6. ID 7. OS 8. APP 9. CAPABILITY 10. TELECOM OPERATOR Note: here IP is IP Address. Value of the device value 1..n Alphanumeric Min:1 C 1. MOBILE: details Max:99 countrycode+nnnnnnnnnn 2. GEOCODE: nn.nnnn,nn.nnnn 39 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules 3. LOCATION: Area with city, state, and country code 01-23 - Terminal Address 24-36 - Terminal City 37-38 - Terminal State Code 39-40 - Terminal Country Code 4. IP: Valid IP address format (v4, v6) 5. TYPE: a. Min - 1, Max - 20 b. List of values: i. MOB (Mobile) ii. INET (Internet) iii. POS (Point of Sale) 6. ID: Min - 1, Max - 35 7. OS: a. Min - 1, Max 20- b. List of values: 40 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules i. iOS ii. Android 8. APP: Min - 1, Max - 20 9. CAPABILITY: Min - 1, Max – 99, e.g.,“5200000200010004000 639292929292” 10. TELECOM OPERATOR: Min - 1, Max - 99 (it is mandatory for USSD) Payee account details 1..1 M This is a parent tag. Type of account details addrType 1..1 String Min:1 M Default = ACCOUNT Max:20 Settlement account Name of the account name 1..n String Fixed M List of values: details value 1. ACNUM 2. ACTYPE 3. IFSC 41 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Value of the account value 1..n Alphanumeric Min:1 M 1. IFSC = It should be an 11 digit details Max:99 alphanumeric value. 2. ACTYPE = It should be a fixed value. Can be SAVINGS or CURRENT. 3. ACNUM = It should have a maximum of 30 digits. Information related to mandatory only for dynamic QR. transaction Transaction amount value 1..1 Numeric Min:0 M Format: 2 digits after the Max:15 decimal str allowed. E.g., (Amount Value = “100.00”). Transaction currency curr 1..1 String 3 M It should have a 3-character alphabetic value as defined by ISO4217. Transaction amount Name of the amount name 1..n String Fixed C Mandatory only if the parent tag details value is present in the API. 42 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules List of values: 1. baseAmount 2. baseCurr 3. FX 4. Mkup Value of the amount value 1..n Alphanumeric Min:1 C Mandatory only if the parent tag details Max:99 is present in the API. Merchant details Merchant identification Merchant category code subCode 0..1 Numeric 4 O Merchant ID mid 0..1 Alphanumeric Min:1 M Max:20 Store ID sid 0..1 Alphanumeric Min:1 O Max:20 Terminal ID tid 0..1 Alphanumeric Min:1 M Max:20 43 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Merchant type merchantType 1..1 String Fixed M List of values: value 1. SMALL 2. LARGE Note: IP needs to define the type of merchant Merchant genre merchantGenre 0..1 String Fixed M List of values: value 1. ONLINE 2. OFFLINE Onboarding type of the onBoardingType 1..1 String Fixed M List of values: merchant value 1. BANK 2. AGGREGATOR 3. TPAP 4. NETWORK Merchant registration ID regId 0..1 Alphanumeric Max:35 O Area pincode pinCode 0..1 Numeric Min:4 O Max:6 Tier of the city tier 0..1 Alphanumeric String O Location of the merchant merchantLoc 1..1 Alphanumeric Max:70 M 44 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Institution code of the merchantInstCo 0..1 Alphanumeric Min:1 O merchant de Max:20 Payee merchant name Brand name of the brand 1..n Alphanumeric Min:1 M merchant Max:99 Legal name of the legal 0..1 Alphanumeric Min:1 O merchant Max:99 Franchise agent name franchise 0..1 Alphanumeric Min:1 O Max:99 Merchant ownership Type of ownership type 0..1 String Fixed O List of values: value 1. PROPRIETARY 2. PARTNERSHIP 3. PRIVATE 4. PUBLIC 5. OTHERS 45 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules Invoice details Name on the invoice name 1..1 Alphanumeric Min:1 M Max:99 Invoice number num 1..1 Alphanumeric Max:20 M Invoice date date 1..1 ISODateTime Min:1 M Format to be: Max:255 Ex: 2026-07-28T12:22:41+06:00 Institution Block Merchant QR string QrPayLoad 1..1 String M IP to pass the values as received in the ReqValQr. Network institution ID is netInstId 0..1 Alphanumeric 10 O During onboarding, NIPL assigns the unique network ID the netInstId to IP. assigned to IP by NIPL Country code of the conCode 1..1 String 2 M It is a 2-character alphabetic merchant value, as defined by ISO 3166-.1 FX details for the 1..1 M Only base amount, baseCurr to transaction be passed by IP to NIPL. Other 46 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules sub tags are mandatory and shall be passed by NIPL. FX rate details 1..n M This is a parent tag. Amount payable in the baseAmount 1..1 Numeric Min:0 M Format: 2 digits after the baseCurr of the Max:15 decimal are allowed. merchant E.g., (Amount Value= “100.00”). Currency code at the baseCurr 1..1 String 3 M It should have a 3-character merchant’s location alphabetic value as defined by ISO4217. Logic: For INR model, baseCurr to be ‘INR’ For FCY model, baseCurr to be ‘FCY’(SGD, AED, etc.) It denotes that the active 1..1 String 1 M FX active is provided by iUPI currency is active in the List of values: Y | N NIPL repository Foreign exchange rate is FX 1..1 Numeric Min:0 M FX is provided by iUPI daily the baseCurr to quote Max:15 Logic: the currency conversion 47 Strictly Private and Confidential RespValQr Tag Description Occurrence Data Type Length M/O/C Rules rate. It is provided by For INR model, FX to always be iUPI. ‘1’ For FCY model, FX to always be fetched by iUPI and provided Markup is the processing Mkup 1..1 Numeric Min:1 M The value in this field should fee obtained by NIPL for Max:99 have 2 digits after the decimal. cross border Example: for FCY model, if the transactions. It is markup rate is 3.29% then the provided by iUPI in value in said field will be Mkup = percentage form. 3.29 Logic: For INR model, Mkup to always be ‘0.00’ Last modified date of the lastModifiedTs 0..1 ISODateTime Min:1 O FX Max:255 48 Strictly Private and Confidential 6.2. International Credit Request/Response This API is used to initiate the payment request to the IP for crediting the merchant. 6.2.1. International Credit Request (ReqPay) 49 Strictly Private and Confidential 50 Strictly Private and Confidential Below is a sample request structure for the ReqPay API. 51 Strictly Private and Confidential 52 Strictly Private and Confidential Table 3: ReqPay API ReqPay Tag Description Occurrence Data Type Length M/O/C Rules API Name ReqPay 1..1 M API Schema xmlns 1..1 String Min:1 M namespace Max:255 Header 1..1 M This is a parent tag. Version of the API ver 1..1 Numeric Min:1 M Default = 2.0 Max:6 Timestamp ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- indicating when the Max:255 DDTHH:mm:ss.sssZ API message was where 'T' serves as the delimiter, and generated 'Z' represents the Indian time zone offset from GMT, which is +05:30. It changes with each leg of the transaction. 53 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Organisation ID of orgId 1..1 Numeric Min:1 M ID of NIPL will be passed in this field message initiator Max:20 Type of the product prodType 0..1 String Fixed O Default = UPI value Message identifier msgId 1..1 Alphanumeric Min:1 M It is unique to each transaction and Max:35 each API request and response Meta data primarily 0..1 O This is a parent tag. for analytics purposes Meta data details 0..1 O This is a parent tag. Name of the meta name 1..n String Min:1 C Mandatory only if the parent tag is details Max:20 present in the API. List of values: 1. PAYREQSTART 2. PAYREQEND Value of the meta value 1..n ISODateTime Min:1 C Mandatory only if the parent tag is details Max:255 present in the API. Transaction 1..1 M This is a parent tag. information 54 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Unique identifier id 1..1 Alphanumeric 35 M Transaction ID of ReqPay API is used that remains for reconciliation. consistent across both the request and the response for ReqPay type=credit Remarks provided note 1..1 String Min:1 M Permitted special characters are dot by the Payer Max:50 ‘.’ and hyphen ‘-’ Reference ID is refId 1..1 Alphanumeric 35 M It remains consistent across both the generated and used request and the response. by the Payer PSP for internal tracking. Website URL of refUrl 1..1 String Min:1 M Default = http://www.npci.org.in/ NIPL Max:35 Timestamp ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- indicating when the Max:255 DDTHH:mm:ss.sssZ transaction was where 'T' serves as the delimiter, and initiated 'Z' represents the Indian time zone offset from GMT, which is +05:30. 55 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules It changes with each leg of the transaction. Type of the type 1..1 String Min:1 M List of values: transaction Max:20 1. CREDIT (when a credit request is initiated to IP). 2. REVERSAL (when IP fails to send a response for ReqPay type = CREDIT and ReqChkTxn, ReqPay type = REVERSAL is initiated to reverse the transaction). Original transaction orgTxnId 1..1 Alphanumeric 35 C 1. Offline acceptance (11): ID Mandatory for type=REVERSAL 2. Online acceptance (62,66): Mandatory for ReqPay type=CREDIT and REVERSAL. 3. For type = CREDIT: The credit request will always be initiated with a new transaction ID. The orgTxnId shall have the value of the transaction ID from ReqValQr 56 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules 4. For type = REVERSAL: The credit reversal request will always be initiated with a new transaction ID. The orgTxnId shall have the value of the transaction ID from ReqPay type = CREDIT. Customer custRef 1..1 Numeric 12 M reference number provided by the Payer PSP remains consistent across both the request and the response Subtype of subType 1..1 String Min:1 M 1. If type = CREDIT, then subtype = transaction Max:20 PAY 2. If type = REVERSAL, then subtype = CREDIT Mode of initiating initiationMode 1..1 Numeric 2 M List of values: the transaction 00 = Default 01 = Offline Static QR Code 02 = Offline Static Secure QR Code 57 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules 04 = Intent 05 = Secure Intent 15 = Offline Dynamic QR Code 16 = Offline Dynamic Secure QR Code 22 = Online Dynamic QR Code 23 = Online Dynamic Secure QR Code Online/offline purpose 1..1 Numeric Fixed M List of values: transaction value 11 = Offline Acceptance identifier 62 = Online FCY Acceptance 66 = Online INR Acceptance Original retrieval orgRrn 0..1 Numeric 12 O reference number contains the respective custRef tag value Original date of the orgTxnDate 0..1 ISODateTime Min:1 O Format: YYYY-MM- transaction Max:255 DDTHH:mm:ss.sssZ where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. 58 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules It changes with each leg of the transaction. Reference category refCategory 0..1 Numeric Fixed O If the invoice attachment URL is - to identify the value available in the refurl field, then value invoice category of = 02 the transaction Else, Default = 00. Risk score related 0..1 M This is a parent tag. to the transaction and the entities Risk score related and the entities Name of the entity provider 1..1 String Min:1 M Default = NPCI providing the risk Max:20 score Type of risk type 1..1 String Min:1 M Default = TXNRISK Max:99 Risk score value of value 1..1 Numeric Min:1 M Score calculated by NIPL post the risk evaluation Max:50 validation of platform specific rules, including the transaction velocity and 59 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules amount validation. It is used by the remitter bank for fraud detection at the time of debit Qr Block 1..1 M This is a parent tag. Version of the QR qVer 1..1 Numeric Min:1 M Default = 01 Max:6 Timestamp ts 0..1 ISODateTime Min:1 C Mandatory for dynamic QR indicating when the Max:255 Format: YYYY-MM- QR was generated DDTHH:mm:ss.sssZ where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. It remains consistent across both request & response for validation and financial leg Source channel, qrMedium 0..1 Numeric Min:1 O List of values: i.e., creation point Max:99 02 - APP of the QR 03 - POS 04 - PHYSICAL/ Share Intent mode 05 - ATM 06 - WEB 60 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Validity of the QR expireTs 0..1 ISODateTime Min:1 C Mandatory for dynamic QR. which is mapped to Max:255 Format: YYYY-MM- ‘QRexpire’ DDTHH:mm:ss.sssZ parameter in QR where 'T' serves as the delimiter, and string 'Z' represents the Indian time zone offset from GMT, which is +05:30. It remains consistent across both the request and the response for the validation and financial legs. Query query String Max: 20 O Verification token verToken 0..1 String Min:1 O passed by IP in Max:80 RespValQr will be passed here System trace audit stan 0..1 String 6 O number is present in the QR. It denotes the value generated and passed by IP. 61 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Payer details 1..1 M This is a parent tag. UPI ID of the Payer addr 1..1 String Min:1 M 1. UPI ID consists of the alias of the (alias/proxy ID) Max:255 Payer followed by the bank identifier. (Ex: abc.123@bank) 2. Permitted special characters are dot ‘.’ at ‘@’ and hyphen ‘-’ 3. Total length of UPI ID is inclusive of the bank identifier. Name of the Payer name 1..1 String Min:1 M Permitted special characters are dot Max:99 ‘.’ and hyphen ‘-’ Number of times a seqNum 1..1 Numeric Min:1 M Default = 1 transaction is made Max:3 Type of the Payer type 1..1 String Fixed M Default = PERSON Value Merchant code 1..1 Numeric 4 M Default = 0000 Classification Code Payer Institution 1..1 M This is a parent tag. Block Merchant QR string QrPayLoad 1..1 String M 62 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Network institution netInstId 1..1 Alphanumeric 10 M ID is the unique network ID assigned to IP by NIPL Country of the conCode 1..1 String 2 M It is a 2-character alphabetic value, merchant as defined by ISO 3166-1. Information related 1..1 M to the amounts in the transaction Transaction value 1..1 Numeric Min:0 M Format: 2 digits after the decimal. amount Max:15 E.g., (Amount Value= “100.00”). Transaction curr 1..1 String Fixed M Default = INR currency value Details of Name of the name 1..n String Min:1 C Mandatory only if parent tag is amount details Max:20 present in the API. List of values: 1. baseAmount 63 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules 2. baseCurr 3. FX 4. Mkup Value of the value 1..n Alphanumeric Min:1 C Mandatory only if parent tag is amount details Max:99 present in the API. Details related to 1..1 M This is a parent tag. the beneficiary Payee details 1..1 M This is a parent tag. UPI ID of the Payee addr 1..1 Alphanumeric Min:1 M 1. UPI ID consists of the alias of the (alias/proxy ID) Max:255 Payee followed by the bank identifier. (Ex: abc.123@bank) 2. Permitted special characters are dot ‘.’ at ‘@’ and hyphen ‘-’ 3. Total length of UPI ID is inclusive of the bank identifier. Name of the Payee name 1..1 Alphanumeric Min:1 M Permitted special characters are dot Max:99 ‘.’ and hyphen ‘-’ 64 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Number of times a seqNum 1..1 Numeric Min:1 M Default = 1 transaction is made Max:3 Type of the Payee type 1..1 String Fixed M Default = ENTITY value Merchant code 1..1 Numeric 4 M Classification Code Information related 1..1 M This is a parent tag. to the Payee Payee identity Type of identifier type 1..1 String Fixed M Default = ACCOUNT value Name as per the verifiedName 1..1 Alphanumeric Min:1 M identifier Max:99 ID of the Identifier id 1..1 Alphanumeric Min:1 M Max:99 Rating of the Payee 65 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Verification of verifiedAddress 1..1 BOOLEAN Fixed M List of values: address value 1. TRUE 2. FALSE Details of the 0..1 O This is a parent tag. device from which the transaction was initiated Payee device present in the API. Name of the device name 1..n String Fixed C List of values: details value 1. MOBILE 2. GEOCODE 3. LOCATION 4. IP 5. TYPE 6. ID 7. OS 8. APP 66 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules 9. CAPABILITY 10. TELECOM OPERATOR Note: here IP is IP Address. Value of the device value 1..n Alphanumeric Min:1 C 1. MOBILE: details Max:99 countrycode+nnnnnnnnnn 2. GEOCODE: nn.nnnn,nn.nnnn 3. LOCATION: Area with city, state, and country code 01 - 23 - Terminal Address 24 - 36 - Terminal City 37 - 38- Terminal State Code 39 - 40- Terminal Country Code 4. IP: Valid IP address format (v4, v6) 5. TYPE: a. Min - 1, Max - 20 b. List of values: i. MOB (Mobile) ii. INET (Internet) iii. POS (Point of Sale) 67 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules 6. ID: Min - 1, Max - 35 7. OS: a. Min - 1, Max - 20 b. List of values: i. iOS ii. Android 8. APP: Min - 1, Max - 20 9. CAPABILITY: Min - 1, Max – 99, e.g., “52000002000100040006392929 29292” 10. TELECOM OPERATOR: Min - 1, Max - 99 (it is mandatory for USSD) Payee account 1..1 M This is a parent tag. details Type of account addrType 1..1 String Min:1 M Default = ACCOUNT detail Max:20 Settlement account 1..n M This is a parent tag. details of IP 68 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Name of the name 1..n String Fixed M List of values: account detail value 1. ACNUM 2. ACTYPE 3. IFSC Value of the value 1..n Alphanumeric Min:1 M 1. IFSC = It should be an 11 digit account detail Max:99 alphanumeric value. 2. ACTYPE = It should be fixed Value. Can be SAVINGS or CURRENT. 3. ACNUM = It should have a maximum of 30 digits. Information related 1..1 M This is a parent tag. to the amounts in the transaction INR transaction value 1..1 Numeric Min:0 M Format: 2 digits after the decimal. amount Max:15 E.g., (Amount Value= “100.00”). Transaction curr 1..1 String Fixed M Default = INR currency value Transaction 69 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Name of the name 1..n String Fixed C Mandatory only if parent tag is amount details value present in the API. List of values: 1. baseAmount 2. baseCurr 3. FX 4. Mkup Value of the value 1..n Alphanumeric Min:1 C Mandatory only if parent tag is amount details Max:99 present in the API. Merchant details 1..1 M This is a parent tag. Merchant details Merchant category subCode 0..1 Numeric 4 O code Merchant ID mid 1..1 Alphanumeric Min:1 M Max:20 Store ID sid 0..1 Alphanumeric Min:1 O Max:20 70 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Terminal ID tid 1..1 Alphanumeric Min:1 M Max:20 Type of merchant merchantType 1..1 String Fixed M List of values: value 1. SMALL 2. LARGE Merchant genre merchantGenre 1..1 String Fixed M List of values: value 1. ONLINE 2. OFFLINE Onboarding type of onBoardingType 1..1 String Fixed M List of values: the merchant value 1. BANK 2. AGGREGATOR 3. TPAP 4. NETWORK Merchant regId 0..1 Alphanumeric Max:35 O registration ID Area pincode pinCode 0..1 Numeric Min:4 O Max:6 Tier of the city tier 0..1 Alphanumeric String O 71 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Location of the merchantLoc 1..1 Alphanumeric Max:70 M merchant Merchant merchantInstCode 0..1 Alphanumeric Min:1 O institution code Max:20 Payee merchant Brand name of the brand 1..1 Alphanumeric Min:1 M merchant Max:99 Legal name of the legal 0..1 Alphanumeric Min:1 O merchant Max:99 Franchise agent franchise 0..1 Alphanumeric Min:1 O name Max:99 Merchant Type of ownership type 0..1 String Fixed O List of values: value 1. PROPRIETARY 2. PARTNERSHIP 3. PRIVATE 4. PUBLIC 72 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules 5. OTHERS Invoice details Name on the name 1..1 Alphanumeric Min:1 M invoice Max:99 Invoice number num 1..1 Alphanumeric Max:20 M Invoice date date 1..1 ISODateTime Min:1 M Format: YYYY-MM- Max:255 DDTHH:mm:ss.sssZ where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. It remains consistent across both the request and the response for the validation and financial legs. FX details 1..1 M This is a parent tag. FX rate details 1..n M This is a parent tag. baseAmount 1..1 Numeric M 73 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Amount payable in Min:0 Format: 2 digits after the decimal is the baseCurr of the Max:15 allowed. merchant E.g. (Amount Value= “100.00”). Currency code at baseCurr 1..1 String 3 M It should have a 3-character the merchant’s alphabetic value as defined by location ISO4217. Logic: For INR model, baseCurr to be ‘INR’ For FCY Model, baseCurr to be ‘FCY’ It denotes that the active 1..1 M FX_active is provided by iUPI currency is active in the NIPL repository Foreign exchange FX 1..1 Numeric Min: 0 M FX is provided by iUPI daily. rate is the baseCurr Max:15 Logic: to quote the For INR model, FX to always be ‘1’ currency For FCY model, FX to always be conversion rate. It fetched by iUPI and provided. is provided by iUPI. 74 Strictly Private and Confidential ReqPay Tag Description Occurrence Data Type Length M/O/C Rules Markup is the Mkup 1..1 Numeric Min:1 M The value in this field should have 2 processing fee Max:99 digits after the decimal. obtained by NIPL Example: for the FCY model, if the for cross border markup rate is 3.29% then the value transactions. It is in the said field will be Mkup = 3.29 provided by iUPI in Logic: percentage form. For INR model, Mkup to always be ‘0.00’ Last modified date lastModifiedTs 0..1 ISODateTime Min:1 O of the FX Max:255 INTERNATIONAL CREDIT RESPONSE (RespPay) 75 Strictly Private and Confidential Below is a sample response structure for the RespPay API. 76 Strictly Private and Confidential Table 4: RespPay API RespPay Tag Description Occurrence Data Type Length M/O/C Rules API Name RespPay 1..1 M API Schema xmlns 1..1 String Min:1 M namespace Max:255 Header 1..1 M This is a parent tag. Version of the API ver 1..1 Numeric Min:1 M Default = 2.0 Max:6 Timestamp ts 1..1 ISODateTime Min:1 M Format: YYYY-MM-DDTHH:mm:ss.sssZ indicating when Max:255 where T is the delimiter and Z is the time the API message zone difference from GMT in +/- hh:mm was generated It changes with each leg of the transaction. Organisation ID of orgId 1..1 Numeric Min:1 M During onboarding, NIPL assigns the orgID message initiator Max:20 to the IP. IP to pass the assigned ID here. Type of product prodType 0..1 String Fixed O Default = UPI Value 77 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules Message msgId 1..1 Alphanumeric Min:1 M It is unique to each transaction and each identifier Max:35 API request and response Transaction 1..1 M This is a parent tag. information Unique identifier id 1..1 Alphanumeric 35 M IP to pass the values as received in the that remains ReqPay. consistent across both the request and the response for financial leg Remarks entered note 1..1 String Min:1 M Permitted special characters are dot ‘.’ by the Payer Max:50 and hyphen ‘-’ Reference ID is refId 1..1 Alphanumeric 35 M IP to pass the values as received in the generated and ReqPay. used by the Payer PSP for internal tracking. Attachment/ refUrl 1..1 String Min:1 M IP has provision to pass the invoice website URL of IP Max:35 attachment URL; else IP can pass their website URL as default 78 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules Timestamp ts 1..1 ISODateTime Min:1 M Format: YYYY-MM-DDTHH:mm:ss.sssZ indicating when Max:255 where T is the delimiter and 'Z' represents the transaction the Indian time zone offset from GMT, was initiated which is +05:30. It remains the same throughout the transaction. Type of type 1..1 String Min:1 M List of values: transaction Max:20 1. CREDIT (when a credit response is initiated by IP). 2. REVERSAL (when IP fails to send response for ReqPay type = CREDIT and ReqChkTxn, RespPay type = REVERSAL is initiated by IP to reverse the transaction). Original orgTxnId 1..1 Alphanumeric 35 C IP to pass the values as received in the transaction ID ReqPay. Customer custRef 1..1 Numeric 12 M IP to pass the values as received in the reference number ReqPay. provided by the Payer PSP remains 79 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules consistent across both the request and the response Subtype of subType 0..1 String Min:1 M 1. If type = CREDIT, then subtype = PAY transaction Max:20 2. If type = REVERSAL, then subtype = CREDIT Mode of initiating initiationMod 1..1 Numeric 2 M List of values: the transaction e 00 = Default 01 = Offline Static QR Code 02 = Offline Static Secure QR Code 04 = Intent 05 = Secure Intent 15 = Offline Dynamic QR Code 16 = Offline Dynamic Secure QR Code 22 = Online Dynamic QR Code 23 = Online Dynamic Secure QR Code Online/offline purpose 1..1 Numeric Fixed M List of values: transaction value 11= Offline Acceptance identifier 62 = Online FCY Acceptance 66 = Online INR Acceptance 80 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules Original date of orgTxnDate 0..1 ISODateTime Min:1 O IP to pass the values as received in the the transaction Max:255 ReqPay. Reference refCategory 0..1 Numeric Fixed O If invoice attachment URL is available in category - to value the refurl field, then value = 02 identify the else Default = 00. invoice category of the transaction Risk score related and the entities Risk score related and the entities Name of the provider 1..1 String Min:1 C Mandatory only if parent tag is present in entity providing Max:20 the API. the risk score Type of risk type 1..1 String Min:1 C Default = "TXNRISK" Max:99 Mandatory only if parent tag is present in the API. 81 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules Risk score value value 1..1 Numeric Min:1 C Mandatory only if parent tag is present in of risk evaluation Max:50 the API. Score calculated by IP post validation of platform specific rules, including the transaction velocity and amount validation. It is used by the remitter bank for fraud detection at the time of debit. Qr Block 1..1 M This is a parent tag. Version of the QR qVer 1..1 Numeric Min:1 M Default = “01” Max:6 Timestamp ts 0..1 ISODateTime Min:1 C Mandatory for dynamic QR indicating when Max:255 Format: YYYY-MM-DDTHH:mm:ss.sssZ the QR was where 'T' serves as the delimiter, and 'Z' generated represents the Indian time zone offset from GMT, which is +05:30. It remains consistent across both the request and the response for the validation and financial legs. Source channel, qrMedium 0..1 Numeric Min:1 O List of values: i.e., creation point Max:99 02 - APP of the QR 03 - POS 04 - PHYSICAL/ Share Intent 82 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules 05 - ATM 06 - WEB Validity of the QR expireTs 0..1 ISODateTime Min:1 C Mandatory for dynamic QR which is mapped Max:255 Format: YYYY-MM-DDTHH:mm:ss.sssZ to ‘QRexpire’ where 'T' serves as the delimiter, and 'Z' parameter in QR represents the Indian time zone offset string from GMT, which is +05:30. It remains consistent across both the request and the response for the v alidation and financial legs. Query query 0..1 String Max: 20 O Verification token verToken 0..1 String Min:1 O for request Max:80 System trace stan 0..1 String 6 O audit number is present in the QR. It denotes the value generated and passed by IP. Response details 1..1 M This is a parent tag. 83 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules Message ID of the reqMsgId 1..1 Alphanumeric Min:1 M IP to pass the value from ‘msgId’ from the corresponding Max:35 ReqPay API. API request Result of the result 1..1 String Min:1 M List of values: transaction Max:20 1. SUCCESS 2. FAILURE Transaction error errCode 1..1 Alphanumeric Min:1 C Mandatory only if result = FAILURE. code Max:20 IP to populate the relevant error code per NIPL’s response/ error code. Transaction 1..n M This is a parent tag. reference details Type of reference type 1..1 String Fixed M Default = PAYEE Value Number of times seqNum 1..1 Numeric Min:1 M Default = 1 a transaction is Max:3 made UPI ID of the addr 1..1 Alphanumeric Min:1 M 1. UPI ID consists of the alias of the Payee (alias/proxy Max:255 Payee followed by the bank identifier. ID) (Ex: abc.123@bank) 84 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules 2. Permitted special characters are dot ‘.’ at ‘@’ and hyphen ‘-’ 3. Total length of UPI ID is inclusive of the bank identifier. Settlement settAmount 1..1 Numeric Min:0 M Settlement amount will be 0.00 if the amount Max:15 result = "FAILURE" Settlement amount will be the same as the org amount if the result = "SUCCESS" Settlement settCurrency 1..1 String Fixed M Default = INR currency value Unique approvalNum 1..1 Alphanumeric 6 C Mandatory if result = SUCCESS transaction reference number for approved transactions Transaction respCode 1..1 Alphanumeric Min:1 M IP to populate the relevant response code response code Max:20 per NIPL’s response/ error code document 85 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules Merchant’s regName 1..1 Alphanumeric Min:1 M It should contain the same name as the registered name Max:99 name of the Payee with the bank Original orgAmount 1..1 Numeric Min:0 M Format: 2 digits after the decimal. transaction Max:15 E.g. (Amount Value= “100.00”). It should amount be the same as the transaction amount. Response code in reversalResp 0..1 Alphanumeric Min :1 C Mandatory if type = REVERSAL case of Code Max :20 transaction reversal Settlement bank acNum 1..1 Alphanumeric Min :1 M account number Max :30 Merchant code 1..1 Numeric 4 M Classification Code IFSC code of the IFSC 1..1 Alphanumeric 11 M respective bank branch Type of account accType 1..1 String Fixed M List of values: value 1. SAVINGS 86 Strictly Private and Confidential RespPay Tag Description Occurrence Data Type Length M/O/C Rules 2. CURRENT 6.3. Check Transaction Status In the event of a ReqPay (CREDIT) API timeout, iUPI will initiate a ReqChkTxn API to the IP to verify the status of the credit. 1. If the IP does not respond with a RespChkTxn, NIPL will initiate a ReqPay (REVERSAL) to reverse the transaction. 2. If ReqPay (REVERSAL) also encounters a timeout, NIPL will classify the transaction as DEEMED and close it accordingly. 87 Strictly Private and Confidential 6.3.1. Check Transaction Request (ReqChkTxn) NIPL sends the check transaction request to the IP to check the status of the credit when no/late response is received for the credit request. Below is a sample request structure for the transaction status check API. 88 Strictly Private and Confidential Table 5: ReqChkTxn ReqChkTxn Tag Description Occurrence Data Type Length M/O/C Rules API Name ReqChkTxn 1..1 M API Schema namespace xmlns 1..1 String Min:1 M Max:255 Header 1..1 M This is a parent tag. Version of the API ver 1..1 Numeric Min:1 M Default = 2.0 Max:6 Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the API message Max:255 DDTHH:mm:ss.sssZ was generated where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. It changes with each leg of the transaction. Organisation ID of orgId 1..1 Numeric Min:1 M ID of NIPL will be passed in this message initiator Max:20 field Type of product prodType 0..1 String Fixed O Default = UPI value 89 Strictly Private and Confidential ReqChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Message identifier msgId 1..1 Alphanumeric Min:1 M It is unique to each transaction Max:35 and each API request and response Transaction information 1..1 M This is a parent tag. Unique identifier that id 1..1 Alphanumeric 35 M Transaction ID of ReqChkTxn shall remains consistent across contain the transaction ID of the both the request and the ReqPay type = CREDIT response for the check transaction API Remarks provided by the note 1..1 String Min:1 M Permitted special characters are Payer Max:50 dot ‘.’ and hyphen ‘-’ Reference ID is generated refId 1..1 Alphanumeric 35 M It remains consistent across both and used by the Payer PSP the request and the response. for internal tracking. Website URL of NIPL refUrl 1..1 Alphanumeric Min:1 M Default = http://www.npci.org.in/ Max:35 Reference category - to refCategory 1..1 Numeric Fixed O Default value is 00. identify the invoice value If the value is 02, then refUrl will category of the transaction have an invoice attachment link. 90 Strictly Private and Confidential ReqChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Subtype of transaction subType 1..1 String Min:1 M Default = “CREDIT” Max:20 Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the transaction was Max:255 DDTHH:mm:ss.sssZ initiated where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. Type of transaction type 1..1 String Min:1 M Default = “ChkTxn” Max:20 Original date of the orgTxnDate 0..1 ISODateTime Min:1 O Format: YYYY-MM- transaction Max:255 DDTHH:mm:ss.sssZ where 'T' serves as the delimiter, and 'Z' represents the Indian time. zone offset from GMT, which is +05:30. It remains the same throughout the transaction. Mode of initiating the initiationMode 1..1 Numeric 2 M List of values: transaction 00 = Default 01 = Offline Static QR Code 91 Strictly Private and Confidential ReqChkTxn Tag Description Occurrence Data Type Length M/O/C Rules 02 = Offline Static Secure QR Code 04 = Intent 05 = Secure Intent 15 = Offline Dynamic QR Code 16 = Offline Dynamic Secure QR Code 22 = Online Dynamic QR Code 23 = Online Dynamic Secure QR Code Original transaction ID orgTxnId 1..1 Alphanumeric 35 M orgTxnId of ReqChkTxn shall contain the txn.id of the ReqPay type = CREDIT Original message ID orgMsgId 0..1 Alphanumeric Min:1 O Max:35 Purpose of the transaction purpose 1..1 Numeric 2 M List of values: 11 = Offline Acceptance 62 = Online FCY Acceptance 66 = Online INR Acceptance Original retrieval reference orgRrn 0..1 Numeric 12 O number contains the respective custRef value 92 Strictly Private and Confidential ReqChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Customer reference custRef 1..1 Numeric 12 M number provided by the Payer PSP remains consistent across both the request and the response 6.3.2. Check Transaction Response (RespChkTxn) This API shall be used by the IP to confirm the status of CREDIT to NIPL. 93 Strictly Private and Confidential Below is a sample response structure for the transaction status check API. Table 6: RespChkTxn RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules API Name RespChkTxn 1..1 M API Schema namespace xmlns 1..1 String Min:1 M Max:255 Header 1..1 M This is a parent tag. 94 Strictly Private and Confidential RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Version of the API ver 1..1 Numeric Min:1 M Default = 2.0 Max:6 Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the API message Max:255 DDTHH:mm:ss.sssZ was generated where 'T' serves as the delimiter, and 'Z' represents the Indian time. zone offset from GMT, which is +05:30. It changes with each leg of the transaction. Organisation ID of orgId 1..1 Numeric Min:1 M During onboarding, NIPL assigns message initiator Max:20 the orgID to the IP. IP to pass the assigned ID here. Message identifier msgId 1..1 Alphanumeric Min:1 M It is unique to each transaction Max:35 and each API request and response Type of the product prodType 0..1 String Fixed O Default = UPI value Transaction information 1..1 M This is a parent tag. which is carried across 95 Strictly Private and Confidential RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules the system and is visible to all parties Unique identifier that id 1..1 Alphanumeric 35 M IP to pass the values as received remains consistent in the ReqChkTxn. across both the request and the response for the financial leg Remarks provided by the note 1..1 Alphanumeric Min:1 M Permitted special characters are Payer Max:50 dot ‘.’ and hyphen ‘-’ Reference ID is refId 1..1 Alphanumeric 35 M IP to pass the values as received generated and used by in the ReqChkTxn. the Payer PSP for internal tracking. Attachment/ website refUrl 1..1 Alphanumeric Min:1 M IP has the provision to pass the URL of IP Max:35 invoice attachment URL; else the IP can pass their website URL as default. 96 Strictly Private and Confidential RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Reference category - to refCategory 1..n Numeric Fixed M Default is 00. identify the category of Value If the value is 02, then refUrl will the transaction have an invoice attachment link. Customer reference custRef 1..1 Numeric 12 M IP to pass the values as received number provided by the in the ReqChkTxn. Payer PSP remains consistent across both the request and the response Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the transaction Max:255 DDTHH:mm:ss.sssZ was initiated where T is the delimiter and 'Z' represents the Indian time zone offset from GMT, which is +05:30. It remains the same throughout the transaction. Subtype of transaction subType 0..1 String Min:1 O Default = “CREDIT” Max:20 Type of transaction type 1..1 String Min:1 M Default = “ChkTxn” Max:20 97 Strictly Private and Confidential RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Purpose of the purpose 1..1 String Fixed M List of values: transaction value 11 = Offline Acceptance 62 = Online FCY Acceptance 66 = Online INR Acceptance Online/offline orgTxnDate 0..1 ISODateTime Min:1 O IP to pass the values as received transaction identifier Max:255 in the ReqPay. Mode of initiating the initiationMode 1..1 Numeric 2 M List of values: transaction 00 = Default 01 = Offline Static QR Code 02 = Offline Static Secure QR Code 04 = Intent 05 = Secure Intent 15 = Offline Dynamic QR Code 16 = Offline Dynamic Secure QR Code 22 = Online Dynamic QR Code 23 = Online Dynamic Secure QR Code 98 Strictly Private and Confidential RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Original transaction ID orgTxnId 1..1 Alphanumeric 35 M IP to pass the values as received in the ReqChkTxn. Original message ID. It orgMsgId 0..1 Alphanumeric Min:1 O contains the msgID of the Max:35 credit request. Response details 1..1 M This is a parent tag. Message ID of the reqMsgId 1..1 Alphanumeric Min:1 M IP to pass the value from ‘msgId’ corresponding API Max:35 from the ReqChkTxn API. request Result of the transaction result 1..1 String Min:1 M List of values: Max:20 1. SUCCESS 2. FAILURE Transaction error code errCode 1..1 Alphanumeric Min:1 C Mandatory only if result = Max:20 FAILURE IP to populate the relevant error code per NIPL’s response/ error code. Response reference 1..n M This is a parent tag. 99 Strictly Private and Confidential RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Type of reference type 1..1 String Fixed M Default = PAYEE value Number of times the seqNum 1..1 Numeric Min:1 M Default = 1 transaction is made Max:3 UPI ID of the Payee addr 1..1 Alphanumeric Min:1 M 1. UPI ID consists of the alias of (alias/proxy ID) Max:255 the Payee followed by the bank identifier. (Ex: abc.123@bank) 2. Permitted special characters are dot ‘.’ at ‘@’ and hyphen ‘-’ 3. Total length of UPI ID is inclusive of the bank identifier. Merchant Classification code 1..1 Numeric 4 M Code Response code respCode 1..1 Alphanumeric Min:1 M IP to populate the relevant Max:20 response code per NIPL’s response/ error code document Original transaction orgAmount 1..1 Numeric Min:0 M Format: 2 digits after the amount Max:15 decimal. E.g., Amount = 100.00 100 Strictly Private and Confidential RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules It should be the same as the txn amount. Settlement amount settAmount 1..1 Numeric Min:0 M Settlement amount will be 0.00 if Max:15 the result = "FAILURE" Settlement amount will be the same as the orgAmount if the result = "SUCCESS" Settlement currency settCurrency 1..1 String Fixed M Default = INR value Unique transaction approvalNum 1..1 Alphanumeric 6 C Mandatory only if result = reference number for SUCCESS approved transactions Merchant’s registered regName 1..1 Alphanumeric Min:1 M It should contain the same name name with the bank Max:99 as the name of the Payee Settlement bank account acNum 1..1 Alphanumeric Min:1 M number Max:30 IFSC code of the IFSC 1..1 Alphanumeric 11 M respective bank branch 101 Strictly Private and Confidential RespChkTxn Tag Description Occurrence Data Type Length M/O/C Rules Type of account accType 1..1 String Fixed M List of values: value 1. SAVINGS 2. CURRENT 6.4. Heartbeat API The UPI platform uses Heartbeat API to check the connectivity and monitor system uptime of the onboarded entities. This API can be initiated by both the parties, i.e., NIPL and the IP. The steps to perform Heartbeat API are as follows: 1. IP initiates ReqHbt API to NIPL. 2. NIPL sends a subsequent Ack to the ReqHbt API from the IP. 3. NIPL sends a RespHbt to the IP. 4. IP sends back an Ack to the RespHbt API from NIPL. Note: IP is expected to initiate an Hbt API call every 30 seconds (30 seconds to be set as configurable). NIPL initiates this API during troubleshooting. 102 Strictly Private and Confidential 6.4.1. ReqHbt Heartbeat API request is initiated by the IP to NIPL for checking system uptime. Below is the sample API message for Heartbeat API request. 103 Strictly Private and Confidential Table 7: ReqHbt API ReqHbt Tag Description Occurrence Data Type Length M/O/C Rules API Name ReqHbt 1..1 M Name of the API API Schema xmlns 1..1 Alphanumeric Min:1 M Default = ‘http://npci.org/upi/schema/’ namespace Max:255 Header 1..1 String Fixed M This is a parent tag. value Version of the ver 1..1 Numeric Min:1 M Default = 2.0 API Max:6 Timestamp ts 1..1 ISODateTime Min:1 M Format: YYYY-MM-DDTHH:mm:ss.sssZ indicating when Max:255 where 'T' serves as the delimiter, and 'Z' the API message represents the Indian time zone offset from was generated GMT, which is +05:30. Organisation ID orgId 1..1 Numeric Min:1 M ID of NIPL will be passed in this field of message Max:20 initiator Message msgId 1..1 Alphanumeric Min:1 M 1. It is unique to each transaction and each identifier Max:35 API request and response Type of product prodType 0..1 Alphanumeric Fixed O Default = UPI value 104 Strictly Private and Confidential ReqHbt Tag Description Occurrence Data Type Length M/O/C Rules Transaction 1..1 String Fixed M This is a parent tag. i nformation value Unique identifier id 1..1 Alphanumeric 35 M 1. Transaction ID is unique for every that remains transaction. consistent across both the 2. It should always be 35 digits. request and the 3. The first 3 digits should be the bank response participation code assigned by NIPL followed by 32 digits that are generated by UUID logic. 4. No special characters are permitted. Remarks note 1..1 Alphanumeric Min:1 M Permitted special characters are dot ‘.’ and entered by IP Max:50 hyphen ‘-’ Reference ID is a refId 1..1 Alphanumeric Min:1 M Value should be the same as the txn ID to be unique identifier Max:35 passed. consistent across both the request and the response Public URL of IP refUrl 1..1 Alphanumeric Min:1 M IP to pass its website URL. Max:35 105 Strictly Private and Confidential ReqHbt Tag Description Occurrence Data Type Length M/O/C Rules Type of type 1..1 String Fixed M Default = Hbt transaction value Request time set ts 1..1 ISODateTime Min:1 M Format: YYYY-MM-DDTHH:mm:ss.sssZ by IP Max:255 where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. Heartbeat value Value of risk Value 1..1 String Fixed M Default = NA evaluation value 6.4.2. RespHbt Heartbeat API response is sent by NIPL to the IP. 106 Strictly Private and Confidential Below is the sample API message for Heartbeat API response. Table 8: RespHbt API RespHbt Tag Description Occurrence Data Type Length M/O/C Rules API Name RespHbt 1..1 M Name of the API. API Schema xmlns 1..1 Alphanumeric Min:1 M Default= namespace Max:255 ‘http://npci.org/upi/schema/’ Header 1..1 String Fixed M This is a parent tag. value Version of the API ver 1..1 Numeric Min:1 M Default = 2.0 Max:6 Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the API message Max:255 DDTHH:mm:ss.sssZ was generated where 'T' serves as the delimiter, and 'Z' represents the Indian time 107 Strictly Private and Confidential RespHbt Tag Description Occurrence Data Type Length M/O/C Rules zone offset from GMT, which is +05:30. It changes with each leg of the transaction. Organisation ID of orgId 1..1 Numeric Min:1 M During onboarding, NIPL assigns the message initiator Max:20 orgID to the IP. IP to pass the assigned ID here. Message identifier msgId 1..1 Alphanumeric Min:1 M 1. It is unique to each transaction Max:35 and each API request and response NIPL product type prodType 0..1 Alphanumeric Fixed O Default =UPI value Org ID of the IP destinationOr 0..1 Numeric Min:1 O gId Max:20 Transaction 1..1 String Fixed M This is a parent tag information value Unique identifier that id 1..1 Alphanumeric 35 M 1. Transaction ID is unique for remains consistent every transaction. across both the request and the 2. It should always be 35 digits. response 3. The first 3 digits should be the bank participation code assigned by NIPL followed by 108 Strictly Private and Confidential RespHbt Tag Description Occurrence Data Type Length M/O/C Rules 32 digits that are generated by UUID logic. Remarks note 1..1 Alphanumeric Min:1 M Permitted special characters are Max:50 dot ‘.’ and hyphen ‘-’ Reference ID is a refId 1..1 Alphanumeric Min:1 M If value is the same as the txn ID, it unique identifier Max:35 can be passed. consistent across both the request and the response Public URL of IP/NIPL refUrl 1..1 Alphanumeric Min:1 M Website of IP or NIPL Max:35 Type of transaction type 1..1 String Fixed M Default = Hbt value Timestamp indicating ts 1..1 ISODateTime Min:1 M Format: YYYY-MM- when the request was Max:255 DDTHH:mm:ss.sssZ initiated where 'T' serves as the delimiter, and 'Z' represents the Indian time zone offset from GMT, which is +05:30. It changes with each leg of the transaction. Transaction response 1..1 M 109 Strictly Private and Confidential RespHbt Tag Description Occurrence Data Type Length M/O/C Rules Message ID of reqMsgId 1..1 String Min:1 M The value from ‘msgId’’ from the corresponding API Max:35 ReqHbt API is to be passed here. request Result of the result 1..1 String 35 M List of values: transaction 1. SUCCESS 2. FAILURE Error code of the errCode 1..1 Alphanumeric Min:1 C Mandatory only if result = FAILURE transaction Max:20 IP to populate the relevant error code as per NIPL’s response / error code. 110 Strictly Private and Confidential 7. API BRIEFLY 1. Asynchronous communication Principle: APIs are non-blocking; the system does not wait for a response after sending a request. Benefits: a. Improves system responsiveness. b. Enables the parallel processing of multiple transactions. c. Reduces latency and resource locking. How it works: a. A request is initiated with a unique transaction ID. b. The system immediately acknowledges receipt of the request. c. The actual response is initiated later through a separate response API, using the same transaction ID for reference. 2. Scalability and performance Principle: Asynchronous APIs allows the system to scale horizontally and manage high loads. Benefits: a. Supports high transaction volumes. b. Avoids bottlenecks caused by synchronous waiting. c. Enables load balancing and distributed processing. How it works: a. Incoming requests are queued and processed independently. b. Multiple backend services can process transactions in parallel. c. Load balancers distribute traffic across multiple nodes. 3. Transaction ID for correlation Principle: Every API call must include a unique transaction ID. Benefits: a. Ensures traceability and auditability. b. Allows the accurate matching of requests and responses. c. Facilitates error handling. How it works: a. The client generates a unique transaction ID for each request. b. This ID is included in both the request and the asynchronous response. c. Systems use this ID to correlate and track the transaction lifecycle. 4. Secure and standardised communication Principle: All APIs must use Hypertext Transfer Protocol Secure (HTTPS) and XML for secure and consistent data exchange. Benefits: a. HTTPS ensures encrypted transmission. b. XML provides a structured, interoperable format. c. Ensures compliance with regulatory and industry standards. 111 Strictly Private and Confidential How it works: a. All API endpoints are exposed over HTTPS. b. Request and response payloads are formatted in XML. c. Digital signatures and encryption (for Cred block) are applied to protect sensitive data. 5. Acknowledgement mechanism (ACK) Principle: Every request must be acknowledged immediately, even if processing is deferred. Benefits: a. Confirms that the request is received and queued. b. Prevents duplicate submissions of request/response. c. Improves user experience with instant feedback. How it works: a. Upon receiving a request, the server queues for processing. b. An immediate ACK is sent back to the client. c. The actual processing result is sent later via the response API. 6. Uniform API design across participants Principle: The same REST based APIs are used by UPI and all its participants (banks, PSPs, TPAPs). Benefits: a. Ensures interoperability across the ecosystem. b. Simplifies integration and reduces development effort. c. Promotes standardisation and consistency. How it works: a. NIPL defines a common API specification. b. All participants implement the same set of endpoints and data structures. c. This uniformity allows participants to interact with each other seamlessly. 7.1. API Protocol 1. All the APIs shall be initiated as an HTTPS call and acknowledged with an Ack message. 2. Following is the URL format for all APIs under the unified interface: https:///iUPI///urn:txnid: a. host – API server address (Actual production server address will be provided to members at the time of rollout and all API clients should ensure that actual URL is configurable). b. iUPI – static value denoting the root of all API URL paths under the Unified Payment Interface – UPI International Stack. c. api – name of the API URL endpoint. 112 Strictly Private and Confidential d. ver – version of the API. Revised versions of the same API may be available for supporting gradual migration. As of this specification, the default version is "2.0". e. txnId– Transaction id which will be used for load balancing purpose at UPI end. 3. All APIs have the same acknowledgement response as given below: a. Ack – root element name of the acknowledgement message. b. api – name of the API for which acknowledgement is given out. c. reqMsgId - message ID of the input for which the acknowledgement is given out. d. err - this denotes any error in receiving the original request message. e. ts - the timestamp at which the receiver sends the acknowledgement f. Sample for successful ACK is given below: Negative acknowledgement (NACK) is provided by NIPL. NIPL provided the HTTPS response code 200 in case of the NACK to IP. Below is the sample for NACK: X09 TXN.ORGTXNDATE SHOULD BE WITHIN 90 DAYS 113 Strictly Private and Confidential 7.2. Message Security, Trust, And Authenticity Key security features of the UPI solution: 1. End-to-end security and data protection: Explanation: This means that from the moment a transaction is initiated to its completion, the data is protected. This is crucial in preventing unauthorised access or tampering with transaction data. Importance: It ensures that sensitive information, such as financial details, remains secure throughout the transaction process, safeguarding both the sender's and the receiver's information. 2. Digital signature for message integrity and authentication: Explanation: Digital signatures are used to verify the authenticity of the sender and ensure that the message has not been altered during transmission. This is achieved through public-key cryptography, where the sender signs the message with their private key and the recipient verifies it using the sender's public key. Importance: This mechanism prevents impersonation and ensures that transactions are genuine and have not been tampered with, thereby maintaining the trust and integrity of the NPCI system. 3. Secure message exchange protocol: Explanation: The use of HTTPS for communication ensures that all data exchanged between IP participants and the NPCI platform is encrypted via SSL certificate. Additionally, the use of XML-formatted messages that are digitally signed with the RSA-SHA256 algorithm provides confidentiality, integrity, and non-repudiation. Importance: This ensures that all communication is secure, preventing eavesdropping, tampering, and man-in-the-middle attacks. The digital signature with RSA-SHA256 algorithm provides a high level of security, making it virtually impossible for an attacker to alter the message without being detected, and ensures that the sender cannot deny having sent the message. 7.2.1 IP Whitelisting 1. IP whitelisting will be done at the firewall level. 2. This is to filter out messages from unrecognised sources. During PSP on boarding, the IP address of the PSP will need to be configured into the NIPL firewall. 7.2.2 Certificate Requirement The following two types of certificates are required: Sr. No. Requirement Key Length Certificate Type 1 SSL RSA 2048 Class 3 2 Digital Signing RSA 2048 Class 3 114 Strictly Private and Confidential A. Certificates used by NIPL: Sr. No. Key Used By Shared By Reason 1 SSL NIPL IP For SSL connection 2 Digital Signing NIPL IP To verify digital signature of the XML message B. Certificates used by the IP: Sr. No. Key Used By Shared By Reason 1 SSL IP NIPL For SSL connection 2 Digital Signing IP NIPL To verify digital signature of the XML message 7.2.3 Protection Against Phishing 1. The sender, i.e., the owner of the merchant / individual data must ensure that the customers against whom requests are initiated must be KYC compliant. 2. It is the responsibility of the sender to validate the details of the customer, whether the customer is a valid customer or not before sending the request. 3. Data compliance shall be as per RBI guidelines provided for the respective payment models. 7.2.4 Security Considerations UPI provides strong end-to-end security and data protection. To maintain security and authenticity of the transactions, all API messages are generated with a digital signature by the sender which is validated by the receiver. Further, message communication between the UPI participant and UPI will be in XML format over HTTPS and all the messages will be digitally signed using RSA-SHA256. For storing data at the IP participants’ end, the IP participants need to follow the security standards applicable to them. NIPL will support TLS 1.2 and above. Signer certificate will be used for the message signing and validation. The SSL certificate will be used for Secure TLS communication. For data security, the following classes of information are defined: 1. Sensitive Data – This includes data such as PIN, passwords, etc. This data is not to be stored and should be transported in encrypted form. 2. Private Data – This includes data such as account numbers. This information may be stored, but only in encrypted form. 115 Strictly Private and Confidential 3. Non-Sensitive data – This includes data such as name and transaction history (amount, timestamp, response code, location, etc.) and can be stored in unencrypted form. 7.2.5 Digital Signature Guidelines (For Reference Only) This section provides the guidelines for generating and validating DOM based XML signatures following JSR 105. Following is a Java sample code with instructions: 1. This java tool SignatureGenUtil.java is currently configured to use RSA 2048 bit signer. And tested in jdk "1.8.0_51". 2. Please change the qualified paths under main method - qualifiedPathXMLToBeSigned, generatedSignedXML, targetSignedXML respectively pointing to the xml to be signed, where the signed xml will be generated and path of file whose signature will be validated. 3. Please modify the signer passphrase at line number 208 ('password') as required. Default is passphrase being used in issued test doc signers. 4. Please modify the signer and certificate qualified path in line number 203 & 218 respectively under init(). File signerFile = new File("D:\\signer\\signer.p12"); java.security.cert.Certificate cert = getCertificate("D:\\signer\\signer.crt"); 5. Java XML Digital Signature API Specification (JSR 105) is being followed as best practice for xml signature. Hence, the xml signature is generated on DOM. 6. For any details regarding the XML canonicalisation, please refer to http://www.w3.org/TR/xml-exc-c14n/ 7. For RSA with SHA256 following is the signature method URI http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 One may need to use any JSR 105 provider depending upon the java version used. 116 Strictly Private and Confidential 117 Strictly Private and Confidential 118 Strictly Private and Confidential 119 Strictly Private and Confidential 120 Strictly Private and Confidential Below is the sample XML request with digital signature: Hit URI: https:///upi/ReqPay/2.0/urn:txnid:ABCef6fdfde87454cc084071ca3725e2979 Received Message: 121 Strictly Private and Confidential 2.0 122 Strictly Private and Confidential d7c8r4DwxkC+XD+B+fqH27Zvdy5JhJPMiU9kbvPlSZE= WS2WY36wk/wkptfS3gaYoqXGJ/n/jYGTTwOOZZ8y2xnnP2X/ vOsTNyk9UQx+jjRyp+zkHmPbCEQmwZXu/z1qzGqvmgac6So1d9iEo6gGyBSbs+r3 qV4MqTMQVooRAJ7RN1qnU6hvL/+aKNsrLzHIACHnmLW6wQoDRtVGX/2raGW08cB7 4VI8ZBb8t7fhTMYrK5zvPyZK33u5J2qUDz24gVvx0WAsVDM2QJQ+2svLyUUxRdxg hMTHeZeDHiq/quM46sngjnj+TqPghwYNST+ofB5MjaMbysJIJY5s8Z7URnJ5BJUZ zXK E91mPaCghCH9HoVooEgOTsZ9mVrBGUrjDMQ== vT5CxuS4WVHnDQPb4VEMB7EnaPcBJ73pKP127ACIsN3HEgJw0kil+WQ ZaAmDQ6sJT5Q1gfAbvDAUZa43Ya3gOYC34yNt8MsXF7Aw10F936sVxsCAdYtJ2/j 7Ir+Br6BkOP0ovfg8l4r+MA61HXTWehwN4QFLZjCMUIaSQ13029aobgvVdB+wc3o U9pdWA004wZxD1egbCefO+6Po+GrpETUTGm+scBYu+e06x37JfuimWNbQyph5dmn OmHO0KjdhJQIpgw8ck7LK9YWn/DWRkK2M20jLI+QFKCJhpKUkIIdwbJWRNJgePAO rLMdTBp1doAf2HKiZ/ZQf7IfDyyDyQ== AQAB 123 Strictly Private and Confidential 8. ERROR CODES FOR ACCEPTANCE CODE DESC TD/BD API RespPay Debit, RespPay HS BANKS HSM IS Credit, RespPay Debit DOWN(REMITTER) TD (Mandate) & RespChkTxn API UNABLE TO PROCESS DUE TO RespPay Debit, RespPay IR INTERNAL EXCEPTION TD Credit, RespPay Debit AT SERVER/CBS/ETC ON (Mandate) & REMITTER SIDE RespChkTxn API RespPay Debit, RespPay XT CUT-OFF IS IN PROCESS (REMITTER) TD Credit, RespPay Debit (Mandate) & RespChkTxn API RespPay Debit, RespPay XY REMITTER CBS OFFLINE TD Credit, RespPay Debit (Mandate) & RespChkTxn API REMITTER SWITCH IS RespPay Debit, RespPay ZK INOPERATIVE/NODE OFFLINE TD Credit, RespPay Debit (Reserved for future purpose) (Mandate) & RespChkTxn API B7 BANK CARD MANAGEMENT SYSTEM IS DOWN TD RespRegMob This is Response code 91 Response Timeout TD description of RB from UPI side in RespPay 92 Invalid NBIN TD Resppay UNABLE TO PROCESS DUE TO RespPay Debit, RespPay UB INTERNAL EXCEPTION AT SERVER/CBS/ETC ON TD Credit, RespPay Debit (Mandate) & BENEFICIARY SIDE RespChkTxn API RespPay Debit, RespPay UP PSP TIME-OUT TD Credit, RespPay Debit (Mandate) & RespChkTxn API RespPay Debit, RespPay X7 MERCHANT NOT REACHABLE TD Credit, RespPay Debit (ACQURIER) (Mandate) & RespChkTxn API 124 Strictly Private and Confidential CODE DESC TD/BD API RespPay Debit, RespPay XU CUT-OFF IS IN PROCESS Credit, RespPay Debit (BENEFICIARY) TD (Mandate) & RespChkTxn API RespPay Debit, RespPay Y1 BENEFICIARY CBS OFFLINE TD Credit, RespPay Debit (Mandate) & RespChkTxn API ACQUIRER/BENEFICIARY RespPay Debit, RespPay ZC UNAVAILABLE TD Credit, RespPay Debit (Reserved for future purpose) (Mandate) & RespChkTxn API BENEFICIARY OR ACQUIRING SWITCH RespPay Debit, RespPay ZJ IS INOPERATIVE/NODE TD Credit, RespPay Debit OFFLINE (Reserved for future (Mandate) & RespChkTxn API purpose) RespPay Debit, RespPay B6 MISMATCH IN PAYMENT DETAILS TD Credit, RespPay Debit (Mandate) & RespChkTxn API RR DEBIT REVERSAL TIMEOUT - WITHOUT INITIATING CREDIT TD Response code in Settlement DEBIT REVERSAL TIMEOUT - R9 AFTER CREDIT BD Response code in Settlement FAILURE/TIMEOUT Response codes in RespPay DUPLICATE RRN FOUND IN THE Debit, RespPay Credit, DT TRANSACTION. (REMITTER) BD RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay LD UNABLE TO PROCESS DEBIT IN BANK’S POOL/BGL ACCOUNT BD Debit, RespPay Credit, RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay VD INCORRECT AMOUNT RULE BD Debit, RespPay Credit, RespPay Debit (Mandate) & RespChkTxn API XB INVALID TRANSACTION OR IF BD Response codes in RespPay MEMBER IS NOT ABLE Debit, RespPay Credit, 125 Strictly Private and Confidential CODE DESC TD/BD API TO FIND ANY APPROPRIATE RespPay Debit (Mandate) & RESPONSE CODE (REMITTER) RespChkTxn API Response codes in RespPay XF FORMAT ERROR (INVALID Debit, RespPay Credit, FORMAT) (REMITTER) BD RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay XH ACCOUNT DOES NOT EXIST (REMITTER) BD Debit, RespPay Credit, RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay XJ REQUESTED FUNCTION NOT Debit, RespPay Credit, SUPPORTED (REMITTER) BD RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay XN NO CARD RECORD (REMITTER) BD Debit, RespPay Credit, RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay XP TRANSACTION NOT PERMITTED TO CARDHOLDER (REMITTER) BD Debit, RespPay Credit, RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay XR RESTRICTED CARD, DECLINE (REMITTER) BD Debit, RespPay Credit, RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay NO FINANCIAL ADDRESS Debit, RespPay Credit, XX RECORD FOUND BD RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay YC DO NOT HONOUR (REMITTER) BD Debit, RespPay Credit, RespPay Debit (Mandate) & RespChkTxn API TRANSACTION FREQUENCY Response codes in RespPay Z7 LIMIT EXCEEDED BD Debit, RespPay Credit, AS SET BY REMITTING MEMBER RespPay Debit (Mandate) & RespChkTxn API PER TRANSACTION LIMIT Z8 EXCEEDED AS SET BY BD Response codes in RespPay REMITTING MEMBER Debit, RespPay Credit, 126 Strictly Private and Confidential CODE DESC TD/BD API RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay ZD VALIDATION ERROR BD Debit, RespPay Credit, RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay ZF TRANSACTION NOT PERMITTED Debit, RespPay Credit, TO DEVICE BD RespPay Debit (Mandate) & RespChkTxn API LIMIT EXCEEDED FOR Response codes in RespPay ZU REMITTING BANK/ISSUING BD Debit, RespPay Credit, BANK RespPay Debit (Mandate) & RespChkTxn API Response codes in RespPay ZX INACTIVE OR DORMANT BD Debit, RespPay Credit, ACCOUNT (REMITTER) RespPay Debit (Mandate) & RespChkTxn API Incorrect Account details due to Response codes in RespPay MR Amalgamated/ Merged Activity on Remitter BD Debit, RespPay Credit, RespPay Debit (Mandate) & Side (Remitter) RespChkTxn API B2 ACCOUNT LINKED WITH MULTIPLE NAMES BD RespListAccount MOBILE NUMBER REGISTERED BR WITH MULTIPLE CUSTOMER BD RespListAccount IDS REGISTRATION IS TEMPORARY RN BLOCKED BD RespRegMob CN Country/ Currency not supported BD Resppay RD Request Decline by the bank BD Resppay SA TRANSACTION NOT PERMITTED FOR THIS A/C TYPE (OD) BD RespAuthDetail 01 Unable to Process Reversal BD RespPay Debit, RespPay NO ORIGINAL REQUEST Credit, RespPay Debit NO FOUND DURING DEBIT/CREDIT BD (Mandate) & RespChkTxn API 127 Strictly Private and Confidential CODE DESC TD/BD API RespPay Debit, RespPay YI INVALID RESPONSE CODE BD Credit, RespPay Debit (Mandate) & RespChkTxn API RespPay Debit, RespPay AM MPIN NOT SET BY CUSTOMER BD Credit, RespPay Debit (Mandate) & RespChkTxn API REGISTERED MOBILE NUMBER RespPay Debit, RespPay B1 LINKED TO THE ACCOUNT HAS BEEN BD Credit, RespPay Debit (Mandate) & CHANGED/REMOVED RespChkTxn API RespPay Debit, RespPay QU PAYER ACCOUNT HAS Credit, RespPay Debit CHANGED(PAYER) BD (Mandate) & RespChkTxn API RespPay Debit, RespPay Credit, RespPay Debit XD INVALID AMOUNT (REMITTER) BD (Mandate) & RespChkTxn API RespPay Debit, RespPay XL EXPIRED CARD, DECLINE (REMITTER) BD Credit, RespPay Debit (Mandate) & RespChkTxn API RespPay Debit, RespPay YA LOST OR STOLEN CARD (REMITTER) BD Credit, RespPay Debit (Mandate) & RespChkTxn API RespPay Debit, RespPay YE REMITTING ACCOUNT BLOCKED/FROZEN BD Credit, RespPay Debit (Mandate) & RespChkTxn API RespPay Debit, RespPay Z6 NUMBER OF PIN TRIES EXCEEDED BD Credit, RespPay Debit (Mandate) & RespChkTxn API INSUFFICIENT FUNDS IN RespPay Debit, RespPay Z9 CUSTOMER (REMITTER) BD Credit, RespPay Debit ACCOUNT (Mandate) & RespChkTxn API 128 Strictly Private and Confidential CODE DESC TD/BD API RespPay Debit, RespPay ZM INVALID MPIN BD Credit, RespPay Debit (Mandate) & RespChkTxn API RespPay Debit, RespPay FL FIRST TRANSACTION LIMIT Credit, RespPay Debit EXCEEDED BD (Mandate) & RespChkTxn API RespPay Debit, RespPay FP FREEZE PERIOD FOR FIRST TIME USER BD Credit, RespPay Debit (Mandate) & RespChkTxn API AJ CARD IS NOT ACTIVE BD RespRegMob INVALID MPIN RM ( VIOLATION OF POLICIES WHILE SETTING/CHANGING BD RespSetCred MPIN ) SP INVALID/INCORRECT ATM PIN BD RespRegMob KN KYC not Available BD RespValQr SD Service disable on UPI/ Customer is not active BD RespPay IN International Service not activated/disabled BD RespPay RespPay Debit, RespPay DF DUPLICATE RRN FOUND IN THE TRANSACTION. (BENEFICIARY) BD Credit, RespPay Debit (Mandate) & RespChkTxn API: UNABLE TO PROCESS CREDIT RespPay Debit, RespPay LC FROM BANK’S POOL/BGL BD Credit, RespPay Debit ACCOUNT (Mandate) & RespChkTxn API: RespPay Debit, RespPay ZY INACTIVE OR DORMANT ACCOUNT (BENEFICIARY) BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay IV Invalid verification token BD Credit, RespPay Debit (Mandate) & RespChkTxn API: 129 Strictly Private and Confidential CODE DESC TD/BD API RespPay Debit, RespPay PE Payment validity expired BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay X1 RESPONSE NOT RECEIVED Credit, RespPay Debit WITHIN TAT AS SET BY PAYEE BD (Mandate) & RespChkTxn API: RespPay Debit, RespPay YG MERCHANT ERROR (PAYEE PSP) BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay UA PSP NOT SUPPORTED BY UPI BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay RESTRICTED CARD, DECLINE Credit, RespPay Debit XS (BENEFICIARY) BD (Mandate) & RespChkTxn API: RespPay Debit, RespPay YB LOST OR STOLEN CARD (BENEFICIARY) BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay YD DO NOT HONOUR (BENEFICIARY) BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay YF BENEFICIARY ACCOUNT BLOCKED/FROZEN BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay YH MERCHANT ERROR(ACQUIRING BANK) BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay ZR INVALID OTP BD Credit, RespPay Debit (Mandate) & RespChkTxn API: 130 Strictly Private and Confidential CODE DESC TD/BD API RespPay Debit, RespPay ZS OTP EXPIRED BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay ZT OTP TRANSACTION LIMIT Credit, RespPay Debit EXCEEDED BD (Mandate) & RespChkTxn API: ZV INCORRECT OTP (Reserved for future purpose) BD ACCOUNT IS ALREADY RZ REGISTERED WITH MBEBA BD RespListAccount FLAG AS 'Y' RespPay Debit, RespPay ZA TRANSACTION DECLINED BY Credit, RespPay Debit CUSTOMER BD (Mandate) & RespChkTxn API: RespPay Debit, RespPay ZG VPA RESTRICTED BY CUSTOMER BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RA PAYER AND PAYEE ACCOUNT SHOULD NOT BE EQUAL BD RespAuthDetails RespPay Debit, RespPay 15 ISSUER NOT LIVE ON UPI BD Credit, RespPay Debit (Mandate) & RespChkTxn API: SUSPECTED FRAUD, 59 DECLINE/TRANSACTIONS DECLINED BASED ON BD same as KI RISKSCORE BY REMITTER RespPay Debit, RespPay CI COMPLIANCE ERROR CODE FOR ISSUER BD Credit, RespPay Debit (Mandate) & RespChkTxn API: SUSPECTED FRAUD, DECLINE / RespPay Debit, RespPay K1 TRANSACTIONS DECLINED BASED ON RISK BD Credit, RespPay Debit (Mandate) & RespChkTxn SCORE BY REMITTER API: 131 Strictly Private and Confidential CODE DESC TD/BD API TRANSACTION CANNOT BE RespPay Debit, RespPay XV COMPLETED. COMPLIANCE VIOLATION BD Credit, RespPay Debit (Mandate) & RespChkTxn (REMITTER) API: TRANSACTION NOT PERMITTED TO THE ACCOUNT (EXAMPLE: MINOR ACCOUNT, RespPay Debit, RespPay B3 PROPRIETOR ACCOUNT,LEGAL BD Credit, RespPay Debit CASE AGAINST THIS ACCOUNT (Mandate) & RespChkTxn ETC., NRE (AS PER BANK’S API: POLICY)) RespPay Debit, RespPay CA COMPLIANCE ERROR CODE Credit, RespPay Debit FOR ACQUIRER BD (Mandate) & RespChkTxn API: TRANSACTION CANNOT BE RespPay Debit, RespPay XW COMPLETED. COMPLIANCE VIOLATION BD Credit, RespPay Debit (Mandate) & RespChkTxn (BENEFICIARY) API: SUSPECTED FRAUD, DECLINE / TRANSACTIONS DECLINED RespPay Debit, RespPay ZI BASED BD Credit, RespPay Debit ON RISK SCORE BY (Mandate) & RespChkTxn BENEFICIARY API: RespPay Debit, RespPay SPAM COLLECT DECLINED BY Credit, RespPay Debit S0 PSP BD (Mandate) & RespChkTxn API: RespPay Debit, RespPay S1 PAYEE IS REPORTED AS SPAM Credit, RespPay Debit UNDER RULE 1 BD (Mandate) & RespChkTxn API: RespPay Debit, RespPay S2 PAYEE IS REPORTED AS SPAM UNDER RULE 2 BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay S3 PAYEE IS REPORTED AS SPAM UNDER RULE 3 BD Credit, RespPay Debit (Mandate) & RespChkTxn API: `01 Unable to process reversal TD RespPay 132 Strictly Private and Confidential CODE DESC TD/BD API S98 ISSUER_DISPATCH_FAILED TD RespPay U13 EXTERNAL ERROR TD UPI error code sheet - Response Code U28 REMITTER BANK NOT AVAILABLE TD UPI error code sheet - Response Code UG1 Response Activation TimeOut TD Activation leg UPI error code sheet - HS3 HSM communication error TD Response Code description in UPI sheet - S96 REMITTER_DISPATCH_FAILED TD REMITTER_DISPATCH_FAILE D U16 RISK THRESHOLD EXCEEDED BD UPI error code sheet - Response Code U78 Beneficiary Bank offline TD UPI error code sheet - Response Code REMITTER BANK DEEMED HIGH UPI error code sheet - U90 RESPONSE TIME CHECK TD DECLINE Response Code BENEFICIARY BANK DEEMED U91 HIGH RESPONSE TIME CHECK TD UPI error code sheet - DECLINE Response Code DEBIT REVERSAL DECLINED BY ND ND - WITHOUT INITIATING TD RespPay (Debit- Reversal) CREDIT DEBIT REVERSAL DECLINED BY OD OD - WITHOUT INITIATING TD RespPay (Debit- Reversal) CREDIT DEBIT REVERSAL DECLINED BY UR 96 - TD RespPay (Debit- Reversal) WITHOUT INITIATING CREDIT DEBIT REVERSAL DECLINED BY U9 96 - AFTER CREDIT TD RespPay (Debit- Reversal) FAILURE/TIMEOUT RS DEBIT REVERSAL SUCCESS - WITHOUT INITIATING CREDIT NA RespPay (Debit- Reversal) DEBIT REVERSAL SUCCESS - S9 AFTER CREDIT NA RespPay (Debit- Reversal) FAILURE/TIMEOUT 133 Strictly Private and Confidential CODE DESC TD/BD API RB Deemed Success Deemed RespPay M16 AI MODEL DECLINE BD UPI error code sheet - Response Code PSP REQUEST CREDIT PAY U26 ACKNOWLEDGEMENT IS NOT TD UPI error code sheet - RECEIVED Response Code DEVICE FINGERPRINT UPI error code sheet - U66 MISMATCH BD Response Code S95 BENEFICIARY_DISPATCH_FAILE D BD UPI error code sheet - Response Code INVALID TRANSACTION OR IF RespPay Debit, RespPay Credit, RespPay Debit XC MEMBER IS NOT ABLE TO FIND BD ANY APPROPRIATE RESPONSE (Mandate) & RespChkTxn API: U29 ADDRESS RESOLUTION IS FAILED NA UPI error code sheet - Response Code RespPay Debit, RespPay ZH INVALID VIRTUAL ADDRESS BD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay ZE TRANSACTION NOT PERMITTED TO VPA by the PSP BD Credit, RespPay Debit (Mandate) & RespChkTxn API: U14 ENCRYPTION ERROR TD UPI error code sheet - Response Code UPI error code sheet - U09 REQAUTH TIME OUT FOR PAY TD Response Code S93 PAYEE_PSP_THROTTLE_DECLIN E_OUTGOING_COUN TD UPI error code sheet - Response Code U31 CREDIT HAS BEEN FAILED BD UPI error code sheet - Response Code U48 TRANSACTION ID IS NOT PRESENT TD UPI error code sheet - Response Code S94 PAYEE_PSP_THROTTLE_DECLIN E_RESPONSE_TIME TD UPI error code sheet - Response Code U94 PAYEE PSP THROTTLE DECLINE TD UPI error code sheet - Response Code 134 Strictly Private and Confidential CODE DESC TD/BD API S97 ADD_RESLN_DISPATCH_FAILE D TD UPI error code sheet - Response Code 00 Success Success Success ADEQUATE FUNDS NOT RespPay Debit, RespPay AVAILABLE IN THE ACCOUNT Credit, RespPay Debit IE BECAUSE FUNDS HAVE BEEN BD (Mandate) & RespChkTxn BLOCKED FOR MANDATE API: FD FRM Decline BD RespPay RespPay Debit, RespPay VM NATURE OF DEBIT NOT Credit, RespPay Debit ALLOWED IN ACCOUNT TYPE BD (Mandate) & RespChkTxn API: PA PAN NOT VALID BD-CR TRANSACTION ID OR AMOUNT RespPay Debit, RespPay U54 IN CREDENTIAL BLOCK DOES NOT MATCH WITH THAT IN TD Credit, RespPay Debit (Mandate) & RespChkTxn REQPAY API: HS1 HSM Offline TD UPI/iUPI error ID Invalid Device id TD RespPay Debit, RespPay S99 Graceful Decline TD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay U30 DEBIT HAS BEEN FAILED TD Credit, RespPay Debit (Mandate) & RespChkTxn API: PSP REQUEST PAY DEBIT RespPay Debit, RespPay U53 ACKNOWLEDGEMENT NOT TD Credit, RespPay Debit RECEIVED (Mandate) & RespChkTxn API: O2 Aadhaar number does not have verified mobile BD O3 Aadhaar number does not have both email and mobile BD RespPay Debit, RespPay U19 REQUEST AUTHORISATION IS DECLINED BD Credit, RespPay Debit (Mandate) & RespChkTxn API: 135 Strictly Private and Confidential CODE DESC TD/BD API RespPay Debit, RespPay U96 PAYER AND PAYEE Credit, RespPay Debit IFSC/ACNUM CAN'T BE SAME BD (Mandate) & RespChkTxn API: RespPay Debit, RespPay BT ACQUIRER/BENEFICIARY Credit, RespPay Debit UNAVAILABLE(TIMEOUT) TD (Mandate) & RespChkTxn API: RespPay Debit, RespPay UT REMITTER/ISSUER UNAVAILABLE (TIMEOUT) TD Credit, RespPay Debit (Mandate) & RespChkTxn API: RespPay Debit, RespPay XK REQUESTED FUNCTION NOT Credit, RespPay Debit SUPPORTED (BENEFICIARY) BD (Mandate) & RespChkTxn API: RespPay Debit, RespPay PAYER ACCOUNT HAS Credit, RespPay Debit VJ CHANGED (REMITTER) BD (Mandate) & RespChkTxn API: UG2 REQUEST ACTIVATION IS FAILED TD Error received by UPI/iUPI UG3 RESPONSE VALQR TIMEOUT TD ReqValQr UG4 REQUEST VALQR IS FAILED TD Error received by UPI/iUPI UG5 FOREX ERROR IN VALQR TD RespValAdd, RespValQr UG6 QR payload Invalid/ not found BD Error received by UPI/iUPI REMITTER BANK DOES NOT UB9 SUPPORT VERSION BD UPI error U30 DEBIT HAS BEEN FAILED TD UPI error U31 CREDIT HAS BEEN FAILED TD UPI error U09 REQAUTH TIME OUT (valadd timeout) TD RespFXRate, ReqBooking NSTNP NET_INST_ID_NOT_PRESENT TD ReqFXCancellation MTA MISSING_TXN_AMOUNT TD ReqBooking ITA INVALID_TXN_AMOUNT TD RespFXCancellation, ReqBooking 136 Strictly Private and Confidential CODE DESC TD/BD API RespFXRate, MFXR MISSING_FX_RATE TD RespFXCancellation, ReqBooking RespFXRate,ReqFXCancellat IFXR INVALID_FX_RATE TD ion, RespFXCancellation, ReqBooking, RespBooking RespPay, RespFXRate, RespBooking, DUP DUPLICATE TD RespFXCancellation, RespValCust, RespChkTxn, RespValQr, RespValAdd IRAP ILLEGAL_REQUEST_OR_ALREA DY_PROCESSED TD RespChkTxn RespValAdd, RespValQr, DNF DOWNSTREAM_NOT_FOUND TD ReqValQr, ReqFXRate, ReqBooking, ReqFXCancellation, DNA DOWWNSTREAM_NOT_ALIVE TD ReqFXRate, ReqBooking, ReqFXCancellation, ReqAuthMandate, ReqValAdd, ReqValQr, DCF DOWWNSTREAM_COMMUNIC ATION_FAILED TD ReqFXRate, ReqBooking, ReqFXCancellation, ReqRefund UCF UPI_COMMUNICATION_FAILED TD ReqValCust DRT DEBIT_TIMEOUT TD ReqPay CRT CREDIT_TIMEOUT TD ReqPay ReqValQr, ReqFXRate, ReqBooking, DNK DOWNSTREAM_NACK TD ReqFXCancellation, ReqValCust, ReqPay, ReqRefund DB DOWNSTREAM_BLOCKED TD ReqFXRate, ReqBooking, ReqFXCancellation ReqPay, RespPay, RespFXRate, RespBooking, AP ALREADY_PROCESSED TD RespFXCancellation, RespValCust, RespChkTxn, RespRiskScore, RespValQr, RespValAdd, 137 Strictly Private and Confidential CODE DESC TD/BD API RespAuthMandate, RespRefund, ReqValQr, ReqFXRate, ReqBooking, ReqFXCancellation, ReqValCust, ReqPay, ReqRefund ReqComplaint, ReqFXCancellation, RespFXCancellation, RespChkTxn, ReqChkTxn, RespRiskScore, RespValAdd, ReqValAdd, ReqAuthMandate, ReqMandateConfirmation, RespMandateConfirmation, TIM TXN_ID_MISMATCH TD RespAuthMandate, ReqRefund, RespRefund, ReqValCust, RespValCust, ReqFXRate, RespFXRate, ReqPay, RespPay, ReqHbt, RespHbt, ReqTxnConfirmation, RespTxnConfirmation, ReqValQr, RespValQr, ReqBooking, RespBooking, RespChkTxn, RespFXRate, RespBooking, RespFXCancellation, RespValCust, RespPay, RespChkTxn, RespValQr, ReqRefund, ReqFXRate, ReqBooking, ReqFXCancellation, TNP TXN_NOT_PRESENT TD ReqValCust, ReqPay, ReqValQr, RespValAdd, ReqValAdd, ReqTxnConfirmation, ReqAuthMandate, ReqMandateConfirmation, RespMandateConfirmation, RespAuthMandate, ReqHbt, ReqRefund, RespRefund 138 Strictly Private and Confidential CODE DESC TD/BD API RespChkTxn, RespFXRate, RespBooking, RespFXCancellation, RespValCust, RespPay, RespChkTxn, RespValQr, ReqRefund, ReqFXRate, ReqBooking, ReqFXCancellation, , , TIDNP TXN_ID_NOT_PRESENT TD ReqValCust, ReqPay, ReqValQr, RespValAdd, ReqValAdd, ReqTxnConfirmation, ReqAuthMandate, ReqMandateConfirmation, RespMandateConfirmation, RespAuthMandate, ReqHbt, ReqRefund, RespRefund, ReqChkTxn RespHbt, ReqFXRate, RespFXRate, ReqBooking, RespBooking, ReqFXCancellation, RespFXCancellation, ReqValCust, RespValCust, ReqPay, RespPay, RespTxnConfirmation, ReqTxnConfirmation, HNP HEADER_NOT_PRESENT TD RespChkTxn, ReqChkTxn, ReqValQr, RespValQr, RespValAdd, ReqValAdd, ReqAuthMandate, RespAuthMandate, ReqMandateConfirmation, RespMandateConfirmation, ReqAdFXRate, RespAdFXRate, ReqHbt, ReqRefund, RespRefund RespHbt, ReqFXRate, RespFXRate, ReqBooking, RespBooking, IMT INVALID_OR_MISSING_TS TD ReqFXCancellation, RespFXCancellation, ReqValCust, RespValCust, ReqPay, RespPay, 139 Strictly Private and Confidential CODE DESC TD/BD API RespTxnConfirmation, ReqTxnConfirmation, RespChkTxn, ReqChkTxn, ReqValQr, RespValQr, RespValAdd, ReqValAdd, ReqAuthMandate, RespAuthMandate, ReqMandateConfirmation, RespMandateConfirmation, ReqAdFXRate, RespAdFXRate, ReqHbt, ReqRefund, RespRefund RespHbt, ReqFXRate, RespFXRate, ReqBooking, RespBooking, ReqFXCancellation, RespFXCancellation, ReqValCust, RespValCust, ReqPay, RespPay, RespTxnConfirmation, ReqTxnConfirmation, IMO INVALID_OR_MISSING_ORG_ID TD RespChkTxn, ReqChkTxn, ReqValQr, RespValQr, RespValAdd, ReqValAdd, ReqAuthMandate, RespAuthMandate, ReqMandateConfirmation, RespMandateConfirmation, ReqAdFXRate, RespAdFXRate, ReqHbt, ReqRefund, RespRefund RespHbt, ReqFXRate, RespFXRate, ReqBooking, RespBooking, ReqFXCancellation, RespFXCancellation, ReqValCust, RespValCust, IMM INVALID_OR_MISSING_MSG_ID TD ReqPay, RespPay, RespTxnConfirmation, ReqTxnConfirmation, RespChkTxn, ReqChkTxn, ReqValQr, RespValQr, RespValAdd, ReqValAdd, ReqAuthMandate, 140 Strictly Private and Confidential CODE DESC TD/BD API RespAuthMandate, ReqMandateConfirmation, RespMandateConfirmation, ReqAdFXRate, RespAdFXRate, ReqHbt, ReqRefund, RespRefund RespHbt, ReqFXRate, RespFXRate, ReqBooking, RespBooking, ReqFXCancellation, RespFXCancellation, ReqValCust, RespValCust, ReqPay, RespPay, RespTxnConfirmation, ReqTxnConfirmation, IMTT INVALID_OR_MISSING_TXN_TY PE TD RespChkTxn, ReqChkTxn, ReqValQr, RespValQr, RespValAdd, ReqValAdd, ReqAuthMandate, RespAuthMandate, ReqMandateConfirmation, RespMandateConfirmation, ReqAdFXRate, RespAdFXRate, ReqHbt, ReqRefund, RespRefund MSRI MISSING_SUCCESS_REF_ID TD RespBooking MSTS MISSING_SUCCESS_TS TD RespBooking ISTNP INSTITUTION_NOT_PRESENT TD RespFXCancellation, ReqBooking, ReqFXRate RespValQr, RespValCust, IRE INVALID_RESPONSE TD RespFXCancellation, RespBooking, RespFXRate RespPay, RespChkTxn, RespValAdd, IRR INVALID_RESPONSE_RESULT TD RespAuthMandate, RespValQr, RespValCust, RespFXCancellation, RespBooking, RespFXRate IPRC INVALID_PAYER_CURRENCY TD ReqPay IPEC INVALID_PAYEE_CURRENCY TD ReqPay IPRA INVALID_PAYER_AMOUNT TD ReqPay 141 Strictly Private and Confidential CODE DESC TD/BD API IPEA INVALID_PAYEE_AMOUNT TD ReqPay PPAM PAYER_PAYEE_AMOUNT_MISM ATCH TD ReqPay IPEPI INVALID_PAYEE_PAYMENT_INS TRUMENT TD ReqPay, ReqValCust IPV INVALID_PAYEE_VPA TD ReqPay ReqPay, ReqValCust, IPRL INVALID_PAYER_LOCATION TD ReqValAdd IL INSUFFICIENT_LIMIT BD ReqPay, ReqValCust UNKNO WN UNKNOWN_ERROR TD ReqValCust, ReqFXRate DRF DR_FAILURE TD ReqPay OTNF ORG_TXN_NOT_FOUND TD ReqChkTxn VTNF VALIDATION_TXN_NOT_FOUND TD ReqPay VTI VALIDATION_TXN_INVALID TD ReqPay VTIP VALIDATION_TXN_IN_PROGRES S TD ReqPay VTNS VALIDATION_TXN_NOT_SUCCE SSFUL TD ReqPay OTNFIN ORG_TXN_NON_FIN TD ReqChkTxn ReqFXRate, RespFXRate, IMCUR INVALID_OR_MISSING_BASECU ReqBooking, RespBooking, RR TD ReqFXCancellation, RespFXCancellation SETTLEMENT_BANK_NOT_FOU SBNF ND TD ReqPay, ReqValCust CBNF COMPLIANCE_BANK_NOT_FOU ND TD ReqValCust CBNA COMPLIANCE_BANK_NOT_ALIV E TD ReqValCust CBCF COMPLIANCE_BANK_COMMU NICATION_FAILED TD CBB COMPLIANCE_BANK_BLOCKED TD ReqValCust APNF AML_PROV_NOT_FOUND TD ReqPay, ReqValCust APNA AML_PROV_NOT_ALIVE TD ReqPay, ReqValCust 142 Strictly Private and Confidential CODE DESC TD/BD API APCF AML_PROV_COMMUNICATION _FAILED TD APB AML_PROV_BLOCKED TD ReqPay, ReqValCust U17 PSP_IS_NOT_REGISTERED BD ReqValQr, RespValAdd ECCF EXTERNAL_COMPLIANCE_COM MUNICATION_FAILED TD ReqPay, ReqValCust EXTERNAL_COMPLIANCE_COM ECCT MUNICATION_TIMEOUT TD ReqPay, ReqValCust ACF AML_COMMUNICATION_FAILE D TD ReqPay, ReqValCust ACT AML_COMMUNICATION_TIMEO UT TD ReqPay, ReqValCust IMDS INVALID_OR_MISSING_DEALT_ SIDE TD RespBooking IMDT INVALID_OR_MISSING_DEALT_ TYPE TD RespBooking MTII MISSING_TXN_INST_ID TD ReqFXCancellation ITII INVALID_TXN_INST_ID TD ReqFXCancellation INSTID INVALID_NET_INST_ID TD ReqFXRate, RespFXRate, IMTEN INVALID_OR_MISSING_TENOR TD ReqBooking, RespBooking, ReqFXCancellation, RespFXCancellation MCA MISSING_CONTRA_AMOUNT TD ReqBooking ICA INVALID_CONTRA_AMOUNT TD RespBooking, RespFXCancellation MUQI MISSING_UNIQUOTESID TD RespFXRate, ReqBooking, ReqFXCancellation IUQI INVALID_UNIQUOTESID TD ReqBooking, RespBooking, ReqFXCancellation ReqValCust, ReqPay, RespPay, ReqMandateConfirmation, IIRP INVALID_IRP TD ReqFXRate, RespFXRate, ReqFXCancellation, RespFXCancellation, , ReqBanEnq, ReqValQr, ReqValAdd, ReqRefund 143 Strictly Private and Confidential CODE DESC TD/BD API MTAE MAX_TXN_AMOUNT_EXCEEDE D BD ReqValCust, ReqPay, ReqValAdd A06 INVALID_PAYER_PAYMENT_INS TRUMENT TD ReqPay INVALID_PAYER_REQ_ID_DETAI IPRID LS TD ReqValCust IPI INVALID_PAYER_IFSC TD ReqPay VAN VAL_ADD_NACK TD ReqValCust, ReqPay VAT VAL_ADD_TIMEOUT TD ReqValCust UC5 VAL_ADD_TIMEOUT_FOR TD ReqValCust ECN EXT_COMPL_NACK TD ReqValCust, ReqPay AN AML_NACK TD ReqValCust, ReqPay AD AML_DECLINE TD ReqValCust, ReqPay CD COMPLIANCE_DECLINE TD ReqValCust, ReqPay VAD VAL_ADD_DECLINE TD ReqValCust E10 SETTLEAMOUNT_IS_MANDATO RY_AND_DECIMAL TD RespPay LK06 HANDLE_NOT_ALLOWED_FOR_ IRP TD ReqValCust, ReqPay DS REV_TIMED_OUT TD ReqPay QM1 INVALID_MCC_FOR_THE_PAYE E TD RespValQr, RespValAdd Q03 PAYER/PAYEE.TAG.DEVICE.NA ME/VALUE MUST BE PRESENT TD ReqPay, ReqValQr XE INVALID AMOUNT (BENEFICIARY) BD Error received by UPI/iUPI U03 NET DEBIT CAP IS EXCEEDED BD UPI error U68 CREDIT TIMEOUT TD UPI error 144 Strictly Private and Confidential 9. FREQUENTLY ASKED QUESTIONS 1. During merchant onboarding, is NIPL involved in validating or storing merchant details? - No, NIPL is not involved in merchant onboarding, QR generation, or merchant validation. The IP manages all these activities. When an Indian customer scans a QR, NIPL simply forwards the entire QR string as-is to the IP, who performs the validation and returns the merchant details in the response to NIPL. 2. Does NIPL support only UPI QRs, or does NIPL also support proprietary QRs? - NIPL supports both UPI QRs and proprietary QRs. For proprietary QRs, IPs must include a unique identifier that clearly indicates that the QR belongs to them. This identifier must be present in all their QRs. NIPL uses this identifier to route the QR to the respective IP for merchant validation. 3. What is a Payee addr? Is it the geolocation of the Payee? - No, it refers to the UPI ID or the alias of the Payee. UPI ID format: a. UPI ID consists of the alias of the Payee followed by the bank identifier. (Ex: abc.123@bank) b. Permitted special characters are dot ‘.’ at ‘@’ and hyphen ‘-’ c. Total length of UPI ID is a 255 character string which is inclusive of the bank identifier. 4. What is considered as ‘Credit Success’ during a transaction reversal? - When IP does not respond to the original credit request and the status check request, iUPI initiates a credit reversal request. If during the reversal, the IP confirms with the response code ‘CS’, i.e., the amount was credited to the merchant, the transaction is marked as Credit Success. 5. What is considered as ‘Reversal Success’ during a transaction reversal? - When IP does not respond to the original credit request and the status check request, iUPI initiates a credit reversal request. If during the reversal, the IP confirms with the response code ‘00’, i.e., the amount was not credited to the merchant, the transaction is marked as Reversal Success and the money is credited back to the source account. 145 Strictly Private and Confidential 6. What are ‘DEEMED’ transactions? - When IP does not respond to the original credit request, status check request, and credit reversal request, iUPI marks the transaction as ‘DEEMED’ success temporarily. Since the merchant may have already delivered the goods/services and the customer’s account is already debited, the transaction cannot be marked as ‘FAILURE’. During the reconciliation cycle, the IP will update the final status, and the transaction will be updated in aURCS portal accordingly. 7. What are Transaction ID, Reference ID, Message ID, and Custref? What is the purpose of the various IDs in the API? a. Message ID i. A unique ID generated for every API message. ii. Each request and response has its own Message ID and is used to correlate between request and response. b. Reference ID i. During the validation flow, one reference ID is used. ii. During the financial flow, a new reference ID is generated. iii. It is used by Payer PSP for internal tracking of the transactions. c. Transaction ID i. During the validation flow, one Transaction ID is used. ii. During the financial flow, a new Transaction ID is generated. d. Custref i. A 12 digit numeric identifier used for customer traceability across systems. ii. IP to pass same value as received in the request API. 8. What is the purpose of the various timestamps in the API? a. Head Timestamp (head.ts) This timestamp indicates when each API message is generated. Since every request or response is created at a different moment, this value changes for every API message. b. Transaction Timestamp (txn.ts) This timestamp captures the exact time when the transaction is initiated. c. QR Timestamp (qr.ts): 146 Strictly Private and Confidential This timestamp represents the moment the QR code is generated. As the QR is created only once per transaction, this timestamp also remains the same for the entire duration of the transaction. 9. Can IP initiate reqchktxn to check the status of the transaction? - No, Reqchktxn API can only be initiated by NIPL to check the status of the credit. At present, IPs cannot initiate reqchktxn. 10. The APIs include Payee account details. Do IPs need to provide end beneficiary account information? - No, IPs do not need to pass end beneficiary details. The Payee account field refers to the Indian settlement bank account of the IP, not the merchant’s or end beneficiary’s account. ***** END OF DOCUMENT ***** 147