UnionPay International Developer

Open API >Information Service >UnionPay Tax Refund

UnionPay Tax Refund

Information Service Acquirer

UnionPay Tax Refund Open Platform provides cooperative partners with open APIs of tax refund related services，including overseas tax refund inquiries and home refund application & inquiry, meanwhile, platform provides TRSP with technical support on product development， optimization.

Sandbox Testing

API Introduction

What is it?

Via integrating Unionpay APIs, the online platform can provide partners like banks, tax refund companies, travel agencies and OTA to offer value added services related to Tax Refund Business to its clients based on partners' specifical requirements.

Key Features

Through integrating APIs, the cooperative partners can provide its users with the corresponding tax refund services, such as:Tax refund form tracker, Tax refund points inquiry, Tax refund stores inquiry, Online Home refund application, and Online Home refund inquiry.The key features are:

1.Simple Interface & personalized customization:API or whole set H5 pages functions can be chosen to meet the partners needs.Also the interface can be customized as required.

2.Public platform & more cooperation opportunities:APIs provided by agencies are accepted for secondary development and integration functions, information, value-added services are introduced to partners.For the non-tax refund institutions, the platform can benefit the non-tax refund institutions to connect to the top tax refund companies in the world, and there's no need to integrate the related services for their own front-end.

When to Use it?

1、It is applied to the tax refund company. In the tax refund company side, it can provide its users to inquire the processing status of a tax refund with card number and setting time. Meanwhile, its users can inquire both tax refund points and tax refund stores by setting country and region.

2、It is applied to the banks. In banks side, it can provide the online home refund application and online home refund inquiry services to its users which can improve the users’ experience and better customer satisfaction.

3、It is applied to travel agency and OTA. In travel agency and OTA side, it can provide the added-value services to its users and also, through integrating the APIs,co-marketing activities can be further implemented which can benefit the travel agency and OTA to attract more potential clients and deepen the connection with existing clients.

Who Use it?

The system developers of the application provider, system developers of UnionPay International, and system testing and business acceptance personnel.

Where to Use it?

This API is available globally.

Flow Chart

tax refund 流程图-改.jpg

API Reference

Sub App for Retu-to-Chi Tax Retu
Query of Retu-to-Chi Tax Ref Sta
Query of Overseas Tax Refu Progr
Query of UnionPay Tax Refu Progr
Query of Tax Refund Branches
Query of Tax Refund Merchants

Interface description

It is available for cardholders to apply for return-to-China tax Return via UnionPay interface after having the Tax Return Form stamped by the Customs.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Access to Application Identification

appid

string

M:Mandatory

Subject to the provisions of the both parties, namely 32 digits.

Language

lang

string

M:Mandatory

en – English.

Request Message

data

string

M:Mandatory

Piece data in different fields required by interfaces into character string of JSON format, and then go through encryption as per the regulated rules.

Name of Cardholder	name	string	M:Mandatory
Mobile Number	mobile	string	M:Mandatory
Bank Card Number	cardno	string	M:Mandatory
ID number	certno	string	M:Mandatory
Chained address of picture on the info page of use s passport	m1	string	O:Optional	Transcoding by encodeURIComponent().
Chained address of picture on Tax Return Form	m2	string	O:Optional	Transcoding by encodeURIComponent().
Chained address of picture on shopping Form	m3	string	O:Optional	Transcoding by encodeURIComponent().

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Processed Result

result

string

M:Mandatory

success or fail.

Description of Processed Result

msg

string

M:Mandatory

Returned Message

data

string

M:Mandatory

Data is available for successful processed result. Otherwise, field data are absent.

Response Code	respCode	string	M:Mandatory
Tax Return Status	status	string	O:Optional
Tax Return Form No	order_no	string	O:Optional	Such as 030338260.

Sample code

Request code

Java

