Customs Declaration API
The Customs Declaration API allows merchants to report cross-border eCommerce transactions to customs authorities via Alipay or WeChat. This process is required in certain jurisdictions to:- Comply with cross-border trade regulations
- Enable customs clearance
- Prevent shipment delays
- Ensure payment and goods release alignment
When to Use
Use this API when:- The payment is cross-border
- Customs reporting is legally required
- The payment was completed successfully (
respcd = 0000) - The transaction involves Alipay or WeChat
syssn) used here refers to the payment ID, not a refund ID.
1. Push Customs Declaration
Submit declaration data to Alipay or WeChat.Endpoint
§§§http HTTP POST /custom/v1/declare §§§Request Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
trade_type | Yes | String(8) | Payment platform: weixin or alipay |
syssn | Yes | String(32) | QFPay Transaction ID (Payment ID) |
customs | Yes | String(20) | Customs bureau code (e.g. SHANGHAI_ZS) |
mch_customs_no | Yes | String(20) | Merchant customs registration number |
action_type | No | String | WeChat only: ADD (new) or MODIFY (update) |
mch_customs_name | No | String | Alipay merchant record name |
out_request_no | No | String(32) | Unique request ID (Alipay only) |
amount | No | String | Declaration amount (Alipay only, e.g. 2.00) |
Sub-Order Fields (Split or Modified Orders)
Required only when the original payment is split into multiple customs declarations.| Parameter | Conditional | Type | Description |
|---|---|---|---|
sub_order_no | Yes (split orders) | String(64) | Sub-order identifier |
fee_type | Yes (WeChat only) | String(8) | Must be CNY |
order_fee | Yes (WeChat only) | String | Total sub-order amount in CNY cents |
product_fee | Yes | String | Product amount in CNY cents |
transport_fee | Yes | String | Shipping amount in CNY cents |
Response Parameters
| Parameter | Description |
|---|---|
syssn | QFPay Transaction ID (Payment ID) |
respcd | 0000 = Success1143 / 1145 = PendingOthers = Failure |
resperr | Error message |
respmsg | Additional info |
verify_department | Customs authority handling the declaration |
verify_department_trade_id | Customs-assigned trade ID |
Response Behaviour
0000→ Declaration successfully accepted.1143/1145→ Declaration processing.- Other codes → Failed. Merchant should correct and retry.
2. Query Customs Declaration
Check the current status of a declaration.Endpoint
§§§http HTTP POST /custom/v1/query GET /custom/v1/query §§§Request Parameters
| Parameter | Required | Description |
|---|---|---|
trade_type | Yes | weixin or alipay |
customs | Yes | Customs bureau code |
syssn | Yes | QFPay Transaction ID (Payment ID) |
sub_order_no | No | Required for split-order declarations |
Response Fields
| Parameter | Description |
|---|---|
syssn | QFPay Transaction ID |
respcd | Result code |
resperr | Error reason |
respmsg | Additional info |
data | Array of sub-declaration records including: - sub_order_no- verify_department- verify_department_trade_id- resperr- errmsg |
3. Repush Customs Declaration
Use when a previous declaration was not successfully received by customs.Endpoint
§§§http HTTP POST /custom/v1/redeclare §§§Request Parameters
| Parameter | Required | Description |
|---|---|---|
trade_type | Yes | weixin or alipay |
customs | Yes | Customs bureau code |
syssn | Yes | QFPay Transaction ID (Payment ID) |
mch_customs_no | Yes | Merchant customs registration number |
sub_order_no | No | Required for split-order declarations |
Integration Notes
- Use the payment ID (
syssn), not refund ID. - Store
verify_department_trade_idfor reconciliation. - For WeChat, split declarations must ensure
order_fee = product_fee + transport_fee. - For Alipay, ensure
mch_customs_namematches your registered customs record. - If
1143/1145is returned, query status instead of immediately retrying. - Customs declaration rules vary by jurisdiction. Confirm compliance requirements before go-live.
For a complete list of return codes, refer to
Transaction Status Codes.