Server APIs

String(50)

您自定義的訂單編號，用於 TapPay 做訂單識別，可重複帶入
格式請參考 reference。若有帶入此欄位，則不能為空

String(40)

銀行端的訂單編號
強烈建議商戶可在此自訂，但不能與之前的重複；若您沒有自訂則會自動幫您產生一組。
但若您沒自訂，當發生421 Gateway 操作逾時（發生機率低），則無法反查該筆交易
(格式規格請參考備註 reference)

details*

String(100)

交易品項內容，為符合 PCI 要求至少必須要有品項名稱
我們的詐欺檢測器將會以此作為詐欺判定的基準，所以建議您填寫的資訊能越詳細越好
銀行儲存格式規格請參考 reference
若您啟用TSP服務，且收單銀行為台新銀行，請務必填入交易品項內容; 若沒帶入，TapPay將預設該值為交易序號以避免交易失敗
若您的收單銀行為藍新金流或支付方式為LINE Pay, Atome，此欄位須填入值，否則會導致交易失敗

cardholder*

JSONObject

持卡人或購買人資訊，裡面應包含以下值。
以下資料將為「詐欺檢測器」，資料越詳細，可獲得越完整的保護
若此筆交易需身份驗證，請詳讀備註中各銀行需驗證的必填欄位，並在對應的參數欄位中帶入正確的值
若無此資料，則該對應的 Key 值，可以帶空字串，(如：zip_code: “”)

名稱(*為必填)	類別(長度)	內容
phone_number*	String(40)	手機號碼，可為 09 開頭的電話或是包含加號之 E.164 格式(“+886923456789”)
name*	String(40)	姓名
email*	String(40)	電子信箱
zip_code	String(40)	郵遞區號
address	String(90)	地址
national_id	String(40)	身份證字號
member_id	String(64)	持卡人或購買人會員編號。用於 TapPay 詐欺檢測、會員資料管理時使用。支援 : Direct Pay

cardholder_verify

JSONObject

身份驗證欄位，請注意：若此筆交易需身份驗證，請詳讀備註中各銀行需驗證的必填欄位，若該欄位為 “true” ，則會將 cardholder 欄位對應之資訊送至收單機構進行身份驗證。

若要進行兩段式身份驗證，務必於 kyc_verification_merchant_id 填入您於Portal的商家管理 > KYC 驗證商家設置的merchant ID

如使用 AE 卡進行驗證，將會扣除 1 元，並於兩週內會退還。
您可以在 sandbox 環境中使用備註中的測試用身分證字號及電話號碼
支援: Direct Pay
有以下兩種使用情境

使用情境說明	支援身份驗證收單銀行	支援授權收單銀行	支援程度	注意事項
身份驗證及授權皆可使用同一 merchant id 完成	財團法人聯合信用卡處理中心	財團法人聯合信用卡處理中心	所有發卡行	無法做電話號碼驗證，可參考備註
	台新銀行	台新銀行	所有發卡行
	玉山銀行	玉山銀行	自行卡	無法做電話號碼驗證，可參考備註
兩段式身份驗證（身份驗證跟授權不同收單）	財團法人聯合信用卡處理中心	所有TapPay支援的銀行	所有發卡行
兩段式身份驗證（身份驗證跟授權不同收單）	TapPay 身份驗證	所有TapPay支援的銀行	所有國內發卡行（Visa, MasterCard, JCB）	無法做身分證字號驗證，可參考備註

驗證欄位

名稱	類型(長度)	內容
phone_number	Boolean	是否驗證電話號碼
national_id	Boolean	是否驗證身分證字號

kyc_verification_merchant_id

String

此欄位請填入僅供身份驗證，無授權功能的merchant ID。
支援產業：電支產業/ 產壽險業

instalment

int(2)

分期付款期數，預設為 0
目前支援: 台新銀行, 財團法人聯合信用卡處理中心, 藍新金流, 國泰世華銀行, 玉山銀行, 中國信託銀行, 環匯亞太, 聯邦銀行
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
由於 Atome 不可選擇分期期數，結帳時 Atome 即自動分成三期，故此欄位不支援 Atome

delay_capture_in_days

int

