# 全方位金流API技術文件 /準備事項 / 介接注意事項

####

## 呼叫綠界 API

- 請確認各項交易參數傳送時是使用 Http POST 方式傳送至綠界API。
- 傳送參數值的內容不允許使用 html tag 標示，例如：<br><h1>
- 請勿將重要的加密金鑰資訊(例如:HashKey及HashIV)存放或顯示於前端網頁內程式碼內例如：JavaScript、HTML、CSS…等，避免金鑰被盜取使用造成損失及交易資料外洩。
- 若為平台商身分(也就是建立訂單時使用平台商編號 PlatformID)，請使用PlatformID配對的 HashKey 及 HashIV 產生CheckMacValue。PlatformID為平台商所綁的會員編號MerchantID。
- 傳輸參數不支援特殊符號，若使用會造成建立訂單錯誤。
- 參數內容若有包含%26(&)及%3C(<) 這二個值時，請先進行urldecode() 避免呼叫API失敗。
- 信用卡記憶卡號功能，若特店有開 OTP 簡訊驗証時，可不用輸入信用卡安全碼。
- 合作特店須進行主機「時間校正」，避免主機產生時差，延伸 API 無法正常運作。
- 為保障消費者權益與網路交易安全，綠界串接服務只支援 TLS 1.2 加密通訊協定。
- 假如程式呼叫 API 的速度太快(不包含建立付款訂單)，會收到 HTTP Status Code 403 的狀態碼，此時請降低呼叫 API 的速度，並等候 30 分鐘後再重新呼叫，如果有高速存取 API 的需求，請先確認您具備「特約賣家」身分，並聯繫所屬業務人員。
- 若呼叫綠界API作業([交易](https://developers.ecpay.com.tw/?p=2864.md)/[請款/退款](https://developers.ecpay.com.tw/?p=2885.md)/[補授權/停用](https://developers.ecpay.com.tw/?p=2900.md))時未收到回應結果時，可透過[查詢訂單](https://developers.ecpay.com.tw/?p=2887.md)相關API查詢結果。

## 特店防火牆設定說明

- 特店防火牆如需連到綠界主機，因為綠界主機 IP 不固定，請以 FQDN 方式設定以下 domain：
    正式環境 ：payment.ecpay.com.tw TCP 443
    測試環境：payment-stage.ecpay.com.tw TCP 443
    如貴司防火牆需固定IP，請至線上回報 <https://member.ecpay.com.tw/ServiceReply/CreateProblem> 申請，問題類別及子類別請選擇：申請主機IP鎖定。
- 特店防火牆如需允許綠界主機連入，請設定以下 domain 放行：
    正式環境：postgate.ecpay.com.tw TCP 443
    測試環境 ：postgate.ecpay.com.tw TCP 443 ，postgate-stage.ecpay.com.tw TCP 443
    如貴司防火牆需固定IP，postgate IP 不須另外申請，請自行使用ping指令查詢IP的位址。

## 付款完成通知回傳網址\[ReturnURL\]

- 付款結果通知回傳網址ReturnURL為特店的Server或主機的URL，用來接收綠界後端回傳的付款結果通知。測試呼叫綠界API時請確認ReturnURL的連線已開放對外。
- 若賣家使用CDN服務(Content Delivery Network)，也就是賣家的主機不在台灣、但透過CDN服務提供網站資料給台灣或相鄰地區的使用者，ReturnURL請設定主機的URL，不設定為CDN網址以避免主機無法接收付款結果。
- ReturnURL的接收程式接收綠界後端回傳的付款結果參數後，必須依據收到的參數運算產生檢查碼CheckMacValue，並判斷CheckMacValue是否與綠界回傳的CheckMacValue相符。若相同才回傳 1|OK 給綠界。
- 綠界API僅支援HTTP及HTTPS (80 port及443 port)；ReturnURL請避免指定port否則導致無法接收綠界回傳付款結果通知。
- ReturnURL不支援中文網址，若為中文網址參數請使用 punycode 編碼後的網址，例如中文.tw 改成 xn--fiq228c.tw。

## 綠界CDN(Content Delivery Network)會導致阻擋特殊字元或規則

- 檢測用於執行系統指令/工具的字詞：

    - ‘net localgroup’ (Windows command to modify local groups)
    - ‘net.exe’ (Windows Net command)
    - ‘nmap.exe’ (NMap executable for Windows)
    - ‘nc.exe’ (NetCat executable for Windows)
    - ‘traceroute’ and ‘tracert’ (Traceroute utility)
    - ‘telnet.exe’ (Windows Telnet client)
    - ‘tclsh’ and ‘tclsh8’ (Simple shell / TCL interpreter)
    - ‘tftp’ (Trivial FTP client)
    - ‘wguest.exe’ (Webcom Guestbook CGI – contains a known command injection vulnerability)
    - ‘wsh.exe’ (Windows Script Host)
    - ‘rcmd.exe’ (Windows NT remote command utility)
    - ‘ftp.exe’ (Windows FTP client)
    - ‘echo’ (Shell echo command)
    - ‘cmd32.exe’ or ‘cmd.exe’ (Windows command shell)
    - ‘cmd’ with the ‘/c’ switch (Windows command shell)
    - ‘cd’ and a trailing slash (/) or backslash (), or a trailing double-dot (..)
    - ‘chmod’ with the ‘+x’ switch (Unix change file mode)

- 檢測使用 Shell 相關的字符來附加於原始輸入的指令，字符包括分號 ( ; ), pipe ( | ), 反引號( ` )：

    - ‘chgrp’
    - ‘chmod’
    - ‘chown’
    - ‘csh’
    - ‘cmd’
    - ‘cpp’
    - ‘passwd’
    - ‘python’
    - ‘perl’
    - ‘ping’
    - ‘ps’
    - ‘nasm’
    - ‘nmap’
    - ‘nc’
    - ‘finger’
    - ‘ftp’
    - ‘kill’
    - ‘mail’
    - ‘xterm’
    - ‘rm’
    - ‘ls’
    - ‘lsof’
    - ‘telnet’
    - ‘uname’
    - ‘echo’
    - ‘id’
    - ‘g++’
    - ‘gcc’