Stripe Payments

Webアプリに Stripe による決済機能を追加します。一般的なパターン — ワンタイム支払い、サブスクリプション、webhook、カスタマーポータル — を実装コード付きでカバーします。MCP サーバーは不要です。

どの Stripe API が必要か？

やりたいこと	使用する API	複雑度
ワンタイム支払いを受け取る	Checkout Sessions	低 — Stripe が支払いページをホスト
UI に支払いフォームを埋め込む	Payment Element + Payment Intents	中程度 — フォームはあなたが構築、カード処理は Stripe
定期請求 / サブスクリプション	Checkout Sessions (subscription mode)	低～中程度
後で使用するためカードを保存	Setup Intents	低
マーケットプレイス / プラットフォーム支払い	Stripe Connect	高
顧客に請求を管理させる	Customer Portal	低 — Stripe がホスト

デフォルトの推奨: Checkout Sessions から始めましょう。お金を受け取るための最速パスです。後から埋め込みフォームを追加できます。

セットアップ

インストール

npm install stripe @stripe/stripe-js

API キー

# キーを取得: https://dashboard.stripe.com/apikeys
# テストキーは sk_test_ と pk_test_ で始まる
# ライブキーは sk_live_ と pk_live_ で始まる

# Cloudflare Workers の場合 — シークレットとして保存:
npx wrangler secret put STRIPE_SECRET_KEY
npx wrangler secret put STRIPE_WEBHOOK_SECRET

# ローカル開発 — .dev.vars:
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PUBLISHABLE_KEY=pk_test_...

サーバーサイド クライアント

import Stripe from 'stripe';

// Cloudflare Workers
const stripe = new Stripe(c.env.STRIPE_SECRET_KEY);

// Node.js
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

ワンタイム支払い (Checkout Sessions)

支払いを受け取る最速の方法。Stripe がチェックアウトページ全体をホストします。

Checkout Session を作成 (サーバー)