定義交易授權後銀行要過多久才會請款，單位為天
此參數非必要，預設值為0(當天請款)
若您想要自行手動請款，可帶入 -1 表示暫時不請款
* 收單銀行皆設有請款期限，請向您的收單銀行確認。若您採取手動請款模式，請留意如果該筆交易的請款日超過銀行請款期限，可能會導致請款失敗。

three_domain_secure

Boolean

是否開啟 3D 驗證，預設為 false
目前支援: 台新銀行、中國信託銀行、財團法人聯合信用卡處理中心、玉山銀行、永豐(New)、藍新金流、富邦、RAZER PAY、彰化銀行、國泰世華銀行、聯邦銀行
3DS2.0 驗證目前只支援AE 卡交易且收單行為財團法人聯合信用卡處理中心
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

result_url

JSONObject

使用 LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付或 three_domain_secure 為 true 時必填

名稱	類別	內容
frontend_redirect_url	String	使用 LINE Pay、街口支付、悠遊付、Atome、Pi錢包、全盈支付或者 3D 驗證交易時，當消費者在 LINE Pay、街口支付、悠遊付、Atome、Pi錢包、全盈支付或 3D 驗證完成交易程序後，導轉回到商戶網頁前端的交易結果頁面 URL。必須以 https 開頭。
backend_notify_url	String	商戶 Server 接收交易結果的 URL。必須以 https 開頭，僅支援 443 port。
go_back_url	String	3D 驗證交易時，當消費者因不當操作而被導到 TapPay Error 頁面時，頁面上「Go back」按鈕連結。此情境僅會發生於玉山銀行, 國泰世華銀行, 台新銀行。若您在交易的 Request 中有定義此參數，則消費者按下 Go back按鈕後，會導到您所指定的 URL；亦可於TapPay Portal > 開發人員內容 > 系統設定 > 跳轉連結設定設定 Go back 按鈕指向的 URL。強烈建議您在 3D 交易時定義這個欄位，避免消費者被導轉到交易錯誤頁面時，無法回到商家頁面完成交易或查看交易結果。建議您此 URL 可以設定為商家首頁或是購物車頁面

remember

boolean

是否記憶卡號
不支援: Apple Pay, Google Pay, Samsung Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
LINE Pay 交易 remember: true 時，只支援使用 POINT 與信用卡

redeem

boolean

是否為紅利折抵。
目前支援: 財團法人聯合信用卡處理中心
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

additional_data

JSONString(3000)

資料會加密保存，並在其他客製化需求時才解密做使用

event_code

String(50)

與銀行或錢包合作之活動中，雙方協議的指定活動代碼。支援 : 悠遊付

product_image_url

String(500)

交易付款頁面上所顯示的商品或商家圖片。此欄位等同於line_pay_product_image_url, 若您於呼叫時同時帶入 product_image_url 與line_pay_product_image_url，TapPay 將以product_image_url 欄位的內容為主。格式規格請參考備註 reference

jko_pay_insurance_policy

StringArray

街口支付產壽險交易，保單明細
支援: JKOPAY
當使用 JKOPAY 進行產壽險交易時，以下欄位皆為必填

名稱	類別(長度)	內容
proposer	String(10)	要保人的身分證字號或居留證
insured	StringArray	被保人的身分證字號或居留證
insurance_type	String	險種。詳細參數規格，請參考 Reference
policy_id	String(60)	保單識別碼。保險公司自定義
payment_deadline	Long	保單繳費期限
payment_frequency	Int	繳別。詳細參數規格，請參考 Reference
final_price	Int	保單金額。所有保單金額的加總，應該等於 Pay by Prime Request 中的 amount 金額

extra_info

JSONObject

額外資訊
支援: Atome

名稱	類別(長度)	內容
shopper_info	JSONObject	消費者資訊

// *** 格式 ***
// 測試環境 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

名稱

類別(長度)

內容

int

交易代碼，成功的話為0

String

錯誤訊息

rec_trade_id

String(20)

由 TapPay 伺服器產生的交易字串
將於退款時用到，請妥善保管

String(40)

銀行端的訂單編號
強烈建議商戶可在此自訂，但不能與之前的重複；若您沒有自訂則會自動幫您產生一組。
但若您沒自訂，當發生421 Gateway 操作逾時（發生機率低），則無法反查該筆交易
格式規格請參考 reference

bank_order_number

