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

# 交易狀態碼

> QFPay 常見交易回應碼與整合建議。

以下列出 QFPay 常見回應碼（`respcd`）與對應說明。

<Note>
  `respcd = 0000` 表示 API 呼叫成功。<br />實際交易狀態仍需依 `txstatus` 或查詢 API 確認。
</Note>

***

# 一般成功

| 返回碼  | 說明   |
| ---- | ---- |
| 0000 | 交易成功 |

***

# 請求與簽名錯誤

| 返回碼  | 說明      |
| ---- | ------- |
| 1102 | 重複請求    |
| 1103 | 請求格式錯誤  |
| 1104 | 請求參數錯誤  |
| 1108 | 簽名錯誤    |
| 2011 | 交易流水號重複 |

整合建議：

* 檢查參數格式與必填欄位
* 確認簽名排序與演算法
* 確保 `out_trade_no` 唯一

***

# 設備與門市狀態錯誤

| 返回碼  | 說明            |
| ---- | ------------- |
| 1105 | 設備未啟用         |
| 1106 | 無效設備          |
| 1107 | 設備無權限         |
| 1241 | 門市不存在或狀態不正確   |
| 1242 | 門市配置異常        |
| 1243 | 門市已被禁用        |
| 1251 | 門市配置異常（系統處理中） |

整合建議：

* 確認門市與設備開通狀態
* 若持續發生，聯絡技術支援

***

# 訂單狀態相關

| 返回碼  | 說明      |
| ---- | ------- |
| 1125 | 交易已退款   |
| 1142 | 訂單已關閉   |
| 1181 | 訂單已過期   |
| 1260 | 該訂單已支付  |
| 1261 | 該訂單未支付  |
| 1262 | 該訂單已退款  |
| 1263 | 該訂單已撤銷  |
| 1264 | 該訂單已關閉  |
| 1266 | 訂單金額錯誤  |
| 1267 | 訂單信息不匹配 |
| 1268 | 訂單不存在   |

整合建議：

* 先使用交易查詢 API 確認最新狀態
* 避免直接重送支付請求

***

# 處理中狀態

| 返回碼  | 說明               |
| ---- | ---------------- |
| 1143 | 訂單尚未支付或消費者正在輸入密碼 |
| 1145 | 交易處理中            |
| 1298 | 網絡擁擠，若已付款請勿重試    |

整合建議：

* 請勿立即重試
* 使用交易查詢 API 輪詢確認狀態
* 建議實作延遲查詢機制

***

# 支付渠道錯誤

| 返回碼  | 說明         |
| ---- | ---------- |
| 1147 | 微信支付交易錯誤   |
| 1201 | 餘額不足       |
| 1202 | 付款碼錯誤或過期   |
| 1203 | 賬戶錯誤       |
| 1204 | 銀行錯誤       |
| 1205 | 交易失敗       |
| 1212 | 請使用銀聯境外碼付款 |
| 1297 | 銀行系統繁忙     |
| 2005 | 付款碼錯誤或過期   |

整合建議：

* 提示消費者更換支付方式
* 可允許重新發起交易

***

# 退款相關限制

| 返回碼  | 說明             |
| ---- | -------------- |
| 1150 | T0 結算方式不支援撤銷   |
| 1155 | 退款請求被拒絕        |
| 1265 | 特定時段或活動交易不支援退款 |
| 1269 | 當日未結算金額不足      |
| 1270 | 該幣種不支援部分退款     |
| 1271 | 該交易不支援部分退款     |
| 1272 | 退款金額超過可退款金額    |

整合建議：

* 查詢原交易狀態與可退款金額
* 確認支付渠道退款規則

***

# 系統或風控錯誤

| 返回碼  | 說明            |
| ---- | ------------- |
| 1100 | 系統維護中         |
| 1101 | Reversal 錯誤   |
| 1136 | 交易不存在或無法處理    |
| 1250 | 交易被禁止         |
| 1252 | 發送交易請求時發生系統錯誤 |
| 1254 | 系統異常          |
| 1294 | 交易存在風險，被銀行禁止  |
| 1295 | 網絡擁擠          |
| 1296 | 網絡擁擠，請稍後重試    |

整合建議：

* 可實作延遲重試機制
* 若涉及風控（1294），不建議自動重試
* 持續發生請聯絡技術支援

***

# 整合建議總結

1. 僅在明確可重試情境下實作重試機制
2. 對於 1143 / 1145 等狀態，使用查詢 API 確認結果
3. 避免在未知狀態下重複發送支付請求
4. 所有錯誤均應記錄完整日誌（含請求參數與回應碼）