非同步通知

QFPay 目前支援以下兩種非同步通知：

付款成功："notify_type": "payment"
退款成功："notify_type": "refund"

未來版本的通知參數可能新增欄位。建議你的接收端採用「可忽略未知欄位」的處理方式，並定期查看最新文件更新。

概述

當支付或退款成功後，QFPay 會以 HTTP POST 方式向商戶已設定的 callback URL 發送一筆 JSON 通知，用於即時更新交易結果。

即使已收到通知，也建議使用交易查詢 API 二次驗證交易狀態，避免因網路重試或重放造成誤判。

出於安全考量，callback URL 僅支援 80 / 443 端口，且 Content-Type 固定為 application/json。

非同步通知規則

僅在交易成功（付款或退款）後才會發送通知。
請透過電郵提交通知端點 URL 至 technical.support@qfpay.com，由技術支援協助設定。
商戶收到通知後必須進行簽名驗證。驗證成功後回覆：
- HTTP Status Code：200 OK
- Response Body：SUCCESS
若未收到預期回應，系統會依以下時間間隔重試：
- 2 分鐘 → 10 分鐘 → 10 分鐘 → 60 分鐘 → 2 小時 → 6 小時 → 15 小時
同一組 app_code + client_key 僅能綁定一個通知 URL。代理商應為子商戶共用同一接收端點。
HTTP 方法：POST
Content-Type：application/json

簽名驗證

非同步通知的簽名驗證方式與一般 API 請求不同：必須使用「原始 request body（未重排 / 未格式化的 JSON 字串）」來驗證。

驗證步驟

從 HTTP header 取得 X-QF-SIGN。
取得原始 request body（JSON 字串），直接在尾端串接 client_key。
對字串做 MD5 雜湊，並轉成大寫。
若雜湊結果等於 X-QF-SIGN，視為驗證成功，回覆 200 OK 與 SUCCESS。

請使用「原始 body」做驗證。若你把 JSON parse 後再 json.dumps() 重新序列化，欄位順序與空白可能不同，會導致簽名不一致。

簽名範例

import hashlib

client_key = "3ABB1BFFE2E0497BB9270978B0BXXXXX"

# 假設你取得的 raw_body 是 HTTP request 的原始 body（bytes 或 str）
raw_body = b'{"status":"1","notify_type":"payment"}'

combine = raw_body + client_key.encode("utf-8")
signature = hashlib.md5(combine).hexdigest().upper()

print(signature)

實作時請以你實際收到的完整 raw body 進行計算；上例僅示意流程。

通知內容範例

JSON

{
  "status": "1",
  "pay_type": "800101",
  "sysdtm": "2020-05-14 12:32:56",
  "paydtm": "2020-05-14 12:33:56",
  "goods_name": "",
  "txcurrcd": "HKD",
  "txdtm": "2020-05-14 12:32:56",
  "mchid": "lkbqahlRYj",
  "txamt": "10",
  "exchange_rate": "",
  "chnlsn2": "",
  "out_trade_no": "YEPE7WTW46NVU30JW5N90H7DHD94N56B",
  "syssn": "20200514000300020093755455",
  "cash_fee_type": "",
  "cancel": "0",
  "respcd": "0000",
  "goods_info": "",
  "cash_fee": "0",
  "notify_type": "payment",
  "chnlsn": "2020051422001453561444935817",
  "cardcd": "2088032341453564"
}

回傳欄位說明

欄位名稱	必填	類型	說明
`status`	是	String	交易成功狀態，固定為 `1`
`notify_type`	是	String	通知類型：`payment` 或 `refund`
`pay_type`	是	String	QFPay 支付代碼，請參考支付方式
`syssn`	是	String	QFPay 交易號（可能是「付款交易號」或「退款交易號」，取決於 `notify_type`）
`out_trade_no`	是	String	商戶訂單號
`txamt`	是	String	金額（單位：分）。建議金額 > 200 以避免風控
`txcurrcd`	是	String	幣別，請參考交易貨幣
`txdtm`	是	String	商戶請求時間
`sysdtm`	是	String	系統交易時間（常用作結算日切點）
`paydtm`	是	String	用戶實際支付時間
`cancel`	是	String	交易取消狀態：`0`=未取消；其他值請見下方「Cancel 定義」
`respcd`	是	String	固定為 `0000`（表示成功通知）
`mchid`	否	String	商戶號（多見於代理商場景）
`goods_name`	否	String	商品名稱（中文請使用 UTF-8）
`goods_info`	否	String	商品描述
`exchange_rate`	否	String	匯率（若有跨幣種轉換）
`chnlsn`	否	String	支付渠道交易號
`chnlsn2`	否	String	附加渠道交易參考
`cardcd`	否	String	卡號
`cash_fee`	否	String	實際用戶支付金額（扣除優惠後）
`cash_fee_type`	否	String	`cash_fee` 的幣別
`cash_refund_fee`	否	String	實際退款金額
`cash_refund_fee_type`	否	String	`cash_refund_fee` 的幣別

syssn 的語境容易混淆：在非同步通知中，syssn 代表「本次通知所對應的交易號」。若 notify_type=refund，它通常是退款交易號，而不是原始付款交易號。

Cancel 定義

值	意義
`0`	未取消
`1`	CPM：已撤銷或已退款
`2`	MPM：已取消
`3`	已退款
`4`	預授權訂單已完成（Alipay）
`5`	部分退款

通知來源 IP

請確保你的伺服器允許以下來源 IP 發送的 POST 請求：

13.228.112.115
18.138.115.47
18.166.202.92

準備

商業場景

API 參考文件

實體店支付

線上支付

共用端點

概述

非同步通知規則

簽名驗證

驗證步驟

簽名範例

通知內容範例

回傳欄位說明

Cancel 定義

通知來源 IP

​概述

​非同步通知規則

​簽名驗證

​驗證步驟

​簽名範例

​通知內容範例

​回傳欄位說明

​Cancel 定義

​通知來源 IP

概述

非同步通知規則

簽名驗證

驗證步驟

簽名範例

通知內容範例

回傳欄位說明

Cancel 定義

通知來源 IP