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)持卡人或購買人會員編號。用於 TapPay 詐欺檢測、會員資料管理時使用。
cardholder_verify JSONObject 身份驗證欄位,請注意:若此筆交易需身份驗證,請詳讀備註中各銀行需驗證的必填欄位,若該欄位為 “true” 會根據您的使用情境送至對應的機構進行身份驗證
您可以在 sandbox 環境中使用備註中的測試用身分證字號及電話號碼
支援: Direct Pay
有以下兩種使用情境
使用情境說明支援身份驗證收單銀行支援授權收單銀行支援程度注意事項
身份驗證及授權皆可使用同一 merchant id 完成財團法人聯合信用卡處理中心財團法人聯合信用卡處理中心所有發卡行無法做電話號碼驗證,可參考備註
台新銀行台新銀行所有發卡行
玉山銀行玉山銀行自行卡無法做電話號碼驗證,可參考備註
身份驗證:財團法人聯合信用卡處理中心
授權:所有TapPay支援的銀行
財團法人聯合信用卡處理中心所有TapPay支援的銀行所有發卡行kyc_verification_merchant_id必填,並請填入您於Portal的商家管理 > KYC 驗證商家設置建立的merchant ID

驗證欄位
名稱類型(長度)內容
phone_numberBoolean是否驗證電話號碼
national_idBoolean是否驗證身分證字號
kyc_verification_merchant_id String 此欄位請填入僅供身份驗證,無授權功能的merchant ID。
支援銀行:財團法人聯合信用卡處理中心
支援產業:電支產業/ 產壽險業
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 驗證目前只支援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 開頭,僅支援 443 port。
go_back_urlString3D 驗證交易時,當消費者因不當操作而被導到 TapPay Error 頁面時,頁面上「Go back」按鈕連結。此情境僅會發生於玉山銀行, 國泰世華銀行, 台新銀行。
若您在交易的 Request 中有定義此參數,則消費者按下 Go back按鈕後,會導到您所指定的 URL;亦可於TapPay Portal > 開發者 > 系統設定 > 跳轉連結設定 設定 Go back 按鈕指向的 URL。
強烈建議您在 3D 交易時定義這個欄位,避免消費者被導轉到交易錯誤頁面時,無法回到商家頁面完成交易或查看交易結果。
建議您此 URL 可以設定為商家首頁或是購物車頁面
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(40) 銀行回傳的交易結果代碼
bank_result_msg String(300) 銀行回傳的交易結果訊息
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 商戶參考資訊
名稱類別內容
affiliate_codesArray商戶於 TapPay 後台或第三方合作方設定之聯名卡資訊,當交易符合設定時才會回傳,不支援 JKOPAY
event_code String(50) 與銀行或錢包合作之活動中,雙方協議的指定活動代碼。支援 : 悠遊付
is_rba_verified Boolean 該交易有無取得 RBA 評估的風險分數RBA 可以為每筆交易評估風險,以辨認和防止偽冒交易發生。該產品即將上線,您可以參考 TapPay 官網更了解 RBA 這項服務。
transaction_method_details JSONObject 交易方式細節
RBA 可以為每筆交易評估風險,以辨認和防止偽冒交易發生。該產品即將上線,您可以參考 TapPay 官網更了解 RBA 這項服務。
名稱類別內容
transaction_methodStringTHREE_DOMAIN_SECURE: 表示訂單以 3D 驗證的規格送往銀行做交易
FRICTIONLESS: 表示訂單以一般授權的規格送往銀行做交易
transaction_method_referenceStringRBA : 該訂單最後的交易方式,是由 RBA 風險分數規則決定
REQUEST : 訂單最後的交易方式,是由商戶交易時帶來的 Request 規格決定

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,此欄位須填入值,否則會導致交易失敗
cardholder_verify JSONObject 身份驗證欄位,請注意:若此筆交易需身份驗證,請詳讀備註中各銀行需驗證的必填欄位,若該欄位為 “true” 會根據您的使用情境送至對應的機構進行身份驗證
您可以在 sandbox 環境中使用備註中的測試用身分證字號及電話號碼
支援: Direct Pay
有以下兩種使用情境
使用情境說明支援身份驗證收單銀行支援授權收單銀行支援程度注意事項
身份驗證及授權皆可使用同一 merchant id 完成財團法人聯合信用卡處理中心財團法人聯合信用卡處理中心所有發卡行無法做電話號碼驗證,可參考備註
台新銀行台新銀行所有發卡行
玉山銀行玉山銀行自行卡無法做電話號碼驗證,可參考備註
身份驗證:財團法人聯合信用卡處理中心
授權:所有TapPay支援的銀行
財團法人聯合信用卡處理中心所有TapPay支援的銀行所有發卡行kyc_verification_merchant_id必填,並請填入您於Portal的商家管理 > KYC 驗證商家設置建立的merchant ID

