# declare `POST /aps/api/v1/customs/declare` The declare API is used by the Acquiring Service Provider (ACQP) to send a customs declaration request to Alipay+. Currently, only for payments that are processed by the AlipayCN wallet, declarations are required. **Note:** In the following sections, Mobile Payment Provider (MPP) is also known as Payment Service Provider. For example, the pspId parameter specifies the ID that identifies an MPP.  ## 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](api_overview.md#3mLq0) - [Response header](api_overview.md#YdmVS) **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 #### paymentRequestId (String, REQUIRED) The unique ID that is assigned by the ACQP to identify a payment request for the order. The value of this parameter is the same as _paymentRequestId_ that is specified in the **pay** API.  This paramter is used as the order ID for declaration only if the value of _isSplit_ is `false`. More information: - Maximum length: 64 characters #### customsDeclarationRequestId (String, REQUIRED) The unique ID that is assigned by the merchant to identify a customs declaration request. This parameter is not provided for the customs. More information: - This field is an API idempotency field. - Maximum length: 64 characters #### customs (CustomsInfo, REQUIRED) The customs information, including customs code and region. ##### customsCode (String, REQUIRED) The customs code (in either uppercase or lowercase). See _Customs code_ for details. More information: - Maximum length: 128 characters ##### region (String, REQUIRED) The customs region in a two-character ISO 3166 country/region code. The value of this parameter must be `CN`. More information: - Maximum length: 2 characters #### merchantCustomsInfo (MerchantCustomsInfo, REQUIRED) The merchant information that is registered in the customs system. ##### merchantCustomsCode (String, REQUIRED) The merchant code that is registered in the customs system. More information: - Maximum length: 128 characters ##### merchantCustomsName (String, REQUIRED) The merchant name that is registered in the customs system. More information: - Maximum length: 256 characters #### declarationAmount (Amount, REQUIRED) The customs declaration amount. **Note:** When specifying the child parameters: - _declarationAmount.currency_: the value of this parameter needs to be fixed as `CNY`. - _declarationAmount.value_: the value of this parameter and the accumulated declaration amount for the same _paymentRequestId_ cannot exceed the original payment amount, namely the value of _customsDeclarationAmount.value_ in the **inquiryPayment** and **notifyPayment** APIs. ##### currency (String, REQUIRED) The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros. More information: - Maximum length: 3 characters ##### value (Integer, REQUIRED) The value of the amount as a natural number. By default, the value of this parameter is 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. More information: - Value range: 1 - unlimited #### isSplit (Boolean, REQUIRED) This parameter indicates whether the payment order needs to be split for declaration. Valid values are: - `true`: indicates that order splitting is needed. - `false`: indicates that order splitting is not needed. **Note:** The value of this parameter affects the value of order ID for declaration.  - If _isSplit_ is `true`, the order ID for declaration is the value of _referenceOrderId_. - If _isSplit_ is `false`, the order ID for declaration is the value of _paymentRequestId_. More information: - Maximum length: 1 character #### referenceOrderId (String, REQUIRED) The unique ID that is assigned by the merchant to identify an order that needs to be declared to the customs. This paramter is used as the order ID for declaration only if _isSplit_ is `true`. **Note:** Required if _isSplit_ is `true`. More information: - Maximum length: 64 characters #### buyerCertificate (Certificate) The buyer's identity information, including name, certificate type, and certificate number. **Note:** Specify this parameter if the merchant wants to ensure that the buyer's identity is consistent with the payer's identity. If so, Alipay+ returns the identity result, which can help improve the customs declaration success rate. ##### certificateType (String, REQUIRED) The identification type. Valid values are: - `ID_CARD`: indicates that the identification type is an ID card. ##### certificateNo (String, REQUIRED) The identification number. More information: - Maximum length: 64 characters ##### holderName (UserName) The identification holder's name, i.e. the buyer's name. ###### firstName (String) The first name of the user. **Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates. More information: - Maximum length: 32 characters ###### middleName (String) The middle name of the user. **Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates. More information: - Maximum length: 32 characters ###### lastName (String) The last name of the user. **Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates. More information: - Maximum length: 32 characters ###### fullName (String, REQUIRED) The full name of the user. More information: - Maximum length: 128 characters ##### effectiveDate (Datetime) The date and time when the ID card takes into effect. **Note**: Specify this parameter if you have the information. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". ##### expireDate (Datetime) The date and time when the ID card expires. **Note**: Specify this parameter if you have the information. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". ## Response parameters #### result (Result, REQUIRED) The result of the business processing, including the result status, result code, and the result message. **Note:** This parameter only indicates whether the request is accepted by Alipay+, but not indicates whether the declaration is approved by the customs or not. For the declaration result, see the _declarationRequestStatus_ parameter in the **inquireDeclarationRequests** API. ##### resultCode (String, REQUIRED) The result code that indicates the detailed processing result. More information: - Maximum length: 64 characters ##### resultStatus (String, REQUIRED) The result status that indicates the processing result. Valid values are: - `S`: Successful - `F`: Failed - `U`: Unknown ##### resultMessage (String) The result message that describes the result code in detail. More information: - Maximum length: 256 characters #### pspPaymentId (String) The payment ID that is provided for the customs by the AlipayCN wallet. More information: - Maximum length: 64 characters #### pspDeclarationRequestId (String) The declaration request ID that is assigned by the AlipayCN wallet. This ID is not provided for the customs. **Note**: Returned by Alipay+ if _result_._resultStatus_ is `S`. More information: - Maximum length: 64 characters #### pspCustomsCode (String) The AlipayCN wallet's registration ID in the customs system. **Note:** Returned by Alipay+ if _result_._resultStatus_ is `S`. More information: - Maximum length: 32 characters #### clearingChannel (String) The clearing channel of the merchant. Valid values are: - `CUP`: indicates that the clearing channel is Unionpay. - `NUCC`: indicates that the clearing channel is NetsUnion. - `OTHER`: indicates that the clearing channel is others. **Note**: Returned by Alipay+ if _result_._resultStatus_ is `S`. #### clearingTransactionId (String) The clearing organization's clearing serial number, which be verified by organizations trusted by the People's Bank of China. **Note**: Returned by Alipay+ if _result_._resultStatus_ is `S`. More information: - Maximum length: 64 characters #### pspOrderAmount (Amount) The transaction amount that was paid with the AlipayCN wallet. **Note:** Returned by Alipay+ if _result_._resultStatus_ is `S`. ##### currency (String, REQUIRED) The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros. More information: - Maximum length: 3 characters ##### value (Integer, REQUIRED) The value of the amount as a natural number. By default, the value of this parameter is 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. More information: - Value range: 1 - unlimited #### identityCheckResult (String) The verification result that indicates whether the buyer's identity is consistent with the payer's identity. Valid values are: - `CHECK_PASSED`: indicates that the buyer's name and ID card number are the same as the payer's. - `CHECK_NOT_PASSED`: indicates that the buyer's name and ID card number are not the same as that of the payer's. **Note**: Returned by Alipay+ if - _resultStatus_ is `S`, and - _buyerCertificate_ is specified by the ACQP/merchant. ## More information ### Payment information retransmission Currently, the digital wallet that requires customs declaration is only AlipayCN, and for payments made with AlipayCN, you can change the information of a declared payment and submit it again by using the **declare** API. The retransmission function can be used if: - the payment data is missing in the customs system; or - the previous declaration data contains the wrong information, including but not limited to the values of _merchantCustomsInfo.merchantCustomsCode_, _merchantCustomsInfo.merchantCustomsName_ and _customsInfo.customsCode_. The _declarationAmount_ in the retransmitted request is not stacked in the total amount of the customs declaration, but replaces the previous amount. #### Retransmission conditions All declarations can be retried. Before retransmitting the request, make sure that the following conditions are met: - The declaration with the same _customsDeclarationRequestId_ exists in the Alipay+ system. - More than 5 minutes have passed since the last API call. (Alipay+ might adjust this time value according to the actual situation.) - All information must be the same as that of the original request, except the values of the following paramerters: - _merchantCustomsCode_ - _merchantCustomsName_ - _customs__Code_ - _declarationAmount_ - If _declarationAmount_ has changed, the new accumulated 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 is changed, Alipay+ returns idempotent success. - If retransmission conditions are not met but one or more parameter values are changed, Alipay+ returns `REPEAT_REQ_INCONSISTENT` or other error codes. - If retransmission conditions are met and retransmission is successful, the response is the same as what was returned for the first successful transmission. ### Customs code

