綠界科技 ecpay 全方位金流 - 非信用卡介接技術文件 ·...

綠界科技股份有限公司 Green World FinTech Service Co., Ltd.

綠界科技全方位金流

非信用卡介接技術文件

V 5.1.26

文件編號 gw_p120

2019-12-17

I

目錄

1. 簡介................................................................................................................................................ 1

2. 交易流程說明................................................................................................................................ 2

3. 前置準備事項................................................................................................................................ 7

4. 產生訂單........................................................................................................................................ 8

5. ATM、CVS 或 BARCODE 的取號結果通知 ................................................................................. 19

6. 付款結果通知.............................................................................................................................. 22

7. 查詢訂單(可依需求來決定是否撰寫此 API) ............................................................................. 25

8. 額外回傳的參數.......................................................................................................................... 27

9. 檢查碼機制.................................................................................................................................. 29

10. 下載特店對帳媒體檔.................................................................................................................. 31

附錄 1. 關鍵字一覽表...................................................................................................................... 35

附錄 2. 交易狀態代碼表.................................................................................................................. 35

附錄 3. 付款方式一覽表.................................................................................................................. 36

附錄 4. 回覆付款方式一覽表.......................................................................................................... 37

附錄 5. URLEncode 轉換表 .............................................................................................................. 38

II

Version History：

Version Date Content

V2.0.0 2016/08/19 Create

V2.0.1 2016/10/24 移除取得檢查碼 API

V2.0.2 2016/10/28 付款通知結果主機 dns 更換為 postgate.ecpay.com.tw

V2.0.3 2016/11/03 增加付款結果通知參數範例

V2.0.4 2016/11/10 增加建立訂單付款方式欄位注意事項，若為手機版時不支援 Barcode 及 WebATM 付款

方式

V2.0.5 2016/11/16 增加查詢信用卡單筆明細記錄及下載信用卡撥款對帳資料檔二支 api

V2.0.6 2016/12/12 檢查碼加密方式改為必填且用 sha256 方式加密

V2.0.7 2017/02/17 新增 Stage 環境平台商使用之測試帳號

V4.0.0 2017/02/22 V4 版本:增加建立訂單信用卡記憶欄位

V4.0.1 2017/02/23 新增 Stage 環境平台商使用之測試帳號

V4.0.2 2017/03/09 修正查詢訂單網址為 V4 版本，增加使用信用卡記憶欄位使用限制說明

V5.0.0 2017/04/25 V5 版本:增加客制化使用欄位、店家代碼(門市/分店)

V5.0.1 2017/05/02 信用卡定期定額增加使用限制說明

V5.0.2 2017/05/05 新增定期定額停用說明、下載對帳媒體檔 IP 限制說明、優化發票開立說明。

V5.0.3 2017/05/19 參數[ChooseSubPayment]、[AllocateStatus]敘述調整，對外 IP 更新。

V5.0.4 2017/05/24 前置準備事項增加注意事項說明，傳輸參數不支援特殊符號

V5.0.5 2017/06/01 增加付款方式 AndroidPay

V5.0.6 2017/06/05 調整『退刷』[InvoiceTaxType][CarruerNum]敘述

V5.0.7 2017/06/15 信用卡分期參數使用調整

V5.0.8 2017/06/28 移除信用卡分期付款金額 InstallmentAmount 參數

V5.0.9 2017/06/29 優化載具類別說明

V5.1.0 2017/07/10 優化信用卡關帳/退刷/取消/放棄 API 的關帳說明

下載特店對帳媒體檔 API 增加回傳欄位

額外回傳的參數說明調整 V5.1.1 2017/07/24 文件內容描述調整，如特店改為特店，綠界改為綠界

V5.1.2 2017/08/29 調整建立訂單開立發票參數[Print]、[Donation]、[CarruerType]說明

V5.1.3 2017/09/18 優化[ClientRedirectURL]、[OrderResultURL]、[TradeDesc]、[MerchantTradeNo]內容。

V5.1.4 2017/11/10 優化文件欄位描述，並增加客製化欄位支援特殊符號項目說明

V5.1.5 2017/11/16 電子發票開立欄位捐贈碼編碼規則調整

V5.1.6 2017/12/06 電子發票開立欄位捐贈註記代碼調整

V5.1.7 2017/12/11 新增銀行 ATM 虛擬帳號使用注意事項

V5.1.8 2017/12/25 優化第 5、13、15 章描述。

V5.1.9 2018/01/16 優化第 6 章內容

V5.1.10 2018/01/22 增加推薦捐贈碼說明

V5.1.11 2018/02/05 調整下載會員對帳媒體檔注意事項說明

III

V5.1.12 2018/03/01 調整注意事項表格格式

增加前置準備注意事項說明，串接只支援 TLS 1.2 以上之加密通訊協定

V5.1.13 2018/03/19 新增交易金額說明 WEBATM/ATM 最低交易金額限制 5 元

V5.1.14 2018/03/27 調整電子發票載具編號參數說明，增加綠界科技會員載具編號的編碼說明

V5.1.15 2018/04/30 調整產生訂單交易金額 CVS /BARCODE 限制說明

增加 ATM、CVS 或 BARCODE 的取號結果通知注意事項說明

V5.1.16 2018/05/03 1. 因應財政部修法將「無實體電子發票」更名「雲端發票」，「愛心碼」更名「捐贈

碼」，「社福團體」更名「受捐贈機關或團體」

2. 產生訂單 API 移除 HoldTradeAMT 延遲撥款參數及申請撥款 API

V5.1.17 2018/08/06 調整電子發票參數[Customer]客戶名稱長度由 30 字元改為 60 字元

修正電子發票參數 InvoiceItemTaxType、TaxType 說明內容

調整產生訂單交易金額 CVS /BARCODE 限制說明 V5.1.18 2018/09/11 修正電子發票參數 ClearanceMark 通關方式的說明內容

V5.1.19 2018/11/05 調整 StoreID 欄位名稱及說明

V5.1.20 2019/03/06 調整載具編號說明內容

V5.1.21 2019/04/19 增加載具編號注意事項說明

V5.1.22 2019/07/29 修改產生訂單參數[TotalAmount]說明欄/檢查碼機制計算範例

優化產生訂單使用 iOS 注意事項說明

V5.1.23 2019/08/14 移除 InvType 參數 08 特種稅額發票、ItemName 參數新增說明事項

新增前置準備事項欄位說明、新增產生訂單 iOS 注意事項修正

V5.1.24 2019/08/20 修改第 3 章前置處理事項的特店管理後台登入帳號

V5.1.25 2019/11/27 修改 Barcode 手機條碼說明

修改[ItemName]參數說明

各章節 POST 欄位增加可支援的格式說明

V5.1.26 2019/12/17 調整非信用卡 StoreExpireDate 參數說明

調整欄位書籤連結

綠界科技股份有限公司

Green World FinTech Service Co., Ltd.

綠界科技全方位金流整合介接技術文件 1 / 38

1. 簡介

綠界金流服務對於有收款需求的賣家，提供完整的交易介接技術，並提供多種收款方式供賣家

選擇，包含信用卡、網路 ATM、ATM 櫃員機、超商代碼、超商條碼、AndroidPay(限手機使用)

等，本文主要說明非信用卡收款方式介接規格，與各種交易 API 的使用時機及方法。

[圖 1-1]交易示意圖




2. 交易流程說明

一般訂單產生流程

綠界金流系統特店系統消費者

成功

失敗

7顯示付款畫面

3訂單資料

9確定繳費

4接收訂單資料

8選擇付款方式

11背景通知會員系統付款結果

5檢核資料

10更新付款狀態

開始

1確定消費 2建立訂單

結束

12付款資料13背景接收付款結果

ReturnURL

15顯示結果畫面OrderResultURL

14返回會員系統畫面

6建立訂單

[圖 2-1]一般訂單系統介接循序圖




處理角色流程名稱處理說明

消費者 1.確定消費消費者確定消費付款。

特店 2.建立訂單收到消費者的請求並建立訂單。

特店 3.傳送訂單建立訂單後，傳送訂單資料至綠界，透過綠界提供的 API (AioCheckOut)

開始付款。

ECPAY 4.接收訂單接收並解析傳送過來的訂單資料。

