declare

2024-04-10 03:24

POST /v1/customs/declare

Use this API to transmit information to customs.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

declarationRequestId String REQUIRED

The unique ID that is assigned by the merchant to identify a declaration request. The length of each declaration request number ranges from 1 to 32 bits.

More information about this field

This field is an API idempotency field.
Maximum length: 32 characters

paymentId String REQUIRED

The unique ID that is assigned by Alipay to identify a payment.

More information about this field

Maximum length: 64 characters

declarationAmount Amount object REQUIRED

The accumulated transaction declaration amount, which cannot be greater than the total transaction amount. Only China customs declaration is supported. The default currency is CNY (Chinese Renminbi).

Note: This field can be obtained from the customsDeclarationAmount field in the notifyPayment request and inquiryPayment response.

Show child parameters

customs CustomsInfo object REQUIRED

The customs information

Show child parameters

merchantCustomsInfo MerchantCustomsInfo object REQUIRED

The merchant information that is registered in the customs system.

Show child parameters

splitOrder Boolean REQUIRED

The merchant can decide whether the order is split for declaration. If the value of this field is true, order splitting is allowed. If the value of this field is false, no order splitting is allowed.

suborderId String

The suborder ID that is assigned by the merchant.

Notes:

Specify this field when splitOrder is true. The suborder ID is transmitted to the customs as the order ID in the payment information when the following business scenarios occur:

A payment contains multiple commodities and needs to be submitted to different customs, or the customs require separate submission according to the commodities.
In a combined payment, a customs declaration is required for some commodities.
Other situations where customs declaration needs to be split.

After the order is split, ensure that the suborder ID of these two suborders is the same as the order ID in the payment information. Otherwise, the order will be rejected due to information inconsistency.

More information about this field

Maximum length: 64 characters

buyerCertificate Certificate object

The buyer information.

Notes:

Specify this field when the buyer information needs to be verified. Actually, it is recommended to provide the buyer information in this API to meet the customs declaration policy requirements and facilitate Alipay to check the buyer information. Although this field is optional, it is suggested to specify this field because customs will check buyer information at random.
If this field is not specified, the merchant needs to ensure that the buyer and payer information is consistent. Any inconsistency detected by customs will result in a rejected declaration. Specifying this field will reduce the risk of the order being returned.

Show child parameters

Response parameters

result Result object REQUIRED

The request result, which contains information such as status and error codes.

Note: This field does not indicate the declaration result. This field only indicates whether the declare API is called successfully.

Show child parameters

customsPaymentId String

The payment ID provided to the customs by the declaration service provider.

Note: This field is returned when result.resultCode is S.

More information about this field

Maximum length: 64 characters

customsOrderId String

The order ID provided to the customs by the declaration service provider.

Note: This field is returned when result.resultCode is S.

More information about this field

Maximum length: 64 characters

identityCheckResult String

The identity check result. Valid values are:

CHECK_PASSED: indicates that the buyer is also the payer.
CHECK_NOT_PASSED: indicates that the buyer is not the payer.

Note: This field is returned when result.resultCode is S. If this field is not returned, it indicates that the buyer's identity is not checked.

clearingChannel String

The clearing organization. Valid values are:

CUP: indicates that the clearing channel is Unionpay. For example, when the user uses the bank card to pay, this value might be returned.
NUCC: indicates that the clearing channel is NetsUnion. For example, when the user uses the bank card to pay, this value might be returned.
OTHER: indicates that the clearing channel is others. For example, when the user uses credit products such as Huabei, this value is returned.

Note: This field is returned when these two conditions are met:

resultCode is S.
The customs receipt is returned.

clearingTransactionId String

The clearing organization's serial number.

Note: This field is returned when these two conditions are met:

resultCode is S.
The customs receipt is returned.

More information about this field

Maximum length: 64 characters

customsProviderRegistrationId String

The registration ID in the customs system.

Note: This field is returned when these two conditions are met:

resultCode is S.
The customs receipt is returned.

More information about this field

Maximum length: 32 characters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Request Body

Response

Case

Success

Response Body

More Information

This section provides additional information about this API.

Customs code

This table shows details about the 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 ZHENGZHOU	ZHENGZHOU	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

Payment information retransmission

The declare API can be re-triggered for sending payment data to customs. Retransmission is used when:

The payment data is missing in the customs system.
The previous declaration data contains the wrong information.

Notes:

