POS全方位金流API技術文件

授權交易 / POS掃碼交易授權

應用場景

提供特店利用POS取得TWQR Code後呼叫綠界API進行交易授權。 

❗ 注意事項：此 API 需與銀行連線，如遇銀行連線不穩定時可能導致回應時間增加。特店如需設定 API 連線逾時的時間，建議至少 30 秒以上。

API介接網址

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

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)
特店編號 必填

OrderInfo Object
交易訂單資訊 必填

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

僅支援英文及數字

MerchantTradeDate String(20)
特店交易時間 必填

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

Amount Int
交易金額 必填

ItemName String(400)
商品名稱 必填

  • 如有多項商品，商品名稱以分隔線#分開
  • 請勿傳入超過長度 200 的內容，避免該欄位資訊被截斷

TradeDesc String(200)
交易描述 必填

ReturnURL String(200)
付款回傳結果URL 必填

請帶入可接收付款結果的URL

ChoosePayment String(20)
付款方式  必填

固定為 POS

POSInfo Object
收銀機資訊

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

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

消費者出示的QRCode

StoreID String(10)
分店代號 

StoreName String(20)
分店名稱   

StoreAddr String(200)
分店地址   

CustomField String(200)
自訂欄位 

請勿傳入超過長度200的內容，避免該欄位資訊被截斷

Data參數範例(Json格式)

				
					{
  "MerchantID": "3002607",
  "OrderInfo": {
    "MerchantTradeNo": "TEST202604290001",
    "MerchantTradeDate": "2026/04/29 13:15:00",
    "Amount": 500,
    "ItemName": "泡麵#清潔用品",
    "TradeDesc": "POS掃碼交易測試",
    "ReturnURL": "https://example.com/api/ecpay/pos/return"
  },
  "ChoosePayment": "POS",
  "POSInfo": {
    "TerminalID": "POS0000001",
    "PaymentCode": "01",
    "StoreID": "STORE001",
    "StoreName": "台北門市",
    "StoreAddr": "台北市信義區市府路1號",
    "CustomField": "內部備註欄位"
  }
}

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

MerchantID String(10)
特店編號 

RpHeader Object
回傳資料 

Timestamp Number
回傳時間 

時間戳 Unix timestamp

TransCode Int
回傳代碼 

1 代表 API 傳輸資料 (MerchantID, RqHeader, 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)
回應訊息

MerchantID String(10)
特店編號

OrderInfo Object
交易訂單資訊 

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
金流服務費 

交易手續費

ProcessFee  Number
交易處理費 

TradeStatus String(8)
交易狀態 

若為 0 時，代表交易訂單付款失敗
若為 1 時，代表交易訂單付款成功

POSInfo Object
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",
  "OrderInfo": {
    "MerchantTradeNo": "TEST202604290001",
    "TradeNo": "2504291358001234",
    "TradeAmt": 500,
    "TradeDate": "2026/04/29 13:58:00",
    "PaymentType": "POS",
    "PaymentDate": "2026/04/29 13:58:05",
    "ChargeFee": 0,
    "ProcessFee": 0,
    "TradeStatus": "1"
  },
  "POSInfo": {
    "TerminalID": "POS0000001",
    "PayFrom": "TWQR_OPAY",
    "PaymentCode": "01",
    "StoreID": "STORE001",
    "StoreName": "台北門市",
    "StoreAddr": "台北市信義區市府路1號",
    "GatewayTradeNo": "GW202604291358000001",
    "CustomField": "內部備註欄位"
  }
}

YAML

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

				
					openapi: 3.1.0
info:
  title: ECPay POS BackAuth API
  version: 1.0.0
  description: >
    POS 掃碼交易授權 API。
    特店利用 POS 取得 TWQR Code 後，呼叫綠界 API 進行交易授權。

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

paths:
  /1.0.0/POS/BackAuth:
    post:
      tags:
        - POS
      summary: POS 掃碼交易授權
      description: >
        此 API 供特店在 POS 掃碼交易情境下送出授權請求。
        注意：此 API 需與銀行連線，如遇銀行連線不穩定時可能導致回應時間增加，
        建議特店 API 連線逾時設定至少 30 秒以上。
      operationId: posBackAuth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackAuthRequest'
            examples:
              request:
                summary: 外層請求範例
                value:
                  MerchantID: "3002607"
                  RqHeader:
                    Timestamp: 1714370340
                  Data: "ENCRYPTED_DATA_STRING"
      responses:
        '200':
          description: 成功接收請求並回傳處理結果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackAuthResponse'
              examples:
                response:
                  summary: 外層回應範例
                  value:
                    MerchantID: "3002607"
                    RpHeader:
                      Timestamp: 1714370345
                    TransCode: 1
                    TransMsg: "Success"
                    Data: "ENCRYPTED_RESPONSE_DATA"

