SHOPLINE Payments 金流串接指南

此技能提供 SHOPLINE Payments 金流串接的完整文檔與程式碼範例。

概述

SHOPLINE Payments 提供兩種串接方式：

| 串接方式 | 說明 | 適用場景 | |---------|------|---------| | 導轉式 | 透過 API 取得付款頁 URL，導轉顧客至 SHOPLINE 付款頁 | 串接簡單，適合快速整合 | | 內嵌式 | 透過 SDK + API 將付款表單內嵌於特店網站（詳見 references/embedded.md） | 支援綁卡/快捷/定期交易等進階功能 |

環境設定

環境 URL

| 環境 | Base URL | |------|----------| | 沙盒環境 | https://api-sandbox.shoplinepayments.com | | 正式環境 | https://api.shoplinepayments.com |

必要金鑰

| 金鑰 | 用途 | |-----|------| | merchantId | 特店 ID | | apiKey | Server API 串接認證 | | clientKey | SDK 串接認證（內嵌式使用） | | signKey | Webhook Event 通知簽章驗證 |

文檔結構

根據用戶需求，參考以下文檔：

| 需求 | 文檔 | 說明 | |------|------|------| | 建立結帳交易 | references/redirect.md | 導轉式結帳交易 API | | 內嵌式串接 | references/embedded.md | SDK + API 內嵌式串接指南 | | 查詢交易 | references/query.md | 查詢結帳/付款交易狀態 | | 退款 | references/refund.md | 建立退款交易 | | 請款/取消 | references/capture-cancel.md | 信用卡請款與取消授權 | | Webhook | references/webhook.md | 事件通知與簽章驗證 | | 錯誤碼 | references/error-codes.md | 錯誤碼完整參考 | | 沙盒測試 | references/sandbox.md | 測試卡號與測試規則 | | 付款方式 | references/payment-methods.md | 支援的付款方式說明 |

工作流程

導轉式串接流程（本專案主要使用）

1. 特店後端呼叫「建立結帳交易」API
2. 取得 sessionUrl
3. 前端導轉顧客至 sessionUrl（SHOPLINE 付款頁）
4. 顧客完成付款後自動導回 returnUrl
5. 特店透過 Webhook 接收付款結果
6. （建議）主動查詢交易狀態二次確認

內嵌式串接流程

1. 前端引入 JS SDK（NPM 或 CDN）
2. 初始化 SDK 並呈現收銀台
3. 顧客填寫付款資訊並點擊結帳
4. SDK 建立 paySession
5. 後端呼叫「建立付款交易」API（帶入 paySession）
6. 前端呼叫 payment.pay(nextAction) 發起付款
7. 完成 3D 驗證（如需要）後導回 returnUrl
8. 透過 Webhook 接收付款結果

完整內嵌式串接說明請參考 references/embedded.md

API 認證機制

所有 Server-API 請求必須包含以下 HTTP Header：

Content-Type: application/json
merchantId: <YOUR-MERCHANT-ID>
apiKey: <YOUR-API-KEY>
requestId: <UNIQUE-REQUEST-ID>

補充：若為平台特店（Platform Connect）請另外帶入 platformId；建議在「建立結帳交易」等具冪等需求的請求帶入 idempotentKey，避免重複下單。

快速範例

JavaScript - 建立結帳交易

async function createCheckoutSession(orderData) {
  const response = await fetch('https://api-sandbox.shoplinepayments.com/api/v1/trade/sessions/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'merchantId': process.env.SHOPLINE_MERCHANT_ID,
      'apiKey': process.env.SHOPLINE_API_KEY,
      'requestId': Date.now().toString()
    },
    body: JSON.stringify({
      referenceId: orderData.orderId,
      amount: { value: orderData.amount * 100, currency: 'TWD' },
      returnUrl: orderData.returnUrl,
      mode: 'regular',
      allowPaymentMethodList: ['CreditCard', 'LinePay'],
      customer: {
        personalInfo: {
          firstName: orderData.name,
          email: orderData.email,
          phone: orderData.phone
        }
      },
      client: { ip: orderData.clientIp }
    })
  });
  return await response.json();
}

程式碼範例

完整的程式碼範例請參考：

• scripts/checkout.js - Node.js 建立結帳交易
• scripts/webhook.js - Webhook 簽章驗證
• scripts/gas-integration.js - Google Apps Script 整合

重要注意事項

1. 金額格式：台幣金額需 × 100（如 100 元傳入 10000）
2. 訂單號唯一：referenceId 不可重複
3. HTTPS 必須：所有 API 請求必須使用 HTTPS
4. 金鑰保密：apiKey 和 signKey 不可暴露在前端
5. 退款時效：付款交易可退款時效為 180 天
6. 取消授權：只能在請款前取消，請款後只能退款

Troubleshooting

金額格式錯誤 (Error 1004)

問題：收到 1004 Param error 原因：金額未轉換為「分」 解決：amount.value = 實際金額 * 100（如 100 元傳 10000）

重複訂單號 (Error 1001)

問題：收到 1001 Order exist 原因：referenceId 已被使用 解決：確保每筆訂單使用唯一的 referenceId

API 認證失敗 (Error ACCESS_DENIED)

問題：收到 ACCESS_DENIED 原因：

1. apiKey 或 merchantId 錯誤
2. 使用沙盒金鑰呼叫正式環境（或反之） 解決：確認金鑰正確且環境對應

Webhook 收不到通知

問題：付款完成後未收到 Webhook 原因：

1. Webhook URL 未設定（需聯繫 SLP 窗口申請）
2. URL 非 HTTPS
3. 伺服器防火牆阻擋
4. 回應非 HTTP 200 解決：確認 URL 可公開存取並回應 200

Webhook 簽章驗證失敗

問題：簽章比對不符 原因：

1. signKey 錯誤
2. payload 組合方式錯誤（應為 timestamp.bodyString）
3. body 被解析後重新序列化導致格式改變 解決：使用原始 body 字串進行簽章計算

沙盒測試一直失敗

問題：測試交易都失敗 原因：金額不符合測試規則 解決：

• 非 3D 交易：金額去掉 00 後為奇數才會成功（如 101, 501）
• 3D 交易：金額為 3 的倍數進入 3D 流程（如 300, 600）

退款失敗 (Error 1014/4701)

問題：收到「無可退款金額」或「退款金額超過可退金額」 原因：

1. 已全額退款
2. 退款金額超過原交易可退金額 解決：查詢原交易確認可退款金額

取消授權失敗 (Error 6002)

問題：收到「交易已請款，無法取消」 原因：已請款的交易無法取消授權 解決：請款後只能使用「退款」功能