Advanced

int

交易代碼，成功的話為 0

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_token	String(67)	卡片識別字串，以後需用此參數在 Pay by Card Token 直接交易
card_key	String(64)	卡片安全金鑰，以後需用此參數在 Pay by Card Token 直接交易

JSONObject

卡片資訊
不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

名稱	類別(長度)	內容
bin_code	String(6)	卡片前六碼
last_four	String(4)	卡片後四碼
issuer	String	發卡銀行
issuer_zh_tw	String	發卡銀行中文名稱
bank_id	String	發卡銀行代碼
funding	int	卡片類別 -1 = Unknown 0 = 信用卡 (Credit Card) 1 = 簽帳卡 (Debit Card) 2 = 預付卡 (Prepaid Card)
type	int	卡片種類 -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX
level	String	卡片等級
country	String	發卡行國家
country_code	String	發卡行國家碼
expiry_date	String	卡片到期時間，格式為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_method	String	THREE_DOMAIN_SECURE: 表示訂單以 3D 驗證的規格送往銀行做交易 FRICTIONLESS: 表示訂單以一般授權的規格送往銀行做交易
transaction_method_reference	String	RBA : 該訂單最後的交易方式，是由 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

此 API 能讓您查詢 TapPay 與銀行請退款後的結果
如欲取得 TapPay 與銀行最新請退款結果，請於每日 13:00 pm 以後於此篩選前一日請退款結果
此 API 僅支援回覆 2020/10/16 以後的請退款紀錄
請注意資料篩選的時間區間，起始時間到結束時間的天數不得超過 31 天

名稱(* = 必填)	類別(長度)	內容
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

名稱

類別

內容

Int

交易代碼
2 的話代表在當前過濾條件內，已無更多紀錄

String

錯誤訊息

records_per_page

int

每頁的交易數量，最大為 200

page

int

第幾頁交易

total_page_count

int

總頁數

number_of_transactions

long

總交易筆數

reconciliation_datas

JSONArray

每筆交易的請退款動作細節

名稱

類別

內容

merchant_id

String

於 Portal 登陸商家時所產生的識別碼

merchant_description

String

TapPay Portal 商家設定中的 Merchant 備註

acquirer

String

收單銀行中文名稱，例如：玉山銀行

payment_method

String

付款方式

名稱	內容
direct_pay	Direct Pay
apple_pay	Apple Pay
google_pay_token	Google Pay Token 卡號
google_pay_fpan	Google Pay 原始卡號
samsung_pay	Samsung Pay
line_pay	LINE Pay
tsp_token	TSP Token
jko_pay	JKOPAY
easy_wallet	悠遊付
atome	Atome
pi_wallet	Pi 錢包
plus_pay	全盈支付

rec_trade_id

String

交易紀錄識別碼

bank_transaction_id

String

由大寫英文字母及數字所組成的訂單編號，此訂單編號為方便您對帳使用，並將會送至銀行

bank_order_number

String

銀行或錢包端於授權時回傳的訂單編號
支援：悠遊付
各支援銀行或錢包回傳長度限制，請參考 Reference

bank_refund_order_number

String

銀行或錢包端於退款時回傳的退款編號
支援：悠遊付, Atome, Pi錢包, 全盈支付
各支援銀行或錢包回傳長度限制，請參考 Reference

order_number

String

自定義的訂單編號，用於 TapPay 做訂單識別，可重複帶入

millis

long

觸發該狀態的時間

bank_transaction_millis

long

真實送到銀行進行授權、請款、退款、取消退款的時間。

transaction_action

String

交易操作
請款：CAPTURE
退款(意指請款後退款)：REFUND

transaction_result

Boolean

該狀態是否成功

trade_amount

int

請退款金額

auth_millis

long

商戶呼叫 TapPay API 進行授權的時間

auth_amount

int

授權金額

currency

String

此筆交易幣別

partial_card_number

String

卡號的前六碼與後四碼

card_type

