alipay.overseas.tax.order.pay

2023-05-09 09:46

Call this interface to pay a user's Alipay account.

Request

Service address

Environment	HTTPS request URL
Production environment	Https://globalopenapi.alipay.com/gateway.do

Request parameters

Parameter Description

Basic parameter

app_id

String(32) Required

The unique ID that is assigned by Alipay to identify an application.

Example:2014072300007148

method

String(128) Required

Interface name

Example:alipay.overseas.tax.order.pay

format

String(40)

Only JSON is supported.

Example:JSON

charset

String(10) Required

The charset with which the request data is encoded, such as GBK, UTF-8, and GB2312.

Example:UTF-8

sign_type

String(10) Required

The sign type. RSA and RSA2 are supported. RSA2 is recommended.

Example:RSA2

sign

String(344) Required

Signature value

Example:ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE

timestamp

String(19) Required

The time when the request is sent. The format is yyyy-mm-dd hh:mm:ss.

Example:2014-07-24 03:07:50

version

String(3) Required

The API version. The value is fixed as 1.0.

Example:1.0

app_auth_token

String(40)

See Overview of the app authorization for details.

biz_content

String

The collection of request parameters in JSON format. The maximum length is not limited. Except for common parameters, all other request parameters must be passed in to this parameter.

Business parameter

out_order_no

String(64) Required

The unique serial number that is assigned by the tax refund organization to identify a tax refund order. The length of each serial number ranges from 3-64 bits, and only numbers and English characters can be passed.

Example:0005520171122115751

identify_account_type

String(32) Required

The Alipay account identifier type. The value is fixed as barcode.

Example:barcode

identify_account_no

String(32) Required

The number that is used to identify an Alipay account.

Example:286139798480113981

biz_mode

String(32) Required

The business mode. Only FOREX_TAX_REFUND is supported now.

Example:FOREX_TAX_REFUND

tax_refund_scene_type

String(2) Required

The tax refund type. Only real-time tax refund is supported now.

Example:03

tax_refund_currency

String(3) Required

The currency used by the tax refund agency, which is foreign currency normally and follows the ISO alpha-3 currency code.

Example:SGD

tax_refund_amount

Price(11) Required

The refund amount that is accurate to the smallest unit of the currency specified by tax_refund_currency. For example, if the currency is SGD, the smallest unit is cent. For SGD 100, the value of tax_refund_amount is 10000.

Example:100

user_received_currency

String(3) Required

The currency that the agency uses to pay to the user, which is CNY normally and follows the ISO alpha-3 currency code.

Example:CNY

user_received_amount

Price(11)

The amount that the agency pays to the user, which is accurate to the smallest unit of the currency specified by user_received_currency. For example, if the currency is CNY, the smallest unit is fen. For CNY 100, the value of user_received_amount is 10000.

Example:100

passport_no

String(32)

The user's passport number

Example:103369874587

country_code

String(2) Required

The tax refund country, which follows the ISO standard alpha-2 country code.

Example:SG

passport_name

String(128)

The English name in the passport

Example:GxxLxx

nationality

String(3)

The nationality stated on the user's passport, which follows the three-letter country code in the passport.

Example:CHN

extend_param

String(1024)

The extend parameters, which is in JSON format.

Example:{"key":"value"}

doc_id

String(64) Required

The unique ID of a tax refund form, which is assigned by the tax refund company. The length of each ID ranges from 3-64 bits, and only numbers and English characters can be passed.

Example:12345670001

sales_date

Date(20)

The shopping time on the receipt. The time is in GMT+8, and in a yyyy-mm-dd hh:mm:ss format.

Example:2017-11-28 11:23:04

tax_refund_print_date

Date(20) Required

The print date of a tax refund form. The time is in GMT+8, and in a yyyy-mm-dd hh:mm:ss format.

Example:2017-11-28 11:23:04

doc_expire_date

Date(20) Required

The expiry date of a tax refund form. The time is in GMT+8, and in a yyyy-mm-dd hh:mm:ss format. The expiry time is six months.

Example:2018-05-28 20:23:04

confirm_date

Date(20)

The date of departure confirmation. The time is in GMT+8, and in a yyyy-mm-dd hh:mm:ss format.

Example:2017-11-15 11:23:04

sales_currency

String(3) Required

The currency used when shopping, which follows the ISO standard alpha-3 currency code.

Example:SGD

sales_amount

Price(11) Required

The shopping amount on a tax refund form. The value is a number, which is accurate to the smallest unit of the currency specified by sales_currency. For example, if the currency is SGD, the smallest unit is cent. For SGD 100, the value of sales_amount is 10000.

Example:48000

departure_port

String(64) Required

The port of departure.

Example:airport

company_name

String(64)

