# inquireDeclarationRequests `POST /aps/api/v1/customs/inquireDeclarationRequests` The **inquireDeclarationRequests** API is used by the Acquiring Service Provider (ACQP) to query the status of an payment order that is declared to the 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](api_overview#3mLq0) - [Response header](api_overview#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 #### declarationRequestIds (Array, REQUIRED) The unique declaration request IDs that are assigned by the merchant to identify declaration requests. Batch queries are supported, and up to 10 declaration request IDs are supported at a time. More information: - Maximum size: 10 elements ## 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 the result of the declaration request inquiry, but does not indicate the result of declarations or declaration requests. ##### 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 #### declarationRequestsNotFound (Array) The list of declaration request IDs that are not found in the customs system. **Note:** Returned by Alipay+ if _result_._resultCode_ is `S` and one or multiple declaration request IDs can't refer to any existing declarations. More information: - Maximum size: 10 elements #### declarationRecords (Array) The list of customs declaration records. Each record represents a customs declaration. **Note**: Returned by Alipay+ if _result_._resultCode_ is `S`. More information: - Maximum size: 10 elements ##### customsDeclarationRequestId (String, REQUIRED) The unique ID that is assigned by the merchant to identify a customs declaration request. More information: - Maximum length: 64 characters ##### pspDeclarationRequestId (String, REQUIRED) The declaration request ID that is assigned by the AlipayCN wallet. This ID is not provided for the customs. More information: - Maximum length: 64 characters ##### pspPaymentId (String, REQUIRED) The payment ID that is provided to the customs by the AlipayCN wallet. More information: - Maximum length: 64 characters ##### customs (CustomsInfo, REQUIRED) The customs information. ###### customsCode (String, REQUIRED) The customs code (in either uppercase or lowercase). See _Customs code_ in the [**declare**](declare) API 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 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 cannot exceed the value of _customsDeclarationAmount.value_ in the **inquiryPayment** and **notifyPayment** API. ###### 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 is split for declaration. Valid values are: - `true`: indicates that the payment order is split. - `false`: indicates that the payment order is not split. 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. **Note**: Returned by Alipay+ if _isSplit_ is `true`. More information: - Maximum length: 64 characters ##### declarationRequestStatus (String, REQUIRED) The status of the customs declaration. Valid values are: - `WAITING_FOR_PROCESSING`: indicates that the declaration is to be processed by the customs.  - `IN_PROCESS`: indicates that the declaration is being processed by the customs. - `CUSTOMS_ACCEPT_SUCCESS`: indicates that the declaration is received by the customs. ##### modifiedTime (Datetime, REQUIRED) The last modification time of the customs declaration status. 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". ##### customsResultCode (String) The declaration result that is returned in the customs receipt. Valid values are: - `2`: indicate that the declaration succeeds and this result is recorded in the payment information. - `120`: indicates that the order, the payment transaction and the logistics number are verified correctly by the customs. - Numbers less than 0: indicate that an error occurs. Check _customsResultDescription_ for more information. - `success`: indicates that the decalaration is sent to the customs successfully. **Notes：** - Returned by Alipay+ if _declarationRequestStatus_ is `CUSTOMS_ACCEPT_SUCCESS` and the customs receipt contains the result code. - The value of this parameter is subject to the customs definition. More information: - Maximum length: 64 characters ##### customsResultDescription (String) The description of the declaration result that is returned on the customs receipt. **Note:** Returned by Alipay+ if the customs receipt contains the result code and its description. More information: - Maximum length: 2048 characters ##### customsResultReturnedTime (Datetime) The date and time when the customs returns the receipt. **Note:** Returned by Alipay+ if the customs offers a receipt. 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". ## 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. | | COUNT_OF_REQUEST_EXCEED_LIMIT | F | For each inquiry, only up to 10 declaration request IDs can be used. | Ensure that the number of declaration request IDs in the request does not exceed 10. | | INVALID_CLIENT | F | The client is invalid. | It is recommended that you 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. | | 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. | | 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 ### ALIPAY, ALIPAY_HK, DANA, H5, DIRECT ```json { "declarationRequestIds": [ "2021081900000000000000001", "2021081900000000000000002" ] } ``` ## Response ```json { "result": { "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }, "declarationRequestsNotFound": [ "2021081900000000000000002" ], "declarationRecords": [ { "customsDeclarationRequestId": "2021081900000000000000001", "pspDeclarationRequestId": "2013112611001004680073950000", "pspPaymentId": "202108120000000231200000", "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", "declarationRequestStatus": "WAITING_FOR_PROCESSING", "modifiedTime": "2021-01-01T12:08:55Z", "customsResultCode": "2", "customsResultDescription": "success_201508201108237064750527108110000", "customsResultReturnedTime": "2021-01-01T12:08:55Z" } ] } ```