應用場景
提供特店查詢訂單資訊，可透過此API來過濾是否為有效訂單。
- Step 1. 特店：以Server POST方式傳送以下參數至API網址
- Step 2. 綠界：接受並檢核正確後，回傳訂單資訊參數。
注意事項：
- 當取得付款結果通知時，請呼叫查詢訂單API驗證付款結果
- 在訂單產生後未收到綠界通知的付款結果
- 信用卡及TWQR付款方式
- 請於付款後10分鐘使用API查詢付款結果。若遇到銀行尚未回覆的情況，查詢結果中的TradeStatus交易狀態為0：未付款，請再過10分鐘後重新查詢訂單。
- 或在付款後40分鐘後再呼叫API查詢付款結果，以避免重複呼叫查詢API。
- ATM、CVS、BARCODE及BNPL付款方式
- 因為為離線付款方式，請待綠界通知的付款結果。
- 信用卡及TWQR付款方式
- 若有多筆訂單查詢的需求，請參考下載特店對帳媒體檔。
- 假如程式呼叫 API 的速度太快，會收到 HTTP Status Code 403 的狀態碼，此時請降低呼叫 API 的速度，並等候 30 分鐘後再重新呼叫，如果有高速存取 API 的需求，請先確認您具備「特約賣家」身分，並聯繫所屬業務人員。
API介接網址
- 正式環境：https://payment.ecpay.com.tw/Cashier/QueryTradeInfo/V5
- 測試環境：https://payment-stage.ecpay.com.tw/Cashier/QueryTradeInfo/V5
HTTPS 傳輸協定
- Content Type ：application/x-www-form-urlencoded
- HTTP Method ：POST
特店傳入參數說明
MerchantID String(10)
特店編號(由綠界提供) 必填
MerchantTradeNo String(20)
特店交易編號 必填
訂單產生時傳送給綠界的特店交易編號。
TimeStamp Int
驗證時間 必填
- 將當下的時間轉為UnixTimeStamp(見範例)用於驗證此次介接的時間區間。
- 綠界驗證時間區間暫訂為 3 分鐘內有效，超過則此次介接無效。
- 參考資料：http://www.epochconverter.com/。
CheckMacValue String
檢查碼 必填
請參考附錄檢查碼機制與產生檢查碼範例程式。
PlatformID String(10)
特約合作平台商代號
為專案合作的平台商使用。
- 一般特店或平台商本身介接，則參數請帶放空值。
- 若為專案合作平台商的特店使用時，則參數請帶平台商所綁的特店編號[MerchantID]。
綠界回傳參數說明
MerchantID String(10)
特店編號
MerchantTradeNo String(20)
特店交易編號
訂單產生時傳送給綠界的特店交易編號。
StoreID String(20)
特店旗下店舖代號
TradeNo String(20)
綠界的交易編號
TradeAmt Int
交易金額
PaymentDate String(20)
付款時間
格式為yyyy/MM/dd HH:mm:ss
PaymentType String(20)
特店選擇的付款方式
HandlingCharge Number
手續費合計
PaymentTypeChargeFee Number
交易手續費金額
TradeDate String(20)
訂單成立時間
格式為yyyy/MM/dd HH:mm:ss
- 若為0時，代表交易訂單成立未付款
- 若為1時，代表交易訂單成立已付款
- 若為 10200095時，代表交易訂單未成立，消費者未完成付款作業，故交易失敗。
ItemName String(400)
商品名稱
CustomField1 String(50)
自訂名稱欄位1
提供合作廠商使用記錄用客製化使用欄位
CustomField2 String(50)
自訂名稱欄位2
提供合作廠商使用記錄用客製化使用欄位
CustomField3 String(50)
自訂名稱欄位3
提供合作廠商使用記錄用客製化使用欄位
CustomField4 String(50)
自訂名稱欄位4
提供合作廠商使用記錄用客製化使用欄位
CheckMacValue String
檢查碼
特店必須檢查檢查碼[CheckMacValue]來驗證，請參考附錄檢查碼機制。
YAML
提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。
openapi: 3.1.0
info:
title: ECPay Order Query API
version: 1.0.0
servers:
- url: https://payment.ecpay.com.tw
description: Production Environment
- url: https://payment-stage.ecpay.com.tw
description: Testing Environment
paths:
/Cashier/QueryTradeInfo/V5:
post:
summary: Query order information
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
MerchantID:
type: string
description: Merchant ID provided by ECPay
MerchantTradeNo:
type: string
description: Merchant trade number
TimeStamp:
type: integer
description: Unix timestamp of the request
CheckMacValue:
type: string
description: CheckMac value for verification
PlatformID:
type: string
description: Partner platform ID
required:
- MerchantID
- MerchantTradeNo
- TimeStamp
- CheckMacValue
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
MerchantID:
type: string
description: Merchant ID
MerchantTradeNo:
type: string
description: Merchant trade number
StoreID:
type: string
description: Store ID under the merchant
TradeNo:
type: string
description: ECPay trade number
TradeAmt:
type: integer
description: Transaction amount
PaymentDate:
type: string
description: Payment date (yyyy/MM/dd HH:mm:ss)
PaymentType:
type: string
description: Payment type selected by the merchant
HandlingCharge:
type: number
description: Total handling charge
PaymentTypeChargeFee:
type: number
description: Payment type charge fee
TradeDate:
type: string
description: Order creation date (yyyy/MM/dd HH:mm:ss)
TradeStatus:
type: string
description: Transaction status (0: not paid, 1: paid, 10200095: not completed)
ItemName:
type: string
description: Item name
CustomField1:
type: string
description: Custom field 1
CustomField2:
type: string
description: Custom field 2
CustomField3:
type: string
description: Custom field 3
CustomField4:
type: string
description: Custom field 4
CheckMacValue:
type: string
description: CheckMac value