Customs Declarations

The Customs Declaration API help merchants to complete customs clearance process as regulation required. This API applies only to China customs requirements and workflows.

Endpoints

POST /api/v1/pa/customs_declarations/create
GET /api/v1/pa/customs_declarations/{id}
POST /api/v1/pa/customs_declarations/{id}/update
POST /api/v1/pa/customs_declarations/{id}/redeclare

Create a Customs Declaration

POST /api/v1/pa/customs_declarations/create

Copy for LLMView as Markdown

Start the declaration process by creating a customs declaration. Please note that sub_order fields are required. If there is no need to split your original order, please fill the sub_order fields with your original order information for declaration. In this case, remember to use the provider_order_id in the response for your order information/shipment information declaration.

Request body

customs_detailsrequiredobject

Customs details.

customs_details.customs_coderequiredstring

China customs code, please refer to here for information https://www.airwallex.com/docs/payments/apac/wechat-pay/customs-declaration,https://www.airwallex.com/docs/payments/apac/alipay/customs-declaration.

customs_details.merchant_customs_namerequiredstring

Merchant's registered name in customs system. Maximum length is 256.

customs_details.merchant_customs_numberrequiredstring

Merchant's registered number in customs system. Maximum length is 32.

payment_intent_idrequiredstring

Unique identifier of the payment intent on which customs declaration will be created.

request_idrequiredstring

Unique request identifier specified by the merchant. Maximum length is 64.

shopper_detailsobject

Shopper details. Will be used for shopper identity check.

shopper_details.shopper_idrequiredstring

Mainland China unique identifier of the shopper.

shopper_details.shopper_namerequiredstring

Name of the shopper in simplified Chinese.

sub_orderobject

Suborder info, required when there are split orders.

sub_order.amountrequirednumber

The total amount of your sub_order, shipping fee shall be included, unit is Yuan. Please refer to supported currencies for supported minor units.

sub_order.currencyrequiredstring

Currency for the suborder, only CNY supported now.

sub_order.order_numberrequiredstring

Suborder number in merchant system. Maximum length is 128.

sub_order.shipping_feerequirednumber

Suborder transport fee, unit is Yuan.

sub_order.provider_order_idstring

The unique transaction identifier assigned by the provider for your sub_order. Please use this field as the provider transaction no. for your order information/shipment information’s declaration. Example of our providers: Cards, WeChat, Alipay etc.

Response body - 201 Created

awx_request_idstring

Request unique identifier generated by Air Wallex send to the provider for a Payment Attempt

created_atstring

Time at which the Customs Declaration was created

customs_detailsobject

Customs details

customs_details.customs_codestring

customs_details.merchant_customs_namestring

Merchant's registered name in customs system. Maximum length is 256.

customs_details.merchant_customs_numberstring

Merchant's registered number in customs system. Maximum length is 32.

customs_status_messagestring

Additional status message from customs

idstring

Unique identifier for the Customs Declaration

payment_method_typestring

Payment method type of the Payment Attempt

provider_transaction_idstring

The unique transaction identifier assigned by the provider for a payment attempt. Example of our providers: Cards, WeChat, Alipay etc.

request_idstring

Unique request identifier specified by the merchant in the last operation

shopper_identity_check_resultstring

Identity check result of the shopper.

statusstring

Customs processing status, UNDECLARED/PROCESSING/SUCCESS/FAIL

sub_orderobject

Suborder info, required for each customs declaration.

sub_order.amountnumber

The total amount of your sub_order, shipping fee shall be included, unit is Yuan. Please refer to supported currencies for supported minor units.

sub_order.currencystring

Currency for the suborder, only CNY supported now.

sub_order.order_numberstring

Suborder number in merchant system. Maximum length is 128.

sub_order.shipping_feenumber

Suborder transport fee, unit is Yuan

sub_order.provider_order_idstring

updated_atstring

Last time at which the Customs Declaration was updated or operated on

verification_department_codestring

Verification department code

verification_department_transaction_idstring