Customs District

Unified Customs Solution

Customs Code

AlipayCN Registration ID

General Administration of Customs P.R. China

Transmit to ZONGSHU

ZONGSHU

31222699S7

Henan Bonded Logistics Center

Transmit to ZHENGZHOU

ZHENGZHOU

31222699S7

Ningbo Customs District P.R. China

Transmit to NINGBO

NINGBO

31222699S7

Shanghai Customs

Transmit to SHANGHAI\_CBT

SHANGHAI\_CBT

31222699S7

**Note:** Use `ZONGSHU` to declare to the customs districts that are not included in the table above, for example, Hangzhou Customs District, Guangzhou Customs District, and Tianjin Customs District. ## Result/Error codes | Code | Value | Message | Further action | | --- | --- | --- | --- | | SUCCESS | S | Success | N/A | | ACCESS_DENIED | F | Access is denied. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | DECLARED_AMOUNT_EXCEED_LIMIT | F | The accumulated declared amount exceeds the total transaction amount. | Ensure that the accumulated declared amount is not greater than the total transaction amount at the digital wallet side. | | DUPLICATED_DECLARATION | F | An order can only be declared once at the same customs. | Check if the order is declared by a previous request. | | INVALID_CLIENT | F | The client is invalid. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | INVALID_ORDER_STATUS | F | The order status is invalid for this operation. | Check the payment order status. If the order status is normal, contact connect_support@service.alipay.com to troubleshoot the issue. | | INVALID_SIGNATURE | F | The signature is invalid. | Check whether the public key, signed message, and signature algorithm are as expected. | | KEY_NOT_FOUND | F | The key is not found. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. | Use a media type that is accepted by Alipay+. | | METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTPS method. | Ensure the HTTP method is POST. | | NO_INTERFACE_DEF | F | API is not defined. | Check whether the request URL is correct. Ensure that the endpoint of the called API is correct. | | ORDER_NOT_EXIST | F | The order doesn't exist. | Ensure that the value of paymentRequestId is correct. | | PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. | Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of each API, see the Structure section of the specific API reference topic. | | PROCESS_FAIL | F | A general business failure occurred. Do not retry. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | Ensure the parameters in the repeated requests have the same values. | | USER_STATUS_ABNORMAL | F | The user status is abnormal. | Contact connect_support@service.alipay.com for help. | | REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Reduce the frequency of API calls. | | UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. | Try to recall the API. | ## Request ```json { "paymentRequestId": "2021081200000002312800000", "customsDeclarationRequestId": "20210812000000045800000", "customs": { "customsCode": "HANGZHOU", "region": "CN" }, "merchantCustomsInfo": { "merchantCustomsCode": "test_merchant_customs_code", "merchantCustomsName": "test_merchant_customs_name" }, "declarationAmount": { "currency": "CNY", "value": "100" }, "isSplit": "true", "referenceOrderId": "P202108120000000231280000", "buyerCertificate": { "certificateType": "ID_CARD", "certificateNo": "230227198707200000", "holderName": { "fullName": "张三" } } } ``` ## Response ```json { "result": { "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }, "pspPaymentId": "202108120000000231200000", "pspDeclarationRequestId": "2013112611001004680073950000", "pspCustomsCode": "31222699S7", "clearingTransactionId": "202108120000000808000000", "clearingChannel": "CUP", "pspOrderAmount": { "currency": "CNY", "value": "100" }, "identityCheckResult": "CHECK_NOT_PASSED" } ```