alipay.acquire.customs

2024-09-05 02:07

Call this interface to transmit information to customs.

Request

Service address

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

Request parameters

Parameter Description

Basic parameter

service

String Required

Interface name

Example:alipay.acquire.customs

partner

String(16) Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088.

Example:2088*********662

_input_charset

String Required

The charset with which the request data are encoded. UTF-8 is supported.

Example:UTF-8

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

sign

String Required

Sign value

Example:2118ac8fad6bc1d9e88a6cd017c18d37

Business parameter

out_request_no

String(32) Required

The unique business number generated by the merchant to identify a declaration operation. The recommended generation rule: yyyymmdd type 8-bit date + 4-bit serial number. The length of this parameter ranges from 6 to 32 bits.

Example:9193457120563834

trade_no

String(64) Required

The transaction serial number of this transaction in the Alipay system

Example:2015051446800462000100020003

merchant_customs_code

String(20) Required

The merchant recordation number in the customs system

Example:hanguo

amount

String(20) Required

The declaration amount in CNY, with the unit of Yuan and up to two digits after the decimal point.

Note: The declaration amount added up by multiple transactions cannot exceed the total amount of transactions.

Example:2

customs_place

String(20) Required

The customs code, both upper and lower cases are supported.

Example:ZONGSHU

merchant_customs_name

String(256) Required

The merchant recordation name in the customs system

Example:jwyhanguo_card

is_split

String(1)

The merchant can decide whether the form is split for declaration. Only when the value of this field is T or t, the form splitting is triggered and customs declaration must support form splitting. If the value of this field is F or f, no form splitting is allowed.

Example:T

sub_out_biz_no

String(32)

The merchant sub order number. The merchant must specify this field when the form is split, otherwise, an error code of INVALID_PARAMETER is returned.

Example:2015080811223212345453

buyer_name

String(10)

Buyer's name in the merchant system

Example:Andy

buyer_id_no

String(18)

The buyer ID in the merchant system

Example:330681199010104783

Response

Synchronous response

Parameter Description

Basic parameter

is_success

String Required

Indicates whether the request succeeds or not, with a value of T for success and F for failure.

Note: a successful request does not mean the business is accepted and processed successfully.

Example:T

sign_type

String

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

sign

String

Sign value

Example:3afc92ac4708425ab74ecb2c4e58ef56

error

String

Error code that is returned when the request is failed to describe the request failure reason. For more information, see the Error Code section in this document.

Example:ILLEGAL_SIGN

Business parameter

result_code

String(32) Required

Processing result of the request, with a value of SUCCESS to indicate the process is successful, or FAIL to indicate the process is failed.

Example:SUCCESS

trade_no

String(64)

The payment number pushed to customs by Alipay

Example:2013111511001004390000105126

alipay_declare_noString(64)

The Alipay declaration serial number

Example:2013112611001004680073956707

detail_error_code

String(48)

Detailed error code, which describes the reason for not receiving a result_code of SUCCESS. If the response code of result_code is SUCCESS, this parameter is not returned. For more information about the value of detail_error_code, see the Error Code section.

Example:SAME_CUSTOMS_DECLARE_ONCE

detail_error_des

String(64)

Explanation of the detailed error code. If result_code is SUCCESS, this parameter is not returned.

Example:The same transaction can only be declared once in the same customs

identity_check

String(1)

This parameter is used to identify whether the payer and shopper is the same person. The value of this parameter can be T or F. Alipay verifies once for the same declaration. The parameter is not returned if multiple retransmissions occur.

Example:T

ver_dept

String(1) Required

The organization that verifies the transaction. The value can be one of the following items:

1: Unionpay

2: NetsUnion

3: Others

Example:3

pay_code

String(18) Required

The Alipay registration ID in the customs system

Example:31222699S7

pay_transaction_id

String(32) Required

The unique ID assigned by Alipay to identify a transaction. The ID can be verified through the organization that is recognized by The People's Bank of China.

Example:2017082300037460045411523

total_amount

String(17) Required

The total amount

Samples

Request

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.customs&partner=208xxxxxxxxx6931&_input_charset=UTF-8&sign_type=MD5&out_request_no=out_request_no_20190904_172900&trade_no=201xxxxxxxxxxxxxxxxxxxx5788&merchant_customs_code=333xxx3222&amount=0.07&customs_place=ZONGSHU&merchant_customs_name=Mika's%20Corporation&is_split=T&sub_out_biz_no=000xxxxxxxxxxxxx8785&buyer_name=%E5%90%B4%E6%96%87%E6%B3%A2&buyer_id_no=340xxxxxxxxxxx3212&sign=5158c4d5ac3e948d431eede501a718cb

