全方位金流API技術文件

下載特店對帳媒體檔

應用場景

提供特店下載CSV格式的對帳媒體檔內容，包含各種付款方式的交易紀錄，若須信用卡退款交易記錄請參考「下載信用卡撥款對帳資料檔」單元說明。

  • Step 1. 特店：將要查詢的訂單資料條件，以POST(HTTP Method)傳送至綠界，進行查詢。
  • Step 2. 綠界：接受特店訂單查詢並檢核資料後，回傳CSV檔案格式提供特店下載。

❗ 注意事項：

  1. 此API有限制 IP 存取，請到「廠商後台->系統開發管理->系統介接設定->介接設定」設定 IP 。
  2. 同IP 僅開放一分鐘下載一個對帳媒體檔 。
  3. 請每天呼叫「下載特店對帳媒體檔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
  • 若為裕富無卡分期時，則參數請帶13
  • 若為全部時，請忽略此一參數

PlatformStatus String(1)
訂單類型 非必填

要查詢的訂單類型

  • 若為一般時，則參數請帶1
  • 若為平台時，則參數請帶2
  • 若為全部時，請忽略此一參數

PaymentStatus String(1)
付款狀態 非必填

要查詢的訂單付款狀態

  • 若為未付款時，則參數請帶0
  • 若為已付款時，則參數請帶1
  • 若為訂單失敗時，則參數請帶2
  • 若為全部時，請忽略此一參數

AllocateStatus String(1)
撥款狀態 非必填

要查詢的訂單撥款狀態

  • 若為未撥款時，則參數請帶0
  • 若為已撥款時，則參數請帶1
  • 若為全部時，請忽略此一參數

MediaFormated String(1)
CSV格式 必填

要下載的檔案格式

  • 若為V1格式時，則參數請帶0 (舊版格式)
  • 若為V2格式時，則參數請帶1 (新版格式)
  • 若為V3格式時，則參數請帶2 (2025/04/01 新增)

CharSet String(1)
檔案編碼格式 非必填

要下載的檔案編碼格式

  • 若為Big5格式時，則參數請帶1
  • 若為UTF8格式時，則參數請帶2
  • 若未傳入此參數或為空值時，預設為Server Default編碼格式

CheckMacValue String
檢查碼 必填

請參考附錄檢查碼機制

綠界回傳CSV V1 舊版檔案格式說明

交易日期 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 V2 新版檔案格式說明

訂單日期 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

❗ 注意事項：

  1. 目前信用卡退款無法在這報表取得，若要取得退款資訊請參考https://developers.ecpay.com.tw/?p=2898 
退款金額 Int

❗ 注意事項：

  1. 目前信用卡退款無法在這報表取得，若要取得退款資訊請參考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

綠界回傳CSV V3檔案格式說明​

❗ 注意事項：預計2025/04/01 上線

訂單日期 String

格式為yyyy-MM-dd hh:mm:ss

廠商訂單編號 String
綠界訂單編號 String
店鋪代號 String
MID String
平台名稱 String
付款方式 String
信用卡授權單號 String
信用卡卡號末4碼 String
超商資訊/ATM繳款帳號 String
付款狀態 String
交易金額 Int

手續費率(每筆) number

小數到第4位,四捨五入

手續費 number

小數到第2位,四捨五入

處理費 number

小數到第2位,四捨五入

交易手續費 Number
平台手續費 Number
應收款項(淨額) Number
撥款狀態 String
備註 String
廠商備註 String
商品名稱 String
交易描述 String
付款人姓名 String
付款人手機 String
付款人Email String
收件人姓名 String
收件人手機 String
收件人地址 String
收件人Email String
統一編號 String

❗ 注意事項：

  1. 下載的格式與廠商後台的「一般訂單查詢/全方位金流訂單」下載格式相同。
  2. 若查無資料時，對帳媒體檔僅包含各欄位名稱。
  3. 若發生錯誤時，對帳媒體檔除各欄位名稱之外，同時會再寫入一筆資料記錄執行時期的回傳訊息於「備註」或「廠商備註」欄位。除了上述欄位，其餘欄位皆為無值。

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=1` 時，CSV 格式如下:
                      ```
                      訂單日期, 廠商訂單編號, 綠界訂單編號, 店鋪代號, 平台名稱, 付款方式, 費率(每筆), 信用卡授權單號, 信用卡卡號末4碼, 超商資訊/ATM繳款帳號, 付款狀態, 交易金額, 退款日期, 退款金額, 交易手續費, 交易服務費金額, 應收款項(淨額), 撥款狀態, 備註, 廠商備註, 商品名稱, 交易描述, 付款人姓名, 付款人手機, 付款人Email, 收件人姓名, 收件人手機, 收件人地址, 收件人Email, 統一編號
                      ```

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

綠界官方網站