Skip to content

boyonglin/shopline-payments-skill

shopline-payments

Verified

USE WHEN: 用戶詢問 SHOPLINE Payments 金流串接、導轉式付款流程、建立結帳交易(sessionUrl)、 returnUrl 回跳處理、Webhook 簽章驗證、交易查詢、退款/請款/取消操作, 或整合 LINE Pay、信用卡、ATM、街口支付(JKO)等台灣在地付款方式。 DO NOT USE WHEN: 詢問其他金流服務(如綠界 ECPay、藍新 NewebPay、TapPay)、 非台灣地區金流、或 SHOPLINE 電商平台非金流相關功能。

FileKindSize
SKILL.mdskill md7.3 KB
references/capture-cancel.mdmarkdown8.5 KB
references/embedded.mdmarkdown8.4 KB
references/error-codes.mdmarkdown14.0 KB
references/payment-methods.mdmarkdown1.5 KB
references/query.mdmarkdown4.8 KB
references/redirect.mdmarkdown10.8 KB
references/refund.mdmarkdown5.1 KB
references/sandbox.mdmarkdown4.6 KB
references/webhook.mdmarkdown9.0 KB
scripts/checkout.jsscript7.6 KB
scripts/gas-integration.jsscript12.2 KB
scripts/webhook.jsscript7.0 KB
---
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)

**問題**:收到「交易已請款,無法取消」
**原因**:已請款的交易無法取消授權
**解決**:請款後只能使用「退款」功能
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall