NAV
docs

Server APIs

Overview

我們的後台使用的是 REST 架構,所以每個請求皆是使用 HTTP POST 來進行傳輸

Pay by Prime API

當您要進行3D驗證交易,請在Request欄位中的three_domain_secure帶入true,且在result_url的frontend_redirect_url與backend_notify_url分別帶入對應的值。

名稱(* = 必填) 類別(長度) 內容
prime* String(67) 用卡號所換得的字串,由 getPrime 成功時回傳
prime 的時效為 90秒
若您有開啟 Apple Pay 延後授權,請自行保管 Prime(預設 Prime 有效期限為 30 天)
呼叫 Pay By Prime ,您可以在 sandbox 環境中使用此測試用prime
付款方式測試 prime
Direct Paytest_3a2fb2b7e892b914a03c95dd4dd5dc7970c908df67a49527c0a648b2bc9
Apple Pay 請將 amount 設為 12
ap_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Google Pay(代碼化交易)gp_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Google Pay(原始卡號交易)gp_test_kjo6i5uthfuehfjgit867584urjfhtyr74ytuhjyu7685jtufyejgitu
LINE Payln_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Samsung Pay sp_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
JKOPAYjk_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Easy Walletew_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
merchant_group_id String(50) 於 Portal 設置的商家管理設置,交易時會依據 portal 的支付配置進行交易
不可與 merchant_id 同時使用
amount* int 交易金額。目前支援台幣、港幣、馬幣、美金,台幣以外金額需乘以 100後帶入,各幣別交易金額上限,請參考 reference
merchandise_details JSONObject 交易商品明細
目前只支援 JKOPAY 悠遊付
名稱類別內容
no_rebate_amountInt不適用回饋之金額(例如:煙)
currency String(3) 貨幣種類,銀行支援幣別請參考 reference,預設為 TWD
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
bank_transaction_id String(40) 銀行端的訂單編號
強烈建議商戶可在此自訂,但不能與之前的重複;若您沒有自訂則會自動幫您產生一組。
但若您沒自訂,當發生421 Gateway 操作逾時(發生機率低),則無法反查該筆交易
(格式規格請參考備註 reference)
details* String(100) 交易品項內容,為符合 PCI 要求至少必須要有品項名稱
我們的詐欺檢測器將會以此作為詐欺判定的基準,所以建議您填寫的資訊能越詳細越好
銀行儲存格式規格請參考 reference
若您啟用TSP服務,且收單銀行為台新銀行,請務必填入交易品項內容; 若沒帶入,TapPay將預設該值為交易序號以避免交易失敗
若您的收單銀行為藍新金流或支付方式為LINE Pay,此欄位須填入值,否則會導致交易失敗
cardholder* JSONObject 持卡人或購買人資訊,裡面應包含以下值。
以下資料將為「詐欺檢測器」,資料越詳細,可獲得越完整的保護
若此筆交易需身份驗證,請詳讀備註中各銀行需驗證的必填欄位,並在對應的參數欄位中帶入正確的值
若無此資料,則該對應的 Key 值,可以帶空字串,(如:zip_code: “”)
名稱(*為必填)類別(長度)內容
phone_number*String(40)手機號碼,可為 09 開頭的電話或是包含加號之 E.164 格式(“+886923456789”)
name*String(40)姓名
email*String(40)電子信箱
zip_codeString(40)郵遞區號
addressString(90)地址
national_idString(40)身份證字號,首位英文字需大寫
member_idString(64)會員編號
cardholder_verify JSONObject 身份驗證欄位,請注意:若此筆交易需身份驗證,請詳讀備註中各銀行需驗證的必填欄位,若該欄位為 “true” 就會將 cardholder 中對應的值送至收單銀行做身份驗證
支援: Direct Pay
支援銀行: 財團法人聯合信用卡處理中心, 台新銀行(只支援自行卡)
名稱類型(長度)內容
phone_numberBoolean是否驗證電話號碼
national_idBoolean是否驗證身分證字號
instalment int(2) 分期付款期數,預設為 0
目前支援: 台新銀行, 財團法人聯合信用卡處理中心, 藍新金流, 國泰世華銀行, 玉山銀行, 中國信託銀行, 環匯亞太
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
delay_capture_in_days int 定義交易授權後銀行要過多久才會請款,單位為天
此參數非必要,預設值為0(當天請款)
若您想要自行手動請款,可帶入 -1 表示暫時不請款
* 收單銀行皆設有請款期限,請向您的收單銀行確認。若您採取手動請款模式,請留意如果該筆交易的請款日超過銀行請款期限,可能會導致請款失敗。
three_domain_secure Boolean 是否開啟 3D 驗證,預設為 false
目前支援: 台新銀行、中國信託銀行、財團法人聯合信用卡處理中心、玉山銀行、永豐(New)、藍新金流、富邦、RAZER PAY、彰化銀行、國泰世華銀行
3DS2.0 驗證目前只支援National Credit Card Center of R.O.C AE 卡
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
result_url JSONObject 使用 LINE Pay, JKOPAY, 悠遊付 或 three_domain_secure 為 true 時必填
名稱類別內容
frontend_redirect_urlString使用 LINE Pay、街口支付、悠遊付或者 3D 驗證交易時,當消費者在 LINE Pay、街口支付、悠遊付或 3D 驗證完成交易程序後,導轉回到商戶網頁前端的交易結果頁面 URL。必須以 https 開頭。
backend_notify_urlString商戶 Server 接收交易結果的 URL。必須以 https 開頭。
remember boolean 是否記憶卡號
不支援: Apple Pay, Google Pay, Samsung Pay, JKOPAY, 悠遊付
LINE Pay 交易 remember: true 時,只支援使用 POINT 與信用卡
redeem boolean 是否為紅利折抵。
目前支援: 財團法人聯合信用卡處理中心
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
additional_data JSONString(3000) 資料會加密保存,並在其他客製化需求時才解密做使用
event_code String(50) 與銀行或錢包合作之活動中,雙方協議的指定活動代碼。支援 : 悠遊付
product_image_url String(500) 交易付款頁面上所顯示的商品或商家圖片。此欄位等同於line_pay_product_image_url, 若您於呼叫時同時帶入 product_image_url 與line_pay_product_image_url,TapPay 將以product_image_url 欄位的內容為主。格式規格請參考備註 reference
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/payment/pay-by-prime
// 正式環境 URL: https://prod.tappaysdk.com/tpc/payment/pay-by-prime
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "prime": String,
  "partner_key": String,
  "merchant_id": "merchantA",
  "details":"TapPay Test",
  "amount": 100,
  "cardholder": {
      "phone_number": "+886923456789",
      "name": "王小明",
      "email": "LittleMing@Wang.com",
      "zip_code": "100",
      "address": "台北市天龍區芝麻街1號1樓",
      "national_id": "A123456789"
  },
  "remember": true
}

