永豐金 API - PHP SDK: 建立信用卡、虛擬帳號訂單

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

建立訂單

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

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

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

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

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

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

資料欄位	對應 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: PHP SDK - 建立信用卡訂單程式碼

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

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

程式碼範例：

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

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

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

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

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

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

圖 12-5: 文件第 7 頁

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

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

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

圖 12-7: 文件第 6 頁

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

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

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

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

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

$qpay->enableSandbox();