Next.js に Stripe サブスクを導入する 2026 完全ガイド:Webhook まで
Next.js で Stripe サブスクリプションを導入し、本番で壊れない最短ルートです。動く部品は四つ、無駄はありません——さらに、ほとんどのガイドが省略する検証の詳細も含めます。
サブスク連携が失敗するのは、たいてい正常系ではありません。顧客が購読をクリックし、Checkout Session が作られ、Webhook が飛んで、データベースのフラグが反転する。これはどのチュートリアルでも動きます。壊れるのはその周辺です:偽造 Webhook が 200 で受け入れられる、リトライされたイベントが二回適用される、解約後にプランが戻らない、秘密鍵が誤ってブラウザに配られる、といった具合です。このガイドは失敗ケースを含めたループ全体を扱います。

前提条件
コードを書く前に三つ必要です:
- App Router を使う Next.js 15 プロジェクト。新規なら App Router ドキュメントが基準です。
- テストモードの Stripe アカウントと、シークレットキーおよび Webhook 署名シークレット。
plan列を持つ users テーブル、または別の subscriptions テーブルで、サーバーから書き込めるもの。
環境変数は一度で設定し、テストと本番の認証情報を別環境に保ちます:
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_PRO=price_...
NEXT_PUBLIC_APP_URL=http://localhost:3000Stripe のシークレットに NEXT_PUBLIC_ を付けてはいけません。この接頭辞の付く変数はブラウザバンドルに埋め込まれ、定義上公開されます。クライアントの秘密鍵はショートカットではなく、公開済みの認証情報です。
ステップ 1:製品と価格を作成する
Stripe ダッシュボードで、周期価格を持つ Product を作ります。たとえば Pro を月 12 ドル。Price ID を STRIPE_PRICE_ID_PRO にコピーし、ソースにハードコードしないでください。Price ID はテストと本番で異なるため、テスト価格をハードコードすると静かな本番バグになります:チェックアウトは正常に見えても金額や通貨が違うのです。
自社のプラン名と価格 ID の対応表を短く持っておくと、地域別や段階別の価格変更がコード変更ではなくデータ変更になります。プランはコードの分岐ではなくデータとしてモデル化しましょう。id、priceId、entitlements を持つ PLANS オブジェクトがあれば、機能ゲートはプラン名ではなく canExport や seats のようなケイパビリティを調べられ、段階名を変えてもすべてのルートに触れずに済みます。年払いも簡単で、同じプランに第二の価格 ID を追加し、検証済みリクエストからチェックアウトルートが選べばよいのです。

ステップ 2:SDK をインストールして設定する
npm install stripe で公式サーバー SDK を入れます。モジュールスコープでクライアントを一つ生成し、初期化を一度きりにします:
import Stripe from "stripe";
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
apiVersion: "2025-02-24.acacia",
});API バージョンはコードで固定し、浮動させないでください。Stripe が新しいバージョンを出したとき、変更ログを読んで意図的に採用するのであって、請求書で挙動の変化を知るのではありません。
ステップ 3:チェックアウトルート
POST /api/checkout は要求されたプランを読み、価格 ID を解決し、mode: "subscription"、ユーザーの client_reference_id、明示的な success_url と cancel_url を持つ Checkout Session を作ります。ホストされた URL をブラウザに返します。明確な理由がなければ、自前の決済フォームは作らないでください。
セッション作成前にログイン済みユーザーを要求します。ゲスト checkout では権限を与える相手がいません:Webhook はユーザー ID か決済メールで権限を与えるので、どちらもアカウントに一致しなければライセンスの所有者がいないのです。ルートハンドラーではクライアントから渡されたユーザー ID ではなく、cookies からセッションを読みます。
export async function POST(req: Request) {
const user = await getSessionUser(); // サーバー側、cookies から
if (!user) return Response.json({ error: "unauthorized" }, { status: 401 });
const { plan } = await req.json();
const priceId = PLANS[plan]?.priceId; // 環境変数から、クライアントからは絶対に取らない
if (!priceId) return Response.json({ error: "bad plan" }, { status: 400 });
const session = await stripe.checkout.sessions.create({
mode: "subscription",
line_items: [{ price: priceId, quantity: 1 }],
client_reference_id: user.id,
customer_email: user.email,
success_url: `${APP_URL}/billing?status=success`,
cancel_url: `${APP_URL}/billing?status=cancel`,
});
return Response.json({ url: session.url });
}重要なのは二点です。価格は環境変数から取り、リクエストボディからは絶対に取りません。そうしないとクライアントが 1 ドルでエンタープライズ価格を選べてしまいます。もう一つは二つの URL を明示することで、デフォルトに頼ると支払い後に Stripe 所有のページへ送られます。セッションの全オプションは Checkout Sessions API リファレンスにあります。

