stripe

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stripe — Next.js App Router

Complete Stripe integration patterns for Next.js App Router with Server Actions and Route Handlers.

基于Next.js App Router结合Server Actions和Route Handlers的完整Stripe集成方案。

Setup (3 steps)

设置步骤（共3步）

Step 1: Install

步骤1：安装

bash

npm install stripe @stripe/stripe-js @stripe/react-stripe-js

bash

npm install stripe @stripe/stripe-js @stripe/react-stripe-js

Step 2: Environment variables

步骤2：环境变量

Copy

templates/env-example.txt

→

.env.local

and fill in your keys from Stripe Dashboard.

Env Variable	Value	Exposed to Client
`STRIPE_SECRET_KEY`	`sk_test_...` or `sk_live_...`	NO
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	`pk_test_...` or `pk_live_...`	Yes
`STRIPE_WEBHOOK_SECRET`	`whsec_...`	NO
`NEXT_PUBLIC_APP_URL`	`http://localhost:3000`	Yes

复制

templates/env-example.txt

→

.env.local

，并从Stripe控制台填入你的密钥。

环境变量	取值	是否暴露给客户端
`STRIPE_SECRET_KEY`	`sk_test_...` 或 `sk_live_...`	否
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	`pk_test_...` 或 `pk_live_...`	是
`STRIPE_WEBHOOK_SECRET`	`whsec_...`	否
`NEXT_PUBLIC_APP_URL`	`http://localhost:3000`	是

Step 3: Initialize SDK

步骤3：初始化SDK

Copy

templates/stripe-server.ts

→

lib/stripe.ts

and

templates/stripe-client.ts

→

lib/stripe-client.ts

Load

references/setup.md

for details.

复制

templates/stripe-server.ts

→

lib/stripe.ts

，以及

templates/stripe-client.ts

→

lib/stripe-client.ts

。

查看

references/setup.md

获取详细说明。

Quick Patterns

快速集成方案

Task	Approach	Reference
One-time payment	Checkout Session → redirect to Stripe	`references/checkout.md`
Custom payment UI	Payment Intents + Stripe Elements	`references/payment-intents.md`
Recurring billing	Subscriptions + Invoices	`references/subscriptions.md`
Receive events	Webhook Route Handler	`references/webhooks.md`
Self-service billing	Customer Portal session	`references/customer-portal.md`
Products & pricing	Products + Prices API	`references/products-prices.md`
Marketplace splits	Stripe Connect	`references/connect.md`
Auto tax calc	Stripe Tax	`references/tax.md`
Fraud prevention	Radar rules + 3D Secure	`references/radar-fraud.md`
Usage-based billing	Billing Meter + usage records	`references/billing-meter.md`
Pricing page	Server-fetched prices + checkout button	`references/pricing-page.md`
Stripe ↔ DB sync	Webhook → database update patterns	`references/database-sync.md`
Paywall / auth guard	Middleware + Server Component guards	`references/middleware-guard.md`

任务	实现方式	参考文档
一次性支付	创建Checkout Session并跳转到Stripe托管页面	`references/checkout.md`
自定义支付UI	Payment Intents + Stripe Elements组件	`references/payment-intents.md`
定期订阅计费	订阅服务 + 发票管理	`references/subscriptions.md`
接收事件	Webhook路由处理器	`references/webhooks.md`
自助账单管理	创建客户门户会话	`references/customer-portal.md`
产品与定价管理	产品+价格API	`references/products-prices.md`
平台分账	Stripe Connect	`references/connect.md`
自动税务计算	Stripe Tax	`references/tax.md`
欺诈防护	Radar规则 + 3D Secure验证	`references/radar-fraud.md`
基于使用量的计费	计费计量器 + 使用记录	`references/billing-meter.md`
定价页面	服务端获取价格 + 结账按钮	`references/pricing-page.md`
Stripe与数据库同步	Webhook触发数据库更新	`references/database-sync.md`
付费墙/权限校验	中间件 + 服务端组件校验	`references/middleware-guard.md`

Essential Webhook Events

核心Webhook事件

Event	When	Action
`checkout.session.completed`	Payment captured	Fulfill order
`invoice.paid`	Subscription renewed	Extend access
`invoice.payment_failed`	Payment failed	Notify user, retry
`customer.subscription.updated`	Plan changed	Update entitlements
`customer.subscription.deleted`	Cancelled	Revoke access
`payment_intent.succeeded`	Custom flow completed	Confirm order
`charge.dispute.created`	Dispute opened	Alert + evidence

Load

references/webhooks.md

for handler implementation.

事件	触发时机	处理动作
`checkout.session.completed`	支付成功到账	履行订单
`invoice.paid`	订阅续费完成	延长用户访问权限
`invoice.payment_failed`	支付失败	通知用户并重试支付
`customer.subscription.updated`	订阅计划变更	更新用户权益
`customer.subscription.deleted`	订阅取消	收回用户访问权限
`payment_intent.succeeded`	自定义支付流程完成	确认订单
`charge.dispute.created`	发起争议退款	发送告警并准备举证材料

查看

references/webhooks.md

获取处理器实现细节。

Test Cards

测试卡号

Number	Result
`4242 4242 4242 4242`	Success
`4000 0000 0000 0002`	Generic decline
`4000 0000 0000 9995`	Insufficient funds
`4000 0000 0000 0069`	Expired card
`4000 0025 0000 3155`	3D Secure required
`4000 0000 0000 3220`	3D Secure 2 required

