# declare > Use this API to transmit information to customs. `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：  - [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur) - [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90) > **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: - This field is an API idempotency field. - Maximum length: 32 characters #### paymentId (String, REQUIRED) The unique ID that is assigned by Antom to identify a payment. More information: - Maximum length: 64 characters #### declarationAmount (Amount, 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**](https://docs.antom.com/ac/ams/paymentrn_online.md) request and [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) response. ##### currency (String, REQUIRED) The 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. More information: - Maximum length: 3 characters ##### value (Integer, REQUIRED) The value of the amount as a positive integer in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to `100`; or if the currency is JPY and the amount is ￥1, set the value of this parameter to `1`.   For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe) . For details about the minimum payment amount allowed for each payment method, see [Minimum amount rules](https://docs.antom.com/ac/ref/cc.md#q9R5A). > Note: Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of this parameter as `00.` More information: - Value range: 0 - unlimited #### customs (CustomsInfo, REQUIRED) The customs information ##### customsCode (String, REQUIRED) The customs code. See the Customs Code section on this page for details. More information: - Maximum length: 28 characters ##### region (String, REQUIRED) The customs region, which follows the 2-character [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country/region code. > Note: Only the China customs region of `CN` is supported for now. More information: - Maximum length: 2 characters #### merchantCustomsInfo (MerchantCustomsInfo, REQUIRED) The merchant information that is registered in the customs system. ##### merchantCustomsCode (String, REQUIRED) The merchant recordation number in the customs system. More information: - Maximum length: 128 characters ##### merchantCustomsName (String, REQUIRED) The merchant recordation name in the customs system. More information: - Maximum length: 256 characters #### 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: - Maximum length: 64 characters #### buyerCertificate (Certificate) 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 Antom 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. ##### certificateType (String, REQUIRED) Identification type of the buyer. Valid values are: - `ID_CARD`: indicates that the identification type is an identification card. When _customs.region_ is CN, use this value. - `PASSPORT`: indicates that the identification type is a passport. ##### certificateNo (String, REQUIRED) Identification number of the buyer. More information: - Maximum length: 64 characters ##### holderName (UserName) The buyer name. > Note: Specify this field when _CertificateType_ is `ID_CARD`. ###### firstName (String) The buyer's first name. More information: - Maximum length: 32 characters ###### middleName (String) The buyer's middle name. More information: - Maximum length: 32 characters ###### lastName (String) The buyer's last name. More information: - Maximum length: 32 characters ###### fullName (String) The buyer's full name. > Note: Specify this field when _CertificateType_ is `ID_CARD`. Chinese buyers need to pay attention to the sequence of the full name. More information: - Maximum length: 128 characters ## Response parameters #### result (Result, 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**](https://docs.antom.com/ac/ams/declare.md) API is called successfully. ##### resultCode (String, REQUIRED) The result code. Possible values are listed in the Result/Error code table on this page. More information: - Maximum length: 64 characters ##### resultStatus (String, REQUIRED) The result status. Valid values are:  - `S`: Indicates that the result status is successful.  - `F`: Indicates that the result status failed.  - `U`: Indicates that the result status is unknown. ##### resultMessage (String, REQUIRED) The result message More information: - Maximum length: 256 characters #### 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: - 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: - 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: - 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: - Maximum length: 32 characters ## 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 Antom system. - More than 5 minutes have passed since the last call. (Antom might adjust this time value according to the actual situation.) - Keep all information the same except the values of the following fields: - _merchantCustomsCode_ - _merchantCustomsName_ - _customs__Code_  - _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 Antom Technical Support for detailed reasons. | | INVALID_API | F | The called API is invalid or not active. | Contact Antom Technical Support to resolve the issue. | | CLIENT_INVALID | F | The client ID is invalid. Antom has restrictions on the client ID. | Check whether the client ID is correct, or contact Antom 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 Antom 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 Antom 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 Antom. | | MERCHANT_NOT_REGISTERED | F | The merchant is not registered. | Please register the merchant by using the registration interface. Contact Antom 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 Antom 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 Antom 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 Antom 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 Antom 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 Antom Technical Support. | | USER_STATUS_ABNORMAL | F | The user status is abnormal on the wallet side. | Contact Antom Technical Support to know the specific reasons. | | REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the API again to resolve the issue. If not resolved, contact Antom Technical Support. | | UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | Call the API again to resolve the issue. If not resolved, contact Antom Technical Support. | ## Request ```json { "declarationAmount": { "currency": "CNY", "value": "100" }, "merchantCustomsInfo": { "merchantCustomsName": "amsdemo", "merchantCustomsCode": "amsdemoskr" }, "paymentId": "20211117194010800100188180203227785", "splitOrder": false, "customs": { "region": "CN", "customsCode": "ZONGSHU" }, "declarationRequestId": "req123", "buyerCertificate": { "holderName": { "firstName": "f", "lastName": "l", "fullName": "cangxi.lj", "middleName": "m" }, "certificateNo": "510502199504139527", "certificateType": "ID_CARD" } } ``` ## Response ### SUCCESS ```json { "result": { "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }, "customsPaymentId": "202103311108288854766XXXX", "customsOrderId": "202109612108270254713XXXX", "identityCheckResult": "CHECK_PASSED", "customsProviderRegistrationId": "ZF1402XXXX", "clearingChannel": "OTHER", "clearingTransactionId": "202103102200135488140026XXXX" } ``` ### DECLARE_REPEAT ```json { "result": { "resultCode": "DUPLICATED_DECLARATIONS", "resultMessage": "The same order can only be declared once at the same customs.", "resultStatus": "F" } } ```