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/web/stripe-payments.md (or send Accept: text/markdown).

Stripe 決済を追加

無料の Stripe アカウント、定期価格のプロダクト、シークレットキー、そしてチェックアウト後にエンタイトルメントを付与する署名付き webhook を作成します。

このガイドについて質問

初心者向けのウォークスルー

前提条件:ローカルで動作するアプリ(5 分で公開)と、実アカウント用の移行済みデータベース(データベースのセットアップ)。Stripe アカウント用のメールアドレスが必要です——カードも課金も不要です。このガイドのすべてはテストモードで行います:偽のお金、テストカード番号、本番化前の無制限の再試行です。

用語メモ:テストモードは Stripe のサンドボックスです——ダッシュボードの Test mode トグルが、オフにするまですべてのキー・プロダクト・支払いを偽物に保ちます。シークレットキー(sk_test_…)は Stripe に対するサーバーのパスワードです。価格付きプロダクトは顧客が買うもので、price id(price_…)がコード内でそれを指名します。webhook は支払い成功やサブスクリプション変更時に Stripe がサーバーを呼び出すもので、署名シークレット(whsec_…)がその呼び出しが本当に Stripe からであることを証明します。

作成するもの:Stripe アカウント、定期価格を持つ 1 つのプロダクト、シークレット API キー、webhook エンドポイント——約 20 分です。チェックアウトページ自体は Stripe がホストします。キットはサーバーサイドでセッションを作成してリダイレクトするため、公開用ブラウザキーは不要です。

範囲を意識してください:このガイドは Web のサブスクリプションのみを販売します。iOS/Android アプリ内の購入は Apple と Google の課金を経由しなければならず——Stripe Checkout は不可——モバイルが RevenueCat を使うのはそのためです。

Stripe アカウントを作成する

1. stripe.com → Start now を開き、メールでサインアップします。

2. オンボーディングは事業について尋ねます——テストモードではすべての質問をスキップしても完全なサンドボックスを使えます。実際の支払いを受ける前にのみアクティベーションを完了してください。

期待される結果:ヘッダーに Test mode トグルが見えるダッシュボードに着地します。以下のすべてでオンのままにしてください——ライブキーは後で本番のシークレットストアに入れるもので、ノート PC の env ファイルには入れません。

API キーをコピーする

1. ダッシュボードで Developers → API keys を開きます。

2. 2 つのテストキーが見えます:Publishable key pk_test_… と、マスクされた Secret key。シークレットの横の Reveal test key をクリックし、sk_test_… の値をコピーします。

キットが必要とするのはシークレットキーだけです:チェックアウトセッションはサーバーで作成され、ユーザーは Stripe のホストページにリダイレクトされるため、公開キーは env 変数に入りません。後で自作するプロダクトが Stripe.js を追加するならクライアント側で公開キーを使いますが、キットの課金フローでは使いません。

sk_test_… キーはサンドボックスアカウントの完全な認証情報です:apps/web/.env.local かシークレットストアに置き、NEXT_PUBLIC_/EXPO_PUBLIC_ 変数にも Git にも決して入れません。

プロダクトと価格を作成する

1. Product catalog → Add product を開きます。

2. プランにちなんだ名前を付けます——Pro はキット同梱のプランに一致します——価格を付け、Recurring(たとえば月額)を選びます:キットのチェックアウトはサブスクリプションモードのセッションを作成するため、一回払いではなく定期価格が必要です。

3. 保存してプロダクトを開き、price id をコピーします——price_… で始まります(プロダクト ID の prod_… ではありません)。

同梱の pro プランはすでに Monthly/Yearly トグルを表示しています:月額は STRIPE_PRICE_ID でチェックアウトし、年額オプションには STRIPE_PRICE_ID_PRO_YEARLY の 2 つ目の定期価格が必要です——ない場合、年額チェックアウトは price-unconfigured で失敗します。プラン名・金額・購入が付与するものは apps/web/src/product-plans.ts で変更します——Stripe はお金の側を保持し、プランファイルはエンタイトルメントの側を保持します。

