By continuing your navigation on our website, you consent to the use of cookies to provide you with better services. To learn more, read our cookies policy.
x
APIs
Products & Solutions
Partner
Support
Sign in
Search
International
中国站
Open API >QR Code Payments >QR Code ATM Cash Withdrawal
QR Code ATM Cash Withdrawal
QR Code Payments Issuer Mobile Payment
UPI QR Code Cash Withdrawal provides ATM cash withdrawal services to cardholders globally.
Sandbox Testing
API Introduction
API Introduction
What is it?

UPI QR Code Cash Withdrawal provides ATM cash withdrawal services to cardholders globally, opening interfaces for issuers and app providers to deal with UPI QR code-based ATM cash withdrawal transaction.

Key Features

1.More security, because of the mobile phone verification method

2.More convenience, CNP cash withdrawal via phone

3.Easy to implement, only software upgrade is required and no need to do hardware modification

4.EMV standard compatible


When to Use it?

Issuer together with its bank app who wants to join the UPI network to do QR code ATM cash withdrawal business

Who Use it?
Issuer, Developers
Where to Use it?
Global
Things to Know

1.App shall support different business logic when it can support both QRC payment and QRC cash withdraw by recognizing the MCC when decoding the code.

2.UnionPay support almost all types of card to do cash withdrawal business. It is recommended that bank app should disable the invalid cards based on bank’s own policy.

3.There is different user experience for QR based ATM cash withdraw. The difference should be taken into consideration if necessary.

4.The implementation of APP and user experience differ when using in different markets. For market outside of mainland China, app shall have the ability to decode the EMV mode QR code and leverage the related interface; while for mainland China market, app shall have the ability to decode the URL mode QR code and leverage the related interface. User experience like entering withdrawal amount and ATM password would also be different in above-mentioned market.


Flow Chart
Flow Chart

二维码取现流程图.png

1. Cardholder binds UnionPay card to a bank app 

2.Cardholder chooses an ATM terminal supporting UnionPay card-not-present cash withdrawal, clicks “QR Code cash withdrawal” and inputs amount. 

3. QR code is generated by the acquirer and displayed on ATM terminal

4. Cardholder uses APP to scan QR code on ATM screen. 

5. ATM terminal displays masked card number, withdrawal amount and prompts cardholder to enter the ATM PIN on ATM terminal. 

6. ATM initiated the cash withdrawal request to UPI system

7. When the transaction is authorized, APP shall receive a notification by the acquirer as a record of ATM cash withdrawal history.

Note:  The QR code displayed on ATM should be a dynamic code based on UPI’s merchant presented QR code encoding specification. This dynamic QR code is generated for each transaction containing a transaction amount.
API Reference
API Reference
  • MPQRC_ATM_EMV
  • MPQRC_ATM_URL
  • TRX_RESULT_INQUIR