ECPAY 5.檢核資料

檢核訂單資料正確性，正確則進入下個處理流程，不正確則停止付款

交易並回傳錯誤資訊。

ECPAY 6.產生訂單於綠界產生特店的訂單。

ECPAY 7.顯示付款畫面顯示付款頁面提供消費者操作。

消費者 8.選擇付款方式選擇要使用的金流付款方式。如果訂單資料已有傳送指定付款方式

[ChoosePayment]時就不用作選擇。

消費者 9.確定繳費消費者依據選擇的付款方式作繳費。

ECPAY 10.更新付款狀態依消費者使用的付款方式，更新訂單的付款狀態。

ECPAY 11.背景通知特店付款

結果綠界確認消費者付款完成後，會以背景(Server POST)通知特店。

ECPAY 12.付款資料綠界透過訂單資料設定的回傳位址[ReturnURL]通知送至特店。

特店 13.背景 (Server POST)

接收付款結果接收並解析付款結果通知資料，並更新訂單付款狀態。

ECPAY 14.返回特店畫面

前景(網頁)重新導向至付款結果網址[OrderResultURL]，如果付款結果

網址[OrderResultURL]參數沒有值時，會導向綠界的付款結果頁。付款

結果頁可以顯示「返回商店」按鈕，條件是訂單資料的返回特店網址

[ClientBackURL]要有填值。

特店 15 顯示結果畫面收到重導向請求後，顯示付款結果畫面讓消費者知道交易已經完成。




ATM/CVS/BARCODE訂單產生流程

銀行系統/超商系統

綠界金流系統特店系統消費者

成功

失敗

7顯示付款畫面 6建立訂單

9確定付款方式

8選擇付款方式

10更新付款方式

開始

3訂單資料 4接收訂單資料

2建立訂單1確定消費

5檢核資料

11背景通知會員系統付款方式

12付款方式資料13背景接收付款方式資料

PaymentInfoURL

結束

14返回會員系統畫面

15顯示結果畫面ClientRedirectUR

L

16依付款方式繳費

17確認付款資料

18背景通知付款結果

19背景接收/ 處理付款結果

21背景接收付款結果

ReturnURL

20背景通知會員系統付款結果

22商品出貨或會員系統其他處理流程

[圖 2-2]ATM/CVS/BARCODE 系統介接循序圖





消費者 1.確定消費確定消費付款。

特店 2.建立訂單收到消費者的請求並建立訂單。

特店 3.訂單資料建立訂單後，準備好訂單資料，透過綠界提供的 API

(AioCheckOut) 開始付款。

ECPAY 4.接收訂單資料接收並解析特店傳送過來的訂單資料。

ECPAY 5.檢核資料檢核特店的訂單資料正確性，若資料有異常，則停止付

款交易，否則進入下個處理流程。

ECPAY 6.建立訂單確立訂單資料無誤後，於綠界建立特店的訂單。

ECPAY 7.顯示付款畫面訂單建立後，依據訂單資料所傳遞的付款方式，顯示可

使用的金流付款功能，供消費者選擇付款。

消費者 8.選擇付款方式

選擇要使用的付款方式。

如果訂單資料已有傳送指定付款方式[ ChoosePayment]

時就不用作選擇。

消費者 9.確定付款方式依選擇的付款方式進行繳費。

ECPAY 10.更新付款方式依據消費者選擇的付款方式,確定並更新付款方式。


方式確定付款方式後,綠界於背景通知特店。

ECPAY 12.付款方式資料

綠界系統準備好消費者選擇的付款方式及繳費資訊等

資料後 , 透過訂單資料設定的回傳位址

[PaymentInfoURL]送至特店。

特店 13.背景接收付款方式

資料

接收並解析綠界傳送過來之消費者所選擇之付款方式

及繳費資訊。

ECPAY 14.返回特店畫面

綠界於背景通知特店消費者所選擇的付款方式及繳費

等資訊後,於前景重新導向至訂單資料設定的繳費資訊

通知網址[ClientRedirectURL]。

特店 15.顯示結果畫面顯示繳費資訊等結果畫面。使消費者得知該筆訂單的繳

費相關資訊,以後續進行付款相關作業

消費者 16.依付款方式繳費依據特店所接收到之繳費資訊,依付款方式完成繳費

銀行系統/

超商系統 17.確認付款資料

確定付款後,銀行系統接收消費者付款資訊,依照對應的

付款方式,確定並更新付款狀態。

銀行系統/

超商系統 18.背景通知付款結果銀行系統/超商系統於背景通知綠界。

ECPAY 19.背景接收 /處理付

款結果

接收並解析銀行系統傳送過來的付款資料等相關繳費

資訊


結果

準備好消費者付款完成的資料後,透過訂單資料設定的

回傳位址[ReturnURL]送至特店。

特店 21. 背景(Server POST)

接收付款結果

接收並解析綠界傳送過來的付款資料，並更新訂單付款

狀態。





特店 22.商品出貨或和做特

店其他處理流程

接收綠界傳送之付款狀態並更新訂單付款狀態後,後續

進行出貨或其他處理流程。




3. 前置準備事項

系統介接測試環境相關資訊：

欄位說明欄位內容

特店編號(MerchantID) 2000132 2000214(非 OTP)

平台商編號

(PlatformID) 3002599

特店管理後台

登入帳號/密碼 stagetest1234/test1234 Stage2000214/test1234 stagetest2/test1234

身分證件末四碼/統一編

號 53538851 3609

特店管理後台

測試環境

https://vendor-stage.ecpay.com.tw

此網站可提供：1. 查詢 ecpay 訂單，2. 模擬付款並通知特店

若執行模擬付款功能，無法收到付款通知時，請留意此表後注意事項。

ALL IN ONE

介接 HashKey 5294y06JbISpM5x9 spPjZn66i0OhqJsQ

ALL IN ONE

介接 HashIV v77hoKGq4kWxNNIS hT5OJckN45isQTTs

對外 IP 請參考綠界 FAQ：是否可限制只允許綠界 IP 連入公司的 Server

※注意事項：接收傳送 API 通知時，請確認下面事項，以利正常收到各項通知：

(1) 請確認訂單產生的付款完成通知回傳網址[ReturnURL]已開放對外連線。

(2) 請確認 Server 是否有開通防火牆綁定 postgate.ecpay.com.tw，以避免付款通知被防火牆阻擋，請勿直接綁定 IP。

(3) 呼叫綠界 API 連接只提供 https (443 port)連線方式，並請使用 DNS(Domain Name System)進行介接。

(4) 請確認各項交易參數傳送時是使用 Http POST 方式傳送至綠界 API。

(5) 請確認 Server URL 連接 port 為 http 80 port 與 https 443 port。

(6) 傳送參數值的內容不允許使用 html tag 標示，例如<br /> <B> <h1> …等。

(7) 請勿將金鑰資訊存放或顯示於前端網頁內，如 Javascript、html、Css…等，避免金鑰被盜取使用。

(8) 當有傳送平台商編號 PlatformID 參數時，請使用平台商的 HashKey 及 HashIV 並產生檢查碼計算，[PlatformID]為

平台商所綁的廠商編號[MerchantID]。

(9) 回傳網址不支援中文網址，網址參數請使用 punycode 編碼後的網址，例如中文.tw 改成 xn--fiq228c.tw。

(10) 傳輸參數不支援特殊符號，會造成建立訂單錯誤。

(11) 更換介接正式環境時，請將以下資訊更換成正式環境中所持有的相關資訊，請參考正式環境金鑰取得。

(12) 為保障消費者權益與網路交易安全，綠界串接服務只支援 TLS 1.2 以上之加密通訊協定。

https://vendor-stage.ecpay.com.tw/

https://www.ecpay.com.tw/CascadeFAQ/CascadeFAQ_Qa?nID=1490





4. 產生訂單

應用場景：

消費者進行購物後送出交易訂單。

Step 1.特店：將訂單資料以 POST(HTTP Method)傳送至綠界，準備進行付款。

Step 2.綠界：接受訂單並檢核資料。

※注意事項：

(1) 使用內置框架 iframe 可能會導致交易失敗，建議不要使用。

(2) 若消費者使用環境為 iOS 系統時，請勿另開新視窗。詳細說明請參考。

