NAV
docs

Advanced

Cap Today API

此 API 能讓您用後台直接讓某筆交易請款

客戶消費後,信用卡款項會經過以下幾個步驟:
授權 > 請款 > 銀行處理 > 完成交易
其中授權至請款中間隔的天數將取決於您呼叫付款 API 時所帶的參數
但若您改變主意,想要提前請款
您可呼叫此 API 讓該筆交易會當天請款

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

由於尖峰時段銀行方面可能會花較久時間處理,因此請將 timeout 時間設定為 30 秒以避免交易資訊不同步

名稱 類別(長度) 內容
partner_key String(64) 綁定 Portal 帳戶的驗證金鑰
rec_trade_id String(20) 欲請款的交易字串,任何一筆交易成功時皆會回傳
// *** 格式 ***
// 測試環境URL: https://sandbox.tappaysdk.com/tpc/transaction/cap
// 正式環境URL: https://prod.tappaysdk.com/tpc/transaction/cap
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "rec_trade_id": String
}

Response

名稱 類別 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
cap_millis long 該交易將會被請款的時間
currency String(3) 貨幣種類(ISO 4217)。銀行支援幣別請參考 reference

Bind Card API

名稱(* = 必填) 類別(長度) 內容
prime* String(67) 用卡號所換得的字串
由 createToken 成功時回傳
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
merchant_group_id String(50) 於 Portal 設置的商家管理設置,交易時會依據 portal 的支付配置進行交易
不可與 merchant_id 同時使用
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference
three_domain_secure Boolean 是否開啟 3D 驗證,預設為 false

3DS2.0 驗證目前只支援AE 卡交易且收單行為財團法人聯合信用卡處理中心
目前支援: 台新銀行、中國信託銀行、財團法人聯合信用卡處理中心、玉山銀行、永豐(New)、藍新金流、富邦、RAZER PAY、彰化銀行、國泰世華銀行、聯邦銀行
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
result_url JSONObject 使用 LINE Pay, 悠遊付, Atome, Pi錢包, 全盈支付 或 three_domain_secure 為 true 時必填
名稱類別內容
frontend_redirect_urlString使用 LINE Pay、街口支付、悠遊付、Atome, Pi錢包 或者 3D 驗證交易時,當消費者在 LINE Pay、街口支付、悠遊付、Atome、Pi 錢包 或 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 可以設定為商家首頁或是購物車頁面
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 詐欺檢測、會員資料管理時使用。支援 : Direct Pay
bank_member_idString(50)持卡人或購買人編號,屬於商戶與銀行或是錢包串接方交換或約定之消費者編號。當使用此 API 執行悠遊付錢包綁定時,此欄位為必填。支援:悠遊付
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。
支援銀行:財團法人聯合信用卡處理中心
支援產業:電支產業/ 產壽險業
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/card/bind
// 正式環境 URL: https://prod.tappaysdk.com/tpc/card/bind
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "prime": String,
  "partner_key": String,
  "merchant_id": "merchantA",
  "currency": "TWD",
  "cardholder": {
    "phone_number": "+886923456789",
    "name": "王小明",
    "email": "LittleMing@Wang.com",
    "zip_code": "100",
    "address": "台北市天龍區芝麻街1號1樓",
    "national_id": "A123456789"
  }
}

Response

名稱 類別(長度) 內容
status int 交易代碼,成功的話為 0
msg String 錯誤訊息
rec_trade_id String 交易識別碼
order_id String 銀行端的訂單編號。與 bank_transaction_id 相同,但在 Bind Card API 中,銀行訂單編號的參數名稱為 order_id。
currency String(3) 貨幣種類,銀行支援幣別請參考reference
不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包
auth_code String(6) 銀行授權碼,不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
merchant_id String(50) 於 Portal 登錄商家時所產生的識別碼
acquirer String 收單銀行 / 金流處理器
card_secret JSONObject 卡片保管資訊
不支援: Apple Pay, Google Pay, Samsung Pay, JKOPAY, Atome, Pi錢包, 全盈支付
如果呼叫時透過LINE Pay獲得的 card key與 card token,若在180天內無成功交易,將會過期導致交易失敗
裡面包含以下值:
名稱類別(長度)內容
card_tokenString(67)卡片識別字串,以後需用此參數在 Pay by Card Token 直接交易
card_keyString(64)卡片安全金鑰,以後需用此參數在 Pay by Card Token 直接交易
card_info JSONObject 卡片資訊
不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
名稱類別(長度)內容
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 / Atome / Pi錢包 / 全盈支付不會回傳此欄位)
millis long 交易時間
bank_transaction_time JSONObject 銀行處理時間
bank_result_code String(40) 銀行回傳的交易結果代碼
bank_result_msg String(300) 銀行回傳的交易結果訊息
card_identifier String 信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
payment_url String 付款頁面網址,將此網址回傳至前端跳轉
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
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 規格決定

