NAV
docs

Advanced

Cap Today API

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

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

當您呼叫此API時,TapPay 將於當日向銀行進行請款,不代表當日請款已成功。
實際請款是否成功,請於請款隔天利用TapPay 後台或 Record API查詢交易狀態進行確認。
各家銀行確認時間可至 Each bank capture/refund 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 驗證目前只支援National Credit Card Center of R.O.C AE 卡
目前支援: 台新銀行、中國信託銀行、財團法人聯合信用卡處理中心、玉山銀行、永豐(New)、藍新金流、富邦、RAZER PAY、彰化銀行、國泰世華銀行
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
result_url JSONObject 使用 LINE Pay 或 three_domain_secure 為 true 時必填
名稱類別內容
frontend_redirect_urlString使用 LINE Pay、街口支付或者 3D 驗證交易時,當消費者在 LINE Pay、街口支付或 3D 驗證完成交易程序後,導轉回到商戶網頁前端的交易結果頁面 URL。必須以 https 開頭。
backend_notify_urlString商戶 Server 接收交易結果的 URL。必須以 https 開頭。
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是否驗證身分證字號
// *** 格式 ***
// 測試環境 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
auth_code String(6) 銀行授權碼,不支援: LINE Pay, JKOPAY
merchant_id String(50) 於 Portal 登錄商家時所產生的識別碼
acquirer String 收單銀行 / 金流處理器
card_secret JSONObject 卡片保管資訊
不支援: Apple Pay, Google Pay, Samsung Pay, JKOPAY, 悠遊付
如果呼叫時透過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
名稱類別(長度)內容
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 不會回傳此欄位)
millis long 交易時間
bank_transaction_time JSONObject 銀行處理時間
bank_result_code String 銀行錯誤代碼
bank_result_msg String 銀行錯誤訊息
card_identifier String 信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付
payment_url String 付款頁面網址,將此網址回傳至前端跳轉
不支援: Apple Pay, Google Pay, Samsung Pay

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) 欲請款的交易字串,任何一筆交易成功時皆會回傳
currency String(3) 貨幣種類(ISO 4217)。銀行支援幣別請參考 reference
trade_history JSONArray 交易歷史紀錄
status int 交易代碼,成功的話為 0
msg String 錯誤訊息

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
名稱類別內容
refund_idString退款動作取得的退款識別碼
amountInt取消退款的金額
bank_result_codeString銀行錯誤代碼
bank_result_msgString銀行錯誤訊息

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
名稱類別(長度)內容
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
名稱類別(長度)內容
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
名稱類別(長度)內容
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) 綁定卡片時所帶入的會員編號
// *** 格式 ***
// 測試環境 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) 綁定卡片時所帶入的會員編號
cards JSONArray
名稱類別(長度)內容
card_tokenString(67)綁定卡片後得到的card token,在Pay by Prime API中remember帶“true”或Bind Card API後可取得
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發卡行國家碼
card_identifierString信用卡識別碼。每張信用卡只會對到一組識別碼
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付

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, 悠遊付
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
amount int 交易金額,台幣以外金額需乘以 100,如港幣(HKD) 1元代表 100
currency String(3) 貨幣種類,銀行支援幣別請參考 reference
不支援: LINE Pay, JKOPAY
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,( 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 銀行錯誤訊息
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字元內且為半形的英數字
名稱類別內容
affiliate_codesArray商戶在 TapPay 後台的 Co-brand card management 功能專區設定的Affiliated codes
cardholder JSONObject
名稱型態內容
member_idString(64)會員編號
pay_info JSONObject 付款資訊
支援:悠遊付
名稱類別(長度)內容
pointint使用Point折抵金額。若無使用此支付方式會顯示為 0
credit_cardint使用信用卡支付金額。若無使用此支付方式會顯示為 0
balanceint使用錢包儲值帳戶支付金額。若無使用此支付方式,會顯示為 0
bank_accountint使用銀行連結帳戶支付金額。若無使用此支付方式,會顯示為 0
e_invoice_carrier JSONObject 電子發票載具資料
名稱類別(長度)內容
typeint(3)載具類型
0:手機條碼
1:自然人憑證條碼
-1:其他載具條碼
-2: 未使用載具
numberString(100)電子發票載具號碼
donationBoolean是否捐贈
donation_idString (50)愛心碼