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

Pay by Card Token API

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

名稱(* = 必填) 類別(長度) 內容
card_key* String(64) 卡片安全金鑰
Pay by Prime 取得
card_token* String(64) 卡片識別字串
Pay by Prime 取得
partner_key* String(64) 綁定 Portal 帳戶的驗證金鑰
merchant_id* String(50) 於 Portal 登錄商家時所產生的識別碼
amount* int 交易金額。目前支援台幣、港幣、馬幣,台幣以外金額需乘以 100後帶入,各幣別交易金額上限,請參考 reference
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
bank_transaction_id String(40) 銀行端的訂單編號
強烈建議商戶可在此自訂,但不能與之前的重複;若您沒有自訂則會自動幫您產生一組。
但若您沒自訂,當發生421 Gateway 操作逾時(發生機率低),則無法反查該筆交易
(格式規格請參考備註 reference)
details* String(100) 交易品項內容,為符合 PCI 要求至少必須要有品項名稱
我們的詐欺檢測器將會以此作為詐欺判定的基準,所以建議您填寫的資訊能越詳細越好
銀行儲存格式規格請參考 reference
若您啟用TSP服務,且收單銀行為台新銀行,請務必填入交易品項內容; 若沒帶入,TapPay將預設該值為交易序號以避免交易失敗
instalment int(2) 分期付款期數,預設為 0
目前支援:台新銀行, 聯合信用卡中心, 智付通, 國泰世華銀行, 玉山銀行, 中國信託
不支援: Apple Pay Google Pay LINE Pay Samsung Pay
delay_capture_in_days int 定義交易授權後銀行要過多久才會請款,單位為天
此參數非必要,預設值為0(當天請款)
若您想要自行手動請款,可帶入 -1 表示暫時不請款
* 收單銀行皆設有請款期限,請向您的收單銀行確認。若您採取手動請款模式,請留意如果該筆交易的請款日超過銀行請款期限,可能會導致請款失敗。
three_domain_secure Boolean 是否開啟 3D 驗證,預設為 false
目前支援:台新銀行、中國信託銀行、聯合信用卡處理中心、玉山銀行、永豐(New)、智付通、富邦、MOLPay
不支援: Apple Pay Google Pay LINE Pay Samsung Pay
result_url JSONObject three_domain_secure 為 true 時必填
名稱類別內容
frontend_redirect_urlString前端跳轉 URL,必須以 https 開頭
backend_notify_urlString後端通知 URL,必須以 https 開頭
fraud_id String 偽卡交易識別碼,若您想要開啟偽卡偵測才需要帶
card_ccv String 卡片的後三碼,若您想要銀行驗證此參數才需要帶
redeem boolean 是否為紅利折抵,目前僅支援聯合信用卡中心
// *** 格式 ***
// 測試環境 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(40) 銀行端的訂單編號
若有需求可在此自訂,但不能與之前的重複
若您沒有自訂則會自動幫您產生一組
格式規格請參考 reference
amount int 交易金額,台幣以外金額需乘以 100,如港幣(HKD) 1元代表 100
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference
auth_code String(6) 銀行授權碼
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
(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 付款頁面網址,將此網址回傳至前端跳轉
instalment_info JSONObject 非 3D 驗證交易,且使用分期付款時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay
名稱類別內容
number_of_instalmentsString分期期數
first_paymentString第一期金額
each_paymentString每一期金額
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 信用卡識別碼。每張信用卡只會對到一組識別碼。
merchant_reference_info JSON 若商戶在 LINE Pay 或 TapPay 後台使用 Co-brand card management 功能,且交易卡號符合設定時,將會回傳此參數
名稱類別內容
affiliate_codesArray商戶在 LINE Pay 或 TapPay 後台的 Co-brand card management 功能專區設定的Affiliated codes

Frontend Redirect

  1. LINE Pay 交易完成後,TapPay 會幫您 redirect 到您於 Pay by Prime 設定的 frontend_redirect_url 的地方去 TapPay 會帶四個交易完成的參數

  2. 3D驗證交易完成後,TapPay 會幫您 redirect 到您於 Pay by Prime / Pay by Token 設定的 frontend_redirect_url 的地方去 TapPay 會帶四個交易完成的參數

Request Header

Key Value
Content-Type html/text

Request Url

https://your.domain.com/transaction_is_done?
rec_trade_id=LN20171109WsvKhn&
order_number=CF46019917&
status=0&
bank_transaction_id=TP20171109WsvKhn

Request Query String

名稱 類別 內容
rec_trade_id String 交易識別碼
order_number String 自定義訂單編號
bank_transaction_id String 銀行端的訂單編號。
強烈建議商戶可在此自訂,但不能與之前的重複;若您沒有自訂則會自動幫您產生一組。
但若您沒自訂,當發生421 Gateway 操作逾時(發生機率低),則無法反查該筆交易(格式規格請參考備註reference)
status Int 交易代碼,成功為 0

前端跳轉資料可能被偽造,建議您實做後端通知,若後端通知失敗請使用 Record API 進行反查詢

Backend Notify

  1. LINE Pay 交易完成後,透過 pay by prime 設定 backend_notify_url 會發一個 POST 到 backend_notify_url 進行通知

  2. 3D驗證交易完成後,透過 pay by prime / pay by token 設定 backend_notify_url 會發一個 POST 到 backend_notify_url 進行通知

Request Header

Key Value
Content-Type application/json

Request Url

Type Method : POST
Sandbox https://{backend_notify_url}
Production https://{backend_notify_url}

Request Body

名稱 類別 內容
rec_trade_id String 由 TapPay 伺服器產生的交易識別字串
將於查詢交易、退款時使用,請妥善保管
auth_code String 銀行授權碼。3D驗證交易時,才會回傳此欄位
bank_transaction_id String 銀行端訂單編號
order_number String 您自定義的訂單編號,用於 TapPay 做訂單識別
amount Int 金額
status Int 交易代碼,成功為 0
msg String 交易訊息
transaction_time_millis Long Int 交易時間
pay_info JSONObject 若此交易使用 LINE Pay 時,由 LINE Pay 回傳訊息
名稱類別內容
methodString交易方式
1. CREDIT_CARD(信用卡)
2. BALANCE(一卡通 iPASS)
3. POINT (LINE Point 全額折抵)
masked_credit_card_numberString遮蔽後的卡片末四碼
pointInt點數折抵金額,若無折抵則為 0
acquirer String 收單銀行 / 金流處理器
card_identifier String 信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援:LINE Pay
bank_result_code String 由銀行回傳的程式碼
bank_result_msg String 由銀行回傳的訊息
merchant_reference_info JSON 若商戶在 LINE Pay 或 TapPay 後台使用 Co-brand card management 功能,且交易卡號符合設定時,將會回傳此參數
名稱類別內容
affiliate_codesArray商戶在 LINE Pay 或 TapPay 後台的 Co-brand card management 功能專區設定的Affiliated codes
instalment_info JSONObject 若有使用分期付款時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay
名稱類別內容
number_of_instalmentsint分期期數
first_paymentint第一期金額
each_paymentint每一期金額
extra_infoJSONObject各間銀行分期額外參數不同,請參考 extra_info
redeem_info JSONObject 若有使用紅利時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay
名稱類別內容
used_pointString紅利折抵點數
balanceString紅利餘額
offset_amountString紅利折抵金額
due_amountString折抵後自付金額
extra_infoJSONObject各間銀行紅利額外參數不同,請參考 extra_info
{
    // Example
    "amount": 1,
    "order_number": "KK44845743",
    "status": 0,
    "bank_transaction_id": "TP201711088cHQHr",
    "transaction_time_millis": 1510136365539,
    "acquirer": "TW_LINE_PAY",
    "msg": "Success",
    "rec_trade_id": "LN201711088cHQHr",
    "pay_info": {
        "point": 0,
        "masked_credit_card_number": "************2178",
        "method": "CREDIT_CARD"
    }
}

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 交易紀錄