app.post('/api/checkout', async (c) => {
  const { priceId, successUrl, cancelUrl } = await c.req.json();

  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: successUrl || `${new URL(c.req.url).origin}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: cancelUrl || `${new URL(c.req.url).origin}/pricing`,
  });

  return c.json({ url: session.url });
});

Checkout にリダイレクト (クライアント)

async function handleCheckout(priceId: string) {
  const res = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ priceId }),
  });
  const { url } = await res.json();
  window.location.href = url;
}

商品と価格を作成

# Stripe CLI 経由 (セットアップに推奨)
stripe products create --name="Pro Plan" --description="Full access"
stripe prices create --product=prod_XXX --unit-amount=2900 --currency=aud --recurring[interval]=month

# またはダッシュボード: https://dashboard.stripe.com/products

価格 ID をハードコード (変わることはない)：

const PRICES = {
  pro_monthly: 'price_1234567890',
  pro_yearly: 'price_0987654321',
} as const;

サブスクリプション

ワンタイムと同じですが mode: 'subscription' で:

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: PRICES.pro_monthly, quantity: 1 }],
  success_url: `${origin}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${origin}/pricing`,
  // 既知の顧客にリンク:
  customer: customerId, // または customer_email: 'user@example.com'
});

サブスクリプション ステータスをチェック

async function hasActiveSubscription(customerId: string): Promise<boolean> {
  const subs = await stripe.subscriptions.list({
    customer: customerId,
    status: 'active',
    limit: 1,
  });
  return subs.data.length > 0;
}

Webhook

Stripe は何かが起きた時 (支払い成功、サブスクリプション キャンセルなど) にサーバーへイベントを送信します。webhook 署名を検証する必要があります。

Webhook ハンドラー (Cloudflare Workers / Hono)

app.post('/api/webhooks/stripe', async (c) => {
  const body = await c.req.text();
  const sig = c.req.header('stripe-signature')!;

  let event: Stripe.Event;
  try {
    // Workers には Node crypto がないため constructEventAsync を使用
    event = await stripe.webhooks.constructEventAsync(
      body,
      sig,
      c.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    console.error('Webhook signature verification failed:', err);
    return c.json({ error: 'Invalid signature' }, 400);
  }

  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session;
      // 注文を履行 — データベース更新、メール送信、アクセス許可
      await handleCheckoutComplete(session);
      break;
    }
    case 'customer.subscription.updated': {
      const sub = event.data.object as Stripe.Subscription;
      await handleSubscriptionChange(sub);
      break;
    }
    case 'customer.subscription.deleted': {
      const sub = event.data.object as Stripe.Subscription;
      await handleSubscriptionCancelled(sub);
      break;
    }
    case 'invoice.payment_failed': {
      const invoice = event.data.object as Stripe.Invoice;
      await handlePaymentFailed(invoice);
      break;
    }
  }

  return c.json({ received: true });
});

Webhook を登録

# Stripe CLI でローカルテスト:
stripe listen --forward-to http://localhost:8787/api/webhooks/stripe

# 本番環境 — ダッシュボード経由で登録:
# https://dashboard.stripe.com/webhooks
# URL: https://yourapp.com/api/webhooks/stripe
# イベント: checkout.session.completed, customer.subscription.updated,
#          customer.subscription.deleted, invoice.payment_failed

Cloudflare Workers の注意点

constructEvent (同期) は Node.js crypto を使用しますが、Workers には存在しません。代わりに constructEventAsync を使用してください — Web Crypto API を使用します。

カスタマーポータル

顧客が自分のサブスクリプションを管理できるようにします (アップグレード、ダウングレード、キャンセル、支払い方法更新):

app.post('/api/billing/portal', async (c) => {
  const { customerId } = await c.req.json();

  const session = await stripe.billingPortal.sessions.create({
    customer: customerId,
    return_url: `${new URL(c.req.url).origin}/dashboard`,
  });

  return c.json({ url: session.url });
});

ダッシュボードでポータルを構成: https://dashboard.stripe.com/settings/billing/portal

価格設定ページ パターン

Stripe 商品から読み取った価格設定ページを生成:

// サーバー: 商品と価格を取得
app.get('/api/pricing', async (c) => {
  const prices = await stripe.prices.list({
    active: true,
    expand: ['data.product'],
    type: 'recurring',
  });

  return c.json(prices.data.map(price => ({
    id: price.id,
    name: (price.product as Stripe.Product).name,
    description: (price.product as Stripe.Product).description,
    amount: price.unit_amount,
    currency: price.currency,
    interval: price.recurring?.interval,
  })));
});

またはプランが 2-3 個だけの場合はハードコード — よりシンプルで、ページロードのたびに API 呼び出しがありません。

Stripe CLI (ローカル開発)

# インストール
brew install stripe/stripe-cli/stripe

# ログイン
stripe login

# ローカルで webhook をリッスン
stripe listen --forward-to http://localhost:8787/api/webhooks/stripe

# テストイベントをトリガー
stripe trigger checkout.session.completed
stripe trigger customer.subscription.created
stripe trigger invoice.payment_failed

よくあるパターン

Stripe カスタマーをあなたのユーザーにリンク

// 最初のチェックアウト時に、カスタマーを作成または検索:
const session = await stripe.checkout.sessions.create({
  customer_email: user.email,  // 存在しない場合は新しいカスタマーを作成
  // または
  customer: user.stripeCustomerId,  // 既存を使用
  metadata: { userId: user.id },  // あなたのユーザーにリンク
  // ...
});

// webhook で顧客 ID を保存:
case 'checkout.session.completed': {
  const session = event.data.object;
  await db.update(users)
    .set({ stripeCustomerId: session.customer as string })
    .where(eq(users.id, session.metadata.userId));
}

無料トライアル

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: PRICES.pro_monthly, quantity: 1 }],
  subscription_data: {
    trial_period_days: 14,
  },
  // ...
});

オーストラリア ドル

// 価格を作成時に通貨を設定
const price = await stripe.prices.create({
  product: 'prod_XXX',
  unit_amount: 2900,  // セント単位で $29.00
  currency: 'aud',
  recurring: { interval: 'month' },
});

注意点

注意点	解決策
Workers で constructEvent が失敗	constructEventAsync を使用 (Web Crypto API)
Webhook は発火しているがハンドラーが呼ばれない	エンドポイント URL が完全に一致することを確認 (末尾のスラッシュは重要)
テストモードの支払いが表示されない	sk_test_ キーを使用していることを確認、sk_live_ ではなく
価格金額はセント単位	2900 = $29.00。表示時は常に 100 で割る
顧客メールがユーザーと一致しない	再度訪問するユーザーには customer_email ではなく customer (既存 ID) を使用
サブスクリプション ステータスが古い	キャッシュしない — API 経由でチェックまたは webhook イベントを信頼
Webhook 再試行	Stripe は失敗した webhook を最大 3 日間再試行。すぐに 200 を返す
checkout リダイレクト時の CORS	Checkout URL は stripe.com にある — fetch ではなく window.location.href を使用