Response

名稱 類別(長度) 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
rec_trade_id String(20) 由 TapPay 伺服器產生的交易字串
將於退款時用到,請妥善保管
bank_transaction_id String(40) 銀行端的訂單編號
強烈建議商戶可在此自訂,但不能與之前的重複;若您沒有自訂則會自動幫您產生一組。
但若您沒自訂,當發生421 Gateway 操作逾時(發生機率低),則無法反查該筆交易
格式規格請參考 reference
auth_code String(6) 銀行授權碼,不支援:LINE Pay, JKOPAY, 悠遊付
card_secret JSONObject 卡片保管資訊。不支援:Apple Pay, Google Pay, Samsung Pay, JKOPAY, 悠遊付
如果呼叫時 remember = false 則不會回傳此物件

透過 LINE Pay 獲得的 card key 與 card token,若在 180 天內無成功交易,將會過期導致交易失敗

裡面包含以下值:
名稱類別(長度)內容
card_tokenString(67)卡片識別字串,以後需用此參數在 Pay by Card Token 直接交易
card_keyString(64)卡片安全金鑰,以後需用此參數在 Pay by Card Token 直接交易
amount int 交易金額,台幣以外金額需乘以 100,如港幣(HKD) 1元代表 100
currency String(3) 貨幣種類,銀行支援幣別請參考reference
不支援:LINE Pay, JKOPAY, 悠遊付
card_info JSONObject 卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付
名稱類別(長度)內容
bin_codeString(6)卡片前六碼
last_fourString(4)卡片後四碼
issuerString發卡銀行
issuer_zh_twString發卡銀行中文名稱
bank_idString發卡銀行代碼
fundingint卡片類別
-1 = Unknown
0 = 信用卡 (Credit Card)
1 = 簽帳卡 (Debit Card)
2 = 預付卡 (Prepaid Card)
typeint卡片種類
-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
4 = Union Pay
5 = AMEX
levelString卡片等級
countryString發卡行國家
country_codeString發卡行國家碼
expiry_dateString卡片到期時間,格式 YYYYMM,( remember = true 時回傳)
(Apple Pay / Google Pay / LINE Pay / Samsung Pay 不會回傳此欄位)
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
acquirer String 收單銀行 / 金流處理器
transaction_time_millis long 交易時間
bank_transaction_time JSONObject 銀行處理時間
bank_result_code String 銀行錯誤代碼
bank_result_msg String 銀行錯誤訊息
payment_url String 付款頁面網址,將此網址回傳至前端跳轉
不支援:Apple Pay, Google Pay, Samsung Pay
instalment_info JSONObject 非 3D 驗證交易,且使用分期付款時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
名稱類別內容
number_of_instalmentsint分期期數
first_paymentint第一期金額
each_paymentint每一期金額
extra_infoJSONObject各間銀行分期額外參數不同,請參考 extra_info
redeem_info JSONObject 非 3D 驗證交易,且使用紅利折抵時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
名稱類別內容
used_pointString紅利折抵點數
balanceString紅利餘額
offset_amountString紅利折抵金額
due_amountString折抵後自付金額
extra_infoJSONObject各間銀行紅利額外參數不同,請參考 extra_info
card_identifier String 不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
信用卡識別碼。每張信用卡只會對到一組識別碼。
merchant_reference_info JSON 若商戶在 TapPay 後台使用 Co-brand card management 功能,且交易卡號符合設定時,將會回傳此參數,不支援 JKOPAY

