[ASP.NET MVC][Vue3] 藍新金流 NewebPay API 串接教學

[ASP.NET MVC][Vue3] 藍新金流 NewebPay API 串接教學

藍新金流 NewebPay 是國內第三方支付平台之一,金流界俗稱的紅藍綠之中的藍新金流。
第三方支付平台提供代收款及代付款等功能,幫助電商網站在網路上向消費者收款,而第三方支付平台則收取手續費做為營業收入。

藍新金流提供主流收款方式,包含線上刷卡、超商代收、ATM/WebATM 以及行動支付工具,每種收款方式的手續費各有不同,關於費率表可參考官方說明

今天將會示範如何在 ASP.NET 串接藍新金流 API,執行線上交易,藍新金流提供測試環境幫助初次串接者測試,所以我會以測試環境做為示範。

藍新金流 API 文件

串接 API 的規則都寫在文件內,可以到 API 文件下載區點擊「線上交易─幕前支付(MPG)」下載。

線上交易─幕前支付(MPG)

要串接的重要資訊都寫在此文件內,串接前一定要看一下。
API 版本會隨時間更新,如果有以前建置的 API,也要定期看一下是否要更新程式內的 API 規則。

串接 API 前準備事項

藍新金流測試環境

對於第一次串接的人來說,難免會有一些狀況發生,而且金流又有錢的問題,如果出錯導致虧損就不好了,建議先在測試環境下串接成功了,再移到正式環境再測一遍。
在 API 文件內有測試環境串接說明。

藍新金流測試環境

有 2 個測試網址,串接網址: https://ccore.newebpay.com/MPG/mpg_gateway,後台管理網址: https://cwww.newebpay.com/,這兩個網址比較重要。

可以先到後台管理網址,註冊帳號填寫個人基本資料,首次註冊需要上傳一些證件驗證,要等官方審核後,才可開立商店。
如果太久都沒有審核通過,建議直接請客服幫忙比較快,因為是測試環境,審核不一定有人處理。

當審核通過後,就可以到「商店管理」的「開立商店設定」新增資料。

開立商店設定

當開立商店完成後,點擊商店的「詳細資料」。

當開立商店完成後,點擊商店的「詳細資料」

對 API 會用到的資訊有「商店代號」,以及下面的「API 串接金鑰」。

商店代號

在下方會找到 API 串接金鑰。

在下方會找到 API 串接金鑰

對外網域

在呼叫金流 API 時,不管成功能否,都會由 API 伺服器主動回報執行結果,所以我們需要建立對外網域來接收結果,對外網域建議先有固定 IP 後,再由網域商註冊網域,然後透過 DNS 指向至網站主機。

如果需要註冊網域,可參考另一篇文章: GoDaddy 購買網域教學-建立你的網路門牌

在開發階段使用的 localhost 網址是不能測試金流 API 的喔。
當開發好程式後,可以在對外網域的 IIS 上建立站台,指定接受網域。

在對外網域的 IIS 上建立站台,指定接受網域

建立專案

開啟 Visual Studio 2022,建立新專案為「ASP.NET Core Web 應用程式 (Model-View-Controller)」。

ASP.NET Core Web 應用程式 (Model-View-Controller)

輸入專案名稱、路徑,架構選擇「.NET 6.0」版本,按下「建立」就會建立此專案。

加入 Vue3 套件

Vue3 是前端控制欄位的框架類別庫,打開 \Views\Shared\_Layout.cshtml 檔案,在下方 JavaScript 引用增加 Vue3 類別庫語法,順序的要求要放在 jQuery 之後才行。

<script src="https://unpkg.com/vue@3"></script>

當在 Layout 加上 Vue3 引用後,我們就可以在所有的頁面使用 Vue3 語法了,此引用語法來源可參考官方文件

停用 Json 回傳預設小寫 (駝峰式命名) 設定

.NET Core 在 Controller 回傳 Json 時,會將變數修改為開頭預設小寫 (駝峰式命名),這設定容易造成前端取值大小寫問題,所以我會停用此設定。

在 Program.cs 加入以下語法:

停用 Json 回傳預設小寫設定

藍新金流 API 串接

接著我在 MVC 的主頁面 Home/Index 設計範例,因為 MVC 是分層架構,所以寫程式碼的位置也會跳來跳去的。我會依順序在不同頁面慢慢增加程式碼。

產生測試資料

打開 \Controllers\HomeController.cs,在 Index() 內加入測試金流測試用語法:

產生測試資料

