PHPackages                             ycs77/laravel-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. [API Development](/categories/api)
4. /
5. ycs77/laravel-newebpay

ActiveLibrary[API Development](/categories/api)

ycs77/laravel-newebpay
======================

A library of connecting newebpay's API service.

v1.0.0(1y ago)3211.2k↓32.8%18MITPHPPHP >=8.1CI passing

Since May 11Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/ycs77/laravel-newebpay)[ Packagist](https://packagist.org/packages/ycs77/laravel-newebpay)[ Docs](https://github.com/ycs77/laravel-newebpay)[ Patreon](https://www.patreon.com/ycs77)[ RSS](/packages/ycs77-laravel-newebpay/feed)WikiDiscussions 2.x Synced 2w ago

READMEChangelog (10)Dependencies (9)Versions (19)Used By (0)

Laravel NewebPay - 藍新金流
=======================

[](#laravel-newebpay---藍新金流)

> Fork from [treerful/laravel-newebpay](https://bitbucket.org/pickone/laravel-newebpay)

[![Latest Version on Packagist](https://camo.githubusercontent.com/acad726caecfc473f9722b12d6cc9373fed67e175d08eedd22d487e4a3d57b8f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f79637337372f6c61726176656c2d6e657765627061793f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ycs77/laravel-newebpay)[![Software License](https://camo.githubusercontent.com/c090e080484e2a2bc766446291d04437db823929042bf614b26a1643660ddf6f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e3f7374796c653d666c61742d737175617265)](LICENSE)[![GitHub Tests Action Status](https://camo.githubusercontent.com/58401ef1b390e4eadc4f8611f92876f98240db10e008df275068269eb6b9d6e1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f79637337372f6c61726176656c2d6e657765627061792f74657374732e796d6c3f6272616e63683d322e78266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/ycs77/laravel-newebpay/actions/workflows/tests.yml?query=branch%3A2.x)[![Total Downloads](https://camo.githubusercontent.com/34f9ee5fe6f25041e0e457476250e5f765fe7913385c9c0fa8eeb2a72aa6cddb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f79637337372f6c61726176656c2d6e657765627061793f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ycs77/laravel-newebpay)

**Laravel NewebPay** 為針對 Laravel 所寫的藍新金流（智付通）金流串接套件。

### 套件功能

[](#套件功能)

- 💳 MPG 多功能收款 API
- 🔍 交易查詢 API
- 🚫 信用卡取消授權 API
- 💸 信用卡請退款 API
- 🔁 信用卡定期定額委託 API

目錄
--

[](#目錄)

- [版本需求](#%E7%89%88%E6%9C%AC%E9%9C%80%E6%B1%82)
- [安裝](#%E5%AE%89%E8%A3%9D)
- [設定](#%E8%A8%AD%E5%AE%9A)
- [測試信用卡號](#%E6%B8%AC%E8%A9%A6%E4%BF%A1%E7%94%A8%E5%8D%A1%E8%99%9F)
- [MPG 多功能付款](#mpg-%E5%A4%9A%E5%8A%9F%E8%83%BD%E4%BB%98%E6%AC%BE)
    - [快速開始](#%E5%BF%AB%E9%80%9F%E9%96%8B%E5%A7%8B)
    - [付款方式](#%E4%BB%98%E6%AC%BE%E6%96%B9%E5%BC%8F)
    - [接收付款結果](#%E6%8E%A5%E6%94%B6%E4%BB%98%E6%AC%BE%E7%B5%90%E6%9E%9C)
    - [取得付款結果的詳細資訊](#%E5%8F%96%E5%BE%97%E4%BB%98%E6%AC%BE%E7%B5%90%E6%9E%9C%E7%9A%84%E8%A9%B3%E7%B4%B0%E8%B3%87%E8%A8%8A)
    - [ATM/超商取號](#atm%E8%B6%85%E5%95%86%E5%8F%96%E8%99%9F)
- [查詢交易詳情](#%E6%9F%A5%E8%A9%A2%E4%BA%A4%E6%98%93%E8%A9%B3%E6%83%85)
- [信用卡取消授權](#%E4%BF%A1%E7%94%A8%E5%8D%A1%E5%8F%96%E6%B6%88%E6%8E%88%E6%AC%8A)
- [信用卡請退款](#%E4%BF%A1%E7%94%A8%E5%8D%A1%E8%AB%8B%E9%80%80%E6%AC%BE)
    - [信用卡請款](#%E4%BF%A1%E7%94%A8%E5%8D%A1%E8%AB%8B%E6%AC%BE)
    - [信用卡退款](#%E4%BF%A1%E7%94%A8%E5%8D%A1%E9%80%80%E6%AC%BE)
- [信用卡定期定額委託](#%E4%BF%A1%E7%94%A8%E5%8D%A1%E5%AE%9A%E6%9C%9F%E5%AE%9A%E9%A1%8D%E5%A7%94%E8%A8%97)
    - [建立委託](#%E5%BB%BA%E7%AB%8B%E5%A7%94%E8%A8%97)
    - [授權週期](#%E6%8E%88%E6%AC%8A%E9%80%B1%E6%9C%9F)
    - [授權期數](#%E6%8E%88%E6%AC%8A%E6%9C%9F%E6%95%B8)
    - [授權起始方式](#%E6%8E%88%E6%AC%8A%E8%B5%B7%E5%A7%8B%E6%96%B9%E5%BC%8F)
    - [接收委託結果](#%E6%8E%A5%E6%94%B6%E5%A7%94%E8%A8%97%E7%B5%90%E6%9E%9C)
    - [修改委託狀態](#%E4%BF%AE%E6%94%B9%E5%A7%94%E8%A8%97%E7%8B%80%E6%85%8B)
    - [修改委託內容](#%E4%BF%AE%E6%94%B9%E5%A7%94%E8%A8%97%E5%85%A7%E5%AE%B9)
- [錯誤處理](#%E9%8C%AF%E8%AA%A4%E8%99%95%E7%90%86)
- [單元測試](#%E5%96%AE%E5%85%83%E6%B8%AC%E8%A9%A6)
- [除錯支援](#%E9%99%A4%E9%8C%AF%E6%94%AF%E6%8F%B4)
- [參考](#%E5%8F%83%E8%80%83)
- [贊助](#%E8%B4%8A%E5%8A%A9)
- [License](#license)

版本需求
----

[](#版本需求)

版本PHP 版本Laravel 版本1.x>=8.1>=9.x2.x>=8.1>=9.x安裝
--

[](#安裝)

使用 Composer 安裝套件：

```
composer require ycs77/laravel-newebpay
```

發布設置檔案：

```
php artisan vendor:publish --tag=newebpay-config
```

設定
--

[](#設定)

前往藍新金流的網站上註冊帳號（測試時需註冊測試帳號）和建立商店。然後在「商店資料設定」中啟用需要使用的金流功能（測試時可以盡量全部啟用），並複製商店串接 API 的商店代號、`HashKey` 和 `HashIV`。

設定 `.env` 的商店代號和 HashKey 等參數：

```
NEWEBPAY_ENV=test            # 設定 API 運行環境 (production 或 test)
NEWEBPAY_MERCHANT_ID=...        # 貼上 商店代號 (Ex: MS3311...)
NEWEBPAY_MERCHANT_HASH_KEY=...  # 貼上 HashKey
NEWEBPAY_MERCHANT_HASH_IV=...   # 貼上 HashIV
```

`NEWEBPAY_ENV` 可以設定為 `test`（測試環境）或 `production`（正式環境）。

測試信用卡號
------

[](#測試信用卡號)

測試環境僅接受以下的測試信用卡號：

- 4000-2211-1111-1111 (一次付清+分期付款)
- 4003-5511-1111-1111 (紅利折抵)

測試卡號有效月年及卡片背面末三碼，可任意填寫。

MPG 多功能付款
---------

[](#mpg-多功能付款)

### 快速開始

[](#快速開始)

首先建立一個含有表單的頁面，讓用戶點擊「付款」按鈕後送出 POST 請求：

*resources/views/pay.blade.php*

```

    @csrf
    付款

```

Inertia.js 可以參考以下：

*resources/js/pages/Pay.vue*

```

    付款

defineProps()

```

然後設定路由來發送 MPG 多功能付款請求。付款方式預設全部關閉，這裡以最常見的信用卡付款為例，用 `withCredit()` 顯式啟用：

```
use Ycs77\NewebPay\Facades\NewebPay;

Route::post('/pay', function () {
    return NewebPay::payment()
        ->withOrder('Vanespl_ec_'.time())  // 訂單編號
        ->withAmount(120)                  // 交易金額
        ->withItemDescription('我的商品')   // 商品名稱
        ->withEmail('test@example.com')    // 付款人信箱
        ->withCredit()                     // 啟用信用卡付款
        ->withReturnUrl('/pay/callback')   // 前景回傳網址 (Callback)
        ->withNotifyUrl('/pay/notify')     // 背景通知網址 (Notify)
        ->submit();
});
```

付款完成後，藍新金流會將結果回傳到指定的網址。信用卡之類可以直接跳轉回網站的付款方式，設定 callback：

```
use Illuminate\Http\Request;
use Ycs77\NewebPay\Facades\NewebPay;

Route::post('/pay/callback', function (Request $request) {
    $result = NewebPay::result($request);

    if ($result->isFail()) {
        return redirect()
            ->to('/pay')
            ->with('error', $result->message());
    }

    // 訂單付款成功，處理訂單邏輯...

    return redirect()
        ->to('/pay')
        ->with('success', '付款成功');
});
```

還要把這個路徑在 `app/Http/Middleware/VerifyCsrfToken.php` 中排除 CSRF 檢查：

```
class VerifyCsrfToken extends Middleware
{
    protected $except = [
        '/pay/callback',
        '/pay/notify',
    ];
}
```

這樣就完成一個最基本的信用卡付款流程了。想開啟更多付款方式，請參考[付款方式](#%E4%BB%98%E6%AC%BE%E6%96%B9%E5%BC%8F)；callback 與 notify 的完整設定，請參考[接收付款結果](#%E6%8E%A5%E6%94%B6%E4%BB%98%E6%AC%BE%E7%B5%90%E6%9E%9C)。

### 付款方式

[](#付款方式)

可依需要啟用信用卡、WebATM／ATM、國民旅遊卡、行動支付、簡單付、超商代碼／條碼等多種付款方式，以下分別說明各自的設定方式。

#### 信用卡

[](#信用卡)

信用卡可搭配紅利折抵與分期付款：

```
use Ycs77\NewebPay\Enums\CreditInst;

NewebPay::payment()
    ...
    ->withCredit()                                       // 一次付清
    ->withCredit(red: true)                              // 啟用紅利折抵
    ->withCredit(inst: [CreditInst::P3, CreditInst::P6]) // 分期付款：3、6 期
    ->submit();
```

分期參數 `inst` 可傳單一 `CreditInst` 或陣列，選項如下：

選項說明`CreditInst::NONE`不啟用分期（預設）`CreditInst::ALL`啟用全部分期`CreditInst::P3`分 3 期`CreditInst::P6`分 6 期`CreditInst::P12`分 12 期`CreditInst::P18`分 18 期`CreditInst::P24`分 24 期#### 信用卡記憶卡號

[](#信用卡記憶卡號)

啟用信用卡記憶卡號功能，傳入付款人名稱：

```
NewebPay::payment()
    ...
    ->withCreditRemember('John Doe')
    ->submit();
```

#### WebATM／ATM 轉帳

[](#webatmatm-轉帳)

```
NewebPay::payment()
    ...
    ->withWebAtm()      // WebATM
    ->withAtmTransfer() // ATM 轉帳
    ->submit();
```

WebATM 與 ATM 轉帳可用 `withBank()` 指定顯示於付款頁上的轉帳銀行（此參數為兩者共用，無法個別分開指定），可傳單一 `Bank` 或陣列：

```
use Ycs77\NewebPay\Enums\Bank;

NewebPay::payment()
    ...
    ->withAtmTransfer()
    ->withBank([Bank::BOT, Bank::HNCB]) // 台灣銀行、華南銀行
    ->submit();
```

可用的銀行有 `Bank::BOT`（台灣銀行）、`Bank::HNCB`（華南銀行）、`Bank::FirstBank`（第一銀行）。若未設定，預設會顯示所有銀行選項。

Note

每日 00:00~01:00 為第一銀行例行維護時間，此區間內不會顯示第一銀行選項；若此時僅指定第一銀行一家，將回應 `MPG01027` 錯誤代碼。

#### 國民旅遊卡

[](#國民旅遊卡)

傳入旅遊地區與起訖日期：

```
use Ycs77\NewebPay\Enums\NTCBLocate;

NewebPay::payment()
    ...
    ->withNationalTravelCard(NTCBLocate::HsinchuCity, '2020-01-01', '2020-12-31')
    ->submit();
```

旅遊地區可使用的選項請參考 `\Ycs77\NewebPay\Enums\NTCBLocate` 類別。

#### 行動支付

[](#行動支付)

Google Pay、Samsung Pay、LINE Pay、銀聯卡、玉山 Wallet、台灣 Pay：

```
NewebPay::payment()
    ...
    ->withGooglePay()  // Google Pay
    ->withSamsungPay() // Samsung Pay
    ->withLinePay()    // LINE Pay
    ->withUnionPay()   // 銀聯卡
    ->withEsunWallet() // 玉山 Wallet
    ->withTaiwanPay()  // 台灣 Pay
    ->submit();
```

LINE Pay 可傳入產品圖檔連結，顯示於 LINE Pay 付款前的產品圖片區（建議尺寸 84\*84 像素，未提供時使用藍新系統預設圖檔）：

```
NewebPay::payment()
    ...
    ->withLinePay(imageUrl: 'http://example.com/logo.png')
    ->submit();
```

#### 簡單付

[](#簡單付)

簡單付電子錢包、微信支付、支付寶：

```
NewebPay::payment()
    ...
    ->withEzPay()       // 簡單付電子錢包
    ->withEzPayWeChat() // 簡單付微信支付
    ->withEzPayAlipay() // 簡單付支付寶
    ->submit();
```

#### 超商代碼／條碼繳費

[](#超商代碼條碼繳費)

```
NewebPay::payment()
    ...
    ->withCvsCode() // 超商代碼繳費
    ->withBarcode() // 條碼繳費
    ->submit();
```

#### 物流設定

[](#物流設定)

設定超商物流相關選項：

```
use Ycs77\NewebPay\Enums\CVSCOM;
use Ycs77\NewebPay\Enums\LgsType;

NewebPay::payment()
    ...
    ->withLogisticsPayment(CVSCOM::NOT_PAY_AND_PAY) // 物流方式
    ->withLogisticsType(LgsType::C2C)               // 物流型態
    ->submit();
```

#### 交易限制

[](#交易限制)

設定交易的秒數限制和截止天數：

```
NewebPay::payment()
    ...
    ->withTradeLimit(900)  // 交易秒數限制 (60~900 秒)
    ->withExpireDays(14)   // 交易截止日 (天數，最大 180 天)
    ->submit();
```

#### 其他付款選項

[](#其他付款選項)

```
NewebPay::payment()
    ...
    ->disableEmailModify()           // 禁止修改 email
    ->withOrderComment('這是訂單備註') // 商店備註 (最大 300 字)
    ->submit();
```

#### 完整方法對照表

[](#完整方法對照表)

付款相關方法一覽：

```
use Ycs77\NewebPay\Enums\Bank;
use Ycs77\NewebPay\Enums\CreditInst;
use Ycs77\NewebPay\Enums\CVSCOM;
use Ycs77\NewebPay\Enums\LgsType;
use Ycs77\NewebPay\Enums\NTCBLocate;

NewebPay::payment()
    ...
    ->withCredit(red: true, inst: [CreditInst::P3, CreditInst::P6]) // 信用卡（可開紅利、分期）
    ->withCreditRemember('John Doe')     // 信用卡記憶卡號
    ->withWebAtm()                       // WebATM
    ->withAtmTransfer()                  // ATM 轉帳
    ->withBank([Bank::BOT, Bank::HNCB])  // 指定 WebATM/ATM 轉帳銀行
    ->withNationalTravelCard(NTCBLocate::HsinchuCity, '2020-01-01', '2020-12-31') // 國民旅遊卡
    ->withGooglePay()                    // Google Pay
    ->withSamsungPay()                   // Samsung Pay
    ->withLinePay(imageUrl: 'http://example.com/logo.png') // LINE Pay
    ->withUnionPay()                     // 銀聯卡
    ->withEsunWallet()                   // 玉山 Wallet
    ->withTaiwanPay()                    // 台灣 Pay
    ->withEzPay()                        // 簡單付電子錢包
    ->withEzPayWeChat()                  // 簡單付微信支付
    ->withEzPayAlipay()                  // 簡單付支付寶
    ->withCvsCode()                      // 超商代碼繳費
    ->withBarcode()                      // 條碼繳費
    ->withLogisticsPayment(CVSCOM::NOT_PAY_AND_PAY) // 物流方式
    ->withLogisticsType(LgsType::C2C)    // 物流型態
    ->withTradeLimit(900)                // 交易秒數限制
    ->withExpireDays(14)                 // 交易截止日
    ->disableEmailModify()               // 禁止修改 email
    ->withOrderComment('這是訂單備註')   // 商店備註
    ->submit();
```

### 接收付款結果

[](#接收付款結果)

依付款方式不同，藍新金流會用兩種方式回傳交易結果：

- **即時付款**（可直接跳轉回網站）：信用卡、Google Pay、Samsung Pay、LINE Pay、銀聯卡、玉山 Wallet、台灣 Pay、國民旅遊卡等，透過 `withReturnUrl()` 設定的 **callback**（前景回傳）接收。
- **取號付款**（需先取號、稍後才付款）：WebATM、ATM 轉帳、超商代碼、條碼、簡單付系列等，透過 `withNotifyUrl()` 設定的 **notify**（背景通知）接收。

如果同時設定了 callback 和 notify，進行部分交易時兩個 API 都會發送訊息，這時就要各司其職：callback 只設定返回給用戶的訊息，而 notify 只負責處理交易的邏輯。

**設定回傳網址**

```
NewebPay::payment()
    ...
    ->withReturnUrl('/pay/callback')      // 前景回傳網址 (Callback)
    ->withNotifyUrl('/pay/notify')        // 背景通知網址 (Notify)
    ->withCustomerUrl('/pay/customer')    // 商店取號網址
    ->withClientBackUrl('/pay/back')      // 返回按鈕網址
    ->submit();
```

> **自動補全網址**：若傳入的字串不是完整 URL（例如 `/pay/callback`），套件會自動以 `config('app.url')` 作為前綴補全。若傳入完整 URL（例如 `https://example.com/callback`），則直接使用不做修改。

**Callback（前景回傳）**

信用卡等即時付款方式，付款完成後會直接跳轉回網站，用 callback 回覆給用戶的訊息：

```
use Illuminate\Http\Request;
use Ycs77\NewebPay\Facades\NewebPay;

Route::post('/pay/callback', function (Request $request) {
    $result = NewebPay::result($request);

    if ($result->isFail()) {
        return redirect()
            ->to('/pay')
            ->with('error', $result->message());
    }

    return redirect()
        ->to('/pay')
        ->with('success', '付款成功');
});
```

**Notify（背景通知）**

ATM、超商等取號付款方式，付款完成是透過幕後通知的，用 notify 處理交易邏輯：

```
use Illuminate\Http\Request;
use Ycs77\NewebPay\Facades\NewebPay;

Route::post('/pay/notify', function (Request $request) {
    $result = NewebPay::result($request);

    if ($result->isFail()) {
        return;
    }

    logger('藍新金流 交易資訊 notify', ['result' => $result->toArray()]);

    // 訂單付款成功，處理訂單邏輯...
});
```

記得把這些路徑在 `app/Http/Middleware/VerifyCsrfToken.php` 中排除 CSRF 檢查：

```
class VerifyCsrfToken extends Middleware
{
    protected $except = [
        '/pay/callback',
        '/pay/notify',
    ];
}
```

**取得回傳結果**

回傳結果可以使用各個方法來取得需要的資料：

```
$result = NewebPay::result($request);
$result->status()          // 交易狀態：'SUCCESS' 或錯誤代碼
$result->isSuccess()       // 交易是否成功
$result->isFail()          // 交易是否失敗
$result->message()         // 交易狀態描述：'授權成功'
$result->result()          // 回傳參數 (陣列)
$result->merchantId()      // 藍新金流商店代號：'MS3311...'
$result->amount()          // 交易金額：120
$result->tradeNo()         // 藍新金流交易序號：'23061500000000000'
$result->orderNo()         // 商店訂單編號：'1686759318'
$result->paymentType()     // 付款方式：PaymentType::CREDIT
$result->payTime()         // 支付完成時間：Carbon 實例
$result->ip()              // 交易 IP：'127.0.0.1'
$result->escrowBank()      // 款項保管銀行：'HNCB'
```

### 取得付款結果的詳細資訊

[](#取得付款結果的詳細資訊)

根據不同的付款方式，可以取得對應的詳細資訊：

```
use Ycs77\NewebPay\Enums\PaymentType;

// 信用卡支付回傳（一次付清、Google Pay、Samaung Pay、國民旅遊卡、銀聯）
if ($result->paymentType() === PaymentType::CREDIT) {
    $credit = $result->credit();
    // 參考：\Ycs77\NewebPay\Results\Trade\CreditResult
}

// WEBATM、ATM 繳費回傳
if ($result->paymentType() === PaymentType::VACC || $result->paymentType() === PaymentType::WEBATM) {
    $atm = $result->atm();
    // 參考：\Ycs77\NewebPay\Results\Trade\ATMResult
}

// 超商代碼繳費回傳
if ($result->paymentType() === PaymentType::CVS) {
    $storeCode = $result->storeCode();
    // 參考：\Ycs77\NewebPay\Results\Trade\StoreCodeResult
}

// 超商條碼繳費回傳
if ($result->paymentType() === PaymentType::BARCODE) {
    $storeBarcode = $result->storeBarcode();
    // 參考：\Ycs77\NewebPay\Results\Trade\StoreBarcodeResult
}

// 超商物流回傳
if ($result->paymentType() === PaymentType::CVSCOM) {
    $lgs = $result->lgs();
    // 參考：\Ycs77\NewebPay\Results\Trade\LgsResult
}

// 跨境支付回傳 (包含簡單付電子錢包、簡單付微信支付、簡單付支付寶)
$ezPay = $result->ezPay();
// 參考：\Ycs77\NewebPay\Results\Trade\EzPayResult

// 玉山 Wallet 回傳
if ($result->paymentType() === PaymentType::ESUNWALLET) {
    $esunWallet = $result->esunWallet();
    // 參考：\Ycs77\NewebPay\Results\Trade\EsunWalletResult
}

// 台灣 Pay 回傳
if ($result->paymentType() === PaymentType::TAIWANPAY) {
    $taiwanPay = $result->taiwanPay();
    // 參考：\Ycs77\NewebPay\Results\Trade\TaiwanPayResult
}
```

### ATM/超商取號

[](#atm超商取號)

預設會直接導向到藍新金流的取號頁面，沒有特別需求不需要自己做。但如果要自訂取號頁面的話，也是可以自己客製調整：

```
use Illuminate\Http\Request;
use Ycs77\NewebPay\Facades\NewebPay;

Route::post('/pay/customer', function (Request $request) {
    $result = NewebPay::customer($request);

    if ($result->isFail()) {
        // 取號錯誤...
        return;
    }

    $result->merchantId()  // 藍新金流商店代號：'MS3311...'
    $result->amount()      // 交易金額：120
    $result->tradeNo()     // 藍新金流交易序號：'23061500000000000'
    $result->orderNo()     // 商店訂單編號：'1686763446'
    $result->paymentType() // 付款方式：PaymentType::BARCODE
    $result->expireTime()  // 繳費截止日期：Carbon 實例

    // 根據付款方式取得對應的取號資訊：
    $result->atm()          // ATM 繳費資訊
    $result->storeCode()    // 超商代碼繳費資訊
    $result->storeBarcode() // 超商條碼繳費資訊
    $result->lgs()          // 超商物流資訊

    // 自訂取號結果頁面...
});
```

還要把路徑在 `app/Http/Middleware/VerifyCsrfToken.php` 中排除 CSRF 檢查：

```
class VerifyCsrfToken extends Middleware
{
    protected $except = [
        ...
        '/pay/customer',
    ];
}
```

查詢交易詳情
------

[](#查詢交易詳情)

從訂單編號和該筆交易的金額來查詢交易詳情：

```
use Ycs77\NewebPay\Facades\NewebPay;

$result = NewebPay::query()
    ->withOrder('Order001') // 該筆交易的訂單編號
    ->withAmount(1050)      // 該筆交易的金額
    ->get();

$result->merchantId() // 藍新金流商店代號：'TestMerchantID1234'
$result->orderNo()    // 商店訂單編號：'Order001'
$result->tradeNo()    // 藍新金流交易序號：'23061500000000000'
$result->amount()     // 交易金額：1050
```

如果是組合型商店，可以使用 `forCompositeStore()` 來查詢：

```
$result = NewebPay::query()
    ->withOrder('Order001')
    ->withAmount(1050)
    ->forCompositeStore()
    ->get();
```

信用卡取消授權
-------

[](#信用卡取消授權)

在尚未請款時可以發動取消信用卡交易。使用訂單編號取消授權：

```
use Ycs77\NewebPay\Facades\NewebPay;

$result = NewebPay::creditCard()
    ->reverse()
    ->withOrder('Order001') // 該筆交易的訂單編號
    ->withAmount(1050)      // 該筆交易的金額
    ->send();

$result->merchantId() // 藍新金流商店代號：'TestMerchantID1234'
$result->orderNo()    // 商店訂單編號：'Order001'
$result->tradeNo()    // 藍新金流交易序號：'23061500000000000'
$result->amount()     // 取消授權金額：1050
```

或者使用藍新交易編號取消授權：

```
$result = NewebPay::creditCard()
    ->reverse()
    ->withTrade('23061500000000000') // 藍新金流交易序號
    ->withAmount(1050)
    ->send();
```

信用卡請退款
------

[](#信用卡請退款)

### 信用卡請款

[](#信用卡請款)

信用卡請款：

```
use Ycs77\NewebPay\Facades\NewebPay;

$result = NewebPay::creditCard()
    ->capture()
    ->withOrder('Order001') // 該筆交易的訂單編號
    ->withAmount(1050)      // 該筆交易的金額
    ->send();

$result->merchantId() // 藍新金流商店代號：'TestMerchantID1234'
$result->orderNo()    // 商店訂單編號：'Order001'
$result->tradeNo()    // 藍新金流交易序號：'23061500000000000'
$result->amount()     // 請款金額：1050
```

取消請款，在請款的基礎上加上 `reverse()`：

```
$result = NewebPay::creditCard()
    ->capture()
    ->withOrder('Order001')
    ->withAmount(1050)
    ->reverse() // 取消請款
    ->send();
```

### 信用卡退款

[](#信用卡退款)

信用卡退款：

```
use Ycs77\NewebPay\Facades\NewebPay;

$result = NewebPay::creditCard()
    ->refund()
    ->withOrder('Order001') // 該筆交易的訂單編號
    ->withAmount(1050)      // 該筆交易的金額
    ->send();

$result->merchantId() // 藍新金流商店代號：'TestMerchantID1234'
$result->orderNo()    // 商店訂單編號：'Order001'
$result->tradeNo()    // 藍新金流交易序號：'23061500000000000'
$result->amount()     // 退款金額：1050
```

取消退款，在退款的基礎上加上 `reverse()`：

```
$result = NewebPay::creditCard()
    ->refund()
    ->withOrder('Order001')
    ->withAmount(1050)
    ->reverse() // 取消退款
    ->send();
```

信用卡定期定額委託
---------

[](#信用卡定期定額委託)

### 建立委託

[](#建立委託)

建立信用卡定期定額委託的基本範例：

```
use Ycs77\NewebPay\Facades\NewebPay;

Route::post('/subscribe', function () {
    return NewebPay::period()
        ->create()
        ->withOrder('Order'.time())              // 訂單編號
        ->withAmount(120)                        // 交易金額
        ->withItemDescription('我的訂閱制商品')   // 商品名稱
        ->withEmail('test@example.com')          // 付款人信箱
        ->withReturnUrl('/pay/period/callback')  // 前景回傳網址 (Callback)
        ->withNotifyUrl('/pay/period/notify')    // 背景通知網址 (Notify)
        ->everyFewDays(2)                        // 每隔 2 天授權一次
        ->times(3)                               // 共授權 3 次
        ->submit();
});
```

發送建立委託前需要先建立一個含有表單的頁面：

*resources/views/subscribe.blade.php*

```

    @csrf
    訂閱

```

### 授權週期

[](#授權週期)

若於週期內需授權多次，請以建立多次委託方式執行。

設定此委託於固定天期制授權，輸入數字為間隔天數 2~999。以授權日期隔日起算，以下為每隔 40 天授權一次：

```
NewebPay::period()
    ->create()
    ...
    ->everyFewDays(40)
    ->times(1)
    ->submit();
```

設定此委託於每週授權，輸入數字為 1~7，代表每週一至週日。以下為每週日授權一次：

```
NewebPay::period()
    ->create()
    ...
    ->weekly(7)
    ->times(1)
    ->submit();
```

設定此委託於每月授權，輸入數字為 1~31，每月的第幾天執行委託，若當月沒該日期則由該月的最後一天做為扣款日。以下為每月 20 日授權一次：

```
NewebPay::period()
    ->create()
    ...
    ->monthly(20)
    ->times(1)
    ->submit();
```

設定此委託於每年授權，輸入每年的幾月幾日執行委託。以下為每年 3 月 4 日授權一次：

```
NewebPay::period()
    ->create()
    ...
    ->yearly(3, 4)
    ->times(1)
    ->submit();
```

### 授權期數

[](#授權期數)

設定授權委託的期數。以下為每月 4 日授權，共授權 6 次，為期 6 個月：

```
NewebPay::period()
    ->create()
    ...
    ->monthly(4)
    ->times(6)
    ->submit();
```

### 授權起始方式

[](#授權起始方式)

設定立即執行十元授權，以驗證信用卡：

```
'period' => [
    'start_type' => PeriodStartType::TEN_DOLLARS_NOW,
],
```

設定立即執行委託金額授權：

```
'period' => [
    'start_type' => PeriodStartType::AUTHORIZE_NOW,
],
```

設定刷卡完之後，不檢查信用卡資訊，也不執行授權：

```
'period' => [
    'start_type' => PeriodStartType::NO_AUTHORIZE,
],
```

當選擇不授權時，需要設定首期授權日：

```
NewebPay::period()
    ->create()
    ...
    ->everyFewDays(2)
    ->times(3)
    ->firstChargeAt(2023, 3, 1) // 首期授權日
    ->submit();
```

### 接收委託結果

[](#接收委託結果)

設定建立委託完成後，將頁面導向回原本的網站頁面：

```
use Illuminate\Http\Request;
use Ycs77\NewebPay\Facades\NewebPay;

Route::post('/pay/period/callback', function (Request $request) {
    $result = NewebPay::periodResult($request);

    if ($result->isFail()) {
        return redirect()->to('/pay')->with('error', $result->message());
    }

    $result->merchantID()   // 藍新金流商店代號：'TestMerchantID1234'
    $result->orderNo()      // 商店訂單編號：'Order001'
    $result->periodNo()     // 委託單號：'20200101000000001'
    $result->periodAmount() // 委託金額：1050

    return redirect()->to('/pay')->with('success', '付款成功');
});
```

以及設定每期委託授權結果通知：

```
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Ycs77\NewebPay\Facades\NewebPay;

Route::post('/pay/period/notify', function (Request $request) {
    $result = NewebPay::periodNotify($request);

    if ($result->isFail()) {
        Log::error('藍新金流 定期定額 定期交易錯誤', $result->toArray());

        return;
    }

    $result->merchantID()  // 藍新金流商店代號：'TestMerchantID1234'
    $result->orderNo()     // 商店訂單編號：'Order001'
    $result->authAmount()  // 本期授權金額：1050
    $result->periodNo()    // 委託單號：'20200101000000001'

    // 委託授權成功，處理訂單邏輯...
});
```

記得要把這些路徑在 `app/Http/Middleware/VerifyCsrfToken.php` 中排除 CSRF 檢查：

*app/Http/Middleware/VerifyCsrfToken.php*

```
class VerifyCsrfToken extends Middleware
{
    protected $except = [
        ...
        '/pay/period/callback',
        '/pay/period/notify',
    ];
}
```

### 修改委託狀態

[](#修改委託狀態)

修改委託狀態需要傳入訂單編號和委託單號，並呼叫對應的狀態方法：

終止委託：

```
use Ycs77\NewebPay\Facades\NewebPay;

$result = NewebPay::period()
    ->alterStatus()
    ->withOrder('Order001')                // 訂單編號
    ->withPeriod('20200101000000001')       // 委託單號
    ->terminate();                         // 終止委託

$result->orderNo()       // 商店訂單編號：'Order001'
$result->periodNo()      // 委託單號：'20200101000000001'
$result->periodStatus()  // 委託狀態：PeriodStatus::TERMINATE
```

暫停委託：

```
$result = NewebPay::period()
    ->alterStatus()
    ->withOrder('Order001')
    ->withPeriod('20200101000000001')
    ->suspend(); // 暫停委託
```

暫停後重新啟用委託：

```
$result = NewebPay::period()
    ->alterStatus()
    ->withOrder('Order001')
    ->withPeriod('20200101000000001')
    ->resume(); // 重新啟用委託
```

Important

委託狀態設定成暫停之後可以改成啟用，但終止委託後就無法再次啟用了。暫停後再次啟用的委託將於最近一期開始授權，總期數不變，扣款時間將向後展延至期數滿期。

### 修改委託內容

[](#修改委託內容)

修改委託內容需要傳入訂單編號、委託單號，和設定要修改成的委託觸發週期和授權次數：

```
use Ycs77\NewebPay\Facades\NewebPay;

$result = NewebPay::period()
    ->alter()
    ->withOrder('Order001')            // 訂單編號
    ->withPeriod('20200101000000001')  // 委託單號
    ->withAmount(1000)                 // 新的委託金額
    ->everyFewDays(3)                  // 新的授權週期
    ->times(10)                        // 新的授權次數
    ->send();

$result->orderNo()       // 商店訂單編號：'Order001'
$result->periodNo()      // 委託單號：'20200101000000001'
$result->periodAmount()  // 新的委託金額：1000
```

錯誤處理
----

[](#錯誤處理)

當藍新金流 API 回傳失敗的回應時，會拋出 `NewebPayException` 例外，可以取得藍新金流的錯誤代碼和錯誤訊息進行進一步處理：

```
use Ycs77\NewebPay\Exceptions\NewebPayException;

try {
    $result = NewebPay::query()
        ->withOrder('Order001')
        ->withAmount(1050)
        ->get();
} catch (NewebPayException $e) {
    $status = $e->getApiStatus(); // 'MPG01001'
    $message = $e->getApiMessage(); // '商店代號不存在'

    // 記錄錯誤日誌...
    logger()->error($e->getMessage(), $e->context());

    // 顯示錯誤訊息給使用者...
    return response()->json([
        'error' => $message,
    ], 400);
}
```

單元測試
----

[](#單元測試)

在單元測試中，可以使用 `NewebPay::fake()` 模擬 API 回應，這邊要模擬交易查詢回應，因此使用 `QueryResult` 來建立模擬回應資料：

```