String appid = getPara("appid"), lang = getPara("lang"), data = getPara("data");
Res res = getLocal(lang);
try {
    String appkey = getAppKey(appid);
    if (appkey == null) {
         renderJson(getErrJson(res.get("errorClient")));
         return;
    }
String decryptData = ThreeDESCodec.decryptData(data, appkey);
if ("".equals(decryptData)) {
    renderJson(getErrJson(res.get("errorDecrypt")));
    return;
}
JSONObject reqJson = JSONObject.fromObject(decryptData);
Map<String, Object> params = new HashMap<String, Object>();
try {
    String name = reqJson.getString("name");
    params.put("name", name);
    params.put("mobile", reqJson.getString("mobile"));
    params.put("m1", reqJson.getString("m1"));
    params.put("m2", reqJson.getString("m2"));
    params.put("m3", reqJson.getString("m3"));
    params.put("bank_user", reqJson.getString("name"));
    params.put("bank_card", reqJson.getString("cardno"));
    params.put("bank_name", DBService.getBankName(reqJson.getString("cardno")));
    params.put("certno", reqJson.getString("certno"));
    // temperately use page name
    params.put("outer_user", reqJson.has("userid") ? reqJson.getString("userid") : "");
    params.put("appid", appid);
    // other
} catch (JSONException e) {
    logger.error("", e);
    renderJson(getErrJson(res.get("errorParameter") + e.getMessage()));
    return;
}

Response code

Java

JSONObject respJson = JSONObject.fromObject(taxRefundService.applyHome(params));
JSONObject resultJson = new JSONObject(), dataJson = new JSONObject();

if (!"100".equals(String.valueOf(respJson.get("status")))) {
    renderJson(getErrJson(res.get("errorRespCode") + respJson.getString("msg")));
    return;
}

String orderNo = respJson.getJSONObject("data").getString("order_no");
String status = respJson.getJSONObject("data").getString("status");
dataJson.put("status", status);
dataJson.put("order_no", orderNo);

String encryptData = ThreeDESCodec.encryptData(dataJson.toString(), appkey);
if ("".equals(encryptData)) {
    renderJson(getErrJson(res.get("errorEncrypt")));
    return;
}

resultJson.put("data", encryptData);
resultJson.put("result", "success");
resultJson.put("msg", "");

String storekey = ConfigHolder.get("appkey");
DBService.saveUserInfo(newUserInfo(orderNo, params, storekey));
renderJson(resultJson.toString());
} catch (Exception e) {
    logger.error("", e);
    renderJson(getErrJson(res.get("errorProgram")));
}

Interface description

Where cardholders use UnionPay Interface to apply for return-to-China tax refund, it’s available to transfer the special interface of UnionPay to inquire the status of tax refund as well as the exchange rate used for tax return currency conversion. Submit an application for return-to-China tax refund.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Access to Application Identification

appid

string

M:Mandatory

Subject to the provisions of the both parties, namely 32 digits.

Language

lang

string

M:Mandatory

en – English.

Request Message

data

string

M:Mandatory

Piece data in different fields required by interfaces into character string of JSON format, and then go through encryption as per the regulated rules.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Processed Result

result

string

M:Mandatory

success or fail.

Description of Processed Result

msg

string

M:Mandatory

Returned Message

data

string

M:Mandatory

Data is available for successful processed result. Otherwise, field data are absent.

Response Code	respCode	string	M:Mandatory
Detailed Information	detail	string	O:Optional	Detailed information varies corresponding to different tax-refund status.
Application Time of Tax Refund	submit_time	string	M:Mandatory	Such as Dec. 12, 2014 12:00:00
Tax Refund Status	status	string	M:Mandatory
ID Number	certno	string	M:Mandatory
Bank Card Number	cardno	string	M:Mandatory
Contact Number of Cardholder	mobile	string	M:Mandatory
Name of Cardholder	name	string	M:Mandatory
Tax Refund Form Number	order_no	string	M:Mandatory	Such as 030338260.

Sample code

Request code

Java

