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

      alipay.acquire.customs

      Call this interface to transmit information to customs.

      #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.acquire.customs

      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:2118ac8fad6bc1d9e88a6cd017c18d37

      Business parameter

      out_request_no

      String(32) Required

      The unique business number generated by the merchant to identify a declaration operation. The recommended generation rule: yyyymmdd type 8-bit date + 4-bit serial number. The length of this parameter ranges from 6 to 32 bits.

      Example:9193457120563834

      trade_no

      String(64) Required

      The transaction serial number of this transaction in the Alipay system

      Example:2015051446800462000100020003

      merchant_customs_code

      String(20) Required

      The merchant recordation number in the customs system

      Example:hanguo

      amount

      String(20) Required

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

      Note: The declaration amount added up by multiple transactions cannot exceed the total amount of transactions.

      Example:2

      customs_place

      String(20) Required

      The customs code, both upper and lower cases are supported.

      Example:HANGZHOU

      merchant_customs_name

      String(256) Required

      The merchant recordation name in the customs system

      Example:jwyhanguo_card

      is_split

      String(1)

      The merchant can decide whether the form is split for declaration. Only when the value of this field is T or t, the form splitting is triggered and customs declaration must support form splitting. If the value of this field is F or f, no form splitting is allowed. 

      Example:T

      sub_out_biz_no

      String(32)

      The merchant sub order number. The merchant must specify this field when the form is split, otherwise, an error code of INVALID_PARAMETER is returned. 

      Example:2015080811223212345453

      buyer_name

      String(10)

      Buyer's name in the merchant system

      Example:Andy

      buyer_id_no

      String(18)

      The buyer ID in the merchant system

      Example:330681199010104783

      #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

      trade_no

      String(64)

      The payment number pushed to customs by Alipay

      Example:2013111511001004390000105126

      alipay_declare_noString(64)

      The Alipay declaration serial number

      Example:2013112611001004680073956707

      detail_error_code

      String(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 Error Code section.

      Example:SAME_CUSTOMS_DECLARE_ONCE

      detail_error_des

      String(64)

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

      Example:The same transaction can only be declared once in the same customs

      identity_check

      String(1)

      This parameter is used to identify whether the payer and shopper is the same person. The value of this parameter can be T or F. Alipay verifies once for the same declaration. The parameter is not returned if multiple retransmissions occur.

      Example:T

      ver_dept

      String(1) Required

      The organization that verifies the transaction. The value can be one of the following items:

      1: Unionpay

      2: NetsUnion

      3: Others

      Example:3

      pay_code

      String(18) Required

      The Alipay registration ID in the customs system

      Example:31222699S7

      pay_transaction_id

      String(32) Required

      The unique ID assigned by Alipay to identify a transaction. The ID can be verified through the organization that is recognized by The People's Bank of China.

      Example:2017082300037460045411523

      total_amount

      String(17) Required

      The total amount

      #Samples

      #Request

      https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.customs&partner=208xxxxxxxxx6931&_input_charset=UTF-8&sign_type=MD5&out_request_no=out_request_no_20190904_172900&trade_no=201xxxxxxxxxxxxxxxxxxxx5788&merchant_customs_code=333xxx3222&amount=0.07&customs_place=ZONGSHU&merchant_customs_name=Mika's%20Corporation&is_split=T&sub_out_biz_no=000xxxxxxxxxxxxx8785&buyer_name=%E5%90%B4%E6%96%87%E6%B3%A2&buyer_id_no=340xxxxxxxxxxx3212&sign=5158c4d5ac3e948d431eede501a718cb


      #Response

      Synchronous response

      When the request is successful, and the business processing succeeds:

      copy
      <?xml version="1.0" encoding="utf-8"?>
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="merchant_customs_name">Mika's Corporation</param>
              <param name="amount">0.07</param>
              <param name="_input_charset">UTF-8</param>
              <param name="is_split">T</param>
              <param name="sub_out_biz_no">000xxxxxxxxxxxxx8785</param>
              <param name="sign">5158c4d5ac3e948d431eede501a718cb</param>
              <param name="buyer_name">Tom</param>
              <param name="partner">208xxxxxxxxx6931</param>
              <param name="service">alipay.acquire.customs</param>
              <param name="trade_no">201xxxxxxxxxxxxxxxxxxxxx5788</param>
              <param name="merchant_customs_code">333xxx3222</param>
              <param name="customs_place">ZONGSHU</param>
              <param name="buyer_id_no">340xxxxxxxxxxx3212</param>
              <param name="sign_type">MD5</param>
              <param name="out_request_no">out_request_no_20190904_172900</param>
          </request>
          <response>
              <alipay>
                  <alipay_declare_no>201xxxxxxxxxxxxxxxxxx8161</alipay_declare_no>
                  <currency>142</currency>
                  <identity_check>F</identity_check>
                  <out_request_no>out_request_no_20190904_172900</out_request_no>
                  <pay_code>31222699S7</pay_code>
                  <pay_transaction_id>201xxxxxxxxxxxxxxxxxxxxx5788</pay_transaction_id>
                  <result_code>SUCCESS</result_code>
                  <total_amount>0.07</total_amount>
                  <trade_no>201xxxxxxxxxxxxxxxxxx8161</trade_no>
                  <ver_dept>3</ver_dept>
              </alipay>
          </response>
          <sign>197847e2c638d99a6d85a960e7140e19</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="trade_no">201xxxxxxxxx0462</param>
              <param name="merchant_customs_code">hanguo</param>
              <param name="sign_type">MD5</param>
              <param name="merchant_customs_name">jwyhanguo_card</param>
              <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
              <param name="amount">2</param>
              <param name="_input_charset">UTF-8</param>
              <param name="customs_place">HANGZHOU</param>
              <param name="service">alipay.acquire.customs</param>
              <param name="out_request_no">919xxxxxxxxx3834</param>
              <param name="partner">208xxxxxxxxx8662</param>
          </request>
          <response>
              <alipay>
                 <detail_error_code>SAME_CUSTOMS_DECLARE_ONCE</detail_error_code>
                 <detail_error_des>The same transaction can only be declared once in the same customs</detail_error_des>
                 <result_code>FAIL</result_code>
              </alipay>
          </response>
          <sign>3afc92ac4708425ab74ecb2c4e58ef56</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>


      #Synchronous response feature

      1. After Alipay processes the merchant's request, the current Alipay gateway page refreshes automatically and returns the processing result immediately.
      2. For one request, Alipay returns the processing result only once.
      3. The synchronous reponse can be debugged on the local computer, instead on the server.
      4. The processing result is returned in the format of XML.
      5. The XML processing result can be remotely parsed to obtain the result data when Alipay processes the result. In the page with result data, the merchant performs the logical analysis based on the data.
      6. The configuration of the local computer or merchant server must support XML remote parse. For example, SSL is supported.
      7. After the Alipay gateway page refreshes, the link is only valid within one minute. If the link is invalid after one minute, the business logic program written by the merchant in the page cannot be processed.


      #Payment information retransmission

      The declaration interface can be re-triggered for sending payment data to customs, it is used when:

      1. The payment data are missing in the customs system.
      2. The previous declaration data contain wrong information.


      Retransmission conditions

      The following list describes the conditions before re-triggering the interface:

      • The declaration with the same out_request_no exists in Alipay system already.
      • Re-trigger must be more than 5 minutes since last call (Alipay might adjust this time value).
      • Keep all information the same except the values of the following fields:
        • merchant_customs_code
        • merchant_customs_name
        • customs_place
        • amount
        • sub_out_biz_no
      • The target customs supports retransmission.
        Customs NANSHAGJ does not support retransmission. If merchants want to modify the payment information which is already received by Customs NANSHAGJ, contact NANSHAGJ offline to do the modification. If merchants want to retransmit the payment information which is sent by Alipay but is not received by Customs NANSHAGJ, contact Alipay Global Merchant Technical Support (overseas_support@service.alibaba.com) to do manual retransmission.
      • If the amount is 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 no parameter value is changed, return idempotent success.
      • If retransmission conditions are not met but one or more parameter values are changed, return the error code CONTEXT_INCONSISTENT or other error codes.
      • If retransmission conditions are met and retransmission is successful, return value is the same as that returned during the first successful transmission.


      Note:

      Merchants can use the QUERY interface to query the retransmission status.


      #Unified customs solution

      According to the unified messages announced by General Administration of Customs since 2017, the information is only transmitted to General Administration of Customs or only to local customs. However, if the customs is in Tianjin city or Henan province, merchants transmit the payment information to both General Administration of Customs and the local customs. Merchants can check the transmission solutions in Customs code


      When is_split is not T or no value is passed into is_split:

      1. First transmit to the local customs, then use the new out_request_no to transmit to General Administration of Customs.
      2. To ensure that the information is matched, keep the fields of two transmissions the same except the following fields:
        • customs_place
        • merchant_customs_code
        • merchant_customs_name


      When is_split is T:

      1. First transmit to the local customs, then transmit the same out_request_no to General Administration of Customs.
      2. To ensure that the information is matched, keep the fields of two transmissions the same except the following fields:
        • customs_place
        • merchant_customs_code
        • merchant_customs_name


      Note:

      The declaration amount transmitted to General Administration of Customs and local Customs will not be added up.


      #Customs code

      Customs nameUnified customs solutionCustoms codeAlipay registration ID
      General Administration of CustomsTransmit to ZONGSHUZONGSHU

      31222699S7

      Henan bonded logistics centerTransmit to ZHENGZHOU

      ZHENGZHOU

      31222699S7

      Ningbo Customs

      Transmit to NINGBONINGBO

      31222699S7

      Xinzheng comprehensive bonded zone (Airport)First transmit to HENAN, then to ZONGSHU

      HENAN

      P460400005

      Tianjin Customs

      Transmit to ZONGSHU

      TIANJIN

      Q12150016000019

      Shanghai Customs

      Transmit to SHANGHAI_CBT

      SHANGHAI_CBT

      31222699S7

      Guangzhou Customs (Airport)

      Transmit to ZONGSHU

      GUANGZHOU_AIRPORT

      C000010000416158

      Guangzhou Customs (Nansha)

      Transmit to ZONGSHU

      GUANGZHOU_NANSHA

      C000010000416158

      Guangzhou Customs (Huangpu)

      Transmit to ZONGSHU

      GUANGZHOU_HUANGPU

      C000010000416158

      Guangzhou Customs (Shatian)

      Transmit to ZONGSHU

      GUANGZHOU_SHATIAN

      C000010000416158

      Hangzhou Customs

      Transmit to HANGZHOU_ZONGSHU

      HANGZHOU_ZONGSHU

      ZF14021901

      #Error code

      Error code

      Description

      Reason

      Solution

      TRADE_NOT_EXIST

      The transaction does not exist.

      The passed in value of trade_no is incorrect and not found.

      Confirm if the value of trade_no is correct.

      TRADE_STATUS_ERROR

      The transaction status is not supported for declaration.

      The transaction does not complete the payment successfully.

      Confirm the transaction status.

      INVALID_PARAMETER

      Incorrect parameter

      The value exceeds the length or the value is not passed in.

      Check the parameter format according to the API document.

      CONTEXT_INCONSISTENT

      The parameters of the same transaction are inconsistent.

      Send multiple requests for the same transaction and the parameters are inconsistent.

      Confirm if the parameters are correct.

      SAME_CUSTOMS_DECLARE_ONCE

      The same transaction can only be declared once at the same customs.

      The same transaction can only be declared once at the same customs.

      Confirm if the the transaction is already declared at the same customs.

      REQUEST_AMOUNT_EXCEED

      The amount exceeds the limit.

      The added up declaration amount exceeds the transaction amount.

      Confirm the accumulated declaration amount of the transaction.

      PARTNER_ERROR

      The partner IDs in the transaction and declaration are inconsistent.

      The partner IDs in the transaction and declaration are inconsistent.

      Confirm if the partner in the declaration is the same with the one in the transaction.

      PAYER_ENABLE_STATUS_FORBID

      Invalid status of the payerThe status of the payer in the declared transaction cannot pass the verification.

      Confirm the account status of the payer in Alipay.