Remove Card API

此 API 能讓您將一組綁定的 card_key 及 card_token 從我們的伺服器上移除

由於尖峰時段銀行方面可能會花較久時間處理,因此請將 timeout 時間設定為 30 秒以避免交易資訊不同步

名稱(* = 必填) 類別(長度) 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
card_key* String(64) 卡片安全金鑰
card_token* String(67) 卡片識別字串
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/card/remove
// 正式環境 URL: https://prod.tappaysdk.com/tpc/card/remove
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "card_key": String,
  "card_token": String
}

Response

名稱 類別(長度) 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息

Trade History API

此 API 能讓您查詢該筆交易的詳細狀態

名稱(* = 必填) 類別(長度) 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
rec_trade_id* String(20) 欲請款的交易字串,任何一筆交易成功時皆會回傳
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/transaction/trade-history
// 正式環境 URL: https://prod.tappaysdk.com/tpc/transaction/trade-history
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "rec_trade_id": String
}

Response

名稱 類別 內容
rec_trade_id String(20) 欲請款的交易字串,任何一筆交易成功時皆會回傳
bank_order_number String 銀行或錢包端於授權時回傳的訂單編號
支援:悠遊付, Atome, 全盈支付
各支援銀行或錢包回傳長度限制,請參考 Reference
currency String(3) 貨幣種類(ISO 4217)。銀行支援幣別請參考 reference
trade_history JSONArray 交易歷史紀錄
status int 交易代碼,成功的話為 0
msg String 錯誤訊息

Reconciliation API

名稱(* = 必填) 類別(長度) 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
records_per_page int 每頁的交易數量,最大為 200筆,預設為 50筆
page int 第幾頁的交易,預設為 0
start_time_millis* long 真實向銀行請退款的起始時間
end_time_millis* long 真實向銀行請退款的結束時間
transaction_actions* StringArray 交易操作
請款:CAPTURE
退款(意指請款後退款):REFUND
merchant_ids StringArray 於 Portal 登陸商家時所產生的識別碼
可放多個 Merchant ID
Merchant ID 與收單銀行只可擇一使用
acquirers StringArray 可以放多個 acquirers
Merchant ID 與收單銀行只可擇一使用
各收單銀行參數名稱請參考 reference
// *** 格式 ***
// 測試環境URL: https://sandbox.tappaysdk.com/tpc/transaction/reconciliation
// 正式環境URL: https://prod.tappaysdk.com/tpc/transaction/reconciliation
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "transaction_actions": ["CAPTURE", "REFUND"],
    "start_time_millis": long,
    "end_time_millis": long
}

Response