String appid = getPara("appid"), lang = getPara("lang"), data = getPara("data");
Res res = getLocal(lang);
try {
    // handle request and validate
    String appkey = getAppKey(appid);
    if (appkey == null) {
        renderJson(getErrJson(res.get("errorClient")));
    return;
}
String decryptData = ThreeDESCodec.decryptData(data, appkey);
if ("".equals(decryptData)) {
    renderJson(getErrJson(res.get("errorDecrypt")));
    return;
}
JSONObject reqJson = JSONObject.fromObject(decryptData);
if (!reqJson.has("order_no")) {
    renderJson(getErrJson(res.get("errorParameter")));
    return;
}
String orderNo = reqJson.getString("order_no").trim();
// handle response
JSONObject respJson = JSONObject.fromObject(taxRefundService.trackHomeRefundStatus(orderNo));
if (respJson.getInt("status") != 100) {
    renderJson(String.format(errJsonV2, res.get("errorRespCode") + respJson.get("msg")));
    return;
}

Response code

Java

JSONObject resultJson = new JSONObject(), dataJson = new JSONObject();

// save query info
DBService.saveQuery(newTblQuery(appid, EnumPartner.UNIONCURR, orderNo, reqJson.toString(), "", respJson.toString()));

// prepare data Json
for (Object key : respJson.getJSONObject("data").keySet()) {
    dataJson.put(key, respJson.getJSONObject("data").get(key));
}
UserInfo u = DBService.getUserInfo(getPara("orderNo"));
String storekey = ConfigHolder.get("appkey");
dataJson.put("cardno", u == null ? "" : StringUtils.des(u.getStr("CARD_NO"), storekey));
dataJson.put("certno", u == null ? "" : StringUtils.des(u.getStr("CERT_NO"), storekey));
String[] whiteList = { "order_no", "name", "mobile", "cardno", "certno", "status", "detail", "submit_time" };
prune(dataJson, whiteList);

// prepare result Json
String encryptData = ThreeDESCodec.encryptData(dataJson.toString(), appkey);
if ("".equals(encryptData)) {
    renderJson(getErrJson(res.get("errorEncrypt")));
    return;
}
resultJson.put("data", encryptData);
resultJson.put("result", "success");
resultJson.put("msg", "");
renderJson(resultJson.toString());
} catch (Exception e) {
    logger.error("", e);
    renderJson(String.format(errJsonV2, res.get("unionCurrTrackStatusError")));
}

Interface description

Where cardholders want to inquire the handling progress of tax refund Institutions upon completing the tax refund procedure at airport, it’s available to enter the barcode of Form or ID No. at the interface of UnionPay to inquire the handling progress of tax refund Institutions.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Access to Application Identification

appid

string

M:Mandatory

Subject to the provisions of the both parties, namely 32 digits.

Language

lang

string

M:Mandatory

en – English.

Request Message

data

string

M:Mandatory

Piece data in different fields required by interfaces into character string of JSON format, and then go through encryption as per the regulated rules.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Processed Result

result

string

M:Mandatory

success or fail.

Description of Processed Result

msg

string

M:Mandatory

Returned Message

data

string

M:Mandatory

Data is available for successful processed result. Otherwise, field data are absent.

Tax Refund Status	status	string	M:Mandatory	2:Refunded – Cash ; 3:Refunded – Non Cash ; 7:Voucher Validation – Payment Pending ; other:Your refund query requires further information
Detailed Information	detail	string	M:Mandatory	Detailed information refers to a piece of text description in relation to tax refund status.
Response Code	respCode	string	M:Mandatory

Sample code

Request code

Java

