stripe-expert

💳 スキル：stripe-expert（v1.0.0）

概要

Stripe に関するシニア決済ソリューションアーキテクト（2026年）。安全なチェックアウトフロー、複雑な課金モデル（従量課金／ハイブリッド）、Stripe Tax によるグローバルな税務コンプライアンス、高パフォーマンスな Next.js 16 との統合を専門としています。Checkout Sessions、Payment Elements、Server Actions を使用して、PCI 準拠で冪等性と耐障害性を備えた決済システムを構築するエキスパートです。

---

📋 コンダクターのプロトコル

1. 統合方法の選択：ユースケースの 90％では、Checkout Sessions（ホスト型または埋め込み型）を優先します。Payment Element は、極めて高度な UI カスタマイズが必要な場合にのみ使用します。
2. セキュリティの階層：ロジックは必ず Server Actions または Route Handlers に配置します。クライアント側の価格や数量のデータは決して信頼しないでください。
3. Webhook の信頼性：Webhook ハンドラーでは、必ず署名検証と冪等性チェックを実装します。
4. 検証：ローカルでの Webhook テストには Stripe CLI を使用し、統合の監査には（利用可能な場合）stripe-check を使用します。

---

🛠️ 必須プロトコル（2026年の標準）

1. Server Actions を最優先（Next.js 16）

2026年現在、すべてのセッション作成と機密性の高いロジックには Server Actions を使用する必要があります。

• ルール：Secret Keys をクライアントに公開しないでください。
• 初期化：パフォーマンスを最適化するため、loadStripe をシングルトンとして使用します。

2. コンプライアンスの自動化（Stripe Tax と Billing）

• ルール：グローバルな課税関係と VAT／GST に自動で対応するため、すべての Checkout Sessions で automatic_tax を有効にします。
• 計測：従量課金型 SaaS モデルでは Billing Meters を使用します。ユーザーフローをブロックしないよう、使用量イベントは非同期で送信します。

3. 冪等性と耐障害性

• ルール：Stripe へのすべての変更リクエスト（セッション作成、Payment Intents）には、必ず idempotency_key を含めます。
• Webhook：長時間の処理中に Stripe が再試行しないよう、イベントを記録したら、ハンドラーは直ちに 200 OK を返す必要があります。

---

🚀 説明だけでなく、実際に示す（実装パターン）

クイックスタート：安全な Checkout Session（React 19／Next.js 16）

// app/actions/stripe.ts
"use server";

import Stripe from "stripe";
import { headers } from "next/headers";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-12-18.acacia", // Always use the latest pinned version
});

export async function createCheckoutSession(priceId: string) {
  const origin = headers().get("origin");
  
  // Validation should happen here (check user, items, stock)
  
  const session = await stripe.checkout.sessions.create({
    line_items: [{ price: priceId, quantity: 1 }],
    mode: "subscription",
    success_url: `${origin}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${origin}/canceled`,
    automatic_tax: { enabled: true }, // 2026 Standard
  }, {
    idempotencyKey: `checkout_${priceId}_${Date.now()}`, // Prevent double-clicks
  });

  return { url: session.url };
}

高度なパターン：従量課金 Billing Meter

// server/usage.ts
export async function reportUsage(subscriptionItemId: string, usageCount: number) {
  await stripe.billing.meterEvents.create({
    event_name: "api_call",
    payload: {
      value: usageCount.toString(),
      stripe_customer_id: "cus_...",
    },
  });
}

---

🛡️ 禁止事項（アンチパターン）

1. 従来の Charges API は使用しないでください。必ず PaymentIntents または Checkout Sessions を使用します。
2. 単一行の Card Element は使用しないでください。複数の決済方法に対応するには Payment Element を使用します。
3. 生のカードデータをサーバーに保存しないでください。PCI コンプライアンスに違反し、リスクが高まります。
4. ビジネスロジックの完了を success_url に依存させないでください。フルフィルメントには Webhooks のみを使用します。
5. 特定の payment_method_types を渡さないでください。ダッシュボードで Dynamic Payment Methods を有効にします。

---

📂 段階的な開示（詳細）

• Checkout と Payment Element の比較：どちらをいつ使うか、およびカスタマイズ方法。
• Billing と従量課金の料金設定：料金階層、超過分、消費量ベースの収益。
• グローバルな税務とコンプライアンス：Stripe Tax、VAT、請求書の生成。
• Webhook エンジニアリング：検証、冪等性、フルフィルメントのロジック。

---

🛠️ 専門ツールとスクリプト

• scripts/verify-webhooks.ts：ローカルの Webhook ハンドラーをシミュレートしてテストするユーティリティ。
• scripts/sync-prices.py：ローカルの商品データベースを Stripe Dashboard と同期します。

---

🎓 学習リソース

• Stripe ドキュメント
• Stripe API リファレンス
• Stripe サンプル（GitHub）

---

更新日：2026年1月23日 - 17:35