名稱 類別 內容
status Int 交易代碼
2 的話代表在當前過濾條件內,已無更多紀錄
msg String 錯誤訊息
records_per_page int 每頁的交易數量,最大為 200
page int 第幾頁交易
total_page_count int 總頁數
number_of_transactions long 總交易筆數
reconciliation_datas JSONArray 每筆交易的請退款動作細節
名稱類別內容
merchant_idString於 Portal 登陸商家時所產生的識別碼
merchant_descriptionStringTapPay Portal 商家設定中的 Merchant 備註
acquirerString收單銀行
payment_methodString付款方式
名稱內容
direct_payDirect Pay
apple_payApple Pay
google_pay_tokenGoogle Pay Token 卡號
google_pay_fpanGoogle Pay 原始卡號
samsung_paySamsung Pay
line_payLINE Pay
tsp_tokenTSP Token
jko_payJKOPAY
easy_wallet悠遊付
atomeAtome
pi_walletPi 錢包
plus_pay全盈支付
rec_trade_idString交易紀錄識別碼
bank_transaction_idString由大寫英文字母及數字所組成的訂單編號,此訂單編號為方便您對帳使用,並將會送至銀行
bank_order_numberString銀行或錢包端於授權時回傳的訂單編號
支援:悠遊付
各支援銀行或錢包回傳長度限制,請參考 Reference
bank_refund_order_numberString銀行或錢包端於退款時回傳的退款編號
支援:悠遊付, Atome, Pi錢包, 全盈支付
各支援銀行或錢包回傳長度限制,請參考 Reference
order_numberString自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
millislong觸發該狀態的時間
bank_transaction_millislong真實送到銀行進行授權、請款、退款、取消退款的時間。
transaction_actionString交易操作
請款:CAPTURE
退款(意指請款後退款):REFUND
transaction_resultBoolean該狀態是否成功
trade_amountint請退款金額
auth_millislong商戶呼叫 TapPay API 進行授權的時間
auth_amountint授權金額
currencyString此筆交易幣別
partial_card_numberString卡號的前六碼與後四碼
card_typeint卡片種類
-1 = Unknown
1 = Visa
2 = MasterCard
3 = JCB
4 = Union Pay
5 = AMEX
auth_codeString銀行授權碼
is_kyc_verifiedBoolean是否有做 KYC 驗證
instalment_infoJSONObject使用分期付款時回傳不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
名稱類別內容
number_of_instalmentsint分期付款期數
redeem_infoJSONObject使用紅利折抵時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
名稱類別內容
offset_amountString紅利折抵金額
pay_infoJSONObject若此交易使用 LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付 時回傳訊息
Atome 只能綁定銀行帳戶和 debit card,所以 pay_info 中只有 bank_account 會有值
名稱類別內容
credit_cardint使用信用卡支付金額。若無使用此支付方式會顯示為 0
balanceint使用錢包儲值帳戶支付金額。若無使用此支付方式,會顯示為 0
bank_accountint使用銀行連結帳戶支付金額。若無使用此支付方式,會顯示為
pointintLINE Point 或接口幣折抵金額。若無折抵則為 0
discountintLINE Pay 折扣碼折抵金額

Refund Cancel API

此 API 能讓您取消退款的請求,請於當天銀行進行批次處理前使用
目前僅支援台新銀行

名稱(* = 必填) 類別(長度) 內容
partner_key* String 綁定 Portal 帳戶的驗證金鑰
rec_trade_id* String 欲取消退款的交易字串,任何一筆交易成功時皆會回傳
refund_id String 退款取得的退款識別碼
// *** 格式 ***
// 測試環境URL: https://sandbox.tappaysdk.com/tpc/transaction/refund/cancel
// 正式環境URL: https://prod.tappaysdk.com/tpc/transaction/refund/cancel
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "rec_trade_id": String,
    "refund_id": String
}

Response

名稱 類別 內容
status Int 交易代碼,成功的話為 0
msg String 錯誤訊息
currency String 幣別
rec_trade_id String 由 TapPay 伺服器產生的交易字串
result Array
名稱類別內容
successboolean取消退款成功或失敗
refund_idString退款動作取得的退款識別碼
amountInt取消退款的金額
bank_result_codeString(40)銀行回傳的交易結果代碼
bank_result_msgString(300)銀行回傳的交易結果訊息

Cap Cancel API

此 API 能夠取消請款的動作,請於該筆交易送至銀行批次請款之前呼叫

名稱(* = 必填) 類別(長度) 內容
partner_key* String 綁定 Portal 帳戶的驗證金鑰
rec_trade_id* String 欲取消請款的交易字串,任何一筆交易成功時皆會回傳
// *** 格式 ***
// 測試環境URL: https://sandbox.tappaysdk.com/tpc/transaction/cap/cancel
// 正式環境URL: https://prod.tappaysdk.com/tpc/transaction/cap/cancel
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "rec_trade_id": String 
}

Response

名稱 類別 內容
status Int 交易代碼,成功的話為 0
msg String 錯誤訊息
currency String 幣別
rec_trade_id String 由 TapPay 伺服器產生的交易字串

Card Metadata API

若加購 TSP 服務即可使用此 API 取得卡片詳細資料 (如卡片、卡別、信用卡銀行、Cobrand 名稱等…)

名稱 類別(長度) 內容
partner_key String(64) 於 Portal 後台帳號資訊可取得
card_key String(64) 卡片安全金鑰
card_token String(67)  卡片識別字串
// *** 格式 ***
// 測試環境URL: https://sandbox.tappaysdk.com/tpc/card/metadata
// 正式環境URL: https://prod.tappaysdk.com/tpc/card/metadata
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "card_key": String,
  "card_token": String
}