declarationRequestId must be the same as the original request, otherwise, it will be considered as a new request.
Only merchantCustomsCode, merchantCustomsName, customsPlace, declarationAmount, suborderId, and buyer can be modified in the retransmission. The retransmission's declarationAmount is not included in the total amount of the customs declaration.

Retransmission conditions

Before re-triggering the interface, make sure that the following conditions are met:

The declaration with the same declarationRequestId exists in the Alipay system.
More than 5 minutes have passed since the last call. (Alipay might adjust this time value according to the actual situation.)
Keep all information the same except the values of the following fields:

merchantCustomsCode
merchantCustomsName
customsCode
declarationAmount
suborderId
buyerCertificate.holderName.fullName
buyerCertificate.certificateNo

If declarationAmount has 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 none of the parameter values have changed, return idempotent success.
If retransmission conditions are not met but one or more parameter values have changed, the error code CONTEXT_INCONSISTENT or other error codes will be returned.
If retransmission conditions are met and retransmission is successful, the return value will be the same as that which was returned during the first successful transmission.

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success	The customs declaration is successful. Call the inquiryDeclarationRequests interface to query the customs declaration result.
ACCESS_DENIED	F	Access is denied.	Contact Alipay Technical Support for detailed reasons.
INVALID_API	F	The called API is invalid or not active.	Contact Alipay Technical Support to resolve the issue.
CLIENT_INVALID	F	The client ID is invalid. Alipay has restrictions on the client ID.	Check whether the client ID is correct, or contact Alipay Technical Support for detailed reasons.
DUPLICATED_DECLARATIONS	F	The same order can only be declared once at the same customs.	Check whether paymentId has been used to declare. Use a different payment ID to initiate the declaration request.
INVALID_CONTRACT	F	The parameter values in the contract do not match those in the current transaction.	Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Alipay Technical Support to troubleshoot the issue.
INVALID_SIGNATURE	F	The signature is not validated. The private key used to sign a request does not match the public key of Antom Dashboard.	Check whether the private key used to sign a request matches the public key of Antom Dashboard. The following signature references are useful: The signature field in a request header How to calculate a signature
KEY_NOT_FOUND	F	The private key or public key of Alipay or the merchant is not found.	Check whether the private key or public key exists. If not, upload the private key in Antom Dashboard.
MEDIA_TYPE_NOT_ACCEPTABLE	F	The server does not implement the media type that is acceptable to the client.	Check whether the media type is correct and use a media type that is accepted by Alipay.
MERCHANT_NOT_REGISTERED	F	The merchant is not registered.	Please register the merchant by using the registration interface. Contact Alipay Technical Support if failed to call the registration interface.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method. Only the POST method is supported.	Ensure the HTTP method is POST.
NO_INTERFACE_DEF	F	API is not defined.	Check whether the URL is correct. Please refer to the endpoint in the API documentation.
ORDER_NOT_EXIST	F	The order does not exist.	Check whether paymentId is correct. If correct, contact Alipay Technical Support for specific reasons.
ORDER_STATUS_INVALID	F	The order status is invalid. The transaction is under process or the transaction is failed.	Check the order status and take corresponding actions. Wait if the transaction is under process. Do not initiate the declaration if the transaction failed. If not, contact Alipay Technical Support for specific reasons.
PARAM_ILLEGAL	F	The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong.	Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid.
PROCESS_FAIL	F	A general business failure occurred.	Do not retry. Human intervention is usually needed. It is recommended that you contact Alipay Technical Support to troubleshoot the issue.
REPEAT_REQ_INCONSISTENT	F	The amount or currency is different from the previous request.	Use a unique declarationRequestId value to initiate the customs declaration again. In retransmission scenarios, make sure to meet all the conditions in the retransmission conditions section and retransmission.
RISK_REJECT	F	The request is rejected because of the risk control.	Prompt the user that the request is rejected because the risk control failed.
SYSTEM_ERROR	F	A system error occurred.	Do not retry, and contact Alipay Technical Support for more details.
TOTAL_DECLARATION_AMOUNT_EXCEED	F	The total declared amount exceeds the payment amount.	Confirm whether the total declared amount exceeds the payment amount. Create a new declaration by using an amount less than or equal to the payment amount, or contact Alipay Technical Support.
USER_STATUS_ABNORMAL	F	The user status is abnormal on the wallet side.	Contact Alipay Technical Support to know the specific reasons.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support.