Server APIs

Overview

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

支付方式定義說明
為協助開發者理解各交易欄位的適用範圍，以下說明 TapPay 文件中「Direct Pay」、「電子支付」、「Token Pay」三種支付方式的定義與適用場景。

Direct Pay
定義：
Direct Pay 是指消費者直接於商戶前端頁面輸入信用卡資訊，透過 TapPay 金流閘道進行付款的交易。

電子支付
定義：
電子支付是指透過電子錢包帳戶完成的交易，包含以下支付業者：LINE Pay, 街口支付, 悠遊付等，完整的支付業者請參考 電子支付支援功能

API 欄位支援與格式依各電子支付業者而異，請參考詳細 API 規格說明。

Token Pay
定義：
Token Pay 僅指使用 行動支付服務（Apple Pay, Goole Pay, Samsung Pay）所產生的 Tokenized 信用卡號 (DPAN) 所完成的交易

Pay by Prime API

• 非3D交易流程

• 3D驗證交易流程

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

建議您在收到frontend redirect 後，於前端顯示交易結果頁面給消費者前，打 Record API(以 rec_trade_id 作為搜尋條件)進行反查確認交易狀態，以避免您因意外狀況未收到 Backend Notify 而發生交易狀態不一致問題。

• 利用前端所取得的 prime 字串進行交易
  
• 每個 prime 字串只可使用一次，因此每次呼叫此 API 前都必須重新取得一個 prime 字串
  
• 若將 remember 設為 true 記憶卡號，則會獲得 card_key 和 card_token，以後即可省去 createToken 這個步驟並改為呼叫 Pay by Card Token 來進行交易。亦可使用 card_key 和 card_token 來進行定期定額扣款，存下此兩個參數後，即可定期呼叫 Pay by Card Token 進行定期定額扣款，且呼叫的週期與金額可自行決定。Apple Pay、Google Pay、Samsung Pay、JKOPAY、悠遊付、Atome、Pi 錢包、全盈支付 不支援此功能
• 由於尖峰時段銀行方面可能會花較久時間處理，因此請將 timeout 時間設定為 30 秒以避免交易資訊不同步
  

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

Pay by Card Token API

• 非3D驗證交易流程

• 3D驗證交易流程

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

建議您在收到frontend redirect 後，於前端顯示交易結果頁面給消費者前，打 Record API(以 rec_trade_id 作為搜尋條件)進行反查確認交易狀態，以避免您因意外狀況未收到 Backend Notify 而發生交易狀態不一致問題。

• 由於尖峰時段銀行方面可能會花較久時間處理，因此請將 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 進行定期定額扣款，且呼叫的週期與金額可自行決定。

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

Refund API

• 此 API 能讓您用後台直接進行退款，會同時做取消授權及取消請款的動作 若您有部分退款的需求，則必須呼叫此 API
  
• 由於尖峰時段銀行方面可能會花較久時間處理，因此請將 timeout 時間設定為 30 秒以避免交 易資訊不同步
  
• 當您呼叫此 API 時，TapPay 將於當日向銀行進行退款，不代表當日退款已成功。
  實際退款是否成功，請於退款隔天利用 TapPay 後台或 Record API 查詢交易狀態進行確認。
  
• 為確保交易狀態一致，當銀行/錢包在請款中不支援取消授權，需等TapPay收到銀行回覆（時間請參考Each bank capture time），確認該筆交易狀態後才能進行後續動作

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

Record API

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

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