iT邦幫忙

2021 iThome 鐵人賽

DAY 12
0
永豐金融APIs

永豐金 API - 豐支付 PHP SDK 設計及 WooCommerce 電商串接實戰系列 第 12

Day 12 - PHP SDK: 建立信用卡、虛擬帳號訂單

昨天發佈了 Sinopac PHP SDK,接著來有幾天的篇幅會介紹如何使用。今天先來談談建立訂單的部分。

建立訂單

Day 11 我們已經實例化 QPay 類別。

圖 12-1
圖 12-1: PHP SDK - 實例化 QPay 類別 程式碼

接著可以使用以下方法來建立訂單。

和 API 的欄位稍有不同,陣列的鍵值一律小寫 Snake-case naming,是為了一致的 Coding Style 及簡化輸入架構,一律為一維陣列。

有的必填參數已自動帶入了所以不用填寫,只列出對應的部分。


QPay::createOrderByCreditCard(array $data)

建立信用卡訂單,使用信用卡刷卡付款。

資料欄位 對應 API 的欄位 說明
order_no * OrderNo 訂單編號
amount * Amount 訂單總金額,需補上小數二位,若金額為 10 元則值請填入 1000
product_name * PrdtName 商品名稱
order_note Memo 備註
param_1 Param1 自訂參數一
param_2 Param2 自訂參數二
param_3 Param3 自訂參數三
return_url * ReturnURL 將消費者端導回您指定的付款完成頁面
backend_url BackendURL 通知您主機端付款完成的 URL
cc_auto_billing * CardParam [AutoBilling] 建立信用卡時為 - Y:自動請款 N:不自動請款。若使用銀聯卡或定期定額時系統一律為自動請款。
cc_expired_billing_days CardParam [ExpBillingDays] 若訂單為待授權未請款時,可以指定刷卡完成後多久自動請款。可設定範圍為 1-7 但是 AutoBilling 設為 Y 時則該參數會忽略。
cc_expired_minutes CardParam [ExpMinutes] 信用卡付款連結有效時間(分鐘) 。預設為 10 分鐘可設定範圍為 1-30

程式碼範例:
圖 12-2
圖 12-2: PHP SDK - 建立信用卡訂單 程式碼

以上為使用 createOrderByCreditCard 方法建立訂單,API 回應的結果主要資訊在 Message 已解密為陣列結構,請參考 API 文件第 35 頁,有對回應的欄位有詳細說明。


QPay::createOrderByATM(array $data)

建立虛擬帳號訂單,使用 ATM 轉帳到虛擬帳號付款。

資料欄位 對應 API 的欄位 說明
order_no * OrderNo 訂單編號
amount * Amount 訂單總金額,需補上小數二位,若金額為 10 元則值請填入 1000
product_name * PrdtName 商品名稱
order_note Memo 備註
param_1 Param1 自訂參數一
param_2 Param2 自訂參數二
param_3 Param3 自訂參數三
return_url * ReturnURL 將消費者端導回您指定的付款完成頁面
backend_url BackendURL 通知您主機端付款完成的 URL
atm_expired_date * ATMParam [ExpireDate] 付款截止日期。例如 2017/5/3 則帶 20170503,設定值最大為 30 天。

程式碼範例:
圖 12-3
圖 12-3: PHP SDK - 建立虛擬帳號訂單 程式碼

以上為使用 createOrderByATM 方法建立訂單,API 回應的結果主要資訊在 Message 已解密為陣列結構,請參考 API 文件第 35 頁,有對回應的欄位有詳細說明。


API 回應

在前一個文章段落介紹的建單過程取得永豐金收款平台的 API 回應後,資料欄位在 Message 且 SDK 已自動解密可直接取用。

<?php
if (!empty($results['Message'])) {
    print_r($results['Message']);
}

信用卡付款

圖 12-4
圖 12-4: 信用卡訂單 Messsage 欄位 (JSON 排版)

建立信用卡訂單後,API 的回應會有 CardPayURL 這個欄位,提供給商店網站進行轉址到信用卡付款頁面,讓使用者進行付款。付款完再跳轉回商店網站,如下圖流程。

圖 12-5
圖 12-5: 文件第 7 頁

在永豐金收款平台刷卡完之後,從建立訂單的欄位 return_url 轉回商店網站時會帶上 PayToken 參數,讓商店網站可以查詢付款狀態。

虛擬帳號付款

圖 12-6
圖 12-6: 虛擬帳號訂單 Messsage 欄位 (JSON 排版)

建立虛擬帳號訂單後,API 的回應會,API 的回應會有 AtmPayNoWebAtmURLOtpURL 這三個欄位,提供給商店網站。

圖 12-7
圖 12-7: 文件第 6 頁

AtmPayNo 用於顯示在結帳完成頁面 (Thank-you page) 或訂單資訊頁面,讓使用者能透過 ATM 轉帳進行結帳。

建立虛擬帳號訂單時,建議帶上 backend_url,以利永豐金收款平台在收到款項時,即時通知商店網站進行商店的訂單狀態變更及其它商業邏輯上的後續處理(例如出貨,等等。)

總結

PHP SDK 把中間複雜的 HashId 計算IV 計算Sign 計算AES 加密解密等流程,都幫忙處理了,所以只要用少少的程式碼就能完成串接,能大幅增加開發人員的工作效率喔。

如果在使用上有什麼問題,歡迎到 GitHub 回報,我會盡快修復唷。^^

註:如果是在測試環境,請記得啟用沙盒模式,發起 API 請求時會送往收款平台的測試網址。

$qpay->enableSandbox();

上一篇
Day 11 - 豐收款非官方 PHP SDK 發佈
下一篇
Day 13 - PHP SDK: 查詢訂單狀態
系列文
永豐金 API - 豐支付 PHP SDK 設計及 WooCommerce 電商串接實戰30

尚未有邦友留言

立即登入留言