Customs Declaration

Declaration Query Interface

Request Parameter Description

Request parameters are the request data provided to Alipay when merchants are exchanging data with Alipay, in order for Alipay to carry out further processing based on these data.

Parameter	Type (byte length)	Parameter Description	Null or Not	Examples
Basic Parameters
service	String	The interface name	Not Null	alipay.overseas.acquire.customs.query
partner	String(16)	The unique Alipay user ID corresponding to the signed Alipay account. The 16-bit pure number started with 2088.	Not Null	2088101568338364
_input_charset	String	The encoding formats used by the merchant websites, such as utf-8, gbk, gb2312, etc.	Not Null	UTF-8
sign_type	String	The three optional values are DSA, RSA, and MD5, which must be capitalized.	Not Null	MD5
sign	String	Please refer to "Appendix: Signature and Signature Verfication" of this document.	Not Null	b7baf9af3c91b37bef4261849aa76281
Business Parameters
out_request_nos	String(329)	The merchant-side declaration request number to be requested supports batch queries, multiple values are separated by English commas, and there are up to 10 declaration request numbers in one time The length of each declaration request number ranges from 6 to 32 bits, without spaces before or after, and only the following types of characters are allowed to be passed: numbers, English letters, "_", "-", ":"	Not Null	201506010001,201506010002,201506010003

https://mapi.alipay.com/gateway.do?out_request_nos=201506010001%2C201506010002%2C201506010003&sign_type=MD5&sign=b7baf9af3c91b37bef4261849aa76281&_input_charset=UTF-8&service=alipay.overseas.acquire.customs.query&partner=2088101568338364

Description:

This sample is for reference only, and the gateway of Alipay ishttps://mapi.alipay.com/gateway.do.

Synchronous Reponse Parameters

After Alipay processes the request data provided by the merchant, it will return the result data in order for the merchant to carry out further processing based on these data.

The returned results are divided into two scenarios, one is the result from normally accepted business, and another is system-level exception or accessed data errors. For the normally accepted business, the merchants need to parse the response code to determine whether the business is successfully processed.

Parameter	Type (Length Range)	Parameter Description	Null or Not	Examples
Basic Parameters
is_success	String	Whether the request is successful. A successful request doesn't mean the business has been processed successfully. T represents success F represents failure	Not Null	T
sign_type	String	The three optional values are DSA, RSA, and MD5, which must be capitalized.	Nullable	MD5
sign	String	Please refer to "Appendix: Signature and Signature Verification" of this document.	Nullable	3afc92ac4708425ab74ecb2c4e58ef56
error	String	When a request is successful, this parameter does not exist; When a request failed, this parameter is an error code.	Nullable	ILLEGAL_SIGN
Business Parameters
result_code	String(32)	The response code of processing results. SUCCES: success FAIL: Failure	Not Null	SUCCESS
not_found	String	The business is processed successfully (result_code=SUCCESS), but there are unfound declaration request numbers, then this parameter can be returned, and multiple values are separated by English commas.	Nullable	201506010001
detail_error_code	String(48)	The cause description to returned response code, please refer to Business Error Codes. When the result_code response code is SUCCESS, this parameter will not be returned.	Nullable	INVALID_PARAMETER
detail_error_des	String(64)	The textual description to detailed error code, please refer to the meanings in Business Error Codes. When the result_code response code is SUCCESS, this parameter will not be returned.	Nullable	Declaration Form Parameters Illegal
<customs_declare>There may exist multiple declaration form information, and xml nodes
out_request_no	String(32)	The merchant-side declaration request number, corresponding to a certain declaration request number in the parameters	Nullable	4877067126133624
alipay_declare_no	String(64)	The Alipay declaration serial number.	Nullable	2015082011082370647505271
trade_no	String(64)	The payments document number pushed to customs by Alipay. For the split declaration request, this document number is not equal to the original transaction number of Alipay	Nullable	2015082011082370647505271
customs_place	String(20)	The customs number.	Nullable	hangzhou
merchant_customs_code	String(20)	The merchant customs recordation number.	Nullable	code
merchant_customs_name	String(256)	The merchant customs recordation name.	Nullable	1
amount	String(20)	The declaration amount, with the unit RMB "Yuan", up to two digits after the decimal point.	Nullable	1.00
is_split	String(1)	T: Form-splitting F: Non-form-splitting	Nullable	T
sub_out_biz_no	String(32)	The merchant sub order number. It is passed during form splitting by the merchant and must be passed during form splitting.	Nullable	999999999999999
status	String(10)	The current status of this declaration form. ws: Waiting for sending to the customs sending: Submitted to send to the customs succ: Customs returned acceptance successfully	Nullable	succ
memo	String(256)	The notes.	Nullable	The customs returned parameters is illegal
last_modified_time	String(20)	The last update time of status.	Nullable	10/15/2015 2:24:56 PM
customs_code	String	After the declaration is launched, the result code in the customs returned receipt. 2: E-port in the declaration 3: Sending to customs successful 4: Sending to customs failed 100: Customs form withdrawal 399: Customs conclusion Numbers less than 0: The exception handling receipts Note: Alipay returns the data as returned by the customs, and the parameter values subject to the customs definition.	Nullable	2
customs_info	String	After the declaration is launched, the result description in the customs returned receipt.	Nullable	Adding Declaration Successful [B0B2F23E-2CF6-434D-9F24-8931B835A056]
customs_return_time	String	After the declaration is launched, the receipt time returned by customs, with the format: yyyyMMddHHmmss.	Nullable	20160414142358