int

卡片種類
-1 = Unknown
1 = Visa
2 = MasterCard
3 = JCB
4 = Union Pay
5 = AMEX

auth_code

String

銀行授權碼

is_kyc_verified

Boolean

是否有做 KYC 驗證

instalment_info

JSONObject

使用分期付款時回傳不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

名稱	類別	內容
number_of_instalments	int	分期付款期數

redeem_info

JSONObject

使用紅利折抵時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

名稱	類別	內容
offset_amount	String	紅利折抵金額

pay_info

JSONObject

若此交易使用 LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付時回傳訊息
Atome 只能綁定銀行帳戶和 debit card，所以 pay_info 中只有 bank_account 會有值

名稱	類別	內容
credit_card	int	使用信用卡支付金額。若無使用此支付方式會顯示為 0
balance	int	使用錢包儲值帳戶支付金額。若無使用此支付方式，會顯示為 0
bank_account	int	使用銀行連結帳戶支付金額。若無使用此支付方式，會顯示為
point	int	LINE Point 或接口幣折抵金額。若無折抵則為 0
discount	int	LINE 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

名稱

類別

內容

Int

交易代碼，成功的話為 0

String

錯誤訊息

currency

String

幣別

rec_trade_id

String

由 TapPay 伺服器產生的交易字串

result

Array

名稱	類別	內容
success	boolean	取消退款成功或失敗
refund_id	String	退款動作取得的退款識別碼
amount	Int	取消退款的金額
bank_result_code	String(40)	銀行回傳的交易結果代碼
bank_result_msg	String(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.”

JSONObject

卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

名稱	類別(長度)	內容
bin_code	String(6)	卡片前六碼
last_four	String(4)	卡片後四碼
issuer	String	發卡銀行
funding	int	卡片類別 -1 = Unknown 0 = 信用卡 (Credit Card) 1 = 簽帳卡 (Debit Card) 2 = 預付卡 (Prepaid Card)
type	int	卡片種類 -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX
level	String	卡片等級
country	String	發卡行國家
country_code	String	發卡行國家碼
expiry_date	String	卡片到期時間
token_status	String	未支援(卡片不支援 Tokenization):NOT_SUPPORT 請求處理中(與銀行確認中):REQUEST_PROCESSING 啟用中:ACTIVE 已暫停:SUSPENDED 已刪除:DELETED

card_art_info

JSONObject

卡面資料

名稱

類別

說明

card_art_status

String

未支援(卡片不支援真實卡面):NOT_SUPPORT
請求處理中(與銀行取得卡面資料中):REQUEST_PROCESSING
支援原卡面(已取得真實卡面):SUPPORT

is_real_card_face

Boolean

判斷是否為真實卡面
當以下情況時皆會回傳假卡片：
1. 卡片為不支援的卡種時（目前為 JCB 卡、AE 卡、銀聯卡等 )
2.卡片為 Visa、MasterCard 但發卡銀行不支援時
3. 卡片為 Visa、MasterCard 但發卡銀行註冊時並未提供國際組織卡面(極少發生)

image

Json

名稱	類別	內容
url	String	連結網址，由 “https://” 開頭
width	Int	卡面寬度, 單位 : px
height	Int	卡面高度, 單位 : px

foreground_color

String

卡面上字的顏色

masked_card_number

String

遮蔽後卡號後四碼
(e.g. : **** **** **** 1234)

issuer

String