Response

名稱 型態 內容
status Int(5) 交易代碼,成功的話為0
*若所提供之 card_key & card_token 不存在於此商店或已刪除時,會回應 2011 (Card not found. Invalid token.)
msg String(100) 回傳交易訊息
* 若所提供之 card_key & card_token 不存在於此商家或已刪除時,status 會為 2011 ,並回覆 “Card not found. Invalid token.”
card_info JSONObject 卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
名稱類別(長度)內容
bin_codeString(6)卡片前六碼
last_fourString(4)卡片後四碼
issuerString發卡銀行
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卡片到期時間
token_statusString未支援(卡片不支援 Tokenization):NOT_SUPPORT
請求處理中(與銀行確認中):REQUEST_PROCESSING
啟用中:ACTIVE
已暫停:SUSPENDED
已刪除:DELETED
card_art_info JSONObject 卡面資料
名稱類別說明
card_art_statusString未支援(卡片不支援真實卡面):NOT_SUPPORT
請求處理中(與銀行取得卡面資料中):REQUEST_PROCESSING
支援原卡面(已取得真實卡面):SUPPORT
is_real_card_faceBoolean判斷是否為真實卡面
當以下情況時皆會回傳假卡片:
1. 卡片為不支援的卡種時( 目前為 JCB 卡、AE 卡、銀聯卡等 )
2.卡片為 Visa、MasterCard 但發卡銀行不支援時
3. 卡片為 Visa、MasterCard 但發卡銀行註冊時並未提供國際組織卡面(極少發生)
imageJson
名稱類別內容
urlString連結網址,由 “https://” 開頭
widthInt卡面寬度, 單位 : px
heightInt卡面高度, 單位 : px
foreground_colorString卡面上字的顏色
masked_card_numberString遮蔽後卡號後四碼
(e.g. : **** **** **** 1234)
issuerString卡面上顯示的發卡銀行
(若未顯示即為發卡行未提供)
(建議 Is_real_card_face 若為 false 可將發卡銀行名稱加入在卡面上)

Card Notify API

若加購TSP服務,當卡片狀態異動(包含Visa與Mastercard卡)時,會在每個整點將上個小時符合上述狀態的卡片資訊一起通知商戶。



*用戶須先告知 TapPay 客服人員貴司欲接收卡片更新通知的URL

Request Header

Key Value
Content-Type application/json

Request Url

Type Method : POST
Production https://{tsp_notify_url}

Request Body

名稱 類別 內容
status Int 交易代碼,成功的話為 0
msg String 回傳交易訊息
card_token Array 對應到該卡片所有的 TapPay 卡片識別字串(由 Pay by Prime remember:true 時或 Bind card API 取得)
card_info JSONObject 卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
名稱類別(長度)內容
bin_codeString(6)卡片前六碼
last_fourString(4)卡片後四碼
issuerString發卡銀行
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卡片到期時間
token_statusString啟用中:ACTIVE 已暫停:SUSPENDED 已刪除:DELETED
card_art_info JSONObject 卡面資料
名稱類別說明
card_art_statusString未支援(卡片不支援真實卡面):NOT_SUPPORT
支援原卡面(已取得真實卡面):SUPPORT
is_real_card_faceBoolean判斷是否為真實卡面
當以下情況時皆會回傳假卡片:
1. 卡片為不支援的卡種時 ( 目前為 JCB 卡、AE 卡、銀聯卡等 )
2.卡片為 Visa、MasterCard 但發卡銀行不支援時
3. 卡片為 Visa、MasterCard 但發卡銀行註冊時並未提供國際組織卡面(極少發生)
imageJson
名稱類別內容
urlString連結網址,由 “https://” 開頭
widthInt卡面寬度, 單位 : px
heightInt卡面高度, 單位 : px
foreground_colorString卡面上字的顏色
masked_card_numberString遮蔽後卡號後四碼
(e.g. : **** **** **** 1234)
issuerString卡面上顯示的發卡銀行
(若未顯示即為發卡行未提供)
(建議 Is_real_card_face 若為 false 可將發卡銀行名稱加入在卡面上)
{
    // Example
    {
    "status" : Int,
    "msg" : String,
    "card_token" : [String, String],
    "card_info" : {
        "bin_code" : String, 
        "last_four" : String,
        "issuer" : String,
        "funding" : Int,
        "type" : Int,
        "level" : String,
        "country" : String,
        "country_code" : String,
        "expiry_date" : String,
        "token_status" : String,
    },
    "card_art_info": {
        "card_art_status": String,
        "is_real_card_face" : boolean,
        "image" : {
            "url" : String,
            "width" : Int,
            "height" : Int
        },
            "foreground_color" : String,
            "masked_card_number" : String,
            "issuer" : String 
        }
    }
}