Description:

The synchronously returned parameters may return more nodes with the evolution of the Alipay service side, which requires the program users to ignore the nodes outside the document description.

Example of successful query return:


<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="sign">eb9ece9d658e7a9671411d1b43b5750c</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign_type">MD5</param>
        <param name="service">alipay.overseas.acquire.customs.query</param>
        <param name="out_request_nos">4877067126133624,7665166179649532</param>
        <param name="partner">2088101143686350</param>
    </request>
    <response>
        <alipay>
            <records>
                <customs_declare>
                    <alipay_declare_no>2015082011082370647505271</alipay_declare_no>
                    <amount>1.00</amount>
                    <is_split>T</is_split>
                    <sub_out_biz_no>999999999999999</sub_out_biz_no>
                    <customs_place>hangzhou</customs_place>
                    <last_modified_time>2015-10-15 14:24:56</last_modified_time>
                    <memo/>
                    <merchant_customs_code>code</merchant_customs_code>
                    <merchant_customs_name>1</merchant_customs_name>
                    <out_request_no>4877067126133624</out_request_no>
                    <status>succ</status>
                    <trade_no>2015082011082370647505271</trade_no>
                    <customs_code>2</customs_code>
                    <customs_info> Adding Declaration Successful [B0B2F23E-2CF6-434D-9F24-8931B835A056]</customs_info>
                    <customs_return_time>20160414142358</customs_return_time>
                </customs_declare>
                <customs_declare>
                    <alipay_declare_no>2015081811082379147506255</alipay_declare_no>
                    <amount>1.00</amount>
                    <customs_place>henan</customs_place>
                    <last_modified_time>2015-10-15 14:24:56</last_modified_time>
                    <memo/>
                    <merchant_customs_code>code</merchant_customs_code>
                    <merchant_customs_name>name</merchant_customs_name>
                    <out_request_no>7665166179649532</out_request_no>
                    <status>succ</status>
                    <trade_no>2015081710650237</trade_no>
                    <customs_code>2</customs_code>
                    <customs_info> Adding Declaration Successful [B0B2F23E-2CF6-434D-9F24-8931B835A056]</customs_info>
                    <customs_return_time>20160414142358</customs_return_time>
                </customs_declare>
            </records>
            <result_code>SUCCESS</result_code>
        </alipay>
    </response>
    <sign>15669c65f3d19d0691425bba349a8b55</sign>
    <sign_type>MD5</sign_type>
</alipay>

Example of when a request is successful, but the business processing fails:


<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="sign">48201072f0d0991c3bab798d963c6cd8</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign_type">MD5</param>
        <param name="service">alipay.overseas.acquire.customs.query</param>
        <param name="out_request_nos">4877067126133624,7665166179649532,,</param>
        <param name="partner">2088101143686350</param>
    </request>
    <response>
        <alipay>
            <detail_error_code>INVALID_PARAMETER</detail_error_code>
            <detail_error_des> Declaration Form Parameters Illegal </detail_error_des>
            <result_code>FAIL</result_code>
        </alipay>
    </response>
    <sign>48fd2067e7fa2a7e779465d9e80dced5</sign>
    <sign_type>MD5</sign_type>
</alipay>

Example of when a request is failed or the accessed data is incorrect:


<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
</alipay>

Synchronous Response Features

