Payment Links API

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

認證

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

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 資料

範例

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"
  }'

import { Recur } from 'recur-tw/server'

const recur = new Recur({ secretKey: 'sk_test_xxx' })

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

回應

{
  "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	—	篩選啟用/停用狀態

回應

{
  "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	更新或移除自訂資料

範例

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。停用後，造訪該連結會顯示錯誤訊息。

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

回應

{
  "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）

Payment Links API

On this page