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 は実行しないでください。2 つ目の 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 — すでに存在する SANDBOX キーとプロダクトの一覧を取得します。 既存のものを再利用し、不足しているものだけを作成してください（作成の呼び出しごとに 新しい行が追加されるため、このステップを確認せずに再実行すると重複が発生します）。
2. 概要に表示されない SANDBOX キータイプごとに create_api_key を実行します。呼び出し 1 回につきキーが 1 つ作成されます。environment: SANDBOX（pk_test_… / sk_test_…） を指定し、type: PUBLISHABLE および／または type: SECRET を設定します。シークレットキーは 一度だけ表示されるため、保管してください。既存のシークレットキーを再度読み取ることは できません。紛失した場合は新しいキーを作成し、古いキーを revoke_api_key で失効させてください。
3. 概要または list_products に一致するプロダクトがない場合に限り、create_product を実行します。 例：名前 Pro、価格 499（TWD の整数であり、セント単位ではありません）、間隔 month（MCP では month / year を使用します。下記の CLI フラグのみ monthly と表記します）、 タイプ SUBSCRIPTION。返されたプロダクトの id を控えてください（prod_ プレフィックス ではなく、cm5x… のような CUID です）。

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 の SANDBOX キーペア（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：プロバイダーを追加する（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() によるモーダル／埋め込みチェックアウトには、プロバイダーで 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 エンドポイントを設定した

よくある問題

「無効な API キー」

• キーの形式を確認してください。pk_test_、sk_test_、pk_live_、または sk_live_ で始まる必要があります。
• フロントエンドにはパブリッシャブルキー、バックエンドにはシークレットキーを使用していることを確認してください。

「Product not found」

• まず作成してください：MCP の create_product、npx @recur-tw/cli products create、またはダッシュボードを使用します
• list_products / npx @recur-tw/cli products list が返す実際の id（cm5x… のような CUID）を使用してください（Recur のプロダクト ID に prod_ プレフィックスはありません）。プレースホルダーは使用しないでください
• 正しい環境（sandbox と production のキー）を使用していることを確認してください

チェックアウトが表示されない場合

• RecurProvider がアプリをラップしていることを確認してください
• ブラウザーのコンソールにエラーがないか確認してください
• 公開可能キーが正しいことを確認してください

次のステップ

• /recur-checkout - チェックアウトフローのオプションについて確認する
• /recur-webhooks - 支払い通知を設定する
• /recur-entitlements - アクセス制御を実装する

リソース

• Recur のドキュメント
• あらゆるエージェント向けの MCP セットアップ
• npm の SDK
• npm の CLI（@recur-tw/cli）
• API リファレンス