Transaction unique identifier returned by verification department

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `duplicate_request`, `resource_already_exists`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url)
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/pa/customs_declarations/create

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/pa/customs_declarations/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "request_id": "ac88c53b-f1bd-479b-a1b8-2686db548b39",
>  "payment_intent_id": "int_hkpdskz7vg1xc7uscdj",
>  "customs_details": {
>    "customs_code": "GUANGZHOU_ZS",
>    "merchant_customs_name": "Airwallex",
>    "merchant_customs_number": "C129000000"
>  },
>  "sub_order": {
>    "amount": 10,
>    "currency": "USD",
>    "order_number": "o100001213",
>    "provider_order_id": "T912345678901234569",
>    "shipping_fee": 0
>  }
>}'

Response (201 Created)

1{
2  "id": "cdc_hkpdkjd4t98sa",
3  "request_id": "ac88c53b-f1bd-479b-a1b8-2686db548b39",
4  "status": "UNDECLARED",
5  "payment_method_type": "card",
6  "provider_transaction_id": "t202401091234567890123456789",
7  "awx_request_id": "1234567890123456789",
8  "verification_department_code": "OTHERS",
9  "verification_department_transaction_id": "tx1202401091234567890123456789",
10  "customs_details": {
11    "customs_code": "GUANGZHOU_ZS",
12    "merchant_customs_number": "C129000000",
13    "merchant_customs_name": "Airwallex"
14  },
15  "sub_order": {
16    "order_number": "o100001213",
17    "provider_order_id": "T912345678901234569",
18    "amount": 10,
19    "shipping_fee": 0,
20    "currency": "USD"
21  },
22  "shopper_identity_check_result": "UNCHECKED",
23  "created_at": "2024-01-31T06:59:10+00:00",
24  "updated_at": "2024-01-31T06:59:10+00:00"
25}

Was this section helpful?

Retrieve a Customs Declaration

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

Copy for LLMView as Markdown

Retrieve an existing customs declaration.

Path parameters

idrequiredstring

Customs Declaration unique identifier.

Response body - 200 OK

awx_request_idstring

Request unique identifier generated by Air Wallex send to the provider for a Payment Attempt

created_atstring

Time at which the Customs Declaration was created

customs_detailsobject

Customs details

customs_details.customs_codestring

customs_details.merchant_customs_namestring

Merchant's registered name in customs system. Maximum length is 256.

customs_details.merchant_customs_numberstring

Merchant's registered number in customs system. Maximum length is 32.

customs_status_messagestring

Additional status message from customs

idstring

Unique identifier for the Customs Declaration

payment_method_typestring

Payment method type of the Payment Attempt

provider_transaction_idstring

The unique transaction identifier assigned by the provider for a payment attempt. Example of our providers: Cards, WeChat, Alipay etc.

request_idstring

Unique request identifier specified by the merchant in the last operation

shopper_identity_check_resultstring

Identity check result of the shopper.

statusstring

Customs processing status, UNDECLARED/PROCESSING/SUCCESS/FAIL

sub_orderobject

Suborder info, required for each customs declaration.

sub_order.amountnumber

The total amount of your sub_order, shipping fee shall be included, unit is Yuan. Please refer to supported currencies for supported minor units.

sub_order.currencystring

Currency for the suborder, only CNY supported now.

sub_order.order_numberstring

Suborder number in merchant system. Maximum length is 128.

sub_order.shipping_feenumber

Suborder transport fee, unit is Yuan

sub_order.provider_order_idstring

updated_atstring

Last time at which the Customs Declaration was updated or operated on

verification_department_codestring

Verification department code

verification_department_transaction_idstring

