For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ja/docs/modules/billing-configuration.md (or send Accept: text/markdown).

Stripe 設定と webhook

Web サブスクリプションをサーバー側権限に接続する。

このガイドについて質問

インストールとセットアップ

手順の前に、始める前にとターミナルの基本をお読みください。これらの手順では、VS Code で完全な supastack モノリポジトリを開いたことが前提となっています。そのルート package.json はリポジトリのルートをマークします。 pnpm コマンドでは、ワークスペースパッケージはアプリまたは共有コードフォルダーです。この製品では、ワークスペースはチームのデータコンテナであり、セキュリティ境界です。 corepack pnpm --filter ... コマンドがルートから実行されている間にモノリポジトリから 1 つのパッケージを選択します。同期されたモバイルフォルダーまたはデスクトップフォルダーのみを開いた場合、そのフォルダーには Web バックエンド、Docker セットアップ、またはルートスクリプトが含まれていません。このモノリポジトリまたはアクセス可能なホストサーバーからバックエンドを実行し、プラットフォームフォルダー独自のスクリプトを使用します。環境変数は、ローカルの .env ファイルまたはホスティングダッシュボードに保存される名前付き設定です。変更後に関連するアプリを再起動し、NEXT_PUBLIC_ および EXPO_PUBLIC_ 値にサーバーシークレットが含まれないようにします。

1. apps/web/.env.local を開き、チェックアウト画面を学習しながら BILLING_PROVIDER=local を保持します。

2. 実際に統合するには、1 つのプロバイダーでテストモード製品を作成し、そのサーバーキーと Webhook シークレットを Web ホストのプライベート環境設定に追加します。 Webhook は、チェックアウト、更新、またはキャンセル後に課金サービスがアプリに送信する署名付きメッセージです。エンドポイントのパスは、このガイドのコード例にリストされています。

3. corepack pnpm --filter @supastack/web dev を使用して Web を起動し、サンドボックスのみをテストします。予期: 検証された Webhook により、サインインしたワークスペースの資格が更新されます。チェックアウトページを開いただけではアクセスは許可されません。

統合中にサンドボックス/テスト認証情報を使用します。 BILLING_PROVIDER とプロバイダーのサーバー専用シークレットを構成します: ストライプ → STRIPE_SECRET_KEY、STRIPE_PRICE_ID、STRIPE_WEBHOOK_SECRET;レモンスクイージー → LEMONSQUEEZY_API_KEY、LEMONSQUEEZY_STORE_ID、LEMONSQUEEZY_VARIANT_ID、LEMONSQUEEZY_WEBHOOK_SECRET;クリーム → CREEM_API_KEY、CREEM_PRODUCT_ID、CREEM_WEBHOOK_SECRET (サンドボックスの場合は CREEM_TEST_MODE=true);極 → POLAR_ACCESS_TOKEN、POLAR_PRODUCT_ID、POLAR_WEBHOOK_SECRET (POLAR_SERVER);誰 → WHOP_API_KEY、WHOP_PLAN_ID、WHOP_WEBHOOK_SECRET;パドル → PADDLE_API_KEY、PADDLE_PRICE_ID、PADDLE_WEBHOOK_SECRET (PADDLE_ENVIRONMENT);ドードー → DODO_PAYMENTS_API_KEY、DODO_PRODUCT_ID、DODO_PAYMENTS_WEBHOOK_KEY (DODO_PAYMENTS_ENVIRONMENT);ペイパル → PAYPAL_CLIENT_ID、PAYPAL_CLIENT_SECRET、PAYPAL_PLAN_ID、PAYPAL_WEBHOOK_ID (PAYPAL_ENVIRONMENT)。価格/製品は、意図した定期的なサブスクリプションを表す必要があります。

Webhook endpoint: /api/billing/webhook (stripe), /api/billing/webhook/lemonsqueezy, /api/billing/webhook/creem, /api/billing/webhook/polar, /api/billing/webhook/whop, /api/billing/webhook/paddle, /api/billing/webhook/dodo, /api/billing/webhook/paypal
Checkout endpoint: /api/billing/checkout
Portal endpoint: /api/billing/portal

コピーするコマンド

コメントに従って、コマンドがどのフォルダーで実行されるかを確認します。 2 つのターミナルにラベルが付いている場合は、2 つのターミナルウィンドウを開き、2 番目のコマンドを使用している間、最初のコマンドを実行し続けます。

corepack pnpm --filter @supastack/web dev

実装ワークフロー

webhook エンドポイントの設定には docs/real-provider-smoke.md のライフサイクルイベントリストに従ってください。署名検証にはエンドポイントに対応する webhook シークレットが必要です。チェックアウトリダイレクト単体はアクセスを許可してはいけません。

サーバーアクション境界の権限が有料作業が許可されるかを決めます。繰り返しイベントを安全に処理し、顧客/サブスクリプションレコードを正しいワークスペースにスコープします。Web チェックアウトはネイティブ購入と分離されたままです。

プランが付与するキーは、サーフェス間で共有される製品ボキャブラリーです。 src/product-plans.ts の ProductPlan.entitlement は、プランの支払い中に台帳に書き込まれる小文字のマシンキーを宣言します (キットにはプロおよびライフタイムに「ai.reference-task」が同梱されます。src/billing-runtime.ts はそれを BFF に渡します)。同じキーが、CMS エントリの required_entitlement フィールドと EntitlementGate コンポーネントの entitlementKey プロパティの等価比較の対象になります。「ai.reference-task」でゲートされたエントリは、その権限を保持しているすべてのワークスペースのロックを解除しますが、プランが権限を付与していないキーは全員に対してロックされたままになります。

検証とトラブルシューティング

Webhook が拒否された場合は、プロバイダーダッシュボードの正確なサンドボックス URL と署名シークレットをサーバー設定と比較し、そのプロバイダーがリクエストを localhost に転送する必要があるかどうかを確認します。チェックアウトは機能するが、アクセスがロックされたままの場合は、Webhook の結果とプランの資格キーを検査してください。このローカルガイドに従っている間は、ライブ支払い認証情報を使用してテストしないでください。

サンドボックスで有効化、更新、キャンセル、無効な署名、繰り返しイベントをテストします。処理後の永続化されたアクセス状態を検査します。消費されないチェックアウトセッションの作成は接続性のみを証明し、ライフサイクルフルフィルメントではありません。