Card Notify API Sandbox

當您加購 TSP 服務, TapPay 會透過您輸入的『接收更新的URL』,並藉由 Card Notify API 通知您相關訊息(通知的時機請詳見 Card Notify API),此 API 目的為測試您提供的 URL 能正確收到通知

名稱(* = 必填) 類別(長度) 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
card_key* String(64) 卡片安全金鑰
Pay by Prime 取得
請使用測試卡號:4242424181784242
card_token* String(67) 卡片識別字串
Pay by Prime 取得
請使用測試卡號:4242424181784242
tsp_notify_url* String(500) 接收卡片狀態異動通知的URL
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/sandbox/card/metadata/notify
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "card_key": String,
    "card_token": String,
    "tsp_notify_url": String
}

Request body to tsp_notify_url

名稱 類別 內容
status Int 交易代碼,成功的話為 0
msg String 回傳交易訊息並回覆 Card not found. Invalid token.
card_token Array 對應到該卡片所有的 TapPay 卡片識別字串(由 Pay by Prime remember:true 時或 Bind card API 取得)
card_info JSONObject 卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
名稱類別(長度)內容
bin_codeString(6)卡片前六碼
last_fourString(4)卡片後四碼
issuerString發卡銀行
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
token_statusStringSUSPENDED
card_art_info JSONObject 卡面資料
名稱類別說明
card_art_statusStringSUPPORT
is_real_card_faceBoolean判斷是否為真實卡面
imageJson
名稱類別內容
urlString連結網址,由 “https://” 開頭
widthInt卡面寬度, 單位 : px
heightInt卡面高度, 單位 : px
foreground_colorString卡面上字的顏色
masked_card_numberString遮蔽後卡號後四碼
(e.g. : **** **** **** 1234)
issuerString卡面上顯示的發卡銀行
(若未顯示即為發卡行未提供)
(建議 Is_real_card_face 若為 false 可將發卡銀行名稱加入在卡面上)

Get Member Card API

此為 TapPay 取得會員目前綁卡資料之API,負責回傳商戶各會員編號下所綁定之卡片

名稱(* = 必填) 類別(長度) 內容
partner_key* String(67) 於 Portal 後台 帳號資訊 可複製的 API Partner Key
member_id* String(64) 綁定卡片時所帶入的會員編號。支援 : Direct Pay
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/direct-pay/get-member-card
// 正式環境 URL: https://prod.tappaysdk.com/tpc/direct-pay/get-member-card
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "member_id": String
}

Response

名稱 類別(長度) 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
member_id String(64) 綁定卡片時所帶入的會員編號。支援 : Direct Pay
cards JSONArray
名稱類別(長度)內容
card_tokenString(67)綁定卡片後得到的card token,在Pay by Prime API中remember帶“true”或Bind Card API後可取得
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發卡行國家碼
card_identifierString信用卡識別碼。每張信用卡只會對到一組識別碼
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
expiry_dateString卡片到期時間,格式 YYYYMM(Apple Pay / Google Pay / LINE Pay / Samsung Pay 不會回傳此欄位)

Get Barcode API

此 API 負責幫商戶產出 barcode 資料

名稱(* = 必填) 類別(長度) 內容
partner_key* String(67) 綁定 Portal 帳戶的驗證金鑰
card_key* String(64) 卡片安全金鑰
Pay by Prime 取得
card_token* String(67) 卡片識別字串
Pay by Prime 取得
barcode_length Int bar code長度(建議5-60個位元)(若沒帶,預設值為15)
barcode_update_secs Int bar code更新時間(秒數)(若沒帶,預設值為90)(秒數上限為86400秒)
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/direct-pay/get-barcode
// 正式環境 URL: https://prod.tappaysdk.com/tpc/direct-pay/get-barcode
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "card_key": String,
    "card_token": String,
    "barcode_length": Int,
    "barcode_update_secs": Int
}

