| name | shopline-payments |
| description | USE WHEN: 用戶詢問 SHOPLINE Payments 金流串接、導轉式付款流程、建立結帳交易（sessionUrl）、 returnUrl 回跳處理、Webhook 簽章驗證、交易查詢、退款/請款/取消操作， 或整合 LINE Pay、信用卡、ATM、街口支付（JKO）等台灣在地付款方式。 DO NOT USE WHEN: 詢問其他金流服務（如綠界 ECPay、藍新 NewebPay、TapPay）、 非台灣地區金流、或 SHOPLINE 電商平台非金流相關功能。
|
| argument-hint | [feature: checkout/query/refund/capture/cancel/webhook] |
| user-invocable | true |
| metadata | {"author":"Clancy Lin","version":"1.1.0","documentation":"https://docs.shoplinepayments.com/","last-verified":"2026-02-01T00:00:00.000Z"} |
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 通知簽章驗證 |
文檔結構
根據用戶需求，參考以下文檔：
工作流程
導轉式串接流程（本專案主要使用）
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();
}
程式碼範例
完整的程式碼範例請參考：
重要注意事項
- 金額格式：台幣金額需 × 100（如 100 元傳入 10000）
- 訂單號唯一：
referenceId 不可重複
- HTTPS 必須：所有 API 請求必須使用 HTTPS
- 金鑰保密：
apiKey 和 signKey 不可暴露在前端
- 退款時效：付款交易可退款時效為 180 天
- 取消授權：只能在請款前取消，請款後只能退款
Troubleshooting
金額格式錯誤 (Error 1004)
問題：收到 1004 Param error
原因：金額未轉換為「分」
解決：amount.value = 實際金額 * 100（如 100 元傳 10000）
重複訂單號 (Error 1001)
問題：收到 1001 Order exist
原因：referenceId 已被使用
解決：確保每筆訂單使用唯一的 referenceId
API 認證失敗 (Error ACCESS_DENIED)
問題：收到 ACCESS_DENIED
原因：
apiKey 或 merchantId 錯誤- 使用沙盒金鑰呼叫正式環境（或反之）
解決：確認金鑰正確且環境對應
Webhook 收不到通知
問題：付款完成後未收到 Webhook
原因：
- Webhook URL 未設定（需聯繫 SLP 窗口申請）
- URL 非 HTTPS
- 伺服器防火牆阻擋
- 回應非 HTTP 200
解決：確認 URL 可公開存取並回應 200
Webhook 簽章驗證失敗
問題：簽章比對不符
原因：
signKey 錯誤- payload 組合方式錯誤（應為
timestamp.bodyString）
- body 被解析後重新序列化導致格式改變
解決：使用原始 body 字串進行簽章計算
沙盒測試一直失敗
問題：測試交易都失敗
原因：金額不符合測試規則
解決：
- 非 3D 交易：金額去掉 00 後為奇數才會成功（如 101, 501）
- 3D 交易：金額為 3 的倍數進入 3D 流程（如 300, 600）
退款失敗 (Error 1014/4701)
問題：收到「無可退款金額」或「退款金額超過可退金額」
原因：
- 已全額退款
- 退款金額超過原交易可退金額
解決：查詢原交易確認可退款金額
取消授權失敗 (Error 6002)
問題：收到「交易已請款，無法取消」
原因：已請款的交易無法取消授權
解決：請款後只能使用「退款」功能