這裡是產生訂單需要的資料,呼叫 API 時需要設定接收網址,我自訂幾個接收網址,API 參數說明可在文件中查詢。

API 參數說明可在文件中查詢

設定檔加入 API 串接金鑰

我們在藍新金流得到的「商店代號」與「API 串接金鑰」,建議放在專案設定檔裡面,打開「appsettings.json」,加入以下新設定:

View 訂單頁

打開 \Views\Home\Index.cshtml,先清空原有的語法,然後貼上此語法:

這裡設計了表單畫面,還有一個執行方法,按下方法 SendToNewebPay(ChannelID) 會呼叫至 HomeController 的 SendToNewebPay() 方法。

此頁面執行後的畫面是。

藍新金流 API 串接

傳送至藍新金流 API

打開 \Controllers\HomeController.cs,這裡要新增一個方法,接收 View 的 SendToNewebPay() 呼叫。
加入以下語法:

這裡接收到 View 的表單後,就會組合 API 資料進行加密,等加密後會回傳至前端 View 再傳送至藍新金流 API Server。
藍新金流使用兩者加密方法,一種是 AES 可逆的加密法,另一種是 SHA256 不可逆雜湊運算

藍新金流 API 只接收 5 個欄位,可參考文件:

藍新金流 API 只接收 5 個欄位,可參考文件

其中的 TradeInfo 欄位會包含訂單主要資訊,但會經過加密後才傳送出去。

補充語法內用到的加解密方法:

ViewModel 欄位

這裡要建一個 ViewModel 類別,來定義 Controller 與 View 之間的欄位定義,在 Models 按右鍵加入一個類別,取名為「HomeViewModel」。

在 Models 按右鍵加入一個類別

在類別內加入 Controller 會用到的欄位:

這時候你的程式碼應該就沒有錯誤提示了。

當我們執行功能傳送至藍新金流時,會顯示付款畫面。

藍新金流 API 串接

API 返回網址接收方法

我們在前面有設定 3 個 API 返回網址,這是會從藍新金流主動呼叫的網址,所以我們要建立接收方法來取得回傳資料。
我的接收位置同樣設定在 HomeController 內,所以要新增這 3 個接收網址。

設定 3 個 API 返回網址

加入支付完成返回商店網址方法

在送出訂單 API 時會跳轉至藍新金流付款畫面,當使用者完成付款動作時,藍新金流會回傳呼叫我們的「支付完成返回商店網址」,這裡會接收使用者付款的狀態,我們可以從回傳資訊內查詢使用者是否已付款。

同樣在 HomeController 內加入此語法:

接收方法裡面要做的就是解密資料,我們傳送前有加密後再傳送,接收時也需要解密才能看到資料,解密方法是 AES,補充解密方法:

在前端 View 我簡單顯示資料就好,加入 View 頁面 \Views\Home\CallbackReturn.cshtml 後,貼上語法:

加入商店取號網址方法

商店取號網址會用在使用者選擇 ATM 付款時,藍新金流會呼叫這個網址,告知我們使用者要匯款的銀行代碼和帳號是多少,我們可以顯示銀行代碼和帳號給使用者知道。

同樣在 HomeController 內加入此語法:

在前端 View 我簡單顯示資料就好,加入 View 頁面 \Views\Home\CallbackCustomer.cshtml 後,貼上語法:

接收頁面顯示如下。

商店取號網址

我們可以從 BankCode 和 CodeNo 知道使用者要匯款的銀行代碼和帳號。

加入支付通知網址方法

這個方法是當使用者實際付款完成時,不管是信用卡、ATM 或超商付款,會收到的通知,這個方法不需要設計顯示頁面。
例如使用者選擇 ATM 付款時,任何時間在 ATM 完成付款,我們從這方法收到通知後,寫入資料庫內紀錄使用者已付款就好。

同樣在 HomeController 內加入此語法:

其實這 3 個回傳接收方法解密方式都一樣,也使用相同的 API 金鑰,可以將 API 金鑰放在設定檔內保存。
然後我示範解密的方法,實際上再依各自的需求修改讀取需要的資料。

再次提醒一下,你要測試藍新金流時,首先要在測試環境下串接,測試完整後,再到正式環境再測一遍,然後要有對外網域或 IP 才可以測試,最後祝大家串接順利。

範例下載

連結 GitHub 下載範例

相關學習文章

如果你在學習上有不懂的地方,需要諮詢服務,可以參考站長服務,我想辨法解決你的問題
如果文章內容有過時、不適用或錯誤的地方,幫我在下方留言通知我一下,謝謝

加入社團一起討論

關注我的 IG