票券作業 / 票券退貨

應用場景

提供可使用此API執行票券退貨或取消退貨作業

API介接網址

測試環境：https://ecticket-stage.ecpay.com.tw/api/Ticket/Refund
正式環境：https://ecticket.ecpay.com.tw/api/Ticket/Refund

HTTPS傳輸協定

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

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

PlatformID String(10)
平台商或POS商編號

平台商或POS商在綠界的會員編號[MerchantID]

MerchantID String(10)
特店編號 必填

RqHeader Object
傳輸資料 必填

Timestamp Number
傳入時間 必填

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

注意事項：

驗證時間區間暫訂為10分鐘內有效，若超過此驗證時間則此次訂單將無法建立，參考資料：http://www.epochconverter.com/。
合作特店須進行主機「時間校正」，避免主機產生時差，延伸API無法正常運作。

Data String
加密資料 必填

回傳相關資料，此為加密過JSON格式的資料。加密方法說明

CheckMacValue String
檢查碼 必填

請參考附錄檢查碼機制進行計算

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

				
					{
    "PlatformID": "3002599",
    "MerchantID": "2000132",
    "RqHeader": {
        "Timestamp": 1525168923
    },
    "Data": "…",
    "CheckMacValue": "…"
}

Data參數說明(JSON格式)

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

MerchantID String(10)
特店編號 必填

TicketNo String(16)
票券序號

注意事項：

此欄位與WriteOffNo須擇一必填

WriteOffNo String(18)
核銷代碼

每張票券會有一組專屬核銷代碼，掃描消費者出示的票券Barcode取得

注意事項：

此欄位與TicketNo須擇一必填

Action String(1)
執行動作 必填

1：退貨
2：取消退貨

注意事項：

贈品券不可取消退貨

HandlingFeeRate Int
提貨券退貨手續費率

指定手續費率百分比，再由綠界依此費率計算退貨手續費

注意事項：

贈品券及超過履約保障期限的提貨券僅能輸入0
當Action=1時，如需指定退貨手續費率/金額，則此欄位與HandlingFee需擇一必填，且僅可選擇其一填寫；若未填寫則預設為0。
末2碼為小數位，e.g., 手續費為3.5%，此欄位請帶入350
因手續費不可超過或等於票面金額，故單筆退貨手續費率僅能輸入0 – 9999（即代表0% – 99.99%）

HandlingFee Int
提貨券退貨手續費金額

指定退貨手續費金額

注意事項：

贈品券及超過履約保障期限的提貨券僅能輸入0
當Action=1時，如需指定退貨手續費率/金額，此欄位與HandlingFeeRate需擇一必填，且僅可選擇其一填寫；若未填寫則預設為0。
單筆退貨手續費金額需小於票面金額，且不可為負數。

Reason String(50)
退貨或取消退貨原因

StoreID String(20)
分店編號

操作此筆票券退貨/取消退貨的分店。當有傳入此參數時，系統會檢核分店是否存在且狀態為啟用中，並判斷是否具備退貨/取消退貨權限，如不需權限控管請勿填寫。

注意事項：

請先於綠界廠商後台建立分店資料，再傳入此分店編號。
※如何建立分店資料？請參考：ECTicket發行管理平台操作手冊
限英、數字，且不可使用全形
長度限制為 2~20 個字
當欄位為空值時，代表此筆為總店執行退貨/取消退貨。

Operator String(10)
建立人員 必填

操作此筆票券退貨/取消退貨人員，僅為歷程紀錄使用

注意事項：

限英、數字，且不可使用全形

Data參數範例(JSON格式)

				
					{
    "MerchantID": "2000132",
    "TicketNo":"",
    "WriteOffNo":"LEU4loiSZ9TDTWAtxL",
    "Action":"1",
    "HandlingFeeRate":0,
    "HandlingFee":0,
    "Reason":"操作錯誤",
    "StoreID":"TP30116",
    "Operator":"LeoWang"
}

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

PlatformID String(10)
平台商或POS商編號

MerchantID String(10)
特店編號

RpHeader Object
回傳資料

Timestamp Number
回傳時間

時間戳 Unix timestamp

TransCode Int
回傳代碼

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

TransMsg String(200)
回傳訊息

Data String
加密資料

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

CheckMacValue String
檢查碼

請參考附錄檢查碼機制進行計算

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

				
					{
    "PlatformID": "3002599",
    "MerchantID": "2000132",
    "RpHeader": {
        "Timestamp": 1525169058
    },
    "TransCode": 1,
    "TransMsg": "",
    "Data": "…",
    "CheckMacValue": "…"  
}

Data參數說明(JSON格式)

RtnCode Int
回應代碼

1為成功，其餘為失敗

RtnMsg String(200)
回應訊息

HandlingFee Int
提貨券退貨手續費金額

若傳入參數有指定退貨手續費金額，則直接回傳指定的金額
若是指定手續費率，則由綠界依下列公式計算後回傳，計算公式：提貨券票券面額X指定費率(%)，小數點第一位以下無條件捨去，再四捨五入至整數位。

Data參數範例(JSON格式)

				
					{
    "RtnCode": 1,
    "RtnMsg": "新增成功",
    "HandlingFee"0
}

注意事項：

如欲取消退貨，須於退貨當日23:59前執行，系統將於退貨隔日00:00進行票務更新作業。
超過履約保障期限之「提貨券」退貨，由於款項已於價金到期時依約定撥款天期撥入廠商綠界帳戶餘額，如欲退款給原購買人，請自行與購買人確認退款方式。

綠界官方網站