Skip to main content

平台特店串接指南

本指南旨在闡述 SHOPLINE Payments API 在不同業務場景下的應用與串接邏輯。我們將聚焦於「何時」與「為何」使用特定 API，而非詳細的 API 參數說明，具體 API 使用方式請參閱各 API 的獨立規格。本指南將涵蓋平台權限、子特店串接、代為交易、以及進階的結算、轉帳和分帳功能。

1. 成為平台，具備平台權限​

當您的商業模式需要作為一個支付平台，為多個子特店提供支付服務，並代理其收款、退款等交易時，您需要成為 SHOPLINE Payments 的「平台特店」。

  1. 申請與審核： 首先，您必須與 SHOPLINE Payments 的業務團隊聯繫，表達成為平台特店的意向，並依循其指示完成相關的申請與審核流程。這是取得平台特店身分的先決條件。

  2. 取得金鑰： 成功透過審核後，SHOPLINE Payments 將會提供您專屬的串接金鑰，包含：

    • apiKey：用於 API 串接認證。
    • clientKey：用於 SDK 串接認證（若有使用 SDK）。
    • signKey：用於 Webhook 事件通知的串接認證。

    這些金鑰是您作為平台特店進行所有 API 操作的身分憑證。

平台特店的優勢在於，您無需子特店提供其敏感的 API 金鑰，而是透過 SHOPLINE Payments 提供的「Connect」機制，安全地取得子特店的授權，進而代理其交易，確保資訊安全。

2. 與子特店進行 Connect​

作為平台特店，您需要將子特店整合到您的支付服務中，您需要為子特店建立一個在您平台內的新的SHOPINE Payments 帳戶。

2.1. 透過 Connect API 建立授權連結​

此方式適用於您希望子特店自行完成註冊並授權給您的平台。此方式讓子特店保有對其帳戶的控制權，並明確授權您的平台代理其交易。

  1. 發起授權請求： 您的平台會建構一個特殊的授權 URL，其中包含您的平台識別碼 (client_id)、授權範圍 (scope)、重導向網址 (redirect_uri) 等參數。這個 URL 會引導子特店前往 SHOPLINE Payments 的授權頁面。詳情可參考 建構授權 URL。
  2. 子特店授權： 子特店點擊此授權 URL，註冊並登入其 SHOPLINE Payments 帳戶，並確認授權您的平台。完成授權後，子特店的瀏覽器會自動重導向回您平台預設的 redirect_uri，並在網址中帶回一個一次性的授權碼 code 。
  3. 取得子特店 ID： 您的平台接收到授權碼 code 後，需立即呼叫 SHOPLINE Payments 的 連接子特店 API，將 code 傳送給 SHOPLINE Payments 進行驗證。驗證成功後，SHOPLINE Payments 會回傳該子特店的 merchantId。此 merchantId 是您後續代理該子特店所有交易的唯一識別碼。

2.2. 透過 Onboarding API 直接註冊子特店​

此方式適用於您的平台已經留存有子特店的 KYC 資料，可以直接為新的商家建立 SHOPLINE Payments 帳戶，並將其納入您的支付服務體系。這通常發生在您提供一站式服務，希望簡化子特店的註冊流程時。

  1. 呼叫子特店 Onboarding API： 您的平台直接呼叫 SHOPLINE Payments 的 子特店 Onboarding 系列 API。在請求中，您需要提供一個由您的平台自訂的子特店代號 (referenceMerchantId)。
  2. 取得子特店 ID： 成功呼叫 API 後，SHOPLINE Payments 會為該子特店建立一個新的帳戶，並回傳由 SHOPLINE Payments 分配的子特店 merchantId。此 merchantId 即可用於後續代理該子特店的交易。

3. 代為子特店進行交易​

一旦您的平台取得了子特店的 merchantId，您就可以代表該子特店處理其客戶的支付與退款請求。這使得您的平台能夠提供統一的支付介面和管理體驗。

注意

在建立交易前，建議先確認好子特店已經被 SHOPLINE Payments 審核透過，和可以使用的付款方式。

子特店的審核狀態可透過 審核結果 Webhook 取得，而子特店的可用付款方式可透過 查詢子特店付款方式 API 取得。

SHOPLINE Payments 為特店提供了兩種串接方式，分別是導轉式和內嵌式。兩種方式各有優劣，平台特店可按需選用。

串接方式介紹說明串接規格
導轉式此方式透過 API 提供金流付款頁連結給特店，由特店的結帳頁進行導轉付款。 導轉式付款串接
內嵌式此方式透過 SDK + API 提供金流服務給特店，讓特店在其結帳頁內嵌金流 SDK，讓顧客可以直接進行在結帳頁進行付款。此方式支援信用卡的進階服務，如綁定卡片、定期交易等。 內嵌式付款串接

