Data Loading...
多元支付平台-WEBAPI介面規格(V1.7) Flipbook PDF
多元支付平台-WEBAPI介面規格(V1.7)
174 Views
166 Downloads
FLIP PDF 581.84KB
統一客樂得多元支付平台 WEB API 規格說明文件
系統版本：1.7 更新日期：2020 年 4 月 22 日
1
文件修改記錄 日期
版本
說明
2017-07-18
1.0
初版
2017-12-11
1.1
新增 APN 文件
2018-01-11
1.2
刷卡 API 新增
2018-01-30
1.3
API 規格 一、CVS 代收代付 2. 契客新增訂單 - 新增參數 payment_acquirerType 3. 訂單查詢 - 新增參數 cvs_acquirer_type
2018-03-20
1.3.1
API 規格：建立訂單，新增 apn_url 欄位
2018-04-11
1.3.2
CVS 代收代付-建立訂單增加檢查條件 1. 資料錯誤，「繳款人郵遞區號」必填. 2. 資料錯誤，「繳費到期日」為必填.
2018-06-13
1.3.3
新增變更金流服務簡訊簡稱功能
2018-06-25
1.3.4
API 規格：建立訂單，新增 short_url 欄位
2018-10-12
1.3.5
刷卡訂單查詢新增 card_no 欄位
2019-04-29
1.4
新增 ibon 變更繳款到期日功能
2019-07-15
1.5
CVS 契客新增訂單、COCS 契客新增刷卡訂單、COCS 契客新 增刷卡訂單-加值服務、COCS 契客新增刷卡訂單-玉山銀聯 卡以上 API 新增開立電子發票功能
2019-09-10
1.6
CVS 契客新增繳款單明細欄位
2020-04-22
1.7
COCS 繳款到期日新增分鐘制功能 增加訂單程序狀態 13(刷卡確認頁)
2
內容 說明 ............................................................................................................................................ 4 格式說明 .................................................................................................................................... 4 API 規格 ..................................................................................................................................... 5 一、 CVS 代收代付 ..................................................................................................... 5 1. 取得 Token 驗証碼 ............................................................................................ 5 2. 契客新增訂單 .................................................................................................... 6 3. 訂單查詢 .......................................................................................................... 12 4. 變更 ibon 繳款金額......................................................................................... 15 5.
變更 ibon 繳款到期日..................................................................................... 18
6. 二、
APN ................................................................................................................... 21 COCS 線上刷卡 ................................................................................................ 25
1. 2. 3. 4. 5. 6. 7.
取得 Token 驗証碼 .......................................................................................... 25 契客新增刷卡訂單 .......................................................................................... 27 銀行授權完成回報 .......................................................................................... 31 銀行授權失敗回報 .......................................................................................... 32 契客新增刷卡訂單-加值服務 ......................................................................... 33 訂單查詢 .......................................................................................................... 38 訂單取消授權 .................................................................................................. 41
8. 訂單取消交易(退貨、退款) ........................................................................... 43 9. 指定請款金額 .................................................................................................. 46 10. 契客新增刷卡訂單-玉山銀聯卡 ................................................................. 48 11. 訂單取消交易(退貨、退款) -玉山銀聯卡 ................................................. 52 12. 三、 1. 四、 1. 2.
APN ............................................................................................................... 54 主檔管理 .......................................................................................................... 58 變更金流服務簡訊簡稱 .................................................................................. 58 附件 .................................................................................................................. 59 訂單程序狀態一覽表 ...................................................................................... 59 分期參數 .......................................................................................................... 60
3
說明 提供契約客戶使用多元支付平台 CVS 代收代付與 COCS 線上刷卡 API 串接服務。
格式說明 1. 2. 3. 4.
傳輸資料皆採用 JSON 格式處理，UTF-8 編碼。 規格中無特別註明 Content-Type，則一律使用 application/json。 採用.NET 內建 OAuth 認證協定授權。 若程式需要 Token 驗證，則 Content-Type 使用 application/x-www-formurlencoded。
5. Token 應放置於 HTTP Header 中傳送。 Ex: Authorization: Bearer VKJ0qMXkD27J5ZaDu8ygWrFuK…
4
API 規格 一、
1.
CVS 代收代付
取得 Token 驗証碼
提供契約客戶 API 帳密驗證作業，驗證完成後為此帳號產出一組有時效性的 Token，授 權該帳號存取相關功能使用；Token 過期後，契客將無法繼續使用此 Token 存取相關功 能，直到重新驗證帳密產出新 Token 為止。
POST /Token ※傳輸網址：https://4128888card.com.tw/Token ※傳送資料： Content-Type: application/x-www-form-urlencoded 欄位
型態
長度
必填
加密
說明
grant_type
string
20
Y
授權方式(固定帶入 password)
username
string
20
Y
會員帳號
password
string
20
Y
會員 API 密碼
※回覆資料 欄位
型態
說明
access_token
string
存取憑證
token_type
string
憑證種類
expires_in
string
有效期(單位”秒”，預設 1 天)
userName
string
會員帳號
.issued
datetime
建立時間(GMT)
.expires
datetime
到期時間(GMT)
※錯誤回覆 欄位
型態
說明
Error
string
invalid_grant
error_description
string
使用者名稱或密碼不正確。
※Sample 5
Send { “grant_type”: “password”, “username”: “12656354001”, “password”: “1q2w” } Response 成功： { "access_token": "nII7I64yQLVIY8OBeKAn1K…", "token_type": "bearer", “expires_in": 86399, "userName": "12656354001", ".issued": " Tue, 18 Jul 2017 02:53:12 GMT", ".expires": " Wed, 19 Jul 2017 02:53:12 GMT" } 失敗： { “error”: “invalid_grant” “error_description”: “使用者名稱或密碼不正確。” }
2.
契客新增訂單
契約客戶透過 API 新增訂單。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CvsOrderAppend)
6
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
契客訂單號碼（契約客戶自 定之識別用號碼，該號碼在 同一契約客戶代號下必須為 唯一）
order_amount
number
Y
代繳金額
expire_date
string
10
Y
繳費到期日(YYYY-MM-DD)
payer_name
string
50
Y
繳款人姓名
payer_postcode
string
10
Y
繳款人郵遞區號
payer_address
string
240
Y
繳款人地址
payer_mobile
string
30
Y
繳款人手機
payer_email
string
240
Y
繳款人電子郵件
payment_type
string
2
Y
繳款方式 0: ibon 繳款 1: ATM 銀行轉帳 2:三段式條碼
payment_acquirerType string
2
收單行(預設 0:玉山) 0:玉山 1:中信
apn_url
250
APN 指定傳送網址(選填，若
string
沒有填寫則取得金流服務中 的 APN 網址) 繳款單明細
order_detail
string
50
b2c
string
1
電子 發票
此訂單是否開立電子發票 0:不開立 1:開立
product_name
string
60
電子 發票
商品名稱(必填)
print_invoice
string
1
電子 發票
是否列印紙本發票(必填) 0:不列印 1:列印
vehicle_type
string
1
電子 發票
載具類別 1:會員載具 2:手機條碼 3:自然人憑證
vehicle_barcode
string
20
電子
載具條碼
7
發票 donate_invoice
string
1
電子 發票
是否捐贈發票(必填) 0:不捐贈 1:捐贈
love_code
string
20
電子 發票
愛心碼(選捐贈。愛心碼如不 輸入，預設為創世基金會 919)
buyer_bill_no
string
8
電子 發票
買方統一編號
buyer_invoice_title
string
161
電子 發票
發票抬頭
buyer_invoice_zip
string
5
電子 發票
買方統編發票寄送郵遞區號
buyer_invoice_addr
string
240
電子 發票
買方統編發票寄送地址
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
order_amount
number
代繳金額
expire_date
string
繳費到期日(YYYY-MM-DD)
ibon_code
string
ibon 碼
ibon_shopid
string
安源 ibon 廠商代碼
virtual_account
string
代繳帳號(ATM 轉帳帳號)
st_barcode1
string
超商條碼 1
st_barcode2
string
超商條碼 2
st_barcode3
string
超商條碼 3
bill_amount
number
帳單金額
cs_fee
number
超商手續費
cvs_acquirer_type
string
收單行(預設 0:玉山) 0:玉山 1:中信 2:安源 ibon 8
short_url
string
短網址
print_invoice
string
是否列印紙本發票 0:不列印 1:列印
vehicle_type
string
載具類別 1:會員載具 2:手機條碼 3:自然人憑證
vehicle_barcode
string
載具條碼
donate_invoice
string
是否捐贈發票 0:不捐贈 1:捐贈
love_code
愛心碼
string
※Sample Send { “cmd”: “CvsOrderAppend”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010723”, “order_amount”: 50, “expire_date”: “2017-07-18”, “payer_name”: “王大明”, “payer_postcode”: “260”, “payer_address”: “宜蘭市中山路 111 號”, “payer_mobile”: “0970325698”, “payer_email”: “[email protected]”, “payment_type”: “1”, “payment_acquirerType”: “0”, “apn_url”: “”, “b2c”: “1”, “product_name”: “手機”, “print_invoice”: “0”, “vehicle_type”: “1”, “vehicle_barcode”: “”, “donate_invoice”: “0”, “love_code”: “”, 9
“buyer_bill_no”: “”, “buyer_invoice_title”: “”, “buyer_invoice_zip”: “”, “buyer_invoice_addr”: “” } Response 成功： { “status”: “OK” “cust_order_no”: “20170718010712”, “order_amount”: 50, “expire_date”: “2017-07-18”, “ibon_code”: “719906142811”, “ibon_shopid”: “CCAT”, “virtual_account”: “”, “st_barcode1”: “”, “st_barcode2”: “”, “st_barcode3”: “”, “bill_amount”: 50, “cs_fee”: 0, “cvs_acquirer_type”: “0”, “short_url”: “https://goo.gl/PV1EZ3”, “print_invoice”: “0”, “vehicle_type”: “1”, “vehicle_barcode”: “”, “donate_invoice”: “0”, “love_code”: “” } 失敗： { “status”: “ERROR”, “msg”: “新增訂單失敗” } ※異常訊息列表 項目 項目名稱 1
cmd 資料不正確.
2
資料錯誤，「代繳金額」必須為數值. 10
3
資料錯誤，「繳費到期日」必須為日期或時間.系統解析您輸入的繳費到期日 為:XXXXX
4
資料錯誤，「繳費到期日」為必填.
5
契客未設定回應網址.
6
契約客戶資料不正確.
7
契約客戶資料不存在.
8
使用者密碼不可超過 40 碼.
9
使用者登入失敗，帳號或密碼錯誤.
10
使用者登入失敗, 使用者已經停用.
11
資料錯誤，「契客訂單號碼」必須為填寫.
12
資料錯誤，您已經上傳過此一「契約訂單號碼」：XXXXX，不可再次上傳.
13
資料錯誤，「契客訂單號碼」超過長度限制 30 碼.
14
資料錯誤，「代繳金額」必須為數值.
15
資料錯誤，「代繳金額」不可有小數位
16
資料錯誤，「代繳金額」必須小於 XXXXX
17
資料錯誤，「代繳金額」必須大於 XXXXX
18
資料錯誤，「繳費到期日」日期必須為未來 XXXXX 日至 XXXXX 日之間.系統解 析您輸入的繳費到期日為:XXXXX
19
資料錯誤，「繳款人郵遞區號」超過長度限制 10 碼.
20
資料錯誤，「繳款人郵遞區號」必填.
21
資料錯誤，「繳款人手機號碼」超過長度限制 30 碼.
22
資料錯誤，「繳款方式有誤」
23
資料錯誤，「代繳金額」必須大於契客手續費 XXXXX
24
金流服務已停用
25
金流服務尚未開始
26
金流服務已過期
27
繳費到期日超過金流服務有效日期[XXXXX]
28
繳款人手機必填
29
金流服務包含電子郵件，繳款人電子郵件必填
30
金流服務包含 PDF 附件，繳款人姓名及地址必填
31
新增訂單失敗!!
32
尚未啟用電子發票功能
33
是否印製紙本發票未輸入或格式錯誤
34
是否捐贈發票未輸入或格式錯誤
35
捐贈發票、統編(公司戶)發票、印製紙本發票或共通載具只能選一種
36
請輸入捐贈、紙本列印發票或使用發票載具 11
3.
37
請輸入載具類型
38
資料錯誤，「載具條碼」必填
39
載具條碼格式有誤
40
資料錯誤，「載具條碼」必填
41
載具條碼格式有誤
42
資料錯誤，「商品名稱」必填
43
資料錯誤，買方統一編號錯誤
44
資料錯誤，「發票抬頭」必填
45
資料錯誤，「買方統編發票寄送郵遞區號」必填
46
資料錯誤，「買方統編發票寄送郵遞區號」格式錯誤
47
資料錯誤，「買方統編發票寄送地址」必填
訂單查詢
契約客戶透過 API 查詢代繳資訊。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CvsOrderQuery)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
契客訂單號碼
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況 12
cust_order_no
string
契客訂單號碼
order_amount
number
代繳金額
expire_date
string
繳費到期日(yyyy-MM-dd)
ibon_code
string
ibon 碼
ibon_shopid
string
安源 ibon 廠商代碼
virtual_account
string
代繳帳號(ATM 轉帳帳號)
st_barcode1
string
超商條碼 1
st_barcode2
string
超商條碼 2
st_barcode3
string
超商條碼 3
bill_amount
number
帳單金額（需列印於帳單上之帳單金 額）
cs_fee
number
超商手續費
create_time
string
代繳資訊建立時間 (yyyy-MM-dd HH:mm:ss )
process_code
number
訂單程序狀態代碼 (參考附件 1)
process_code_update_time
string
訂單程序狀態變更日期 (yyyy-MM-dd HH:mm:ss)
pay_date
string
繳款日期(yyyy-MM-dd HH:mm:ss )
grant_amount
number
（預計）撥款金額
grant_date
string
撥款日期(yyyy-MM-dd)
cvs_acquirer_type
string
收單行(預設 0:玉山) 0:玉山 1:中信 2:安源 ibon 短網址
short_url print_invoice
string
是否列印紙本發票 0:不列印 1:列印
vehicle_type
string
載具類別 1:會員載具 2:手機條碼 3:自然人憑證
vehicle_barcode
string
載具條碼
donate_invoice
string
是否捐贈發票 0:不捐贈 1:捐贈
love_code
string
愛心碼 13
invoice_no
string
發票號碼
invoice_date
string
發票日期
random_number
string
隨機碼
※Sample Send { “cmd”: “CvsOrderQuery”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010712” } Response 成功： { “status”: “OK” “cust_order_no”: “20170718010712”, “order_amount”: 50, “expire_date”: “2017-07-18”, “ibon_code”: “719906142811”, “ibon_shopid”: “CCAT”, “virtual_account”: “”, “st_barcode1”: “”, “st_barcode2”: “”, “st_barcode3”: “”, “bill_amount”: 50, “cs_fee”: 0, “create_time”: “2017-07-18 13:46:55”, “process_code”: 2, “process_code_update_time”: “2017-07-18 13:46:59”, “pay_date”: “”, “grant_amount”: 0, “grant_date”: “”, “cvs_acquirer_type”: “0”, “print_invoice ”: “0”, “vehicle_type”: “1”, “vehicle_barcode”: “”, “donate_invoice”: “0”, 14
“love_code”: “”, “invoice_no”: “”, “invoice_date”: “”, “random_number”: “” } 失敗： { “status”: “ERROR”, “msg”: “取得查詢代繳資訊失敗” } ※異常訊息列表 項目 項目名稱
4.
1
cmd 資料不正確.
2
契約客戶資料不正確.
3
契約客戶資料不存在.
4
使用者密碼不可超過 40 碼.
5
使用者登入失敗，帳號或密碼錯誤.
6
使用者登入失敗, 使用者已經停用.
7
必須要有參數+cust_order_no
8
找不到此筆代繳資訊
9
取得查詢代繳資訊失敗
變更 ibon 繳款金額
契約客戶透過 API 針對已新增訂單繳款方式為 ibon 繳款的訂單變更繳款金額。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 15
CvsIbonUpdate) cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
契客訂單編號，必須是已建立 的繳款單
order_amount
number
Y
異動後的繳款單金額
ibon_shopid
string
14
Y
廠商代碼(CCAT、BCAT)
ibon_code
string
20
Y
ibon 代碼
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
order_amount
number
代繳金額
expire_date
string
繳費到期日 (YYYY-MM-DD)
ibon_code
string
ibon 碼
ibon_shopid
string
安源 ibon 廠商代碼
virtual_account
string
代繳帳號(ATM 轉帳帳號)
st_barcode1
string
超商條碼 1
st_barcode2
string
超商條碼 2
st_barcode3
string
超商條碼 3
bill_amount
number
帳單金額
cs_fee
number
超商手續費
※Sample Send { “cmd”: “CvsIbonUpdate”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010712”, “order_amount”: 80, “ibon_shopid”: “CCAT”, 16
“ibon_code”: “719906142811” } Response 成功： { “status”: “OK” “cust_order_no”: “20170718010712”, “order_amount”: 50, “expire_date”: “2017-07-18”, “ibon_code”: “719906142811”, “ibon_shopid”: “CCAT”, “virtual_account”: “”, “st_barcode1”: “”, “st_barcode2”: “”, “st_barcode3”: “”, “bill_amount”: 80, “cs_fee”: 0 } 失敗： { “status”: “ERROR”, “msg”: “變更 ibon 繳款金額失敗” } ※異常訊息列表 項目 項目名稱 1
cmd 資料不正確.
2
契約客戶資料不正確.
3
契約客戶資料不存在.
4
使用者密碼不可超過 40 碼.
5
使用者登入失敗，帳號或密碼錯誤.
6
使用者登入失敗, 使用者已經停用.
7
資料錯誤，「代繳金額」必須為數值.
8
資料錯誤，「繳費到期日」必須為日期或時間.系統解析您輸入的繳費到期日 為: XXXXX
9
契客未設定回應網址.
10
必須要有參數+cust_order_number 17
5.
11
必須要有參數+order_amount
12
必須要有參數+ibon_code
13
必須要有參數+ibon_shopid
14
契約客戶無法變更金額
15
繳款單資料不存在
16
繳款單不允許變更金額
17
參數 ibon_shopid 不正確
18
繳款單狀態已無法變更金額
19
變更繳款單「代繳金額」不能小於 0 元
20
變更繳款單「代繳金額」必須大於契客手續費 XXXXX
21
變更後帳單金額超過單筆 20000 元繳款上限
變更 ibon 繳款到期日
契約客戶透過 API 針對已新增訂單繳款方式為 ibon 繳款的訂單變更繳款到期日。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CvsIbonUpdateDate)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
契客訂單編號，必須是已建立 的繳款單
order_amount
number
Y
異動後的繳款單金額
expire_date
string
Y
繳費到期日 (YYYY-MM-DD)
ibon_shopid
string
14
Y
廠商代碼(CCAT、BCAT)
ibon_code
string
20
Y
ibon 代碼
nonce
string
10
Y
隨機數，不會重覆的時間+亂 數組合採用時分秒+亂數產 18
生:HHNNSSRRRR HHNNSS:主機時間的時分秒(6 位數) RRRR:四位數隨機亂數 checksum
string
32
檢核驗證碼比對 checksum 的 內容是否與下列運算後的結果 相同，相同的 MD5 結果表示 這個訊息的內容與原始資料相 符。
Y
checksum = MD5 (cust_order_no + ":" + order_amount +":" + nonce ) ※回覆資料 欄位
型態
說明
status
string
回應狀態 僅 OK 與 ERROR 兩種訊息狀態，OK 為 處理成功，ERROR 為處理時發生異常 狀況
cust_order_no
string
契客訂單號碼
order_amount
number
代繳金額
expire_date
string
繳費到期日 (YYYY-MM-DD)
ibon_code
string
ibon 碼
ibon_shopid
string
安源 ibon 廠商代碼
virtual_account
string
代繳帳號(ATM 轉帳帳號)
st_barcode1
string
超商條碼 1
st_barcode2
string
超商條碼 2
st_barcode3
string
超商條碼 3
bill_amount
number
帳單金額
cs_fee
number
超商手續費
create_time
string
訂單建立日期
process_code
number
訂單狀態
process_code_update_time
string
訂單狀態變更時間
pay_date
string
繳款日期(yyyy-MM-dd HH:mm:ss )
grant_amount
number
（預計）撥款金額
grant_date
string
撥款日期(yyyy-MM-dd) 19
cvs_acquirer_type
收單行(預設 0:玉山)
string
0:玉山、1:中信、2: ibon (安源) short_url
短網址
string
※Sample Send { “cmd”: “CvsIbonUpdateDate”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20190402000001”, “order_amount”: 250, “expire_date”: “2019-04-07”, “ibon_shopid”: “CCAT”, “ibon_code”: “909606553021”, “nonce”:”21”, “checksum”:” e309160d46bcefaa7dd8db18a23f179f” } 這個例子中，checksum 的產生方式是 MD5(20190402000001:250:21) Response 成功： { "msg": "", "status": "OK", "cust_order_no": "20190402000001", "order_amount": 250, "expire_date": "2019-04-07", "ibon_code": "909606553021", "ibon_shopid": "CCAT", "virtual_account": "", "st_barcode1": "", "st_barcode2": "", "st_barcode3": "", "bill_amount": 280, "cs_fee": 0, "create_time": "2019-04-02 17:34:05", "process_code": 6, "process_code_update_time": "2019-04-02 18:14:31", 20
"pay_date": "2019-04-02 18:14:31", "grant_amount": 220, "grant_date": "", "cvs_acquirer_type": "2", "short_url": null } 失敗： { “status”: “ERROR”, “msg”: “變更 ibon 繳款日期失敗” } ※異常訊息列表 項目 項目名稱
6.
1
cmd 資料不正確.
2
契約客戶資料不正確.
3
契約客戶資料不存在.
4
使用者密碼不可超過 40 碼.
5
使用者登入失敗，帳號或密碼錯誤.
6
使用者登入失敗, 使用者已經停用.
7
檢核驗證碼不正確.
8
資料錯誤，「繳費到期日」必須為日期或時間.系統解析您輸入的繳費到期日 為: XXXXX
9
必須要有參數+cust_order_number
10
必須要有參數+order_amount
11
必須要有參數+ibon_code
12
必須要有參數+ibon_shopid
13
繳款單資料不存在
14
參數 ibon_shopid 不正確
APN
當您使用了我們的繳款服務，成為簽約的客戶後，您可以使用我們提供的系統後端介 接 (Server To Server)繳款狀態更新通知功能，讓您在每筆繳款交易的狀態變更時 (例 如：繳款完成、繳款單逾期...) 能夠最快收到通知，讓您的前後端系統即時更新訂單資 料。 如果要啓用這個功能，請準備一個接收通知的 URL，並向相關單位人員提出申請，我 21
們的系統會在您每一筆交易的繳款狀態變化時利用 HTTP POST 方式發送到您指定的 URL，通知的內容包含了所有繳款資料的必要欄位與內容，您的主機程式會從系統接收 到以 json 封裝的繳款單資料，就可以從解析後的資料取得您需要的繳款單內容。 ※傳輸資料格式 欄位
說明
Description
1.以 json 格式封裝繳款單資料做為傳輸的訊息。 2.ContentType = application/json。 3.使用 checksum 確保資料的安全性。
URL
在多元支付平台後台管理系統，登錄的契客回傳網址
Method
POST
Retrun
契客接收端接收到資料後，應回傳 OK 字串訊息給 APN 傳送端； 若無接收到任何回應，則 APN 傳送端將會繼續傳送通知訊息，最多傳 送 3 次。
※傳送資料： 欄位
型態
長 度
加 密
說明
api_id
string
32
配發給契客的系統識別碼
trans_id
string
32
每個繳款單都有一個唯一的交易識 別碼
order_no
string
20
契客訂單編號
amount
number
expire_time
string
25
繳款逾期時間， 格式:YYYY-MM-DDTHH:NN:SS+08:00 (年-月-日 T 時:分:秒+08:00)
status
string
1
狀態碼 A=等待繳款人繳納 B=繳款人已繳納 C=契客註定註銷 D=已過期繳款單
繳款單金額
E=已預約撥款給契客 I=開立發票通知 J=開立發票折讓單號通知 payment_code
number
payment_detail
Object
客樂得代收代繳服務=2 { 22
"st_barcode1":"超商條碼 1", "st_barcode2":"超商條碼 2", "st_barcode3":"超商條碼 3", "st_barcode_note":"超商備註", "bank_id":"銀行代號", "virtual_account":"代繳帳號", "atm_note":"銀行備註", "ibon_shopid":"ibon 廠商代碼", "ibon_code":"ibon 代碼", "ibon_note":"ibon 備註" } 保留使用
memo
Object
create_time
string
25
繳款單建立時間， 格式:YYYY-MM-DDTHH:NN:SS+08:00 (年-月-日 T 時:分:秒+08:00)
modify_time
string
25
狀態更新時間， 格式:YYYY-MM-DDTHH:NN:SS+08:00 (年-月-日 T 時:分:秒+08:00)
nonce
string
10
隨機數，不會重覆的時間+亂數組合 採用時分秒+亂數產生:HHNNSSRRRR HHNNSS:主機時間的時分秒(6 位數) RRRR:四位數隨機亂數
checksum
string
32
檢核驗證碼比對 checksum 的內容是 否與下列運算後的結果相同，相同 的 MD5 結果表示這個訊息的內容與 原始資料相符。 checksum = MD5 ( api_id +":" + trans_id +":" + amount+":" + status +":" + nonce )
print_invoice
string
1
是否列印紙本發票 0:不列印 1:列印
vehicle_type
string
1
載具類別 1:會員載具 23
2:手機條碼 3:自然人憑證 vehicle_barcode
string
20
載具條碼
donate_invoice
string
1
是否捐贈發票 0:不捐贈 1:捐贈
love_code
string
20
愛心碼
invoice_no
string
10
發票號碼
invoice_date
string
10
發票日期
random_number
string
4
隨機碼
16
折讓單號
invoice_discount_no string ※Sample
Response 當契客使用代收代繳款服務後，來自 APN 的回傳訊息 { "api_id":"CV0000000000", "trans_id":"550e8400e29b41d4a716446655440000", "order_no":"PO5488277", "amount":1250, "expire_time":"2013-09-28T08:15:00+08:00", "status":"D", "payment_code":2, "payment_detail": { "st_barcode1":"030222619", "st_barcode2":"9821400000096500", "st_barcode3":"030258000000050", "st_barcode_note":"外加", "bank_id":"808", "virtual_account":"98214000000965", "atm_note":"內含", "ibon_shopid":"CCAT", "ibon_code":"405300000960", "ibon_note":"外加" }, "memo":"", "create_time":"2016-04-03T08:00:00+08:00", "modify_time":"2016-04-08T08:30:00+08:00", 24
"nonce":"1234569999", "checksum":"3579609ba3914a49441e98cb7e8a55de" "print_invoice":"0", "vehicle_type":"2", "vehicle_barcode":"/1234567", "donate_invoice":"", "love_code":"", "invoice_no":"", "invoice_date":"", "random_number":"", "invoice_discount_no":"" } 這個例子中，checksum 的產生方式是 MD5(CV0000000000:550e8400e29b41d4a716446655440000:1250:D:1234569999)
二、
1.
COCS 線上刷卡
取得 Token 驗証碼
提供契約客戶 API 帳密驗證作業，驗證完成後為此帳號產出一組有時效性的 Token，授 權該帳號存取相關功能使用；Token 過期後，契客將無法繼續使用此 Token 存取相關功 能，直到重新驗證帳密產出新 Token 為止。
POST /Token ※傳輸網址：https://4128888card.com.tw/Token ※傳送資料： Content-Type: application/x-www-form-urlencoded 欄位
型態
長度
必填
加密
grant_type
string
20
Y
授權方式(固定帶入 password)
username
string
20
Y
會員帳號
password
string
20
Y
會員 API 密碼
※回覆資料 欄位
型態
說明 25
說明
access_token
string
存取憑證
token_type
string
憑證種類
expires_in
string
有效期(單位”秒”，預設 1 天)
userName
string
會員帳號
.issued
datetime
建立時間(GMT)
.expires
datetime
到期時間(GMT)
※錯誤回覆 欄位
型態
說明
error
string
invalid_grant
error_description
string
使用者名稱或密碼不正確。
※Sample Send { “grant_type”: “password”, “username”: “12656354001”, “password”: “1q2w” } Response 成功： { "access_token": "nII7I64yQLVIY8OBeKAn1K…", "token_type": "bearer", “expires_in": 86399, "userName": "12656354001", ".issued": " Tue, 18 Jul 2017 02:53:12 GMT", ".expires": " Wed, 19 Jul 2017 02:53:12 GMT" } 失敗： { “error”: “invalid_grant” “error_description”: “使用者名稱或密碼不正確。” }
26
2.
契客新增刷卡訂單
契約客戶透過 API 新增刷卡訂單。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CocsOrderAppend)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
契客訂單號碼（契約客戶自定 之識別用號碼，該號碼在同一 契約客戶代號下必須為唯 一）。可不輸入，當此欄位為 空時，系統將會自動產生 YYYYMMDD######的號碼，前 八碼為西元年月日，後六碼為 該日期內之訂單流水號，從 1 開始累增，例如： 20170718000003
order_amount
number
order_detail
string
acquirer_type
string
Y
訂單/交易金額
150
Y
訂單明細
20
Y
指定收單銀行 esun: 玉山銀行 chinatrust: 中國信託銀行
limit_product_id
string
50
Y
限定產品別（可不輸入，當此 欄位為空時，意為允許所有產 品別。各產品別以”|”分隔） (參考附件 2) 例如：esun.normal|esun.m3
send_time
string
10
Y
傳送時間，必須為傳送時之最 27
新時間，格式為 yyyy-MM-dd HH:mm:ss，例如：2017-07-18 07:17:25 success_url
string
250
apn_url
string
250
訂單授權成功指定回傳 URL 若此參數有傳入 URL，授權成 功回覆 URL 會帶入此網址，若 沒有輸入會依客樂得金流服務 設定中授權成功所指定網址回 傳
Y
APN 指定傳送網址(選填，若沒 有填寫則取得金流服務中的 APN 網址)
b2c
string
1
電子 發票
此訂單是否開立電子發票 0:不開立 1:開立
product_name
string
60
電子 發票
商品名稱(必填)
print_invoice
string
1
電子 發票
是否列印紙本發票(必填) 0:不列印 1:列印
vehicle_type
string
1
電子
載具類別
發票
1:會員載具 2:手機條碼 3:自然人憑證
vehicle_barcode
string
20
電子 發票
載具條碼
donate_invoice
string
1
電子 發票
是否捐贈發票(必填) 0:不捐贈 1:捐贈
love_code
string
20
電子 發票
愛心碼(選捐贈。愛心碼如不輸 入，預設為創世基金會 919)
payer_name
string
50
電子 發票
繳款人姓名(必填)
payer_postcode
string
10
電子 發票
繳款人郵遞區號(必填)
payer_address
string
240
電子 發票
繳款人地址(必填)
28
payer_mobile
string
30
電子
繳款人手機(必填)
發票
發票中獎後簡訊通知
payer_email
string
240
電子 發票
繳款人電子郵件(必填) 開立電子發票及發票中獎 EMAIL 通知
buyer_bill_no
string
8
電子 發票
買方統一編號
buyer_invoice_title
string
161
電子 發票
發票抬頭
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
url
string
產生訂單對應的線上刷卡網址
※Sample Send { “cmd”: “CocsOrderAppend”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010723”, “order_amount”: 50, “order_detail”: “測試訂單備註”, “acquirer_type”: “esun”, “limit_product_id”: “esun.normal|esun.m3”, “send_time”: “2017-07-18 01:07:23” } Response 成功： { “status”: “OK”, “cust_order_no”: “20170718010723”, “url”: “https://goo.gl/K616G6” 29
} 失敗： { “status”: “ERROR”, “msg”: “新增刷卡訂單失敗” } ※異常訊息列表 項目 項目名稱 1
cmd 資料不正確.
2
契約客戶資料不正確.
3
契約客戶資料不存在.
4
使用者密碼不可超過 40 碼.
5
使用者登入失敗，帳號或密碼錯誤.
6
使用者登入失敗, 使用者已經停用.
7
取得金流服務資訊失敗
8
缺少必要的欄位.
9
order_detail 格式不正確，內容不可包含 Html Tag.
10
order_amount 格式不正確.
11
send_time 格式不正確.
12
send_time 異常.
13
契客資料不存在.
14
收單銀行設定錯誤.
15
您尚未申請玉山銀行為收單銀行.
16
您尚未申請中國信託為收單銀行.
17
契客未設定回應網址.
18
cust_order_no 必須為三位數以上的英數字或減號.
19
訂單已經逾期.
20
資料錯誤，您已經上傳過此一「契約訂單號碼」：XXXXX，不可再次上傳.
21
金流服務已停用
22
資料錯誤，「代繳金額」必須小於 XXXXX
23
資料錯誤，「代繳金額」必須大於 XXXXX
24
尚未設定銀行手續費率
25
特店代號和押碼 KEY 不能為空白
26
尚未啟用電子發票功能.
27
是否印製紙本發票未輸入或格式錯誤. 30
28
是否捐贈發票未輸入或格式錯誤.
29
捐贈發票、統編(公司戶)發票、印製紙本發票或共通載具只能選一種
30
請輸入捐贈、紙本列印發票或使用發票載具
31
請輸入載具類型.
32
資料錯誤，「載具條碼」必填.
33
載具條碼格式有誤.
34
資料錯誤，「載具條碼」必填.
35
載具條碼格式有誤.
36
資料錯誤，「商品名稱」必填.
37
資料錯誤，「繳款人姓名」必填.
38
資料錯誤，「繳款人郵遞區號」格式錯誤.
39
資料錯誤，「繳款人郵遞區號」必填.
40
資料錯誤，「繳款人地址」必填.
41
資料錯誤，無效的繳款人手機號碼.
42
資料錯誤，「繳款人手機號碼」必填.
43
資料錯誤，無效的繳款人 Email 信箱.
44
資料錯誤，「繳款人電子郵件」必填.
45
資料錯誤，買方統一編號錯誤.
46
資料錯誤，「發票抬頭」必填.
3.
銀行授權完成回報
於銀行授權完成時，重新導向客戶端瀏覽器網址：契約客戶指定的「授權完成時重新 導向契客網址」 ※回覆資料 欄位
型態
說明
ret
string
回應狀態 授權成功時為 OK
cust_order_no
string
契客訂單號碼
order_amount
string
訂單/交易金額
send_time
string
原先的訂單傳送時間 (為契客新增訂單內輸入之傳送時間)， 格式為 yyyy-MM-dd HH:mm:ss， 例如：2017-09-14 10:31:25
acquire_time
string
收單交易時間（取得授權時間）， 格式為 yyyy-MM-dd HH:mm:ss， 31
例如：2017-09-14 10:36:38 auth_code
string
授權碼
card_no
string
信用卡號碼後四碼
notify_time
string
通報時間，為本次傳送訊息的時間 （每一次傳輸均會更新）， 格式為 yyyy-MM-dd HH:mm:ss， 例如：2017-09-14 10:37:08
chk
string
檢核碼，檢核碼產生方式為 MD5(hash_base+'$'+order_amount+'$'+ send_time+'$'+ret+'$'+acquire_time +'$'+auth_code+'$'+card_no+'$'+ notify_time+'$'+cust_order_no) 先將各欄位以'$'串接，再以 MD5 演 算法取得。 hash_base：作為產生 chk 檢核碼的基 礎，於申請使用本服務時由系統配發
※Sample 授權完成時重新導向契客網址：http://10.10.10.100/cocs/authSuccess.php Response http://10.10.10.100/cocs/authSuccess.php?ret=OK&cust_order_no=C201709141001&ord er_amount=2&send_time=2017-09-14 10:31:25&acquire_time=2017-09-14 10:36:38&auth_code=951294&card_no=1849¬ify_time=2017-09-14 10:37:08&chk=9ea4928734f4099b387c75a344fe3e50
4.
銀行授權失敗回報
於銀行授權失敗時，重新導向客戶端瀏覽器網址：契約客戶指定的「授權失敗時重新 導向契客網址」 ※回覆資料 欄位
型態
說明
ret
string
回應狀態 授權成功時為 FAIL
cust_order_no
string
契客訂單號碼 32
order_amount
string
訂單/交易金額
send_time
string
原先的訂單傳送時間 (為契客新增訂單內輸入之傳送時間)， 格式為 yyyy-MM-dd HH:mm:ss， 例如：2017-09-14 10:31:25
notify_time
string
通報時間，為本次傳送訊息的時間 （每一次傳輸均會更新）， 格式為 yyyy-MM-dd HH:mm:ss， 例如：2017-09-14 10:37:08
chk
string
檢核碼，檢核碼產生方式為 MD5(hash_base+'$'+order_amount+'$'+ send_time+'$'+ret+'$'+ notify_time+'$'+cust_order_no) 先將各欄位以'$'串接，再以 MD5 演 算法取得。 hash_base：作為產生 chk 檢核碼的基 礎，於申請使用本服務時由系統配發
※Sample 授權失敗時重新導向契客網址：http://10.10.10.100/cocs/authFail.php Response http://10.10.10.100/cocs/authFail.php?ret=FAIL&cust_order_no=C201709141001&order_ amount=2&send_time=2017-09-14 10:31:25¬ify_time=2017-09-14 10:37:08&chk= 3aa9a501ae2c8e58f8dfdcb07af4b7c3
5.
契客新增刷卡訂單-加值服務
契約客戶透過 API 新增訂單且依簽約時所指定的加值服務。系統會依照設定的內容， 主動透過簡訊或電子郵件發送給繳款人線上刷卡繳款連結短網址通知。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： 33
Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CocsOrderAppend2)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
契客訂單號碼（契約客戶自定 之識別用號碼，該號碼在同一 契約客戶代號下必須為唯 一）。可不輸入，當此欄位為 空時，系統將會自動產生 YYYYMMDD######的號碼，前 八碼為西元年月日，後六碼為 該日期內之訂單流水號，從 1 開始累增，例如： 20170718000003
Y
訂單/交易金額
150
Y
訂單明細
string
50
Y
繳款人姓名
string
20
order_amount
number
order_detail
string
payer_name payer_mobile
繳款人手機號碼（若加值服務 有啟用，此欄位為必填） 繳款人電子郵件（若加值服務 有啟用，此欄位為必填）
payer_email
string
50
acquirer_type
string
20
Y
指定收單銀行 esun: 玉山銀行 chinatrust: 中國信託銀行
limit_product_id
string
50
Y
限定產品別（可不輸入，當此 欄位為空時，意為允許所有產 品別。各產品別以”|”分隔） (參考附件 2) 例如：esun.normal|esun.m3
send_time
string
10
傳送時間，必須為傳送時之最 新時間，格式為 yyyy-MM-dd HH:mm:ss，例如：2017-07-18
Y
07:17:25 success_url
string
250
訂單授權成功指定回傳 URL
Y 34
若此參數有傳入 URL，授權成 功回覆 URL 會帶入此網址，若 沒有輸入會依客樂得金流服務 設定中授權成功所指定網址回 傳 APN 指定傳送網址(選填，若沒 有填寫則取得金流服務中的 APN 網址)
apn_url
string
250
b2c
string
1
電子 發票
此訂單是否開立電子發票 0:不開立 1:開立
product_name
string
60
電子 發票
商品名稱(必填)
print_invoice
string
1
電子
是否列印紙本發票(必填)
發票
0:不列印 1:列印
vehicle_type
string
1
電子 發票
載具類別 1:會員載具 2:手機條碼 3:自然人憑證
vehicle_barcode
string
20
電子
載具條碼
發票 donate_invoice
string
1
電子 發票
是否捐贈發票(必填) 0:不捐贈 1:捐贈
love_code
string
20
電子 發票
愛心碼(選捐贈。愛心碼如不輸 入，預設為創世基金會 919)
payer_name
string
50
電子 發票
繳款人姓名(必填)
payer_postcode
string
10
電子 發票
繳款人郵遞區號(必填)
payer_address
string
240
電子 發票
繳款人地址(必填)
payer_mobile
string
30
電子 發票
繳款人手機(必填) 發票中獎後簡訊通知
payer_email
string
240
電子 發票
繳款人電子郵件(必填) 開立電子發票及發票中獎
35
EMAIL 通知 buyer_bill_no
string
8
電子 發票
買方統一編號
buyer_invoice_title
string
161
電子 發票
發票抬頭
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
url
string
產生訂單對應的線上刷卡網址
※Sample Send { “cmd”: “CocsOrderAppend2”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010723”, “order_amount”: 50, “order_detail”: “測試訂單備註”, “payer_name”: “王大明”, “payer_mobile”: “0970325698”, “payer_email”: “[email protected]”, “acquirer_type”: “esun”, “limit_product_id”: “esun.normal|esun.m3”, “send_time”: “2017-07-18 01:07:23” } Response 成功： { “status”: “OK”, “cust_order_no”: “20170718010723”, “url”: “https://goo.gl/K616G6” } 36
失敗： { “status”: “ERROR”, “msg”: “新增刷卡訂單失敗” } ※異常訊息列表 項目 項目名稱 1
cmd 資料不正確.
2
契約客戶資料不正確.
3
契約客戶資料不存在.
4
使用者密碼不可超過 40 碼.
5
使用者登入失敗，帳號或密碼錯誤.
6
使用者登入失敗, 使用者已經停用.
7
取得金流服務資訊失敗
8
缺少必要的欄位.
9
order_detail 格式不正確，內容不可包含 Html Tag.
10
未授權使用服務.
11
必需輸入繳款人手機，或是您輸入的資料不正確.
12
必需輸入繳款人 E-mail，或是您輸入的資料不正確.
13
order_amount 格式不正確.
14
send_time 格式不正確.
15
send_time 異常.
16
契客資料不存在.
17
收單銀行設定錯誤.
18
您尚未申請玉山銀行為收單銀行.
19
您尚未申請中國信託為收單銀行.
20
契客未設定回應網址.
21
cust_order_no 必須為三位數以上的英數字或減號.
22
訂單已經逾期.
23
資料錯誤，您已經上傳過此一「契約訂單號碼」：XXXXX，不可再次上傳.
24
金流服務已停用
25
資料錯誤，「代繳金額」必須小於 XXXXX
26
資料錯誤，「代繳金額」必須大於 XXXXX
27
尚未設定銀行手續費率
28
特店代號和押碼 KEY 不能為空白 37
6.
29
尚未啟用電子發票功能.
30
是否印製紙本發票未輸入或格式錯誤.
31
是否捐贈發票未輸入或格式錯誤.
32
捐贈發票、統編(公司戶)發票、印製紙本發票或共通載具只能選一種.
33
請輸入捐贈、紙本列印發票或使用發票載具.
34
請輸入載具類型.
35
資料錯誤，「載具條碼」必填.
36
載具條碼格式有誤.
37
資料錯誤，「載具條碼」必填.
38
載具條碼格式有誤.
39
資料錯誤，「商品名稱」必填.
40
資料錯誤，「繳款人姓名」必填.
41
資料錯誤，「繳款人郵遞區號」超過長度限制 10 碼.
42
資料錯誤，「繳款人郵遞區號」必填.
43
資料錯誤，「繳款人地址」必填.
44
資料錯誤，無效的繳款人手機號碼.
45
資料錯誤，「繳款人手機號碼」必填.
46
資料錯誤，無效的繳款人 Email 信箱.
47
資料錯誤，「繳款人電子郵件」必填.
48
資料錯誤，買方統一編號錯誤.
49
資料錯誤，「發票抬頭」必填.
訂單查詢
契約客戶透過 API 查詢刷卡資訊。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CocsOrderQuery) 38
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
契客訂單號碼
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
order_amount
number
代繳金額
expire_date
string
繳費到期日(yyyy-MM-dd HH:mm:ss)
acquirer_type
string
授權銀行(玉山銀行/中國信託銀行)
period_type
string
授權產品(參考附件 2)
request_date
string
預計請求請款日期(yyyy-MM-dd )
request _amount
number
（預計）請款金額
grant_date
string
撥款日期(yyyy-MM-dd)
grant_amount
number
（預計）撥款金額
process_code
number
訂單程序狀態代碼 (參考附件 1)
process_code_update_time
string
訂單程序狀態變更日期 (yyyy-MM-dd HH:mm:ss)
create_time
訂單建立時間
string
(yyyy-MM-dd HH:mm:ss ) card_no
string
信用卡號後 4 碼
print_invoice
string
是否列印紙本發票 0:不列印 1:列印
vehicle_type
string
載具類別 1:會員載具 2:手機條碼 3:自然人憑證
vehicle_barcode
string
載具條碼
donate_invoice
string
是否捐贈發票 0:不捐贈 1:捐贈
love_code
string
愛心碼 39
invoice_no
string
發票號碼
invoice_date
string
發票日期
random_number
string
隨機碼
※Sample Send { “cmd”: “CocsOrderQuery”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010712” } Response 成功： { “status”: “OK” “cust_order_no”: “20170825103044”, “order_amount”: 50, “expire_date”: “2017-08-25 13:31:00”, “acquirer_type ”: “玉山銀行”, “period_type”: “一次付清”, “request_date”: “2017-08-27”, “request_amount”: 50, “grant_date”:”2017-08-29”, “grant_amount”: 0, “process_code”: 15, “process_code_update_time”: “2017-08-25 10:31:55”, “create_time”: “2017-08-25 10:30:44”, “card_no”: “1243”, “print_invoice”: “0”, “vehicle_type”: “”, “vehicle_barcode”: “”, “donate_invoice”: “1”, “love_code”: “919”, “invoice_no”: “”, “invoice_date”: “”, “random_number”: “” } 40
失敗： { “status”: “ERROR”, “msg”: “取得查詢刷卡資訊失敗” }
※異常訊息列表 項目 項目名稱
7.
1
cmd 資料不正確.
2
契約客戶資料不正確.
3
契約客戶資料不存在.
4
使用者密碼不可超過 40 碼.
5
使用者登入失敗，帳號或密碼錯誤.
6
使用者登入失敗, 使用者已經停用.
7
必須要有參數+cust_order_no
8
找不到此筆刷卡資訊
9
取得查詢刷卡資訊失敗
訂單取消授權
契約客戶透過 API 取消訂單授權。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CocsOrderCancel)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
原契客訂單編號 41
order_amount
number
acquirer_type
string
send_time
string
Y
訂單/交易金額
20
Y
指定收單銀行 esun: 玉山銀行 chinatrust: 中國信託銀行
10
Y
傳送時間，必須為傳送時之最 新時間，格式為 yyyy-MM-dd HH:mm:ss，例如：2017-07-18 07:17:25
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
契客訂單號碼
string
※Sample Send { “cmd”: “CocsOrderCancel”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010723”, “order_amount”: 50, “acquirer_type”: “esun”, “send_time”: “2017-07-18 03:07:23” } Response 成功： { “status”: “OK”, “cust_order_no”: “20170718010723” } 失敗： { “status”: “ERROR”, “msg”: “訂單取消授權失敗” 42
} ※異常訊息列表 項目 項目名稱
8.
1
cmd 資料不正確.
2
缺少必要的欄位.
3
order_amount 格式不正確.
4
send_time 格式不正確.
5
send_time 異常.
6
契客資料不存在.
7
收單銀行設定錯誤.
8
您尚未申請玉山銀行為收單銀行.
9
您尚未申請中國信託為收單銀行.
10
目前的訂單程序不允許取消授權.
11
訂單金額不正確.
12
取消授權作業失敗，無此訂單.
13
cust_order_no 不存在.
14
取消授權作業失敗，通訊異常.
15
取消授權作業失敗. 銀行端回覆: XXXXX
訂單取消交易(退貨、退款)
契約客戶透過 API 取消訂單交易。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CocsOrderRefund)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼 43
Y
原契客訂單編號
number
Y
訂單/交易金額
refund_amount
number
Y
取消交易（退貨、退款）金額 （必須輸入，小於或等於訂單/ 交易金額）
acquirer_type
string
20
Y
指定收單銀行 esun: 玉山銀行 chinatrust: 中國信託銀行
send_time
string
10
Y
傳送時間，必須為傳送時之最 新時間，格式為 yyyy-MM-dd HH:mm:ss，例如：2017-07-18
cust_order_no
string
order_amount
30
07:17:25 ※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
refund_amount
string
取消交易（退貨、退款）金額
※Sample Send { “cmd”: “CocsOrderRefund”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010723”, “order_amount”: 50, “refund_amount”: 50, “acquirer_type”: “esun”, “send_time”: “2017-07-18 03:07:23” } Response 成功： { 44
“status”: “OK”, “cust_order_no”: “20170718010723”, “refund_amount”: 50 } 失敗： { “status”: “ERROR”, “msg”: “訂單取消交易失敗” } ※異常訊息列表 項目 項目名稱 1
cmd 資料不正確.
2
缺少必要的欄位.
3
order_amount 格式不正確.
4
refund_amount 格式不正確.
5
send_time 格式不正確.
6
send_time 異常.
7
契客資料不存在.
8
收單銀行設定錯誤.
9
您尚未申請玉山銀行為收單銀行.
10
您尚未申請中國信託為收單銀行.
11
您尚未申請中國銀聯為收單銀行.
12
缺少中國銀聯收單行資訊.
13
缺少特店代號或押碼 Key.
14
目前的訂單程序不允許取消交易.
15
訂單金額不正確.
16
取消交易金額不可大於訂單金額.
17
取消交易金額必需大於 0 元.
18
指定取消交易金額不可大於請款金額.
19
累積取消交易金額不可大於訂單金額.
20
累積取消交易金額不可大於指定請款金額.
21
不允許部份取消交易.
22
取消交易作業失敗，無此訂單，或不是使用玉山或中國信託銀行付款.
23
cust_order_no 不存在.
24
取消交易作業失敗，無此訂單，或不是使用玉山付款.
25
取消交易作業失敗，無此訂單，或不是使用中信付款. 45
9.
指定請款金額
契約客戶透過 API 指定請款金額。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CocsCashRequest)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
原契客訂單編號
order_amount
number
Y
訂單/交易金額
cr_amount
number
Y
請款金額
send_time
string
Y
傳送時間，必須為傳送時之最 新時間，格式為 yyyy-MM-dd HH:mm:ss，例如：2017-07-18
10
07:17:25 ※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
cr_amount
number
請款金額
※Sample Send 46
{ “cmd”: “CocsCashRequest”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010723”, “order_amount”: 50, “cr_amount”: 50, “send_time”: “2017-07-18 03:07:23” } Response 成功： { “status”: “OK”, “cust_order_no”: “20170718010723”, “cr_amount”: 50 } 失敗： { “status”: “ERROR”, “msg”: “指定請款金額失敗” }
※異常訊息列表 項目 項目名稱 1
cmd 資料不正確.
2
缺少必要的欄位.
3
order_amount 格式不正確.
4
cr_amount 格式不正確.
5
send_time 格式不正確.
6
send_time 異常.
7
契客資料不存在.
8
指定的訂單不允許指定請款金額.
9
目前的訂單程序不允許指定請款金額.
10
訂單金額不正確.
11
指定請款金額不可大於訂單金額.
12
這個帳號未開通指定請款金額服務. 47
13
指定請款金額作業失敗，無此訂單，或不是使用玉山或中國信託銀行付款.
14
cust_order_no 不存在.
10. 契客新增刷卡訂單-玉山銀聯卡 契約客戶透過 API 新增玉山銀聯卡訂單。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CocsUnionpayAppend)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
契客訂單號碼（契約客戶自定 之識別用號碼，該號碼在同一 契約客戶代號下必須為唯 一）。可不輸入，當此欄位為 空時，系統將會自動產生 YYYYMMDD######的號碼，前 八碼為西元年月日，後六碼為 該日期內之訂單流水號，從 1 開始累增，例如： 20170718000003
order_amount
number
order_detail
string
send_time
string
Y
訂單/交易金額
150
Y
訂單明細
10
Y
傳送時間，必須為傳送時之最 新時間，格式為 yyyy-MM-dd HH:mm:ss，例如：2017-07-18 07:17:25
success_url
string
250
訂單授權成功指定回傳 URL
Y 48
若此參數有傳入 URL，授權成 功回覆 URL 會帶入此網址若， 沒有輸入會依客樂得金流服務 設定中授權成功所指定網址回 傳 APN 指定傳送網址(選填，若沒 有填寫則取得金流服務中的 APN 網址)
apn_url
string
250
b2c
string
1
電子 發票
此訂單是否開立電子發票 0:不開立 1:開立
product_name
string
60
電子 發票
商品名稱(必填)
print_invoice
string
1
電子
是否列印紙本發票(必填)
發票
0:不列印 1:列印
vehicle_type
string
1
電子 發票
載具類別(必填) 1:會員載具 2:手機條碼 3:自然人憑證
vehicle_barcode
string
20
電子
載具條碼
發票 donate_invoice
string
1
電子 發票
是否捐贈發票(必填) 0:不捐贈 1:捐贈
love_code
string
20
電子 發票
愛心碼(選捐贈。愛心碼如不輸 入，預設為創世基金會 919)
payer_name
string
50
電子 發票
繳款人姓名(必填)
payer_postcode
string
10
電子 發票
繳款人郵遞區號(必填)
payer_address
string
240
電子 發票
繳款人地址(必填)
payer_mobile
string
30
電子 發票
繳款人手機(必填) 發票中獎後簡訊通知
payer_email
string
240
電子 發票
繳款人電子郵件(必填) 開立電子發票及發票中獎
49
EMAIL 通知 buyer_bill_no
string
8
電子 發票
買方統一編號
buyer_invoice_title
string
161
電子 發票
發票抬頭
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
url
string
產生訂單對應的線上刷卡網址
※Sample Send { “cmd”: “CocsUnionpayAppend”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010723”, “order_amount”: 50, “order_detail”: “測試訂單備註”, “send_time”: “2017-07-18 01:07:23” } Response 成功： { “status”: “OK”, “cust_order_no”: “20170718010723”, “url”: “https://goo.gl/K616G6” } 失敗： { “status”: “ERROR”, “msg”: “新增刷卡訂單失敗” } 50
※異常訊息列表 項目 項目名稱 1
cmd 資料不正確.
2
契約客戶資料不正確.
3
契約客戶資料不存在.
4
使用者密碼不可超過 40 碼.
5
使用者登入失敗，帳號或密碼錯誤.
6
使用者登入失敗, 使用者已經停用.
7
取得金流服務資訊失敗
8
缺少必要的欄位.
9
order_detail 格式不正確，內容不可包含 Html Tag.
10
order_amount 格式不正確.
11
send_time 格式不正確.
12
send_time 異常.
13
契客資料不存在.
14
您尚未申請玉山銀行為收單銀行.
15
契客未設定回應網址.
16
cust_order_no 必須為三位數以上的英數字或減號.
17
訂單已經逾期.
18
資料錯誤，您已經上傳過此一「契約訂單號碼」：XXXXX，不可再次上傳.
19
金流服務已停用
20
資料錯誤，「代繳金額」必須小於 XXXXX
21
資料錯誤，「代繳金額」必須大於 XXXXX
22
尚未設定銀行手續費率
23
特店代號和押碼 KEY 不能為空白
24
尚未啟用電子發票功能.
25
是否印製紙本發票未輸入或格式錯誤.
26
是否捐贈發票未輸入或格式錯誤.
27
捐贈發票、統編(公司戶)發票、印製紙本發票或共通載具只能選一種.
28
請輸入捐贈、紙本列印發票或使用發票載具.
29
請輸入載具類型.
30
資料錯誤，「載具條碼」必填.
31
載具條碼格式有誤.
32
資料錯誤，「載具條碼」必填.
33
載具條碼格式有誤. 51
34
資料錯誤，「商品名稱」必填.
35
資料錯誤，「繳款人姓名」必填.
36
資料錯誤，「繳款人郵遞區號」超過長度限制 10 碼.
37
資料錯誤，「繳款人郵遞區號」必填.
38
資料錯誤，「繳款人地址」必填.
39
資料錯誤，無效的繳款人手機號碼.
40
資料錯誤，「繳款人手機號碼」必填.
41
資料錯誤，無效的繳款人 Email 信箱.
42
資料錯誤，「繳款人電子郵件」必填.
43
資料錯誤，買方統一編號錯誤.
44
資料錯誤，「發票抬頭」必填.
11. 訂單取消交易(退貨、退款) -玉山銀聯卡 契約客戶透過 API 取消玉山銀聯卡訂單交易。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 CocsUnionpayRefund)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
cust_order_no
string
30
Y
原契客訂單編號
order_amount
number
Y
訂單/交易金額
refund_amount
number
Y
取消交易（退貨、退款）金額 （必須輸入，小於或等於訂單/ 交易金額）
send_time
string
Y
傳送時間，必須為傳送時之最 新時間，格式為 yyyy-MM-dd HH:mm:ss，例如：2017-07-18
10
52
07:17:25 ※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
cust_order_no
string
契客訂單號碼
refund_amount
string
取消交易（退貨、退款）金額
※Sample Send { “cmd”: “CocsUnionpayRefund”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, “cust_order_no”: “20170718010723”, “order_amount”: 50, “refund_amount”: 50, “send_time”: “2017-07-18 03:07:23” } Response 成功： { “status”: “OK”, “cust_order_no”: “20170718010723”, “refund_amount”: 50 } 失敗： { “status”: “ERROR”, “msg”: “訂單取消交易失敗” } ※異常訊息列表 項目 項目名稱 1
cmd 資料不正確. 53
2
缺少必要的欄位.
3
order_amount 格式不正確.
4
refund_amount 格式不正確.
5
send_time 格式不正確.
6
send_time 異常.
7
契客資料不存在.
8
您尚未申請中國銀聯為收單銀行.
9
缺少中國銀聯收單行資訊.
10
缺少特店代號或押碼 Key.
11
目前的訂單程序不允許取消交易.
12
訂單金額不正確.
13
取消交易金額不可大於訂單金額.
14
取消交易金額必需大於 0 元.
15
指定取消交易金額不可大於請款金額.
16
累積取消交易金額不可大於訂單金額.
17
累積取消交易金額不可大於指定請款金額.
18
不允許部份取消交易.
19
取消交易作業失敗，無此訂單，或不是使用玉山或中國信託銀行付款.
20
cust_order_no 不存在.
21
取消交易作業失敗，無此訂單，或不是使用銀聯付款.
22
取消交易作業失敗，通訊異常.
23
取消交易作業初步檢核失敗. 銀行端回覆: XXXXX
12. APN 契約客戶於訂單狀態變更時，主動發送通報訊息到客戶端網址：契約客戶指定的 「APN-主動發送訊息網址」。 ※傳輸資料格式 欄位
說明
Description
1.以 json 格式封裝訂單資料做為傳輸的訊息。 2.ContentType = application/json。 3.使用 checksum 確保資料的安全性。
URL
在多元支付平台後台管理系統，登錄的 APN-主動發送訊息網址
Method
POST
Retrun
APN 傳送端將會傳送通知訊息總共會傳送 3 次。 54
※傳送資料： 欄位
型態
長 度
加 密
說明
api_id
string
32
您的契客代號，於申請本服務配發 的代號。
trans_id
string
32
每筆線上刷卡訂單唯一的交易識別 碼。
order_no
string
20
契客訂單編號
amount
number
status
string
訂單/交易金額交易金額 訂單狀態碼
1
B=授權完成 O=請款作業中 (請款作業中，無法進行取消授權) E=請款完成 F=授權失敗 D=訂單逾期 P=請款失敗 M=取消交易完成 N=取消交易失敗 Q=取消授權完成 R=取消授權失敗 I=開立發票通知 J=開立發票折讓單號通知 payment_code
number
客樂得刷卡代繳服務(固定值為 1)
payment_detail
Object
{ "auth_code":"刷卡授權碼(6 位)", "auth_card_no":"信用卡號碼後四 碼" } 刷卡完成的刷卡資訊範例 { "auth_code":"123456", "auth_card_no":"1234" } 刷卡失敗的刷卡資訊範例 { 55
"auth_code":null, "auth_card_no":null } 保留使用
memo
Object
expire_time
string
25
繳款逾期時間， 格式:YYYY-MM-DDTHH:NN:SS+08:00 (年-月-日 T 時:分:秒+08:00)
create_time
string
25
繳款單建立時間， 格式:YYYY-MM-DDTHH:NN:SS+08:00 (年-月-日 T 時:分:秒+08:00)
modify_time
string
25
狀態更新時間， 格式:YYYY-MM-DDTHH:NN:SS+08:00 (年-月-日 T 時:分:秒+08:00)
nonce
string
隨機數，不會重覆的時間+亂數組合
10
採用時分秒+亂數產生:HHNNSSRRRR HHNNSS:主機時間的時分秒(6 位數) RRRR:四位數隨機亂數 checksum
string
檢核驗證碼比對 checksum 的內容是 否與下列運算後的結果相同，相同 的 MD5 結果表示這個訊息的內容與 原始資料相符。
32
checksum = MD5 ( api_id +":" + trans_id +":" + amount+":" + status +":" + nonce ) print_invoice
string
1
是否列印紙本發票 0:不列印 1:列印
vehicle_type
string
1
載具類別 1:會員載具 2:手機條碼 3:自然人憑證
vehicle_barcode
string
20
載具條碼
donate_invoice
string
1
是否捐贈發票 0:不捐贈 1:捐贈
love_code
string
20
愛心碼
invoice_no
string
10
發票號碼 56
invoice_date
string
10
發票日期
random_number
string
4
隨機碼
16
折讓單號
invoice_discount_no string ※Sample
Response 當契客使用刷卡代繳服務後，來自 APN 的回傳訊息 { "api_id":"CC0000000001", "trans_id":"550e8400e29b41d4a716446655440000", "order_no":"PO5488277", "amount":1250, "status":"B", "payment_code":1, "payment_detail":{"auth_code":"123456","auth_card_no":"0000"}, "memo":"", "expire_time":"2013-09-28T08:15:00+08:00", "create_time":"2013-09-28T08:00:00+08:00", "modify_time":"2013-09-28T08:30:00+08:00", "nonce":"1234569999", "checksum":"d09d5532767453ad4c6ba9b649034187", "print_invoice":"0", "vehicle_type":"2", "vehicle_barcode":"/1234567", "donate_invoice":"", "love_code":"", "invoice_no":"", "invoice_date":"", "random_number":"", "invoice_discount_no":"" } 這個例子中，checksum 的產生方式是 MD5(CC0000000001: 550e8400e29b41d4a716446655440000:1250:B:1234569999)
57
三、
1.
主檔管理
變更金流服務簡訊簡稱
契約客戶透過 API 調整簡訊簡稱資料。
POST /api/Collect ※傳輸網址：https://4128888card.com.tw/api/Collect ※傳送資料： Content-Type: application/json Authorization: Bearer [token…] 欄位
型態
長度
必填
說明
cmd
string
20
Y
交易代碼(固定帶入 SmsShortNameUpdate)
cust_id
string
20
Y
契客代號
cust_password
string
20
Y
契客 API 密碼
service_type
string
1
Y
金流服務類型 0：CVS 代收代付 1：COCS 線上刷卡
sms_short_name
string
20
調整後簡訊簡稱
Y
※回覆資料 欄位
型態
說明
status
string
回應狀態 僅有 OK 與 ERROR 兩種訊息狀態， OK 為處理成功，ERROR 為處理時發 生異常狀況
msg
string
回覆訊息
※Sample Send { “cmd”: “SmsShortNameUpdate”, “cust_id”: “12656354001”, “cust_password”: “1q2w”, 58
“service_type”: “0”, “sms_short_name”: “簡訊簡稱 XXXX” } Response 成功： { “status”: “OK” } 失敗： { “status”: “ERROR”, “msg”: “變更金流服務簡訊簡稱失敗” } ※異常訊息列表 項目 項目名稱 1
cmd 資料不正確.
2
契約客戶資料不正確.
3
契約客戶資料不存在.
4
使用者密碼不可超過 40 碼.
5
使用者登入失敗，帳號或密碼錯誤.
6
使用者登入失敗, 使用者已經停用.
7
資料錯誤，「金流服務類型指定錯誤」.
8
資料錯誤，「尚未申請 CVS 代收代付金流服務類型」.
9
資料錯誤，「尚未申請 COCS 線上刷卡金流服務類型」.
10
資料錯誤，「簡訊簡稱不能為空白」.
11
簡訊簡稱不可超過 20 碼.
12
取得金流服務失敗.
13
變更金流服務簡訊簡稱失敗
四、
1.
附件
訂單程序狀態一覽表
數值 說明 0
契約客戶提出代繳需求，等待契約客戶確認 59
1
已確認繳款單明細，等待列印(製作)繳款單
3
等待繳款人繳納
4
繳款人已繳納
5
契客設定註銷
6
繳款單逾期
7
已預約撥款給契客
8
已完成撥款給契客
13
刷卡確認頁
14
繳款人確認
15
授權完成
16
授權失敗
17
取消授權完成
18
取消授權失敗
20
請求請款
21
請款作業中
22
請款完成
23
請款失敗
24
請求取消交易
25
取消交易(退貨)申請中
26
取消交易(退貨)作業中
27
取消交易(退貨)完成
28
取消交易(退貨)失敗
29
取消交易(退貨)申請失敗
2.
分期參數
數值
說明
esun.normal
玉山銀行一次性付款
esun.m3
玉山銀行 3 期
esun.m6
玉山銀行 6 期
esun.m12
玉山銀行 12 期
chinatrust.normal 中國信託銀行一次性付款 中國信託銀行 3 期 chinatrust.m3 chinatrust.m6
中國信託銀行 6 期
chinatrust.m12
中國信託銀行 12 期
60