String

銀行或錢包端於授權時回傳的訂單編號
支援：悠遊付, Pi錢包
各支援銀行或錢包回傳長度限制，請參考 Reference

auth_code

String(6)

銀行授權碼，不支援:LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

card_secret

JSONObject

卡片保管資訊。不支援:Apple Pay, Google Pay, Samsung Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付
如果呼叫時 remember = false 則不會回傳此物件

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

裡面包含以下值：

名稱	類別(長度)	內容
card_token	String(67)	卡片識別字串，以後需用此參數在 Pay by Card Token 直接交易
card_key	String(64)	卡片安全金鑰，以後需用此參數在 Pay by Card Token 直接交易

int

交易金額，台幣以外金額需乘以 100，如港幣(HKD) 1元代表 100

currency

String(3)

貨幣種類，銀行支援幣別請參考reference
不支援:LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

card_info

JSONObject

卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

名稱	類別(長度)	內容
bin_code	String(6)	卡片前六碼
last_four	String(4)	卡片後四碼
issuer	String	發卡銀行
issuer_zh_tw	String	發卡銀行中文名稱
bank_id	String	發卡銀行代碼
funding	int	卡片類別 -1 = Unknown 0 = 信用卡 (Credit Card) 1 = 簽帳卡 (Debit Card) 2 = 預付卡 (Prepaid Card)
type	int	卡片種類 -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX
level	String	卡片等級
country	String	發卡行國家
country_code	String	發卡行國家碼
expiry_date	String	卡片到期時間，格式 YYYYMM，( remember = true 時回傳) (Apple Pay / Google Pay / LINE Pay / Samsung Pay / Atome / Pi錢包 / 全盈支付不會回傳此欄位)

String(50)

您自定義的訂單編號，用於 TapPay 做訂單識別，可重複帶入
格式請參考 reference

acquirer

String

收單銀行 / 金流處理器

transaction_time_millis

long

交易時間

bank_transaction_time

JSONObject

銀行處理時間

bank_result_code

String(40)

銀行回傳的交易結果代碼

bank_result_msg

String(300)

銀行回傳的交易結果訊息

payment_url

String

付款頁面網址，將此網址回傳至前端跳轉
不支援:Apple Pay, Google Pay, Samsung Pay

instalment_info

JSONObject

非 3D 驗證交易，且使用分期付款時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

名稱	類別	內容
number_of_instalments	int	分期期數
first_payment	int	第一期金額
each_payment	int	每一期金額
extra_info	JSONObject	各間銀行分期額外參數不同，請參考 extra_info

redeem_info

JSONObject

非 3D 驗證交易，且使用紅利折抵時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

名稱	類別	內容
used_point	String	紅利折抵點數
balance	String	紅利餘額
offset_amount	String	紅利折抵金額
due_amount	String	折抵後自付金額
extra_info	JSONObject	各間銀行紅利額外參數不同，請參考 extra_info

card_identifier

String

不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付
信用卡識別碼。每張信用卡只會對到一組識別碼。

merchant_reference_info

JSON

商戶參考資訊

名稱	類別	內容
affiliate_codes	Array	商戶於 TapPay 後台或第三方合作方設定之聯名卡資訊，當交易符合設定時才會回傳，不支援 LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

event_code

String(50)

與銀行或錢包合作之活動中，雙方協議的指定活動代碼。支援 : 悠遊付

is_rba_verified

Boolean

該交易有無取得 RBA 評估的風險分數RBA 可以為每筆交易評估風險，以辨認和防止偽冒交易發生。該產品即將上線，您可以參考 TapPay 官網更了解 RBA 這項服務。

transaction_method_details

JSONObject

交易方式細節
RBA 可以為每筆交易評估風險，以辨認和防止偽冒交易發生。該產品即將上線，您可以參考 TapPay 官網更了解 RBA 這項服務。

名稱	類別	內容
transaction_method	String	THREE_DOMAIN_SECURE: 表示訂單以 3D 驗證的規格送往銀行做交易 FRICTIONLESS: 表示訂單以一般授權的規格送往銀行做交易
transaction_method_reference	String	RBA : 該訂單最後的交易方式，是由 RBA 風險分數規則決定 REQUEST : 訂單最後的交易方式，是由商戶交易時帶來的 Request 規格決定