Interface description
After the cardholder scans an EMV standard merchant-presented QR code, the mobile application will capture and parse the payload from the merchant-presented QR code. MPQRC_ATM_EMV interface is for mobile application to initiate ATM cash withdrawal transaction based on Merchant-presented QR Code Payment (EMV Mode). QR Code in EMV mode applies to transactions outside of Mainland China.
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Message Information msgInfo Object M:Mandatory
Version Number versionNo ANS 5 M:Mandatory Valid Value: "1.0.0"
Message ID msgID AN 17-49 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates any day. The value in the response must match the value in the request. Components: “A”+ Wallet ID+ Serial Code. Example: "A0001034420171230235959000031"
Time Stamp timeStamp N 14 M:Mandatory The value in the response must match the value in the request. Format: YYYYMMDDhhmmss. Example: "20170714235959"
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "MPQRC_ATM_EMV"
Wallet ID walletID AN 8 M:Mandatory The unique value associated to a wallet. Example: "00010344"
Transaction Information trxInfo Object M:Mandatory
Device ID deviceID ANS 1-64 M:Mandatory The unique value associated to a device. It shall be IMEI for Android mobile and IDFV for iOS mobile.
Token token N 16-19 C:Conditional Token PAN. Either "token" or "pan" shall be present. Example: "6200008888888888888"
Primary Account Number pan AN 1-2048 C:Conditional Encrypted with the public key of the Encryption Certificate.Either "token" or "pan" shall be present.
Transaction ID txnID AN 17-49 M:Mandatory It is used to link a transaction to subsequent messages within a transaction set. The transaction identifier remains the same in all related messages: MPQRC_ATM_EMV, TRX_RESULT_INQUIRY, TRX_STATUS_NOTIFICATION, etc. The value must uniquely identify any transaction set that the wallet initiates any day. Components: “A”+ Wallet ID+ Serial Code. Example:"A0001034420171230235959000090"
Transaction Amount trxAmt ANS 1-13 M:Mandatory It is captured by the Cardholder’s mobile application from the Merchant-presented QRC data, ID "54". The value in this field includes tip or convenience fee, if applicable. For example, the value of transaction amount (ID "54") in the dynamic QRC data is "100". The value of fixed convenience fee (ID "56") is "1.10". Then the value of "trxAmt" shall be "101.10".
Transaction Currency trxCurrency N 3 M:Mandatory A 3-digit numeric value, as defined by [ISO 4217], that indicates the transaction currency code. The mobile application should display the transaction currency in a readable way, such as "RMB".
Transaction Fee Amount trxFeeAmt ANS 1-13 C:Conditional The tip or the convenience fee. Present if the Tip or Convenience Fee exists
Merchant-presented QRC Payload “mpqrcPayload S 1-512 M:Mandatory It contains the raw payload data in the Merchant-presented QRC.
Back URL backURL ANS 1-50 O:Optional The UMPS system will send messages, such as TRX_STATUS_NOTIFICATION, back to this URL if it is present. Otherwise, it will be sent back to the configured URL of the wallet.
Risk Information riskInfo Object O:Optional
GPS gps ANS 1-64 O:Optional Components: +(-) latitude/+(-) longitude．Example: "+37.12/-121.23"
SIM Card simCard Array 1-200 O:Optional The mobile number of the SIM cards. The mobile phone possibly have more than one SIM card.
Application User ID appUserID ANS 1-64 O:Optional An alias for the application user ID.
User Enrollment Date usrEnrolDate N 6 O:Optional The date when the Cardholder registers in the wallet. Format: YYMMDD
Card Number Capture Method captureMethod ANS 1-64 O:Optional Valid Values: • "MANUAL" • "NFC" • "CAMERA" • "UNKNOWN"
IP Address ipAddress ANS 1-64 O:Optional The public network IP address of the device
Reserved Mobile Number reservedMobileNo ANS 1-25 O:Optional The mobile number collected by the application when the user registers his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164] Components: Country code (1-3 digits) + “-” + subscriber number. If the country code is not present, the UMPS system will consider it as a Chinese mobile number. Example: “86-13900000000”
Device Type deviceType ANS 1-20 O:Optional Valid Values: “MOBILE”. Reserved Values: “WATCH” , “PAD” , “PC”
Device Score deviceScore N 1 O:Optional Valid Values: “1” to “5”. “5” indicates the device is the most reliable, and “1” indicates the device is the least reliable.
Additional Data additionalData Object C:Conditional Present if the template "62" exists in the Merchant-presented QRC.
Bill Number billNo ANS 1-25 C:Conditional The invoice number or bill number. It may be provided by the Merchant or entered by the Cardholder. Present if the ID "01" under template "62" exists in the Merchant-presented QRC.
Mobile Number mobileNo ANS 1-25 C:Conditional The Mobile Number to be used for multiple use cases, such as mobile top-up and bill payment. It may be provided by the Merchant or entered by the Cardholder. The mobile number may be different from the Cardholder mobile number, which will be passed to the Acquirer/Merchant as additional information. Present if the ID "02" under template "62" exists in the Merchant-presented QRC.
Store Label storeLabel ANS 1-25 C:Conditional A unique value associated to a store. It may be provided by the Merchant or entered by the Cardholder. Present if the ID "03" under template "62" exists in the Merchant-presented QRC.
Loyalty Number loyaltyNumber ANS 1-25 C:Conditional Typically, a loyalty card number. It may be provided by the Merchant or entered by the Cardholder. Present if the ID "04" under template "62" exists in the Merchant-presented QRC.
Reference Label referenceLabel ANS 1-25 C:Conditional Any value defined by the Merchant or the Acquirer to identify the transaction. It may be provided by the Merchant or entered by the Cardholder. Present if the ID "05" under template "62" exists in the Merchant-presented QRC.
Customer Label customerLabel ANS 1-25 C:Conditional Any value identifying a specific Cardholder. It may be provided by the Merchant or entered by the Cardholder. Present if the ID "06" under template "62" exists in the Merchant-presented QRC.
Terminal Label terminalLabel ANS 1-25 C:Conditional A unique value associated to a terminal in the store. It may be provided by the Merchant or entered by the Cardholder. Present if the ID "07" under template "62" exists in the Merchant-presented QRC.
Purpose of Transaction trxPurpose S 1-25 C:Conditional Any value defining the purpose of the transaction. It may be provided by the Merchant or entered by the Cardholder. Present if the ID "08" under template "62" exists in the Merchant-presented QRC.
Email Address of the Consumer consumerEmail S 1-100 C:Conditional The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the Cardholder. It will not be verified in the payment procedure but be provided to the Acquirer/Merchant as additional information. Present if the ID "09" under template "62" contains value "E" in the Merchant-presented QRC
Address of the Consumer consumerAddress S 1-100 C:Conditional The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the Cardholder. It will not be verified in the payment procedure but be provided to the Acquirer/Merchant as additional information. Present if the ID "09" under template "62" contains value "A" in the Merchant-presented QRC
Mobile Number of the Consumer consumerMobileNo ANS 1-25 C:Conditional The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the Cardholder. It will not be verified in the payment procedure but be provided to the Acquirer/Merchant as additional information. Present if the ID "09" under template "62" contains value "M" in the Merchant-presented QRC
Certificate and Signature certificateSignature Object M:Mandatory
Application Signature Certificate ID appSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The application gateway uses the private key of this certificate for signature.
UMPS Encryption Certificate ID umpsEncCertID AN 1-128 C:Conditional The serial number of the certificate. The application uses the public key of this certificate for encryption. Present if encrypted information exists in the request message.
Signature signature ANS 1-2048 M:Mandatory Please refer to the section of Signature in UMPS Book 1 -Section 3.2 for details.
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Message Information msgInfo Object M:Mandatory
Version Number versionNo ANS 5 M:Mandatory Valid Value: "1.0.0"
Message ID msgID AN 17-49 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the wallet initiates any day. The value in the response must match the value in the request. Components: “A”+ Wallet ID+ Serial Code. Example: "A0001034420171230235959000031"
Time Stamp timeStamp N 14 M:Mandatory The value in the response must match the value in the request. Format: YYYYMMDDhhmmss. Example: "20170714235959"
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "MPQRC_ATM_EMV"
Wallet ID walletID AN 8 M:Mandatory The unique value associated to a wallet. Example: "00010344"
Transaction Information trxInfo Object M:Mandatory
Transaction ID txnID AN 17-49 M:Mandatory It is used to link a transaction to subsequent messages within a transaction set. The transaction identifier remains the same in all related messages: MPQRC_ATM_EMV, TRX_RESULT_INQUIRY, TRX_STATUS_NOTIFICATION, etc. The value must uniquely identify any transaction set that the wallet initiates any day. Components: “A”+ Wallet ID+ Serial Code. Example: "A0001034420171230235959000090"
QRC Voucher Number qrcVoucherNo ANS 1-20 C:Conditional Populated by UnionPay if the transaction is acknowledged. Example: "1234567890123456789"
Message Response msgResponse Object M:Mandatory
Response Code responseCode AN 2 M:Mandatory It contains a code that defines the response to a request. Please refer to the table of Response Code and Message in Response Code Reference for the valid values.
Response Message responseMsg S 1-100 M:Mandatory It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the Cardholder of the transaction outcome. Please refer to the table of Response Code and Message in Response Code Reference for details.
Certificate and Signature certificateSignature Object M:Mandatory
UMPS Signature Certificate ID umpsSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The UMPS system uses the private key of this certificate for signature.
Signature signature ANS 1-2048 M:Mandatory Please refer to the section of Signature in UMPS Book 1 -Section 3.2 for details.
Response Code Reference
Response Code Reference
Response code Description
0 Approved
1 Please refer to the card issuer
12 Invalid transaction
13 Invalid amount
14 Invalid card number
15 No such issuer
21 Card status error
25 Unable to locate the original transaction
3 Invalid merchant
30 Message format error
32 Exceed OTP max tries
34 Fraud card
4 Pending Transaction result is unknown Please check later
40 The transaction is not supported by the issuer
41 Lost card
43 Stolen card
5 Cardholder verification fails
51 Insufficient balance
54 Expired card
55 Invalid device id
57 Transaction not permitted to cardholder
61 Exceeds approval amount limit
62 Restricted transaction
70 Validation error from issuer
71 Issuer declined
72 Issuer verify mac failed
73 Enrollment not found
74 OTP expired
75 Invalid OTP
76 OTP not found
77 IDV not set
78 Duplicate request
8 TSP error
88 Card already provisioned
89 Card profile not found
90 The system is in cut-off
91 Issuer system error
92 Network error
93 Invalid enrol state
94 Duplicated transaction
95 Enrolment timed out
96 UnionPay system error
98 Timeout
99 Other error
A0 Signature verification fails
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.
©Copyright 2002 - 2024. All rights reserved