carllee1983/ecpay-payment

綠界全方位金流 SDK - ECPay Payment Gateway SDK

Maintainers

Details

github.com/CarlLee1983/ecpay-payment

Homepage

Source

Issues

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/carllee1983/ecpay-payment

v1.0.0 2025-11-27 05:02 UTC

Requires

Requires (Dev)

MIT 521017b720489cbc9792d380eab2be5b2f1079e6

  • Carl Lee <carllee0520.woop@gmail.com>

paymentsdkgatewaylaravelcvsTaiwancredit-cardecpayatm

This package is auto-updated.

Last update: 2025-11-27 05:05:12 UTC

README

綠界全方位金流 PHP SDK

安裝

composer require carllee1983/ecpay-payment

環境需求

  • PHP 8.3+
  • OpenSSL 擴展
  • JSON 擴展
  • TLS 1.2 支援（綠界僅支援 TLS 1.2 加密通訊協定）

重要注意事項

安全性警告

  • 請勿將 HashKey/HashIV 存放或顯示於前端網頁（如 JavaScript、HTML、CSS），避免金鑰被盜取造成損失及資料外洩
  • 務必透過環境變數或設定檔管理金鑰，確保不納入版本控制
  • 平台商身分請使用 PlatformID 配對的 HashKey/HashIV 產生 CheckMacValue

API 呼叫注意事項

  • 所有 API 使用 HTTP POST 方式傳送
  • 參數值不允許使用 HTML tag（如 <br>、<h1>）
  • 傳輸參數不支援特殊符號
  • 參數內容若有包含 %26(&) 及 %3C(<) 時，請先進行 urldecode() 避免呼叫 API 失敗
  • 請進行主機時間校正，避免時差導致 API 無法正常運作
  • API 呼叫速度過快會收到 HTTP 403，請降低呼叫頻率並等候 30 分鐘後重試

ReturnURL 設定

  • ReturnURL 為 Server 端 URL，用於接收綠界後端回傳的付款結果
  • 請確認 ReturnURL 已開放對外連線
  • 僅支援 HTTP/HTTPS（80/443 port），指定其他 port 將無法接收通知
  • 不支援中文網址，請使用 punycode 編碼
  • 收到通知後必須驗證 CheckMacValue 並回傳 1|OK

防火牆設定

如需設定防火牆連線至綠界主機：

環境 Domain Port
正式環境 payment.ecpay.com.tw TCP 443
測試環境 payment-stage.ecpay.com.tw TCP 443

如需允許綠界連入：

環境 Domain Port
正式環境 postgate.ecpay.com.tw TCP 443
測試環境 postgate-stage.ecpay.com.tw TCP 443

支援的付款方式

付款操作 (Operations)

類別 別名 說明
AllInOne all_in_one 全方位金流
CreditPayment credit_payment 信用卡一次付清
CreditInstallment credit_installment 信用卡分期付款
CreditRecurring credit_recurring 信用卡定期定額
AtmPayment atm_payment ATM 虛擬帳號
CvsPayment cvs_payment 超商代碼
BarcodePayment barcode_payment 超商條碼
WebAtmPayment web_atm_payment 網路 ATM
ApplePayPayment apple_pay_payment Apple Pay
TwqrPayment twqr_payment TWQR 行動支付
BnplPayment bnpl_payment 無卡分期 (BNPL)
WechatPayment wechat_payment 微信支付
EcPayPayPayment ec_pay_pay_payment 綠界 PAY

信用卡操作 (Actions)

類別 別名 說明
CreditAction actions.credit_action 請款/退款/取消授權

查詢操作 (Queries)

類別 別名 說明
QueryOrder queries.query_order 查詢訂單
QueryCreditDetail queries.query_credit_detail 信用卡明細查詢
QueryRecurringOrder queries.query_recurring_order 定期定額訂單查詢
DownloadMerchantBalance queries.download_merchant_balance 下載對帳檔
DownloadCreditBalance queries.download_credit_balance 下載信用卡撥款對帳檔

通知處理 (Notifications)

類別 說明
PaymentNotify 付款結果通知
AtmNotify ATM/CVS/BARCODE 取號通知
RecurringNotify 定期定額扣款通知

設定

環境變數

ECPAY_PAYMENT_SERVER=https://payment-stage.ecpay.com.tw
ECPAY_PAYMENT_MERCHANT_ID=your_merchant_id
ECPAY_PAYMENT_HASH_KEY=your_hash_key
ECPAY_PAYMENT_HASH_IV=your_hash_iv
ECPAY_PAYMENT_RETURN_URL=https://your-domain.com/payment/callback

Laravel 整合

發布設定檔：

php artisan vendor:publish --provider="CarlLee\EcPayPayment\Laravel\EcPayPaymentServiceProvider"

基本用法

信用卡一次付清

use CarlLee\EcPayPayment\Factories\OperationFactory;
use CarlLee\EcPayPayment\FormBuilder;

$factory = new OperationFactory([
    'merchant_id' => 'your_merchant_id',
    'hash_key' => 'your_hash_key',
    'hash_iv' => 'your_hash_iv',
]);

$payment = $factory->make('credit_payment')
    ->setMerchantTradeNo('ORDER_' . time())
    ->setTotalAmount(1000)
    ->setTradeDesc('測試訂單')
    ->setItemName('商品名稱')
    ->setReturnURL('https://your-domain.com/callback');

$formBuilder = new FormBuilder('https://payment-stage.ecpay.com.tw');
echo $formBuilder->autoSubmit($payment);

整合模式

綠界金流 API 需要透過瀏覽器 POST 導向綠界付款頁面（消費者需在綠界頁面輸入卡號、進行 3D 驗證等）。以下是常見的整合模式：