The name of the tax refund agency.

Example:KICC

available_day

Number(2) Required

The available days of the tax refund data, which ranges from 15-30 days. If the value of this field exceeds 30 and tax refund is not processed, the tax refund has failed.

Example:15

Response

Parameter Description

Basic parameter

code

String Required

The gateway return code, which indicates whether the request is accepted by the Alipay gateway.

Example:40004

msg

String Required

Description of the gateway return code

Example:Business Failed

sub_code

String

Processing result of the request.

Example:isv.invalid-signature

sub_msg

String

Description of the request's processing result.

Example:The transaction has been paid.

sign

String(64) Required

Signature value

Business parameter

tax_no

String(64) Required

A unique serial number that is assigned by Alipay to identify a tax refund order.

Example:2014102800001425

Error codes

Error code	Description
ILLEGAL_ARGUMENT	The parameter is incorrect. Check each request parameter according to the API specification.
ILLEGAL_IDENTIFY_ACCOUNT_NO	The tax refund has failed. Either the format of the user's account number is incorrect, or the Alipay ID of the user cannot be found.
USER_NOT_EXIST	The tax refund has failed. The user's account information cannot be retrieved. For example, the account has been signed off.
ACCESS_FORBIDDEN	The tax refund result is unknown. The merchant doesn't sign the contract or the contract has expired.
TAX_REFUND_PAY_FAIL	The tax refund has failed. The user's Alipay account was not paid. Either the user's Alipay account cannot collect payment, or the pre-funding of the tax refund agency's Alipay account is insufficient.
AMOUNT_LIMIT_EXCEEDED	The tax refund has failed. The amount exceeds the limit.
REAL_NAME_UNCERTIFIED	The tax refund has failed. The user's Alipay account is not real-name validated.
ILLEGAL_USER	The tax refund has failed. Only individual users can tax refund.
USER_ACCOUNT_FREEZED	The tax refund has failed. The user's Alipay account is frozen.
TAX_REFUND_CLOSED	The tax refund has failed. The tax refund order is expired or closed.
SYSTEM_ERROR	The tax refund result is unknown. The system is busy.
INCONSISTENT_PARAMETER	The tax refund result is unknown. This code is returned when the parameters are changed during a retry.
ILLEGAL_REFUND_CURRENCY	The tax refund has failed. The value of `TAX_REFUND_CURRENCY` is inconsistent with the value stated in the contract.
PAYMENT_CLOSED	The tax refund has failed. The payment is closed due to timeout.

Samples

Request sample

JAVA

copy
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayOverseasTaxOrderPayRequest request = new AlipayOverseasTaxOrderPayRequest(); request.setBizContent("{" +
"\"out_order_no\":\"0005520171122115751\"," + "\"identify_account_type\":\"barcode\"," + "\"identify_account_no\":\"286139798480113981\"," + "\"biz_mode\":\"FOREX_TAX_REFUND\"," + "\"tax_refund_scene_type\":\"03\"," + "\"tax_refund_currency\":\"SGD\"," + "\"tax_refund_amount\":100," + "\"user_received_currency\":\"CNY\"," + "\"user_received_amount\":100," + "\"passport_no\":\"103369874587\"," + "\"country_code\":\"SG\"," + "\"passport_name\":\"GONGLEI\"," + "\"nationality\":\"CHN\"," + "\"extend_param\":\"{\\\"key\\\":\\\"value\\\"}\"," + "\"doc_id\":\"12345670001\"," + "\"sales_date\":\"2017-12-18 17:34:13\"," + "\"tax_refund_print_date\":\"2017-12-18 17:34:13\"," + "\"doc_expire_date\":\"2017-12-18 17:34:13\"," + "\"confirm_date\":\"2017-12-18 17:34:13\"," + "\"sales_currency\":\"SGD\"," + "\"sales_amount\":48000," + "\"departure_point\":\"airport\"," + "\"company_name\":\"KICC\"," + "\"available_day\":15" +
" }");
AlipayOverseasTaxOrderPayResponse response = alipayClient.execute(request); if(response.isSuccess()){
System.out.println("Success");
} else {
System.out.println("Fail");
}

PHP

