Skip to main content

​
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
Customs declaration must be performed after a successful payment.

​
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
The QFPay Transaction ID (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

​
Sub-Order Fields (Split or Modified Orders)

Required only when the original payment is split into multiple customs declarations.

​
Response Parameters

​
Response Behaviour

  • 0000 → Declaration successfully accepted.
  • 1143 / 1145 → Declaration processing.
  • Other codes → Failed. Merchant should correct and retry.
Customs declaration processing may not be instantaneous.

​
2. Query Customs Declaration

Check the current status of a declaration.

​
Endpoint

§§§http HTTP POST /custom/v1/query GET /custom/v1/query §§§

​
Request Parameters

​
Response Fields

​
3. Repush Customs Declaration

Use when a previous declaration was not successfully received by customs.

​
Endpoint

§§§http HTTP POST /custom/v1/redeclare §§§

​
Request Parameters

​
Integration Notes

Customs declaration must only be submitted after a successful payment (respcd = 0000). Submitting before payment confirmation may cause rejection.
  • Use the payment ID (syssn), not refund ID.
  • Store verify_department_trade_id for reconciliation.
  • For WeChat, split declarations must ensure order_fee = product_fee + transport_fee.
  • For Alipay, ensure mch_customs_name matches your registered customs record.
  • If 1143 / 1145 is 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.