應用場景
提供特店下載CSV格式的對帳媒體檔內容,包含各種付款方式的交易紀錄,若須信用卡退款交易記錄請參考「下載信用卡撥款對帳資料檔」單元說明。
- Step 1. 特店:將要查詢的訂單資料條件,以POST(HTTP Method)傳送至綠界,進行查詢。
- Step 2. 綠界:接受特店訂單查詢並檢核資料後,回傳CSV檔案格式提供特店下載。
注意事項:
- 此API有限制 IP 存取,請到「廠商後台->系統開發管理->系統介接設定->介接設定」設定 IP 。
- 同IP 僅開放一分鐘下載一個對帳媒體檔 。
- 請每天呼叫「下載特店對帳媒體檔API」 查詢交易訂單結果進行對帳。
介接方式
- 測試環境:https://vendor-stage.ecpay.com.tw/PaymentMedia/TradeNoAio
- 正式環境:https://vendor.ecpay.com.tw/PaymentMedia/TradeNoAio
HTTPS 傳輸協定
- Content Type :application/x-www-form-urlencoded
- HTTP Method :POST
特店傳入參數說明
MerchantID String(10)
特店編號(由綠界提供) 必填
DateType String(1)
查詢日期類別 必填
要查詢的日期類別
- 若為查詢付款日期時,則參數請帶2
- 若為查詢撥款日期時,則參數請帶4
- 若為查詢訂單日期時,則參數請帶6
BeginDate String(10)
查詢開始日期 必填
要查詢的開始日期
日期格式為「yyyy-MM-dd」
EndDate String(10)
查詢結束日期 必填
要查詢的結束日期
日期格式為「yyyy-MM-dd」
PaymentType String(2)
付款方式 非必填
要查詢訂單的付款方式
- 若為信用卡時,則參數請帶01
- 若為網路ATM時,則參數請帶02
- 若為ATM 櫃員機時,則參數請帶03
- 若為超商代碼時,則參數請帶04
- 若為超商條碼時,則參數請帶05
- 若為全家條碼立即儲時,則參數請帶10
- 若為圓夢彈性分期時,則參數請帶11
- 若為TWQR行動支付時,則參數請帶12
- 若為全部時,請忽略此一參數
PlatformStatus String(1)
訂單類型 非必填
要查詢的訂單類型
- 若為一般時,則參數請帶1
- 若為平台時,則參數請帶2
- 若為全部時,請忽略此一參數
PaymentStatus String(1)
付款狀態 非必填
要查詢的訂單付款狀態
- 若為未付款時,則參數請帶0
- 若為已付款時,則參數請帶1
- 若為訂單失敗時,則參數請帶2
- 若為全部時,請忽略此一參數
AllocateStatus String(1)
撥款狀態 非必填
要查詢的訂單撥款狀態
- 若為未撥款時,則參數請帶0
- 若為已撥款時,則參數請帶1
- 若為全部時,請忽略此一參數
MediaFormated String(1)
CSV格式 必填
要下載的檔案格式
- 若為舊版格式時,則參數請帶0
- 若為新版格式時,則參數請帶1
CharSet String(1)
檔案編碼格式 非必填
要下載的檔案編碼格式
- 若為Big5格式時,則參數請帶1
- 若為UTF8格式時,則參數請帶2
- 若未傳入此參數或為空值時,預設為Server Default編碼格式
CheckMacValue String
檢查碼 必填
請參考附錄檢查碼機制
綠界回傳CSV舊版檔案格式說明
交易日期 String
格式為yyyy-MM-dd hh:mm:ss
綠界交易序號 String
特店訂單編號 String
ATM條碼 String
交易金額 Int
付款方式 String
付款結果 String
付款日期 String
格式為yyyy-MM-dd hh:mm:ss
款項來源(銀行/超商) String
通路費 Int
交易服務費率(%數 / $筆) String
交易服務費金額 Number
應收款項(淨額) Number
撥款狀態 String
撥款日期 String
格式為yyyy-MM-dd hh:mm:ss
備註 String
綠界回傳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
注意事項:
- 目前信用卡退款無法在這報表取得,若要取得退款資訊請參考https://developers.ecpay.com.tw/?p=2898
退款金額 Int
注意事項:
- 目前信用卡退款無法在這報表取得,若要取得退款資訊請參考https://developers.ecpay.com.tw/?p=2898
交易手續費 Number
平台手續費 Number
應收款項(淨額) Number
撥款狀態 String
備註 String
廠商備註 String
商品名稱 String
交易描述 String
付款人姓名 String
付款人手機 String
付款人Email String
收件人姓名 String
收件人手機 String
收件人地址 String
收件人Email String
統一編號 String
注意事項:
- 下載的格式與廠商後台的「一般訂單查詢/全方位金流訂單」下載格式相同。
- 若查無資料時,對帳媒體檔僅包含各欄位名稱。
- 若發生錯誤時,對帳媒體檔除各欄位名稱之外,同時會再寫入一筆資料記錄執行時期的回傳訊息於「備註」或「廠商備註」欄位。除了上述欄位,其餘欄位皆為無值。
YAML
提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊,方便開發人員理解和使用 API。
openapi: 3.1.0
info:
title: ECPay Reconciliation File Download API
version: 1.0.0
servers:
- url: https://vendor.ecpay.com.tw
description: Production Environment
- url: https://vendor-stage.ecpay.com.tw
description: Testing Environment
paths:
/PaymentMedia/TradeNoAio:
post:
summary: Download reconciliation file
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
MerchantID:
type: string
description: Merchant ID provided by ECPay
DateType:
type: string
description: Date type for query (2 is payment date, 4 is allocation date, 6 is order date)
BeginDate:
type: string
description: Start date for the query (yyyy-MM-dd)
EndDate:
type: string
description: End date for the query (yyyy-MM-dd)
PaymentType:
type: string
description: Payment method (optional)
PlatformStatus:
type: string
description: Order type (optional)
PaymentStatus:
type: string
description: Payment status (optional)
AllocateStatus:
type: string
description: Allocation status (optional)
MediaFormated:
type: string
description: CSV format (0 is old format, 1 is new format)
CharSet:
type: string
description: File encoding format (optional)
CheckMacValue:
type: string
description: CheckMac value for verification
required:
- MerchantID
- DateType
- BeginDate
- EndDate
- MediaFormated
- CheckMacValue
responses:
'200':
description: Successful response
content:
text/csv:
schema:
oneOf:
- type: string
format: binary
description: |
當 `MediaFormated=0` 時,CSV 格式如下:
```
交易日期,綠界交易序號,特店訂單編號,ATM條碼,交易金額,付款方式,付款結果,付款日期,款項來源,通路費,交易服務費率,交易服務費金額,應收款項,撥款狀態,撥款日期,備註
```
- type: string
format: binary
description: |
當 `MediaFormated=2` 時,CSV 格式如下:
```
訂單日期, 廠商訂單編號, 綠界訂單編號, 店鋪代號, 平台名稱, 付款方式, 費率(每筆), 信用卡授權單號, 信用卡卡號末4碼, 超商資訊/ATM繳款帳號, 付款狀態, 交易金額, 退款日期, 退款金額, 交易手續費, 交易服務費金額, 應收款項(淨額), 撥款狀態, 備註, 廠商備註, 商品名稱, 交易描述, 付款人姓名, 付款人手機, 付款人Email, 收件人姓名, 收件人手機, 收件人地址, 收件人Email, 統一編號
```