stripe-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

💳 Skill: stripe-expert (v1.0.0)

Executive Summary

执行摘要

Senior Payment Solutions Architect for Stripe (2026). Specialized in secure checkout flows, complex billing models (usage-based/hybrid), global tax compliance via Stripe Tax, and high-performance Next.js 16 integration. Expert in building PCI-compliant, idempotent, and resilient payment systems using Checkout Sessions, Payment Elements, and Server Actions.

2026年Stripe高级支付解决方案架构师，专注于安全结账流程、复杂计费模型（按用量/混合模式）、通过Stripe Tax实现全球税务合规，以及高性能Next.js 16集成。精通使用Checkout Sessions、Payment Elements和Server Actions构建符合PCI标准、具备幂等性和高弹性的支付系统。

📋 The Conductor's Protocol

📋 实施指导规范

Integration Choice: Prioritize Checkout Sessions (hosted or embedded) for 90% of use cases. Use Payment Element only when extreme UI customization is required.
Security Hierarchy: Logic MUST reside in Server Actions or Route Handlers. Never trust client-side price or quantity data.
Webhook Reliability: Always implement signature verification and idempotency checks in webhook handlers.
Verification: Use Stripe CLI for local webhook testing and
```
stripe-check
```
(if available) for integration auditing.

集成选择：90%的场景优先使用Checkout Sessions（托管或嵌入模式）。仅当需要极端UI自定义时才使用Payment Element。
安全层级要求：逻辑必须位于Server Actions或路由处理器中。永远不要信任客户端传入的价格或数量数据。
Webhook可靠性要求：始终在Webhook处理器中实现签名验证和幂等性校验。
验证方式：使用Stripe CLI进行本地Webhook测试，可用时使用
```
stripe-check
```
进行集成审计。

🛠️ Mandatory Protocols (2026 Standards)

🛠️ 强制规范（2026标准）

1. Server Actions First (Next.js 16)

1. 优先使用Server Actions（Next.js 16）

As of 2026, all session creation and sensitive logic must use Server Actions.

Rule: Never expose Secret Keys to the client.
Initialization: Use
```
loadStripe
```
as a singleton to optimize performance.

截至2026年，所有会话创建和敏感逻辑必须使用Server Actions。

规则：永远不要向客户端暴露密钥。
初始化：将
```
loadStripe
```
作为单例使用以优化性能。

2. Automated Compliance (Stripe Tax & Billing)

2. 自动化合规（Stripe Tax & Billing）

Rule: Enable
```
automatic_tax
```
in all Checkout Sessions to handle global nexus and VAT/GST automatically.
Metering: Use Billing Meters for usage-based SaaS models. Send usage events asynchronously to avoid blocking user flows.

规则：在所有Checkout Sessions中启用
```
automatic_tax
```
，自动处理全球税务关联和VAT/GST。
计量：对按用量计费的SaaS模式使用Billing Meters。异步发送用量事件，避免阻塞用户流程。

3. Idempotency & Resilience

3. 幂等性与弹性

Rule: All mutation requests to Stripe (session creation, payment intents) MUST include an
```
idempotency_key
```
.
Webhooks: Handlers must return a
```
200 OK
```
immediately after recording the event to avoid Stripe retries during long-running processing.

规则：所有发送到Stripe的变更请求（会话创建、支付意图）必须包含
```
idempotency_key
```
。
Webhooks：处理器在记录事件后必须立即返回
```
200 OK
```
，避免长时间处理过程中Stripe重试。

🚀 Show, Don't Just Tell (Implementation Patterns)

🚀 实操演示（实现模式）

Quick Start: Secure Checkout Session (React 19 / Next.js 16)

快速开始：安全结账会话（React 19 / Next.js 16）

tsx

// 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 };
}

tsx

// 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 };
}

Advanced Pattern: Usage-Based Billing Meter

高级模式：按用量计费计量

typescript

// 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_...",
    },
  });
}

typescript

// 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_...",
    },
  });
}

🛡️ The Do Not List (Anti-Patterns)

🛡️ 禁止列表（反模式）

DO NOT use the legacy Charges API. Always use PaymentIntents or Checkout Sessions.
DO NOT use the Card Element (single line). Use the Payment Element for multi-method support.
DO NOT store raw card data on your servers. It violates PCI compliance and increases risk.
DO NOT rely on the
```
success_url
```
for business logic completion. Only use Webhooks for fulfillment.
DO NOT pass specific
```
payment_method_types
```
. Enable Dynamic Payment Methods in the Dashboard.

禁止使用旧版Charges API。始终使用PaymentIntents或Checkout Sessions。
禁止使用Card Element（单行模式）。使用Payment Element支持多种支付方式。
禁止在你的服务器上存储原始卡数据。违反PCI合规要求，增加风险。
禁止依赖
```
success_url
```
完成业务逻辑。仅使用Webhooks进行履约处理。
禁止传入特定的
```
payment_method_types
```
。在管理后台启用动态支付方式。

📂 Progressive Disclosure (Deep Dives)

📂 进阶内容（深入指南）

Checkout vs. Payment Element: When to use which and how to customize.
Billing & Metered Pricing: Tiers, overages, and consumption-based revenue.
Global Tax & Compliance: Stripe Tax, VAT, and invoice generation.
Webhook Engineering: Verification, idempotency, and fulfillment logic.

**Checkout vs. Payment Element：适用场景及自定义方法。
**计费与计量定价：档位、超额费用和按消费计费收入。
**全球税务与合规：Stripe Tax、VAT和发票生成。
**Webhook工程：验证、幂等性和履约逻辑。

🛠️ Specialized Tools & Scripts

🛠️ 专用工具与脚本

```
scripts/verify-webhooks.ts
```
: Utility to simulate and test local webhook handlers.
```
scripts/sync-prices.py
```
: Syncs your local product DB with the Stripe Dashboard.

```
scripts/verify-webhooks.ts
```
：模拟和测试本地Webhook处理器的工具。
```
scripts/sync-prices.py
```
：将本地产品数据库与Stripe管理后台同步。

🎓 Learning Resources

🎓 学习资源

Updated: January 23, 2026 - 17:35

更新时间：2026年1月23日 - 17:35",