Transaction unique identifier returned by verification department

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url), `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

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

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/pa/customs_declarations/cdc_hkpdkjd4t98sa' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "id": "cdc_hkpdkjd4t98sa",
3  "request_id": "4dd119d8-331d-41a0-b037-122f0113b227",
4  "status": "DECLARED",
5  "payment_method_type": "card",
6  "provider_transaction_id": "t202401091234567890123456789",
7  "awx_request_id": "1234567890123456789",
8  "verification_department_code": "OTHERS",
9  "verification_department_transaction_id": "tx1202401091234567890123456789",
10  "customs_details": {
11    "customs_code": "GUANGZHOU_ZS",
12    "merchant_customs_number": "C129000000",
13    "merchant_customs_name": "Airwallex"
14  },
15  "sub_order": {
16    "order_number": "o100001213",
17    "provider_order_id": "T912345678901234569",
18    "amount": 10,
19    "shipping_fee": 0,
20    "currency": "USD"
21  },
22  "shopper_identity_check_result": "UNCHECKED",
23  "created_at": "2024-01-31T06:59:10+00:00",
24  "updated_at": "2024-01-31T06:59:10+00:00"
25}

Was this section helpful?

Update a Customs Declaration

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

Copy for LLMView as Markdown

Update an existing customs declaration. SHANGHAI_CBT does not support update after a successful declaration.

Path parameters

idrequiredstring

id.

Request body

request_idrequiredstring

Unique request identifier specified by the merchant. Maximum length is 64.

customs_codestring

China customs code.

merchant_customs_namestring

Merchant's registered name in customs system. Maximum length is 256.

merchant_customs_numberstring

Merchant's registered number in customs system. Maximum length is 32.

shopper_detailsobject

Shopper details. Will be used to update shopper identity check information.

shopper_details.shopper_idrequiredstring

Mainland China unique identifier of the shopper.

shopper_details.shopper_namerequiredstring

Name of the shopper in simplified Chinese.

sub_order_amountnumber

Suborder amount. Please refer to supported currencies for supported minor units.

Response body - 200 OK

awx_request_idstring

Request unique identifier generated by Air Wallex send to the provider for a Payment Attempt

created_atstring

Time at which the Customs Declaration was created

customs_detailsobject

Customs details

customs_details.customs_codestring

customs_details.merchant_customs_namestring

Merchant's registered name in customs system. Maximum length is 256.

customs_details.merchant_customs_numberstring

Merchant's registered number in customs system. Maximum length is 32.

customs_status_messagestring

Additional status message from customs

idstring

Unique identifier for the Customs Declaration

payment_method_typestring

Payment method type of the Payment Attempt

provider_transaction_idstring

The unique transaction identifier assigned by the provider for a payment attempt. Example of our providers: Cards, WeChat, Alipay etc.

request_idstring

Unique request identifier specified by the merchant in the last operation

shopper_identity_check_resultstring

Identity check result of the shopper.

statusstring

Customs processing status, UNDECLARED/PROCESSING/SUCCESS/FAIL

sub_orderobject

Suborder info, required for each customs declaration.

sub_order.amountnumber

The total amount of your sub_order, shipping fee shall be included, unit is Yuan. Please refer to supported currencies for supported minor units.

sub_order.currencystring

Currency for the suborder, only CNY supported now.

sub_order.order_numberstring

Suborder number in merchant system. Maximum length is 128.

sub_order.shipping_feenumber

Suborder transport fee, unit is Yuan

sub_order.provider_order_idstring

updated_atstring

Last time at which the Customs Declaration was updated or operated on

verification_department_codestring

Verification department code

verification_department_transaction_idstring

Transaction unique identifier returned by verification department

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `invalid_status_for_operation`, `provider_declined`, `provider_unavailable`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url), `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

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

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/pa/customs_declarations/cdc_hkpdkjd4t98sa/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "customs_code": "GUANGZHOU_ZS",
>  "merchant_customs_name": "C129000000",
>  "merchant_customs_number": "Airwallex",
>  "request_id": "ce113401-b801-4722-b43b-1ddb50e8951f",
>  "shopper_details": {
>    "shopper_id": "800000206709306711",
>    "shopper_name": "nessus_was_textvpwjrhzt"
>  },
>  "sub_order_amount": 10
>}'

Response (200 OK)

