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

references/sandbox.md

View on GitHub
# 沙盒測試環境

SHOPLINE Payments 提供沙盒環境進行串接測試。

## 環境資訊

| 環境 | Base URL |
|------|----------|
| 沙盒環境 | `https://api-sandbox.shoplinepayments.com` |
| 正式環境 | `https://api.shoplinepayments.com` |

## 取得測試金鑰

聯繫 SHOPLINE Payments 串接窗口獲取沙盒環境的:
- `apiKey`
- `clientKey`(內嵌式使用)
- `signKey`

---

## 信用卡測試

### 測試卡號

| 卡組織 | 卡號 | 有效期限 | CVC |
|-------|------|---------|-----|
| JCB | 3565586700000200 | 03/30 | 484 |
| Visa | 4147633700198405 | 03/30 | 638 |
| MasterCard | 5149147700000300 | 03/30 | 231 |

### 3D 驗證測試

**觸發條件**:金額為 3 的倍數會進入 3D 驗證流程

| 金額 | 是否 3D | 說明 |
|-----|--------|------|
| 300 | 是 | 進入 3D 驗證(300 ÷ 3 = 100) |
| 600 | 是 | 進入 3D 驗證(600 ÷ 3 = 200) |
| 301 | 否 | 不進入 3D |
| 401 | 否 | 不進入 3D |

在沙盒環境中,3D 流程會跳轉至模擬頁面,可選擇模擬的交易結果(成功/失敗)。

### 非 3D 交易測試

**規則**:金額非 3 的倍數,去掉最小單位 (00) 後:

| 金額 | 去掉 00 後 | 奇偶 | 結果 |
|-----|----------|------|------|
| 401 | 4 | 偶數 | 失敗 |
| 501 | 5 | 奇數 | 成功 |
| 400 | 4 | 偶數 | 失敗 |
| 500 | 5 | 奇數 | 成功 |
| 101 | 1 | 奇數 | 成功 |
| 201 | 2 | 偶數 | 失敗 |

**簡單記法**:
- 金額結尾為 **奇數** → 成功(如 101, 301, 501)
- 金額結尾為 **偶數** → 失敗(如 200, 400, 600)

---

## Apple Pay 測試

### 前置準備

1. 準備 MacOS 10.14.1+ 的 MacBook 或 iOS 12.1+ 的 iPhone
2. 登入 Apple Pay 沙盒環境的 Apple ID

### 沙盒 Apple ID

```
帳號:slpsandbox2@shopline.com
密碼:Aa123456!
```

> **請勿修改密碼**

### 設定步驟

1. 登入沙盒 Apple ID
2. 在 Wallet 添加 Apple Pay 測試卡號
3. 測試卡號請參考 [Apple 官方文檔](https://developer.apple.com/apple-pay/sandbox-testing/)

### 交易規則

與信用卡相同:
- 金額奇數 → 成功
- 金額偶數 → 失敗

---

## 其他付款方式測試

### LINE Pay / 街口支付 / ATM 等

沙盒環境會跳轉至 SHOPLINE 模擬頁面,可在頁面上選擇模擬的交易狀態:

- 成功
- 失敗
- 取消

---

## 測試流程建議

### 1. 基本流程測試

```
□ 建立結帳交易,取得 sessionUrl
□ 訪問 sessionUrl,選擇付款方式
□ 完成付款(使用測試卡號)
□ 驗證 returnUrl 跳轉
□ 接收 Webhook 通知
□ 查詢交易狀態確認
```

### 2. 分期付款測試

```
□ 設定 installmentCounts: ["0", "3", "6"]
□ 在付款頁選擇分期期數
□ 完成分期交易
□ 驗證回應中的分期資訊
```

### 3. 退款測試

```
□ 完成一筆成功交易
□ 呼叫退款 API
□ 驗證退款狀態
□ 接收退款 Webhook
```

### 4. 錯誤處理測試

```
□ 測試付款失敗情況(金額偶數)
□ 測試重複訂單號錯誤
□ 測試參數錯誤
□ 測試 Webhook 簽章驗證
```

### 5. Webhook 測試

```
□ 設定 Webhook URL
□ 驗證簽章邏輯
□ 測試各種事件類型
□ 測試冪等處理
```

---

## 測試清單

### 付款功能

| 項目 | 測試內容 | 狀態 |
|-----|---------|------|
| 信用卡一般 | 使用 Visa 測試卡完成付款 | □ |
| 信用卡 3D | 金額 300 測試 3D 驗證流程 | □ |
| 信用卡分期 | 測試 3 期分期付款 | □ |
| LINE Pay | 模擬 LINE Pay 付款成功 | □ |
| 街口支付 | 模擬街口支付付款成功 | □ |
| ATM 虛擬帳號 | 建立虛擬帳號,模擬付款 | □ |

### 交易管理

| 項目 | 測試內容 | 狀態 |
|-----|---------|------|
| 查詢結帳 | 查詢 session 狀態 | □ |
| 查詢付款 | 查詢 trade 狀態 | □ |
| 退款 | 全額退款 | □ |
| 部分退款 | 部分金額退款 | □ |
| 取消授權 | 請款前取消授權 | □ |

### Webhook

| 項目 | 測試內容 | 狀態 |
|-----|---------|------|
| 簽章驗證 | 驗證 Webhook 簽章 | □ |
| trade.succeeded | 付款成功通知 | □ |
| trade.failed | 付款失敗通知 | □ |
| trade.refund.succeeded | 退款成功通知 | □ |

---

## 常見問題

### Q: 測試時一直失敗?

檢查金額是否為偶數,改用奇數金額(如 101, 501)。

### Q: 3D 驗證頁面在哪裡?

沙盒環境使用模擬頁面,會自動跳轉,可選擇成功或失敗。

### Q: Webhook 收不到?

1. 確認 URL 是 HTTPS
2. 確認已向 SHOPLINE 申請開通
3. 檢查伺服器是否正確回應 200

### Q: 如何切換到正式環境?

1. 取得正式環境金鑰
2. 將 Base URL 改為 `https://api.shoplinepayments.com`
3. 更新 Webhook URL
4. 使用真實信用卡測試小額交易
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