Response

名稱 類別(長度) 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
barcode String(5-60) 由大小寫英數字組成的barcode
barcode_update_secs Int barcode更新秒數

Pay by Barcode API

此 API 允許商戶利用 barcode 付款

名稱(* = 必填) 類別(長度) 內容
barcode* String(5-60) 每次交易的條碼
partner_key* String(67) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
merchant_group_id String(50) 於 Portal 設置的商家管理設置,交易時會依據 portal 的支付配置進行交易
不可與 merchant_id 同時使用
amount* int 交易金額。目前支援台幣、港幣、馬幣、美金,台幣以外金額需乘以 100後帶入
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference,預設為 TWD
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference。若有帶入此欄位,則不可為空
bank_transaction_id String(40) 銀行端的訂單編號
強烈建議商戶可在此自訂,但不能與之前的重複;若您沒有自訂則會自動幫您產生一組。
但若您沒自訂,當發生421 Gateway 操作逾時(發生機率低),則無法反查該筆交易
(格式規格請參考備註 reference)
details* String(100) 交易品項內容,為符合 PCI 要求至少必須要有品項名稱
我們的詐欺檢測器將會以此作為詐欺判定的基準,所以建議您填寫的資訊能越詳細越好
若您的收單銀行為藍新金流或支付方式為LINE Pay,此欄位須填入值,否則會導致交易失敗
銀行儲存格式規格請參考 reference
delay_capture_in_days int 定義交易授權後銀行要過多久才會請款,單位為天
此參數非必要,預設值為0(當天請款)
若您想要自行手動請款,可帶入 -1 表示暫時不請款
retry_mode String 新交易 = 1, 重送交易 = 2,
沒帶預設為 新交易 = 1
redeem boolean 是否為紅利折抵。
目前支援: 財團法人聯合信用卡處理中心
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
additional_data String 請依約定格式帶入 JSON String,資料會加密保存,並在其他客製化需求時才解密做使用。
merchantdise_details JSONObject 交易商品明細
名稱類別(長度)內容
no_rebate_amountint不適用回饋之金額(例如:煙)
branch_info JSONObject 分店資訊
名稱類別(長度)內容
branch_codeString(20)分店代碼
branch_nameString(20)分店名稱
pos_idString(8)分店收銀機代碼
payment_method int(2) 付款方式
0=信用卡
5=Easy Wallet
Default: 0
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/payment/pay-by-barcode
// 正式環境 URL: https://prod.tappaysdk.com/tpc/payment/pay-by-barcode
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "barcode": String,
    "partner_key": String,
    "merchant_id": "merchantA",
    "amount": 100,
    "details":"TapPay Test",
    "currency": "TWD",
    "order_number": String,
    "bank_transaction_id": String,
    "delay_capture_in_days": Int
}

Response

名稱 類別(長度) 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
rec_trade_id String(20) 由 TapPay 伺服器產生的交易字串
將於退款時用到,請妥善保管
bank_transaction_id String(40) 銀行端的訂單編號
強烈建議商戶可在此自訂,但不能與之前的重複;若您沒有自訂則會自動幫您產生一組。
但若您沒自訂,當發生421 Gateway 操作逾時(發生機率低),則無法反查該筆交易
格式規格請參考 reference
bank_order_number String 銀行或錢包端於授權時回傳的訂單編號
支援:悠遊付
各支援銀行或錢包回傳長度限制,請參考 Reference
amount int 交易金額,台幣以外金額需乘以 100,如港幣(HKD) 1元代表 100
merchant_id String(50) 於 Portal 登錄商家時所產生的識別碼
currency String(3) 貨幣種類,銀行支援幣別請參考 reference
不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
auth_code String(6) 銀行授權碼
不支援:LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
card_info JSONObject 卡片資訊
不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
裡面包含以下值:
名稱類別(長度)內容
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 / Atome / Pi錢包 / 全盈支付 不會回傳此欄位)
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) 銀行回傳的交易結果訊息
redeem_info JSONObject 非 3D 驗證交易,且使用紅利折抵時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
名稱類別內容
used_pointString紅利折抵點數
balanceString紅利餘額
offset_amountString紅利折抵金額
due_amountString折抵後自付金額
extra_infoJSONObject各間銀行紅利額外參數不同,請參考 extra_info
card_identifier String 信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
merchant_reference_info JSON 商戶參考資訊
名稱類別內容
affiliate_codesArray商戶於TapPay後台或第三方合作方設定之聯名卡資訊,當交易符合設定時才會回傳
不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
member_uidString(60)會員編號(由串接方回傳)
cardholder JSONObject
名稱型態內容
member_idString(64)持卡人或購買人會員編號。用於 TapPay 詐欺檢測、會員資料管理時使用。支援 : Direct Pay
pay_info JSONObject 付款資訊
支援:悠遊付
名稱類別(長度)內容
pointint使用Point折抵金額。若無使用此支付方式會顯示為 0
credit_cardint使用信用卡支付金額。若無使用此支付方式會顯示為 0
balanceint使用錢包儲值帳戶支付金額。若無使用此支付方式,會顯示為 0
bank_accountint使用銀行連結帳戶支付金額。若無使用此支付方式,會顯示為 0
discountInt折扣碼折抵金額
masked_credit_card_numberString遮蔽後的卡片末四碼
e_invoice_carrier JSONObject 電子發票載具資料
名稱類別(長度)內容
typeint(3)載具類型
0:手機條碼
1:自然人憑證條碼
-1:其他載具條碼
-2: 未使用載具
numberString(100)電子發票載具號碼
donationBoolean是否捐贈
donation_idString (50)愛心碼