介接路徑：

正式環境：https://payment.ecpay.com.tw/Cashier/AioCheckOut/V5

測試環境：https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5

傳入參數說明 (名稱前若有紅色星號*為必填欄位)：支援 form-data 格式

參數參數名稱型態說明範例

*MerchantID

特店編號

(由綠界提

供)

String(10) 由 ECPAY 提供 2000132

*MerchantTradeNo 特店交易

編號 String(20)

為唯一值，不可重複使用。

英數字大小寫混合。

如何避免訂單編號重複請參考 FAQ

如有使用 PlatformID，平台商底下所有

商家之訂單編號亦不可重複。

ecPay1234

StoreID 特店旗下

店舖代號 String(20)

提供特店填入分店代號使用，僅可用英

數字大小寫混合。

*MerchantTradeDate 交易時間 String(20) 格式為：

yyyy/MM/dd HH:mm:ss 2012/03/21 15:40:18

*PaymentType 交易類型 String(20) 請固定填入 aio aio

*TotalAmount 交易金額 Int

請帶整數，不可有小數點

僅限新台幣

各付款金額的限制，請參考：


5000

*TradeDesc 交易描述 String(200) 傳送到綠界前，請將參數值先做

UrlEncode。 ecpay 商城購物

*ItemName 商品名稱 String(400) 1. 如果商品名稱有多筆，需在金流選手機 20 元 X2#隨身碟









擇頁一行一行顯示商品名稱的話，商品

名稱請以符號#分隔

2. 商品名稱字數限制為中英數 400 字

內，超過此限制系統將自動截斷。

60 元 X1

*ReturnURL

付款完成

通知回傳

網址

String(200)

當付款完成後，綠界會將付款結果參數

以幕後(Server POST)回傳到該網址。

詳細說明請參考付款結果通知

注意事項：

１. 請勿設定與 Client 端接收付款結果

網址 OrderResultURL 相同位置，避免程

式判斷錯誤。

２. 請在收到 Server 端付款結果通知

後，請正確回應 1|OK。

http://your.web.site/receive.php

*ChoosePayment 選擇預設

付款方式 String(20)

提供下列付款方式，請於建立訂單時傳

送過來:

WebATM:網路 ATM

ATM:自動櫃員機

CVS:超商代碼

BARCODE:超商條碼

ALL:不指定付款方式，由綠界顯示付款

方式選擇頁面。

注意事項：

若為手機版時不支援下列付款方式:

WebATM:網路 ATM

Credit

*CheckMacValue 檢查碼 String 請參考附錄檢查碼機制

ClientBackURL

Client 端返

回特店的

按鈕連結

String(200)

消費者點選此按鈕後，會將頁面導回到

此設定的網址

注意事項：

導回時不會帶付款結果到此網址，只是

將頁面導回而已。

設定此參數，綠界會在付款完成或取號

完成頁面上顯示[返回商店]的按鈕。

設定此參數，發生簡訊 OTP 驗證失敗

時，頁面上會顯示[返回商店]的按鈕。

若未設定此參數，則付款完成頁或取號

完成頁面，不會顯示[返回商店]的按鈕。

若導回網址未使用 https 時，部份瀏覽

器可能會出現警告訊息。

http://your.web.site/Shopping/Detail





ItemURL 商品銷售

網址 String(200)

Remark 備註欄

位。 String(100)

ChooseSubPayment 付款子項

目 String (20)

若設定此參數，建立訂單將轉導至綠界

訂單成立頁，依設定的付款方式及付款

子項目帶入訂單，無法選擇其他付款子

項目。請參考付款方式一覽表

TAISHIN

OrderResultURL

Client 端回

傳付款結

果網址

String(200)

為付款完成後，綠界將頁面導回到特店

網址，並將付款結果帶回。

注意事項：

沒帶此參數則會顯示綠界的付款完成

頁。

如果要將付款結果頁顯示在特店內，請

設定此參數。

若與[ClientBackURL]同時設定，將會以

此參數為主。

部分銀行 WebATM 在交易成功後,會停

留在銀行的頁面,並不會導回給綠界,所

以綠界也不會將頁面導回到

[OrderResultURL]的頁面。

銀聯卡及非即時交易 (ATM、CVS、

BARCODE)不支援此參數。

建議在測試階段時先不要設定此參

數，可將畫面停留在綠界，看見綠界所

提供的錯誤訊息，便可以有效除錯。

若有設定此參數，請務必根據回傳的交

易狀態來判斷顯示付款成功與否的頁

面。



http://your.web.site/client.php

NeedExtraPaidInfo

是否需要

額外的付

款資訊

String(1)

預設值：N

額外的付款資訊：

若不回傳額外的付款資訊時，參數值請

傳：Ｎ

若要回傳額外的付款資訊時，參數值請

傳：Ｙ，付款完成後綠界會以 Server

POST 方式回傳額外付款資訊。

注意事項：

N





回傳額外付款資訊參數請參考-額外回

傳的參數

DeviceSource 裝置來源 String(10) 請帶空值，由系統自動判定。

IgnorePayment 隱藏付款

方式 String(100)

當付款方式 [ChoosePayment] 為 ALL

時，可隱藏不需要的付款方式，多筆請

以井號分隔(#)。

可用的參數值：

Credit:信用卡

AndroidPay: AndroidPay

WebATM:網路 ATM

ATM:自動櫃員機

CVS:超商代碼

BARCODE:超商條碼

Credit #AndroidPay

PlatformID 平台商代

號 String(10)

為專案合作的平台商使用。

一般特店或平台商本身介接，則參數請

帶放空值。

若為專案平台商的特店使用時，則參數

請帶平台商所綁的特店編號

[MerchantID]。

InvoiceMark 電子發票

開立註記 String(1)

此參數為付款完成後同時開立電子發

票。

若要使用時，該參數須設定為「Y」，

同時還要設定「電子發票介接相關參

數」

注意事項：

正式環境欲使用電子發票功能，須與我

們申請開通，若未開通請致電客服中心

(02) 2655-1775。

CustomField1 自訂名稱

欄位 1 String(50)

提供客製化使用欄位

注意事項：

特殊符號只支援,.#()$[];%{}:/?&@<>!


欄位 2 String(50)


注意事項：

特殊符號只支援,.#()$[];%{}:/?&@<>!


欄位 3 String(50)


注意事項：

特殊符號只支援,.#()$[];%{}:/?&@<>!


欄位 4 String(50)


注意事項：





特殊符號只支援,.#()$[];%{}:/?&@<>!

*EncryptType

CheckMacV

alue 加密

類型

Int 請固定填入 1，使用 SHA256 加密。 1

當 ChoosePayment 參數為使用 ALL 或 ATM 付款方式時：


ExpireDate 允許繳費有

效天數 Int

若需設定最長 60 天，最短 1 天。

未設定此參數則預設為 3 天

注意事項：

以天為單位

7

PaymentInfoURL

Server 端回

傳付款相關

資訊

String(200)

若有設定此參數，訂單建立完成後(非

付款完成)，綠界 Server 端背景會回傳

消費者付款方式相關資訊(例：銀行代

碼、繳費虛擬帳號繳費期限…等)。

請參考[ATM、CVS 或 BARCODE 的取號

結果通知.]

注意事項：

頁面將會停留在綠界，顯示繳費的相關

資訊。

http://your.web.site/paymentinfo.php

ClientRedirectURL

Client 端回

傳付款相關

資訊

String (200)


付款完成)，綠界 Client 端會回傳消費

者付款方式相關資訊(例：銀行代碼、

繳費虛擬帳號繳費期限…等)且將頁面

轉到指定的頁面。請參考[ATM、CVS

或 BARCODE 的取號結果通知.]

注意事項：

若設定此參數，將會使設定的返回特店

的按鈕連結[ClientBackURL]失效。



http://your.web.site/ ClientRedirectURL.php

注意事項：

各銀行 ATM 繳款帳號，若金額錯誤、逾期繳費、重覆繳款，是經由銀行端機制進行檢核 ATM 繳款帳號資訊，綠界科

技無法進行金額錯誤、逾期繳費、重覆繳款的訂單阻擋。




