查詢訂單 / 查詢訂單

應用場景

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

注意事項：

在訂單產生後的10分鐘內未收到綠界通知的付款結果，您可以使用API查詢付款結果。如遇銀行尚未回覆的情況，查詢結果中的TradeStatus交易狀態為0：未付款，請於再過10分鐘後重新查詢訂單。

API介接網址

測試環境: https://ecpayment-stage.ecpay.com.tw/1.0.0/POS/QueryTrade
正式環境: https://ecpayment.ecpay.com.tw/1.0.0/POS/QueryTrade

HTTPS 傳輸協定

Content Type：application/json
HTTP Method：POST

特店Request參數說明 (Json格式)

MerchantID String(10)
特店編號 必填

- 測試環境合作特店編號

RqHeader Object
傳輸資料 必填

Timestamp Number
傳輸時間 必填

請將傳輸時間轉換為時間戳(GMT+8)，綠界會利用此參數將當下的時間轉為 Unix TimeStamp 來驗證此次介接的時間區間。

注意事項：

驗證時間區間為 10 分鐘內有效，若超過此驗證時間則此次訂單將無法建立，產生時間戳請參考相關資料。
合作特店須進行主機「時間校正」，避免主機產生時差，導致API無法正常運作。

Data String
加密資料 必填

此參數為加密過的 JSON 格式資料，加密方式請參考說明。

特店Request參數範例 (Json格式)

				
					{
    "MerchantID": "3002607",
    "RqHeader": {
        "Timestamp": 1234567890
    },
    "Data": "enter your data"
}

加密前Data參數說明(Json格式)

注意事項：請在加密前對參數值進行 URLEncode

MerchantID String(10)
特店編號 必填

MerchantTradeNo String(20)
特店交易編號 必填

加密前Data參數範例(Json格式)

				
					{
    "MerchantID": "3002607",
    "MerchantTradeNo": "20180914001"
}

綠界Response參數說明 (Json格式)

MerchantID String(10)
特店編號

RpHeader Object
回傳資料

Timestamp Number
回傳時間

時間戳 Unix timestamp

TransCode Int
回傳代碼

1 代表 API 傳輸資料 (MerchantID, RpHeader, Data) 接收成功，實際的API執行結果狀態請參考 RtnCode 參數

TransMsg String(200)
回傳訊息

Data String
加密資料

此參數為加密過的 JSON 格式資料

綠界Response參數範例 (Json格式)

				
					{
    "MerchantID": "3002607",
    "RpHeader": {
        "Timestamp": 1234564848
    },
    "TransCode": 1,
    "TransMsg": "Success",
    "Data": "…"
}

解密後Data參數說明(Json格式)

RtnCode Int
交易狀態

1 代表 API 執行成功，其餘代碼均為失敗，失敗代碼請參考交易訊息代碼表。

RtnMsg String(200)
回應訊息

PlatformID String(10)
平台商編號

MerchantID String(10)
特店編號

OrderInfo Object
訂單資訊

MerchantTradeNo String(20)
特店交易編號

TradeNo String(20)
綠界交易編號

TradeAmt Int
交易金額

TradeDate String(20)
訂單成立時間

PaymentType String(20)
付款方式

PaymentDate String(20)
付款時間

格式為 yyyy/MM/dd HH:mm:ss

ChargeFee Number
手續費

TradeStatus String(8)
交易狀態

RefundAmount Int
退款總金額

RefundList Array
退款明細資訊

MerchantRefundNo String(20)
廠商退款訂單編號

RefundTradeNo String(20)
綠界退款訂單編號

RefundTradeDate String(20)
退款交易日期

格式為 yyyy/MM/dd HH:mm:ss

RefundAmount Int
退款金額

RefundStatus String(1)
退款交易狀態

0 : 退款作業中.
1 : 退款成功
2 : 退款失敗

RefundStatusDesc String(50)
退款狀態說明

