模擬串接服務 - 購買票券交易

經銷商『購買票券交易』請求欄位
Id Name Description Type Additional Information
1 agent_uid 經銷商商務代號
string 必填
2 service 服務名稱
string 必填
{ "service_name": "api", "cmd": "api\/voucherservicepurchase" }
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\/voucherservicepurchase" }
JSON格式,AES256加密資料
3 encry_data 『購買票券交易』欄位資料 string 必填
『購買票券交易』欄位參考
JSON格式,AES256加密資料
購買票券交易』欄位
Id Name Description Type Additional Information
1 sales_store_uid 銷售點特約商店代碼 string 必填
2 order_id 購買票券交易票券交易編號(唯一) string 必填
3 pfn 指定購買票券時,指定支付方式(不指定請帶0) string 必填
4 user_data 消費者資訊 object 必填
『消費者資訊』欄位參考
5 is_pre_issue 是否為預發行 integer 『是否為預發行』值參考
6 cost 總金額 string 必填
7 currency 預設交易幣別(預設為TWD新台幣) string
8 items 物品資訊 array 必填
每筆『票券項目』欄位參考
9 theme 指定佈景主題名稱 string
10 echo_0 自訂回傳參數 1 string
11 echo_1 自訂回傳參數 2 string
12 echo_2 自訂回傳參數 3 string
13 echo_3 自訂回傳參數 4 string
14 echo_4 自訂回傳參數 5 string
15 success_returl 購買交易成功導頁網址 string
16 failure_returl 購買交易失敗導頁網址 string
購買票券交易』回傳欄位
Id Name Description Type Additional Information
1 code 執行狀態碼 string 『票券執行狀態碼』值參考
2 msg 執行狀態訊息 string
3 uid 購買票券交易訂單UID string
4 key 交易驗証碼 string
5 url 交易網址(網址一分鐘內失效,只能使用一次) string
接收回報方式說明

接收到資料時,請主動回傳字串【8888】四個字元,確認完成。若貴司沒有回傳,系統會間隔十五分鐘傳送一次持續四次,若仍未接受到貴司回傳確認字串,系統即會停止傳送。

回報使用 HTTP Protocol的Post方式,內容格式為 application/x-www-form-urlencoded。