Response

Synchronous response

When the request is successful, and the business processing succeeds:

copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="merchant_customs_name">Mika's Corporation</param>
        <param name="amount">0.07</param>
        <param name="_input_charset">UTF-8</param>
        <param name="is_split">T</param>
        <param name="sub_out_biz_no">000xxxxxxxxxxxxx8785</param>
        <param name="sign">5158c4d5ac3e948d431eede501a718cb</param>
        <param name="buyer_name">Tom</param>
        <param name="partner">208xxxxxxxxx6931</param>
        <param name="service">alipay.acquire.customs</param>
        <param name="trade_no">201xxxxxxxxxxxxxxxxxxxxx5788</param>
        <param name="merchant_customs_code">333xxx3222</param>
        <param name="customs_place">ZONGSHU</param>
        <param name="buyer_id_no">340xxxxxxxxxxx3212</param>
        <param name="sign_type">MD5</param>
        <param name="out_request_no">out_request_no_20190904_172900</param>
    </request>
    <response>
        <alipay>
            <alipay_declare_no>201xxxxxxxxxxxxxxxxxx8161</alipay_declare_no>
            <currency>142</currency>
            <identity_check>F</identity_check>
            <out_request_no>out_request_no_20190904_172900</out_request_no>
            <pay_code>31222699S7</pay_code>
            <pay_transaction_id>201xxxxxxxxxxxxxxxxxxxxx5788</pay_transaction_id>
            <result_code>SUCCESS</result_code>
            <total_amount>0.07</total_amount>
            <trade_no>201xxxxxxxxxxxxxxxxxx8161</trade_no>
            <ver_dept>3</ver_dept>
        </alipay>
    </response>
    <sign>197847e2c638d99a6d85a960e7140e19</sign>
    <sign_type>MD5</sign_type>
</alipay>

When the request is successful, but the business processing fails:

copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="trade_no">201xxxxxxxxx0462</param>
        <param name="merchant_customs_code">hanguo</param>
        <param name="sign_type">MD5</param>
        <param name="merchant_customs_name">jwyhanguo_card</param>
        <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
        <param name="amount">2</param>
        <param name="_input_charset">UTF-8</param>
        <param name="customs_place">ZONGSHU</param>
        <param name="service">alipay.acquire.customs</param>
        <param name="out_request_no">919xxxxxxxxx3834</param>
        <param name="partner">208xxxxxxxxx8662</param>
    </request>
    <response>
        <alipay>
           <detail_error_code>SAME_CUSTOMS_DECLARE_ONCE</detail_error_code>
           <detail_error_des>The same transaction can only be declared once in the same customs</detail_error_des>
           <result_code>FAIL</result_code>
        </alipay>
    </response>
    <sign>3afc92ac4708425ab74ecb2c4e58ef56</sign>
    <sign_type>MD5</sign_type>
</alipay>

When the request is failed or the accessed data are incorrect:

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

Synchronous response feature

After Alipay processes the merchant's request, the current Alipay gateway page refreshes automatically and returns the processing result immediately.
For one request, Alipay returns the processing result only once.
The synchronous reponse can be debugged on the local computer, instead on the server.
The processing result is returned in the format of XML.
The XML processing result can be remotely parsed to obtain the result data when Alipay processes the result. In the page with result data, the merchant performs the logical analysis based on the data.
The configuration of the local computer or merchant server must support XML remote parse. For example, SSL is supported.
After the Alipay gateway page refreshes, the link is only valid within one minute. If the link is invalid after one minute, the business logic program written by the merchant in the page cannot be processed.

Payment information retransmission

The declaration interface can be re-triggered for sending payment data to customs, it is used when:

The payment data are missing in the customs system.
The previous declaration data contain wrong information.

Retransmission conditions

The following list describes the conditions before re-triggering the interface:

The declaration with the same out_request_no exists in Alipay system already.
Re-trigger must be more than 5 minutes since last call (Alipay might adjust this time value).
Keep all information the same except the values of the following fields:

merchant_customs_code
merchant_customs_name
customs_place
amount
sub_out_biz_no