Update Cardholder API

此API 能讓您修改已綁定的持卡人資訊
資訊一但被更新, TapPay 將只保留最新持卡人資訊.

名稱(* = 必填) 類別(長度) 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
card_token* String(67) 卡片識別字串
Pay by Prime 取得
name String(40) 姓名
phone_number String(40) 手機號碼,可為 09 開頭的電話或是包含加號之 E.164 格式(“+886923456789”)
email String(40) 電子信箱
zip_code String(40) 郵遞區號
address String(90) 地址
national_id String(40) 身份證字號
member_id String(64) 持卡人或購買人會員編號。用於 TapPay 詐欺檢測、會員資料管理時使用。支援 : Direct Pay
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/card/update-cardholder
// 正式環境 URL: https://prod.tappaysdk.com/tpc/card/update-cardholder
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "card_token": String,
    "name": String,
    "phone_number": String,
    "email": String,
    "zip_code": String,
    "address": String,
    "national_id": String,
    "member_id": String,
}

Response

名稱 類別(長度) 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
card_token String(67) 卡片識別字串
Pay by Prime 取得
update_millis Long 更新時間
cardholder JSONObject 此次修改後的持卡人或購買人的最新資訊
名稱類別(長度)內容
nameString(40)姓名
phone_numberString(40)手機號碼
emailString(40)電子信箱
zip_codeString(40)郵遞區號
addressString(90)地址
national_idString(40)身份證字號
member_idString(64)持卡人或購買人會員編號。用於 TapPay 詐欺檢測、會員資料管理時使用。支援 : Direct Pay

Check Affiliate Code API

此 API 可以讓您知道該實體或token卡號是否隸屬於您帶入的聯名卡

名稱(* = 必填) 類別(長度) 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
affiliate_code_group_name String(50) 聯名卡群組
affiliate_code_name* String(20) 聯名卡
card_token String(67) 卡片識別字串
需和 card_key 同時帶入,但不可與 prime 同時帶入
card_key String(64) 卡片安全金鑰
需和 card_token 同時帶入,但不可與 prime 同時帶入
prime String(67) 用卡號所換得的字串,由 getPrime 成功時回傳
不可與card_token/card_key 同時帶入
// *** 格式 ***
// 測試環境 URL: https://sandbox.tappaysdk.com/tpc/affiliate-code/check
// 正式環境 URL: https://prod.tappaysdk.com/tpc/affiliate-code/check
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "affiliate_code_group_name": String,
    "affiliate_code_name": String,

    // 第一種帶法 
    "card_token": String,
    "card_key": String,

    // 第二種帶法
    "prime": String,
}

Response

名稱 類別 內容
status Int 0 代表動作成功
msg String 錯誤訊息
result_code Int 是否符合查詢條件
0 代表符合,1 代表不符合

Push Token API