RefundReason String(500)
退款原因

Payment String(20)
原始付款方式

GatewayRefundTradeNo String(64)
閘道退款交易編號

POSInfo Object
信用卡資訊

TerminalID String(10)
終端機編號 必填

PaymentCode String(2)
付款碼編號 必填

消費者出示的QRCode

PayFrom String(10)
付款工具 必填

TWQR_OPAY : TWQR

StoreID String(10)
分店代號

StoreName String(20)
分店名稱

StoreAddr String(200)
分店地址

CustomField String(200)
自訂欄位

提供特店使用客制化欄位

解密後Data參數範例(Json格式)

				
					{
  "RtnCode": 1,
  "RtnMsg": "Success",
  "PlatformID": "",
  "MerchantID": "3002607",
  "OrderInfo": {
    "MerchantTradeNo": "20180914001",
    "TradeNo": "2404291530001234",
    "TradeAmt": 1000,
    "TradeDate": "2026/04/29 15:10:25",
    "PaymentType": "TWQR",
    "PaymentDate": "2026/04/29 15:12:03",
    "ChargeFee": 15,
    "TradeStatus": "1",
    "RefundAmount": 300
  },
   "RefundList": [
      {
        "MerchantRefundNo": "RF202604290001",
        "RefundTradeNo": "RT202604290001",
        "RefundTradeDate": "2026/04/29 15:30:10",
        "RefundAmount": 300,
        "RefundStatus": "1",
        "RefundStatusDesc": "退款成功",
        "RefundReason": "顧客申請退款",
        "Payment": "TWQR_OPAY",
        "GatewayRefundTradeNo": "GWREFUND202604290001"
      }
    ],
  "POSInfo": {
    "TerminalID": "T123456789",
    "PaymentCode": "01",
    "PayFrom": "TWQR_OPAY",
    "StoreID": "S001",
    "StoreName": "台北信義門市",
    "StoreAddr": "台北市信義區市府路1號",
    "CustomField": "自訂欄位內容"
  }
  
}

YAML

提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。

				
					openapi: 3.1.0
info:
  title: ECPay POS QueryTrade API
  version: 1.0.0

servers:
  - url: https://ecpayment-stage.ecpay.com.tw
    description: 測試環境
  - url: https://ecpayment.ecpay.com.tw
    description: 正式環境

paths:
  /1.0.0/POS/QueryTrade:
    post:
      summary: 查詢訂單
      description: 提供特店查詢訂單資訊，可透過此 API 過濾是否為有效訂單。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryTradeRequest'
            example:
              MerchantID: "3002607"
              RqHeader:
                Timestamp: 1234567890
              Data: "enter your data"
      responses:
        '200':
          description: 成功回傳
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryTradeResponse'
              example:
                MerchantID: "3002607"
                RpHeader:
                  Timestamp: 1234564848
                TransCode: 1
                TransMsg: "Success"
                Data: "..."