商戶於TapPay後台設定的affiliate code management須限制於20字元內且為半形的英數字
名稱類別內容
affiliate_codesArray商戶在 TapPay 後台的 Co-brand card management 功能專區設定的Affiliated codes
event_code String(50) 與銀行或錢包合作之活動中,雙方協議的指定活動代碼。支援 : 悠遊付

Pay by Card Token API

當您要進行3D驗證交易,請在Request欄位中的three_domain_secure帶入true,且在result_url的frontend_redirect_url與backend_notify_url分別帶入對應的值。

名稱(* = 必填) 類別(長度) 內容
card_key* String(64) 卡片安全金鑰
Pay by Prime 取得
card_token* String(67) 卡片識別字串
Pay by Prime 取得
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
merchant_group_id String(50) 於 Portal 設置的商家管理設置,交易時會依據 portal 的支付配置進行交易
不可與 merchant_id 同時使用
amount* int 交易金額。目前支援台幣、港幣、馬幣、美金,台幣以外金額需乘以 100後帶入,各幣別交易金額上限,請參考 reference
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
bank_transaction_id String(40) 銀行端的訂單編號
強烈建議商戶可在此自訂,但不能與之前的重複;若您沒有自訂則會自動幫您產生一組。
但若您沒自訂,當發生421 Gateway 操作逾時(發生機率低),則無法反查該筆交易
(格式規格請參考備註 reference)
details* String(100) 交易品項內容,為符合 PCI 要求至少必須要有品項名稱
我們的詐欺檢測器將會以此作為詐欺判定的基準,所以建議您填寫的資訊能越詳細越好
銀行儲存格式規格請參考 reference
若您啟用TSP服務,且收單銀行為台新銀行,請務必填入交易品項內容; 若沒帶入,TapPay將預設該值為交易序號以避免交易失敗
若您的收單銀行為藍新金流或支付方式為LINE Pay,此欄位須填入值,否則會導致交易失敗
instalment int(2) 分期付款期數,預設為 0
目前支援: 台新銀行, 財團法人聯合信用卡處理中心, 藍新金流, 國泰世華銀行, 玉山銀行, 中國信託銀行, 環匯亞太
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
delay_capture_in_days int 定義交易授權後銀行要過多久才會請款,單位為天
此參數非必要,預設值為0(當天請款)
若您想要自行手動請款,可帶入 -1 表示暫時不請款
* 收單銀行皆設有請款期限,請向您的收單銀行確認。若您採取手動請款模式,請留意如果該筆交易的請款日超過銀行請款期限,可能會導致請款失敗。
three_domain_secure Boolean 是否開啟 3D 驗證,預設為 false
目前支援:台新銀行、中國信託銀行、財團法人聯合信用卡處理中心、玉山銀行、永豐(New)、藍新金流、富邦、RAZER PAY、彰化銀行、國泰世華銀行