webhook エンドポイントを追加する

webhook が実際にアクセスを付与するものです:キットは署名付き Stripe イベントが到着して初めてエンタイトルメントを反転するため、チェックアウトのリダイレクトだけでは何も証明されません。

1. Developers → Webhooks → Add endpoint を開きます。

2. Endpoint URL: 公開 URL に /api/billing/webhook を付けたもの——たとえば https://yourdomain.com/api/billing/webhook。他の課金プロバイダーはそのディレクトリ下の独自パスを持ち、Stripe のレシーバーはルートにあります。

3. Select events で、キットが処理するイベントを選びます:checkout.session.completed、checkout.session.async_payment_succeeded、checkout.session.async_payment_failed、invoice.paid、invoice.payment_failed、customer.subscription.created、customer.subscription.updated、customer.subscription.deleted。

4. エンドポイントを作成してページを開き、Signing secret の下の Reveal をクリックし、whsec_… の値をコピーします——エンドポイントごとに独自のシークレットがあります。

ローカル開発では Stripe のサーバーを受信できないため、代わりに Stripe CLI を使います:一度 stripe login し、別ターミナルで stripe listen --forward-to localhost:3000/api/billing/webhook を実行します。一時的な whsec_… が表示されます——stripe listen の実行中は、ダッシュボードの値ではなくその値が .env.local に入ります。

値をアプリに追加する

以下の行を apps/web/.env.local に設定します。BILLING_PROVIDER=stripe がアダプターを選択し、残りの 3 つはキー・価格・署名シークレットです。これらのどれかが欠けた状態でプロバイダーを有効にすると起動が失敗し、その変数が名指しされます。

3 つの STRIPE_* 値はすべてサーバー専用です——NEXT_PUBLIC_/EXPO_PUBLIC_ には入れず、コミットもしません。本番ではホストのシークレットマネージャー経由で渡します(デプロイガイドが Secret Manager を扱っています)。編集後は開発サーバーを再起動してください。

# apps/web/.env.local
BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_…
STRIPE_PRICE_ID=price_…
STRIPE_WEBHOOK_SECRET=whsec_…   # `stripe listen` value locally; endpoint signing secret in production
# STRIPE_PRICE_ID_PRO_YEARLY=price_…   # required for the shipped Yearly toggle

確認とトラブルシューティング

stripe listen --forward-to localhost:3000/api/billing/webhook を起動して実行したままにし、開発サーバーを再起動してから /billing を開き、Pro プランを選び、テストカード 4242 4242 4242 4242、将来の有効期限、任意の CVC で Stripe のホストチェックアウトを完了します。

期待される結果:アプリが /billing?checkout=success に戻り、ワークスペースのエンタイトルメントがアクティブに反転します——listen ターミナルが配信されたイベントをログに出し、ダッシュボードの Developers → Webhooks → そのエンドポイントに緑の配信が表示されます。

チェックアウトをクリックせずにレシーバーを試すには、stripe trigger checkout.session.completed が listen フォワーダー経由で合成イベントを送ります。

よくある失敗:すべての配信で 400 が返るのは署名シークレットがそのエンドポイントと一致しないことを意味します——正しいエンドポイントの whsec_… をコピーし直して env を更新してください。静かな無反応は BILLING_PROVIDER がまだ local のままであることを意味します。テスト環境に sk_live_ キーが混ざっているのは誤ったモードのキーをコピーしたことを意味します——テストとライブは厳密に分けてください。

キットは Lemon Squeezy、Creem、Polar、Whop、Paddle、Dodo、PayPal にも同じ 1 コントラクトのアダプターを同梱しています——同じフローで、コンソールと env 名が異なるだけです。モバイル購入は Stripe ではなく RevenueCat に留まります。