components:
  schemas:

    # ── Request ──────────────────────────────────────────
    QueryTradeRequest:
      type: object
      required:
        - MerchantID
        - RqHeader
        - Data
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
        RqHeader:
          type: object
          required:
            - Timestamp
          properties:
            Timestamp:
              type: integer
              description: 傳輸時間 (Unix Timestamp GMT+8)
        Data:
          type: string
          description: 加密資料 (加密前為 QueryTradeEncryptedData JSON)

    # ── Response ─────────────────────────────────────────
    QueryTradeResponse:
      type: object
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
        RpHeader:
          type: object
          properties:
            Timestamp:
              type: integer
              description: 回傳時間 (Unix Timestamp)
        TransCode:
          type: integer
          description: 回傳代碼 (1 = 資料接收成功)
        TransMsg:
          type: string
          maxLength: 200
          description: 回傳訊息
        Data:
          type: string
          description: 加密資料 (解密後為 QueryTradeDecryptedData JSON)

    # ── 加密前 Data ───────────────────────────────────────
    QueryTradeEncryptedData:
      type: object
      required:
        - MerchantID
        - MerchantTradeNo
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
        MerchantTradeNo:
          type: string
          maxLength: 20
          description: 特店交易編號

    # ── 解密後 Data ───────────────────────────────────────
    QueryTradeDecryptedData:
      type: object
      properties:
        RtnCode:
          type: integer
          description: 交易狀態 (1 = API 執行成功，其餘為失敗)
        RtnMsg:
          type: string
          maxLength: 200
          description: 回應訊息
        PlatformID:
          type: string
          maxLength: 10
          description: 平台商編號
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
        OrderInfo:
          $ref: '#/components/schemas/OrderInfo'
        POSInfo:
          $ref: '#/components/schemas/POSInfo'
        CustomField:
          type: string
          maxLength: 200
          description: 自訂欄位

    # ── OrderInfo ─────────────────────────────────────────
    OrderInfo:
      type: object
      description: 訂單資訊
      properties:
        MerchantTradeNo:
          type: string
          maxLength: 20
          description: 特店交易編號
        TradeNo:
          type: string
          maxLength: 20
          description: 綠界交易編號
        TradeAmt:
          type: integer
          description: 交易金額
        TradeDate:
          type: string
          maxLength: 20
          description: 訂單成立時間 (格式 yyyy/MM/dd HH:mm:ss)
        PaymentType:
          type: string
          maxLength: 20
          description: 付款方式
        PaymentDate:
          type: string
          maxLength: 20
          description: 付款時間 (格式 yyyy/MM/dd HH:mm:ss)
        ChargeFee:
          type: number
          description: 手續費
        TradeStatus:
          type: string
          maxLength: 8
          description: 交易狀態
        RefundAmount:
          type: integer
          description: 退款總金額
        RefundList:
          type: array
          description: 退款明細資訊
          items:
            $ref: '#/components/schemas/RefundItem'

    # ── RefundList Item ───────────────────────────────────
    RefundItem:
      type: object
      description: 退款明細
      properties:
        MerchantRefundNo:
          type: string
          maxLength: 20
          description: 廠商退款訂單編號
        RefundTradeNo:
          type: string
          maxLength: 20
          description: 綠界退款訂單編號
        RefundTradeDate:
          type: string
          maxLength: 20
          description: 退款交易日期 (格式 yyyy/MM/dd HH:mm:ss)
        RefundAmount:
          type: integer
          description: 退款金額
        RefundStatus:
          type: string
          maxLength: 1
          description: |
            退款交易狀態
            - 0: 退款作業中
            - 1: 退款成功
            - 2: 退款失敗
          enum: ["0", "1", "2"]
        RefundStatusDesc:
          type: string
          maxLength: 50
          description: 退款狀態說明
        RefundReson:
          type: string
          maxLength: 500
          description: 退款原因
        Payment:
          type: string
          maxLength: 20
          description: 原始付款方式
        GatewayRefundTradeNo:
          type: string
          maxLength: 64
          description: 閘道退款交易編號

    # ── POSInfo ───────────────────────────────────────────
    POSInfo:
      type: object
      description: POS 資訊
      required:
        - TerminalID
        - PaymentCode
        - PayFrom
      properties:
        TerminalID:
          type: string
          maxLength: 10
          description: 終端機編號
        PaymentCode:
          type: string
          maxLength: 2
          description: 付款碼編號 (消費者出示的 QR Code)
        PayFrom:
          type: string
          maxLength: 10
          description: |
            付款工具
            - TWQR_OPAY: TWQR
          enum: ["TWQR_OPAY"]
        StoreID:
          type: string
          maxLength: 10
          description: 分店代號
        StoreName:
          type: string
          maxLength: 20
          description: 分店名稱
        StoreAddr:
          type: string
          maxLength: 200
          description: 分店地址

綠界官方網站