> ## 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.

# 請求參數

> 支付 API 請求參數格式與 HTTP Header 要求說明。

以下說明 `/trade/v1/payment` API 的常見請求參數格式與 HTTP 要求。

不同支付場景可能需要額外參數，請依對應 API 文件確認。

***

## HTTP 請求

```text TEXT theme={null}
POST /trade/v1/payment 
```

***

# 公共支付請求參數

| 參數名稱           | 是否必填     | 類型          | 說明                                                       |
| -------------- | -------- | ----------- | -------------------------------------------------------- |
| `txamt`        | 是        | Int(11)     | 交易金額，以「分」為單位（例如 100 = 1 元）。建議大於 200 以降低風控攔截機率。           |
| `txcurrcd`     | 是        | String(3)   | 交易幣別。請參考 [交易貨幣](./currencies.md)。                        |
| `pay_type`     | 是        | String(6)   | 支付方式代碼。請參考 [支付方式代碼](./paytypes.md)。                      |
| `out_trade_no` | 是        | String(128) | 商戶交易編號。在同一商戶帳戶下，每一筆支付與退款請求必須唯一。                          |
| `txdtm`        | 是        | String(20)  | 交易時間，格式：`YYYY-MM-DD HH:mm:ss`                            |
| `auth_code`    | 僅 CPM 必填 | String(128) | 消費者錢包條碼或二維碼授權碼。每個 `auth_code` 僅可使用一次，並於產生後 24 小時內有效。     |
| `expired_time` | 僅 MPM 可選 | String(3)   | QR Code 有效時間（分鐘）。預設 30，最小 5，最大 120。                      |
| `goods_name`   | 視場景      | String(64)  | 商品名稱或描述。最多 20 字元，不得包含特殊符號。中文需使用 UTF-8 編碼。部分 App 支付場景為必填。 |
| `mchid`        | 視開通情況    | String(16)  | 若商戶開通時提供 `mchid`，請求中必須帶上；若未提供，請勿傳入。                      |
| `udid`         | 否        | String(40)  | 裝置識別碼，用於內部交易追蹤。                                          |
| `notify_url`   | 否        | String(256) | 交易完成後的非同步通知 URL。                                         |

***

## 重要規則

<Note>
  `out_trade_no` 必須在同一商戶帳戶下保持唯一。\
  重複使用將導致交易拒絕或回傳既有交易結果。
</Note>

<Note>
  不同 `pay_type` 可能對參數有額外限制（例如幣別限制或是否支援退款）。
</Note>

***

# 簽名要求

所有請求必須依規則產生簽名。

請參考：

[簽名生成方式](/zh-hant/integration/preparation/authentication-and-signature)

***

# 請求格式說明

| 欄位                 | 說明                                |
| ------------------ | --------------------------------- |
| Character Encoding | UTF-8                             |
| Method             | POST（部分 API 支援 GET，請依文件說明）        |
| Content-Type       | application/x-www-form-urlencoded |

***

# 必要 HTTP Header

| Header          | 是否必填 | 說明                                            |
| --------------- | ---- | --------------------------------------------- |
| `X-QF-APPCODE`  | 是    | QFPay 提供的商戶 App Code                          |
| `X-QF-SIGN`     | 是    | 依簽名規則產生的簽名值                                   |
| `X-QF-SIGNTYPE` | 否    | 使用的簽名演算法。若為 SHA256，需傳入 `SHA256`；未指定時預設為 `MD5` |

***

# 回應格式說明

<Note>
  API 回應內容為 JSON 格式。

  建議同時驗證回應資料完整性，並依 `respcd` 判斷交易結果。
</Note>