NAV
docs

Server APIs

Overview

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

Pay by Prime API

名稱(* = 必填) 類別(長度) 內容
prime* String(67) 用卡號所換得的字串,由 getPrime 成功時回傳
prime 的時效為 90秒
若您有開啟 Apple Pay 延後授權,請自行保管 Prime(預設 Prime 有效期限為 30 天)
呼叫 Pay By Prime ,您可以在 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
JKOPAYjk_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
merchant_group_id String(50) 於 Portal 設置的商家管理設置,交易時會依據 portal 的支付配置進行交易
不可與 merchant_id 同時使用
amount* int 交易金額。目前支援台幣、港幣、馬幣、美金,台幣以外金額需乘以 100後帶入,各幣別交易金額上限,請參考 reference
merchandise_details JSONObject 交易商品明細
目前只支援 JKOPAY
名稱類別內容
no_rebate_amountInt不適用回饋之金額(例如:煙)
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 持卡人或購買人資訊,裡面應包含以下值。
以下資料將為「詐欺檢測器」,資料越詳細,可獲得越完整的保護
若此筆交易需身份驗證,請詳讀備註中各銀行需驗證的必填欄位,並在對應的參數欄位中帶入正確的值
若無此資料,則該對應的 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是否驗證身分證字號
instalment int(2) 分期付款期數,預設為 0
目前支援:台新銀行, 聯合信用卡中心, 智付通, 國泰世華銀行, 玉山銀行, 中國信託
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY
delay_capture_in_days int 定義交易授權後銀行要過多久才會請款,單位為天
此參數非必要,預設值為0(當天請款)
若您想要自行手動請款,可帶入 -1 表示暫時不請款
* 收單銀行皆設有請款期限,請向您的收單銀行確認。若您採取手動請款模式,請留意如果該筆交易的請款日超過銀行請款期限,可能會導致請款失敗。
three_domain_secure Boolean 是否開啟 3D 驗證,預設為 false
目前支援:台新銀行、中國信託銀行、聯合信用卡處理中心、玉山銀行、永豐(New)、智付通、富邦、MOLPay、彰化銀行

3DS2.0 驗證目前只支援 NCCC AE 卡
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay
result_url JSONObject 使用 LINE Pay, JKOPAY 或 three_domain_secure 為 true 時必填
名稱類別內容
frontend_redirect_urlString前端跳轉 URL,必須以 https 開頭
backend_notify_urlString後端通知 URL,必須以 https 開頭
remember boolean 是否記憶卡號
不支援:Apple Pay, Google Pay, Samsung Pay, JKOPAY
LINE Pay 交易 remember : true 時,只支援使用 POINT 與信用卡
redeem boolean 是否為紅利折抵。
目前支援:聯合信用卡中心
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY
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, JKOPAY
card_secret JSONObject 卡片保管資訊。不支援:Apple Pay, Google Pay, Samsung Pay, JKOPAY
如果呼叫時 remember = false 則不會回傳此物件

透過 LINE Pay 獲得的 card key 與 card token,若在 180 天內無成功交易,將會過期導致交易失敗

裡面包含以下值:
名稱類別(長度)內容
card_tokenString(67)卡片識別字串,以後需用此參數在 Pay by Card Token 直接交易
card_keyString(64)卡片安全金鑰,以後需用此參數在 Pay by Card Token 直接交易
amount int 交易金額,台幣以外金額需乘以 100,如港幣(HKD) 1元代表 100
currency String(3) 貨幣種類,銀行支援幣別請參考reference
不支援: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 銀行錯誤訊息
payment_url String 付款頁面網址,將此網址回傳至前端跳轉
不支援:Apple Pay, Google Pay, Samsung Pay
instalment_info JSONObject 非 3D 驗證交易,且使用分期付款時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY
名稱類別內容
number_of_instalmentsint分期期數
first_paymentint第一期金額
each_paymentint每一期金額
extra_infoJSONObject各間銀行分期額外參數不同,請參考 extra_info
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 功能,且交易卡號符合設定時,將會回傳此參數,不支援 JKOPAY

商戶於TapPay後台設定的affiliate code management須限制於20字元內且為半形的英數字
名稱類別內容
affiliate_codesArray商戶在 TapPay 後台的 Co-brand card management 功能專區設定的Affiliated codes

Refund API

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

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

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