메뉴
USE WHEN: 用戶詢問 SHOPLINE Payments 金流串接、導轉式付款流程、建立結帳交易（sessionUrl）、 returnUrl 回跳處理、Webhook 簽章驗證、交易查詢、退款/請款/取消操作， 或整合 LINE Pay、信用卡、ATM、街口支付（JKO）等台灣在地付款方式。 DO NOT USE WHEN: 詢問其他金流服務（如綠界 ECPay、藍新 NewebPay、TapPay）、 非台灣地區金流、或 SHOPLINE 電商平台非金流相關功能。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| 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 提供兩種串接方式：
| 串接方式 | 說明 | 適用場景 |
|---|---|---|
| 導轉式 | 透過 API 取得付款頁 URL，導轉顧客至 SHOPLINE 付款頁 | 串接簡單，適合快速整合 |
| 內嵌式 | 透過 SDK + API 將付款表單內嵌於特店網站（詳見 references/embedded.md） | 支援綁卡/快捷/定期交易等進階功能 |
| 環境 | 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
所有 Server-API 請求必須包含以下 HTTP Header：
Content-Type: application/json
merchantId: <YOUR-MERCHANT-ID>
apiKey: <YOUR-API-KEY>
requestId: <UNIQUE-REQUEST-ID>
補充：若為平台特店（Platform Connect）請另外帶入
platformId；建議在「建立結帳交易」等具冪等需求的請求帶入idempotentKey，避免重複下單。
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 整合referenceId 不可重複apiKey 和 signKey 不可暴露在前端問題：收到 1004 Param error
原因：金額未轉換為「分」
解決：amount.value = 實際金額 * 100（如 100 元傳 10000）
問題：收到 1001 Order exist
原因：referenceId 已被使用
解決：確保每筆訂單使用唯一的 referenceId
問題：收到 ACCESS_DENIED
原因：
apiKey 或 merchantId 錯誤問題：付款完成後未收到 Webhook 原因：
問題：簽章比對不符 原因：
signKey 錯誤timestamp.bodyString）問題：測試交易都失敗 原因：金額不符合測試規則 解決：
問題：收到「無可退款金額」或「退款金額超過可退金額」 原因：
問題：收到「交易已請款，無法取消」 原因：已請款的交易無法取消授權 解決：請款後只能使用「退款」功能