POS全方位金流API技術文件

退款交易 / 退款結果通知

應用場景

Server端方式(POST)
當特店呼叫退款API並有設定NotifyURL 時，可透過Server接收退款結果訊息。

  • Step1.綠界：以ServerPost方式傳送退款結果訊息至廠商的Server網址(NotifyURL)
  • 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 參數

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

MerchantTradeNo String(20)
特店交易編號

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

RefundStatus String(1)
退款交易狀態

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

RefundStatusDesc String(50)
退款狀態說明

RefundReason String(500) 
退款原因

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

RefundTradeDate String(20) 
退款交易時間

RefundAmount Int 
退款金額

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

CustomField String(200)
自訂欄位 

提供特店使用客制化欄位

Data參數範例(Json格式)

				
					{
  "RtnCode": 1,
  "RtnMsg": "Success",
  "MerchantID": "3002607",
  "MerchantTradeNo": "EC202604290001",
  "MerchantRefundNo": "RF202604290001",
  "RefundStatus": "1",
  "RefundStatusDesc": "退款成功",
  "RefundReason": "客戶取消訂單",
  "RefundTradeNo": "ECPR202604290001",
  "RefundTradeDate": "2026/04/29 15:10:00",
  "RefundAmount": 1000,
  "GatewayRefundTradeNo": "GWREFUND202604291510000001",
  "CustomField": "order_10001"
}

❗ 注意事項：

  1. 若未正確回應1|OK，系統會隔5~15分鐘後重發訊息給特店，當天重複發送四次。
  2. 若特店持續收到綠界回傳付款資訊，此時請檢查是否未正確回應1|OK給綠界，常見錯誤回傳值為(“1|OK”、1|ok、_OK 、1\OK、空白 )。

YAML

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

				
					openapi: 3.0.3
info:
  title: ECPay Refund Result Notify Webhook
  version: 1.0.0
  description: |
    綠界退款結果通知 Webhook。
    當商戶呼叫退款 API 並設定 NotifyURL 後，
    綠界會主動以 HTTP POST 將退款結果通知送至商戶端點。

servers:
  - url: https://merchant.example.com
    description: Merchant webhook endpoint host

paths:
  /ecpay/refund-result/notify:
    post:
      summary: 綠界退款結果通知
      description: |
        綠界主動呼叫商戶 NotifyURL，傳送退款結果通知。
        商戶端收到後應回傳純文字 1|OK。
      operationId: receiveRefundResultNotify
      tags:
        - ECPay Webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundResultNotifyRequest'
            examples:
              success:
                summary: 綠界通知外層範例
                value:
                  MerchantID: "3002607"
                  RpHeader:
                    Timestamp: 1234564848
                  TransCode: 1
                  TransMsg: "Success"
                  Data: "EncryptedString"
      responses:
        '200':
          description: 商戶成功接收通知
          content:
            text/plain:
              schema:
                type: string
                example: 1|OK
        '400':
          description: 商戶未正確接收或格式錯誤
          content:
            text/plain:
              schema:
                type: string
                example: 0|Error

components:
  schemas:
    RefundResultNotifyRequest:
      type: object
      required:
        - MerchantID
        - RpHeader
        - TransCode
        - TransMsg
        - Data
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
          example: "3002607"
        RpHeader:
          $ref: '#/components/schemas/RpHeader'
        TransCode:
          type: integer
          description: |
            回傳代碼。
            1 代表 API 傳輸資料（MerchantID、RpHeader、Data）接收成功。
            實際退款執行結果需參考解密後 Data 內的 RtnCode。
          example: 1
        TransMsg:
          type: string
          maxLength: 200
          description: 回傳訊息
          example: "Success"
        Data:
          type: string
          description: 加密過的 JSON 格式資料
          example: "EncryptedString"

    RpHeader:
      type: object
      required:
        - Timestamp
      properties:
        Timestamp:
          type: integer
          format: int64
          description: 回傳時間，Unix timestamp
          example: 1234564848

    RefundResultNotifyData:
      type: object
      description: Data 解密後的 JSON 結構
      required:
        - RtnCode
        - RtnMsg
        - MerchantID
        - MerchantTradeNo
        - MerchantRefundNo
        - RefundStatus
        - RefundStatusDesc
        - RefundReason
        - RefundTradeNo
        - RefundTradeDate
        - RefundAmount
        - GatewayRefundTradeNo
        - CustomField
      properties:
        RtnCode:
          type: integer
          description: 交易狀態，1 代表 API 執行成功，其餘為失敗
          example: 1
        RtnMsg:
          type: string
          maxLength: 200
          description: 回應訊息
          example: "Success"
        MerchantID:
          type: string
          maxLength: 10
          description: 特店編號
          example: "3002607"
        MerchantTradeNo:
          type: string
          maxLength: 20
          description: 特店交易編號
          example: "EC202604290001"
        MerchantRefundNo:
          type: string
          maxLength: 20
          description: 特店退款交易編號
          example: "RF202604290001"
        RefundStatus:
          type: string
          maxLength: 1
          description: 退款交易狀態
          enum:
            - "0"
            - "1"
            - "2"
          example: "1"
        RefundStatusDesc:
          type: string
          maxLength: 50
          description: 退款狀態說明
          example: "退款成功"
        RefundReason:
          type: string
          maxLength: 500
          description: 退款原因
          example: "客戶取消訂單"
        RefundTradeNo:
          type: string
          maxLength: 20
          description: 綠界退款交易編號
          example: "ECPR202604290001"
        RefundTradeDate:
          type: string
          maxLength: 20
          description: 退款交易時間
          example: "2026/04/29 15:10:00"
        RefundAmount:
          type: integer
          description: 退款金額
          example: 1000
        GatewayRefundTradeNo:
          type: string
          maxLength: 64
          description: 閘道退款交易編號
          example: "GWREFUND202604291510000001"
        CustomField:
          type: string
          maxLength: 200
          description: 自訂欄位
          example: "order_10001"

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

綠界官方網站