平台特店串接指南
本指南旨在闡述 SHOPLINE Payments API 在不同業務場景下的應用與串接邏輯。我們將聚焦於「何時」與「為何」使用特定 API，而非詳細的 API 參數說明，具體 API 使用方式請參閱各 API 的獨立規格。本指南將涵蓋平台權限、子特店串接、代為交易、以及進階的結算與轉帳功能。
1. 成為平台，具備平台權限
當您的商業模式需要作為一個支付平台，為多個子特店提供支付服務，並代理其收款、退款等交易時，您需要成為 SHOPLINE Payments 的「平台特店」。
申請與審核： 首先，您必須與 SHOPLINE Payments 的業務團隊聯繫，表達成為平台特店的意向，並依循其指示完成相關的申請與審核流程。這是取得平台特店身份的先決條件。
取得金鑰： 成功通過審核後，SHOPLINE Payments 將會提供您專屬的串接金鑰，包含：
apiKey：用於 API 串接認證。clientKey：用於 SDK 串接認證（若有使用 SDK）。signKey：用於 Webhook 事件通知的串接認證。
這些金鑰是您作為平台特店進行所有 API 操作的身份憑證。
平台特店的優勢在於，您無需子特店提供其敏感的 API 金鑰，而是透過 SHOPLINE Payments 提供的「Connect」機制，安全地取得子特店的授權，進而代理其交易，確保資訊安全。
2. 與子特店進行 Connect
作為平台特店，您需要將子特店整合到您的支付服務中，您需要為子特店建立一個在您平台內的新的SHOPINE Payments 帳戶。
2.1. 透過 Connect API 建立授權連結
此方式適用於您希望子特店自行完成註冊並授權給您的平台。此方式讓子特店保有對其帳戶的控制權，並明確授權您的平台代理其交易。
- 發起授權請求： 您的平台會建構一個特殊的授權 URL，其中包含您的平台識別碼 (
client_id)、授權範圍 (scope)、重導向網址 (redirect_uri) 等參數。這個 URL 會引導子特店前往 SHOPLINE Payments 的授權頁面。詳情可參考 建構授權 URL。 - 子特店授權： 子特店點擊此授權 URL，註冊並登入其 SHOPLINE Payments 帳戶，並確認授權您的平台。完成授權後，子特店的瀏覽器會自動重導向回您平台預設的
redirect_uri，並在網址中帶回一個一次性的授權碼code。 - 取得子特店 ID： 您的平台接收到授權碼
code後，需立即呼叫 SHOPLINE Payments 的 連接子特店 API，將code傳送給 SHOPLINE Payments 進行驗證。驗證成功後，SHOPLINE Payments 會回傳該子特店的merchantId。此merchantId是您後續代理該子特店所有交易的唯一識別碼。
2.2. 透過 Onboarding API 直接註冊子特店
此方式適用於您的平台已經留存有子特店的 KYC 資料，可以直接為新的商家建立 SHOPLINE Payments 帳戶，並將其納入您的支付服務體系。這通常發生在您提供一站式服務，希望簡化子特店的註冊流程時。
- 呼叫子特店 Onboarding API： 您的平台直接呼叫 SHOPLINE Payments 的 子特店 Onboarding 系列 API。在請求中，您需要提供一個由您的平台自訂的子特店代號 (
referenceMerchantId)。 - 取得子特店 ID： 成功呼叫 API 後，SHOPLINE Payments 會為該子特店建立一個新的帳戶，並回傳由 SHOPLINE Payments 分配的子特店
merchantId。此merchantId即可用於後續代理該子特店的交易。
3. 代為子特店進行交易
一旦您的平台取得了子特店的 merchantId，您就可以代表該子特店處理其客戶的支付與退款請求。這使得您的平台能夠提供統一的支付介面和管理體驗。
在建立交易前，建議先確認好子特店已經被 SHOPLINE Payments 審核通過，和可以使用的付款方式。
子特店的審核狀態可透過 審核結果 Webhook 取得，而子特店的可用付款方式可透過 查詢子特店付款方式 API 取得。
SHOPLINE Payments 為特店提供了兩種串接方式，分別是導轉式和內嵌式。兩種方式各有優劣，平台特店可按需選用。
| 串接方式 | 介紹說明 | 串接規格 |
|---|---|---|
| 導轉式 | 此方式透過 API 提供金流付款頁連結給特店，由特店的結帳頁進行導轉付款。 | 導轉式付款串接 |
| 內嵌式 | 此方式透過 SDK + API 提供金流服務給特店，讓特店在其結帳頁內嵌金流 SDK，讓顧客可以直接進行在結帳頁進行付款。此方式支援信用卡的進階服務，如綁定卡片、定期交易等。 | 內嵌式付款串接 |
3.1. 建立交易
當子特店的客戶在您的平台完成購物，需要進行支付時，您的平台可以代理子特店發起付款交易。
- 呼叫建立交易 API： 您的平台呼叫 SHOPLINE Payments 的 建立結帳交易 API 或 建立付款交易 API。在請求中，您必須在 Header 或 Body 中明確指定您所代理的子特店
merchantId，以及交易金額、訂單資訊、客戶資訊、終端資訊等必要參數。 - 處理支付結果： SHOPLINE Payments 會處理支付流程，並回傳交易結果，包含
tradeOrderId(SHOPLINE Payments 支付交易訂單編號)、status(支付狀態) 等。您的平台應根據這些資訊更新子特店的訂單狀態。
3.2. 建立退款交易
當子特店需要為其客戶進行退款時，您的平台可以代理子特店發起退款交易。
- 呼叫建立退款交易 API： 您的平台呼叫 SHOPLINE Payments 的 建立退款交易 API。請求中需指定子特店的
merchantId、原始支付交易的tradeOrderId、退款金額以及退款原因等。 - 處理退款結果： SHOPLINE Payments 會處理退款流程，並回傳退款結果，包含
refundId(SHOPLINE Payments 退款交易訂單編號)、status(退款狀態) 等。您的平台應根據這些資訊更新子特店的訂單退款狀態。
4. 進階功能：為子特店交易進行結算與轉帳
除了代理日常交易，平台特店還可能需要對子特店的資金進行更深層次的管理，例如觸發交易結算或在平台特店和不同子特店帳戶間進行資金轉移。
4.1. 為子特店交易進行結算
當子特店的某筆交易已完成，且符合結算條件（交易時的 autoSettle 設定為 FALSE）時，您的平台可以主動觸發該筆交易的結算，將資金從待結算狀態轉為可提領狀態。
- 呼叫付款交易結算 API： 您的平台呼叫 SHOPLINE Payments 的 付款交易結算 API。請求中需指定子特店的
merchantId和需要結算的tradeOrderId。 - 處理結算結果： SHOPLINE Payments 會處理結算請求，並 Webhook 通知結算結果 (
result)。您的平台應根據結果更新內部記錄。
4.2. 平台特店與子特店之間轉帳
您的平台可能需要將資金從平台特店帳戶轉移至子特店帳戶，或從子特店帳戶轉移資金到平台特店帳戶，例如分潤、服務費扣除或資金調撥等。
- 呼叫建立轉帳交易 API： 您的平台呼叫 SHOPLINE Payments 的 建立轉帳交易 API。請求中需指定子特店的
merchantId、轉帳金額、轉帳方向 (destination)、轉帳原因代號 (transferCode) 以及平台自訂的轉帳訂單號 (referenceOrderId) 等。 - 處理轉帳結果： SHOPLINE Payments 會處理轉帳請求，並回傳轉帳交易的
transferId(SHOPLINE Payments 轉帳流水號) 和status(轉帳狀態)。您的平台應根據結果更新相關帳務。