不管是哪一家軟體公司或是金物流廠商，只要他們有提供 API 介面來服務外部網站，通常一定會有串接文件可讓開發者參考，串接文件就像是 API 使用說明書，讓開發者可以知道該怎麼與手邊的系統進行整合。
串接文件通常有分線上版與離線版，離線版就是會拿到一份 PDF 或 Word 檔，台灣金流業者多半是這種類型，可以直接在官網下載。另外有些廠商可能有某種商業考量，會需要申請並審核通過後才能取得他們的串接文件。
還有的是在官網找不到文件下載的連結，只能透過業務窗口取得，總之不管文件的形式為何，當我們的客戶說想要串接金流或是其他的服務時，第一個首要之務就是取得串接文件，有串接文件我們才能評估工作項目。
其次，如果拿到的文件是離線檔案，務必要確認是否為最新版本，我就曾經發生過拿到舊的版本結果一直無法順利串接的情況，正常情況下廠商的 API 介面只會新增不會修改或刪除既有的方法，但還是讓我遇到了，因此一定要跟客戶確認文件是否為最新版本。
有了文件之後還需要取得客戶的使用名稱與密鑰，如果以金流為例，通常會有商家代號以及串接密鑰，前者是金流商辨識客戶的依據，後者是拿來算出加密演算法的參數之一，而金流商會用這個密鑰算出來的值來作為請求付款的身份驗證，所以取得與客戶身份相關的串接資料是必要的。
正常情況下，廠商提供的 API 會有分正式與測試環境，通常是用請求路徑來區分，如果是接金流的話，還會有測試卡號來驗證刷卡是否正常運作，而不用掏自己的信用卡，但也遇過沒有測試卡號只能用一元訂單來測試的廠商，這些資訊在串接前最好都能請客戶先跟廠商確認，不然串接到一半才發現這些資訊有誤的話，會浪費很多時間在進行除錯。
接下來，當我們拿到文件後，必須先理解這家廠商的 API 邏輯，理解後我們才能比較準確的進行任務拆解與工時評估，通常我會注意文件的以下幾個重點：
根據流程圖可以先大概掌握要在什麼時間點把訂單資料送給金流商、在哪個階段做授權驗證以及接收回傳資料的時機，台灣的第三方金流多半是訂單傳送時同時做授權驗證，驗證成功後交給金流商跳轉到付款頁，現在市面上也有陸續出現直接在客戶網站內完成結帳的服務，只要看流程圖我們大概就可以知道客戶網站跟金流廠商之間的資料是如何傳送的。
這是金流商用來驗證從客戶傳過去的資料是否為客戶網站，不同的廠商名稱可能不太一樣，有叫檢查碼的，還有檢核碼、加密法、簽名演算法一堆名稱，文件會說明該如何將傳送資料做大小寫排序、經過組合客戶密鑰、URL Encode、產生雜湊值、轉換大小寫等一堆折騰人的過程，比較貼心的廠商會提供程式範例，我會把這範例寫成一個靜態方法，之後在做驗證時就可以重複利用。
通常要傳給金流商的參數很多，但不外乎就是訂單的相關資料，我會注意有沒有比較特別的欄位，也就是 WooCommerce API 無法一行程式拿到的資料，這種會增加開發時數的欄位要及早發現，還有就是設定付款方式的欄位該如何使用、資料類型為何、有沒有什麼限制，尤其是限制的部分，會需要在資料傳送前先做檢核，像是姓名長度、電話號碼的格式等等，這些都需要計入工作項目之中。
根據客戶的商業情境不同，可能會需要取得刷卡的後四碼或是交易流水號以方便客戶對帳，所以要預先知道能取得的回傳資料有哪些，才能把訂單欄位建立好並寫入資料庫。
串接文件通常會有狀態碼對應訊息的表格，用來說明當 API 回應某些狀態碼時代表的是什麼意思，我會特別關注交易失敗的狀態碼，像是卡號錯誤、信用卡驗證碼錯誤等等的訊息，以便在接受回傳資訊時可以把交易失敗的例外狀況考慮進去，再根據狀態碼來顯示訂單交易失敗的原因，這樣當出問題時才能進行追蹤。
看完文件後，對於該如何串接這個廠商的 API 心裏大概就會有個底，接下來我把開發任務拆解為四大類：
這個階段會包含三個工作，分別是確認完成驗收標準、金流串接相關資料交付確認以及開發環境與程式碼部署配置。首先要跟客戶確認需要串接的付款方式有哪些，以及採用使用者故事來描述顧客結帳流程以及管理者的操作行為。通常金流商提供的付款方式很多種，每種的使用費用不太一樣，客戶會因成本考量有可能全接或是只接部分的付款方式。
另外還需確認付款的介面設計、顧客完成後的顯示欄位以及後台訂單對帳資訊，因為我們已經先行閱讀過文件了，所以可以跟客戶主動建議哪些資料可以顯示以採取對應的作法。
其次的金流串接相關資料交付最好在開工前取得，並且確保是正確的資料，避免串接到一半發生問題，而這部分的工時就是遇到這種狀況的緩衝。
最後的開發環境與程式碼部署配置在後續的文章會提及，主要就是建立開發 WooCommerce 的環境配置。
前台的介面是在 WooCommerce 結帳頁增加金流選項，以及會根據不同的付款方式顯示不同的介面，像是分期付款的選擇期數，後台的介面是讓客戶可以自行輸入商代代號、密鑰以及切換正式或測試環境的設定，後台的介面事實上不一定需要，但有的話可以省下日後修改程式的時間，而且如果未來要發行此外掛的話，設定介面是必須的項目。
這部分包含了串接文件中的實作，像是加密演算法、整理傳送資料與接收回傳資料，以及交易失敗的處理，通常不同付款方式的傳送與接收資料回不大相同，而且還會分即時回傳以及非同步回傳的狀態，像是信用卡結完帳就能立刻取得交易結果，但是 ATM 轉帳或是超商代碼繳費就必須等到顧客真的去付錢後金流商才會回傳資料，所以這部分我會根據不同的付款方式來進行工時預估。
主要包含寫自動化測試與人工測試交易失敗是否有出現正確的提示訊息，以及嘗試著用一些手法像是將訂單金額改為 0 元訂單看能否成功交易，最重要的是測試正式環境的運作是否一切正常，這時前置作業中的確認完成驗收標準就可以當作是測試清單，來確保交易如預期中的結果。
當理解金流串接文件以及確認客戶需求後，下一篇文章我們開始來搭建 WordPress 的本機開發環境，並且運用一些自動化指令碼讓 WooCommerce 開發環境可以自動一鍵安裝完成，省去手動處理的時間。
本文同步發表於：https://oberonlai.blog/tw/woocommerce-payment-document
iThome鐵人賽
看影片追技術