copy
$aop = new AopClient ();
$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do'; $aop->appId = 'your app_id';
$aop->rsaPrivateKey = 'Fill in the developer's private key, one line'; $aop->alipayrsaPublicKey='Fill in the alipay_public_key_file, one line'; $aop->apiVersion = '1.0';
$aop->signType = 'RSA2';
$aop->postCharset='GBK';
$aop->format='json';
$request = new AlipayOverseasTaxOrderPayRequest (); $request->setBizContent("{" . "\"out_order_no\":\"0005520171122115751\"," . "\"identify_account_type\":\"barcode\"," . "\"identify_account_no\":\"286139798480113981\"," . "\"biz_mode\":\"FOREX_TAX_REFUND\"," . "\"tax_refund_scene_type\":\"03\"," . "\"tax_refund_currency\":\"SGD\"," .
"\"tax_refund_amount\":100," . "\"user_received_currency\":\"CNY\"," . "\"user_received_amount\":100," . "\"passport_no\":\"103369874587\"," .
"\"country_code\":\"SG\"," .
"\"passport_name\":\"GONGLEI\"," .
"\"nationality\":\"CHN\"," . "\"extend_param\":\"{\\\"key\\\":\\\"value\\\"}\"," . "\"doc_id\":\"12345670001\"," .
"\"sales_date\":\"2017-12-18 17:34:13\"," . "\"tax_refund_print_date\":\"2017-12-18 17:34:13\"," . "\"doc_expire_date\":\"2017-12-18 17:34:13\"," . "\"confirm_date\":\"2017-12-18 17:34:13\"," . "\"sales_currency\":\"SGD\"," .
"\"sales_amount\":48000," .
"\"departure_point\":\"airport\"," .
"\"company_name\":\"KICC\"," .
"\"available_day\":15" .
" }");
$result = $aop->execute ( $request);
$responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response"; $resultCode = $result->$responseNode->code;
if(!empty($resultCode)&&$resultCode == 10000){
echo "Success";
} else {
echo "Fail"; }

.NET

copy
IAopClient client = new DefaultAopClient("https://openapi.alipay.com/gateway.do", "app_id", "merchant_private_key", "json", "1.0", "RSA2", "alipay_public_key", "GBK", false); AlipayOverseasTaxOrderPayRequest request= new AlipayOverseasTaxOrderPayRequest() ; request.BizContent="{" +
"\"out_order_no\":\"0005520171122115751\"," + "\"identify_account_type\":\"barcode\"," + "\"identify_account_no\":\"286139798480113981\"," + "\"biz_mode\":\"FOREX_TAX_REFUND\"," + "\"tax_refund_scene_type\":\"03\"," + "\"tax_refund_currency\":\"SGD\"," + "\"tax_refund_amount\":100," + "\"user_received_currency\":\"CNY\"," + "\"user_received_amount\":100," + "\"passport_no\":\"103369874587\"," + "\"country_code\":\"SG\"," + "\"passport_name\":\"GONGLEI\"," + "\"nationality\":\"CHN\"," + "\"extend_param\":\"{\\\"key\\\":\\\"value\\\"}\"," + "\"doc_id\":\"12345670001\"," + "\"sales_date\":\"2017-12-18 17:34:13\"," +
"\"tax_refund_print_date\":\"2017-12-18 17:34:13\"," + "\"doc_expire_date\":\"2017-12-18 17:34:13\"," + "\"confirm_date\":\"2017-12-18 17:34:13\"," + "\"sales_currency\":\"SGD\"," + "\"sales_amount\":48000," + "\"departure_point\":\"airport\"," + "\"company_name\":\"KICC\"," + "\"available_day\":15" +
" }";
AlipayOverseasTaxOrderPayResponse response=client.execute(request); Console.WriteLine(response.Body);

HTTP

copy
https://openapi.alipay.com/gateway.do?timestamp=2013-01-01 08:08:08&method=alipay.overseas.tax.order.pay&app_id=5051&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJER EEEEEEEEEEE&version=1.0&biz_content=
{
"out_order_no":"0005520171122115751", "identify_account_type":"barcode", "identify_account_no":"286139798480113981", "biz_mode":"FOREX_TAX_REFUND", "tax_refund_scene_type":"03", "tax_refund_currency":"SGD", "tax_refund_amount":100, "user_received_currency":"CNY", "user_received_amount":100, "passport_no":"103369874587", "country_code":"SG", "passport_name":"GONGLEI", "nationality":"CHN", "extend_param":"{\"key\":\"value\"}", "doc_id":"12345670001", "sales_date":"2017-12-18 17:34:13", "tax_refund_print_date":"2017-12-18 17:34:13", "doc_expire_date":"2017-12-18 17:34:13", "confirm_date":"2017-12-18 17:34:13", "sales_currency":"SGD", "sales_amount":48000, "departure_point":"airport", "company_name":"KICC",
"available_day":15
}
// To ensure secure communication, verify whether the sign value in the response example is provided by Ant Financial.
Response sample
JSON edition:
"alipay_overseas_tax_order_pay_response":{
 "code":"10000",
 "msg":"Success",
"tax_no":"2014102800001425"
}
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" }
Exception sample

JSON

copy
{
"alipay_overseas_tax_order_pay_response":{
"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"System busy"} ,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"}