第一網第一網
第一網編輯部

綠界金流串接申請流程、帳戶類型選擇、API 技術錯誤排除與電子發票自動化設定指南

綠界金流串接申請流程、帳戶類型選擇、API 技術錯誤排除與電子發票自動化設定指南

依收款規模與營利事業登記狀態選擇個人或企業帳戶

選擇綠界金流帳戶的第一步是確認您的法律身份。如果您是尚未辦理營業登記的個人賣家,僅能申請「個人會員」,這類帳戶的信用卡收款額度通常受到嚴格限制(單筆與每月總額),且無法開立電子發票。擁有統一編號的企業或行號應申請「商務會員」,才能獲得完整的 API 權限、較高的收款額度,以及串接電子發票系統的功能。

比較項目個人會員商務會員(公司/行號)
收款工具信用卡、ATM、超商代碼/條碼信用卡(含分期)、ATM、超商、Apple Pay、Google Pay
信用卡手續費約 2.75% - 3.5%(依活動變動)約 2.0% - 2.8%(依產業與交易量議定)
電子發票功能可加購串接 API 自動開立
提領天數約 T+7 至 T+12約 T+4 至 T+7(視銀行合約而定)
單筆收款上限較低(通常 5 萬以下)依銀行審核結果而定,彈性較大

若您的月營額超過新台幣 8 萬元(銷售貨物)或 4 萬元(銷售勞務),依規定必須辦理稅籍登記,此時應直接申請商務會員。商務會員需準備公司大、小章、負責人身分證影本、公司登記證明文件以及撥款用的銀行存摺影本。審核時間通常需要 3 到 7 個工作天,建議在網站上線前兩週完成申請。

評估站內付 2.0 或全方位金流跳轉頁面的轉換率影響

串接模式決定了消費者的結帳體驗。目前主要的兩種串接方式為「全方位金流(Redirect)」與「站內付 2.0(In-Page)」。全方位金流是將消費者引導至綠界的支付頁面,完成後再跳回官網;站內付 2.0 則允許消費者直接在您的官網輸入卡號。兩者的選擇應基於技術開發能力與對轉換率的要求。

  • 全方位金流(適合初創企業):開發成本最低,綠界負責處理所有的資安合規(PCI-DSS),您不需要在伺服器上處理卡號資訊。缺點是多一次跳轉可能導致部分消費者因網路不穩或疑慮而放棄交易。
  • 站內付 2.0(適合追求轉換率):消費者留在官網結帳,品牌感較強,結帳流程更流暢。但技術門檻較高,需要前端技術配合綠界的 SDK,且必須確保網站具備 SSL 憑證,並通過綠界的資安環境審核。

如果您的網站使用 WordPress (WooCommerce) 或 OpenCart 等常見電商系統,通常有現成的外掛模組支援全方位金流。若是自行開發的官網,則需權衡 UI/UX 設計師與後端工程師的工時成本。對於單價較高的商品,建議使用站內付 2.0 以減少跳轉過程中的流失率。

排除 API 串接失敗與 HashKey/HashIV 加密驗證問題

在技術對接階段,超過 80% 的串接失敗原因在於「CheckMacValue」驗證錯誤。綠界要求所有傳輸的參數必須依照字典順序(A-Z)排列,並結合 HashKey 與 HashIV 進行加密。只要有一個參數大小寫不符,或是多了一個空白字元,交易就會被擋下。

檢查 API 串接的四個關鍵步驟:

  • 確認參數大小寫:綠界 API 區分大小寫,例如 MerchantID 必須是大寫 M 與大寫 I,若寫成 merchantid 將導致驗證失敗。
  • 檢查 ReturnURL 設置:這是綠界回傳交易結果給您伺服器的位址。該網址必須是公開的(Public URL),不能是本機端(localhost)或受防火牆保護的內部網路,且必須支援 HTTPS。
  • 測試環境與正式環境切換:測試時使用的 MerchantID、HashKey、HashIV 與正式環境完全不同。請務必確認在上線前已將 Stage 環境的網址更換為 Production 環境。
  • 編碼格式:所有參數傳輸必須使用 UTF-8 編碼,且在計算 CheckMacValue 前需進行 URL Encoding。

若遇到「交易失敗」或「參數錯誤」,請優先檢查綠界後台的「系統日誌」,那裡會顯示具體的錯誤代碼(如:10100073 代表 CheckMacValue 錯誤)。

整合電子發票自動化開立以降低人工對帳成本

當交易量達到每日 10 筆以上時,人工手動開立發票將成為營運瓶頸。綠界提供的電子發票 API 可以與金流串接同步運作。當金流回傳付款成功(ReturnURL 收到狀態 1)時,系統可自動觸發發票開立請求。這不僅能減少漏開發票的稅務風險,也能自動處理作廢與折讓。

導入電子發票自動化的成本取捨:

項目手動開立(透過綠界後台)自動化串接(透過 API)
人力成本高,需專人逐筆輸入極低,系統自動處理
錯誤率高,人為輸入可能出錯低,直接引用訂單資料
開發成本需工程師撰寫串接邏輯
適用對象初期創業、月訂單量低於 100 筆穩定成長、月訂單量大於 100 筆

在設定自動化開立時,建議設置「延遲開立」。因為電商通常有 7 天鑑賞期,若付款成功後立即開立發票,一旦發生退貨,您還需要額外處理發票作廢。建議將發票設定為「付款後 7-10 天自動開立」或「出貨後開立」,這能大幅減少行政作業量。

串接測試環境與上線審核的具體步驟

在正式對外收款前,必須先在綠界提供的 Stage 測試環境中模擬所有可能的交易情境,包含刷卡成功、刷卡失敗、超商條碼逾期等。測試環境不需要真實扣款,但能驗證您的伺服器是否能正確接收並解析綠界回傳的通知訊號(Webhook)。

上線前的自我檢核清單:

  • ClientBackURL 與 OrderResultURL:確認消費者在支付完成後,點擊「返回商店」能回到正確的頁面,而非顯示 404 錯誤。
  • 金流通知(Webhook)防重發機制:綠界的伺服器若沒收到您回傳的 1|OK,會持續發送通知。您的系統必須能辨識重複的通知,避免產生重複發貨或重複入帳的問題。
  • 信用卡分期設定:若有開啟分期功能,需確認後台設定的利率與分期期數是否與前端頁面顯示一致。
  • 物流整合測試:若同時串接綠界物流,需確認收件人姓名是否符合超商規範(不能有特殊符號,長度需在 2-10 個中文字之間)。

完成測試後,請登入綠界廠商後台下載「正式環境金鑰」,並將網站的 API 介接網址更換。注意,正式環境的金鑰應妥善保管,切勿上傳至公開的程式碼倉庫(如 GitHub),以免造成信用卡扣款權限外洩的資安事故。

綠界金流串接申請流程、帳戶類型選擇、API 技術錯誤排除與電子發票自動化設定指南 | 第一網