> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customs Declaration API

> Submit cross-border transaction information to customs authorities for Alipay and WeChat payments.

# 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

| 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` = Success<br />`1143` / `1145` = Pending<br />Others = 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.

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

| 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:<br />- `sub_order_no`<br />- `verify_department`<br />- `verify_department_trade_id`<br />- `resperr`<br />- `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

<Warning>
  Customs declaration must only be submitted after a successful payment (`respcd = 0000`). Submitting before payment confirmation may cause rejection.
</Warning>

* 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](/integration/api-reference/status-codes).