Airwallex logo

Customs Declaration

The Airwallex Customs Declaration functionality enables Merchants who sell goods to mainland China via bonded warehouses to send payment information to China Customs conveniently and safely as regulated.

Note

Currently, this service supports custom declarations for WeChat Pay transactions that are completed within a year.

To help you better understand what role Airwallex plays in your declaration process and what functionality our customs declaration API delivers, the Customs Declaration Model below illustrates the major parties in your overall declaration procedures. Illustration - Customs Declaration

  1. The customer completes the purchase.

  2. You, as the merchant, shall send custom details and receives payment data via Airwallex Customs Declaration API (see guideline below).

  3. Same as your common practices of completing declaration, it is your responsibility to inform the logistics to send shipment details for declaration, with payment data attached. Also, you need to send order details for declaration, with payment data attached.

  4. After the customs receives all the required information, they will cross-check the detailed information of the order sent by you, payment methods and logistics. If details matched, customs will agree the merchant to dispatch goods.

Guideline for using Customs Declaration APIs

The following guideline will walk you through the process of using Airwallex Customs Declaration service to Create, Update, Retrieve and Redeclare your order. You shall start with creating a customs declaration first and please refer to our API reference for the complete details of the calls.

Create a Customs Declaration

Create a Customs Declaration to send payment information to the customs. Your request should include the payment_intent_id to specify the payment you want to declare. You will also need to provide customs related information so that we can send the payment information to the right customs. In each request, sub_order fields are required, and if there is no need to split your original order, please fill the suborder fields with your original order information for declaration. Please note that you need to provide your customs registration information to us offline in advance for configuration purposes.

{
  "payment_indent_id": "int_kJclUUgEz2RJshlZBzF1U5pWnb4",
  "request_id": "a9bc0297-cdb4-40c5-8e03-034357020672",
  "customs_details": {
     "customs_code": "GUANGZHOU_ZS",
     "merchant_customs_number": "D00411",
     "merchant_customs_name": "1262544101",
 },
 "sub_order": {
     "order_number": "001",
     "currency": "CNY",
     "amount": 10.00,
     "shipping_fee": 1.00
 }
}

After you succeed to create a declaration, the response of the Customs Declaration is provided below and contains an id, it is the unique number generated by Airwallex for the declaration and you will need to use it to Retrieve, Update and Redeclare the declaration. We will also return provider_order_id to you, you need to use it as institution transaction id when sending shipment and order information to customs. It may take several minutes to complete the declaration process. It is possible for you to get PROCESSING status in the response. You are suggested to call the Retrieve a customs declaration API a few minutes later than your creation. The status will turn to “SUCCEEDED” once your declaration succeeds.

{
 "id": "cdc_dLocKBvfz6memtTw3zwS5OlZLOi",
"request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
 "status": "PROCESSING",
 "customs_status_message": "",
 "payment_method_type": "wallet_wechatpay",
 "provider_transaction_id": "1004400740201409030005092168",
 "awx_request_id": "2020090406422504920199020094",
 "verify_department_code": "UNIONPAY",
 "verify_department_transaction_id": "2018112288340107038204310100000",
  "customs_details": {
     "customs_code": "GUANGZHOU_ZS",
     "merchant_customs_number": "D00411",
     "merchant_customs_name": "1262544101",
 },
 "sub_order": {
     "order_number": "001",
     "provider_order_id": "3423547140201409030005097697",
     "currency": "CNY",
     "amount": 10.00,
          "shipping_fee": 1.00
 "created_at": "2019-08-24T14:15:22Z",
 "updated_at": "2019-08-24T14:15:22Z",
 }
}

Also, you shall request the Create API to create a Customs Declaration again, under the case that your request has failed. You will get another id for this successful declaration request.

Update a Customs Declaration

Update the existing Customs Declaration to align with your actual declaration demand. Use the Update API when you need to update the fee, customs, merchant_customs_no from your previous declaration. Note that the declaration under PROCESSING status can not be updated.

{
  "id": "cdc_dLocKBvfz6memtTw3zwS5OlZLOi"
  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
  "sub_order_amount": 10
  "customs_code": "GUANGZHOU_ZS",
  "merchant_customs_name": "jwyhanguo_card",
  "merchant_customs_number": "73625441897",
}

For your convenience, we developed a unified format for the response in our Customs Declaration API. You will obtain a response the same format as the Create API one.

{
 "id": "cdc_dLocKBvfz6memtTw3zwS5OlZLOi",
"request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
 "status": "PROCESSING",
 "customs_status_message": "",
 "payment_method_type": "wallet_wechatpay",
 "provider_transaction_id": "1004400740201409030005092168",
 "awx_request_id": "2020090406422504920199020094",
 "verify_department_code": "UNIONPAY",
 "verify_department_transaction_id": "2018112288340107038204310100000",
  "customs_details": {
     "customs_code": "GUANGZHOU_ZS",
     "merchant_customs_number": "73625441897",
     "merchant_customs_name": "jwyhanguo_card",
 },
 "sub_order": {
     "order_number": "001",
      "provider_order_id": "3423547140201409030005097697",
     "currency": "CNY",
     "amount": 10.00,
     "shipping_fee": 1.00
 "created_at": "2019-08-24T14:15:22Z",
 "updated_at": "2019-08-24T14:15:22Z",
 }
}

