USE WHEN: 用戶詢問 SHOPLINE Payments 金流串接、導轉式付款流程、建立結帳交易(sessionUrl)、 returnUrl 回跳處理、Webhook 簽章驗證、交易查詢、退款/請款/取消操作, 或整合 LINE Pay、信用卡、ATM、街口支付(JKO)等台灣在地付款方式。 DO NOT USE WHEN: 詢問其他金流服務(如綠界 ECPay、藍新 NewebPay、TapPay)、 非台灣地區金流、或 SHOPLINE 電商平台非金流相關功能。
Scanned 2/12/2026
Install via CLI
openskills install boyonglin/shopline-payments-skill---
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-01
---
# SHOPLINE Payments 金流串接指南
此技能提供 SHOPLINE Payments 金流串接的完整文檔與程式碼範例。
## 概述
SHOPLINE Payments 提供兩種串接方式:
| 串接方式 | 說明 | 適用場景 |
|---------|------|---------|
| **導轉式** | 透過 API 取得付款頁 URL,導轉顧客至 SHOPLINE 付款頁 | 串接簡單,適合快速整合 |
| **內嵌式** | 透過 SDK + API 將付款表單內嵌於特店網站(詳見 [`references/embedded.md`](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`](references/redirect.md) | 導轉式結帳交易 API |
| **內嵌式串接** | [`references/embedded.md`](references/embedded.md) | **SDK + API 內嵌式串接指南** |
| 查詢交易 | [`references/query.md`](references/query.md) | 查詢結帳/付款交易狀態 |
| 退款 | [`references/refund.md`](references/refund.md) | 建立退款交易 |
| 請款/取消 | [`references/capture-cancel.md`](references/capture-cancel.md) | 信用卡請款與取消授權 |
| Webhook | [`references/webhook.md`](references/webhook.md) | 事件通知與簽章驗證 |
| 錯誤碼 | [`references/error-codes.md`](references/error-codes.md) | 錯誤碼完整參考 |
| 沙盒測試 | [`references/sandbox.md`](references/sandbox.md) | 測試卡號與測試規則 |
| 付款方式 | [`references/payment-methods.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`](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 - 建立結帳交易
```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`](scripts/checkout.js) - Node.js 建立結帳交易
- [`scripts/webhook.js`](scripts/webhook.js) - Webhook 簽章驗證
- [`scripts/gas-integration.js`](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)
**問題**:收到「交易已請款,無法取消」
**原因**:已請款的交易無法取消授權
**解決**:請款後只能使用「退款」功能
No comments yet. Be the first to comment!