3DS2.0 驗證目前只支援National Credit Card Center of R.O.C AE 卡
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
result_url JSONObject three_domain_secure 為 true 時必填
不支援: Apple Pay, Google Pay, LINE Pay, Samsung Pay
名稱類別內容
frontend_redirect_urlString使用 LINE Pay、街口支付或者 3D 驗證交易時,當消費者在 LINE Pay、街口支付或 3D 驗證完成交易程序後,導轉回到商戶網頁前端的交易結果頁面 URL。必須以 https 開頭。
backend_notify_urlString商戶 Server 接收交易結果的 URL。必須以 https 開頭。
fraud_id String 偽卡交易識別碼,若您想要開啟偽卡偵測才需要帶
card_ccv String 卡片的後三碼,若您想要銀行驗證此參數才需要帶
若您使用 AE 卡進行3DS2.0 驗證交易時必填
redeem boolean 是否為紅利折抵。
目前支援: 財團法人聯合信用卡處理中心
不支援 : Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/payment/pay-by-token
// 正式環境 URL: https://prod.tappaysdk.com/tpc/payment/pay-by-token
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "card_key": String,
  "card_token": String,
  "partner_key": String,
  "currency": "TWD",
  "merchant_id": "merchantA",
  "details":"TapPay Test",
  "amount": 100
}

Response

名稱 類別(長度) 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
rec_trade_id String(20) 由 TapPay 伺服器產生的交易字串
將於退款時用到,請妥善保管
bank_transaction_id String(40) 銀行端的訂單編號
若有需求可在此自訂,但不能與之前的重複
若您沒有自訂則會自動幫您產生一組
格式規格請參考 reference
amount int 交易金額,台幣以外金額需乘以 100,如港幣(HKD) 1元代表 100
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference
auth_code String(6) 銀行授權碼,不支援: LINE Pay, JKOPAY
card_info JSONObject 卡片資訊。不支援: LINE Pay, JKOPAY
名稱類別(長度)內容
bin_codeString(6)卡片前六碼
last_fourString(4)卡片後四碼
issuerString發卡銀行
issuer_zh_twString發卡銀行中文名稱
bank_idString發卡銀行代碼
fundingint卡片類別
-1 = Unknown
0 = 信用卡 (Credit Card)
1 = 簽帳卡 (Debit Card)
2 = 預付卡 (Prepaid Card)
typeint卡片種類
-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
4 = Union Pay
5 = AMEX
levelString卡片等級
countryString發卡行國家
country_codeString發卡行國家碼
expiry_dateString卡片到期時間,格式 YYYYMM
(Apple Pay / Google Pay / LINE Pay / Samsung Pay 不會回傳此欄位)
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
acquirer String 收單銀行 / 金流處理器
transaction_time_millis long 交易時間
bank_transaction_time JSONObject 銀行處理時間
bank_result_code String 銀行錯誤代碼
bank_result_msg String 銀行錯誤訊息
payment_url String 付款頁面網址,將此網址回傳至前端跳轉
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
instalment_info JSONObject 非 3D 驗證交易,且使用分期付款時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
名稱類別內容
number_of_instalmentsString分期期數
first_paymentString第一期金額
each_paymentString每一期金額
extra_infoJSONObject各間銀行分期額外參數不同,請參考 extra_info
redeem_info JSONObject 非 3D 驗證交易,且使用紅利折抵時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
名稱類別內容
used_pointString紅利折抵點數
balanceString紅利餘額
offset_amountString紅利折抵金額
due_amountString折抵後自付金額
extra_infoJSONObject各間銀行紅利額外參數不同,請參考 extra_info
card_identifier String 信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
merchant_reference_info JSON 若商戶在 TapPay 後台使用 Co-brand card management 功能,且交易卡號符合設定時,將會回傳此參數

商戶於TapPay後台設定的affiliate code management須限制於20字元內且為半形的英數字
不支援: JKOPAY
名稱類別內容
affiliate_codesArray商戶在 TapPay 後台的 Co-brand card management 功能專區設定的Affiliated codes

Frontend Redirect

  1. LINE Pay, JKOPAY 或悠遊付交易完成後,TapPay 會幫您 redirect 到您於 Pay by Prime 設定的 frontend_redirect_url 的地方去 TapPay 會帶四個交易完成的參數

  2. 3D驗證交易完成後,TapPay 會幫您 redirect 到您於 Pay by Prime / Pay by Token 設定的 frontend_redirect_url 的地方去 TapPay 會帶四個交易完成的參數

