Is shopline-payments safe to install?

SaferSkills independently audited shopline-payments (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.

CategoryWeightCategory scoreContribution

Securityprompt, exec, net, exfil, eval

35%

100

35.0 pts

Supply chainhash, typosquat, maintainer, lockfile

20%

100

20.0 pts

Maintenancestaleness, pinning, CI

15%

100

15.0 pts

TransparencySKILL.md, perms, README

15%

100

15.0 pts

Communityinstalls, verify, response

15%

100

15.0 pts

Findings & checks · 0 flagged

Securityscore 100 · 0 findings

✓—All security checks passedNo findings in this category for the latest scan.pass

Supply chainscore 100 · 0 findings

✓—All supply chain checks passedNo findings in this category for the latest scan.pass

Maintenancescore 100 · 0 findings

✓—All maintenance checks passedNo findings in this category for the latest scan.pass

Transparencyscore 100 · 0 findings

✓—All transparency checks passedNo findings in this category for the latest scan.pass

Communityscore 100 · 0 findings

✓—All community checks passedNo findings in this category for the latest scan.pass

The primary manifest — the file an agent reads to learn what this artifact does.

SKILL.md · 1 file

SKILL.md7.3 KB · Markdown

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`）	支援綁卡/快捷/定期交易等進階功能

環境設定

環境 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 整合

重要注意事項

金額格式：台幣金額需 × 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)

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

shopline-payments— agent skill

Is shopline-payments safe to install?

SHOPLINE Payments 金流串接指南

概述

環境設定

環境 URL

必要金鑰

文檔結構

工作流程

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

內嵌式串接流程

API 認證機制

快速範例

JavaScript - 建立結帳交易

程式碼範例

重要注意事項

Troubleshooting

金額格式錯誤 (Error 1004)

重複訂單號 (Error 1001)

API 認證失敗 (Error ACCESS_DENIED)

Webhook 收不到通知

Webhook 簽章驗證失敗

沙盒測試一直失敗

退款失敗 (Error 1014/4701)

取消授權失敗 (Error 6002)

Audit the pieces. Scan the whole. Decide.