components:
  schemas:
    BackAuthRequest:
      type: object
      additionalProperties: false
      required:
        - MerchantID
        - RqHeader
        - Data
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
          example: "3002607"
        RqHeader:
          $ref: '#/components/schemas/RequestHeader'
        Data:
          type: string
          description: >
            加密過的 JSON 字串。
            實際內容為 BackAuthRequestData 結構，需先依欄位規格組成 JSON，
            再對參數值進行 URLEncode，最後依綠界加密規則處理後放入此欄位。
          example: "ENCRYPTED_DATA_STRING"

    RequestHeader:
      type: object
      additionalProperties: false
      required:
        - Timestamp
      properties:
        Timestamp:
          type: integer
          format: int64
          description: >
            傳輸時間戳，請使用 GMT+8 對應之 Unix Timestamp。
            驗證時間區間為 10 分鐘內有效。
          example: 1714370340

    BackAuthRequestData:
      type: object
      additionalProperties: false
      required:
        - MerchantID
        - OrderInfo
        - ChoosePayment
        - POSInfo
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
          example: "3002607"
        OrderInfo:
          $ref: '#/components/schemas/OrderInfoRequest'
        ChoosePayment:
          type: string
          description: 付款方式，固定為 POS
          enum:
            - POS
          example: "POS"
        POSInfo:
          $ref: '#/components/schemas/POSInfoRequest'
      example:
        MerchantID: "3002607"
        OrderInfo:
          MerchantTradeNo: "TEST202604290001"
          MerchantTradeDate: "2026/04/29 13:15:00"
          Amount: 500
          ItemName: "泡麵#清潔用品"
          TradeDesc: "POS掃碼交易測試"
          ReturnURL: "https://example.com/api/ecpay/pos/return"
        ChoosePayment: "POS"
        POSInfo:
          TerminalID: "POS0000001"
          PaymentCode: "01"
          StoreID: "STORE001"
          StoreName: "台北門市"
          StoreAddr: "台北市信義區市府路1號"
          CustomField: "內部備註欄位"

    OrderInfoRequest:
      type: object
      additionalProperties: false
      required:
        - MerchantTradeNo
        - MerchantTradeDate
        - Amount
        - ItemName
        - TradeDesc
        - ReturnURL
      properties:
        MerchantTradeNo:
          type: string
          maxLength: 20
          description: 特店交易編號，僅支援英文及數字
          pattern: '^[A-Za-z0-9]+$'
          example: "TEST202604290001"
        MerchantTradeDate:
          type: string
          maxLength: 20
          description: 特店交易時間，格式 yyyy/MM/dd HH:mm:ss
          example: "2026/04/29 13:15:00"
        Amount:
          type: integer
          description: 交易金額
          minimum: 1
          example: 500
        ItemName:
          type: string
          maxLength: 400
          description: >
            商品名稱，多項商品以 # 分隔。
            文件同時提醒請勿傳入超過 200 字內容以避免資訊被截斷，
            若作為正式實作規範，建議由業主再確認實際可接受長度。
          example: "泡麵#清潔用品"
        TradeDesc:
          type: string
          maxLength: 200
          description: 交易描述
          example: "POS掃碼交易測試"
        ReturnURL:
          type: string
          maxLength: 200
          format: uri
          description: 付款回傳結果 URL，需可接收付款結果
          example: "https://example.com/api/ecpay/pos/return"

    POSInfoRequest:
      type: object
      additionalProperties: false
      required:
        - TerminalID
        - PaymentCode
      properties:
        TerminalID:
          type: string
          maxLength: 10
          description: 終端機編號
          example: "POS0000001"
        PaymentCode:
          type: string
          maxLength: 2
          description: 付款碼編號，消費者出示的 QRCode
          example: "01"
        StoreID:
          type: string
          maxLength: 10
          description: 分店代號
          example: "STORE001"
        StoreName:
          type: string
          maxLength: 20
          description: 分店名稱
          example: "台北門市"
        StoreAddr:
          type: string
          maxLength: 200
          description: 分店地址
          example: "台北市信義區市府路1號"
        CustomField:
          type: string
          maxLength: 200
          description: 自訂欄位，避免超過 200 字以免截斷
          example: "內部備註欄位"

    BackAuthResponse:
      type: object
      additionalProperties: false
      required:
        - MerchantID
        - RpHeader
        - TransCode
        - TransMsg
        - Data
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
          example: "3002607"
        RpHeader:
          $ref: '#/components/schemas/ResponseHeader'
        TransCode:
          type: integer
          description: >
            API 傳輸結果代碼。
            1 代表 MerchantID、RqHeader、Data 接收成功；
            實際 API 執行結果請參考解密後 Data 中的 RtnCode。
          example: 1
        TransMsg:
          type: string
          maxLength: 200
          description: 回傳訊息
          example: "Success"
        Data:
          type: string
          description: >
            加密過的 JSON 字串。
            解密後內容為 BackAuthResponseData 結構。
          example: "ENCRYPTED_RESPONSE_DATA"

    ResponseHeader:
      type: object
      additionalProperties: false
      required:
        - Timestamp
      properties:
        Timestamp:
          type: integer
          format: int64
          description: 回傳時間戳，Unix Timestamp
          example: 1714370345

    BackAuthResponseData:
      type: object
      additionalProperties: false
      required:
        - RtnCode
        - RtnMsg
        - MerchantID
        - OrderInfo
        - POSInfo
      properties:
        RtnCode:
          type: integer
          description: >
            API 執行結果，1 代表成功，其餘代碼均為失敗。
            失敗代碼請參考交易訊息代碼表。
          example: 1
        RtnMsg:
          type: string
          maxLength: 200
          description: 回應訊息
          example: "Success"
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
          example: "3002607"
        OrderInfo:
          $ref: '#/components/schemas/OrderInfoResponse'
        POSInfo:
          $ref: '#/components/schemas/POSInfoResponse'
      example:
        RtnCode: 1
        RtnMsg: "Success"
        MerchantID: "3002607"
        OrderInfo:
          MerchantTradeNo: "TEST202604290001"
          TradeNo: "2504291358001234"
          TradeAmt: 500
          TradeDate: "2026/04/29 13:58:00"
          PaymentType: "POS"
          PaymentDate: "2026/04/29 13:58:05"
          ChargeFee: 0
          ProcessFee: 0
          TradeStatus: "1"
        POSInfo:
          TerminalID: "POS0000001"
          PayFrom: "TWQR_OPAY"
          PaymentCode: "01"
          StoreID: "STORE001"
          StoreName: "台北門市"
          StoreAddr: "台北市信義區市府路1號"
          GatewayTradeNo: "GW202604291358000001"
          CustomField: "內部備註欄位"

    OrderInfoResponse:
      type: object
      additionalProperties: false
      required:
        - MerchantTradeNo
        - TradeNo
        - TradeAmt
        - TradeDate
        - PaymentType
        - PaymentDate
        - ChargeFee
        - ProcessFee
        - TradeStatus
      properties:
        MerchantTradeNo:
          type: string
          maxLength: 20
          description: 特店交易編號
          example: "TEST202604290001"
        TradeNo:
          type: string
          maxLength: 20
          description: 綠界交易編號，應保存與 MerchantTradeNo 的對應關係
          example: "2504291358001234"
        TradeAmt:
          type: integer
          description: 交易金額
          example: 500
        TradeDate:
          type: string
          maxLength: 20
          description: 訂單成立時間，格式 yyyy/MM/dd HH:mm:ss
          example: "2026/04/29 13:58:00"
        PaymentType:
          type: string
          maxLength: 20
          description: 付款方式，POS 代表收銀機
          example: "POS"
        PaymentDate:
          type: string
          maxLength: 20
          description: 付款時間，格式 yyyy/MM/dd HH:mm:ss
          example: "2026/04/29 13:58:05"
        ChargeFee:
          type: number
          description: 金流服務費
          example: 0
        ProcessFee:
          type: number
          description: 交易處理費
          example: 0
        TradeStatus:
          type: string
          description: 交易狀態，0=失敗，1=成功
          enum:
            - "0"
            - "1"
          example: "1"

    POSInfoResponse:
      type: object
      additionalProperties: false
      required:
        - TerminalID
        - PayFrom
        - PaymentCode
        - GatewayTradeNo
      properties:
        TerminalID:
          type: string
          maxLength: 10
          description: 終端機編號
          example: "POS0000001"
        PayFrom:
          type: string
          maxLength: 10
          description: 付款工具，TWQR_OPAY 代表 TWQR
          example: "TWQR_OPAY"
        PaymentCode:
          type: string
          maxLength: 2
          description: 付款碼編號
          example: "01"
        StoreID:
          type: string
          maxLength: 10
          description: 分店代號
          example: "STORE001"
        StoreName:
          type: string
          maxLength: 20
          description: 分店名稱
          example: "台北門市"
        StoreAddr:
          type: string
          maxLength: 200
          description: 分店地址
          example: "台北市信義區市府路1號"
        GatewayTradeNo:
          type: string
          maxLength: 64
          description: 閘道交易編號
          example: "GW202604291358000001"
        CustomField:
          type: string
          maxLength: 200
          description: 自訂欄位，提供特店使用客製化資料
          example: "內部備註欄位"

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

綠界官方網站