Request Header

Key Value
Content-Type html/text

Request Url

https://your.domain.com/transaction_is_done?
rec_trade_id=LN20171109WsvKhn&
order_number=CF46019917&
status=0&
bank_transaction_id=TP20171109WsvKhn

Request Query String

名稱 類別 內容
rec_trade_id String 交易識別碼
order_number String 自定義訂單編號
bank_transaction_id String 銀行端的訂單編號。
強烈建議商戶可在此自訂,但不能與之前的重複;若您沒有自訂則會自動幫您產生一組。
但若您沒自訂,當發生421 Gateway 操作逾時(發生機率低),則無法反查該筆交易(格式規格請參考備註reference)
status Int 交易代碼,成功為 0

前端跳轉資料可能被偽造,建議您實做後端通知,若後端通知失敗請使用 Record API 進行反查詢

Backend Notify

  1. LINE Pay, JKOPAY, 或悠遊付交易完成後,透過 pay by prime 設定 backend_notify_url 會發一個 POST 到 backend_notify_url 進行通知

  2. 3D驗證交易完成後,透過 pay by prime / pay by token 設定 backend_notify_url 會發一個 POST 到 backend_notify_url 進行通知

Request Header

Key Value
Content-Type application/json

Request Url

Type Method : POST
Sandbox https://{backend_notify_url}
Production https://{backend_notify_url}

Request Body

名稱 類別 內容
rec_trade_id String 由 TapPay 伺服器產生的交易識別字串
將於查詢交易、退款時使用,請妥善保管
auth_code String 銀行授權碼,不支援: LINE Pay, JKOPAY
bank_transaction_id String 銀行端訂單編號
order_number String 您自定義的訂單編號,用於 TapPay 做訂單識別
amount Int 金額
status Int 交易代碼,成功為 0
msg String 交易訊息
transaction_time_millis Long Int 交易時間
pay_info JSONObject 若此交易使用 LINE Pay, JKOPAY, 悠遊付 時回傳訊息
名稱類別內容
methodString交易方式,只限LINE Pay 交易時回傳
1. CREDIT_CARD(信用卡)
2. BALANCE(一卡通 iPASS)
3. POINT (LINE Point 全額折抵)
4. DISCOUNT(LINE Pay 優惠券)
masked_credit_card_numberString遮蔽後的卡片末四碼
credit_cardInt使用信用卡支付金額。若無使用此支付方式會顯示為 0
balanceInt使用錢包儲值帳戶支付金額。若無使用此支付方式,會顯示為 0
bank_accountInt使用銀行連結帳戶支付金額。若無使用此支付方式,會顯示為 0
pointIntLINE Point 或接口幣折抵金額。若無折抵則為 0
discountIntLINE Pay 折扣碼折抵金額
e_invoice_carrier JSONObject 電子發票載具資料
目前僅支援 : JKOPAY
名稱類別內容
typeInt(3)0:手機條碼
1:自然人憑證條碼
2:其他載具條碼
numberString(100)電子發票載具號碼
donationBoolean是否捐贈
donation_idString(50)愛心碼
acquirer String 收單銀行 / 金流處理器
card_identifier String 信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
bank_result_code String 由銀行回傳的程式碼
bank_result_msg String 由銀行回傳的訊息
merchant_reference_info JSON 當商戶在 TapPay Portal 使用 Affiliate Code 功能,且交易卡號符合設定時,將會回傳此參數;或者當支付方式為電子錢包時,會回傳 TapPay 於電子錢包端收到的聯名卡代碼。不支援: JKOPAY
商戶於 TapPay Portal 設定的 affiliate code 須限制於 20 字元內且為半形的英數字。
名稱類別內容
affiliate_codesArray聯名卡代碼。
裡面包含商戶在 TapPay Portal 設定的 Affiliate Code 與TapPay 從電子錢包端收到的聯名卡代碼
instalment_info JSONObject 若有使用分期付款時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
名稱類別內容
number_of_instalmentsint分期期數
first_paymentint第一期金額
each_paymentint每一期金額
extra_infoJSONObject各間銀行分期額外參數不同,請參考 extra_info
redeem_info JSONObject 非 3D 驗證交易,且使用紅利折抵時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
名稱類別內容
used_pointString紅利折抵點數
balanceString紅利餘額
offset_amountString紅利折抵金額
due_amountString折抵後自付金額
extra_infoJSONObject各間銀行紅利額外參數不同,請參考 extra_info
event_code String(50) 與銀行或錢包合作之活動中,雙方協議的指定活動代碼。支援 : 悠遊付
merchandise_details JSONObject 交易商品明細
目前只支援 JKOPAY 悠遊付
名稱類別內容
no_rebate_amountInt不適用回饋之金額(例如:煙)
{
    // Example
    "amount": 1,
    "order_number": "KK44845743",
    "status": 0,
    "bank_transaction_id": "TP201711088cHQHr",
    "transaction_time_millis": 1510136365539,
    "acquirer": "TW_LINE_PAY",
    "msg": "Success",
    "rec_trade_id": "LN201711088cHQHr",
    "pay_info": {
        "point": 0,
        "masked_credit_card_number": "************2178",
        "method": "CREDIT_CARD"
    }
}