卡面上顯示的發卡銀行
(若未顯示即為發卡行未提供)
(建議 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 取得）

JSONObject

卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

名稱	類別(長度)	內容
bin_code	String(6)	卡片前六碼
last_four	String(4)	卡片後四碼
issuer	String	發卡銀行
funding	int	卡片類別 -1 = Unknown 0 = 信用卡 (Credit Card) 1 = 簽帳卡 (Debit Card) 2 = 預付卡 (Prepaid Card)
type	int	卡片種類 -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX
level	String	卡片等級
country	String	發卡行國家
country_code	String	發卡行國家碼
expiry_date	String	卡片到期時間
token_status	String	啟用中:ACTIVE 已暫停:SUSPENDED 已刪除:DELETED

card_art_info

JSONObject

卡面資料

名稱

類別

說明

card_art_status

String

未支援(卡片不支援真實卡面):NOT_SUPPORT
支援原卡面(已取得真實卡面):SUPPORT

is_real_card_face

Boolean

判斷是否為真實卡面
當以下情況時皆會回傳假卡片：
1. 卡片為不支援的卡種時 ( 目前為 JCB 卡、AE 卡、銀聯卡等 )
2.卡片為 Visa、MasterCard 但發卡銀行不支援時
3. 卡片為 Visa、MasterCard 但發卡銀行註冊時並未提供國際組織卡面(極少發生)

image

Json

名稱	類別	內容
url	String	連結網址，由 “https://” 開頭
width	Int	卡面寬度, 單位 : px
height	Int	卡面高度, 單位 : px

foreground_color

String

卡面上字的顏色

masked_card_number

String

遮蔽後卡號後四碼
(e.g. : **** **** **** 1234)

issuer

String

卡面上顯示的發卡銀行
(若未顯示即為發卡行未提供)
(建議 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 取得）

JSONObject

卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

名稱	類別(長度)	內容
bin_code	String(6)	卡片前六碼
last_four	String(4)	卡片後四碼
issuer	String	發卡銀行
funding	int	卡片類別 -1 = Unknown 0 = 信用卡 (Credit Card) 1 = 簽帳卡 (Debit Card) 2 = 預付卡 (Prepaid Card)
type	int	卡片種類 -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX
level	String	卡片等級
country	String	發卡行國家
country_code	String	發卡行國家碼
expiry_date	String	卡片到期時間，格式 YYYYMM
token_status	String	SUSPENDED

card_art_info

JSONObject

卡面資料

名稱

類別

說明

card_art_status

String

SUPPORT

is_real_card_face

Boolean

判斷是否為真實卡面

image

Json

名稱	類別	內容
url	String	連結網址，由 “https://” 開頭
width	Int	卡面寬度, 單位 : px
height	Int	卡面高度, 單位 : px

foreground_color

String

卡面上字的顏色

masked_card_number

String

遮蔽後卡號後四碼
(e.g. : **** **** **** 1234)

issuer

String

卡面上顯示的發卡銀行
(若未顯示即為發卡行未提供)
(建議 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

名稱

類別(長度)

內容

int

交易代碼，成功的話為0

String

錯誤訊息

member_id

String(64)

綁定卡片時所帶入的會員編號。支援 : Direct Pay

cards

JSONArray

名稱	類別(長度)	內容
card_token	String(67)	綁定卡片後得到的card token，在Pay by Prime API中remember帶“true”或Bind Card API後可取得
bin_code	String(6)	卡片前六碼
last_four	String(4)	卡片後四碼
issuer	String	發卡銀行
issuer_zh_tw	String	發卡銀行中文名稱
bank_id	String	發卡銀行代碼
funding	int	卡片類別 -1 = Unknown 0 = 信用卡 (Credit Card) 1 = 簽帳卡 (Debit Card) 2 = 預付卡 (Prepaid Card)
type	int	卡片種類 -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX
level	String	卡片等級
country	String	發卡行國家
country_code	String	發卡行國家碼
card_identifier	String	信用卡識別碼。每張信用卡只會對到一組識別碼不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
expiry_date	String	卡片到期時間，格式 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_amount	int	不適用回饋之金額(例如：煙)

branch_info

JSONObject

分店資訊

名稱	類別(長度)	內容
branch_code	String(20)	分店代碼
branch_name	String(20)	分店名稱
pos_id	String(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

名稱

類別(長度)

內容

int

交易代碼，成功的話為0

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錢包, 全盈支付

JSONObject

卡片資訊
不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
裡面包含以下值：

名稱	類別(長度)	內容
bin_code	String(6)	卡片前六碼
last_four	String(4)	卡片後四碼
issuer	String	發卡銀行
issuer_zh_tw	String	發卡銀行中文名稱
bank_id	String	發卡銀行代碼
funding	int	卡片類別 -1 = Unknown 0 = 信用卡 (Credit Card) 1 = 簽帳卡 (Debit Card) 2 = 預付卡 (Prepaid Card)
type	int	卡片種類 -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX
level	String	卡片等級
country	String	發卡行國家
country_code	String	發卡行國家碼
expiry_date	String	卡片到期時間，格式 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_point	String	紅利折抵點數
balance	String	紅利餘額
offset_amount	String	紅利折抵金額
due_amount	String	折抵後自付金額
extra_info	JSONObject	各間銀行紅利額外參數不同，請參考 extra_info

card_identifier

String

信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

merchant_reference_info

JSON

商戶參考資訊

名稱	類別	內容
affiliate_codes	Array	商戶於TapPay後台或第三方合作方設定之聯名卡資訊，當交易符合設定時才會回傳不支援： LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
member_uid	String(60)	會員編號（由串接方回傳）

cardholder

JSONObject

名稱	型態	內容
member_id	String(64)	持卡人或購買人會員編號。用於 TapPay 詐欺檢測、會員資料管理時使用。支援 : Direct Pay

pay_info

JSONObject

付款資訊
支援：悠遊付

名稱	類別(長度)	內容
point	int	使用Point折抵金額。若無使用此支付方式會顯示為 0
credit_card	int	使用信用卡支付金額。若無使用此支付方式會顯示為 0
balance	int	使用錢包儲值帳戶支付金額。若無使用此支付方式，會顯示為 0
bank_account	int	使用銀行連結帳戶支付金額。若無使用此支付方式，會顯示為 0
discount	Int	折扣碼折抵金額
masked_credit_card_number	String	遮蔽後的卡片末四碼

e_invoice_carrier

JSONObject

電子發票載具資料

名稱	類別(長度)	內容
type	int(3)	載具類型 0:手機條碼 1:自然人憑證條碼 -1:其他載具條碼 -2: 未使用載具
number	String(100)	電子發票載具號碼
donation	Boolean	是否捐贈
donation_id	String (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

名稱

類別(長度)

內容

int

交易代碼，成功的話為0

String

錯誤訊息

card_token

String(67)

卡片識別字串
由 Pay by Prime 取得

update_millis

Long

更新時間

cardholder

JSONObject

此次修改後的持卡人或購買人的最新資訊

名稱	類別(長度)	內容
name	String(40)	姓名
phone_number	String(40)	手機號碼
email	String(40)	電子信箱
zip_code	String(40)	郵遞區號
address	String(90)	地址
national_id	String(40)	身份證字號
member_id	String(64)	持卡人或購買人會員編號。用於 TapPay 詐欺檢測、會員資料管理時使用。支援 : Direct Pay

Check Affiliate Code API

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

若您有帶入affiliate_code_group_name 欄位, 可以進一步確認該實體或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

商店須加購TSP服務，並向TapPay Support啟用Token Push服務
商店需向Mastercard申請MDES Token Connect 平台，並完成測試案例
Token Push API主要功能為綁卡，提供商店從網銀端發送一張Mastercard卡片至商店完成綁定的服務，並取得Card Key、Card Token

名稱(* = 必填)	類別(長度)	內容
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

名稱

類別(長度)

內容

Int

交易代碼，成功的話為0

String(30)

錯誤訊息

token_status

String(20)

啟用中:ACTIVE

card_secret

JSONObject

名稱	類別(長度)	內容
card_token	String(67)	卡片識別字串，以後需用此參數在 Pay by Card Token 直接交易
card_key	String(64)	卡片安全金鑰，以後需用此參數在 Pay by Card Token 直接交易