Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewChoose your payments solutionGet started with payments
Online payments
Invoice integrations
Payment methods
Payment Methods OverviewGlobal
Alipay CN
Pay with QR Code (Desktop Website Browser) - Alipay CNMobile App - Alipay CNMobile Website Browser - Alipay CNMini Program - Alipay CNCustoms Declaration - Alipay CN
Alipay HK
DOKU Wallet
E.SUN (Taiwan ATM & Internet banking)
GrabPay - Malaysia
GrabPay - Singapore
Indonesian Bank Transfer
Indonesian Convenience Stores - BETA
Jenius Pay
Kakao Pay
Kiosk Payments
Korean Local Cards - BETA
Naver Pay - BETA
Payco - BETA
Philippines Online Banking
Rabbit LINE Pay
Samsung Pay - BETA
Taiwan Convenience Stores
Tesco Lotus
Thailand Online Banking
Toss Pay - BETA
Touch 'n Go
WeChat Pay
Zip - BETA

Customs Declaration - Alipay CN

The feature is under beta testing. If you are interested, please reach out to your Airwallex account manager or [email protected].

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.

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.

Pass in the shopper_details object if you want to verify the shopper identity you collected from the checkout page with the payer identity in the Alipay system. This could help you align the shopper identity with the payer identity during the order information declaration as required.

Please note that you need to provide your customs registration information to us offline in advance for configuration purposes.

POST /api/v1/pa/customs_declarations/create


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 UNDECLARED or 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.

UNDECLAREDAlipay has received the declaration, but it has not yet been sent to the customs.
PROCESSINGThe declaration is being processed by the customs.
SUCCEEDEDThe declaration is received by the customs.
FAILEDAn error occurs. See customs_status_message for details.

If the value of shopper_identity_check_result is DIFFERENT, you shall require the shopper to revise the shopper identity provided in the order to align with the payer identity they set in Alipay. After you get the new identity information, you shall call the Update a customs declaration API and update the identity information of the previous declaration.

POST /api/v1/pa/customs_declarations/{id}/update


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.

POST /api/v1/pa/customs_declarations/{id}/update


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. You can update the shopper_details object until it matches with the payer identity in the Alipay system (shopper_identity_check_result: SAME). Note, shopper_id and shopper_name cannot be updated after the declaration status turns to SUCCEEDED.


Retrieve a Customs Declaration

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

GET /api/v1/pa/customs_declarations/{id}


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


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.

POST /api/v1/pa/customs_declarations/{id}/redeclare


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


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 where you would receive an error response after a 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.

Customs codes

Customs DistrictCustoms CodeNotes
General Administration of Customs P.R. ChinaZONGSHUUse ZONGSHU to declare to the customs districts that are not included, for example, Hangzhou Customs District, Guangzhou Customs District, and Tianjin Customs District.
Henan Bonded Logistics CenterZHENGZHOU
Ningbo Customs District P.R. ChinaNINGBO
Shanghai CustomsSHANGHAI_CBTThe Update API is not available after the status turns to SUCCEEDED.