The target customs supports retransmission.
Customs NANSHAGJ does not support retransmission. If merchants want to modify the payment information which is already received by Customs NANSHAGJ, contact NANSHAGJ offline to do the modification. If merchants want to retransmit the payment information which is sent by Alipay but is not received by Customs NANSHAGJ, contact Alipay Global Merchant Technical Support (AlipayGlobalTechService@service.alipay.com) to do manual retransmission.
If the amount is changed, the new declaration amount cannot exceed the original total transaction amount.

Retransmission Response

The following list describes the responses under different situations:

If retransmission conditions are not met and no parameter value is changed, return idempotent success.
If retransmission conditions are not met but one or more parameter values are changed, return the error code CONTEXT_INCONSISTENT or other error codes.
If retransmission conditions are met and retransmission is successful, return value is the same as that returned during the first successful transmission.

Note:

Merchants can use the QUERY interface to query the retransmission status.

Unified customs solution

According to the unified messages announced by General Administration of Customs since 2017, the information is only transmitted to General Administration of Customs or only to local customs. However, if the customs is in Tianjin city or Henan province, merchants transmit the payment information to both General Administration of Customs and the local customs. Merchants can check the transmission solutions in Customs code.

When is_split is not T or no value is passed into is_split:

First transmit to the local customs, then use the new out_request_no to transmit to General Administration of Customs.
To ensure that the information is matched, keep the fields of two transmissions the same except the following fields:

customs_place
merchant_customs_code
merchant_customs_name

When is_split is T:

First transmit to the local customs, then transmit the same out_request_no to General Administration of Customs.
To ensure that the information is matched, keep the fields of two transmissions the same except the following fields:

customs_place
merchant_customs_code
merchant_customs_name

Note:

The declaration amount transmitted to General Administration of Customs and local Customs will not be added up.

Customs code

Customs name	Unified customs solution	Customs code	Alipay registration ID
General Administration of Customs	Transmit to ZONGSHU	ZONGSHU	31222699S7
Henan bonded logistics center	Transmit to ZONGSHU	ZONGSHU	31222699S7
Ningbo Customs	Transmit to NINGBO	NINGBO	31222699S7
Xinzheng comprehensive bonded zone (Airport)	Transmit to ZONGSHU	ZONGSHU	31222699S7
Tianjin Customs	Transmit to ZONGSHU	ZONGSHU	31222699S7
Shanghai Customs	Transmit to SHANGHAI_CBT	SHANGHAI_CBT	31222699S7
Guangzhou Customs (Airport)	Transmit to ZONGSHU	ZONGSHU	31222699S7
Guangzhou Customs (Nansha)	Transmit to ZONGSHU	ZONGSHU	31222699S7
Guangzhou Customs (Huangpu)	Transmit to ZONGSHU	ZONGSHU	31222699S7
Guangzhou Customs (Shatian)	Transmit to ZONGSHU	ZONGSHU	31222699S7
Hangzhou Customs	Transmit to ZONGSHU	ZONGSHU	31222699S7

Error code

Error code	Description	Reason	Solution
TRADE_NOT_EXIST	The transaction does not exist.	The passed in value of trade_no is incorrect and not found.	Confirm if the value of trade_no is correct.
TRADE_STATUS_ERROR	The transaction status is not supported for declaration.	The transaction does not complete the payment successfully.	Confirm the transaction status.
INVALID_PARAMETER	Incorrect parameter	The value exceeds the length or the value is not passed in.	Check the parameter format according to the API document.
CONTEXT_INCONSISTENT	The parameters of the same transaction are inconsistent.	Send multiple requests for the same transaction and the parameters are inconsistent.	Confirm if the parameters are correct.
SAME_CUSTOMS_DECLARE_ONCE	The same transaction can only be declared once at the same customs.	The same transaction can only be declared once at the same customs.	Confirm if the the transaction is already declared at the same customs.
REQUEST_AMOUNT_EXCEED	The amount exceeds the limit.	The added up declaration amount exceeds the transaction amount.	Confirm the accumulated declaration amount of the transaction.
PARTNER_ERROR	The partner IDs in the transaction and declaration are inconsistent.	The partner IDs in the transaction and declaration are inconsistent.	Confirm if the partner in the declaration is the same with the one in the transaction.
PAYER_ENABLE_STATUS_FORBID	Invalid status of the payer	The status of the payer in the declared transaction cannot pass the verification.	Confirm the account status of the payer in Alipay.