Open API >Primary Credit Transaction >Mobile Real-time Tax Refund
Mobile Real-time Tax Refund
Primary Credit Transaction Merchant Acquirer Issuer Mobile Payment
Mobile Real-time Tax Refund allows users to display real-time tax refund QR Code or barcode to tax refund counter or self-service machine, and the tax refund will be credited immediately after being scanned.
API Introduction
API Introduction
What is it?

After shopping, UnionPay cardholders can enjoy the real-time tax refund service at the UnionPay cooperative refund counters. Cardholders only need to show the refund QRC/barcode and be scanned by the refund counter, and then he/she can get the  refund immediately, which addresses the pain point of  spending long time to receive tax refund and greatly improves the user's refund experience.

The tax refund code is generated according to the international standard of two-dimensional code. The user shall bind the UnionPay card (including debit card, credit card and restorable prepaid card) that supports real-time tax refund service, and the information contained in the code is the token provided by UnionPay.


Key Features

1. The tax refund is credited in the currency in which the card is issued immediately;

2. Provide an electronic and convenient way of tax refund

3. Avoid disclosure of cardholder bank card information or account information

4.Better improve the global tourism service and increase user stickiness on the application


When to Use it?

It is suitable for the party who wishes to enhance its cross-border travelling services on its own application through providing cardholder overseas shopping real-time tax refund service.

The app gateway supporting the tax refund service only needs to connect with UPI tax refund platform. Cardholders can bind the bank card on the third-party app or the H5 page of UPI tax refund platform, then he/she can enjoy UPI real-time tax refund service.


Who Use it?
Issuers, Acquirers, Merchants, Technology solution providers
Where to Use it?
All refundable countries and regions (including China)
Things to Know

1. The tax refund QRC/Barcode is not the payment code or the receiving code, which is generated according to the international standard two-dimensional code. The user is not necessary to enter payment password (PIN)

2. The tax refund code ONLY can be generated when defaulting a bank card that supports the real-time refund service, and UPI would provide a specific card BIN for institutions to pre-check.

3. The tax refund code is dynamic and updated every 10 minutes.

4. The information contained in the tax refund code is a token provided by UnionPay.

5. In order to ensure the service quality, UPI strongly recommends the party to collect users’ passport information and display it on the application to be used for identity verification at the tax refund counter.

6. For any sensitive information, such as the card number (PAN), encryption is required before transmission.

7. The access party shall ensure that its application for providing the real-time refund service complies with local regulations.


Flow Chart
Flow Chart

流程图.png

1. Cardholder defaults UnionPay Cards that supporting instant tax refund 

2. Cardholder insert passport information like passport number & passport phonetic alphabet, so as to be shown on the tax refund counter to further identity verification 

3. Tax refund QRC/Barcode will be generated in international standard other than EMV standard

4. Cardholder claim instant refund via tax refund QRC/Barcode

5. Refund point machine initiate transaction to tax refund company

6. Tax refund company initiate transaction to UPI

7. UPI forward transaction to issuer

8. Issuer credit tax refund to bank account

9. Issuer return credit result to UPI

10.UPI forward result to tax refund company.


API Reference
API Reference
  • Obtaining backendToken
  • Refund Code Transmission
  • Get Customer Info
  • Refund Transaction Status Feedback
Interface description
Tax refund company system regularly obtains “backendToken”through this API, which is the authorization for connecting UnionPay App
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
appId appId string 32 M:Mandatory Specific ID for the connector
nonceStr nonceStr string 16 M:Mandatory Random character string for generating signature
timestamp timestamp number M:Mandatory The instant/real time of this connecting request
signature signature string M:Mandatory The factors including : appId, secret, nonceStr, timestamp
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
backendToken backendToken string 24 M:Mandatory The authentication for connecting to OAUTH2 back system
expiresIn expiresIn number M:Mandatory The expiration time of “backendToken”(Time Unit: second).currently returns 7200 always.please store the backendtoken for every 7200 seconds and during the expiration time please use the same valid backendtoken, otherwise the system will reject the call and backlist the AppID if it is connecting in a high frequency
Security Requirement
Security Requirement

Signature Process:

Step 1: Prior all the parameters for generating the signature based on ASCII code from minimum to maximum, then use the format of URL value(key1=value1 & key2=value2…etc.)to get one random character string “string1”.  In terms of Key & value, both are the original value, remaining the Upper/Lower case letters, and no translations on URL

Step 2: Generate the “Signature” with the signature algorithm ‘SHA256’ based on “string 1”


Example:

Clear Message:

• appId=a5949221470c4059b9b0b45a90c81527

• nonceStr=Wm3WZYTPz0wzccnW

• timestamp=1414587457

• url=http://mobile.xxx.com?params=value

• frontToken=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg


Step 1. Concatenate to string (‘string1’):

appId=a5949221470c4059b9b0b45a90c81527&frontToken=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&nonceStr=Wm3WZYTPz0wzccnW& timestamp=1414587457&url=http://mobile.xxx.com?params=value

Step 2. implement SHA 256 to generate the signature:

604147c81de8b7c28e3c2a37de03a1274f2efddd4e5a9fcc5cb98ef6198df3b9

Note: nonceStr and timestamp for signature should be the same as the one of the request parameters.


Steps to Launch
Steps to Launch

1. The access party shall submit an application and fill in the relevant application form

2. The access party completes the development and testing of related technologies.


Please submit order to get assistance

Response Code Reference
Response Code Reference
Response code Description
00 Success
01 Request message parsing error
02 Parameters Format Error
03 Illegal request code
04 no permission to call this interface
05 URL not supported
06 Login timeout. Please log in again
07 This account has been logged in by another terminal
08 Interface call frequency exceeded limit
98 Marketing System busy, please try later
99 System busy, please try later
A01 Invalid appid
A02 Invalid secret
A03 Invalid scope
A10 Invalid or expired backendToken
A20 Invalid or expired frontendToken
A21 Invalid domain name, not registered
A22 Timestamp for signature is expired.
A23 Invalid signature, signature verification failed
A24 Invalid IP
A30 The authorization callback url is not supported
A31 Invalid or expired authority code
A32 Invalid OpenID
A33 Invalid or expired access_token
A34 Invalid or expired refresh_token
A35 Not authorized to call the interface
A40 System busy, please try again later
A41 incomplete user information
A42 the user mobile number is not recorded
A43 not authorized by the user
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.