Refund API

此 API 能讓您用後台直接進行退款,會同時做取消授權及取消請款的動作
若您有部分退款的需求,則必須呼叫此 API
由於尖峰時段銀行方面可能會花較久時間處理,因此請將 timeout 時間設定為 30 秒以避免交易資訊不同步

當您呼叫此 API 時,TapPay 將於當日向銀行進行退款,不代表當日退款已成功。
實際退款是否成功,請於退款隔天利用 TapPay 後台或 Record API 查詢交易狀態進行確認。
各家銀行確認時間可至 Each bank capture/refund time 查看

名稱(* = 必填) 類別(長度) 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
rec_trade_id* String(20) 欲退款的交易字串,任何一筆交易成功時皆會回傳
bank_refund_id String(20) 商戶定義的退款紀錄識別碼(需為半形的英數字)
amount int 退款金額,全額退款可不用填此參數
外幣金額需包含兩位小數,如 100 代表 1.00
部分退款才需要填寫
additional_data JSONString(3000) 資料會加密保存,並在其他客製化需求時才解密做使用。
// *** 格式 ***
// 測試環境URL: https://sandbox.tappaysdk.com/tpc/transaction/refund
// 正式環境URL: https://prod.tappaysdk.com/tpc/transaction/refund
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "rec_trade_id": String,
  "amount": int // 非必填
}

Response

名稱 類別 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
refund_id String 退款紀錄的識別碼
refund_amount int 退款金額
台幣以外金額需乘以 100,如港幣(HKD) 1元 請帶 100
is_captured boolean 是否已請款
bank_result_code String 銀行錯誤代碼
bank_result_msg String 銀行錯誤訊息
currency String(3) 貨幣種類(ISO 4217)。銀行支援幣別請參考 reference

Record API

此 API 能讓您用您的後台直接進行查詢交易紀錄

名稱(* = 必填) 類別(長度) 預設 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
records_per_page int 50 每頁的交易數量,最大為 200
page int 0 第幾頁交易
filters JSONObject 沒有限制 交易紀錄的限制,有以下幾種可能:
time
amount
cardholder
merchant_id
record_status
rec_trade_id
order_number
bank_transaction_id
auth_code
currency
tsp
card_identifier
order_by JSONObject attribute = time
is_descending = true
排序的方式
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/transaction/query
// 正式環境 URL: https://prod.tappaysdk.com/tpc/transaction/query
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "records_per_page": int,
  "page": int,
  "filters": {
    "time": {
      "start_time": long,
      "end_time": long
    },
    "amount": {
      "upper_limit": int,
      "lower_limit": int
    },
    "cardholder": {
     "phone_number": String,
     "name": String,
     "email": String
   },
    "merchant_id": [String],
    "record_status": int,
    "rec_trade_id": String,
    "order_number": String,
    "bank_transaction_id": String,
    "currency": String
  },
  "order_by": {
    "attribute": String, // "time"(時間排序) 或 "amount"(金額排序)
    "is_descending": boolean
  }
}

Response

名稱 類別 內容
status int 交易代碼
2 的話代表在當前過濾條件內,已無更多紀錄
msg String 錯誤訊息
records_per_page int 每頁的交易數量,最大為 200
page int 第幾頁交易
total_page_count int 總頁數
number_of_transactions long 總交易筆數
trade_records JSONArray 交易紀錄