模擬串接服務 - 交易退款-折價券模式

經銷商『交易退款-折價券模式』請求欄位
Id Name Description Type Additional Information
1 agent_uid 經銷商商務代號
string 必填
2 service 服務名稱
string 必填
{ "service_name": "api", "cmd": "api\/refund" }
JSON格式,AES256加密資料
3 encry_data 『交易退款-折價券模式』欄位資料 string 必填
『交易退款-折價券模式』欄位參考
JSON格式,AES256加密資料
特約商店『交易退款-折價券模式』請求欄位
Id Name Description Type Additional Information
1 store_uid 特約商店商務代號
string 必填
2 service 服務名稱
string 必填
{ "service_name": "api", "cmd": "api\/refund" }
JSON格式,AES256加密資料
3 encry_data 『交易退款-折價券模式』欄位資料 string 必填
『交易退款-折價券模式』欄位參考
JSON格式,AES256加密資料
交易退款-折價券模式』欄位
Id Name Description Type Additional Information
1 store_uid 特約商店代碼 string 必填
2 key 交易驗証碼 string 必填
3 uid 訂單編號(UID) string 必填
4 cost 退款金額(實際支付金額)
若使用折價券模式則需為全額退款
string 必填
5 platform_fee 平台手續費
注意:此費用欄位限定角色為經銷商發動才有效
注意:平台商須有權限才能設置此費用
注意:此費用會從退款金額上扣除,故平台手續費 + 指定消費者負擔匯費 不可以大於退款金額
int
6 voucher_paid 有償折價券退款項目
注意:折價券模式,全額退款定義為(實際支付金額+所有有償折價券+所有無償折價券)
注意:若有使用有償折價券模式,則此欄位為必填
array 每筆『票券項目』欄位參考
7 voucher_free 無償折價券退款項目
注意:折價券模式,全額退款定義為(實際支付金額+所有有償折價券+所有無償折價券)
注意:若有使用無償折價券模式,則此欄位為必填
array 每筆『票券項目』欄位參考
8 invoice_state 若有開立電子發票,指定電子發票使用作廢或折讓
注意:跨發票月份無法作廢
string 『電子發票退款時使用作廢或折讓』值參考
9 items 退款項目
若使用電子發票,此欄位必填
退款項目之項目名稱必須和交易時之產品項目名稱相同
退款項目之總金額必須與退款金額一致
注意:若為全額退款時,不帶此欄位項目,系統會自動補齊
array 每筆『商品項目』欄位參考
10 user_rule 現金類退款消費者規則
注意:超商代碼、超商條碼、虛擬帳號、WEBATM...諸如此類退還現金給消費者之支付方式為必填
object 『現金類退款消費者規則』欄位參考
交易退款-折價券模式』回傳欄位
Id Name Description Type Additional Information
1 key 特約商店驗證碼 (store_token) string
2 uid 訂單編號(UID) string
3 code 處理狀態 B200 或 B500 string
4 msg 回傳訊息 string
5 row_data 退款資訊(即時退款才有此資訊) object 『退款完成回傳資訊』欄位參考
票券項目』欄位
Id Name Description Type Additional Information
1 product_id 票券群組編號(最長限32 Bytes) string
2 serial_number 票券券號(特約商店下的每一個票券群組的票券券號必須是唯一) string
電子發票退款時使用作廢或折讓』 值內容
Value Description Type Additional Information
0 沒有發票 string
4 作廢或作廢重開 string 預設
6 折讓 string
商品項目』欄位
Id Name Description Type Additional Information
1 id 商品編號 string 必填
2 name 商品名稱 string 必填
3 cost 商品單價 integer 必填
4 amount 商品數量 integer 必填
5 total 商品小計 integer 必填
現金類退款消費者規則』欄位
Id Name Description Type Additional Information
1 notification_mode 退款資訊填寫通知模式 int 『退款資訊填寫通知模式』值參考
2 user_email 消費者 E-Mail(通知模式為E-Mail時必填) string
3 return_mode 金流退還模式 int 『金流退還模式』值參考
4 remittance_fee_mode 匯費負擔類型 int 『匯費負擔類型』值參考
5 user_id_mode 交易時是否使用自己會員Id(user_id)
1.使用會員Id,消費者可以直接轉換登入Ocp帳號做填寫銀行帳戶相關資訊
2.無會員Id,消費者則需要輸入帳號密碼做登入Ocp帳號做填寫銀行帳戶相關資訊
int 『匯費負擔類型』值參考
退款完成回傳資訊』欄位
Id Name Description Type Additional Information
1 uid 原MYPAYLINK 之交易流水號 string $uid
2 refund_uid 退款之交易流水號(若多次退款,每次皆會不同) string
3 key 交易驗証碼 string
4 prc 主要交易回傳碼(retcode) string
5 finishtime 退款處理完成時間(YYYYMMDDHHmmss) string
6 order_id 貴特店系統的訂單編號 string
7 user_id 消費者帳號 string
8 cost 申請之退款金額 string
9 currency 申請之退款幣別 string
10 actual_cost 實際退款金額 string
11 voucher_paid 退還之有償票券項目 array 每筆『有償票券項目』欄位參考
12 voucher_free 退還之無償票券項目 array 每筆『無償票券項目』欄位參考
13 actual_currency 實際退款幣別 string
14 retmsg 回傳訊息 string
15 pfn 付費方法 string
16 payment_name 定期定額式/定期分期式扣款名稱 string
17 nois 定期定額式/定期分期式扣繳期數 string
18 group_id 1.定期定額式扣款編號
2.定期分期式扣款編號
string
19 refund_type 退款類型(1.直接線上退款 2.手動退款(信用卡類) 3.手動退款(現金類) string
20 expected_refund_date 現金退款預計退款日(YYYYMMDD) string
21 echo_0 自訂回傳參數 1 string
22 echo_1 自訂回傳參數 2 string
23 echo_2 自訂回傳參數 3 string
24 echo_3 自訂回傳參數 4 string
25 echo_4 自訂回傳參數 5 string
退款資訊填寫通知模式』 值內容
Value Description Type Additional Information
1 使用E-Mail通知(預設) int
金流退還模式』 值內容
Value Description Type Additional Information
1 銀行轉帳 (預設) int
匯費負擔類型』 值內容
Value Description Type Additional Information
1 消費者負擔 (預設) int
0 特約商店負擔 int
匯費負擔類型』 值內容
Value Description Type Additional Information
1 有使用特店帳號 (預設) int
0 無使用特店帳號 int
有償票券項目』欄位
Id Name Description Type Additional Information
1 product_id 票券群組編號(最長限32 Bytes) string
2 serial_number 票券券號(特約商店下的每一個票券群組的票券券號必須是唯一) string
3 name 票券名稱 string
4 cost 票券金額 integer
5 issuer 發行者 string 『有價票券發行者』值參考
6 refund_return_type 退款時,票券金額是否歸還 string 『退款時票券金額是否歸還』值參考
無償票券項目』欄位
Id Name Description Type Additional Information
1 product_id 票券群組編號(最長限32 Bytes) string
2 serial_number 票券券號(特約商店下的每一個票券群組的票券券號必須是唯一) string
3 name 票券名稱 string
4 cost 票券金額 integer
5 issuer 發行者 string 『免費票券發行者』值參考
有價票券發行者』 值內容
Value Description Type Additional Information
1 平台折價券(預設) string
2 行銷合作夥伴折價券 string
退款時票券金額是否歸還』 值內容
Value Description Type Additional Information
1 票券金額給予特店(預設) string
2 票券金額能歸還消費者 string
3 票券金額歸還經銷商 string
免費票券發行者』 值內容
Value Description Type Additional Information
1 平台折價券 string
2 行銷合作夥伴折價券 string
3 商店折價券 string
AES256資料加密方式說明

1、所有的API送出HTTPs請求之欄位中,service 和 encry_data 欄位皆進行 AES256+BASE64 加密處理。
2、AES加密,格式為CBC,長度為256bits,金鑰長度32,IV長度16,傳遞內文為加密後組合IV並經過Base64轉換後傳出。

方式:
使用自訂的AES256函式將JSON資料加密後,再將IV資料和此AES256加密後的JSON資料串聯後,使用base64再進行加密成ASCII字串即可完成加密。

    PHP加密示意:
    AesEncrypt -> base64_ecode($IV . $JSON)

    C#加密示意:
    AesEncrypt -> (bytes)IV+(bytes)Json -> toBase64

    Java加密示意:
    AesEncrypt -> (bytes)IV+(bytes)Json -> toBase64

    Node.js加密示意:
    AesEncrypt -> concat([IV,JSON], [IV_SIZE,JSON_SIZE]) -> toString('base64')
    Python加密示意:
    AesEncrypt -> (bytes)IV+(bytes)Json -> base64.b64encode

範例程式碼