Pay by Card Token API

非3D驗證交易流程
3D驗證交易流程

當您要進行3D驗證交易，請在Request欄位中的three_domain_secure帶入true，且在result_url的frontend_redirect_url與backend_notify_url分別帶入對應的值。

由於尖峰時段銀行方面可能會花較久時間處理，因此請將 timeout 時間設定為 30 秒以避免交易資訊不同步
若在呼叫 Pay by Prime API 時，若將 remember 設為 true 記憶卡號，則會獲得 card_key 和 card_token，以後即可省去 createToken 這個步驟並改為呼叫 Pay by Card Token 來進行交易。亦可使用 card_key 和 card_token 來進行定期定額扣款，存下此兩個參數後，即可定期呼叫 Pay by Card Token 進行定期定額扣款，且呼叫的週期與金額可自行決定。

名稱(* = 必填)

類別(長度)

內容

card_key*

String(64)

卡片安全金鑰
由 Pay by Prime 取得

card_token*

String(67)

卡片識別字串
由 Pay by Prime 取得

partner_key*

String(64)

綁定 Portal 帳戶的驗證金鑰

merchant_id*

String(50)

於 Portal 登錄商家時所產生的識別碼

merchant_group_id

String(50)

於 Portal 設置的商家管理設置，交易時會依據 portal 的支付配置進行交易
不可與 merchant_id 同時使用

amount*

int

交易金額。目前支援台幣、港幣、馬幣、美金，台幣以外金額需乘以 100後帶入，各幣別交易金額上限，請參考 reference

currency*

String(3)

貨幣種類，銀行支援幣別請參考 reference

String(50)

您自定義的訂單編號，用於 TapPay 做訂單識別，可重複帶入
格式請參考 reference。若有帶入此欄位，則不可為空

String(40)

details*

String(100)

交易品項內容，為符合 PCI 要求至少必須要有品項名稱
我們的詐欺檢測器將會以此作為詐欺判定的基準，所以建議您填寫的資訊能越詳細越好
銀行儲存格式規格請參考 reference
若您啟用TSP服務，且收單銀行為台新銀行，請務必填入交易品項內容; 若沒帶入，TapPay將預設該值為交易序號以避免交易失敗
若您的收單銀行為藍新金流或支付方式為LINE Pay，此欄位須填入值，否則會導致交易失敗

cardholder_verify

JSONObject

使用情境說明	支援身份驗證收單銀行	支援授權收單銀行	支援程度	注意事項
身份驗證及授權皆可使用同一 merchant id 完成	財團法人聯合信用卡處理中心	財團法人聯合信用卡處理中心	所有發卡行	無法做電話號碼驗證，可參考備註
	台新銀行	台新銀行	所有發卡行
	玉山銀行	玉山銀行	自行卡	無法做電話號碼驗證，可參考備註
兩段式身份驗證（身份驗證跟授權不同收單）	財團法人聯合信用卡處理中心	所有TapPay支援的銀行	所有發卡行
兩段式身份驗證（身份驗證跟授權不同收單）	TapPay 身份驗證	所有TapPay支援的銀行	所有國內發卡行（Visa, MasterCard, JCB）	無法做身分證字號驗證，可參考備註

驗證欄位

名稱	類型(長度)	內容
phone_number	Boolean	是否驗證電話號碼
national_id	Boolean	是否驗證身分證字號

kyc_verification_merchant_id

String

此欄位請填入僅供身份驗證，無授權功能的merchant ID。
支援產業：電支產業/ 產壽險業

instalment

int(2)

分期付款期數，預設為 0
目前支援: 台新銀行, 財團法人聯合信用卡處理中心, 藍新金流, 國泰世華銀行, 玉山銀行, 中國信託銀行, 環匯亞太, 聯邦銀行
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

delay_capture_in_days

int

three_domain_secure

Boolean

是否開啟 3D 驗證，預設為 false
目前支援:台新銀行、中國信託銀行、財團法人聯合信用卡處理中心、玉山銀行、永豐(New)、藍新金流、富邦、RAZER PAY、彰化銀行、國泰世華銀行、聯邦銀行

3DS2.0 驗證目前只支援AE 卡交易且收單行為財團法人聯合信用卡處理中心
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

result_url

