Download the PHP package ycs77/laravel-newebpay without Composer

Laravel NewebPay - 藍新金流

Fork from treerful/laravel-newebpay

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

套件功能

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

目錄

• 版本需求
• 安裝
• 設定
• 測試信用卡號
• MPG 多功能付款
  • 建立付款流程
  • 自訂付款選項
  • 接收付款結果
  • 取得付款結果的詳細資訊
• ATM/超商取號
• 單筆交易查詢
• 信用卡取消授權
• 信用卡請款
• 信用卡退款
• 信用卡定期定額委託
  • 建立委託
  • 授權週期
  • 授權期數
  • 授權起始方式
  • 接收委託結果
  • 修改委託狀態
  • 修改委託內容
• 錯誤處理
• 單元測試
• 除錯支援
• 參考
• 贊助
• License

版本需求

安裝

使用 Composer 安裝套件：

發布設置檔案：

設定

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

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

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

測試信用卡號

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

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

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

MPG 多功能付款

建立付款流程

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

resources/views/pay.blade.php

Inertia.js 可以參考以下：

resources/js/pages/Pay.vue

然後設定路由來發送 MPG 多功能付款請求：

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

如果是 ATM 的付款方式，需要透過幕後回傳的，設定 notify：

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

自訂付款選項

基本上一般交易可直接在 config/newebpay.php 做設定，但若遇到特殊情況，可依據個別交易設定更多付款選項。

交易限制

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

回傳網址

設定付款完成後的回傳網址：

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

付款方式

覆蓋 config 中的付款方式設定，格式與 config 相同：

信用卡記憶卡號

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

其他選項

物流設定

設定超商物流相關選項：

接收付款結果

在建立付款流程中已設定了基本的 callback 和 notify 路由。如果同時設定了 callback 和 notify，進行部分交易時兩個 API 都會發送訊息，這時就要各司其職，callback 只設定返回給用戶的訊息，而 notify 只負責處理交易的邏輯：

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

取得付款結果的詳細資訊

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

ATM/超商取號

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

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

單筆交易查詢

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

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

信用卡取消授權

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

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

信用卡請款

信用卡請款：

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

信用卡退款

信用卡退款：

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

信用卡定期定額委託

建立委託

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

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

resources/views/subscribe.blade.php

授權週期

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

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

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

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

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

授權期數

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

授權起始方式

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

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

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

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

接收委託結果

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

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

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

app/Http/Middleware/VerifyCsrfToken.php

修改委託狀態

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

終止委託：

暫停委託：

暫停後重新啟用委託：

[!IMPORTANT]

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

修改委託內容

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

錯誤處理

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

單元測試

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

信用卡請款的模擬範例，因為呼叫的是 NewebPay::creditCard()->capture()，因此模擬回應使用 CaptureResult，斷言的資源類別則是 CreditCard：

[!WARNING] 不支援模擬 MPG 多功能付款的 submit() 方法，因為該方法是直接產生跳轉表單資料，實際上不會發送 API 請求。

除錯支援

當發生錯誤時，請協助提供請求與回應的除錯資料，以便更快速地定位問題：

• 使用 $options->toArray() 方法可檢視發送至 API 的請求資料
• 透過 $result->toArray() 可檢視 API 的回應資料內容
• 當發生錯誤時，請在提交 issue 時一併提供請求與回應的除錯資料

參考

API文件下載 | 藍新金流服務平台

當前參考文件版本：

• 線上交易─幕前支付技術串接手冊
• 信用卡定期定額串接技術手冊

相關專案

• agriweather/laravel-ezpay-invoice：Laravel 的 ezPay 電子發票整合套件

貢獻專案

歡迎參與貢獻專案，請參考 貢獻指南 文件。

贊助

如果我維護的套件有幫助到你，可以考慮贊助我~ 我會很感謝你~ 而且還可以顯示您的大頭貼在我的主要專案中。

License

Under the MIT LICENSE