After Alipay has processed the request data of merchants, the current Alipay gateway page (https://mapi.alipay.com) will be automatically refreshed, and output the processing results immediately;
The current interface will be redirected back once for processing one request, which means the processing results will be only returned once;
This step can be debugged on the local computer, without the use of server;
The display format of processing results is the XML format;
This XML format processing result can be remotely analyzed in XML, so that it can get the relevant processing result data when Alipay processes the results, and carry out the business logic processing of merchant to this result interface;
The configurations of local computers and merchant servers need to support the XML remote analysis, such as: the support of SSL;
After the page is redirected, the link in the browser address bar is only valid within one minute and will be invalid afterwards, causing the business logic programs written by merchants in this page cannot be processed.

Business Error Codes

Detailed Error Code (detail_error_code)	Meaning (detail_error_des)
INVALID_PARAMETER	The parameter format is illegal: more than 350 characters, empty, a form number is empty, or a form number is more than 32 characters
MAX_OUT_REQUEST_NO_EXCEEDED	The number of declaration forms in a single request is more than 10

Generate Pre-sign string

Parameters to sign

In the list of request and response parameters, all of them need to be signed except sign and sign_type. (sign_type also needs to be signed in some cases in the list of request parameters)

Generate Pre-sign string

Use the following code to package the data:


		//package the request parameters
		Map sParaTemp = new HashMap();
		sParaTemp.put("service", AlipayConfig.service);
                sParaTemp.put("partner", AlipayConfig.partner);
                sParaTemp.put("_input_charset", AlipayConfig.input_charset);
		sParaTemp.put("notify_url", AlipayConfig.notify_url);
		sParaTemp.put("return_url", AlipayConfig.return_url);
		sParaTemp.put("out_trade_no", out_trade_no);
		sParaTemp.put("subject", subject);
		sParaTemp.put("total_fee", total_fee);
		sParaTemp.put("body", body);
		sParaTemp.put("currency", currency);
		sParaTemp.put("product_code", product_code);
		split_fund_info = split_fund_info.replaceAll("\"", "'");
		sParaTemp.put("split_fund_info", split_fund_info);

		sParaTemp.put("secondary_merchant_id",secondary_merchant_id);
		sParaTemp.put("secondary_merchant_name",secondary_merchant_name);
		sParaTemp.put("secondary_merchant_industry",secondary_merchant_industry);

Rearrange parameters in the data set alphabetically
And connect rearranged parameters with &：

_input_charset=utf-8&app_pay=Y&body=test&currency=USD&notify_url=http://d4779318.ngrok.io/new_create_forex_trade_wap_JAVA-UTF-8-RSA/notify_url.jsp&out_trade_no=test20170901162***&partner=2088101122136***&product_code=NEW_WAP_OVERSEAS_SELLER&return_url=http://d4779318.ngrok.io/new_create_forex_trade_wap_JAVA-UTF-8-RSA/return_url.jsp&service=create_forex_trade_wap&subject=test123&total_fee=0.01

This is the pre-sign string.

Parameters without a value, can be excluded from sign;
Charset in sign must be consistent with the charset used previously
If _input_charset is passed, it also shall be signed.
According to HTTP protocol, special character like &,@ needs to do URL encoding, therefore the request receiver can get correct value. In this situation, pre-sign string shall be the original value instead of encoded one. For example: calling a particular API need to sign the parameter email, the pre-sign string shall be email=test@msn.com, rather than email=test%40msn.com.

Signature Generation

MD5 Signature

Private Key is necessary for MD5 signature. The MD5 private key is the 32-byte string which is composed of English letters and numbers. Partner can log on the Merchant Service Center (https://global.alipay.com) to check the private key.

Sign for request

After the partner receives the pre-sign string during requesting, the private key should be appended to the pre-sign string to generate the new string. Then this new string would be calculated with the MD5 signature algorithm by the MD5 signature function. Thus, the result 32-byte string is the signature result string. (the value is given to parameter “sign”)

Signature Verification for response

After receiving the pre-sign string during responding from Alipay system, the next step is the same as the procedure of Sign for request. When the 32-byte signature result string is generated, it should be verified whether the value is equal to the value of the parameter “sign”. If equal, the verification would be passed.

RSA, RSA2 Signature

Both private key and public key are necessary for RSA signature. Both private key and public key are generated with OPENSSL by partner. Partner and Alipay need to exchange their own public key. Therefore, partner uses Alipay public key and partner private key.

Sign for request

After the partner receives the pre-sign string during requesting, the partner private key and the pre-sign string are used in the RSA signature algorithm by the RSA signature function to get the result string. (the value is given to parameter “sign”)

Signature Verification for response

After receiving the pre-sign string during responding from Alipay system, the Alipay public key, the pre-sign string and the parameter “sign” are used in the RSA signature asymmetric algorithm by the RSA signature function to accomplish the signature verification.

NEED HELP ?