當 ChoosePayment 參數為使用 ALL 或 CVS 或 BARCODE 付款方式時：


StoreExpireDate 超商繳費截

止時間 int

注意事項：

CVS:以分鐘為單位

BARCODE:以天為單位

若未設定此參數，CVS 預設為 10080 分

鐘(7 天)；BARCODE 預設為 7 天。

若需設定此參數，請於建立訂單時將此

參數送給綠界。提醒您，CVS 帶入數值

不可超過 86400 分鐘，超過時一律以

86400 分鐘計(60 天)

例：08/01 的 20:15 分購買商品，繳費

期限為 7 天，表示 8/08 的 20:15 分前

您必須前往超商繳費。

7

Desc_1 交易描述 1 String(20) 會出現在超商繳費平台螢幕上交易描述 1




PaymentInfoURL

Server 端回

傳付款相關

資訊

String(200)


付款完成)，綠界 Server 端背景回傳消

費者付款方式相關資訊(例：繳費代碼

與繳費超商)。

請參考[ATM、CVS 或 BARCODE 的取號

結果通知.]

注意事項：

頁面將會停留在綠界，顯示繳費的相關

資訊。

回傳只有三段號碼，並不會回傳條碼

圖，需自行轉換成 code39 的三段條碼。

ClientRedirectURL

Client 端回

傳付款方式

相關資訊

String(200)


付款完成)，綠界 Client 端回傳消費者

付款方式相關資訊(例：繳費代碼與繳

費超商)且將頁面轉到指定的頁面。請

參考[ATM、CVS 或 BARCODE 的取號結

果通知.]

注意事項：

若設定此參數，將會使設定的返回特店

的按鈕連結[ClientBackURL]失效。







回傳只有三段號碼，並不會回傳條碼

圖，需自行轉換成 code39 的三段條碼。

當 InvoiceMark 參數為 Y 付款完成後開立電子發票時帶入下列參數：


*RelateNumber 特店自訂

編號 String(30)

此為自訂編號，

為唯一值不可重複使用。

Tea0001

CustomerID 客戶代號 String (20) 該參數有值時，僅接受『英文、數字、

下底線』等字元。

CustomerIdentifier 統一編號 String(8)

該參數有值時，請帶固定長度為數字 8

碼。

53348111

CustomerName 客戶名稱 String(60)

當列印註記[Print]為 1(列印)時，則該參

數必須有值。

該參數有值時，僅接受『中、英文及數

字』等字元。

請將參數值做 UrlEncode 方式編碼。

綠界電子支付股份

有限公司 UrlEncode

→

%e6%ad%90%e4%bb%98%e5%af%b6%e9%9b%bb%e5%ad%90%e6%94%af%e4%bb%98%e8%82%a1%e4%bb%bd%e6%9c%89%e9%99%90%e5%85%ac%e5%8f%b8

CustomerAddr 客戶地址 String(200)

當列印註記[Print]為 1(列印)時，則該參

數必須有值。

當該參數有值時，請注意特殊字元轉

換。


臺北市南港區三重

路 19-2 號 5 樓

UrlEncode →

%E8%87%BA%E5%8C%97%E5%B8%82%E5%8D%97%E6%B8%AF%E5%8D%80%E4%B8%89%E9%87%8D%E8%B7%AF19-2%E8%99%9F5%E6%A8%93

CustomerPhone 客戶手機

號碼 String(20)

當客戶電子信箱 [CustomerEmail]為空

字串時，則該參數必須有值。

當該參數有值時，則格式為數字。

注意事項：

請填手機號碼，不能填市話因為要收簡

訊通知用

0912345678

CustomerEmail 客戶電子 String(200) 當客戶手機號碼[CustomerPhone]為空 [email protected]

mailto:[email protected]





信箱字串時，則該參數必須有值。

當該參數有值時，則格式需符合 EMAIL

格式。


Encode →

abc%40ecpay.com.tw

ClearanceMark 通關方式 String(1)

當課稅類別[TaxType]為 2(零稅率)時，

則該參數請帶 1(非經海關出口)或 2(經

海關出口)。

2

*TaxType 課稅類別 String(1)

1. 若為應稅，請帶 1。

2. 若為零稅率，請帶 2。

3. 若為免稅，請帶 3。

4. 若為混合應稅與免稅或零稅率時

(限收銀機發票無法分辨時使用，且

需通過申請核可)，則請帶 9。

1

CarruerType 載具類別 String (1)

1. 若為無載具時，則請帶空字串。

2. 若為會員載具時，則請帶 1。

3. 若為買受人之自然人憑證號碼時，

則請帶 2。

4. 若為買受人之手機條碼資料時，則

請帶 3。

5. 若統一編號 [CustomerIdentifier]有

值時，則載具類別不可為會員載具

或自然人憑證載具。

6. 當[Print]有值時，載具類別不得有

值。

注意事項：

若列印註記[Print]=0(不列印發票)，捐

贈註記 [Donation ] 或載具類別

[CarruerType]需擇一不可為空值。

CarruerNum 載具編號 String (64)

載具編號

1. 當載具類別 [CarruerType]=""( 無載

具)，請帶空字串；

2.當載具類別[CarruerType]="1"(綠界科

技電子發票載具)時，請帶空字串，系

統會自動帶入值，為合作特店載具統一

編號+自訂編號(RelateNumber)。

3.當載具類別[CarruerType]="2"(買受人

之自然人憑證)時，則請帶固定長度為





16且格式為 2碼大寫英文字母加上 14

碼數字。

4.當載具類別[CarruerType]="3"(買受人

之手機條碼)時，則請帶固定長度為 8

碼字元，第 1 碼為【/】; 其餘 7 碼則

由數字【0-9】、大寫英文【A-Z】與特

殊符號【+】【-】【.】這 39 個字元組

成的編號。

注意事項：

1. 若手機條碼中有加號，可能在介接

驗證時發生錯誤，請將加號改為

空白字元，產生驗證碼。

2. 英文、數字、符號僅接受半形字元

3. 若載具編號為手機條碼載具時，請

先呼叫B2C電子發票介接技術文件

手機條碼載驗證ＡＰＩ進行檢核

Donation 捐贈註記 String (1)

預設值：0

1. 若為捐贈時，參數請帶：1。

2. 若為不捐贈或統一編號

[CustomerIdentifier]有值時，參數請

帶：0。

注意事項：




0

LoveCode 捐贈碼 String (7)

消費者選擇捐贈發票則於此欄位須填

入受贈單位之捐贈碼。

1.若捐贈註記[Donation ]= '1' (捐贈)

時，此欄位須有值。

2.捐贈碼以阿拉伯數字為限，最少三

碼，最多七碼。內容定位採「文字格

式」，首位可以為零。

168001

推薦捐贈碼

168001

OMG 關懷社會愛心基金會

成立於 2009 年，希望能集結網友族群的心意，將愛傳遞到社會的每一個角落。

本基金會致力於：清寒學生及偏遠學校助學、流浪動物與動物保育議題、老人及弱勢團體、急難救助、人道救援、

https://www.ecpay.com.tw/Content/files/ecpay_004.pdf






社會公益活動推廣及廣告贊助...等。

Print 列印註記 String (1)

預設值：0

1. 若為不列印或捐贈註記[Donation]

為 1(捐贈)時，參數請帶：0。

2. 若為列印或統一編號

[CustomerIdentifier]有值時，參數請

帶：1。

注意事項：




*InvoiceItemName 商品名稱 String (Max)

預設不可為空字串且格式為名稱 1 |

名稱 2 | 名稱 3 | … | 名稱 n，當含有

二筆或以上的商品名稱時，則以「|」

符號區隔。

將參數值以 UrlEncode 方式編碼。

名稱1|名稱2|名稱3

UrlEncode →

%E5%90%8D%E7%A8%B11%7C%E5%90%8D%E7%A8%B12%7C%E5%90%8D%E7%A8%B13

*InvoiceItemCount 商品數量 String (Max)

預設不可為空字串且格式為數量 1 |

數量 2 | 數量 3 | … | 數量 n，當含有

二筆或以上的商品名稱時，則以「|」

符號區隔。

1|1

*InvoiceItemWord 商品單位 String (Max)

商品單位若超過二筆以上請以「|」符

號區隔

