NAV
docs

Server APIs

Overview

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

Pay by Prime API

利用前端所取得的 prime 字串進行交易
每個 prime 字串只可使用一次,因此每次呼叫此 API 前都必須重新取得一個 prime 字串
若將 remember 設為 true 記憶卡號,則會獲得卡片識別字串卡片金鑰
以後即可省去 createToken 這個步驟並改為呼叫 Pay by Card Token 來進行交易
Apple Pay Google Pay Samsung Pay LINE Pay 不支援此功能
由於尖峰時段銀行方面可能會花較久時間處理,因此請將 timeout 時間設定為 30 秒以避免交易資訊不同步

名稱(* = 必填) 類別(長度) 內容
prime* String(67) 用卡號所換得的字串,由 getPrime 成功時回傳
prime 的時效為 30秒
您可以在 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
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
amount* int 交易金額。目前支援台幣、港幣、馬幣,台幣以外金額需乘以 100後帶入,各幣別交易金額上限,請參考 reference
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將預設該值為交易序號以避免交易失敗
cardholder* JSONObject 持卡人或購買人資訊,裡面應包含以下值:
名稱(*為必填)類別(長度)內容
phone_number*String(40)手機號碼,包含加號之 E.164 格式(“+886923456789”)
name*String(40)姓名
email*String(40)電子信箱
zip_codeString(40)郵遞區號
addressString(90)地址
national_idString(40)身份證字號
member_idString(64)會員編號
選填欄位也應有對應的 key,值的部分可以帶空字串(如:zip_code: “”, address: “”, national_id: “”)
instalment int(2) 分期付款期數,預設為 0
目前支援:台新銀行, 聯合信用卡中心, 智付通, 國泰世華銀行, 玉山銀行, 中國信託
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay
delay_capture_in_days int 定義交易授權後銀行要過多久才會請款,單位為天
此參數非必要,預設值為0(當天請款)
若您想要自行手動請款,可帶入 -1 表示暫時不請款
* 收單銀行皆設有請款期限,請向您的收單銀行確認。若您採取手動請款模式,請留意如果該筆交易的請款日超過銀行請款期限,可能會導致請款失敗。
three_domain_secure Boolean 是否開啟 3D 驗證,預設為 false
目前支援:台新銀行、中國信託銀行、聯合信用卡處理中心、玉山銀行、永豐(New)、智付通、富邦、MOLPay
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay
result_url JSONObject 使用 LINE Pay 或 three_domain_secure 為 true 時必填
名稱類別內容
frontend_redirect_urlString前端跳轉 URL,必須以 https 開頭
backend_notify_urlString後端通知 URL,必須以 https 開頭
remember boolean 是否記憶卡號
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay
redeem boolean 是否為紅利折抵。
目前支援:聯合信用卡中心
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay
additional_data JSONString(3000) 資料會加密保存,並在其他客製化需求時才解密做使用
line_pay_product_image_url String (500) LINE Pay 付款畫面時顯示的商品圖片,大小: 84 x 84
僅支援: LINE Pay
// *** 格式 ***
// 測試環境 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
card_secret JSONObject 卡片保管資訊。不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay
如果呼叫時 remember = false 則不會回傳此物件
裡面包含以下值:
名稱類別(長度)內容
card_tokenString(64)卡片識別字串,以後需用此參數在 Pay by Card Token 直接交易
card_keyString(64)卡片安全金鑰,以後需用此參數在 Pay by Card Token 直接交易
amount int 交易金額,台幣以外金額需乘以 100,如港幣(HKD) 1元代表 100
currency String(3) 貨幣種類,銀行支援幣別請參考reference
不支援:LINE Pay
card_info JSONObject 卡片資訊。不支援:LINE Pay
裡面包含以下值:
名稱類別(長度)內容
bin_codeString(6)卡片前六碼
last_fourString(4)卡片後四碼
issuerString發卡銀行
issuer_zh_twString發卡銀行中文名稱
bank_idString發卡銀行代碼
fundingint卡片類別
0 = 信用卡 (Credit Card)
1 = 簽帳卡 (Debit Card)
2 = 預付卡 (Prepaid Card)
typeint卡片種類
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
名稱類別內容
number_of_instalmentsint分期期數
first_paymentint第一期金額
each_paymentint每一期金額
extra_infoJSONObject各間銀行分期額外參數不同,請參考 extra_info
redeem_info JSONObject 非 3D 驗證交易,且使用紅利時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay
名稱類別內容
used_pointString紅利折抵點數
balanceString紅利餘額
offset_amountString紅利折抵金額
due_amountString折抵後自付金額
extra_infoJSONObject各間銀行紅利額外參數不同,請參考 extra_info
card_identifier String 不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay
信用卡識別碼。每張信用卡只會對到一組識別碼。
merchant_reference_info JSON 若商戶在 LINE Pay 或 TapPay 後台使用 Co-brand card management 功能,且交易卡號符合設定時,將會回傳此參數
名稱類別內容
affiliate_codesArray商戶在 LINE Pay 或 TapPay 後台的 Co-brand card management 功能專區設定的Affiliated codes

Refund API

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

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