ステップ 4:Webhook が真相の源
ブラウザは信頼できません。「支払い成功」とクライアントが言っても何も証明になりません。Stripe が署名した Webhook が権威あるシグナルです。JSON を解析する前に、Stripe-Signature ヘッダーで生の body を検証します:
export async function POST(req: Request) {
const sig = req.headers.get("stripe-signature");
if (!sig) return new Response("missing signature", { status: 400 });
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(
await req.text(), // 正確な生バイト
sig,
process.env.STRIPE_WEBHOOK_SECRET!
);
} catch {
return new Response("invalid signature", { status: 400 });
}
if (await alreadyProcessed(event.id)) return new Response(null, { status: 200 });
await markProcessed(event.id);
switch (event.type) {
case "checkout.session.completed":
await grantPlan(event.data.object.client_reference_id, "pro");
break;
case "customer.subscription.deleted":
await revokePlan(event.data.object.metadata.userId);
break;
}
return new Response(null, { status: 200 });
}先に解析して再シリアライズするとバイトが変わり、HMAC 検証が壊れます。検証失敗——ヘッダー欠落、HMAC 不正、JSON 破損——は例外を投げて HTTP 400 にしなければなりません。偽造リクエストを 200 で acknowledgement するのは無害な no-op ではなくセキュリティバグです。署名方式は Webhook 署名検証に、イベントの全カタログは Webhook イベント種別にあります。
無視されたイベントと失敗したイベントは別物です。正しく署名されているが自分たちが扱わないイベントは、記録して ignored フラグ付きの 200 で返すべきです。検証失敗に 200-ignored を使ってはいけません。

ステップ 5:Webhook を冪等にする
Stripe は Webhook を再試行します。リプレイ対策がなければ、一回の支払いが二回のアップグレードになり、解約が幽灵の返金になります。処理済みイベント ID を event_id に一意制約のあるテーブルに記録し、効果を適用する前に挿入します:
create table processed_events (
event_id text primary key,
received_at timestamptz not null default now()
);挿入そのものがロックです。並行するリトライが同じ ID を使うと、主キー衝突がスキップを教えてくれます。「確認して印を付ける」は読み取りと書き込みに分けず、一つの原子的ステップで行いましょう。そうしないと競合の窓が残ります。セッション作成時に userId をサブスクの metadata に付けておけば、解約イベントがメール検索なしで正しいアカウントを見つけられます。
テンプレートを使う前に確認したい点がもう一つあります。解約 Webhook をそもそも扱っているか? 多くのテンプレートは checkout.session.completed だけを扱い、customer.subscription.deleted を忘れるため、解約後も顧客が権限を持ち続けます。コード内で二つのイベント種別を検索し、片方しかなければ最初の入金前に追加してください。

ステップ 6:機能ゲート
すべての保護されたルートと Server Action で、プランはデータベースから読みます——クライアント状態からも、チェックアウト後に自分で設定した cookie からも絶対に読みません。プランが無効なら 402 を返します。AI エンドポイント、ZIP ダウンロード、席数制限はすべてこの一つのチェックにぶら下がります:
export async function requirePro() {
const user = await getSessionUser();
if (!user) throw new HttpError(401);
const { data } = await supabase
.from("profiles")
.select("plan")
.eq("id", user.id)
.single();
if (data?.plan !== "pro") throw new HttpError(402, "Upgrade required");
}ボタンを隠すクライアント側チェックは UX であってセキュリティではありません。効くのはサーバーのチェックです。ルートハンドラーではなく Server Action の中で行う場合もルールは同じで、Server Actions ドキュメントに変更をサーバーに留める方法が説明されています。

