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

Frontend Redirect

1. LINE Pay, JKOPAY, 悠遊付, Atome, Pi錢包, 全盈支付 交易完成後，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

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

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

Backend Notify

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

Request Header

Request Url

Request Body

{
    // 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），確認該筆交易狀態後才能進行後續動作

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