---
title: Payment Links API
description: Payment Link 建立與管理 API
---

# Payment Links API

建立與管理可分享的付款連結。每條連結是一個永久 URL，顧客造訪時自動建立結帳工作階段。

## 認證

  所有 Payment Links API 端點都需要 **Secret Key** 認證。

```bash
Authorization: Bearer sk_test_xxx
```

## 建立 Payment Link

### 端點

```
POST /payment-links
```

### 請求參數

**產品識別（至少需要其中一個）：**

| 參數 | 必填 | 類型 | 說明 |
|------|------|------|------|
| `productId` | ❌ | string | 產品 ID |
| `productSlug` | ❌ | string | 產品 slug |

**選填參數：**

| 參數 | 類型 | 預設值 | 說明 |
|------|------|--------|------|
| `promotionCode` | string | — | 預設套用的促銷碼 |
| `collectPaymentMethod` | string | `"always"` | `"always"` 或 `"if_required"` |
| `successUrl` | string | — | 自訂付款成功後的導向 URL |
| `maxCompletions` | number \| null | `null` | 最大成功付款次數（`null` = 無限制） |
| `metadata` | object | — | 自訂 key-value 資料 |

### 範例

  
```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,
    "successUrl": "https://your-site.com/thanks"
  }'
```
  
  
```typescript
import { Recur } from 'recur-tw/server'

const recur = new Recur(process.env.RECUR_SECRET_KEY!)

const link = await recur.paymentLinks.create({
  productId: 'prod_xxx',
  promotionCode: 'LAUNCH20',
  maxCompletions: 100,
  successUrl: 'https://your-site.com/thanks',
})

console.log(link.url) // https://buy.recur.tw/7sY3cxcrX1T1ep4
```
  

### 回應

```json
{
  "id": "xxx",
  "url": "https://buy.recur.tw/7sY3cxcrX1T1ep4",
  "url_id": "7sY3cxcrX1T1ep4",
  "active": true,
  "product_id": "prod_xxx",
  "product": {
    "id": "prod_xxx",
    "name": "Pro Monthly",
    "slug": "pro-monthly",
    "price": 590,
    "currency": "TWD",
    "type": "SUBSCRIPTION"
  },
  "promotion_code": "LAUNCH20",
  "collect_payment_method": "always",
  "success_url": "https://your-site.com/thanks",
  "max_completions": 100,
  "metadata": null,
  "environment": "SANDBOX",
  "view_count": 0,
  "session_count": 0,
  "completed_count": 0,
  "created_at": "2026-03-25T12:00:00.000Z"
}
```

## 列出 Payment Links

### 端點

```
GET /payment-links
```

### 查詢參數

| 參數 | 類型 | 預設值 | 說明 |
|------|------|--------|------|
| `limit` | number | `20` | 每頁筆數（1-100） |
| `starting_after` | string | — | 游標分頁（上一頁最後一筆的 ID） |
| `active` | boolean | — | 篩選啟用/停用狀態 |

### 回應

```json
{
  "data": [
    { "id": "xxx", "url": "https://buy.recur.tw/...", "active": true, ... }
  ],
  "has_more": false
}
```

## 取得 Payment Link

```
GET /payment-links/:id
```

回傳單一 Payment Link 的完整資料，格式同建立時的回應。

## 更新 Payment Link

### 端點

```
PATCH /payment-links/:id
```

### 可更新欄位

| 參數 | 類型 | 說明 |
|------|------|------|
| `active` | boolean | 啟用/停用 |
| `promotionCode` | string \| null | 更新或移除促銷碼 |
| `collectPaymentMethod` | string | `"always"` 或 `"if_required"` |
| `successUrl` | string \| null | 更新或移除自訂成功 URL |
| `maxCompletions` | number \| null | 更新或移除使用次數限制 |
| `metadata` | object \| null | 更新或移除自訂資料 |

### 範例

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

## 停用 Payment Link

```
DELETE /payment-links/:id
```

軟刪除：將 `active` 設為 `false`。停用後，造訪該連結會顯示錯誤訊息。

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

### 回應

```json
{
  "id": "xxx",
  "deleted": true
}
```

## Payment Link Object

| 欄位 | 類型 | 說明 |
|------|------|------|
| `id` | string | Payment Link ID |
| `url` | string | 可分享的完整 URL（`buy.recur.tw/:urlId`） |
| `url_id` | string | URL 路徑中的 Base62 短碼 |
| `active` | boolean | 是否啟用 |
| `product_id` | string | 關聯的產品 ID |
| `product` | object | 產品摘要（name, slug, price, currency, type） |
| `promotion_code` | string \| null | 預設促銷碼 |
| `collect_payment_method` | string | 付款方式收集策略 |
| `success_url` | string \| null | 自訂成功 URL |
| `max_completions` | number \| null | 最大完成次數 |
| `metadata` | object \| null | 自訂資料 |
| `environment` | string | `SANDBOX` 或 `PRODUCTION` |
| `view_count` | number | 瀏覽次數 |
| `session_count` | number | 建立工作階段次數 |
| `completed_count` | number | 成功付款次數 |
| `created_at` | string | 建立時間（ISO 8601） |

## URL 參數

Payment Link 的 URL 支援 query parameters，用於預填資料和追蹤歸屬。

### 支援的參數

| 參數 | 說明 |
|------|------|
| `email` | 預填 email 欄位，減少顧客輸入 |
| `promo` | 覆蓋連結預設的促銷碼 |
| `ref` | 業績歸屬追蹤（寫入訂單 metadata） |
| `utm_source` | UTM 來源追蹤 |
| `utm_medium` | UTM 媒介追蹤 |
| `utm_campaign` | UTM 活動追蹤 |
| `utm_term` | UTM 關鍵字追蹤 |
| `utm_content` | UTM 內容追蹤 |

### 範例

```
https://buy.recur.tw/7sY3cxcrX1?email=user@example.com&promo=LAUNCH20&ref=kol_alice&utm_source=ig
```

追蹤參數（`ref`、`utm_*`）會寫入 `checkout_session.metadata`，並透過 Webhook 事件傳遞。