ステップ 7:顧客に管理と解約を任せる
カスタマーポータルを使えば、解約のたびにサポートチケットが飛ぶのを防げます。サーバー側で Billing Portal セッションを作成し、ユーザーをリダイレクトします。ポータルがカード更新、プラン変更、解約を扱い、Stripe が対応する Webhook を飛ばすので、追加コードなしでデータベースが同期します。周期途中のアップグレードの日割りも向こうが計算してくれるので、タイムスタンプから自前で計算しないでください。
ステップ 8:ループ全体をテストする
テストモードとカード番号 4242 4242 4242 4242 を使い、有効期限は未来の任意の日付、CVC は任意の値にします:
- チェックアウトを完了し、プランがデータベースで反転することを確認。
- ポータルで解約し、戻ることを確認。
- 捕捉した
checkout.session.completedイベントをリプレイし、一度だけ適用されることを確認。 - 署名を壊した Webhook を送り、400 が返ることを確認(200 ではない)。
- 無料ユーザーで Pro エンドポイントを呼び、402 を確認。
ローカルでの受け取りは Stripe CLI で転送できます(stripe listen --forward-to localhost:3000/api/webhooks)。表示された署名シークレットを STRIPE_WEBHOOK_SECRET にコピーしてください。CI が Preview をデプロイしているなら、専用の Webhook エンドポイントとシークレットを持つ Preview URL でテストする方がきれいです。
一つの env ファイルでループが動くなら、あなたの課金は本物です。どこかのステップを「仕上げる」ために手作業で DB を書き換える必要があるなら、まだ完成ではありません。

よくある失敗
| 症状 | 考えられる原因 | 修正 | | --- | --- | --- | | すべての Webhook が 400 | 署名シークレットが違う、または検証前に解析している | 生 body と対応するエンドポイントのシークレットを使う | | プランが反転しない | イベントは処理されたが client_reference_id が空 | セッション作成前にログインを要求 | | プランが二回反転する | イベント ID に冪等性がない | event_id 一意テーブル、適用前に原子的挿入 | | ローカルは動くが本番で動かない | 本番 env にテストキーやテスト Price ID | テストと本番を分離し、起動時にキーを検証 | | 無料ユーザーがゲートを通る | クライアント状態を真相としている | 毎回リクエストで DB からプランを読む |
テンプレートが役立つ場所
良いテンプレートならステップ 3〜6 が配線済みで、かつプロバイダ非依存のインターフェースの後ろに置かれています。新しい地域のために Creem、PayPal、Waffo、Lemon Squeezy を追加するとき、これは効きます:アプリ全体のチェックアウトと Webhook を書き直す代わりに、新しいアダプターを書けばよいのです。Uncorne は一つのチェックアウトと Webhook 契約の後ろに五つのプロバイダーアダプターを同梱しており、上記の Stripe ルートがリファレンス実装です。
検証ルールはプロバイダーが変わっても変わりません。生バイトに署名検証をかけ、イベント ID を重複排除し、書き込みはサーバーだけで行い、機能ゲートはサーバーに置く。まず Stripe でこれらを覚えれば、そのまま移転できます。より深いアーキテクチャの理由は Next.js で SaaS を構築する方法に書いてあります。
正直なまとめ
Next.js の Stripe サブスクは四つの部品です:ダッシュボードの製品と価格、ログイン済みユーザーを要求するチェックアウトルート、解析前に検証し書き込み前に重複排除する Webhook、そしてサーバー側のプランゲート。この四つを正しく作れば、正常系はほとんど退屈になる——それこそ課金機能に求められる姿です。地域別価格から二つ目のゲートウェイまで、それ以外はすべてこのループの上のアダプターにすぎません。
FAQ
検証前に Webhook の body を解析してもよいですか?+
いいえ。まず Stripe-Signature ヘッダーで正確な生バイトを検証し、その後に解析します。先に解析して再シリアライズするとバイトが変わり HMAC 検証が壊れ、400 を返すべきです。
なぜゲスト checkout では権限を与えられないのですか?+
Webhook はユーザー ID か決済メールで権限を与えます。ログインしておらず、決済メールもアカウントに一致しない場合、ライセンスに所有者がいません。Checkout Session 作成前にログインを要求してください。
無視された Webhook レスポンスとは何ですか?+
200 と ignored フラグは、イベントが正しく署名されているが自分たちが扱わない種類だという意味です。検証失敗(400 であるべき)に使ってはいけません。無視したイベントは記録し、失敗と区別できるようにしましょう。
リトライされた Webhook でユーザーが二回アップグレードされるのを防ぐには?+
処理済みイベント ID を event_id に一意制約のあるテーブルに保存し、効果を適用する前に原子的に挿入します。リトライが来ると主キー衝突がスキップを教えてくれます。読み取り後の書き込みでは競合の窓が残ります。
Stripe Checkout と埋め込み決済エレメント、どちらを使うべき?+
まずはホスト型 Checkout を使ってください。サブスクへの最短ルートで、決済 UI は Stripe がホストします。自社ページ内で決済体験を管理する必要が出てきたときだけ埋め込みエレメントに移行します。Webhook のロジックはどちらも同じです。