String appid = getPara("appid"), lang = getPara("lang"), data = getPara("data");
Res res = getLocal(lang);
try {
   // handle request
   String appkey = getAppKey(appid);
   if (appkey == null) {
       renderJson(getErrJson(res.get("errorClient")));
       return;
  }
  String decryptData = ThreeDESCodec.decryptData(data, appkey);
  if ("".equals(decryptData)) {
      renderJson(getErrJson(res.get("errorDecrypt")));
      return;
  }
  JSONObject reqJson = JSONObject.fromObject(decryptData);
  if (!reqJson.has("barcode")) {
      renderJson(getErrJson(res.get("errorParameter")));
      return;
  }
  String barcode = reqJson.getString("barcode").trim();
  barcode = barcode.replace("-", "");
   // I.e. S-FR-250-10-10001000 need to be input as SFR2501010001000

   // handle response

   // [{"Code":"System Error","Message":"Index and length must refer to
   // a location within the string.\r\nParameter name: length"}]
  String resultStr = taxRefundService.trackStatusInvoice(barcode);
  if (!resultStr.startsWith("{") && resultStr.contains("Parameter name: length")) {
      renderJson(getErrJson(res.get("errorParameter") + res.get("errorParamBarcode")));
      return;
  }

Response code

Java

  String status = respJson.getString("Status");
  dataJson.put("status", status);
  if ("2".equals(status) || "3".equals(status) || "7".equals(status)) {
      dataJson.put("detail", res.get("fintraxTrackStatus-" + status));
  } else {
      dataJson.put("detail", res.get("fintraxTrackStatus-other"));
  }

  String encryptData = ThreeDESCodec.encryptData(dataJson.toString(), appkey);
  if ("".equals(encryptData)) {
      renderJson(getErrJson(res.get("errorEncrypt")));
      return;
  }

   // prepare result Json
  resultJson.put("data", encryptData);
  resultJson.put("result", "success");
  resultJson.put("msg", "");
  renderJson(resultJson.toString());
} catch (Exception e) {
     logger.error("", e);
     renderJson(String.format(errJsonV2, res.get("fintraxTrackStatusError")));
}

Interface description

Where tax refund Institutions have submitted tax refund documents to UnionPay, cardholders can inquire the current status of tax refund via UnionPay interface, namely whether UnionPay has transferred the amount of tax refund into the account of UnionPay cardholders.

Request Method

HTTP GET

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Access to Application Identification

appid

string

M:Mandatory

Subject to the provisions of the both parties, namely 32 digits.

Language

lang

string

M:Mandatory

en – English.

Request Message

data

string

M:Mandatory

Piece data in different fields required by interfaces into character string of JSON format, and then go through encryption as per the regulated rules.

Termination Date	end_date	string	M:Mandatory	Form as YYYYMMDD.
Commencement Date	start_date	string	M:Mandatory	Commencement Date: it shall be earlier than the termination date and be controlled within three (3) months earlier than the existing date. Form as YYYYMMDD.
Card Number	cardno	string	M:Mandatory	UnionPay card number shall go through the SHA-256 encryption. Multiple card numbers can be separated via comma.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Processed Result

result

string

M:Mandatory

success or fail.

Description of Processed Result

msg

string

M:Mandatory

Returned Message

data

string

M:Mandatory

Data is available for successful processed result. Otherwise, field data are absent.

Aggregation of Relevant Tax Refund Records

trans

string

M:Mandatory

Aggregation of relevant tax refund records having format being JsonArray. Where relevant records are absent for corresponding card number, it refers to a null set.

Bank Card Number	cardno	string	M:Mandatory	Pass card number on querying.
Tax Refund Status	taxrefund_status	string	M:Mandatory	0: Not liquidated ; 1: Liquidated ; 2: Error on acquisition status.
Name of Tax Refund Institution	taxrefund_agent	int	M:Mandatory	Such as GlobalBlue
Liquidation Date of Tax Refund Transaction	refund_date	string	M:Mandatory	Such as 20160222.
Amount of Tax Refund	refund_amount	string	M:Mandatory	Such as 100.123
Currency of Tax Refund	refund_curr	string	M:Mandatory

Sample code

Request code

