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

# Card BIN 推廣活動

QFPay Checkout 支援線上卡支付的 **Card BIN 推廣活動（Card BIN Promotions）**。\
商戶可透過指定符合資格的 Card BIN 範圍，向特定持卡人提供折扣或推廣活動。

Card BIN 推廣常見應用場景包括：

* 銀行聯名卡推廣活動
* Visa / Mastercard 推廣活動
* 商戶補貼折扣
* 限時發卡機構活動
* 會員或合作品牌推廣活動

***

## Card BIN 推廣運作方式

Card BIN 推廣會根據以下條件進行匹配：

1. 商戶定義的 `promotion_tag`
2. 符合資格的 Card BIN 範圍
3. 支援的支付方式
4. 推廣活動有效期間

只有符合所有條件的交易才可成功套用推廣。

***

## 核心概念

| 名稱              | 說明                            |
| --------------- | ----------------------------- |
| 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 範例

```text theme={null}
{
  "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)