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 Checkout 支援線上卡支付的 Card BIN 推廣活動（Card BIN Promotions）。
商戶可透過指定符合資格的 Card BIN 範圍，向特定持卡人提供折扣或推廣活動。
Card BIN 推廣常見應用場景包括：
- 銀行聯名卡推廣活動
- Visa / Mastercard 推廣活動
- 商戶補貼折扣
- 限時發卡機構活動
- 會員或合作品牌推廣活動
Card BIN 推廣運作方式
Card BIN 推廣會根據以下條件進行匹配：
- 商戶定義的
promotion_tag
- 符合資格的 Card BIN 範圍
- 支援的支付方式
- 推廣活動有效期間
只有符合所有條件的交易才可成功套用推廣。
核心概念
| 名稱 | 說明 |
|---|
| Card BIN | 卡號前 6–8 位數字，用於識別發卡銀行與卡種 |
promotion_tag | 用於識別推廣活動的唯一標識 |
| 推廣期間 | 推廣活動的開始與結束時間 |
| 支援支付方式 | 可參與推廣的支付方式（如 Visa、Mastercard） |
支援場景
支援的推廣活動範例：
- Visa 持卡人享有 9 折優惠
- Mastercard 用戶獲得 Cashback
- 特定銀行卡推廣活動
- 商戶季節性推廣
- 聯名品牌合作活動
前置需求
在啟用 Card BIN 推廣前，商戶需先向 QFPay 提供以下資料進行預先登記。
必要資訊
| 項目 | 說明 |
|---|
| 推廣期間 | 推廣開始與結束日期 / 時間 |
| Card BIN 清單 | 符合資格的 Card BIN 範圍 |
| Promotion Tag | 推廣活動唯一識別碼 |
| 歷史推廣資訊 | （選填）過往推廣活動資料供審核參考 |
推廣設定範例
| 項目 | 範例 |
|---|
| 推廣期間 | 2025-06-01 至 2025-06-30 |
| 支援支付方式 | Visa、Mastercard |
| 符合資格 BIN | 412345、512345、622345 |
| Promotion Tag | PROMO12345 |
API 對接方式
如需將交易識別為推廣活動交易，請於支付請求中加入 promotion_tag。
Request 範例
{
"promotion_tag": "PROMO12345"
}
$$
---
## Request Parameters
| 參數 | 類型 | 必填 | 說明 |
| --- | --- | --- | --- |
| `promotion_tag` | String | 是 | 推廣活動註冊時使用的 Promotion Identifier |
---
## 推廣匹配邏輯
交易需符合以下條件才可成功套用推廣：
- `promotion_tag` 有效
- 推廣期間內
- Card BIN 符合資格清單
- 支援的支付方式
若任何條件不符合，交易可能無法套用推廣，並於支付過程中顯示不符合推廣資格的提示訊息。
---
## 測試與驗證
正式上線前，建議進行以下測試：
### 測試交易
請分別使用：
- 符合資格的 Card BIN
- 不符合資格的 Card BIN
確認：
- 符合資格的卡可成功觸發推廣
- 不符合資格的卡不會獲得推廣
---
## 錯誤處理
請確保系統能正確處理推廣相關錯誤情境。
### 常見情境
| 情境 | 說明 |
| --- | --- |
| `promotion_tag` 無效 | 推廣活動不存在 |
| BIN 不符合資格 | 卡 BIN 不符合推廣規則 |
| 推廣已過期 | 推廣活動已超過有效期間 |
| 不支援的支付方式 | 錢包或卡種不支援推廣 |
---
## Webhook 與報表
商戶可透過以下方式監控推廣活動表現與驗證交易：
- QFPay Merchant Portal
- 交易報表
- 商戶後台交易紀錄
建議商戶於內部訂單系統中保存 `promotion_tag` 以便後續對帳與分析。
---
## 最佳實踐
<Tip>
建議每個推廣活動使用獨立的 `promotion_tag`，方便後續對帳與數據分析。
</Tip>
<Tip>
正式上線前，請同時測試成功與失敗的推廣匹配情境。
</Tip>
<Warning>
所有 Card BIN 推廣活動必須事先向 QFPay 完成登記。
未登記的 `promotion_tag` 可能無法成功套用推廣或發卡機構活動。
</Warning>
<Warning>
若同時存在多個推廣活動，請確認交易使用正確的 `promotion_tag`。
</Warning>
---
## 上線流程
1. 向 QFPay 提交推廣活動資料
2. 完成 API 對接與測試
3. 收到 QFPay 確認
4. 於指定推廣期間正式上線
5. 持續監察交易與推廣表現
---
## 推廣活動結束後建議
推廣活動結束後，建議商戶：
- 檢視交易成效
- 分析轉換率與使用情況
- 評估各 BIN 的活動表現
- 向 QFPay 提供改善建議
---
## 技術支援
如需協助設定或登記推廣活動，請聯絡：
[technical.support@qfpay.com](mailto:technical.support@qfpay.com)
