POS全方位金流API技術文件

退款 / 退款功能

應用場景

當消費者選擇要退貨時，提供POS機可以呼叫API進行退款

API介接網址

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

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

原特店交易編號

MerchantRefundNo String(20)
特店退款交易編號 必填

RefundAmount int
退款金額  必填

  • 退款總金額不可超過原訂單金額

RefundReason String(500) 
退款原因

NotifyURL String(200)
退款結果通知URL  

若有填時會透過Server進行API回傳退款結果

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

				
					{
  "MerchantID": "3002607",
  "MerchantTradeNo": "EC202604290001",
  "MerchantRefundNo": "RF202604290001",
  "RefundAmount": 100,
  "RefundReason": "%E5%95%86%E5%93%81%E9%80%80%E8%B2%A8",
  "NotifyURL": "https%3A%2F%2Fyourdomain.com%2Fapi%2Fecpay%2Frefund%2Fnotify"
}

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

PlatformID String(10)
平台商編號

MerchantID String(10)
特店編號

MerchantTradeNo String(20)
特店交易編號

MerchantRefundNo String(20)
特店退款交易編號

RefundStatus String(1)
退款交易狀態

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

RefundStatusDesc String(50)
退款狀態說明

RefundReason String(500) 
退款原因

Payment String(20) 
原始付款方式

RefundTradeNo String(20) 
綠界退款交易編號

RefundTradeDate String(20) 
退款交易時間

RefundAmount Int 
退款金額

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

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

				
					{
  "RtnCode": 1,
  "RtnMsg": "Success",
  "PlatformID": "",
  "MerchantID": "3002607",
  "MerchantTradeNo": "EC202604290001",
  "MerchantRefundNo": "RF202604290001",
  "RefundStatus": "1",
  "RefundStatusDesc": "退款成功",
  "RefundReason": "商品退貨",
  "Payment": "Credit_CreditCard",
  "RefundTradeNo": "ECPRF202604290001",
  "RefundTradeDate": "2026/04/29 14:57:00",
  "RefundAmount": 100,
  "GatewayRefundTradeNo": "GWREFUND202604290001"
}

YAML

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

				
					api:
  name: POS Refund
  description: 消費者退貨時，提供 POS 機呼叫 API 進行退款
  endpoint:
    stage: https://ecpayment-stage.ecpay.com.tw/1.0.0/POS/Refund
    production: https://ecpayment.ecpay.com.tw/1.0.0/POS/Refund
  protocol:
    method: POST
    contentType: application/json

request:
  merchantId:
    type: string
    maxLength: 10
    required: true
    description: 特店編號

  rqHeader:
    type: object
    required: true
    description: 傳輸資料
    properties:
      timestamp:
        type: number
        required: true
        description: 傳輸時間，需為 GMT+8 的 Unix timestamp，驗證時間區間為 10 分鐘內

  data:
    type: string
    required: true
    encrypted: true
    description: 加密過的 JSON 格式資料

requestDataBeforeEncrypt:
  type: object
  description: 加密前 Data JSON
  note:
    - 請在加密前對參數值進行 URLEncode
  properties:
    MerchantID:
      type: string
      maxLength: 10
      required: true
      description: 特店編號

    MerchantTradeNo:
      type: string
      maxLength: 20
      required: true
      description: 原特店交易編號

    MerchantRefundNo:
      type: string
      maxLength: 20
      required: true
      description: 特店退款交易編號

    RefundAmount:
      type: int
      required: true
      description: 退款金額
      constraint:
        - 退款總金額不可超過原訂單金額

    RefundReason:
      type: string
      maxLength: 500
      required: false
      description: 退款原因

    NotifyURL:
      type: string
      maxLength: 200
      required: false
      description: 退款結果通知 URL，若有填入會透過 Server API 回傳退款結果

response:
  merchantId:
    type: string
    maxLength: 10
    description: 特店編號

  rpHeader:
    type: object
    description: 回傳資料
    properties:
      timestamp:
        type: number
        description: 回傳時間，Unix timestamp

  transCode:
    type: int
    description: 回傳代碼，1 代表 API 傳輸資料接收成功，實際執行結果請參考 RtnCode

  transMsg:
    type: string
    maxLength: 200
    description: 回傳訊息

  data:
    type: string
    encrypted: true
    description: 加密過的 JSON 格式資料

responseDataAfterDecrypt:
  type: object
  description: 解密後 Data JSON
  properties:
    RtnCode:
      type: int
      description: 交易狀態，1 代表 API 執行成功，其餘代碼為失敗

    RtnMsg:
      type: string
      maxLength: 200
      description: 回應訊息

    PlatformID:
      type: string
      maxLength: 10
      description: 平台商編號

    MerchantID:
      type: string
      maxLength: 10
      description: 特店編號

    MerchantTradeNo:
      type: string
      maxLength: 20
      description: 特店交易編號

    MerchantRefundNo:
      type: string
      maxLength: 20
      description: 特店退款交易編號

    RefundStatus:
      type: string
      maxLength: 1
      description: 退款交易狀態
      enum:
        "0": 退款作業中
        "1": 退款成功
        "2": 退款失敗

    RefundStatusDesc:
      type: string
      maxLength: 50
      description: 退款狀態說明

    RefundReason:
      type: string
      maxLength: 500
      description: 退款原因

    Payment:
      type: string
      maxLength: 20
      description: 原始付款方式

    RefundTradeNo:
      type: string
      maxLength: 20
      description: 綠界退款交易編號

    RefundTradeDate:
      type: string
      maxLength: 20
      description: 退款交易時間

    RefundAmount:
      type: int
      description: 退款金額

    GatewayRefundTradeNo:
      type: string
      maxLength: 64
      description: 閘道退款交易編號

example:
  request:
    MerchantID: "3002607"
    RqHeader:
      Timestamp: 1234567890
    Data: "encrypted_data_here"

  requestDataBeforeEncrypt:
    MerchantID: "3002607"
    MerchantTradeNo: "EC202604290001"
    MerchantRefundNo: "RF202604290001"
    RefundAmount: 100
    RefundReason: "%E5%95%86%E5%93%81%E9%80%80%E8%B2%A8"
    NotifyURL: "https%3A%2F%2Fyourdomain.com%2Fapi%2Fecpay%2Frefund%2Fnotify"

  response:
    MerchantID: "3002607"
    RpHeader:
      Timestamp: 1234564848
    TransCode: 1
    TransMsg: "Success"
    Data: "encrypted_response_data"

  responseDataAfterDecrypt:
    RtnCode: 1
    RtnMsg: "Success"
    PlatformID: ""
    MerchantID: "3002607"
    MerchantTradeNo: "EC202604290001"
    MerchantRefundNo: "RF202604290001"
    RefundStatus: "1"
    RefundStatusDesc: "退款成功"
    RefundReason: "商品退貨"
    Payment: "Credit_CreditCard"
    RefundTradeNo: "ECPRF202604290001"
    RefundTradeDate: "2026/04/29 14:57:00"
    RefundAmount: 100
    GatewayRefundTradeNo: "GWREFUND202604290001"

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

綠界官方網站