昨天 Day 12 介紹了 Sinopac PHP SDK 關於建立訂單的部分，接著今天要介紹的是查詢訂單狀態。
查詢訂單
圖 13-1: PHP SDK - 實例化 QPay 類別
在進行查詢訂單之前，一樣先實例化我們的 QPay 類別，接下來的程式範例就省略這一段。
QPay::queryOrders(array $data)
查詢批次訂單，必須至少填入以下查詢條件中的任何一個。如果是日期時間參數，則必須開始時間與結束時間為一對一起填入，且結束時間須大於開始時間。日期的時間格式都是 YmdHi，一共 12 碼。
| 資料欄位 | 對應 API 的欄位 | 說明 |
|---|---|---|
| order_no | OrderNo | 訂單編號 |
| pay_type | PayType | 付款方式。ATM 轉帳：A、信用卡：C |
| order_datetime_begin | OrderDateTimeS | 交易起始時間，例如 2021/9/20 12:30 則帶 202109201230。 |
| order_datetime_end | OrderDateTimeE | 交易結束時間，例如 2021/9/20 23:59 則為 202109202359。 |
| pay_datetime_begin | PayDateTimeS | 付款起始時間，例如 2021/9/25 12:30 則為 202109251230。 |
| pay_datetime_end | PayDateTimeE | 付款結束時間，例如 2021/9/25 23:59 則帶 202109252359。 |
| pay_flag | PayFlag | 可接受的值為：Y、N、O。依付款的不同，查詢條件也不同，如下備註說明。 |
ATM 轉帳：A
Y：完成付款 (已轉帳)
N：未完成付款（未轉帳）
O：帳號逾期
信用卡：C
Y：已請款的訂單
N：未請款的訂單（含：未付款、待請款、取消授權、授權逾期）
O：刷卡逾期（信用卡付款逾期被取消的訂單）
程式碼範例：
圖 13-2: PHP SDK - 查詢批次訂單
QPay::queryOrderByToken(string $token)
使用 PayToken 查詢單筆訂單。
| 資料欄位 | 對應 API 的欄位 | 說明 |
|---|---|---|
| pay_token | PayToken | 查詢訂單的授權碼 |
參數只有一個。pay_token 是從建立訂單時，從永豐金收款平台跳轉回 return_url 帶上。或者建立訂單時提供 backend_url 欄位讓收款平台在收完款後主動通知提供該值。
程式碼範例：
圖 13-3: PHP SDK - 查詢單筆訂單
API 回應
在前一個文章段落介紹的建單過程取得永豐金收款平台的 API 回應後，資料欄位在 Message 且 SDK 已自動解密可直接取用。
<?php
if (!empty($results['Message'])) {
print_r($results['Message']);
}查詢批次訂單
圖 13-4: 查詢批次訂單 Messsage 欄位 (JSON 排版)
比較重要的欄位資訊為 PayStaus，須查詢 API 文件 第 54 頁的章節「交易狀態代碼說明」，以這個例子來說，IC400 代表信用卡請款完成。IA400 代表虛擬帳號付款完成。
查詢單筆訂單
圖 13-5: 查詢單筆訂單 Messsage 欄位 (JSON 排版)
圖 13-6: 文件第 30 頁
在 API 文件的第 30 頁有詳細的說明回傳的訊息內容判讀的方向。APType 和 Status 為最重要的回應欄位。
總結
以上就是 Sinopac PHP SDK 主要的功能。接下來在 Day 14，會使用 Pure PHP 建立模擬的網頁來演練一下實際的流程。根據國外的市場研究，WooCommerce 是目前市佔最高的電商解決方案，第二名為 Shopify，而在 Day 16，我們就要開始進入 WooCommerce 電商的世界囉。歡迎有興趣的朋友準時收看喔。
留言