JSONObject

three_domain_secure 為 true 時必填
不支援: Apple Pay, Google Pay, LINE Pay, Samsung Pay

名稱	類別	內容
frontend_redirect_url	String	使用 LINE Pay、街口支付、悠遊付, Atome, Pi 錢包, 全盈支付或者 3D 驗證交易時，當消費者在 LINE Pay、街口支付、悠遊付、Atome、Pi 錢包、全盈支付或 3D 驗證完成交易程序後，導轉回到商戶網頁前端的交易結果頁面 URL。必須以 https 開頭。
backend_notify_url	String	商戶 Server 接收交易結果的 URL。必須以 https 開頭，僅支援 443 port。
go_back_url	String	3D 驗證交易時，當消費者因不當操作而被導到 TapPay Error 頁面時，頁面上「Go back」按鈕連結。此情境僅會發生於玉山銀行, 國泰世華銀行, 台新銀行。若您在交易的 Request 中有定義此參數，則消費者按下 Go back按鈕後，會導到您所指定的 URL；亦可於TapPay Portal > 開發人員內容 > 系統設定 > 跳轉連結設定設定 Go back 按鈕指向的 URL。強烈建議您在 3D 交易時定義這個欄位，避免消費者被導轉到交易錯誤頁面時，無法回到商家頁面完成交易或查看交易結果。建議您此 URL 可以設定為商家首頁或是購物車頁面

card_ccv

String

信用卡安全碼。不可與ccv_prime 同時帶入
當有以下情況時請帶入此參數
1. 未在get-ccv-prime 時取得ccv_prime但想要銀行驗證此參數
2. 未在get-ccv-prime 時取得ccv_prime但使用 AE 卡進行3DS2.0 驗證交易時
不支援LINE Pay, Easy Wallet, Atome, Pi 錢包, 全盈支付

redeem

boolean

是否為紅利折抵。
目前支援: 財團法人聯合信用卡處理中心
不支援 : Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

additional_data

JSONString(3000)

資料會加密保存，並在其他客製化需求時才解密做使用

ccv_prime

String

用信用卡安全碼所換得的字串，由 get-ccv-prime 成功時回傳
不可與card_ccv 同時帶入ccv_prime 的時效為 90秒
支援 : Direct Pay
您可以在 sandbox 環境中使用此測試用
ccv_prime(3碼) : test_65b1ca2d5d0dc8ff5b62296ea8547bab08401f8a57015fb818c5bcd10433fa11
ccv_prime(4碼) : test_cd1e737890874cdadf39caaf56c5b183c36a4117ca89cb24fd674c0892e0fa92

device_id

String(64)

裝置識別碼。若您有使用 TapPay RBA 交易風險評估服務，才需要帶此參數。
有使用 TapPay RBA 交易風險評估服務時，在呼叫 Pay by Card Token API 前，須先呼叫 SDK 的 Get Device ID 方法，並把取得的 Device ID 放入 Pay by Card Token Request 中的 device_id 欄位。

// *** 格式 ***
// 測試環境 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

名稱

類別(長度)

內容

int

交易代碼，成功的話為0

String

錯誤訊息

rec_trade_id

String(20)

由 TapPay 伺服器產生的交易字串
將於退款時用到，請妥善保管

String(40)

銀行端的訂單編號
若有需求可在此自訂，但不能與之前的重複
若您沒有自訂則會自動幫您產生一組
格式規格請參考 reference

bank_order_number

String

銀行或錢包端於授權時回傳的訂單編號
支援：悠遊付
各支援銀行或錢包回傳長度限制，請參考 Reference

int

交易金額，台幣以外金額需乘以 100，如港幣(HKD) 1元代表 100

currency*

String(3)

貨幣種類，銀行支援幣別請參考 reference

auth_code

String(6)

銀行授權碼，不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

card_info

JSONObject

卡片資訊。不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

名稱	類別(長度)	內容
bin_code	String(6)	卡片前六碼
last_four	String(4)	卡片後四碼
issuer	String	發卡銀行
issuer_zh_tw	String	發卡銀行中文名稱
bank_id	String	發卡銀行代碼
funding	int	卡片類別 -1 = Unknown 0 = 信用卡 (Credit Card) 1 = 簽帳卡 (Debit Card) 2 = 預付卡 (Prepaid Card)
type	int	卡片種類 -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX
level	String	卡片等級
country	String	發卡行國家
country_code	String	發卡行國家碼
expiry_date	String	卡片到期時間，格式 YYYYMM (Apple Pay / Google Pay / LINE Pay / Samsung Pay / Atome / Pi 錢包 / 全盈支付不會回傳此欄位)

