Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

declare

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 nameUnified customs solutionCustoms codeAlipay registration ID
General Administration of CustomsTransmit to ZONGSHUZONGSHU31222699S7
Henan bonded logistics centerTransmit to ZHENGZHOUZHENGZHOU31222699S7
Ningbo CustomsTransmit to NINGBONINGBO31222699S7
Xinzheng comprehensive bonded zone (Airport)Transmit to ZONGSHUZONGSHU31222699S7
Tianjin CustomsTransmit to ZONGSHUZONGSHU31222699S7
Shanghai CustomsTransmit to SHANGHAI_CBTSHANGHAI_CBT31222699S7
Guangzhou Customs (Airport)Transmit to ZONGSHUZONGSHU31222699S7
Guangzhou Customs (Nansha)Transmit to ZONGSHUZONGSHU31222699S7
Guangzhou Customs (Huangpu)Transmit to ZONGSHUZONGSHU31222699S7
Guangzhou Customs (Shatian)Transmit to ZONGSHUZONGSHU31222699S7
Hangzhou CustomsTransmit to ZONGSHUZONGSHU31222699S7
 

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

CodeValueMessageFurther action
SUCCESSSSuccess

The customs declaration is successful. Call the inquiryDeclarationRequests interface to query the customs declaration result.

ACCESS_DENIEDFAccess is denied.

Contact Alipay Technical Support for detailed reasons. 

INVALID_APIFThe called API is invalid or not active.

Contact Alipay Technical Support to resolve the issue.  

CLIENT_INVALIDFThe 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_DECLARATIONSFThe 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_CONTRACTFThe 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_SIGNATUREFThe 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:

KEY_NOT_FOUNDFThe 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_ACCEPTABLEFThe 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_REGISTEREDFThe 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_SUPPORTEDFThe server does not implement the requested HTTP method. Only the POST method is supported.

Ensure the HTTP method is POST. 

NO_INTERFACE_DEFFAPI is not defined.

Check whether the URL is correct. Please refer to the endpoint in the API documentation. 

ORDER_NOT_EXISTFThe order does not exist.

Check whether paymentId is correct. If correct, contact Alipay Technical Support for specific reasons. 

ORDER_STATUS_INVALIDFThe 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_ILLEGALFThe 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_FAILFA 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_INCONSISTENTFThe 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_REJECTFThe request is rejected because of the risk control.

Prompt the user that the request is rejected because the risk control failed.  

SYSTEM_ERRORFA system error occurred.

Do not retry, and contact Alipay Technical Support for more details. 

TOTAL_DECLARATION_AMOUNT_EXCEEDFThe 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_ABNORMALFThe user status is abnormal on the wallet side.

Contact Alipay Technical Support to know the specific reasons.

REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.

Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support. 

UNKNOWN_EXCEPTIONUAn 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.