Retrieve a Customs Declaration

Retrieve a customs declaration to obtain the updated status of the declaration earlier submitted.

{
  "id": "cdc_dLocKBvfz6memtTw3zwS5OlZLOi"
}

You will get a response with the latest update on the declaration status.

{
 "id": "cdc_dLocKBvfz6memtTw3zwS5OlZLOi",
"request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
 "status": "SUCCEEDED",
 "customs_status_message": "",
 "payment_method_type": "wallet_wechatpay",
 "provider_transaction_id": "1004400740201409030005092168",
 "awx_request_id": "2020090406422504920199020094",
 "verify_department_code": "UNIONPAY",
 "verify_department_transaction_id": "2018112288340107038204310100000",
  "customs_details": {
     "customs_code": "GUANGZHOU_ZS",
     "merchant_customs_number": "D00411",
     "merchant_customs_name": "1262544101",
 },
 "sub_order": {
     "order_number": "001",
      "provider_order_id": "3423547140201409030005097697",
     "currency": "CNY",
     "amount": 10.00,
     "shipping_fee": 1.00
 "created_at": "2019-08-24T14:15:22Z",
 "updated_at": "2019-08-24T14:15:22Z",
 }
}

Redeclare a Customs Declaration

Redeclare the Customs Declaration which failed during the customs’ verification process . In some instances the information you provide and the information received by the customs may differ. If you receive “payment information does not exist” response when inquiring customs for customs declaration result. In this case, leverage the Redeclare API to send the original payment information again to the customs. Note that you will not get a new id by requesting the Redeclare API.

{
  "id": "cdc_dLocKBvfz6memtTw3zwS5OlZLOi"
}

You will get a response with the same format as above responses.

{
 "id": "cdc_dLocKBvfz6memtTw3zwS5OlZLOi",
"request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
 "status": "PROCESSING",
 "customs_status_message": "",
 "payment_method_type": "wallet_wechatpay",
 "provider_transaction_id": "1004400740201409030005092168",
 "awx_request_id": "2020090406422504920199020094",
 "verify_department_code": "UNIONPAY",
 "verify_department_transaction_id": "2018112288340107038204310100000",
  "customs_details": {
     "customs_code": "GUANGZHOU_ZS",
     "merchant_customs_number": "73625441897",
     "merchant_customs_name": "jwyhanguo_card",
 },
 "sub_order": {
     "order_number": "001",
      "provider_order_id": "3423547140201409030005097697",
     "currency": "CNY",
     "amount": 10.00,
     "shipping_fee": 1.00
 "created_at": "2019-08-24T14:15:22Z",
 "updated_at": "2019-08-24T14:15:22Z",
 }
}

Error handling

After requesting the Customs Declaration APIs, you may be returned with errors and their descriptions correspondingly.

  • If errors are returned after requesting the Create API, it actually means you did not create the declaration successfully. In this case, you shall refer to the error code section in the API doc to correct your declaration fields and request the Create API again to finish creating the declaration successfully. This is the most common case you would receive error response after request.
  • If errors are returned after requesting the Update, Retrieve and Redeclare API, it also means your previous request is considered as failed. You shall correct your declaration and call the corresponding API again to complete your request.
Note

This feature is still under testing. If you are interested in this functionality, you are more than welcomed to contact us for further information.

Customs codes

WeChat

Customs NameCustoms Name (CN)Customs CodeNotes
Guangzhou (General Administration)广州(总署版)GUANGZHOU_ZS
Guangzhou HuangPu CIQ广州黄埔国检GUANGZHOU_HP_GJOrders that are required to be pushed to Huangpu CIQ shall be separately pushed to Guangzhou (General Administration) and Guangzhou Huangpu CIQ, i.e. the Create a customs declaration API shall be requested twice.
Guangzhou Nansha CIQ广州南沙国检GUANGZHOU_NS_GJOrders that are required to be pushed to Nansha CIQ shall be separately pushed to Guangzhou (General Administration) and Guangzhou Nansha CIQ, i.e. the Create a customs declaration API shall be requested twice.
Hangzhou (General Administration)杭州(总署版)HANGZHOU_ZS
Ningbo宁波NINGBO
Zhengzhou (Bonded Logistics Center)郑州(保税物流中心)ZHENGZHOU_BS
Chongqing重庆CHONGQING
Shanghai (General Administration)上海(总署版)SHANGHAI_ZS
Shenzhen深圳SHENZHEN
Zhengzhou Integrated Bonded Area (General Administration)郑州综保(总署版)ZHENGZHOU_ZH_ZS
Tianjin天津TIANJINTo push your order to Tianjin Customs, you need to provide both Tianjin Customs and TJCIQ registration information to us. You only need to call the Create a customs declaration API once.