模式一：後端直接返回自動提交表單

適用於傳統表單提交的網站。

// 後端 Controller
public function createPayment(Request $request)
{
    $factory = new OperationFactory([
        'merchant_id' => config('ecpay.merchant_id'),
        'hash_key' => config('ecpay.hash_key'),
        'hash_iv' => config('ecpay.hash_iv'),
    ]);
    
    $payment = $factory->make('credit_payment')
        ->setMerchantTradeNo($request->order_id)
        ->setTotalAmount($request->amount)
        ->setTradeDesc($request->description)
        ->setItemName($request->items)
        ->setReturnURL(route('payment.callback'));
    
    $formBuilder = new FormBuilder(config('ecpay.server'));
    
    // 返回自動提交的 HTML，瀏覽器會自動 POST 到綠界
    return response($formBuilder->autoSubmit($payment));
}

模式二：API 返回 JSON 給前端

適用於 SPA（Vue/React）或 AJAX 互動的網站。

後端 API：

// 後端 Controller
public function createPayment(Request $request)
{
    $factory = new OperationFactory([...]);
    
    $payment = $factory->make('credit_payment')
        ->setMerchantTradeNo($request->order_id)
        ->setTotalAmount($request->amount)
        ->setTradeDesc($request->description)
        ->setItemName($request->items)
        ->setReturnURL(route('payment.callback'));
    
    $formBuilder = new FormBuilder(config('ecpay.server'));
    
    // 返回 JSON 給前端
    return response()->json([
        'success' => true,
        'data' => [
            'action' => $formBuilder->getActionUrl($payment),
            'fields' => $formBuilder->getFields($payment),
        ],
    ]);
}

前端 JavaScript：

async function createPayment(orderData) {
    const response = await fetch('/api/payment', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(orderData)
    });

    const result = await response.json();

    if (result.success) {
        // 動態建立表單並提交到綠界
        const form = document.createElement('form');
        form.method = 'POST';
        form.action = result.data.action;

        Object.entries(result.data.fields).forEach(([name, value]) => {
            const input = document.createElement('input');
            input.type = 'hidden';
            input.name = name;
            input.value = value;
            form.appendChild(input);
        });

        document.body.appendChild(form);
        form.submit();
    }
}

FormBuilder 方法說明

方法 說明
autoSubmit($payment) 產生自動提交的完整 HTML 頁面
build($payment) 產生含提交按鈕的 HTML 表單
getFields($payment) 取得表單欄位陣列（含 CheckMacValue）
getActionUrl($payment) 取得表單 Action URL
toJson($payment) 取得 JSON 格式的表單資料

⚠️ 注意：綠界的 AioCheckOut API 必須透過瀏覽器導向，無法使用純後端 Server-to-Server POST（因為消費者需要在綠界頁面進行付款操作）。查詢類 API（如 QueryOrder、CreditAction）則可使用 Server-to-Server。

信用卡定期定額

$payment = $factory->make('credit_recurring')
    ->setMerchantTradeNo('REC_' . time())
    ->setTotalAmount(299)
    ->setTradeDesc('月費訂閱')
    ->setItemName('進階會員月費')
    ->setReturnURL('https://your-domain.com/callback')
    ->monthly(299, 12) // 每月 299 元，共 12 期
    ->setPeriodReturnURL('https://your-domain.com/period-callback');

信用卡請款/退款

// 請款
$action = $factory->make('actions.credit_action')
    ->setMerchantTradeNo('ORDER123')
    ->setTradeNo('ECPAY123456')
    ->capture(1000);

// 退款
$action = $factory->make('actions.credit_action')
    ->setMerchantTradeNo('ORDER123')
    ->setTradeNo('ECPAY123456')
    ->refund(500);

// 取消授權
$action = $factory->make('actions.credit_action')
    ->setMerchantTradeNo('ORDER123')
    ->setTradeNo('ECPAY123456')
    ->cancel(1000);

處理付款通知

use CarlLee\EcPayPayment\Notifications\PaymentNotify;

$notify = new PaymentNotify($hashKey, $hashIV);

if ($notify->verify($_POST)) {
    if ($notify->isSuccess()) {
        $tradeNo = $notify->getMerchantTradeNo();
        // 更新訂單狀態
    }
    
    // 重要：必須回傳 1|OK 給綠界
    echo $notify->getSuccessResponse(); // 1|OK
}

下載對帳檔

$query = $factory->make('queries.download_merchant_balance')
    ->setBeginDate('2024-01-01')
    ->setEndDate('2024-01-31')
    ->byPaymentDate();

範例檔案

完整的範例程式碼請參考 examples/ 目錄：

檔案 說明
all_in_one.php 全方位金流範例
credit_payment.php 信用卡一次付清
credit_installment.php 信用卡分期
credit_recurring.php 信用卡定期定額
credit_action.php 信用卡請款/退款
atm_payment.php ATM 虛擬帳號
cvs_payment.php 超商代碼
barcode_payment.php 超商條碼
backend_redirect.php 後端接收請求後自動導向
api_payment.php API 返回 JSON 給前端
payment_callback.php 付款結果通知處理
query_order.php 查詢訂單

測試環境資訊

項目 值
測試環境網址 https://payment-stage.ecpay.com.tw
特店編號 3002607
HashKey pwFHCqoQZGmho4w6
HashIV EkRm7iFT261dpevs
測試信用卡號 4311-9522-2222-2222
信用卡安全碼 任意三碼數字
有效月/年 大於當前日期

參考：綠界全方位金流 API 技術文件

相關資源

授權

MIT License