單位最大長度為 6 碼。

請將參數做 UrlEncode 方式編碼。

單位1|單位2|單位3

UrlEncode →

%E5%96%AE%E4%BD%8D1%7C%E5%96%AE%E4%BD%8D2%7C%E5%96%AE%E4%BD%8D3

*InvoiceItemPrice 商品價格 String (Max)

預設不可為空字串且格式為價格 1 |

價格 2 | 價格 3 | … | 價格 n，當含有

二筆或以上的商品價格時，則以「|」

符號區隔。

50|50

InvoiceItemTaxType 商品課稅

別 String (Max)

1：應稅

2：零稅率

3：免稅

注意事項：

1. 預設為空字串，當課稅類別

[TaxType] = 9 時，此欄位不可為空。

2. 格式為課稅類別 1 | 課稅類別 2 |

課稅類別 3 | … | 課稅類別 n。當含

1|1|3





有二筆或以上的商品課稅類別時，

則以「|」符號區隔。

3. 課稅類別為混合稅率時，需含二筆

或以上的商品課稅別

[InvoiceItemTaxType]，且至少需有

一筆商品課稅別為應稅及至少需有

一筆商品課稅別為免稅或零稅率，

即混稅發票只能 1.應稅+免稅 2.應

稅+零稅率，免稅和零稅率發票不能

同時開立。

InvoiceRemark 備註 String(Max) 當該參數有值時，請將參數值做

UrlEncode 方式編碼。

*DelayDay 延遲天數 Int

預設值：0

本參數值請帶 0~15(天)，

當天數為 0 時，則付款完成後立即開立

發票。

0

*InvType 字軌類別 String(2) 若為一般稅額時，請帶 07。 07

注意事項：串接金流並同時開立電子發票，請參考「電子發票 API-單元 7 查詢發票明細」取得發票相關資訊做使用。





5. ATM、CVS 或 BARCODE 的取號結果通知

甲、應用場景：

使用 ATM/CVS/BARCODE 付款方式建立訂單完成後，以下參數會以 Server POST 方式傳送至訂單

資料設定的回傳付款網址[PaymentInfoURL]。

Step1.綠界：以 ServerPost 方式傳送取號結果訊息至特店的 Server 網址[PaymentInfoURL]

Step2.特店：收到綠界的取號結果訊息，並判斷檢查碼是否相符

Step3.特店：檢查碼相符後，於網頁端回應 1|OK

注意事項：

請勿使用超商代碼販售「遊戲點數(卡)」、「遊戲虛寶」，如經檢舉或稽核屬實，綠界及超商有權限制您的繳費金

額或終止使用權益。

回傳參數說明：


MerchantID 特店編號 String(10) 2000132

PlatformID 平台商代號 String(10)

MerchantTradeNo 特店交易編號 String (20) 訂單產生時傳送給 ecpay 的交易編

號。 123456abc

StoreID 特店旗下店舖

代號 String(20)

提供特店填入分店代號使用，僅可

用英數字大小寫混合。

RtnCode 交易狀態 Int

1.ATM 回傳值時為 2 時，交易狀

態為取號成功，其餘為失敗。

2.CVS/BARCODE 回傳值時為

10100073 時，交易狀態為取號成

功，其餘為失敗。

2

RtnMsg 交易訊息 String(200) Get VirtualAccount Succeeded

TradeNo 綠界交易編號 String(20) 請保存綠界交易編號與特店交易

編號[MerchantTradeNo]的關連。 201203151740582564

TradeAmt 交易金額 Int 22000

PaymentType 特店選擇的付

款方式 String(20) 請參考回覆付款通知一覽表 WebATM_TAISHIN

TradeDate 訂單成立時間 String(20) 格式為 yyyy/MM/dd HH:mm:ss 2012/03/15 17:40:58

CustomField1 自訂名稱欄位 1 String(50) 提供客製化使用欄位





當 ChoosePayment 參數為使用 ATM 付款方式時：


BankCode 繳費銀行代碼 String (3) 812

vAccount 繳費虛擬帳號 String (16) 9103522175887271

ExpireDate 繳費期限 String (10) 格式為 yyyy/MM/dd 2013/12/16

注意事項：

各銀行 ATM 繳款帳號，若金額錯誤、逾期繳費、重覆繳款，是經由銀行端機制進行檢核 ATM 繳款帳號資訊，綠界科技

無法進行金額錯誤、逾期繳費、重覆繳款的訂單阻擋。

當 ChoosePayment 參數為使用 CVS 或 BARCODE 付款方式時：


PaymentNo 繳費代碼 String(14) 如果是條碼，則此欄位回傳空白 GW130412257496

ExpireDate 繳費期限 String(20) 格式為 yyyy/MM/dd HH:mm:ss 2013/12/16 18:00:00

Barcode1 條碼第一段號

碼 String(20)

格式為 9 碼數字，如果是代碼，則

此欄位回傳空白 021030627

Barcode2 條碼第二段號

碼 String(20)

格式為 16 碼數字，如果是代碼，

則此欄位回傳空白 2470200001841540

Barcode3 條碼第三段號

碼 String(20)

格式為 15 碼數字，如果是代碼，

則此欄位回傳空白 103027000000100

回覆參數說明：


String

回傳值為純字串並無參數名稱

若回傳值第一碼值為 1 時為成功。

若回傳值第一碼值為 0 時為失敗，

0|ErrorMessage， ErrorMessage 為

（錯誤代碼－錯誤訊息）。

1|OK

※注意事項：



CheckMacValue 檢查碼 String 必須檢查檢查碼 [CheckMacValue]

來驗證，請參考附錄檢查碼機制




接收取號結果通知時，請確認下面事項，以利收到取號完成通知：

(1) 請確認訂單產生的回傳付款網址[PaymentInfoURL]參數中的程式是否已開發完成。

(2) 請確認回傳付款網址[PaymentInfoURL]中的網址，已經開放對外，從貴公司的網域之外也可以通知得到。

取號結果通知會以下表 form-data 格式參數直接回傳至頁面，並以「參數=值」表示，參數與參數之間以&隔開，

例：

Barcode1=&Barcode2=&Barcode3=&ExpireDate=2017/12/28 00:39:03&MerchantID=2000132&MerchantTradeNo=Test1513787899&PaymentNo=LLL17355880822&PaymentType=CVS_CVS&RtnCode=10100073&RtnMsg=Get CVS Code Succeeded.&TradeAmt=2000&TradeDate=2017/12/21 00:39:03&TradeNo=1712210038341592&StoreID=&CustomField1=&CustomField2=&CustomField3=&CustomField4=&CheckMacValue=EA85AEB76DD14ED00016C41934471D877B53F5B292611AB29CA6FCBCE33205D0




6. 付款結果通知

應用場景Ⅰ：

當消費者付款完成後，接受綠界的付款結果訊息，並回應接收訊息

Step1.綠界：以 ServerPost 方式傳送付款結果訊息至指定的 Server 網址(ReturnURL)

Step2.特店：收到付款結果訊息，並判斷檢查碼是否相符

Step3.特店：檢查碼相符後，回傳 1|OK

注意事項：

(1) 超商繳費條碼(BARCODE)因銀行端作業時間關係會於消費者付款完成兩天後回傳。

(2) ATM、CVS、BARCODE 可透過廠商管理後台的『模擬付款』，來確認 ReturnURL 是否正確接收付款結果通知。

回傳參數說明Ⅰ：


MerchantID 特店編號 String(10) 2000132


MerchantTradeNo 特店交易編

號 String (20)

訂單產生時傳送給綠界交易編號。

英數字大小寫混合 123456abc

StoreID 特店旗下店

舖代號 String(20)

提供特店填入分店代號使用，僅可用

英數字大小寫混合。

RtnCode 交易狀態 Int

若回傳值為 1 時，為付款成功

其餘代碼皆為交易失敗，請勿出貨。

1

RtnMsg 交易訊息 String(200) Success

TradeNo 綠界交易編

號 String(20)

請保存綠界交易編號與特店交易編

號[MerchantTradeNo]的關連。

201203151740582564


PaymentDate 付款時間 String(20) 格式為 yyyy/MM/dd HH:mm:ss 2012/03/16 12:03:12

PaymentType 特店選擇的

