PHPackages                             carllee1983/newebpay - 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/newebpay

ActiveLibrary[Payment Processing](/categories/payments)

carllee1983/newebpay
====================

藍新金流 SDK - NewebPay Payment Gateway SDK for PHP

v2.2.2(5mo ago)01[5 PRs](https://github.com/CarlLee1983/newebpay/pulls)MITPHPPHP ^8.3CI passing

Since Nov 28Pushed 3mo agoCompare

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

READMEChangelog (4)Dependencies (7)Versions (19)Used By (0)

藍新金流 PHP SDK
============

[](#藍新金流-php-sdk)

[![PHP Version](https://camo.githubusercontent.com/62aeff98201d8b5641823c0f650139b2e355414fe60cbb72fe705f1c6c55505d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e332d626c7565)](https://www.php.net)[![License](https://camo.githubusercontent.com/5caa455d8debc46fb23abbadb45a733a937f3910a73fc875c2f7820468e1bb54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e)](LICENSE)[![Tests](https://github.com/CarlLee1983/newebpay/actions/workflows/tests.yml/badge.svg)](https://github.com/CarlLee1983/newebpay/actions/workflows/tests.yml)

藍新金流（NewebPay）PHP SDK，提供簡潔易用的 API 整合藍新金流支付服務。

藍新金流 (NewebPay) PHP SDK
=======================

[](#藍新金流-newebpay-php-sdk)

 [![Latest Version](https://camo.githubusercontent.com/0017ae41ef593592fe0715d8de02db2388870b6bd39a477515c217b53ab0597c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6361726c6c6565313938332f6e657765627061793f7374796c653d666c61742d73717561726526636f6c6f723d626c7565)](https://packagist.org/packages/carllee1983/newebpay) [![Total Downloads](https://camo.githubusercontent.com/b47e6016be18701d7eaa93b76980b9089711c46de9f1a070c36c1735317b8eff/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6361726c6c6565313938332f6e657765627061793f7374796c653d666c61742d73717561726526636f6c6f723d677265656e)](https://packagist.org/packages/carllee1983/newebpay) [![License](https://camo.githubusercontent.com/7c32a60870e1c2fb99358bb6986182b32c3e31264bb435f8f5f7c66493634a5e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d707572706c653f7374796c653d666c61742d737175617265)](LICENSE) [![PHP Version](https://camo.githubusercontent.com/09b0f0d0f3012c00366b3c29d1898588e09dce3e70812afe817cf300690b3e8f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344372e342d3737374242343f7374796c653d666c61742d737175617265266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net)

 **專為現代 PHP 開發者打造的藍新金流全方位整合方案**
 優雅的語法 • 完整的 Type Hinting • Laravel 深度整合

---

✨ 核心特色
------

[](#-核心特色)

- 🚀 **全面支援**：涵蓋信用卡、ATM、超商代碼/條碼、LINE Pay、台灣 Pay、Apple Pay 等主流支付。
- 🛡️ **安全可靠**：內建完整的 AES-256-CBC 加解密驗證機制，確保交易安全。
- 💎 **Laravel 整合**：提供 Service Provider 與 Facades，與 Laravel 生態系完美融合。
- 📦 **開箱即用**：簡單直覺的 Fluent API 設計，讓參數設定變得清晰易讀。
- ✅ **品質保證**：高覆蓋率的單元測試 (100+ tests)，確保每次交易都精確無誤。

📋 系統需求與相容性
----------

[](#-系統需求與相容性)

本套件支援 PHP 7.4 及以上版本，並針對各 Laravel 版本進行了最佳化：

Laravel 版本PHP 最低需求支援狀態**Laravel 11.x**PHP 8.2+✅ 完美支援**Laravel 10.x**PHP 8.1+✅ 完美支援**Laravel 9.x**PHP 8.0+✅ 完美支援**Laravel 8.x**PHP 7.4+✅ 完美支援🚀 快速安裝
------

[](#-快速安裝)

使用 Composer 即可輕鬆安裝：

```
composer require carllee1983/newebpay
```

📖 快速上手
------

[](#-快速上手)

我們提供兩種使用風格，您可自由選擇最適合的一種。

### ⚡ 風格一：Laravel Facade (推薦)

[](#-風格一laravel-facade-推薦)

最簡潔的現代化寫法，適合 Laravel 開發者。

**1. 設定環境變數 (.env)**

```
NEWEBPAY_MERCHANT_ID=您的特店編號
NEWEBPAY_HASH_KEY=您的HashKey
NEWEBPAY_HASH_IV=您的HashIV
NEWEBPAY_TEST_MODE=true
NEWEBPAY_RETURN_URL=https://your-site.com/payment/return
NEWEBPAY_NOTIFY_URL=https://your-site.com/payment/notify
```

**2. 建立交易**

```
use CarlLee\NewebPay\Laravel\Facades\NewebPay;

Route::post('/pay', function () {
    return NewebPay::payment(
        'ORDER_' . time(),  // 訂單編號
        1000,               // 金額
        '測試商品',          // 商品描述
        'user@example.com'  // 買家 Email
    )->submit();
});
```

**進階用法 (指定支付方式)**

```
NewebPay::payment($orderNo, $amount, $desc, $email)
    ->creditInstallment([3, 6]) // 僅開放 3, 6 期分期
    ->atm('2025-12-31')         // 指定 ATM 繳費期限
    ->linePay()                 // 啟用 LINE Pay
    ->submit();
```

### 🛠️ 風格二：原生 PHP 物件導向

[](#️-風格二原生-php-物件導向)

適合非 Laravel 專案或需要細膩控制時使用。

```
use CarlLee\NewebPay\Operations\CreditPayment;
use CarlLee\NewebPay\FormBuilder;

// 初始化
$payment = new CreditPayment('MerchantID', 'HashKey', 'HashIV');

// 設定參數
$payment->setTestMode(true)
        ->setMerchantOrderNo('ORDER_' . time())
        ->setAmt(1000)
        ->setItemDesc('商品名稱')
        ->setEmail('buyer@example.com')
        ->setReturnURL('https://site.com/return')
        ->setNotifyURL('https://site.com/notify');

// 產生 HTML 表單並送出
echo FormBuilder::create($payment)->build();
```

💳 支援支付方式一覽
----------

[](#-支援支付方式一覽)

用途類別對應方法備註**信用卡一次付清**`CreditPayment``->creditCard()`預設啟用**信用卡分期**`CreditInstallment``->creditInstallment()`支援 3/6/12/18/24/30 期**WebATM**`WebAtmPayment``->webAtm()`需搭配讀卡機**ATM 轉帳**`AtmPayment``->atm()`產生虛擬帳號**超商代碼**`CvsPayment``->cvs()`Kiosk 操作列印**超商條碼**`BarcodePayment``->barcode()`手機出示條碼**LINE Pay**`LinePayPayment``->linePay()`行動支付**玉山 Wallet**`EsunWalletPayment``->esunWallet()`電子錢包**台灣 Pay**`TaiwanPayPayment``->taiwanPay()`行動支付**BitoPay**`BitoPayPayment``->bitoPay()`加密貨幣支付**超商取貨付款**`CvscomPayment``->cvscom()`物流整合**Fula 付啦**`FulaPayment``->fula()`BNPL 先買後付**TWQR**`TwqrPayment``->twqr()`通用 QR Code**全支付方式**`AllInOnePayment``->allInOne()`一次啟用多種選擇*(完整列表請參閱 [Wiki](wiki_link_here) 或原始碼)*

🔔 處理回調 (Webhook)
----------------

[](#-處理回調-webhook)

當交易狀態變更時，藍新金流會通知您的伺服器。SDK 提供了優雅的封裝來驗證這些請求。

```
use CarlLee\NewebPay\Notifications\PaymentNotify;

$notify = new PaymentNotify('HashKey', 'HashIV');

try {
    // 1. 自動驗證簽章與解密 (若驗證失敗會拋出例外)
    $data = $notify->verifyOrFail($_POST);

    // 2. 判斷交易結果
    if ($notify->isSuccess()) {
        // 交易成功！
        $orderId = $notify->getMerchantOrderNo();
        $amount = $notify->getAmt();

        // TODO: 更新資料庫訂單狀態...
    } else {
        // 交易失敗 (刷卡失敗、餘額不足等)
    }

} catch (\Exception $e) {
    // 簽章驗證失敗，可能是偽造的請求
    Log::error('Payment notify verification failed: ' . $e->getMessage());
}
```

📢 事件監聽 (Events)
---------------

[](#-事件監聽-events)

在 Laravel 應用程式中，您也可以透過監聽事件來處理支付結果，讓程式碼更乾淨解耦。

**1. 定義監聽器**

```
namespace App\Listeners;

use CarlLee\NewebPay\Laravel\Events\PaymentReceived;

class HandlePaymentReceived
{
    public function handle(PaymentReceived $event)
    {
        $notify = $event->notify;

        if ($notify->isSuccess()) {
            // 處理付款成功邏輯
            $orderId = $notify->getMerchantOrderNo();
            // ...
        }
    }
}
```

**2. 註冊監聽器 (EventServiceProvider)**

```
protected $listen = [
    \CarlLee\NewebPay\Laravel\Events\PaymentReceived::class => [
        \App\Listeners\HandlePaymentReceived::class,
    ],
];
```

🧪 測試 (Testing)
--------------

[](#-測試-testing)

我們提供了 `NewebPay::fake()` 讓您在測試中輕鬆模擬支付請求，無需實際發送 HTTP 請求。

```
use CarlLee\NewebPay\Laravel\Facades\NewebPay;

public function test_payment_flow()
{
    // 1. 啟用模擬模式
    NewebPay::fake();

    // 2. 執行您的程式碼
    $this->post('/checkout');

    // 3. 驗證是否建立了正確的支付請求
    NewebPay::assertSent(function ($payment) {
        return $payment->get('Amt') === 1000 &&
               $payment->get('Email') === 'buyer@example.com';
    });
}
```

🔎 交易查詢與退款
---------

[](#-交易查詢與退款)

**查詢訂單**

```
use CarlLee\NewebPay\Queries\QueryOrder;

$result = QueryOrder::create($id, $key, $iv)
    ->query('ORDER_NO_12345', 1000); // 需帶入訂單編號與金額

echo $result['TradeStatus']; // 1=成功, 0=未付款...
```

**信用卡退款**

```
use CarlLee\NewebPay\Actions\CreditClose;

CreditClose::create($id, $key, $iv)
    ->refund('ORDER_NO_12345', 1000); // 全額退款
```

💻 前後端分離整合 (Vue / React)
-----------------------

[](#-前後端分離整合-vue--react)

由於藍新金流需要 `Form Post` 跳轉，在 SPA (Single Page Application) 中，建議由後端產生 API 回傳表單參數，前端再動態建立表單提交。

**後端 (Laravel Example)**

```
public function checkout() {
    $payment = NewebPay::credit()->...; // 設定參數

    return response()->json([
        'url' => $payment->getApiUrl(),
        'fields' => $payment->getContent() // 取得所有加密後的隱藏欄位
    ]);
}
```

**前端 (Javascript Example)**

```
// 取得後端參數後...
const form = document.createElement('form');
form.method = 'POST';
form.action = response.url;

for (const [key, value] of Object.entries(response.fields)) {
    const input = document.createElement('input');
    input.type = 'hidden';
    input.name = key;
    input.value = value;
    form.appendChild(input);
}

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

🐳 Docker 開發環境
-------------

[](#-docker-開發環境)

為了確保環境一致性，我們提供了完整的 Docker 開發環境配置。

```
make build           # 建構環境
make composer-install # 安裝套件
make test            # 執行測試
```

📄 授權協議
------

[](#-授權協議)

本專案採用 **MIT License** 開源授權，您可以安心使用於商業專案中。

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance77

Regular maintenance activity

Popularity1

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.8% 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

Every ~1 days

Total

12

Last Release

163d ago

Major Versions

v1.0.0 → v2.0.02025-11-28

v1.0.1 → v2.0.22025-11-28

v1.1.0 → v2.2.02025-12-05

1.x-dev → v2.2.12025-12-05

PHP version history (2 changes)v1.0.0PHP ^7.4|^8.0

v2.0.0PHP ^8.3

### 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 (28 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")

---

Tags

laravelsdkpaymentgatewaycvsTaiwancredit-cardnewebpayatm

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

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

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

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