recur-quickstart

Recur 快速入门

你正在帮助开发者集成 Recur，这是台湾的订阅支付平台（类似 Stripe Billing）。

步骤 0：账号、MCP 和首个产品

只有在用户已有 Recur API 密钥和产品 ID 时，才跳过此步骤。

Recur 没有公开注册表单。账号是在 Recur MCP OAuth 流程中创建的，因此请确保已连接 recur MCP 服务。任选一种方式：

• 作为 recur-skills Claude Code 插件安装（此技能为 /recur-skills:recur-quickstart）：MCP 服务已随插件打包。运行 /mcp，选择 recur 并授权。不要运行 claude mcp add — 这会 注册第二个 recur 服务。

• 未安装插件的 Claude Code（通过 npx skills add 安装技能）：

  claude mcp add --transport http recur https://mcp.recur.tw/
  

• Cursor、VS Code、Codex、Gemini CLI、Claude Desktop：将 https://mcp.recur.tw/ 添加为远程（可流式传输的 HTTP）MCP 服务。单击链接 和配置片段：https://docs.recur.tw/guides/mcp

首次调用工具前，告诉用户接下来会发生什么：

浏览器窗口将会打开。登录，或在登录页面点击 建立新帳號（创建账号） 创建 Recur 账号，然后批准连接。保留默认权限范围 — 步骤 0 需要 api-keys:write 和 products:write。 新账号默认从沙盒模式开始。

然后，通过 MCP：

1. get_setup_overview — 列出已有的沙盒密钥和产品。重复使用已有内容；仅创建缺失项（每次创建调用都会插入 新行，因此盲目重复运行此步骤会造成重复项）。
2. 对概览中未显示的每种沙盒密钥类型调用一次 create_api_key — 每次调用仅创建一个密钥：type: PUBLISHABLE 和/或 type: SECRET，并设置 environment: SANDBOX（pk_test_… / sk_test_…）。密钥仅显示一次；请妥善保存。无法重新读取已有的密钥 — 如果丢失，请创建新密钥，并对旧密钥调用 revoke_api_key。
3. 仅当概览 / list_products 中没有匹配产品时，才调用 create_product — 例如名称 Pro、价格 499（整数新台币，不是分），周期 month（MCP 接受 month / year；只有下方的 CLI 标志使用 monthly），类型 SUBSCRIPTION。记下返回的产品 id（例如 cm5x… 这样的 CUID，而不是 prod_ 前缀）。

没有可用的 MCP？用户从控制面板获取密钥后，CLI 也能完成相同操作（app.recur.tw → 开發者 → API 金鑰）：

npx @recur-tw/cli login
npx @recur-tw/cli products create --name "Pro" --price 499 --interval monthly --type SUBSCRIPTION

真实银行卡扣款需要通过商户审核（准备就绪后从 app.recur.tw 申请）；其他所有功能都可在沙盒中端到端运行。

步骤 1：安装 SDK

pnpm add recur-tw
# or
npm install recur-tw

步骤 2：获取 API 密钥

使用步骤 0 中的沙盒密钥对（MCP create_api_key），或从控制面板复制一对，路径为 app.recur.tw → 開發者 → API 金鑰。

密钥格式：

• pk_test_xxx - 公钥（前端使用，可安全公开）
• sk_test_xxx - 密钥（仅限后端使用，绝不可公开）
• pk_live_xxx / sk_live_xxx - 生产环境密钥

要设置的环境变量：

NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY=pk_test_xxx   # frontend (Next.js needs the NEXT_PUBLIC_ prefix)
RECUR_SECRET_KEY=sk_test_xxx                   # backend only

步骤 3：添加 Provider（React）

使用 RecurProvider 包装应用：

'use client'

import { RecurProvider } from 'recur-tw'

export default function App({ children }) {
  return (
    <RecurProvider
      config={{
        publishableKey: process.env.NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY!,
      }}
    >
      {children}
    </RecurProvider>
  )
}

步骤 4：创建首个结账流程（托管式）

托管式结账会跳转到 checkout.recur.tw，且可在 localhost 上使用。（通过 useSubscribe() 使用模态框 / 嵌入式结账需要在 Provider 上设置 checkoutMode 并注册域名 — 详见 /recur-checkout。）

'use client'   // hooks + window: this must be a Client Component in the App Router

import { useState } from 'react'
import { useRecur } from 'recur-tw'

function PricingButton({ productId }: { productId: string }) {
  const { redirectToCheckout } = useRecur()
  const [redirecting, setRedirecting] = useState(false)   // redirectToCheckout does not set isCheckingOut

  const handleCheckout = async () => {
    setRedirecting(true)
    try {
      await redirectToCheckout({
        productId,                                 // the CUID from Step 0 (or productSlug)
        successUrl: `${window.location.origin}/success?session_id={CHECKOUT_SESSION_ID}`,
        cancelUrl: `${window.location.origin}/pricing`,
      })
    } catch (err) {
      setRedirecting(false)
      // Invalid key, unreachable API, bad product id — show it, don't swallow it
      console.error('Failed to start checkout:', err)
      alert('無法開始結帳，請稍後再試')
    }
  }

  return (
    <button onClick={handleCheckout} disabled={redirecting}>
      {redirecting ? 'Redirecting...' : 'Subscribe'}
    </button>
  )
}

结果会通过成功页面和 Webhook（步骤 5）返回，而不是通过回调返回。

步骤 5：设置 Webhook

创建一个 Webhook 端点来接收付款通知。详细说明请参阅 recur-webhooks 技能。

快速验证清单

• 已通过 MCP 连接 Recur 账号，并创建沙盒 API 密钥和产品（步骤 0）
• 已安装 SDK（pnpm list recur-tw）
• 已设置环境变量
• 应用已用 RecurProvider 包装
• 沙盒中的测试结账流程正常
• 已配置 Webhook 端点

常见问题

“Invalid API key”

• 检查密钥格式：必须以 pk_test_、sk_test_、pk_live_ 或 sk_live_ 开头
• 确保前端使用公钥，后端使用密钥

“未找到产品”

• 先创建一个：使用 MCP create_product、npx @recur-tw/cli products create 或控制面板
• 使用 list_products / npx @recur-tw/cli products list 返回的真实 id（类似 cm5x… 的 CUID；Recur 产品 ID 不带 prod_ 前缀），切勿使用占位符
• 检查是否使用了正确的环境（沙盒密钥还是生产密钥）

结账页面未显示

• 确保 RecurProvider 包裹了你的应用
• 检查浏览器控制台是否有错误
• 确认发布密钥正确

后续步骤

• /recur-checkout - 了解结账流程选项
• /recur-webhooks - 设置付款通知
• /recur-entitlements - 实现访问控制

资源

• Recur 文档
• 适用于每种 Agent 的 MCP 设置指南
• npm 上的 SDK
• npm 上的 CLI（@recur-tw/cli）
• API 参考