PHPackages                             carllee1983/ecpay-payment - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. carllee1983/ecpay-payment

ActiveLibrary[Payment Processing](/categories/payments)

carllee1983/ecpay-payment
=========================

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

v1.0.0(5mo ago)00MITPHPPHP ^8.3

Since Nov 27Pushed 5mo agoCompare

[ Source](https://github.com/CarlLee1983/ecpay-payment)[ Packagist](https://packagist.org/packages/carllee1983/ecpay-payment)[ Docs](https://github.com/CarlLee1983/ecpay-payment)[ RSS](/packages/carllee1983-ecpay-payment/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (6)Versions (2)Used By (0)

ECPay Payment SDK
=================

[](#ecpay-payment-sdk)

綠界全方位金流 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-呼叫注意事項)

- 所有 API 使用 **HTTP POST** 方式傳送
- 參數值**不允許使用 HTML tag**（如 ``、``）
- 傳輸參數**不支援特殊符號**
- 參數內容若有包含 `%26(&)` 及 `%3C( '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 給前端

[](#模式二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 方法說明

[](#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`查詢訂單測試環境資訊
------

[](#測試環境資訊)

項目值測試環境網址特店編號3002607HashKeypwFHCqoQZGmho4w6HashIVEkRm7iFT261dpevs測試信用卡號4311-9522-2222-2222信用卡安全碼任意三碼數字有效月/年大於當前日期> 參考：[綠界全方位金流 API 技術文件](https://developers.ecpay.com.tw/?p=2856)

相關資源
----

[](#相關資源)

- [綠界 API 介接注意事項](https://developers.ecpay.com.tw/?p=2858)
- [綠界測試環境介接資訊](https://developers.ecpay.com.tw/?p=2856)
- [綠界特店管理後台（測試）](https://vendor-stage.ecpay.com.tw/)

授權
--

[](#授權)

MIT License

###  Health Score

35

—

LowBetter than 79% of packages

Maintenance76

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

163d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6cc3f5bb28af8b207b65843e86f3b3e9feb1efd05b8ba888e1fa223a370ab822?d=identicon)[Carl Lee](/maintainers/Carl%20Lee)

---

Top Contributors

[![CarlLee1983](https://avatars.githubusercontent.com/u/8252510?v=4)](https://github.com/CarlLee1983 "CarlLee1983 (2 commits)")

---

Tags

laravelsdkpaymentgatewaycvsTaiwancredit-cardecpayatm

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/carllee1983-ecpay-payment/health.svg)

```
[![Health](https://phpackages.com/badges/carllee1983-ecpay-payment/health.svg)](https://phpackages.com/packages/carllee1983-ecpay-payment)
```

###  Alternatives

[lokielse/omnipay-unionpay

UnionPay gateway for Omnipay payment processing library

11358.1k2](/packages/lokielse-omnipay-unionpay)[sebdesign/laravel-viva-payments

A Laravel package for integrating the Viva Payments gateway

4845.9k](/packages/sebdesign-laravel-viva-payments)[evryn/laravel-toman

A simple stable Laravel package to handle popular payment gateways in Iran including ZarinPal and IDPay.

1079.9k](/packages/evryn-laravel-toman)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)