API REFERENCE

Submit a customs declaration

YabandPay documentation·Updated Oct 26, 2026

Tip

Note:

Each order can have only one unsplit-order record and multiple split-order records. Split-order records with the same sub_order_no (merchant sub-order number) are treated as the same record.

To modify customs declaration information, set action_type to MODIFY. Only the merchant registration number, registered name, customs code and amount, and user identity document information can be modified. For split-order records, pass sub_order_no to identify the record to modify.

If a transaction has been submitted for customs declaration but the electronic port loses the order, use the resend API. When resending, keep the customs declaration reference number the same as in the original request.

Amounts in the customs declaration API are in fen.

The customs declaration currency is CNY (the amount paid by the user in CNY), which can be obtained through Order query.

Parameter	Type	Description	Required
user	String	UID of the cashier or super administrator account	Required
sign	String	Signature	Required
method	String	v3.CustomDeclareOrder	Required
time	Long	Timestamp	Required

Parameters

Parameter	Type	Description	Required
trade_id	String	YabandPay transaction ID	Required
customs	String	Customs name	Required
mch_customs_no	String	Merchant customs registration number	Required
mch_name	String	Merchant name registered with customs	Required
duty	Int	Customs duty in fen; not submitted to customs	Optional
action_type	String	Declaration action: ADD to add, MODIFY to modify; defaults to ADD	Optional
sub_order_no	String	Merchant sub-order number	Optional (required for split orders)
currency	String	Declaration currency; CNY is recommended	Optional (required for split orders)
order_fee	Int	Sub-order amount (obtain the total order amount amount_cny through QueryOrder), order_fee=transport_fee+product_fee	Optional (required for split orders)
transport_fee	Int	Sub-order shipping amount in fen	Optional (required for split orders)
product_fee	Int	Sub-order product price in fen	Optional (required for split orders)
cert_type	String	Identity document type; pass the fixed value IDCARD. Only mainland China identity cards are currently supported.	Optional
cert_id	String	Identity document number: the user's mainland China identity card number. If the number ends with X, use an uppercase X.	Optional
name	String	User's name	Optional

customs field values:

WeChat Pay customs declaration values

Field	Description
GUANGZHOU_ZS	Guangzhou (General Administration version)
GUANGZHOU_HP_GJ	Guangzhou Huangpu Inspection and Quarantine
GUANGZHOU_NS_GJ	Guangzhou Nansha Inspection and Quarantine
HANGZHOU_ZS	Hangzhou (General Administration version)
NINGBO	Ningbo
ZHENGZHOU_BS	Zhengzhou (Bonded Logistics Center)
CHONGQING	Chongqing
SHANGHAI_ZS	Shanghai (General Administration version)
SHENZHEN	Shenzhen
ZHENGZHOU_ZH_ZS	Zhengzhou Comprehensive Bonded Zone (General Administration version)
TIANJIN	Tianjin

TIANJIN (To send an order to Tianjin Customs, configure both the Tianjin Customs registration information and the Tianjin Inspection and Quarantine registration information in the merchant management portal. When calling the customs declaration API, send only to Tianjin Customs, using a single API request.)

Alipay customs declaration values

Field	Description
ZONGSHU	General Administration of Customs of China
ZHENGZHOU	Zhengzhou
NINGBO	Ningbo
SHANGHAI_CBT	Shanghai

Signature example:

Sorted parameters concatenated into a URL-style query string

"customs=NINGBO&mch_customs_no=3302462090&mch_name=宁波保税区嘉里大通物流有限公司&method=v3.CustomDeclareOrder&time=1560499094&trade_id=4760a968-4c5d-1e7e-3b88-89641af6e041&user=YOUR_CASHIER_UID"

Sign stringA using secret_key

The resulting signature is:

"YOUR_SIGNATURE"

Request example:

{
	"user": "YOUR_CASHIER_UID",
	"sign": "YOUR_SIGNATURE",
	"method": "v3.CustomDeclareOrder",
	"time": 1560499094,
	"data": {
		"trade_id": "4760a968-4c5d-1e7e-3b88-89641af6e041",
		"customs": "NINGBO",
        "mch_customs_no": "3302462090",
        "mch_name": "宁波保税区嘉里大通物流有限公司"
	}
}

Customs declaration response example:

{
    "status": true,
    "code": "200",
    "data": {
        "appid": "",
        "return_code":"SUCCESS",
        "result_code":"SUCCESS",
        "mchid": "3302462090",
        "out_trade_no": "4434a6e235e81cde4aee954c0031ad96",
        "state": "SUCCESS",
        "sub_order_id": "e0721a7f957e8e55dfbb5c7bcb4441d6",
        "sub_order_no": "1234567890",
        "transaction_id": "2024061922001467961423939655",
        "verify_department": "OTHERS",
        "verify_department_trade_id": "2024061922001467961423939655",
        "cert_check_result": "SAME", //Identity comparison between the purchaser and payer (UNCHECKED: purchaser identity not uploaded; SAME: uploaded purchaser identity matches payer identity; DIFFERENT: uploaded purchaser identity differs from payer identity)
        "transId": "20240619161756813048",
        "customs_declarations_id": "e0721a7f957e8e55dfbb5c7bcb4441d6"
    },
    "message": ""
}

State statuses:

Status	Description
UNDECLARED	Undeclared (the declaration has been submitted and is awaiting customs processing; no resubmission is needed)
SUBMITTED	Declaration submitted (this status is recorded when the order has been sent to customs, the merchant submits a new declaration, and customs provides a modification API)
PROCESSING	Declaration in progress
SUCCESS	Declaration successful
FAIL	Declaration failed
EXCEPT	Customs API error