Java

 String appid = getPara("appid"), lang = getPara("lang"), data = getPara("data");
 Res res = getLocal(lang);
 try {
     // handle request
     String appkey = getAppKey(appid);
     if (appkey == null) {
         renderJson(getErrJson(res.get("errorClient")));
         return;
  }
  String decryptData = ThreeDESCodec.decryptData(data, appkey);
  if ("".equals(decryptData)) {
      renderJson(getErrJson(res.get("errorDecrypt")));
      return;
  }
  JSONObject reqJson = JSONObject.fromObject(decryptData);
  String[] cardnos;
  String startDate, endDate;
  try {
      cardnos = reqJson.getString("cardno").split(",");
      startDate = reqJson.getString("start_date").trim();
      endDate = reqJson.getString("end_date").trim();
  } catch (JSONException e) {
      logger.error("", e);
      renderJson(getErrJson(res.get("errorParameter") + e.getMessage()));
  return;
 }

Response code

Java

List<TblRefundTrans> list = DBService.findRefundTrans(cardnos, startDate, endDate);

// save query
DBService.saveQuery(newTblQuery(appid, EnumPartner.UPI, "", reqJson.toString(), "",list == null ? "" : "" + list.size()));

// prepare result Json
JSONObject resultJson = new JSONObject(), dataJson = new JSONObject();
JSONArray trans = new JSONArray();
if (list != null) {
    for (TblRefundTrans t : list) {
        JSONObject tran = new JSONObject();
        tran.put("cardno", t.getStr("CARD_NO_REF"));
        tran.put("taxrefund_status", t.getStr("ISSR_SETT_FLAG") == null ? "2" : t.getStr("ISSR_SETT_FLAG"));
        String iincode = t.getStr("ACQ_INS_CODE"), orgName = ConfigHolder.get("org_" + iincode);
        tran.put("taxrefund_agent", orgName == null ? iincode : orgName);
        tran.put("refund_date", t.getStr("SETT_DATE"));
        tran.put("refund_amount", t.getDouble("AFTER_SETT_AMT"));
        tran.put("refund_curr", t.getStr("AFTER_SETT_CURR"));
        trans.add(tran);
   }
 }
dataJson.put("trans", trans);

String encryptData = ThreeDESCodec.encryptData(dataJson.toString(), appkey);
if ("".equals(encryptData)) {
    renderJson(getErrJson(res.get("errorEncrypt")));
    return;
}
resultJson.put("data", encryptData);
resultJson.put("result", "success");
resultJson.put("msg", "");
renderJson(resultJson.toString());
} catch (Exception e) {
    logger.error("", e);
    renderJson(getErrJson(e.getMessage()));
}

Interface description

Cardholders can inquire the tax refund branches of specific tax refund Institutions available to provide tax refund service in certain countries and cities by virtue of such UnionPay interface.

Request Method

HTTP GET

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Access to Application Identification

appid

string

M:Mandatory

Subject to the provisions of the both parties, namely 32 digits.

Language

lang

string

M:Mandatory

en – English.

Request Message

data

string

M:Mandatory

Piece data in different fields required by interfaces into character string of JSON format, and then go through encryption as per the regulated rules.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Processed Result

result

string

M:Mandatory

success or fail.

Description of Processed Result

msg

string

M:Mandatory

Returned Message

data

string

M:Mandatory

Data is available for successful processed result. Otherwise, field data are absent.

Country Name or City Name	name	string	M:Mandatory
Agent	agent	string	M:Mandatory
Address	address	string	M:Mandatory
Opening hours	openingHours	string	M:Mandatory
Accepted Vouchers	acceptedVouchers	string	O:Optional
Excluded Vouchers	excludedVouchers	string	O:Optional
Latitude	latitude	string	M:Mandatory
Longitude	longitude	string	M:Mandatory

Sample code

Request code

Java

public void listRefPoints() {
    try {
        String type = getPara("type"), id = getPara("id");
        JSONArray array = new JSONArray();
        JSONObject respJson = JSONObject.fromObject(taxRefundService.listRefPoints(Integer.parseInt(type), id));
        JSONArray nodes = JSONArray.fromObject(respJson.get("nodes"));
        for (int i = 0; i < nodes.size(); i++) {
            JSONObject obj = nodes.getJSONObject(i).getJSONObject("node");
            array.add(obj);
        }
        renderJson(array.toString());
} catch (Exception e) {
        logger.error("", e);
        renderJson(String.format(errJsonV2, e.getMessage()));
}
}

