Recur
API 參考

API 參考

Recur REST API 完整文件 - 認證、端點、參數、回應格式

API 參考

Recur 提供完整的 REST API，讓您能夠完全控制訂閱和計費流程。

Base URL

https://api.recur.tw/v1

認證

Recur API 使用 API Key 認證。在請求標頭中加入：

Authorization: Bearer sk_test_xxx

詳細說明請參考 API 認證。

API Key 類型

類型前綴用途
Secret Keysk_xxx後端使用，完整權限
Publishable Keypk_xxx前端使用，限制權限

環境

環境Key 前綴說明
Sandboxsk_test_ / pk_test_測試環境
Productionsk_live_ / pk_live_正式環境

核心概念

冪等性

理解冪等性的重要性，避免重複扣款等災難

API 端點

Checkout Sessions

建立和管理託管結帳會話

Products

查詢可用的產品（訂閱方案、一次性付款等）

Customers

客戶資料查詢與管理

Subscriptions

訂閱狀態查詢與管理

Webhooks

接收支付和訂閱事件通知

請求格式

所有 API 請求使用 JSON 格式：

curl -X POST https://api.recur.tw/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xxx",
    "mode": "SUBSCRIPTION",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'

回應格式

成功回應

{
  "id": "cs_xxx",
  "url": "https://checkout.recur.tw/cs_xxx",
  "expires_at": "2025-01-01T00:30:00Z"
}

錯誤回應

{
  "error": {
    "code": "invalid_request",
    "message": "product_id is required"
  }
}

常見錯誤代碼

HTTP 狀態錯誤代碼說明
400invalid_request請求參數無效
401unauthorizedAPI Key 無效或缺失
403forbidden無權限執行此操作
404resource_not_found資源不存在
500internal_error伺服器錯誤

分頁

列表類 API 支援分頁：

GET /subscriptions?limit=10&starting_after=sub_xxx
參數說明
limit每頁數量（預設 10，最大 100）
starting_after從指定 ID 之後開始

Rate Limiting

API 有以下限制：

  • 每分鐘 100 次請求（Sandbox）
  • 每分鐘 1000 次請求（Production）

超過限制時會返回 429 Too Many Requests。

下一步

進階功能

發現平台的進階功能並掌握專業技巧

冪等性

理解冪等性 (Idempotency) 的重要性，以及如何在支付系統中正確實作

On this page

API 參考Base URL認證API Key 類型環境核心概念API 端點請求格式回應格式成功回應錯誤回應常見錯誤代碼分頁Rate Limiting下一步