1{
2  "id": "cdc_hkpdkjd4t98sa",
3  "request_id": "ce113401-b801-4722-b43b-1ddb50e8951f",
4  "status": "DECLARED",
5  "payment_method_type": "card",
6  "provider_transaction_id": "t202401091234567890123456789",
7  "awx_request_id": "1234567890123456789",
8  "verification_department_code": "OTHERS",
9  "verification_department_transaction_id": "tx1202401091234567890123456789",
10  "customs_details": {
11    "customs_code": "GUANGZHOU_ZS",
12    "merchant_customs_number": "C129000000",
13    "merchant_customs_name": "Airwallex"
14  },
15  "sub_order": {
16    "order_number": "o100001213",
17    "provider_order_id": "T912345678901234569",
18    "amount": 10,
19    "shipping_fee": 0,
20    "currency": "USD"
21  },
22  "shopper_identity_check_result": "UNCHECKED",
23  "created_at": "2024-01-31T06:59:10+00:00",
24  "updated_at": "2024-01-31T06:59:10+00:00"
25}

Was this section helpful?

Redeclare a Customs Declaration

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

Copy for LLMView as Markdown

Redeclare an existing customs declaration. SHANGHAI_CBT does not support redeclaration after a successful declaration.

Path parameters

idrequiredstring

Customs Declaration unique identifier.

Request body

request_idrequiredstring

Unique request identifier specified by the merchant. Maximum length is 64.

Response body - 200 OK

awx_request_idstring

Request unique identifier generated by Air Wallex send to the provider for a Payment Attempt

created_atstring

Time at which the Customs Declaration was created

customs_detailsobject

Customs details

customs_details.customs_codestring

customs_details.merchant_customs_namestring

Merchant's registered name in customs system. Maximum length is 256.

customs_details.merchant_customs_numberstring

Merchant's registered number in customs system. Maximum length is 32.

customs_status_messagestring

Additional status message from customs

idstring

Unique identifier for the Customs Declaration

payment_method_typestring

Payment method type of the Payment Attempt

provider_transaction_idstring

The unique transaction identifier assigned by the provider for a payment attempt. Example of our providers: Cards, WeChat, Alipay etc.

request_idstring

Unique request identifier specified by the merchant in the last operation

shopper_identity_check_resultstring

Identity check result of the shopper.

statusstring

Customs processing status, UNDECLARED/PROCESSING/SUCCESS/FAIL

sub_orderobject

Suborder info, required for each customs declaration.

sub_order.amountnumber

The total amount of your sub_order, shipping fee shall be included, unit is Yuan. Please refer to supported currencies for supported minor units.

sub_order.currencystring

Currency for the suborder, only CNY supported now.

sub_order.order_numberstring

Suborder number in merchant system. Maximum length is 128.

sub_order.shipping_feenumber

Suborder transport fee, unit is Yuan

sub_order.provider_order_idstring

updated_atstring

Last time at which the Customs Declaration was updated or operated on

verification_department_codestring

Verification department code

verification_department_transaction_idstring

Transaction unique identifier returned by verification department

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `duplicate_request`, `provider_declined`, `provider_unavailable`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url), `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

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

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/pa/customs_declarations/cdc_hkpdkjd4t98sa/redeclare' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "request_id": "a268d48f-f42a-438e-bf99-ca74b7f58d09"
>}'

Response (200 OK)

1{
2  "id": "cdc_hkpdkjd4t98sa",
3  "request_id": "a268d48f-f42a-438e-bf99-ca74b7f58d09",
4  "status": "REDECLARED",
5  "payment_method_type": "card",
6  "provider_transaction_id": "t202401091234567890123456789",
7  "awx_request_id": "1234567890123456789",
8  "verification_department_code": "OTHERS",
9  "verification_department_transaction_id": "tx1202401091234567890123456789",
10  "customs_details": {
11    "customs_code": "GUANGZHOU_ZS",
12    "merchant_customs_number": "C129000000",
13    "merchant_customs_name": "Airwallex"
14  },
15  "sub_order": {
16    "order_number": "o100001213",
17    "provider_order_id": "T912345678901234569",
18    "amount": 10,
19    "shipping_fee": 0,
20    "currency": "USD"
21  },
22  "shopper_identity_check_result": "UNCHECKED",
23  "created_at": "2024-01-31T06:59:10+00:00",
24  "updated_at": "2024-01-31T06:59:10+00:00"
25}

Was this section helpful?