Load

references/testing.md

for full test cards + Stripe CLI workflow.

卡号	测试结果
`4242 4242 4242 4242`	支付成功
`4000 0000 0000 0002`	通用拒绝
`4000 0000 0000 9995`	余额不足
`4000 0000 0000 0069`	卡片过期
`4000 0025 0000 3155`	需要3D Secure验证
`4000 0000 0000 3220`	需要3D Secure 2验证

查看

references/testing.md

获取完整测试卡号列表及Stripe CLI使用流程。

Stripe CLI

bash

stripe login
stripe listen --forward-to localhost:3000/api/webhooks/stripe
stripe trigger checkout.session.completed
stripe trigger invoice.payment_failed
stripe logs tail --filter status:400

bash

stripe login
stripe listen --forward-to localhost:3000/api/webhooks/stripe
stripe trigger checkout.session.completed
stripe trigger invoice.payment_failed
stripe logs tail --filter status:400

Templates

模板文件

Template	Copy To	Description
`templates/stripe-server.ts`	`lib/stripe.ts`	Server-side Stripe instance
`templates/stripe-client.ts`	`lib/stripe-client.ts`	Client-side Stripe.js (lazy)
`templates/webhook-handler.ts`	`app/api/webhooks/stripe/route.ts`	Webhook Route Handler
`templates/checkout-action.ts`	`app/actions/checkout.ts`	Server Action: Checkout Session
`templates/subscription-action.ts`	`app/actions/subscription.ts`	Server Actions: subscription CRUD
`templates/customer-portal-action.ts`	`app/actions/portal.ts`	Server Action: portal session
`templates/env-example.txt`	`.env.local`	Environment variables

模板文件	复制到目标路径	描述
`templates/stripe-server.ts`	`lib/stripe.ts`	服务端Stripe实例
`templates/stripe-client.ts`	`lib/stripe-client.ts`	客户端Stripe.js（懒加载）
`templates/webhook-handler.ts`	`app/api/webhooks/stripe/route.ts`	Webhook路由处理器
`templates/checkout-action.ts`	`app/actions/checkout.ts`	Server Action：创建Checkout Session
`templates/subscription-action.ts`	`app/actions/subscription.ts`	Server Actions：订阅增删改查
`templates/customer-portal-action.ts`	`app/actions/portal.ts`	Server Action：创建客户门户会话
`templates/env-example.txt`	`.env.local`	环境变量配置模板

Error Handling

错误处理

Load

references/error-handling.md

for Stripe error types and retry patterns.

查看

references/error-handling.md

获取Stripe错误类型及重试机制说明。

Security

安全注意事项

Load

references/security.md

for PCI compliance, idempotency, and key management.

查看

references/security.md

获取PCI合规、幂等性及密钥管理相关内容。

All References

全部参考文档

```
references/setup.md
```
— SDK init, singleton, TypeScript config
```
references/checkout.md
```
— Checkout Sessions, hosted vs embedded
```
references/payment-intents.md
```
— Payment Intents, 3D Secure, capture
```
references/subscriptions.md
```
— Recurring billing, trials, proration
```
references/webhooks.md
```
— Signature verification, event routing, idempotency
```
references/customer-portal.md
```
— Self-service portal setup
```
references/products-prices.md
```
— Products, Prices, coupons, promo codes
```
references/connect.md
```
— Marketplace, platform fees, payouts
```
references/tax.md
```
— Automatic tax calculation
```
references/radar-fraud.md
```
— Fraud detection, disputes
```
references/billing-meter.md
```
— Usage-based billing
```
references/error-handling.md
```
— Error types, retry logic
```
references/testing.md
```
— Test cards, CLI, test clocks
```
references/security.md
```
— PCI, keys, idempotency, CSP
```
references/pricing-page.md
```
— Pricing page component pattern
```
references/database-sync.md
```
— Stripe ↔ DB sync patterns
```
references/middleware-guard.md
```
— Auth middleware for paid routes

```
references/setup.md
```
— SDK初始化、单例模式、TypeScript配置
```
references/checkout.md
```
— Checkout Session、托管式 vs 嵌入式
```
references/payment-intents.md
```
— Payment Intents、3D Secure、资金到账
```
references/subscriptions.md
```
— 定期订阅计费、试用、计价调整
```
references/webhooks.md
```
— 签名验证、事件路由、幂等性
```
references/customer-portal.md
```
— 自助客户门户设置
```
references/products-prices.md
```
— 产品、定价、优惠券、促销码
```
references/connect.md
```
— 平台分账、平台手续费、资金提现
```
references/tax.md
```
— 自动税务计算
```
references/radar-fraud.md
```
— 欺诈检测、争议处理
```
references/billing-meter.md
```
— 基于使用量的计费
```
references/error-handling.md
```
— 错误类型、重试逻辑
```
references/testing.md
```
— 测试卡号、CLI、测试时钟
```
references/security.md
```
— PCI合规、密钥管理、幂等性、内容安全策略（CSP）
```
references/pricing-page.md
```
— 定价页面组件实现方案
```
references/database-sync.md
```
— Stripe与数据库同步方案
```
references/middleware-guard.md
```
— 付费路由的权限校验中间件