名稱(* = 必填) 類別(長度) 內容
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
tsp_push_token* String(1000) 開啟商店app時,傳給app的tspPushToken欄位值
// *** 格式 ***
// 正式環境 URL: https://prod.tappaysdk.com/tpc/tsp/token/push-tokenize
// Header:
//   Content-Type: application/json​
//   x-api-key: axgLG8z7vVa8mgIzdU1233rjBFAEmTti19NZd1pI
{
    "partner_key": "axgLG8z7vVa8mgIzdU1233rjBFAEmTti19NZd1pI",
    "tsp_push_token": "eyJxcyI6ImFjY291bnRIb2xkZXJEYXRhU3VwcGxpZWQ9dHJ1ZSZjYWxsYmFja1VSTD1odHRwczovL3Rva2VuY29ubmVjdC5tY3NyY3Rlc3RzdG9yZS5jb20vdG9rZW5pemF0aW9uLXJlc3VsdHMmY29tcGxldGVJc3N1ZXJBcHBBY3RpdmF0aW9uPXRydWUmY29tcGxldGVXZWJzaXRlQWN0aXZhdGlvbj10cnVlJmxvY2FsZT1lbl9VUyZwdXNoQWNjb3VudFJlY2VpcHRzPU1DQy1TVEwtQjI5MDZCNzgtOThGNS00QzVCLUIyNTUtMTQxNjM3QzI0QzZGIiwiY2FyZEJyYW5kIjoiTTRNIiwiY2xpZW50SXAiOiIyMTEuNzIuMTExLjE2MCIsInR4SWQiOiJjZjhmMGFmNzQ5ZDU0MmE2YmY0YzEwMjkwYmE1MGZiOSJ9"
}

Response

名稱 類別(長度) 內容
status Int 交易代碼,成功的話為0
msg String(30) 錯誤訊息
token_status String(20) 啟用中:ACTIVE
card_secret JSONObject 卡片保管資訊
不支援: Apple Pay, Google Pay, Samsung Pay, JKOPAY, Atome, Pi錢包, 全盈支付
如果呼叫時透過LINE Pay獲得的 card key與 card token,若在180天內無成功交易,將會過期導致交易失敗
裡面包含以下值:
名稱類別(長度)內容
card_tokenString(67)卡片識別字串,以後需用此參數在 Pay by Card Token 直接交易
card_keyString(64)卡片安全金鑰,以後需用此參數在 Pay by Card Token 直接交易
card_info JSONObject 卡片資訊
不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
名稱類別(長度)內容
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 / Atome / Pi錢包 / 全盈支付不會回傳此欄位)
cardholder JSONObject 持卡人資訊,沒有資料會回空字串
名稱類別(長度)內容
nameString(40)姓名
phone_numberString(40)手機號碼
emailString(40)電子信箱
zip_codeString(40)郵遞區號
addressString(90)地址
card_network_status String(100) 卡組織錯誤代碼
card_network_msg String(100) 卡組織錯誤訊息
callback_url String(400) 回到網銀url
(optional)
// *** 格式 ***
// 正式環境 URL:https://prod.tappaysdk.com/tpc/tsp/token/push-tokenize
// Header:
//   Content-Type: application/json​
{
    "status": 0,
    "msg": "Success",
    "card_network_status": "",
    "card_network_msg": "",
    "token_status": "ACTIVE",
    "card_secret": {
        "card_token": "da572568e1695f1336b0d9ae889621ee4fd449ba5215a6b4540a5534e1b6540a",
        "card_key": "cb5277a884a07d7ef0fbdaef1ecc01ca4660b60ae28b3e47ac21c90fa530d91e"
    },
    "card_info": {
        "issuer": "CTBC Bank",
        "funding": 0,
        "type": 2,
        "level": "",
        "country": "UNITED STATES",
        "last_four": "4768",
        "bin_code": "520473",
        "issuer_zh_tw": "",
        "bank_id": "822",
        "country_code": "US",
        "expiry_date": "202303"
    },
    "cardholder": {
        "name": "John Doe",
        "email": "John.doe@mailinator.com",
        "address": "10 Sunflower Avenue, Apt. 4B, St. Louis, MO, 61000, USA",
        "phone_number": "+11234567890",
        "zip_code": "61000"
    },
    "callback_url": "https://tokenconnect.mcsrcteststore.com/tokenization-results?results%5BMCC-STL-B2906B78-98F5-4C5B-B255-141637C24C6F%5D=APPROVED%7CDM4MMC000014413677d8fef0baff4e83b4b48c096ab526c4"
}