開發指南
一、API介紹
| API 種類 | 說明 | 必要 |
|---|---|---|
| 付款API | POS 商透過掃碼設備取得用戶的支付條碼後，向街口支付發起付款請求，取得支付結果，透過商店端交易序號(MerchantTradeNo)作為請求唯一值，若請求重複則會返回相同交易處理結果。 | Y |
| 取消API | POS 商系統超時未收到支付結果(超過15秒)，向街口支付發起取消請求，取消該次交易，若未收到取消結果可多次輪循確保雙方交易結果一致性，取消成功後可再次發起新交易請求。 | Y |
| 退款API | POS 商根據實際業務情境，向街口支付發起退款請求，對原街口端交易序號進行退款，支持多次部分退款，但退款金額不可超過原支付金額。 | Y |
| 查詢API | POS 商對於交易結果進行查詢，需於交易發生後 15 秒後方可進行，確保查詢交易已經執行完畢。 | N |
二、流程說明
(1) 店家商戶建立業務商品訂單
店家生成業務商品訂單，並與用戶溝通商品的支付金額
(2) 用戶出示街口支付支付條碼
用戶打開街口支付 APP，提供付款碼讓店家端進行條碼掃描，掃碼設備將支付條碼傳入店家系統中
(3) 店家發起付款 API 請求
店家系統將支付條碼以及相關的支付訊息，完成加簽後，向街口支付發起支付請求
(4) 付款結果通知
街口支付處理完交易流程後，返回交易結果給到店家系統，並於用戶 APP 展示支付結果給到用戶
(5) 店家退款發起API請求
若於交易流程後，用戶有額外退款的要求，店家系統將相關退款訊息，完成加簽後，由店家系統發起退款 API 請求
(6) 交易結果查詢
若店家系統有出現交易狀態不明確時，可以透過查詢 API 來確定交易結果
三、交易異常處理
方案一：取消 API 取消訂單
若店家端於付款 API 當下發生超時行為或者是系統失敗錯誤，無法確定交易狀態結果為何，於系統超時(15秒後)，向街口發起交易取消，若未收到取消結果，可進行多次取消輪循，確保交易實際會取消成功，並線下由店員與用戶重新溝通發起第二次交易請求，街口方收到取消 API 請求後，會進行交易中斷處理，避免用戶發生重複扣款的行為，取消 API 於線下支付場景中，對於支付時效性的要求十分的高，因此為所有商戶必做的功能之一。
方案二：查詢 API 查詢結果
若店家端於付款 API 當下發生超時行為或者是系統失敗錯誤，無法確定交易狀態結果為何，於系統超時(15秒後)，向街口發起交易查詢，若未收到交易查詢結果，可進行多次取消輪循，由於部分店家實作線下交易並非時效性要求較高(如停車場繳費設備等)，因此可透過交易查詢 API 來進行實作，但若為用戶與店員面對面交易，建議一律採用取消 API 實作為主，獲得更快的處理效能
上述兩方案若交易失敗原因為業務原因(如:銀行餘額不足、用戶當月可支付額度不足)，POS 系統商應展示交易失敗原因給到店員進行查看
四、系統實作說明
(1) 特店代碼(MerchantCode)以及店鋪代碼(StoreID)差別
特店代碼是由街口方提供的參數，主要是用來街口用來區分合作特店為誰，會需要根據雙方業務合作條件來建立對應的特店代碼，一般而言，特店代碼的編立與合作公司的統編相同，店鋪代碼則是由店家端系統參數所建立的，對於街口而言店鋪是交易歸屬的最基礎單位，後續街口會根據財務需求進行對應店鋪的歸屬，一般而言，店鋪代碼是根據店家對於交易的歸屬進行拆分的單位。
(2)商店端交易序號(MerchantTradeNo)的業務含義
對於店家端而言，交易時會先成立商品訂單號(例如:一份餐點、一瓶水等等)，該筆商品允許使用多種支付方式，對於街口而言，每一筆的商店端交易序號代表著交易流水號，每一筆新的單號會視為一次新的支付請求，因此務必確保交易序號為唯一值，避免用戶發生重複扣款的情境，若於付款 API 發生交易序號重複的情況，街口方會返回原先交易序號的交易結果，因此需要商店端實作何時該判斷唯一個新的交易請求。
需要特別注意，在付款 API 以及退款 API 中，雖然同時需要店家端傳輸 MerchantTradeNo，但是兩者業務含義不同，一個是付款流水號，另一個則為退款流水號，在退款 API 中，由於存在部分退款的情境，因此若為多次部分退款，需要每次變更不同的退款流水號。
(3) 不可折抵金額(unredeem)說明
在業務情境中，部分交易不允許使用折抵方式(例如:菸、酒等商品)，由於街口有多種折抵方式，若店家端不允許該筆交易使用折抵方式，則需要在付款請求時帶入對應的不可折抵金額
(4) 折抵方式(redeemName)說明
在業務情境中，折抵方式可區分為街口折抵、店家折抵、街口折抵加上店家折抵，對於交易端而言並無影響，對於店家帳務端而言，折抵方式區分的主要目的為折抵金額實際承擔方為誰，街口折抵代表該折抵金額由街口來承擔，店家折抵則為店家承擔，該欄位是否出現需要依照雙方業務合作行銷模式而定。
(5) 載具付款合併說明
街口會於付款完成後傳輸載具，店家端可於系統中實作商品付款後，自行上傳雲端發票，不需要用戶另行出示載具條碼提供給到店家進行二次掃描，加速整體結帳速度。
(6) 取消 API 與退款 API 實作差異
取消 API 的應用情境主要用於系統超時以及失敗，針對原先交易不明確的情況進行整單取消處理，避免重複扣款以及加速整體支付時效用途，且街口方會針對取消 API 去做特別監控，避免異常發生，而退款 API 的應用主要是針對於用戶真實需要發起退款，店家系統方需要傳輸退款訂單號，作為後續對帳處理用，因此實作部分需要店家按照個別情境來分別處理。