NAV
docs

Server APIs

Overview

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

Pay by Prime

名稱(* = 必填) 類別(長度) 內容
prime* String(67) getPrime 成功時回傳 , 您可以在 sandbox 環境中使用此測試用prime
prime : ln_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
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: “”)
result_url* JSONObject
名稱類別內容
frontend_redirect_urlString前端跳轉 URL,必須以 https 開頭
backend_notify_urlString後端通知 URL,必須以 https 開頭
delay_capture_in_days int 定義交易授權後銀行要過多久才會請款,單位為天
此參數非必要,預設值為0(當天請款)
若您想要自行手動請款,可帶入 -1 表示暫時不請款
remember boolean 是否記憶卡號,Apple Pay, Google Pay, Samsung Pay, LINE Pay 不用填寫
line_pay_product_image_url String (500) LINE Pay 付款畫面時顯示的商品圖片,大小: 84 x 84
// *** 格式 ***
// 測試環境 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"
  },
  "result_url": {
      "frontend_redirect_url": "https://your.domain.com/transaction_is_done",
      "backend_notify_url": "https://your.domain.com/tappay_will_notify_this"
  }
}

Response

名稱 類別 內容
status int 交易代碼,成功的話為0
msg String 錯誤訊息
rec_trade_id String(20) 由 TapPay 伺服器產生的交易字串
將於退款時用到,請妥善保管
bank_transaction_id String(16) 銀行端的訂單編號
若有需求可在此自訂,但不能與之前的重複
若您沒有自訂則會自動幫您產生一組
格式規格請參考 reference
order_number String(50) 您自定義的訂單編號,用於 TapPay 做訂單識別,可重複帶入
格式請參考 reference
amount int 交易金額,台幣以外金額需包含兩位小數,如 100 代表 1.00
currency* String(3) 貨幣種類,銀行支援幣別請參考 reference
acquirer String 收單銀行 / 金流處理器
transaction_time_millis long 交易時間
bank_transaction_time JSONObject 銀行處理時間
bank_result_code String 銀行錯誤代碼
bank_result_msg String 銀行錯誤訊息
payment_url String 付款 Url,將此網址送到您的前端進行跳轉

Frontend Redirect

在 Line Pay 或 3D 交易完成之後, TapPay 會幫您 redirect 到您於 Pay by Prime 設定的 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&
satus=0&
bank_transaction_id=TP20171109WsvKhn

Request Query String

名稱 類別 內容
rec_trade_id String 交易識別碼
order_number String 自定義訂單編號
bank_transaction_id String 銀行端的訂單編號
status Int 交易代碼,成功為 0

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

Backend Notify

在 Line Pay 或 3D 驗證交易完成後, TapPay 會通知說交易已結束, TapPay 會發一個 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 交易識別碼
bank_transaction_id String 銀行端訂單編號
order_number String 自定義的訂單編號
amount Int 金額
details String 品項內容
status Int 交易代碼,成功為 0
msg String 交易訊息
transaction_time_millis Long Int 交易時間
pay_info JSONObject
名稱類別內容
methodString交易方式
1. CREDIT_CARD(信用卡)
2. BALANCE(一卡通 iPASS)
3. POINT (LINE Point 全額折抵)
masked_credit_card_numberString遮蔽後的卡片末四碼
pointInt點數折抵金額,若無折抵則為 0
acquirer String 收單銀行 / 金流處理器
merchant_reference_info Json 若商戶在Line Pay後台使用Co-brand card management 功能,且交易卡號符合Co-brand card management 設定時,將會回傳此參數
名稱類別內容
affiliate_codesArray商戶在Line Pay後台的Co-brand card management 功能專區設定的Affiliated code
{
    // Example
    "amount": 1,
    "order_number": "KK44845743",
    "details": "tpdirect-demo line pay test",
    "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(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
tsp
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 交易紀錄