POS全方位金流API技術文件

授權交易 / 付款結果通知 ReturnURL

應用場景

Server端方式(POST)(ReturnURL)
當特店會員交易完成後，特店接受綠界POS授權結果訊息，並回應接收訊息。

  • Step1.綠界：以ServerPost方式傳送授權結果訊息至廠商的Server網址(ReturnURL)
  • Step2.特店：收到綠界的授權結果訊息，回應1|OK

❗ 注意事項：

  • 1|OK 僅是廠商回應綠界是否收到通知，並不會改變付款狀態。

HTTPS 傳輸協定

  • Accept ：text/html
  • Content Type：application/json
  • HTTP Method：POST

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

MerchantID String(10)
特店編號 

RpHeader Object
回傳資料 

Timestamp Number
回傳時間 

時間戳 Unix timestamp

TransCode Int
回傳代碼 

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

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)
回應訊息

MerchantID String(10)
特店編號

SimulatePaid Int
是否為模擬付款

當交易為模擬付款時，才會回傳此欄位。回傳值為:

  • 1 : 代表此交易為模擬付款，並非是由消費者實際真的付款。所以綠界也不會撥款給特店，請勿對該筆交易做出貨等動作，以避免損失。

❗ 注意事項：

  • 特店可透過廠商後台來針對單筆訂單模擬綠界回傳付款通知，以方便介接API
  • 此功能僅只是用於測試ReturnURL是否能成功接收，不會改變付款狀態

OrderInfo JSON
訂單資訊 

MerchantTradeNo String(20)
特店交易編號 

TradeNo String(20)
綠界交易編號 

請保存綠界的交易編號與特店交易編號MerchantTradeNo的關聯。

TradeAmt Int
交易金額 

TradeDate String(20)
訂單成立時間 

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

PaymentType String(20)
付款方式 

  • POS : 收銀機

PaymentDate String(20)
付款時間 

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

ChargeFee Number
手續費 

TradeStatus String(8)
交易狀態 

  • 0 :代表交易訂單成立未付款
  • 1 : 代表交易訂單成立已付款

POSInfo JSON
POS授權資訊 

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

PayFrom String(10)
付款工具 必填

  • TWQR_OPAY : TWQR

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

消費者出示的QRCode

StoreID String(10)
分店代號 

StoreName String(20)
分店名稱   

StoreAddr String(200)
分店地址   

GatewayTradeNo String(64)
閘道交易編號 

CustomField String(200)
自訂欄位 

提供特店使用客制化欄位

Data參數範例(Json格式)

				
					{
  "RtnCode": 1,
  "RtnMsg": "Success",
  "MerchantID": "3002607",
  "SimulatePaid": 0,
  "OrderInfo": {
    "MerchantTradeNo": "TEST20260429001",
    "TradeNo": "2604291234567890",
    "TradeAmt": 150,
    "TradeDate": "2026/04/29 14:21:00",
    "PaymentType": "POS",
    "PaymentDate": "2026/04/29 14:21:35",
    "ChargeFee": 3,
    "TradeStatus": "1"
  },
  "POSInfo": {
    "TerminalID": "T0000001",
    "PayFrom": "TWQR_OPAY",
    "PaymentCode": "01",
    "StoreID": "S001",
    "StoreName": "台北門市",
    "StoreAddr": "台北市中正區重慶南路一段122號",
    "GatewayTradeNo": "GW2026042912345678901234567890",
    "CustomField": ""
  }
}

❗ 注意事項：

  1. 若未正確回應1|OK，系統會隔5~15分鐘後重發訊息給特店，當天重複發送四次。
  2. 若特店持續收到綠界回傳付款資訊，此時請檢查是否未正確回應1|OK給綠界，常見錯誤回傳值為(“1|OK”、1|ok、_OK 、1\OK、空白 )。
  3. 若遇消費者已付款，但未收到綠界回傳付款完成資訊，此時請檢查接收回傳參數的伺服器是否服務正常，導致無法接收。請參考：無法收到綠界回傳的付款結果通知
  4. 特店務必判斷交易狀態RtnCode是否為1，若非1時請勿對該筆交易做出貨動作，並取得交易訊息RtnMsg記錄失敗原因。

YAML

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

				
					openapi: 3.1.0
info:
  title: ECPay POS 付款結果通知（Webhook）
  description: |
    綠界以 Server POST 方式主動呼叫特店 ReturnURL，
    特店收到後須回應 1|OK，否則當天重送 4 次（間隔 5~15 分鐘）。
  version: 1.0.0

webhooks:
  ReturnURL:
    post:
      summary: 付款結果通知（綠界 → 特店）
      description: |
        綠界付款完成後主動 POST 至特店設定的 ReturnURL。
        特店須實作此端點來接收付款結果。
      requestBody:
        description: 綠界傳入的付款通知資料
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ECPayNotifyRequest'
            example:
              MerchantID: "3002607"
              RqHeader:
                Timestamp: 1745907695
              TransCode: 1
              TransMsg: "Success"
              Data: "（AES 加密後字串）"
      responses:
        '200':
          description: 特店成功接收，回應 1|OK
          content:
            text/plain:
              example: 1|OK

components:
  schemas:
    ECPayNotifyRequest:
      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）
        TransCode:
          type: integer
          description: 回傳代碼，1 代表傳輸資料接收成功
        TransMsg:
          type: string
          maxLength: 200
          description: 回傳訊息
        Data:
          type: string
          description: AES 加密後的 JSON 格式資料（解密後結構見 ECPayNotifyData）

    ECPayNotifyData:
      type: object
      description: Data 欄位 AES 解密後的 JSON 結構
      properties:
        RtnCode:
          type: integer
          description: 交易狀態，1 = 成功，其餘為失敗
        RtnMsg:
          type: string
          maxLength: 200
          description: 回應訊息
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
        SimulatePaid:
          type: integer
          description: 模擬付款旗標（1 = 模擬不撥款；正常交易不回傳此欄位）
        OrderInfo:
          $ref: '#/components/schemas/OrderInfo'
        POSInfo:
          $ref: '#/components/schemas/POSInfo'

    OrderInfo:
      type: object
      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: 付款方式（POS = 收銀機）
        PaymentDate:
          type: string
          maxLength: 20
          description: 付款時間，格式 yyyy/MM/dd HH:mm:ss
        ChargeFee:
          type: number
          description: 手續費
        TradeStatus:
          type: string
          maxLength: 8
          description: 交易狀態（0 = 未付款，1 = 已付款）

    POSInfo:
      type: object
      properties:
        TerminalID:
          type: string
          maxLength: 10
          description: 終端機編號（必填）
        PayFrom:
          type: string
          maxLength: 10
          description: 付款工具（必填），TWQR_OPAY = TWQR
        PaymentCode:
          type: string
          maxLength: 2
          description: 付款碼編號（必填）
        StoreID:
          type: string
          maxLength: 10
          description: 分店代號
        StoreName:
          type: string
          maxLength: 20
          description: 分店名稱
        StoreAddr:
          type: string
          maxLength: 200
          description: 分店地址
        GatewayTradeNo:
          type: string
          maxLength: 64
          description: 閘道交易編號
        CustomField:
          type: string
          maxLength: 200
          description: 自訂欄位

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

綠界官方網站