購買票券交易回傳資訊』回報欄位
Id Name Description Type Additional Information
1 uid 購買票券交易訂單UID string
2 key 交易驗証碼 string
3 code 目前狀態碼 string 『購買票券交易狀態碼』值參考
4 msg 回傳訊息 string
5 finishtime 交易完成時間(YYYYMMDDHHmmss) string
6 order_id 購買票券交易票券交易編號 string
7 user_id 消費者帳號 string
8 cost 原交易金額 string
9 currency 原交易幣別 string
10 actual_cost 實際交易金額 string
11 actual_currency 實際交易幣別 string
12 pfn 付費方法 string
13 echo_0 自訂回傳參數 1 string
14 echo_1 自訂回傳參數 2 string
15 echo_2 自訂回傳參數 3 string
16 echo_3 自訂回傳參數 4 string
17 echo_4 自訂回傳參數 5 string
票券電子發票資訊』回報欄位
Id Name Description Type Additional Information
1 uid 購買票券交易訂單UID string
2 key 交易驗証碼 string
3 order_id 購買票券交易票券交易編號 string
4 cost 交易金額 float
5 currency 交易幣別 string
6 actual_cost 實際交易金額 float
7 actual_currency 實際交易幣別 string
8 state 發票開立狀態
0.不處理 1等候處理中,2發票處理成功 3.發票處理失敗 5.系統服務異常
integer 『票券電子發票開立狀態類型』值參考
9 date 發票開立日期(YYYYMMDD) string
10 wordtrack 發票字軌 string
11 number 發票號碼 string
12 rand_code 隨機碼 string
13 seller_ban 賣方統編 string
14 buyer_ban 買方統編 string
15 left_qrcode 左邊QrCode(電子發票查詢碼) string
16 middle_barcode 中間Barcode (Code-39格式) string
17 right_qrcode 右邊QrCode(電子發票產品資訊-精簡版) string
18 amount 電子發票開立總額 string
19 sales_amount 電子發票銷售額 float
20 tax_amount 電子發票稅額 float
21 order_detail 電子發票開立之產品詳細資訊(JSON格式) string 『商品細項』值參考
22 ratetype 電子發票稅率別 integer 『電子發票稅率別』值參考
23 tax_rate 電子發票稅率 float
24 remark 發票註記(依加值中心提供註記功能) string
25 input_type 電子發票開立類型 integer 『電子發票開立類型』值參考
26 cloud_type 電子發票開立類型-雲端發票類型 integer 『雲端發票類型』值參考
27 mobile_code 當cloud_type為2時紀錄的手機條碼 string
28 tax_id 當cloud_type為2時紀錄的統一編號 string
29 natural_person 當cloud_type為3時紀錄的自然人憑證條碼 string
30 m_post_zone 當cloud_type為4時紀錄中獎時紙本發票郵遞區號 string
31 m_address 當cloud_type為4時紀錄中獎時紙本發票收件住址 string
32 love_code 當input_type為2時紀錄的愛心碼 string
33 b2b_title 當input_type為3時紀錄的發票抬頭 string
34 b2b_id 當input_type為3時紀錄的統一編號 string
35 b2b_post_zone 當input_type為3時紀錄的郵遞區號 string
36 b2b_address 當input_type為3時紀錄的發票地址 string
37 allowance 電子發票折讓資訊 array 每筆『電子發票折讓資訊』欄位參考
38 echo_0 自訂回傳參數 1 string
39 echo_1 自訂回傳參數 2 string
40 echo_2 自訂回傳參數 3 string
41 echo_3 自訂回傳參數 4 string
42 echo_4 自訂回傳參數 5 string
消費者資訊』欄位
Id Name Description Type Additional Information
1 user_id 消費者帳號 string 必填
2 user_name 消費者姓名 string
3 user_real_name 消費者真實姓名 string
4 user_english_name 消費者英文名稱 string
5 user_address_post_zone 消費者地址郵遞區號 string
6 user_address 消費者帳單地址 string
7 user_sn_type 1:身分證,2:統一證號,3:護照號碼 付款人為本國人為1,外國人2 or 3 string
8 user_sn 付款人身分證/統一證號/護照號碼 string
9 user_phone 消費者家用電話 string
10 user_cellphone_code 消費者行動電話國碼 string
11 user_cellphone 消費者行動電話 string
12 user_email 消費者 E-Mail string
13 user_birthday 消費者生日 string
14 ip 消費者來源 IP string 必填
是否為預發行』 值內容
Value Description Type Additional Information
0 即時發行(預設) integer
票券項目』欄位
Id Name Description Type Additional Information
1 issuance_uid 委託發行商商務代號 string
2 service_id 委託發行商票券服務編號(依MYTIX設定之編號) string 必填
3 id 票券產品編號(最長限32 Bytes)
限英數字([a-zA-Z0-9])
1.票券服務-一般票券 限用通用券、區域券、單店券
string 必填
4 platform_fee 平台服務費(每張票券) float
5 platform_uid 平台服務費收取商務代號 string
6 sharing 每張票券分潤比例
委託發行商 + 總部 + 銷售點 + 核銷點 需等於 1
object 必填
『票券分潤』欄位參考
7 service_rule 票券服務規則(依票券服務類型帶入處理規則) object 必填
『票券服務-一般票券』欄位參考
『票券服務-月費』欄位參考
『票券服務-課程』欄位參考
『票券服務-貨運』欄位參考
票券執行狀態碼』 值內容
Value Description Type Additional Information
100 資料不正確 string
400 系統錯誤 string
B200 執行成功 string
B500 執行失敗 string
購買票券交易狀態碼』 值內容
Value Description Type Additional Information
100 資料不正確 string
200 資料正確 string
210 交易處理中 string
250 交易成功 string
260 交易進行中(超商代碼繳費) string
270 交易進行中(虛擬帳號) string
280 交易進行中(WEBATM等導頁式交易) string
290 交易成功,但金額不符 string
300 交易失敗 string
380 交易逾時 string
400 系統錯誤 string
500 中斷交易(閘道) string
600 交易成功且結帳 (信用卡) string
A0001 中斷交易(金流) string
A0002 未完成交易 string
票券電子發票開立狀態類型』 值內容
Value Description Type Additional Information
0 不處理或已無效(預設) integer
1 等候處理中 integer
2 發票開立成功 integer
3 發票開立失敗(系統或特約商店發票相關設定不正確) integer
5 發票開立失敗(系統發生錯誤) integer
商品細項』欄位
Id Name Description Type Additional Information
1 Description 商品名稱 string 必填
2 Quantity 數量 string 必填
3 UnitPrice 單價 string 必填
4 Amount 總金額 string 必填
電子發票稅率別』 值內容
Value Description Type Additional Information
1 應稅(預設) integer
2 零稅率 integer
3 免稅 integer
電子發票開立類型』 值內容
Value Description Type Additional Information
0 未使用電子發票開立 integer
1 雲端發票 integer
2 發票捐贈 integer
3 實體發票 integer
雲端發票類型』 值內容
Value Description Type Additional Information
0 未使用雲端發票類型 integer
2 手機條碼 integer
3 自然人憑證條碼 integer
4 以E-Mail寄送 integer
電子發票折讓資訊』欄位
Id Name Description Type Additional Information
1 uid 發生之退款交易UID string
2 date 發票折讓日期(YYYYMMDD) string
3 amount 電子發票折讓金額 float
4 order_detail 電子發票折讓明細(JSON格式) string 『商品細項』值參考
票券分潤』欄位
Id Name Description Type Additional Information
1 issuance 委託發行商分潤 float 必填
2 headquarters 總部分潤 float 必填
3 sales 銷售點分潤 float 必填
4 reimbursement 核銷點分潤 float 必填
票券服務-一般票券』欄位
Id Name Description Type Additional Information
1 price 此批發行票券的每張票券面額 float 必填
2 cost 此批發行票券的每張票券內含價值
(如為無償票券,則金額請帶0)
float 必填
3 amount 購買票券數量 integer 必填
4 total_price 此批票券的面額總和 float 必填
5 total_cost 此批票券內含價值總和
(如為無償票券,則金額請帶0)
float 必填
6 trust_start_date 票券履約保證起始日 string 必填
7 trust_end_date 票券履約保證結束日(履約保證時間必須超過一年) string 必填
8 validity_end_date 票券優惠結束日(格式YYYYmmdd)
如為無償,超過此日不可核銷
如為有償,可核銷,但應該要告知消費者優惠券結束日
string 必填
9 is_custom_serial 是否使用客製票券序號
0. 沒有 1.有
integer 必填
10 serial_numbers 客製票券序號JSON資料
注意:
1.客製票券序號不能重複,且限英數字([a-zA-Z0-9])
2.長度最長32bytes
3.若購賣票券交易狀態為交易失敗、未進行交易等確定不可再進行交易,客製券號可進行回收再利用
4.如無回收未用客製票券序號機制,則請忽略3的實作,不重複即可
string
11 service_type 記名類型 integer 必填
『票券服務(一般票券)記名類型』值參考
票券服務-月費』欄位
Id Name Description Type Additional Information
1 service_type 記名類型 integer 必填
『票券服務(月費)記名類型』值參考
2 area_type 適用區域類型 integer 必填
『票券服務(月費)適用區域類型』值參考
票券服務-課程』欄位
Id Name Description Type Additional Information
1 service_type 記名類型 integer 必填
『票券服務(課程)記名類型』值參考
2 area_type 適用區域類型 integer 必填
『票券服務(課程)適用區域類型』值參考
票券服務-貨運』欄位
Id Name Description Type Additional Information
1 service_type 記名類型 integer 必填
『票券服務(貨運)記名類型』值參考
2 area_type 適用區域類型 integer 必填
『票券服務(貨運)適用區域類型』值參考
票券服務(一般票券)記名類型』 值內容
Value Description Type Additional Information
1 記名票券(預設) integer
2 不記名票券 integer
票券服務(月費)記名類型』 值內容
Value Description Type Additional Information
1 記名票券(預設) integer
票券服務(月費)適用區域類型』 值內容
Value Description Type Additional Information
1 單店券(預設) integer
2 通用券 integer
3 區域券 integer
票券服務(課程)記名類型』 值內容
Value Description Type Additional Information
1 記名票券(預設) integer
票券服務(課程)適用區域類型』 值內容
Value Description Type Additional Information
1 單店券(預設) integer
2 通用券 integer
3 區域券 integer
票券服務(貨運)記名類型』 值內容
Value Description Type Additional Information
2 不記名票券(預設) integer
票券服務(貨運)適用區域類型』 值內容
Value Description Type Additional Information
1 單店券(預設) integer
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

範例程式碼