Open API >Data Service >UnionPay Tax Refund
UnionPay Tax Refund
Data Service Developer 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.
API Introduction
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
Flow Chart

tax refund 流程图-改.jpg

APIs Included
APIs Included
  • 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-Must Subject to the provisions of the both parties, namely 32 digits.
Language lang string M-Must en – English.
Request Message data string M-Must 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-Must
Mobile Number mobile string M-Must
Bank Card Number cardno string M-Must
ID number certno string M-Must
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-Must success or fail.
Description of Processed Result msg string M-Must
Returned Message data string M-Must Data is available for successful processed result. Otherwise, field data are absent.
Response Code respCode string M-Must
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")));
}


Response Code Reference
Response Code Reference
Response code Description
00 success
01 card invalid
02 API exception
03 ID invalid
04 mobile invalid
Steps to Launch
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.


  • Contact Us
  • If you have any further questions, please register and submit order in your user center.