最近一個專案要做只收 ATM 虛擬帳號付款的預約平臺，退款政策比較複雜：金額要照「離預約日剩幾天」動態計算，而人工算遲早會出錯。我們想用退款 API 自動處理，問題卡在這裡：提供 ATM 轉帳的金流平臺一大堆，能用 API 退 ATM 款的卻少之又少。
找了好幾家之後，發現藍新有提供智慧 ATM 2.0 的服務，它是目前少數能讓開發者直接打 API 退 ATM 款項的解決方案。這篇把實際串接時踩到的坑記下來，給同樣要接藍新金流的人少走一段冤枉路。
因為藍新客服的回覆速度是以「週」為單位的，等一個答案動輒五到七個工作天，整個串接節奏全被拖住，我把我們問到的細節整理出來，希望有需要的人不用再排這個隊。
為什麼非得用 ATM 退款 API
銷售端以前就幫客戶接過退費 API，省去人工計算，也避免算錯金額，這次的退款規則比較不同，同一筆訂單，今天退跟三天後退，金額不一樣，如果靠客服人工對著表算再手動匯款，量一大就是災難。所以從第一天我們就確定，退款這段一定要走 API。
研究過幾家金流後發現，提供 ATM 轉帳是基本盤，但 ATM 退款幾乎都要商家自己線下匯回去。藍新的智慧 ATM 2.0 是少數的例外。看完操作手冊，本來覺得問題解決了，真的動手串才發現，跟想像中差很多：
一、後台要先人工申請開通
第一個卡關的地方很基本：智慧 ATM 2.0 預設是關的，後台找不到開關。它得在藍新後臺送出人工申請，等審核通過才會開通這個服務。所以如果你照著文件接到一半發現參數送不出來，先別懷疑程式，去確認服務有沒有開通。
這一步沒寫在串接文件的顯眼處，加上審核要等，建議專案一開始就先去申請，不要等到要測退款才發現卡在審核。開通後，才能在後台的付款方式設定裡將「智慧ATM2.0」這個換成啟用：
二、串接文件沒寫：怎樣才算「智慧 ATM 2.0」
智慧 ATM 2.0 跟網路上能下載到的那份串接文件是同一份，但文件裡沒講清楚一件關鍵的事：要讓客戶走的是 ATM 2.0 而不是傳統 ATM 的話，到底該傳哪些參數？
問了客服才知道，必須同時滿足兩個條件，這筆交易才會被判定成智慧 ATM 2.0：
- 收單銀行必須是凱基銀行
- 請求要帶入
Source Type、SourceBankId、SourceAccountNo，填入顧客的銀行資料
少了任何一個，送出去的就只是一筆普通 ATM 交易，後面想退款也退不了。這層判定邏輯文件完全沒提，只能靠客服口頭確認。文件裡 SourceType 的值定義也很細——帶 1 或 3 時，SourceBankId 與 SourceAccountNo 才會變成必填，而且只有收單銀行是凱基時才會出現匯款帳號欄位。
還有一個更容易踩的雷：必須由網站這端記下客戶的轉帳帳號，呼叫退款 API 時把這個帳號帶回去，錢才會退回原本那位客戶的戶頭。
我原本的假設是這樣：凱基銀行收到款項時，會知道匯款人是誰，交易完成後把銀行帳戶的資料回傳給藍新記錄，等發起退款時，藍新就能用訂單編號自己找到當初的匯款戶頭退回去。實際上不是，後來藍新客服另外交付的退款 API 文件講得很明確——退款時要自己帶入匯款人的帳號。換句話說，匯款人帳號要由你的系統存下來，藍新不會幫你記。
三、ATM 退款 API 文件沒公開在網路上
承上一段，那份定義「退款要帶匯款人帳號」的退款 API 文件，並沒有公開在藍新官網，網路上也搜不到，不太確定原因。我們是跟客服往返好幾輪才拿到的。
而在網路上能下載到的那份串接文件，退款的部分就只有信用卡而已，並沒有提到「智慧 2.0」的退款方式，我不太確定為何他們沒有把這份退款 API 放在網路上，有需要的朋友可以透過以下連結下載：
非信用卡支付商店訂單退款技術串接手冊
四、其他要注意的細節
虛擬帳號最短一小時失效，只有 ATM 2.0 做得到
這個專案的訂單保留時間設計成一小時，傳統 ATM 的虛擬帳號最短只能設到 24 小時，兩者對不上的話結果就是：訂單已經被釋放了，付款用的虛擬帳號卻還有效。
後果很現實——客戶超過一小時才付款，回頭發現預約名額早就被釋出，糾紛就來了。目前能把虛擬帳號失效時間壓到最短一小時的，只有智慧 ATM 2.0，這也是我們最後非它不可的原因之一。
結帳流程要多兩個必填欄位
為了確保顧客收得到退款，結帳流程得多加兩個欄位，而且必須必填：
- 顧客銀行代號
- 顧客銀行戶帳號
沒有這兩個欄位，智慧 ATM 2.0 的退款功能就用不了。對某些平臺來說這是個門檻，因為很少有人背得出自己的銀行帳號，為了結帳特地去翻存摺或提款卡，這一來一往很可能讓一部分人放棄結帳，造成轉換流失。要不要為了自動退款承擔這個代價，是接智慧 ATM 2.0 之前得先想清楚的取捨。
踩坑清單
把這次串接藍新智慧 ATM 2.0 遇到的坑整理成一張清單：
- 服務要人工申請 —— 後台預設關閉，送審通過才開通，專案一開始就先申請
- 觸發 ATM 2.0 的條件文件沒寫 —— 收單銀行限凱基，且要帶
Source Type、SourceBankId、SourceAccountNo - 匯款人帳號要自己存 —— 退款 API 要帶匯款人帳號，藍新不會幫你記
- 退款 API 文件非公開 —— 官網搜不到，得跟客服索取
- 虛擬帳號最短一小時失效 —— 只有 ATM 2.0 支援，傳統 ATM 最短 24 小時
- 結帳要多兩個必填欄位 —— 銀行代號與帳號，可能影響轉換率
想更深入了解金流外掛從零到上線的完整架構，則可以參考WooCommerce 金流串接實戰系列，以及建立訂單時取得金流回傳資料的勾點這篇處理回傳資料的細節。智慧 ATM 2.0 的退款 API 屬於進階需求，等基本串接穩了再上會輕鬆許多。