String(50)

您自定義的訂單編號，用於 TapPay 做訂單識別，可重複帶入
格式請參考 reference

acquirer

String

收單銀行 / 金流處理器

transaction_time_millis

long

交易時間

bank_transaction_time

JSONObject

銀行處理時間

bank_result_code

String(40)

銀行回傳的交易結果代碼

bank_result_msg

String(300)

銀行回傳的交易結果訊息

payment_url

String

付款頁面網址，將此網址回傳至前端跳轉
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

instalment_info

JSONObject

非 3D 驗證交易，且使用分期付款時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

名稱	類別	內容
number_of_instalments	int	分期期數
first_payment	int	第一期金額
each_payment	int	每一期金額
extra_info	JSONObject	各間銀行分期額外參數不同，請參考 extra_info

redeem_info

JSONObject

非 3D 驗證交易，且使用紅利折抵時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

名稱	類別	內容
used_point	String	紅利折抵點數
balance	String	紅利餘額
offset_amount	String	紅利折抵金額
due_amount	String	折抵後自付金額
extra_info	JSONObject	各間銀行紅利額外參數不同，請參考 extra_info

card_identifier

String

信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

merchant_reference_info

JSON

商戶參考資訊

名稱	類別	內容
affiliate_codes	Array	商戶於 TapPay 後台或第三方合作方設定之聯名卡資訊，當交易符合設定時才會回傳，不支援 LINE Pay, JKOPAY, 悠遊付, Atome, Pi 錢包, 全盈支付

is_rba_verified

Boolean

transaction_method_details

JSONObject

交易方式細節
RBA 可以為每筆交易評估風險，以辨認和防止偽冒交易發生。該產品即將上線，您可以參考 TapPay 官網更了解 RBA 這項服務。

名稱	類別	內容
transaction_method	String	THREE_DOMAIN_SECURE: 表示訂單以 3D 驗證的規格送往銀行做交易 FRICTIONLESS: 表示訂單以一般授權的規格送往銀行做交易
transaction_method_reference	String	RBA : 該訂單最後的交易方式，是由 RBA 風險分數規則決定 REQUEST : 訂單最後的交易方式，是由商戶交易時帶來的 Request 規格決定

Frontend Redirect

LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付交易完成後，TapPay 會幫您 redirect 到您於 Pay by Prime 設定的 frontend_redirect_url 的地方去 TapPay 會帶四個交易完成的參數
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

LINE Pay, JKOPAY, 悠遊付 Atome, Pi錢包, 全盈支付交易完成後，透過 pay by prime 設定 backend_notify_url 會發一個 POST 到 backend_notify_url 進行通知
3D驗證交易完成後，透過 pay by prime / pay by token 設定 backend_notify_url 會發一個 POST 到 backend_notify_url 進行通知
若未成功接收到Backend Notify，TapPay將每隔1, 2, 4, 8,16分鐘後再度重送，最多重送五次。若都接收失敗，則會寄發通知信件至聯絡人信箱及技術聯絡人信箱。再請您依照信件指示確認訂單的最新狀態，以免發生交易狀態不一致的問題。

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

銀行授權碼，不支援: LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

String

銀行端訂單編號

bank_order_number

String

銀行或錢包端於授權時回傳的訂單編號
支援：悠遊付
各支援銀行或錢包回傳長度限制，請參考 Reference

String

您自定義的訂單編號，用於 TapPay 做訂單識別。若有帶入此欄位，則不能為空

Int

金額

Int

交易代碼，成功為 0

String

交易訊息

transaction_time_millis

Long

交易時間

pay_info

JSONObject

若此交易使用 LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付時回傳訊息
Atome 只能綁定銀行帳戶和 debit card，所以 pay_info 中只有 bank_account 會有值

