Server APIs

Overview

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

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