MXP CF7 Taiwan Payment

Contact Form 7 藍新金流（NewebPay）整合外掛

簡介

此外掛為 Contact Form 7 的 Add-on，讓表單能夠整合台灣藍新金流付款功能，並提供完整的訂單管理機制。

功能特色

• 與 Contact Form 7 無縫整合
• 支援多種付款方式（信用卡、ATM、超商、WebATM、LINE Pay、台灣 Pay）
• 完整訂單管理後台
• 自動付款提醒與訂單過期處理
• 統計報表與 CSV 匯出
• 響應式前台頁面設計
• 支援主題模板覆寫

系統需求

• WordPress 5.0 或更高版本
• PHP 7.4 或更高版本
• Contact Form 7 外掛
• 藍新金流商店帳號

安裝方式

1. 上傳外掛資料夾至 /wp-content/plugins/ 目錄
2. 在 WordPress 後台「外掛」頁面啟用外掛
3. 前往「設定 → 藍新金流」設定 API 金鑰

設定說明

1. 全域設定

前往「設定 → 藍新金流」設定以下項目：

API 設定

• 商店代號 (MerchantID)
• HashKey
• HashIV
• 環境切換（測試/正式）

付款方式

• 信用卡（支援分期）
• ATM 虛擬帳號
• 超商代碼繳費
• WebATM
• LINE Pay
• 台灣 Pay

通知設定

• 付款成功通知
• 逾期提醒
• Email 模板

2. 表單設定

在 Contact Form 7 表單編輯頁面，點選「藍新付款」分頁：

1. 勾選「啟用藍新付款」
2. 設定金額（固定金額或從欄位計算）
3. 設定商品描述
4. 對應付款人欄位（姓名、Email、電話）
5. 設定繳費期限

付款流程

用戶填寫表單 → 送出表單
      ↓
顯示付款確認頁（訂單編號、金額）
      ↓
點擊「前往付款」
      ↓
跳轉藍新金流付款頁面
      ↓
付款完成 → 顯示結果頁面

訂單管理

訂單列表

• 狀態篩選（待付款/已付款/已過期/已退款）
• 關鍵字搜尋
• 表單篩選
• 日期區間篩選
• CSV 匯出

訂單狀態

狀態	說明
pending	待付款
paid	已付款
failed	付款失敗
expired	已過期
refunded	已退款
cancelled	已取消

統計報表

• 訂單總數與營收總覽
• 依表單統計
• 依付款方式統計
• 每日趨勢圖

主題覆寫

可在主題目錄建立 mxp-cf7-newebpay/ 資料夾覆寫前台模板：

your-theme/
└── mxp-cf7-newebpay/
    ├── payment-confirm.php  # 付款確認頁
    ├── payment-result.php   # 付款結果頁
    └── payment-info.php     # ATM/超商繳費資訊頁

Hook 擴展

Filters

// 修改交易資訊
add_filter( 'mxp_cf7_newebpay_trade_info', function( $trade_info, $order ) {
    return $trade_info;
}, 10, 2 );

// 修改金額
add_filter( 'mxp_cf7_newebpay_amount', function( $amount, $form_data ) {
    return $amount;
}, 10, 2 );

// 修改商品描述
add_filter( 'mxp_cf7_newebpay_item_desc', function( $desc, $form_data ) {
    return $desc;
}, 10, 2 );

// 修改 Email 內容
add_filter( 'mxp_cf7_newebpay_email_content', function( $content, $order ) {
    return $content;
}, 10, 2 );

// 修改付款頁面 HTML
add_filter( 'mxp_cf7_newebpay_payment_page_html', function( $html, $order ) {
    return $html;
}, 10, 2 );

Actions

// 訂單建立後
add_action( 'mxp_cf7_newebpay_order_created', function( $order ) {
    // 自訂處理
}, 10, 1 );

// 付款成功
add_action( 'mxp_cf7_newebpay_payment_success', function( $order, $response ) {
    // 自訂處理
}, 10, 2 );

// 付款失敗
add_action( 'mxp_cf7_newebpay_payment_failed', function( $order, $response ) {
    // 自訂處理
}, 10, 2 );

// 訂單過期
add_action( 'mxp_cf7_newebpay_order_expired', function( $order ) {
    // 自訂處理
}, 10, 1 );

// 退款處理
add_action( 'mxp_cf7_newebpay_order_refunded', function( $order ) {
    // 自訂處理
}, 10, 1 );

// 提醒信發送
add_action( 'mxp_cf7_newebpay_reminder_sent', function( $order ) {
    // 自訂處理
}, 10, 1 );

檔案結構

mxp-cf7-twpayment/
├── mxp-cf7-twpayment.php      # 主檔案
├── includes/
│   ├── class-loader.php        # 載入器
│   ├── class-activator.php     # 啟用處理
│   ├── class-deactivator.php   # 停用處理
│   ├── class-newebpay-api.php  # 藍新 API
│   ├── class-order-manager.php # 訂單管理
│   ├── class-payment-handler.php # 付款處理
│   ├── class-notification.php  # 通知
│   ├── class-cron.php          # 排程
│   └── class-bank-codes.php    # 銀行代碼
├── admin/
│   ├── class-admin.php         # 後台主控制
│   ├── class-settings-page.php # 設定頁
│   ├── class-cf7-integration.php # CF7 整合
│   ├── class-order-list-table.php # 訂單列表
│   ├── class-reports-page.php  # 報表頁
│   └── views/                  # 後台模板
├── public/
│   ├── class-public.php        # 前台控制
│   ├── class-form-handler.php  # 表單處理
│   └── views/                  # 前台模板
├── assets/
│   ├── css/
│   │   ├── admin.css
│   │   └── public.css
│   └── js/
│       ├── admin.js
│       └── public.js
└── languages/                  # 語系檔

常見問題

Q: 付款後沒有收到通知？

A: 請確認：

1. NotifyURL 是否可被藍新伺服器存取
2. SSL 憑證是否有效
3. 檢查 WordPress 排程是否正常運作

Q: 測試環境如何使用？

A: 在「設定 → 藍新金流」將環境切換為「測試環境」，並使用藍新提供的測試商店代號。

Q: 如何自訂 Email 模板？

A: 在「設定 → 藍新金流 → 通知設定」編輯 Email 模板，支援以下變數：

• {order_no} - 訂單編號
• {amount} - 金額
• {payer_name} - 付款人姓名
• {item_desc} - 商品描述
• {payment_url} - 付款連結
• {site_name} - 網站名稱

Q: ATM 虛擬帳號如何顯示？

A: 選擇 ATM 付款後，系統會自動導向繳費資訊頁面，顯示銀行代碼與虛擬帳號。

更新紀錄

1.0.0

• 初始版本
• 完整付款流程
• 訂單管理後台
• 統計報表
• Email 通知
• 排程處理

授權

GPL v2 or later

作者

MXP - https://mxp.tw

支援

如有問題或建議，請至 GitHub Issues 回報： https://github.com/nczz/mxp-cf7-twpayment/issues