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

      alipay.overseas.acquire.customs.query

      Call this interface to query the custom declaration status.

      #Request

      #Service address

      Environment

      HTTPS request URL

      Production environment

      https://intlmapi.alipay.com/gateway.do

      Test environment

      https://mapi.alipaydev.com/gateway.do

      #Request parameters

      ParameterDescription
      Basic parameter

      service

      String Required

      Interface name

      Example:alipay.overseas.acquire.customs.query

      partner

      String(16) Required

      The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088.

      Example:2088*********662

      _input_charset

      String Required

      The charset with which the request data are encoded. UTF-8 is supported.

      Example:UTF-8

      sign_type

      String Required

      Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

      Example:MD5

      sign

      String Required

      Sign value

      Example:b7baf9af3c91b37bef4261849aa76281

      Business parameter

      out_request_nos

      String(329) Required

      The merchant-side declaration request number to be requested, supports batch queries, multiple values are separated by English commas, and there are up to 10 declaration request numbers in one time. The length of each declaration request number ranges from 6 to 32 bits, without spaces before or after, and only the following types of characters are allowed to be passed: numbers, English letters, "_", "-", ":"

      Example:201506010001,201506010002,201506010003

      #Response

      #Synchronous response

      ParameterDescription
      Basic parameter

      is_success

      String Required

      Indicates whether the request succeeds or not, with a value of T for success and F for failure.

      Note: a successful request does not mean the business is accepted and processed successfully.

      Example:T

      sign_type

      String

      Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

      Example:MD5

      sign

      String

      Sign value

      Example:3afc92ac4708425ab74ecb2c4e58ef56

      error

      String

      Error code that is returned when the request is failed, to describe the request failure reason. For more information, see the Error Code section in this document.

      Example:ILLEGAL_SIGN

      Business parameter

      result_code

      String(32) Required

      Processing result of the request, with a value of SUCCESS to indicate the process is successful, or FAIL to indicate the process is failed.

      Example:SUCCESS

      not_found

      String

      This field is returned when the business is processed successfully (result_code=SUCCESS), but unfound declaration request numbers exist. If multiple values are returned, they are separated by English commas.

      Example:201506010001

      detail_error_codeString(48)

      Detailed error code, which describes the reason for not receiving a result_code of SUCCESS. If the response code of result_code is SUCCESS, this parameter is not returned. For more information about the value of detail_error_code, see the Business Error Code section.

      Example:INVALID_PARAMETER

      detail_error_des

      String(64) Required

      Explanation of the detailed error code. If result_code is SUCCESS, this parameter is not returned. 

      Example:Declaration Form Parameters Illegal

      <customs_declare>Multiple declaration form information and xml nodes might exist.

      out_request_no

      String(32)

      The merchant-side declaration request number, corresponding to a certain declaration request number in the parameters

      Example:4877067126133624

      alipay_declare_noString(64)

      The Alipay declaration serial number

      Example:2015082011082370647505271

      trade_no

      String(64)

      The payments document number pushed to customs by Alipay. For the split declaration request, this document number is not equal to the original transaction number of Alipay.

      Example:2015082011082370647505271

      customs_place

      String(20)

      The customs number

      Example:hangzhou

      merchant_customs_code

      String(20)

      The merchant customs recordation number. 

      Example:code

      merchant_customs_name

      String(256)

      The merchant customs recordation name.

      Example:1

      amount

      String(20)

      The declaration amount in CNY, with the unit of Yuan and up to two digits after the decimal point.

      Example:1.00

      is_split

      String(1)

      T: Form-splitting

      F: Non form-splitting

      Example:T

      sub_out_biz_no

      String(32)

      The merchant sub order number. The merchant must specify this field when the form is split.

      Example:999999999999999

      status

      String(10)

      The current status of this declaration form. The value can be one of the following items:

      • ws: Wait to be sent to the customs
      • sending: Submitted to send to the customs
      • succ: Customs returned acceptance successfully.

      Example:succ

      memo

      String(256)

      Transaction notes

      Example:The customs returned parameters is illegal

      last_modified_time

      String(20)

      The last update time of status

      Example:10/15/2015 2:24:56 PM

      customs_code

      String

      After the declaration is launched, the result code in the customs returned receipt. The value can be one of the following items:

      • 2: Adding the payments document declaration successful
      • 120: The order, the payment transaction and the logistics number are verified correctly by the customs.
      • Numbers less than 0: The exception handling receipts
      • success: Sending to customs successful

      Note: Alipay returns the data as returned by the customs, and the parameter values are subject to the customs definition.

      Example:2

      customs_info

      String

      After the declaration is launched, the result description in the customs returned receipt.

      Example:Adding Declaration Successful [B0B2F23E-2CF6-434D-9F24-8931B835A056]

      customs_return_time

      String

      After the declaration is launched, the receipt time returned by customs, with a format of yyyyMMddHHmmss.

      Example:20160414142358

      #Error codes

      Error codeDescription
      INVALID_PARAMETERThe parameter format is illegal, due to one of the following reasons:  more than 350 characters, empty, a form number is empty, or a form number is more than 32 characters.
      MAX_OUT_REQUEST_NO_EXCEEDEDThe number of declaration forms in a single request is more than 10.

      #Samples

      #Request

      https://intlmapi.alipay.com/gateway.do?service=alipay.overseas.acquire.customs.query&partner=208xxxxxxxxx6931&_input_charset=UTF-8&sign_type=MD5&out_request_nos=out_request_no_20190904_172900&sign=3f8cda0bddaf9b79d58cb1f0149affc9


      #Response

      Synchronous response

      A successful query return:

      copy
      <?xml version="1.0" encoding="utf-8"?>
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="sign">eb9ece9d658e7a9671411d1b43b5750c</param>
              <param name="_input_charset">UTF-8</param>
              <param name="sign_type">MD5</param>
              <param name="service">alipay.overseas.acquire.customs.query</param>
              <param name="out_request_nos">487xxxxxxxxx3624,766xxxxxxxxx9532</param>
              <param name="partner">208xxxxxxxxx6350</param>
          </request>
          <response>
              <alipay>
                  <records>
                      <customs_declare>
                          <alipay_declare_no>201xxxxxxxxxxxxxxxxxxx5271</alipay_declare_no>
                          <amount>1.00</amount>
                          <is_split>T</is_split>
                          <sub_out_biz_no>999xxxxxxxx9999</sub_out_biz_no>
                          <customs_place>hangzhou</customs_place>
                          <last_modified_time>2015-10-15 14:24:56</last_modified_time>
                          <memo/>
                          <merchant_customs_code>code</merchant_customs_code>
                          <merchant_customs_name>1</merchant_customs_name>
                          <out_request_no>487xxxxxxxxx3624</out_request_no>
                          <status>succ</status>
                          <trade_no>201xxxxxxxxxxxxxxxxxx5271</trade_no>
                          <customs_code>2</customs_code>
                          <customs_info> Adding Declaration Successful [B0B2F23E-2CF6-434D-9F24-8931B835A056]</customs_info>
                          <customs_return_time>201xxxxxxx2358</customs_return_time>
                      </customs_declare>
                      <customs_declare>
                          <alipay_declare_no>201xxxxxxxxxxxxxxxxxx6255</alipay_declare_no>
                          <amount>1.00</amount>
                          <customs_place>henan</customs_place>
                          <last_modified_time>2015-10-15 14:24:56</last_modified_time>
                          <memo/>
                          <merchant_customs_code>code</merchant_customs_code>
                          <merchant_customs_name>name</merchant_customs_name>
                          <out_request_no>766xxxxxxxxx9532</out_request_no>
                          <status>succ</status>
                          <trade_no>201xxxxxxxxx0237</trade_no>
                          <customs_code>2</customs_code>
                          <customs_info> Adding Declaration Successful [B0B2F23E-2CF6-434D-9F24-8931B835A056]</customs_info>
                          <customs_return_time>201xxxxxxx2358</customs_return_time>
                      </customs_declare>
                  </records>
                  <result_code>SUCCESS</result_code>
              </alipay>
          </response>
          <sign>15669c65f3d19d0691425bba349a8b55</sign>
          <sign_type>MD5</sign_type>
      </alipay>


      When the request is successful, but the business processing fails:

      copy
      <?xml version="1.0" encoding="utf-8"?>
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="sign">48201072f0d0991c3bab798d963c6cd8</param>
              <param name="_input_charset">UTF-8</param>
              <param name="sign_type">MD5</param>
              <param name="service">alipay.overseas.acquire.customs.query</param>
              <param name="out_request_nos">487xxxxxxxxx3624,766xxxxxxxxx9532,,</param>
              <param name="partner">208xxxxxxxxx6350</param>
          </request>
          <response>
              <alipay>
                  <detail_error_code>INVALID_PARAMETER</detail_error_code>
                  <detail_error_des> Declaration Form Parameters Illegal </detail_error_des>
                  <result_code>FAIL</result_code>
              </alipay>
          </response>
          <sign>48fd2067e7fa2a7e779465d9e80dced5</sign>
          <sign_type>MD5</sign_type>
      </alipay>


      When the request is failed or the accessed data are incorrect:

      copy
      <?xml version="1.0" encoding="utf-8"?>
      <alipay>
          <is_success>F</is_success>
          <error>ILLEGAL_SIGN</error>
      </alipay>