PHP code example of ycs77 / laravel-newebpay

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

ycs77 / laravel-newebpay example snippets

use Ycs77\NewebPay\Facades\NewebPay;

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

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', '付款成功');
});

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()]);

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

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

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

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

NewebPay::payment()
    ...
    ->withPaymentMethods([...]) // 付款方式 *依照 config 格式傳送*
    ->submit();

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

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

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

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

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', '付款成功');
});

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

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

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

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

$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
}

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()          // 超商物流資訊

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

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

$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

$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

$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('[email protected]')          // 付款人信箱
        ->withReturnUrl('/pay/period/callback')  // 前景回傳網址 (Callback)
        ->withNotifyUrl('/pay/period/notify')    // 背景通知網址 (Notify)
        ->everyFewDays(2)                        // 每隔 2 天授權一次
        ->times(3)                               // 共授權 3 次
        ->submit();
});

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

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

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

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

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'

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

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(); // 重新啟用委託

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

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);
}

use Ycs77\NewebPay\Facades\NewebPay;
use Ycs77\NewebPay\Options\Trade\QueryOptions;
use Ycs77\NewebPay\Resources\PaymentQuery;
use Ycs77\NewebPay\Results\Trade\QueryResult;

test('can query trade', function () {
    // 模擬交易查詢 API 回應
    NewebPay::fake([
        // 模擬交易查詢回應
        // 需要使用實際呼叫的 Result 類別來建立模擬回應
        //
        // 因為下面使用 NewebPay::query()->get() 來查詢交易
        // 因此模擬的回應類別需要使用 QueryResult 類別
        QueryResult::make([
            'Status' => 'SUCCESS',
            'Message' => '查詢成功',
            'Result' => [
                'MerchantID' => 'TestMerchantID1234',
                'Amt' => 1050,
                'TradeNo' => '23061500000000000',
                'MerchantOrderNo' => 'Order001',
                'TradeStatus' => 1,
                'PaymentType' => 'CREDIT',
                'CreateTime' => '2023-01-01 00:00:00',
                'PayTime' => '2023-01-01 00:00:00',
                'CheckCode' => '123456789',
                'FundTime' => '2023-01-01',
                'RespondCode' => '00',
                'Auth' => '222111',
                'ECI' => '',
                'CloseAmt' => 120,
                'CloseStatus' => 0,
                'BackBalance' => 120,
                'BackStatus' => 0,
                'RespondMsg' => '授權測試',
                'Inst' => 0,
                'InstFirst' => 0,
                'InstEach' => 0,
                'PaymentMethod' => 'CREDIT',
                'Card6No' => '400022',
                'Card4No' => '1111',
                'AuthBank' => 'CTBC',
            ],
        ]),
    ]);

    // 測試發送交易查詢請求
    $result = NewebPay::query()
        ->withOrder('Order001')
        ->withAmount(1050)
        ->get();

    // 斷言發送參數
    //
    // 因為上面是呼叫 NewebPay::query()
    //
    // 因此斷言的資源類別和方法名稱分別是：
    // - PaymentQuery::class 是 query() 方法回傳的資源類別
    // - 'query' 是呼叫的方法名稱
    NewebPay::assertSent(PaymentQuery::class, 'query', function (QueryOptions $options) {
        return $options->orderNo === 'Order001'
            && $options->amount === 1050;
    });

    expect($result->orderNo())->toBe('Order001')
        ->and($result->tradeNo())->toBe('23061500000000000')
        ->and($result->amount())->toBe(1050);
});

use Ycs77\NewebPay\Facades\NewebPay;
use Ycs77\NewebPay\Options\CreditCard\CaptureOptions;
use Ycs77\NewebPay\Resources\CreditCard;
use Ycs77\NewebPay\Results\CreditCard\CaptureResult;

test('can capture credit card', function () {
    NewebPay::fake([
        CaptureResult::make([
            'Status' => 'SUCCESS',
            'Message' => '請款成功',
            'Result' => [
                'MerchantID' => 'TestMerchantID1234',
                'Amt' => 1050,
                'TradeNo' => '23061500000000000',
                'MerchantOrderNo' => 'Order001',
            ],
        ]),
    ]);

    $result = NewebPay::creditCard()
        ->capture()
        ->withOrder('Order001')
        ->withAmount(1050)
        ->send();

    NewebPay::assertSent(CreditCard::class, 'capture', function (CaptureOptions $options) {
        return $options->orderNo === 'Order001'
            && $options->amount === 1050
            && $options->reverse === false;
    });

    expect($result->orderNo())->toBe('Order001')
        ->and($result->amount())->toBe(1050);
});

use Ycs77\NewebPay\Options\Options;

$result = NewebPay::query()
    ->withOrder('Order001')
    ->withAmount(1050)
    ->onPreparedOptions(function (Options $options) {
        dd($options->toArray()); // 查看請求參數資料
    })
    ->get();

dd($result->toArray()); // 查看回應資料

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

html
<form action="/pay" method="POST">
    @csrf
    <button>付款</button>
</form>

html
<form action="/subscribe" method="POST">
    @csrf
    <button>訂閱</button>
</form>