---
title: Payment Links
description: 建立可分享的付款連結，無需寫程式即可收款
---

# Payment Links

Payment Links 是永久、可分享的付款網址。任何人造訪連結時，系統自動建立結帳工作階段，完成付款後即可收到款項。

## Payment Links vs Checkout Session

| | Payment Links | Checkout Session |
|---|---|---|
| **URL** | 永久有效（`buy.recur.tw/:urlId`） | 一次性，30 分鐘過期 |
| **建立方式** | Dashboard 或 API 建立一次 | 每次透過 API 建立 |
| **適用場景** | 社群分享、email、QR Code | 程式化整合、自訂流程 |
| **需要寫程式** | 不需要 | 需要 |

## 功能特點

### 同產品多條連結

同一個產品可以建立多條 Payment Links，各自有不同設定：

- 連結 A：Pro Monthly（無折扣）
- 連結 B：Pro Monthly（預填 20% off 促銷碼）
- 連結 C：Pro Monthly（限用 100 次）

### 預設促銷碼

建立時指定 `promotionCode`，顧客造訪時自動套用折扣。

### 使用次數限制

設定 `maxCompletions` 限制成功付款次數，適合限量優惠。

### 數據追蹤

每條連結自動追蹤：
- **瀏覽次數**（viewCount）
- **建立工作階段次數**（sessionCount）
- **完成付款次數**（completedCount）

### 自訂成功頁面

設定 `successUrl` 將顧客導向您的自訂成功頁面。

## 快速開始

### 透過 API 建立

```bash
curl -X POST https://api.recur.tw/v1/payment-links \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_xxx",
    "promotionCode": "LAUNCH20",
    "maxCompletions": 100
  }'
```

回應：

```json
{
  "id": "xxx",
  "url": "https://buy.recur.tw/7sY3cxcrX1T1ep4",
  "url_id": "7sY3cxcrX1T1ep4",
  "active": true,
  "product_id": "prod_xxx",
  "promotion_code": "LAUNCH20",
  "max_completions": 100,
  "view_count": 0,
  "session_count": 0,
  "completed_count": 0
}
```

### 分享連結

將 `url` 分享到任何地方：

- 社群媒體貼文
- Email 行銷
- 官網按鈕
- QR Code
- LINE / Messenger

## 結帳流程

```
顧客點擊 buy.recur.tw/:urlId
  → 顯示產品資訊 + 結帳表單
  → 顧客輸入 email + 信用卡
  → 付款成功
  → 導向成功頁面
  → Webhook 通知
```

  每次造訪會建立獨立的 Checkout Session，互不影響。多人可同時使用同一條連結。

## 管理連結

### 停用連結

```bash
curl -X DELETE https://api.recur.tw/v1/payment-links/:id \
  -H "Authorization: Bearer sk_test_xxx"
```

停用後，造訪連結會顯示「此連結已失效」。

### 更新設定

```bash
curl -X PATCH https://api.recur.tw/v1/payment-links/:id \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "promotionCode": "NEWYEAR", "maxCompletions": 50 }'
```

## URL 參數

在連結後面加上參數，就能預填顧客資料、自動套用優惠碼、追蹤業績歸屬。

### 可用參數

| 參數 | 說明 | 範例 |
|------|------|------|
| `email` | 預填顧客 email，減少輸入步驟 | `?email=user@example.com` |
| `promo` | 自動套用優惠碼（覆蓋連結預設值） | `?promo=SUMMER20` |
| `ref` | 追蹤業績來源，歸屬到 KOL 或合作夥伴 | `?ref=kol_alice` |
| `utm_source` | UTM 來源 | `?utm_source=instagram` |
| `utm_medium` | UTM 媒介 | `?utm_medium=social` |
| `utm_campaign` | UTM 活動 | `?utm_campaign=spring_sale` |

### 範例

同一條 Payment Link，搭配不同參數用在不同渠道：

```
# 給 KOL Alice，預填 20% off
buy.recur.tw/7sY3cxcrX1?promo=KOL20&ref=kol_alice

# Email 行銷，預填收件者 email
buy.recur.tw/7sY3cxcrX1?email=user@example.com&utm_source=email&utm_campaign=newsletter

# IG Bio
buy.recur.tw/7sY3cxcrX1?utm_source=instagram&utm_medium=bio
```

  所有追蹤參數（`ref`、`utm_*`）會寫入訂單的 metadata，可在 Dashboard 和 Webhook 事件中查看歸屬來源。

## 安全性

- Payment Links 的 URL ID 使用 Base62 編碼（16 字元），不可預測
- 信用卡資料透過 PAYUNi SDK iframe 處理，不經過 Recur 伺服器
- 支援 3D Secure 驗證
- Sandbox / Production 環境完全隔離

## 相關資源

- [Payment Links API 文件](/api-reference/payment-links)
- [託管結帳頁面](/features/customer-experience/checkout)
- [Webhook 事件](/guides/webhooks/events)