3.1. 建立交易​

當子特店的客戶在您的平台完成購物，需要進行支付時，您的平台可以代理子特店發起付款交易。

  1. 呼叫建立交易 API： 您的平台呼叫 SHOPLINE Payments 的 建立結帳交易 API 或 建立付款交易 API。在請求中，您必須在 Header 或 Body 中明確指定您所代理的子特店 merchantId，以及交易金額、訂單資訊、客戶資訊、終端資訊等必要參數。
  2. 處理支付結果： SHOPLINE Payments 會處理支付流程，並回傳交易結果，包含 tradeOrderId (SHOPLINE Payments 支付交易訂單編號)、status (支付狀態) 等。您的平台應根據這些資訊更新子特店的訂單狀態。

3.2. 建立退款交易​

當子特店需要為其客戶進行退款時，您的平台可以代理子特店發起退款交易。

  1. 呼叫建立退款交易 API： 您的平台呼叫 SHOPLINE Payments 的 建立退款交易 API。請求中需指定子特店的 merchantId、原始支付交易的 tradeOrderId、退款金額以及退款原因等。
  2. 處理退款結果： SHOPLINE Payments 會處理退款流程，並回傳退款結果，包含 refundId (SHOPLINE Payments 退款交易訂單編號)、status (退款狀態) 等。您的平台應根據這些資訊更新子特店的訂單退款狀態。

4. 進階功能：結算、轉帳與分帳​

除了代理日常交易，平台特店還需要對資金進行更深層次的管理。SHOPLINE Payments 提供三種進階資金管理功能：

功能適用場景說明
結算（Settle）手動觸發交易結算將待結算的付款交易資金從待結算狀態轉為可提領狀態
轉帳（Transfer）平台與子特店之間資金劃轉在平台帳戶與單一子特店帳戶之間進行資金轉移，如收取手續費、發放獎勵金等
分帳（Split）一筆付款分配給多方針對一筆已完成的付款交易，將資金按比例分配給多個子特店

4.1 為子特店交易進行結算​

當付款交易的 autoSettle 設定為 false 時，交易完成後資金會停留在「待結算」狀態，需主動觸發結算才能轉為可提領狀態。

  1. 呼叫 付款交易結算 API： 請求中需指定子特店的 merchantId 和需要結算的 tradeOrderId。
  2. 處理結算結果： SLP 處理結算請求後，透過 子特店結算 Webhook（trade.settled）通知結算結果。

4.2 平台與子特店之間轉帳​

當您的平台需要在平台帳戶與單一子特店帳戶之間進行資金劃轉時使用，例如收取平台服務費、支付交易手續費、退款、發放獎勵金等。

串接步驟​

  1. 呼叫 建立轉帳交易 API： 請求中需指定子特店的 merchantId、轉帳金額、轉帳方向（destination）、轉帳原因代號（transferCode）以及平台自訂的轉帳訂單號（referenceOrderId）。
  2. 處理轉帳結果： SHOPLINE Payments 處理後回傳 transferId（轉帳流水號）和 status（轉帳狀態），亦可透過查詢轉帳交易 API 查詢取得這些資訊。

4.3 平台分帳​

當一筆付款交易的資金需要分配給多個子特店時使用（例如電商平台一筆訂單包含多家店鋪的商品，需按比例拆分資金給各家子特店）。

注意

平台僅能針對平台協助建立的付款交易發起分帳。

分帳核心規則​

  • 每次分帳針對一筆付款交易（tradeOrderId）
  • 一次可分給多個子特店（splitData 為陣列），每個子特店僅能出現一次
  • finish 參數標記是否為最後一次分帳：true 表示本次分帳後不再對該筆交易發起新的分帳，false 表示後續還會繼續分帳

串接步驟​

  1. 呼叫 建立分帳交易 API： 請求中需指定子特店的 merchantId、原始 tradeOrderId、finish（是否最後一次）、splitData（分帳明細，含每個子特店的分帳金額、原因、說明）。
  2. 處理分帳結果： SHOPLINE Payments 處理後回傳 splitId（分帳流水號）和 status（分帳狀態）。SLP 會透過 分帳交易 Webhook 通知分帳狀態變更，平台應監聽並更新內部記錄。

5. 功能對比：轉帳 vs 分帳​

對比項目轉帳（Transfer）分帳（Split）
資金來源平台或子特店帳戶餘額一筆已完成付款交易的資金
分配對象平台 ↔ 單一子特店（一對一）一筆交易 → 多個子特店（一對多）
是否關聯付款交易❌ 不綁定特定交易✅ 必須指定 tradeOrderId
可否多次操作無限制可多次分帳，finish 控制是否完結
典型場景平台收取手續費、發放獎勵金、退款多店鋪訂單資金拆分、平台佣金分成