名稱	類別	內容
method	String	交易方式，只限LINE Pay 交易時回傳 1. CREDIT_CARD(信用卡) 2. BALANCE(一卡通 iPASS) 3. POINT (LINE Point 全額折抵) 4. DISCOUNT(LINE Pay 優惠券)
masked_credit_card_number	String	遮蔽後的卡片末四碼此欄位僅限LINE Pay，全盈支付交易回傳。若需要須先跟全盈支付申請開通
credit_card	Int	使用信用卡支付金額。若無使用此支付方式會顯示為 0
balance	Int	使用錢包儲值帳戶支付金額。若無使用此支付方式，會顯示為 0
bank_account	Int	使用銀行連結帳戶支付金額。若無使用此支付方式，會顯示為 0
point	Int	LINE Point, 街口幣, 全盈支付折抵金額。若無折抵則為 0
discount	Int	LINE Pay 折扣碼折抵金額
bin_code	String	卡片前6碼或8碼。全盈支付交易回傳。若需要須先跟全盈支付申請開通

e_invoice_carrier

JSONObject

電子發票載具資料
目前僅支援 : JKOPAY, 全盈支付

名稱	類別	內容
type	Int(3)	0:手機條碼 1:自然人憑證條碼 2:其他載具條碼
number	String(100)	電子發票載具號碼
donation	Boolean	是否捐贈
donation_id	String(50)	愛心碼

acquirer

String

收單銀行 / 金流處理器

card_identifier

String

信用卡識別碼。每張信用卡只會對到一組識別碼。
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

bank_result_code

String(40)

銀行回傳的交易結果代碼

bank_result_msg

String(300)

銀行回傳的交易結果訊息

merchant_reference_info

JSON

商戶參考資訊

名稱	類別	內容
affiliate_codes	Array	商戶於 TapPay 後台或第三方合作方設定之聯名卡資訊，當交易符合設定時才會回傳，不支援 LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包

instalment_info

JSONObject

若有使用分期付款時回傳
不支援:Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

名稱	類別	內容
number_of_instalments	int	分期期數
first_payment	int	第一期金額
each_payment	int	每一期金額
extra_info	JSONObject	各間銀行分期額外參數不同，請參考 extra_info

redeem_info

JSONObject

非 3D 驗證交易，且使用紅利折抵時回傳
不支援: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付

名稱	類別	內容
used_point	String	紅利折抵點數
balance	String	紅利餘額
offset_amount	String	紅利折抵金額
due_amount	String	折抵後自付金額
extra_info	JSONObject	各間銀行紅利額外參數不同，請參考 extra_info

event_code

String(50)

與銀行或錢包合作之活動中，雙方協議的指定活動代碼。支援 : 悠遊付

merchandise_details

JSONObject

交易商品明細
目前只支援 JKOPAY 悠遊付 Atome 全盈支付

名稱	類別	內容
no_rebate_amount	Int	不適用回饋之金額(例如：煙)
no_bonus_amount	Int	不適用贈送之金額(例如：煙)

{
    // 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 秒以避免交易資訊不同步
當您呼叫此 API 時，TapPay 將於當日向銀行進行退款，不代表當日退款已成功。
實際退款是否成功，請於退款隔天利用 TapPay 後台或 Record API 查詢交易狀態進行確認。
為確保交易狀態一致，當銀行/錢包在請款中不支援取消授權，需等TapPay收到銀行回覆（時間請參考Each bank capture time），確認該筆交易狀態後才能進行後續動作

名稱(* = 必填)

類別(長度)

內容

partner_key*

String(64)

綁定 Portal 帳戶的驗證金鑰

rec_trade_id*

String(20)

欲退款的交易字串，任何一筆交易成功時皆會回傳

bank_refund_id

String(20)

商戶定義的退款紀錄識別碼(需為半形的英數字)，不可重複。
支援：玉山銀行, Atome

int

退款金額，全額退款可不用填此參數
外幣金額需包含兩位小數，如 100 代表 1.00
部分退款才需要填寫

additional_data

JSONString(3000)

資料會加密保存，並在其他客製化需求時才解密做使用。

merchandise_details

JSONObject

交易商品明細，目前只支援悠遊付

名稱	類別(長度)	內容
no_rebate_amount	int	不適用回饋之金額(例如：煙)

// *** 格式 ***
// 測試環境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

名稱

類別

內容

int

交易代碼，成功的話為0