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

# Visa / Mastercard 線上支付

> 本文件說明如何於香港環境整合 Visa 與 Mastercard 線上信用卡支付，包含整合方式、非同步通知與測試卡資訊。

本頁提供使用 Visa 與 Mastercard 進行線上信用卡支付的整合說明。\
目前於香港環境支援主要國際信用卡品牌之線上交易。

***

## 整合方式選擇

商戶可依需求選擇以下其中一種整合方式：

### 1️⃣ 託管結帳頁面（Checkout）

適用情境：

* 希望快速上線
* 希望降低 PCI 合規負擔
* 不自行處理卡資料

特點：

* 由 QFPay 提供託管式支付頁
* 內建 3D Secure 支援
* PCI 風險最低

***

### 2️⃣ 支付組件（Payment Element SDK）

適用情境：

* 需要完全自訂 UI / UX
* 需與現有頁面深度整合
* 希望保留品牌一致性

特點：

* 卡號輸入欄位嵌入商戶頁面
* 支援 3D Secure
* 提供較高前端控制權

<Note>
  若不確定應選擇哪種整合方式，請依您的上線文件或聯繫 QFPay 技術支援團隊評估。
</Note>

***

## 非同步通知機制（Webhook）

<Info>
  交易完成後，QFPay 將透過非同步通知（Webhook）將最終交易結果推送至商戶後台。
</Info>

商戶需：

* 接收通知
* 驗證簽名
* 根據通知更新訂單狀態

***

## 通知範例

```json Webhook Notification Example theme={null}
{
  "cardtp": "5",
  "cancel": "0",
  "pay_type": "802801",
  "order_type": "payment",
  "clisn": "054256",
  "txdtm": "2021-12-08 07:04:15",
  "out_trade_no": "354267281",
  "syssn": "20211208180500020000001637",
  "sysdtm": "2021-12-08 15:04:16",
  "paydtm": "2021-12-08 15:06:51",
  "txcurrcd": "HKD",
  "udid": "qiantai2",
  "userid": "1130000355",
  "txamt": "1",
  "respcd": "0000",
  "errmsg": "success"
}
```

***

## 重要注意事項

<Warning>
  請務必驗證通知簽名。\
  不可僅依賴未驗證的通知資料更新訂單狀態。
</Warning>

<Note>
  `respcd = 0000` 代表交易成功。\
  其他狀態請依狀態碼文件處理。
</Note>

***

## 補充確認機制

若出現以下情況，建議主動使用 [**交易查詢 API**](/zh-hant/integration/common-api/transaction-enquiry) 補充確認：

* 未收到通知
* 通知延遲
* 簽名驗證失敗
* 系統處理異常

此方式可避免漏單或錯誤入帳。

***

## 測試卡資訊（Sandbox）

以下卡號可於 **測試環境（Sandbox）** 使用，用於模擬各類交易結果（包含 3D Secure）：

| 卡別         | 測試卡號                | 模擬結果          |
| ---------- | ------------------- | ------------- |
| Mastercard | 5200 0000 0000 1096 | 成功付款          |
| Visa       | 4000 0000 0000 1091 | 成功付款          |
| Mastercard | 5200 0000 0000 1005 | 成功（3DS 無干預流程） |
| Visa       | 4000 0000 0000 1000 | 成功（3DS 無干預流程） |
| Mastercard | 5200 0000 0000 1120 | 驗證階段失敗        |
| Visa       | 4000 0000 0000 1125 | 驗證階段失敗        |
| Mastercard | 5200 0000 0000 1013 | 3DS 無干預流程中失敗  |
| Visa       | 4000 0000 0000 1018 | 3DS 無干預流程中失敗  |

<Warning>
  測試卡僅限 Sandbox 環境使用。\
  請勿於正式環境（Production）使用測試卡號。
</Warning>

***

## 小結

* 支援 Visa 與 Mastercard 線上交易
* 提供 Checkout 與 Element 兩種整合方式
* 必須實作 Webhook 與簽名驗證
* 建議搭配交易查詢 API 作為補充保障