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(64) 用卡號所換得的字串,由 getPrime 成功時回傳

您可以在 sandbox 環境中使用此測試用prime
prime : test_3a2fb2b7e892b914a03c95dd4dd5dc7970c908df67a49527c0a648b2bc9
partner_key* String(60) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
amount* int 交易金額,台幣以外金額需包含兩位小數,如 100 代表 1.00
currency String(3) 貨幣種類,銀行支援幣別請參考 reference
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
bank_transaction_id String(16) 銀行端的訂單編號
若有需求可在此自訂,但不能與之前的重複
若您沒有自訂則會自動幫您產生一組
格式規格請參考 reference
details* String(100) 交易品項內容,為符合 PCI 要求至少必須要有品項名稱
我們的詐欺檢測器將會以此作為詐欺判定的基準,所以建議您填寫的資訊能越詳細越好
銀行儲存格式規格請參考 reference
cardholder* JSONObject 持卡人或購買人資訊,裡面應包含以下值:
名稱(*為必填)類別(長度)內容
phone_number*String(40)手機號碼,包含加號之 E.164 格式(“+886923456789”)
name*String(40)姓名
email*String(40)電子信箱
zip_codeString(40)郵遞區號
addressString(90)地址
national_idString(40)身份證字號
選填欄位也應有對應的 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 表示暫時不請款
remember boolean 是否記憶卡號,Apple Pay, Google Pay, Samsung Pay, 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(16) 銀行端的訂單編號
若有需求可在此自訂,但不能與之前的重複
若您沒有自訂則會自動幫您產生一組
格式規格請參考 reference
auth_code String(6) 銀行授權碼
card_secret JSONObject 卡片保管資訊
如果呼叫時 remember = false 則不會回傳此物件
裡面包含以下值:
名稱類別(長度)內容
card_tokenString(64)卡片識別字串,以後需用此參數在 Pay by Card Token 直接交易
card_keyString(64)卡片安全金鑰,以後需用此參數在 Pay by Card Token 直接交易
amount int 交易金額,台幣以外金額需包含兩位小數,如 100 代表 1.00
currency String(3) 貨幣種類,銀行支援幣別請參考 reference
card_info JSONObject 卡片資訊,裡面包含以下值:
名稱類別(長度)內容
bin_codeString(6)卡片前六碼
last_fourString(4)卡片後四碼
issuerString發卡銀行
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 不會回傳此欄位)
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
acquirer String 收單銀行 / 金流處理器
transaction_time_millis long 交易時間
bank_transaction_time JSONObject 銀行處理時間
bank_result_code String 銀行錯誤代碼
bank_result_msg String 銀行錯誤訊息
instalment_info JSONObject
名稱類別內容
number_of_instalmentsint分期期數
first_paymentint第一期金額
each_paymentint每一期金額
extra_infoJSONObject各間銀行分期額外參數不同,請參考 extra_info

Pay by Card Token API

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

名稱(* = 必填) 類別(長度) 內容
card_key* String(64) 卡片安全金鑰
Pay by Prime 取得
card_token* String(64) 卡片識別字串
Pay by Prime 取得
partner_key* String(60) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
amount* int 交易金額,台幣以外金額需包含兩位小數,如 100 代表 1.00
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
bank_transaction_id String(16) 銀行端的訂單編號
若有需求可在此自訂,但不能與之前的重複
若您沒有自訂則會自動幫您產生一組
格式規格請參考 reference
details* String(100) 交易品項內容,為符合 PCI 要求至少必須要有品項名稱
我們的詐欺檢測器將會以此作為詐欺判定的基準,所以建議您填寫的資訊能越詳細越好
銀行儲存格式規格請參考 reference
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,目前支援台新銀行、中國信託銀行、聯合信用卡處理中心、玉山銀行
result_url* JSONObject three_domain_secure 為 true 時必填
名稱類別內容
frontend_redirect_urlString前端跳轉 URL,必須以 https 開頭
backend_notify_urlString後端通知 URL,必須以 https 開頭
fraud_id String 偽卡交易識別碼,若您想要開啟偽卡偵測才需要帶
card_ccv String 卡片的後三碼,若您想要銀行驗證此參數才需要帶
// *** 格式 ***
// 測試環境 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(16) 銀行端的訂單編號
若有需求可在此自訂,但不能與之前的重複
若您沒有自訂則會自動幫您產生一組
格式規格請參考 reference
amount int 交易金額,台幣以外金額需包含兩位小數,如 100 代表 1.00
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference
auth_code String(6) 銀行授權碼
card_info JSONObject 卡片資訊,裡面包含以下值:
名稱類別(長度)內容
bin_codeString(6)卡片前六碼
last_fourString(4)卡片後四碼
issuerString發卡銀行
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發卡行國家碼
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
acquirer String 收單銀行 / 金流處理器
transaction_time_millis long 交易時間
bank_transaction_time JSONObject 銀行處理時間
bank_result_code String 銀行錯誤代碼
bank_result_msg String 銀行錯誤訊息
instalment_info JSONObject
名稱類別內容
number_of_instalmentsString分期期數
first_paymentString第一期金額
each_paymentString每一期金額
extra_infoJSONObject各間銀行分期額外參數不同,請參考 extra_info

Refund API

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

名稱(* = 必填) 類別(長度) 內容
partner_key* String(60) 綁定 Portal 帳戶的驗證金鑰
rec_trade_id* String(20) 欲退款的交易字串,任何一筆交易成功時皆會回傳
amount int 退款金額,全額退款可不用填此參數
外幣金額需包含兩位小數,如 100 代表 1.00
部分退款才需要填寫
// *** 格式 ***
// 測試環境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_amount int 退款金額
台幣以外金額需包含兩位小數,如100代表1.00
is_captured boolean 是否已請款
bank_result_code String 銀行錯誤代碼
bank_result_msg String 銀行錯誤訊息
currency String(3) 貨幣種類(ISO 4217)。銀行支援幣別請參考 reference

Record API

此 API 能讓您用您的後台直接進行查詢交易紀錄

名稱 類別(長度) 預設 內容
partner_key String(60) 綁定 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
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 交易紀錄
pay_by_instalment Boolean 是否有使用分期付款
instalment_info JSONObject
名稱類別內容
number_of_instalmentsint分期付款期數
first_paymentint頭期金額
each_paymentint每期金額
currency String(3) 貨幣種類(ISO 4217)。銀行支援幣別請參考 reference