付款方式 String(20) 請參考回覆付款方式一覽表 Credit_CreditCard

PaymentTypeChargeFee 交易手續費 Int 25

TradeDate 訂單成立時

間 String(20) 格式為 yyyy/MM/dd HH:mm:ss

2012/03/15 17:40:58

SimulatePaid 是否為模擬

付款 Int

回傳值：

若為 1 時，代表此交易為模擬付款，

請勿出貨。

0




回覆參數說明：


String

回傳值為純字串並無參數名稱

若回傳值第一碼值為 1 時為成功。

若回傳值第一碼值為 0 時為失敗，

0|ErrorMessage，ErrorMessage 為（錯

誤代碼－錯誤訊息）。

1|OK

※注意事項：

(1) 務必判斷檢查碼[CheckMacValue]是否正確，以及是否已經對該筆訂單的付款通知，做過相對應的處理，以免

造成交易狀態無法同步的損失。

(2) 若未正確回應 1|OK，系統會進入排程重發訊息給特店，三次後則會延至隔天再發訊息，維持三天發送。

(3) 若持續收到相同的回傳付款資訊，此時請檢查程式是否未正確回應 1|OK，常見錯誤回傳值為(“1|OK”、1|ok、

_OK 、1\OK、空白 )。

(4) 若遇消費者已付款，但未收到綠界回傳付款完成資訊，請檢查接收回傳參數的伺服器是否服務正常，導致無法

接收。請參考：無法收到綠界回傳的付款結果通知

(5) 當模擬付款[SimulatePaid]的值為 1 時，表示此筆訂單資訊是由廠商後台模擬付款按鈕所發送的回傳付款通知測

試資訊，所以綠界不會進行撥款，請勿對該筆交易做出貨等動作，以避免損失。

(6) 務必判斷交易狀態[RtnCode]是否為 1，若非 1 時請勿對該筆交易做出貨動作，並取得交易訊息[RtnMsg] 記錄

失敗原因。

若為 0 時，代表此交易非模擬付款。

注意事項：

可透過廠商後台網站來針對單筆訂

單模擬綠界回傳付款通知，以方便介

接 API 的測試。

CustomField1 自訂名稱欄

位 1 String(50)



位 2 String(50)



位 3 String(50)



位 4 String(50)


CheckMacValue 檢查碼 String 必須檢查檢查碼[CheckMacValue]來

驗證，請參考附錄檢查碼機制。





付款結果通知會以下表 form-data 格式參數直接回傳至頁面，並以「參數=值」表示，參數與參

數之間以&隔開，例： &CustomField1=&CustomField2=&CustomField3=&CustomField4=&MerchantID=2000132 &MerchantTradeNo=Test1510056539&PaymentDate=2017/11/02 16:22:18

&PaymentType=Credit_CreditCard&PaymentTypeChargeFee=1&RtnCode=1&RtnMsg=交易成功

&SimulatePaid=0&StoreID=&TradeAmt=100&TradeDate=2017/11/07 20:08:59&TradeNo=1711072008596023 &CheckMacValue= DB6960E7B3765C2ACDDF8437B9D92EA14823B1B5BA11069017777D79A99A9F1E




7. 查詢訂單(可依需求來決定是否撰寫此 API)

應用場景：

提供查詢訂單資訊，可透過此 API 來過濾是否為有效訂單。

Step 1.特店：以 Server POST 方式傳送以下參數至 API 網址

Step 2.綠界：接受並檢核正確後，回傳訂單資訊參數。

介接路徑：

正式環境：https://payment.ecpay.com.tw/Cashier/QueryTradeInfo/V5

測試環境：https://payment-stage.ecpay.com.tw/Cashier/QueryTradeInfo/V5

傳入參數說明 (名稱前若有紅色星號*為必填欄位)：支援 JSON/form-data 格式


*MerchantID 特店編號 String(10) 2000132

*MerchantTradeNo 特店交易編

號 String(20) 訂單產生時傳送給綠界交易編號。 ecpay1234

*TimeStamp 驗證時間 Int

將當下的時間轉為 UnixTimeStamp(見範

例)用於驗證此次介接的時間區間。

驗證時間區間暫訂為 3 分鐘內有效，超

過則此次介接無效。參考資料：

http://www.epochconverter.com/。

1234567890


為專案平台商使用。

一般特店或平台商本身介接，則參數請

帶放空值。

若為專案平台商的特店使用時，則參數

請帶平台商所綁的特店編號

[MerchantID]。

*CheckMacValue 檢查碼 String 請參考附錄檢查碼機制。

http://www.epochconverter.com/





訂單結果會以下表參數直接回傳至頁面，並以「參數=值」表示，參數與參數之間以&隔開，例：

MerchantID =123456789&MerchantTradeNo=123456abc&TradeNo=201203151740582564


MerchantID 特店編號 String (9) 2000132

PlatformID 平台商代號 String(10) PlatformID

MerchantTradeNo 特店交易編號 String (20) 訂單產生時傳送給綠界交易編號。 123456abc

StoreID 特店旗下店舖

代號 String(20)

提供特店填入分店代號使用，僅可用英數字

大小寫混合。

TradeNo 綠界交易編號 String(20) 201203151740582564


PaymentDate 付款時間 String(20) 格式為 yyyy/MM/dd HH:mm:ss 2012/03/16 12:03:12

PaymentType 特店選擇的付

款方式 String(20) Credit

HandlingCharge 手續費合計 Int 履約結束後才會計算，未計算前為 0 0

PaymentTypeChargeFee 交易手續費 Int 25

TradeDate 訂單成立時間 String(20) 格式為 yyyy/MM/dd HH:mm:ss 2012/03/15 17:40:58

TradeStatus 交易狀態 String(8)

回傳值：

若為 0 時，代表交易訂單成立未付款

若為 1 時，代表交易訂單成立已付款

若為 10200095 時，代表消費者未選擇付款方

式，故交易失敗。

0

ItemName 商品名稱 String(400) 商品 1

CustomField1 自訂名稱欄位

1 String(50)



2 String(50)



3 String(50)



4 String(50)


CheckMacValue 檢查碼 String 必須檢查檢查碼[CheckMacValue]來驗證，請

參考附錄檢查碼機制。




8. 額外回傳的參數

應用場景：

在產生訂單時，若設定需要額外的付款資訊[NeedExtraPaidInfo]為 Y 時，將增加回傳額外參數(如

下表)。

Step 1.特店：產生訂單時，設定是否需要額外的付款資訊[NeedExtraPaidInfo]為 Y 時。

Step 2.綠界：傳送付款結果通知與查詢訂單時會額外回傳以下參數給特店

注意事項：額外回傳的參數全部都需要加入檢查碼計算



WebATMAccBank 付款人銀行代碼 String(3) 若該銀行未提供，則回傳空白 812

WebATMAccNo 付款人銀行帳號後五碼 String(5) 若該銀行未提供，則回傳空白 12345

WebATMBankName 銀行名稱 String(10) 請參考付款方式一覽表 TAISHIN

ATMAccBank 付款人銀行代碼 String(3) 若該銀行未提供，則回傳空白 812

ATMAccNo 付款人銀行帳號後五碼 String(5) 若該銀行未提供，則回傳空白 12345

PaymentNo 繳費代碼 String(14) BARCODE 則回傳空白 GW120821847169

PayFrom 繳費超商 String(10)

family：全家

hilife：萊爾富

okmart：OK 超商

ibon：7-11

family

gwsr 授權交易單號 Int 10123456

process_date 處理時間 String(20) 格式為 yyyy/MM/dd HH:mm:ss 2013/12/19 13:55:20

auth_code 授權碼 String(6) 777777

amount 金額 Int 400

stage 分期期數 Int 3

stast 頭期金額 Int 134

staed 各期金額 Int 133

eci 3D(VBV) Int 回傳值 (eci=5,6,2,1 代表該筆

交易不可否認) 5

card4no 卡片的末 4 碼 String(4) 2222

card6no 卡片的前 6 碼 String(6) 431195

red_dan 紅利扣點 Int 0

red_de_amt 紅利折抵金額 Int 0

red_ok_amt 實際扣款金額 Int 0

red_yet 紅利剩餘點數 Int 0