Response code

Java

public void listRefPoints() {
    try {
        String type = getPara("type"), id = getPara("id");
        JSONArray array = new JSONArray();
        JSONObject respJson = JSONObject.fromObject(taxRefundService.listRefPoints(Integer.parseInt(type), id));
        JSONArray nodes = JSONArray.fromObject(respJson.get("nodes"));
        for (int i = 0; i < nodes.size(); i++) {
            JSONObject obj = nodes.getJSONObject(i).getJSONObject("node");
            array.add(obj);
        }
        renderJson(array.toString());
} catch (Exception e) {
        logger.error("", e);
        renderJson(String.format(errJsonV2, e.getMessage()));
}
}

Interface description

Cardholders can inquire tax refund merchants by virtue of suchUnionPay interface.

Request Method

HTTP GET

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Access to Application Identification

appid

string

M:Mandatory

Subject to the provisions of the both parties, namely 32 digits.

Language

lang

string

M:Mandatory

en – English.

Request Message

data

string

M:Mandatory

Piece data in different fields required by interfaces into character string of JSON format, and then go through encryption as per the regulated rules.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Processed Result

result

string

M:Mandatory

success or fail.

Description of Processed Result

msg

string

M:Mandatory

Returned Message

data

string

M:Mandatory

Data is available for successful processed result. Otherwise, field data are absent.

Store Name	storeName	string	M:Mandatory
Address	address	string	M:Mandatory
Image	image	string	O:Optional
Store Type	storeType	string	M:Mandatory
Latitude	latitude	string	M:Mandatory
Longitude	longitude	string	M:Mandatory
City	city	string	M:Mandatory

Sample code

Request code

Java

public void listMerchants() {
    try {
        int type = getParaToInt(""type"");
        String id = getPara(""id"");
        JSONArray array = new JSONArray();
        JSONObject respJson = JSONObject.fromObject(taxRefundService.listMerchants(type, id));
        JSONArray nodes = JSONArray.fromObject(respJson.get(""nodes""));
        for (int i = 0; i < nodes.size(); i++) {
            JSONObject obj = nodes.getJSONObject(i).getJSONObject(""node"");
            array.add(obj);
        }
        renderJson(array.toString());
} catch (Exception e) {
        logger.error("""", e);
        renderJson(String.format(errJsonV2, e.getMessage()));
}
}

Response code

Java

public void listMerchants() {
    try {
        int type = getParaToInt(""type"");
        String id = getPara(""id"");
        JSONArray array = new JSONArray();
        JSONObject respJson = JSONObject.fromObject(taxRefundService.listMerchants(type, id));
        JSONArray nodes = JSONArray.fromObject(respJson.get(""nodes""));
        for (int i = 0; i < nodes.size(); i++) {
            JSONObject obj = nodes.getJSONObject(i).getJSONObject(""node"");
        array.add(obj);
        }
        renderJson(array.toString());
} catch (Exception e) {
        logger.error("""", e);
        renderJson(String.format(errJsonV2, e.getMessage()));
}
}

Steps to Launch

1.Initial Communication

Both sides discuss about the business scenarios and product requirements that need to be realized.

2.Cooperative agreement signing

Defining cooperation and service content and signing cooperation agreement.

3.Development and testing

Product development and testing according to needs.

4.Product Launch

Completing product generation test, pilot and official launch.

Response Code Reference

Response code	Description
00	success
01	card invalid
02	API exception
03	ID invalid
04	mobile invalid

Card Product

Online Payment

Mobile QuickPass

QR Code

Cross-Border B2B Service

Token Program

SaaS Card Issuing Service Platform

Block Chain

Platforms

Global Service

Digital Solutions

Industry Solutions

Deferred Online ODA Mode

Real-Time Mode

Frictionless Parking

Transit QR Code Mode

Prompt

Kindly Reminder

Prompt