驗證欄位
名稱類型(長度)內容
phone_numberBoolean是否驗證電話號碼
national_idBoolean是否驗證身分證字號
kyc_verification_merchant_id String 此欄位請填入僅供身份驗證,無授權功能的merchant ID。
支援銀行:財團法人聯合信用卡處理中心
支援產業:電支產業/ 產壽險業
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 驗證目前只支援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 開頭,僅支援 443 port。
go_back_urlString3D 驗證交易時,當消費者因不當操作而被導到 TapPay Error 頁面時,頁面上「Go back」按鈕連結。此情境僅會發生於玉山銀行, 國泰世華銀行, 台新銀行。
若您在交易的 Request 中有定義此參數,則消費者按下 Go back按鈕後,會導到您所指定的 URL;亦可於TapPay Portal > 開發者 > 系統設定 > 跳轉連結設定 設定 Go back 按鈕指向的 URL。
強烈建議您在 3D 交易時定義這個欄位,避免消費者被導轉到交易錯誤頁面時,無法回到商家頁面完成交易或查看交易結果。
建議您此 URL 可以設定為商家首頁或是購物車頁面
card_ccv String 信用卡安全碼。不可與ccv_prime 同時帶入
當有以下情況時請帶入此參數
1. 未在get-ccv-prime 時取得ccv_prime但想要銀行驗證此參數
2. 未在get-ccv-prime 時取得ccv_prime但使用 AE 卡進行3DS2.0 驗證交易時
不支援LINE Pay, Easy Wallet
redeem boolean 是否為紅利折抵。
目前支援: 財團法人聯合信用卡處理中心
不支援 : Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
additional_data JSONString(3000) 資料會加密保存,並在其他客製化需求時才解密做使用
ccv_prime String 用信用卡安全碼所換得的字串,由 get-ccv-prime 成功時回傳
不可與card_ccv 同時帶入ccv_prime 的時效為 90秒
支援 : Direct Pay
您可以在 sandbox 環境中使用此測試用
ccv_prime(3碼) : test_65b1ca2d5d0dc8ff5b62296ea8547bab08401f8a57015fb818c5bcd10433fa11
ccv_prime(4碼) : test_cd1e737890874cdadf39caaf56c5b183c36a4117ca89cb24fd674c0892e0fa92
// *** 格式 ***
// 測試環境 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(40) 銀行回傳的交易結果代碼
bank_result_msg String(300) 銀行回傳的交易結果訊息
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 商戶參考資訊
名稱類別內容
affiliate_codesArray商戶於 TapPay 後台或第三方合作方設定之聯名卡資訊,當交易符合設定時才會回傳,不支援 JKOPAY
is_rba_verified Boolean 該交易有無取得 RBA 評估的風險分數RBA 可以為每筆交易評估風險,以辨認和防止偽冒交易發生。該產品即將上線,您可以參考 TapPay 官網更了解 RBA 這項服務。
transaction_method_details JSONObject 交易方式細節
RBA 可以為每筆交易評估風險,以辨認和防止偽冒交易發生。該產品即將上線,您可以參考 TapPay 官網更了解 RBA 這項服務。
名稱類別內容
transaction_methodStringTHREE_DOMAIN_SECURE: 表示訂單以 3D 驗證的規格送往銀行做交易
FRICTIONLESS: 表示訂單以一般授權的規格送往銀行做交易
transaction_method_referenceStringRBA : 該訂單最後的交易方式,是由 RBA 風險分數規則決定
REQUEST : 訂單最後的交易方式,是由商戶交易時帶來的 Request 規格決定

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 交易時間
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(40) 銀行回傳的交易結果代碼
bank_result_msg String(300) 銀行回傳的交易結果訊息
merchant_reference_info JSON 商戶參考資訊
名稱類別內容
affiliate_codesArray商戶於 TapPay 後台或第三方合作方設定之聯名卡資訊,當交易符合設定時才會回傳,不支援 JKOPAY, 悠遊付
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

名稱(* = 必填) 類別(長度) 內容
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(40) 銀行回傳的交易結果代碼
bank_result_msg String(300) 銀行回傳的交易結果訊息
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 交易紀錄