PeriodType 訂單建立時的所設定的 String(1) D





週期種類

Frequency 訂單建立時的所設定的

執行頻率 Int 2

ExecTimes 訂單建立時的所設定的

執行頻率 Int 5

PeriodAmount 訂單建立時的每次要授

權金額 Int 200

TotalSuccessTimes 目前已成功授權的次數 Int 5

TotalSuccessAmount 目前已成功授權的金額

合計 Int 1000




9. 檢查碼機制

在與綠界進行資料傳遞時，除了檢查碼[CheckMacValue]及其餘所有傳遞給歐付寶的參數皆需要

加入檢查碼計算，下列範例為 AioCheckOut 建立訂單計算方式

以下為舉例待加密的字串：

TradeDesc=促銷方案&PaymentType=aio&MerchantTradeDate=2013/03/12

15:30:23&MerchantTradeNo=ecpay20130312153023&MerchantID=2000132&ReturnURL=https://www.ecpay.

com.tw/receive.php&ItemName=Apple iphone 7 手機殼

&TotalAmount=1000&ChoosePayment=ALL&EncryptType=1

檢核碼計算順序如下:

(1) 將傳遞參數依照第一個英文字母，由 A 到 Z 的順序來排序(遇到第一個英名字母相同時，以

第二個英名字母來比較，以此類推)，並且以&方式將所有參數串連。

ChoosePayment=ALL&EncryptType=1&ItemName=Apple iphone 7 手機殼

&MerchantID=2000132&MerchantTradeDate=2013/03/12 15:30:23&MerchantTradeNo=ecpay20130312153023&PaymentType=aio&ReturnURL=https://www.ecpay.co

m.tw/receive.php&TotalAmount=1000&TradeDesc=促銷方案

(2) 參數最前面加上 HashKey、最後面加上 HashIV

HashKey=5294y06JbISpM5x9&ChoosePayment=ALL&EncryptType=1&ItemName=Apple iphone 7 手機殼

&MerchantID=2000132&MerchantTradeDate=2013/03/12 15:30:23&MerchantTradeNo=ecpay20130312153023&PaymentType=aio&ReturnURL=https://www.ecpay.co

m.tw/receive.php &TotalAmount=1000&TradeDesc=促銷方案&HashIV=v77hoKGq4kWxNNIS

(3) 將整串字串進行 URL encode

HashKey%3d5294y06JbISpM5x9%26ChoosePayment%3dALL%26EncryptType%3d1%26ItemName%3dApple+iphone+7+%e6%89%8b%e6%a9%9f%e6%ae%bc%26MerchantID%3d2000132%26MerchantTradeDate%3d2013%2f03%2f12+15%3a30%3a23%26MerchantTradeNo%3decpay20130312153023%26PaymentType%3daio%26ReturnURL%3dhttps%3a%2f%2fwww.ecpay.com.tw%2freceive.php%26TotalAmount%3d1000%26TradeDesc%3d%e4%bf%83%e9%8a%b7%e6%96%b9%e6%a1%88%26HashIV%3dv77hoKGq4kWxNNIS

若使用 PHP 進行 URL encode：

HashKey%3d5294y06JbISpM5x9%26ChoosePayment%3dALL%26EncryptType%3d1%26ItemName%3dApple%20iphone%207%20%e6%89%8b%e6%a9%9f%e6%ae%bc%26MerchantID%3d2000132%26MerchantTradeDate%3d2013%2f03%2f12%2015%3a30%3a23%26MerchantTradeNo%3decpay20130312153023%26PaymentType%3daio%26ReturnURL%3dhttps%3a%2f%2fwww.ecpay.com.tw%2freceive.php%26TotalAmount%3d1000%26TradeDesc%3d%e4%bf%83%e9%8a%b7%e6%96%b9%e6%a1%88%26HashIV%3dv77hoKGq4kWxNNIS

(4) 轉為小寫

hashkey%3d5294y06jbispm5x9%26choosepayment%3dall%26encrypttype%3d1%26itemname%3dapple+iph




one+7+%e6%89%8b%e6%a9%9f%e6%ae%bc%26merchantid%3d2000132%26merchanttradedate%3d2013%2f03%2f12+15%3a30%3a23%26merchanttradeno%3decpay20130312153023%26paymenttype%3daio%26returnurl%3dhttps%3a%2f%2fwww.ecpay.com.tw%2freceive.php%26totalamount%3d1000%26tradedesc%3d%e4%bf%83%e9%8a%b7%e6%96%b9%e6%a1%88%26hashiv%3dv77hokgq4kwxnnis

若使用 PHP 進行 URL encode：

hashkey%3d5294y06jbispm5x9%26choosepayment%3dall%26encrypttype%3d1%26itemname%3dapple%20iphone%207%20%e6%89%8b%e6%a9%9f%e6%ae%bc%26merchantid%3d2000132%26merchanttradedate%3d2013%2f03%2f12%2015%3a30%3a23%26merchanttradeno%3decpay20130312153023%26paymenttype%3daio%26returnurl%3dhttps%3a%2f%2fwww.ecpay.com.tw%2freceive.php%26totalamount%3d1000%26tradedesc%3d%e4%bf%83%e9%8a%b7%e6%96%b9%e6%a1%88%26hashiv%3dv77hokgq4kwxnnis

(5) 依 urlencode 轉換表更換字元 (若使用 PHP 進行 URL encode 時使用)

hashkey%3d5294y06jbispm5x9%26choosepayment%3dall%26encrypttype%3d1%26itemname%3dapple+iphone+7+%e6%89%8b%e6%a9%9f%e6%ae%bc%26merchantid%3d2000132%26merchanttradedate%3d2013%2f03%2f12+15%3a30%3a23%26merchanttradeno%3decpay20130312153023%26paymenttype%3daio%26returnurl%3dhttps%3a%2f%2fwww.ecpay.com.tw%2freceive.php%26totalamount%3d1000%26tradedesc%3d%e4%bf%83%e9%8a%b7%e6%96%b9%e6%a1%88%26hashiv%3dv77hokgq4kwxnnis

(6) 以 SHA256 加密方式來產生雜凑值

cfa9bde377361fbdd8f160274930e815d1a8a2e3e80ce7d404c45fc9a0a1e407

(7) 再轉大寫產生 CheckMacValue

CFA9BDE377361FBDD8F160274930E815D1A8A2E3E80CE7D404C45FC9A0A1E407

※注意事項：

(1) 請接收到綠界傳送的資訊時，檢查檢查碼[CheckMacValue]是否正確，如未判斷可能產生損失。

(2) 請用 SHA256 加密方式產生雜凑值。

(3) 請確認您的語言的 UrlEncode function 轉換後的結果符合附錄 URLENCODE 轉換表中的「.NET 編碼(ecpay)」欄位

值，若有不符合的字元，請用字元替換功能處理，以免無法符合檢查規則。

例如：PHP urlencode function 會將 ! 字元編碼成 %21，不符合「.NET 編碼(ecpay)」，所以在 PHP urlencode 後需

用 str_replace function 將%21 轉回 ! 字元。以下僅以 PHP 轉換範例說明：

$sMacValue = str_replace('%2d', '-', $sMacValue); $sMacValue = str_replace('%5f', '_', $sMacValue); $sMacValue = str_replace('%2e', '.', $sMacValue); $sMacValue = str_replace('%21', '!', $sMacValue); $sMacValue = str_replace('%2a', '*', $sMacValue); $sMacValue = str_replace('%28', '(', $sMacValue); $sMacValue = str_replace('%29', ')', $sMacValue);

其它程式語言的轉換功能，請閱該程式語言的編碼轉換規則改寫。




10. 下載特店對帳媒體檔

應用場景：

提供下載 CSV 格式的對帳媒體檔內容。

Step 1.特店：將要查詢的訂單資料條件，以 POST(HTTP Method)傳送，進行查詢。

Step 2.綠界：接受訂單查詢並檢核資料後，回傳 CSV 檔案格式提供下載。

※注意事項：

(1) 此 API 有限制 IP 存取，請到「廠商後台->基本資料查詢->廠商基本資料」設定 IP 。

(2) 僅開放一分鐘下載一個對帳媒體檔。

介接路徑：

