Stripe 決済ガイド

Stripe 決済の導入から運用までをカバーする。

API キー管理

キーの種類

1Password Environment への保存

ローカル開発用の値は既存の 1Password Environment に保存する。vault item は作らない。

• STRIPEPUBLISHABLEKEY
• STRIPESECRETKEY
• STRIPEWEBHOOKSECRET

追加・更新には $onepassword-environment-secrets を使い、実行時は op run --environment "$OPENVIRONMENTID" -- <command> で注入する。

Cloudflare Workers への設定

公開キーは wrangler.toml の [vars] に、秘匿キーは Worker secret に設定する。Cloudflare 操作には 1Password を使わず、Wrangler の OAuth セッションを使う。

[vars]
STRIPE_PUBLISHABLE_KEY = "pk_live_xxx"

wrangler whoami
wrangler secret put STRIPE_SECRET_KEY
wrangler secret put STRIPE_WEBHOOK_SECRET

Webhook 設定

Stripe Dashboard での設定

1. https://dashboard.stripe.com/webhooks
2. 「エンドポイントを追加」
3. URL: https://example.com/api/webhook
4. イベント: checkout.session.completed を選択
5. Webhook シークレット（whsec_*）をコピーして保存

Webhook ハンドラー実装（Hono + Cloudflare Workers）

import Stripe from "stripe";

webhookRoutes.post("/", async (c) => {
  const stripe = new Stripe(c.env.STRIPE_SECRET_KEY, {
    httpClient: Stripe.createFetchHttpClient(),
  });

  const signature = c.req.header("stripe-signature");
  if (!signature) {
    return c.json({ error: "Missing signature" }, 400);
  }

  const body = await c.req.text();

  let event: Stripe.Event;
  try {
    event = await stripe.webhooks.constructEventAsync(
      body,
      signature,
      c.env.STRIPE_WEBHOOK_SECRET,
      undefined,
      Stripe.createSubtleCryptoProvider(),
    );
  } catch {
    return c.json({ error: "Invalid signature" }, 400);
  }

  if (event.type === "checkout.session.completed") {
    const session = event.data.object as Stripe.Checkout.Session;
    // 注文処理
  }

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

Checkout Session 作成

const stripe = new Stripe(c.env.STRIPE_SECRET_KEY, {
  httpClient: Stripe.createFetchHttpClient(),
});

const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: [
    {
      price_data: {
        currency: "jpy",
        product_data: { name: "商品名" },
        unit_amount: 1000,
      },
      quantity: 1,
    },
  ],
  success_url: `${c.env.SITE_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${c.env.SITE_URL}/cancel`,
  metadata: {
    userId: "xxx",
    // カスタムデータ
  },
});

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

決済テスト

最低決済額

テスト用商品は最低額で作成する。

テストカード（テストモード用）

有効期限: 将来の任意の日付、CVC: 任意の 3 桁

返金処理

CLI から返金

# 1. Stripe セッション ID から payment_intent を取得
curl -s -u "sk_live_xxx:" "https://api.stripe.com/v1/checkout/sessions/cs_live_xxx" | jq -r '.payment_intent'

# 2. 返金実行
curl -s -X POST "https://api.stripe.com/v1/refunds" \
  -H "Authorization: Bearer sk_live_xxx" \
  -d "payment_intent=pi_xxx" | jq '{id, status, amount}'

部分返金

curl -s -X POST "https://api.stripe.com/v1/refunds" \
  -H "Authorization: Bearer sk_live_xxx" \
  -d "payment_intent=pi_xxx" \
  -d "amount=500" | jq '{id, status, amount}'

テスト/本番モードの切替

確認方法

• キーが pktest / sktest → テストモード
• キーが pklive / sklive → 本番モード

切替手順

1. Stripe Dashboard で本番キーを取得
2. 1Password Environment のローカル開発用変数を更新
3. wrangler.toml の STRIPEPUBLISHABLEKEY を更新
4. wrangler secret put で Worker secret を更新
5. Webhook を本番モードで作成し、シークレットを更新
6. デプロイ

wrangler whoami
wrangler secret put STRIPE_SECRET_KEY
wrangler secret put STRIPE_WEBHOOK_SECRET
npm run build
wrangler deploy

Cloudflare Workers での注意点

nodejs_compat フラグ

Stripe SDK は Node.js の util モジュールを使用するため、wrangler.toml に以下が必要:

compatibility_flags = ["nodejs_compat"]

SubtleCrypto Provider

Webhook 署名検証には Stripe.createSubtleCryptoProvider() を使用する（Workers 環境では Node.js の crypto が使えないため）。

トラブルシューティング

"No such module util" エラー

compatibilityflags = ["nodejscompat"] を追加してビルドし直す。

Webhook 署名エラー

1. STRIPEWEBHOOKSECRET が正しいか確認
2. テスト/本番モードの Webhook シークレットが混在していないか確認
3. c.req.text() で body を取得しているか確認（c.req.json() は NG）

決済後にデータベースに保存されない

Webhook エンドポイントが正しく設定されているか確認:

wrangler tail --format=pretty