正式環境：https://vendor.ecpay.com.tw/PaymentMedia/TradeNoAio

測試環境：https://vendor-stage.ecpay.com.tw/PaymentMedia/TradeNoAio

傳入參數說明 (名稱前若有紅色星號*為必填欄位)：支援 JSON/form-data 格式


* MerchantID 特店編號

(由 ECPAY提供) String(10) 2000132

*DateType 查詢日期類別 String (1)

要查詢的日期類別

若為查詢付款日期時，則參數請帶２

若為查詢撥款日期時，則參數請帶４

若為查詢退款日期時，則參數請帶５

若為查詢訂單日期時，則參數請帶６

2

*BeginDate 查詢開始日期 String (10) 要查詢的開始日期

日期格式為「yyyy-MM-dd」 2015-02-12

*EndDate 查詢結束日期 String (10) 要查詢的結束日期

日期格式為「yyyy-MM-dd」 2015-02-12

PaymentType 付款方式 String (2)

要查詢訂單的付款方式

若為信用卡時，則參數請帶 01

若為網路 ATM 時，則參數請帶 02

若為 ATM 櫃員機時，則參數請帶 03

若為超商代碼時，則參數請帶 04

若為超商條碼時，則參數請帶 05

若為信用卡(OTP)時，則參數請帶 08

若為全家條碼立即儲時，則參數請帶 10

若為全部時，請忽略此一參數

02

PlatformStatus 訂單類型 String (1) 要查詢的訂單類型 0





若為一般時，則參數請帶 1

若為平台時，則參數請帶 2


PaymentStatus 付款狀態 String (1)

要查詢的訂單付款狀態

若為未付款時，則參數請帶 0

若為已付款時，則參數請帶 1

若為訂單失敗時，則參數請帶 2


1

AllocateStatus 撥款狀態 String (1)

要查詢的訂單撥款狀態

若為未撥款時，則參數請帶 0

若為已撥款時，則參數請帶 1


0

*MediaFormated CSV 格式 String (1)

要下載的檔案格式

若為舊版格式時，則參數請帶 0

若為新版格式時，則參數請帶 1

1

*CheckMacValue 檢查碼 String 請參考附錄檢查碼機制

Response CSV 舊版檔案格式說明：

欄位名稱型態說明

交易日期 String ‧預設格式為 yyyy/MM/dd hh:mm:ss

綠界交易序號 String

特店訂單編號 String

ATM 條碼 String

交易金額 Int

付款方式 String

付款結果 String

付款日期 String

款項來源(銀行/超商) String

通路費 Int

交易服務費率(%數 / $筆) String

交易服務費金額 Int

應收款項(淨額) Int

撥款狀態 String

撥款日期 String ‧預設格式為 yyyy/MM/dd hh:mm:ss

備註 String




Response CSV 新版檔案格式說明：

欄位名稱型態說明

訂單日期 String ‧預設格式為 yyyy/MM/dd hh:mm:ss

廠商訂單編號 String

綠界訂單編號 String

店鋪代號 String

MID String

平台名稱 String

付款方式 String

費率(每筆) String

信用卡授權單號 String

信用卡卡號末 4 碼 String

超商資訊/ATM 繳款帳號 String

付款狀態 String

交易金額 Int

退款日期 String ‧預設格式為 yyyy/MM/dd hh:mm:ss

退款金額 Int

交易手續費 Int

平台手續費 Int

應收款項(淨額) Int

撥款狀態 String

備註 String

廠商備註 String

商品名稱 String

交易描述 String

付款人姓名 String

付款人手機 String

付款人 Email String

收件人姓名 String

收件人手機 String

收件人地址 String

收件人 Email String

統一編號 String




※注意事項：

(1) 下載的格式與廠商後台的「一般訂單查詢/全方位金流訂單」下載格式相同。

(2) 若查無資料時，對帳媒體檔僅包含各欄位名稱。

(3) 若發生錯誤時，對帳媒體檔除各欄位名稱之外，同時會再寫入一筆資料記錄執行時期的回傳訊息於「備註」或「廠

商備註」欄位。除了上述欄位，其餘欄位皆為無值。




附錄 1. 關鍵字一覽表

名稱說明

特店指提供綠界金流付款服務給消費者付款交易的賣家

特約店家指與綠界金流有特別專案簽訂合約的賣家

專案平台商指與綠界金流有特別專案簽訂合約的平台廠商

AioCheckOut 指綠界提供的金流付款服務

綠界訂單指綠界確認訂單資料無誤後，於綠界產生交易訂單

檢查碼指傳送交易資料由檢查碼機制產生後的交易資料檢核字串

OTP 指信用卡交易時使用的簡訊驗證服務

附錄 2. 交易狀態代碼表

因錯誤代碼一直在新增，詳細的錯誤代碼，請到廠商管理後台->系統開發管理->交易狀態代碼

查詢。




附錄 3. 付款方式一覽表

付款方式付款子方式付款方式名稱

WebATM

TAISHIN WebATM_台新

ESUN WebATM_玉山

BOT WebATM_台灣銀行

FUBON WebATM_台北富邦

CHINATRUST WebATM_中國信託

FIRST WebATM_第一銀行

CATHAY WebATM_國泰世華

MEGA WebATM_兆豐銀行

LAND WebATM_土地銀行

TACHONG WebATM_大眾銀行

SINOPAC WebATM_永豐銀行

ATM

TAISHIN ATM_台新

ESUN ATM_玉山

BOT ATM_台灣銀行

FUBON ATM_台北富邦

CHINATRUST ATM_中國信託

FIRST ATM_第一銀行

LAND ATM_土地銀行

CATHAY ATM_國泰世華銀行

TACHONG ATM_大眾銀行

CVS

CVS 超商代碼繳款

OK OK 超商代碼繳款

FAMILY 全家超商代碼繳款

HILIFE 萊爾富超商代碼繳款

IBON 7-11 ibon 代碼繳款

BARCODE BARCODE 超商條碼繳款




附錄 4. 回覆付款方式一覽表

回覆付款方式( PaymentType) 付款方式名稱

WebATM_TAISHIN 台新銀行 WebATM

WebATM_ESUN 玉山銀行 WebATM

WebATM_BOT 台灣銀行 WebATM

WebATM_FUBON 台北富邦 WebATM

WebATM_CHINATRUST 中國信託 WebATM

WebATM_FIRST 第一銀行 WebATM

WebATM_CATHAY 國泰世華 WebATM

WebATM_MEGA 兆豐銀行 WebATM

WebATM_LAND 土地銀行 WebATM

WebATM_TACHONG 大眾銀行 WebATM

WebATM_SINOPAC 永豐銀行 WebATM

ATM_TAISHIN 台新銀行 ATM

ATM_ESUN 玉山銀行 ATM

ATM_BOT 台灣銀行 ATM

ATM_FUBON 台北富邦 ATM

ATM_CHINATRUST 中國信託 ATM

ATM_FIRST 第一銀行 ATM

ATM_LAND 土地銀行 ATM

ATM_CATHAY 國泰世華銀行 ATM

ATM_TACHONG 大眾銀行 ATM

CVS_CVS 超商代碼繳款

CVS_OK OK 超商代碼繳款

CVS_FAMILY 全家超商代碼繳款

CVS_HILIFE 萊爾富超商代碼繳款

CVS_IBON 7-11 ibon 代碼繳款

BARCODE_BARCODE 超商條碼繳款




附錄 5. URLEncode 轉換表

符號 URLEncode 結果 .NET URLEncode 結果

- %2d -

_ %5f _

. %2e .

! %21 !

~ %7e %7e

* %2a *

( %28 (

) %29 )

space 空格 %20 +

@ %40 %40

# %23 %23

$ %24 %24

% %25 %25

^ %5e %5e

& %26 %26

= %3d %3d

+ %2b %2b

; %3b %3b

? %3f %3f

/ %2f %2f

\ %5c %5c

> %3e %3e

< %3c %3c

% %25 %25

` %60 %60

[ %5b %5b

] %5d %5d

{ %7b %7b

} %7d %7d

: %3a %3a

' %27 %27

" %22 %22

, %2c %2c

| %7c %7c

綠界科技 ecpay 全方位金流 - 非信用卡介接技術文件 ·...

Documents