stripe-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stripe Integration

Stripe集成

Overview

概述

Stripe provides a complete payments platform with server-side SDKs (Node.js) and client-side libraries (Stripe.js, React Stripe.js). The Node.js SDK handles server operations like creating Payment Intents, managing Subscriptions, and verifying webhooks. The React Stripe.js library provides pre-built UI components (PaymentElement, Elements provider) for secure client-side payment collection.

When to use: One-time payments, recurring subscriptions, usage-based billing, marketplace payouts, hosted checkout pages, custom payment forms, webhook-driven fulfillment.

When NOT to use: Cryptocurrency payments (not supported), regions where Stripe is unavailable, simple static product sales without payment processing (use a hosted storefront).

Stripe提供了一套完整的支付平台，包含服务端SDK（Node.js）和客户端库（Stripe.js、React Stripe.js）。Node.js SDK负责处理服务端操作，例如创建Payment Intents、管理Subscriptions以及验证webhooks。React Stripe.js库提供预构建的UI组件（PaymentElement、Elements provider），用于安全的客户端支付信息收集。

适用场景： 一次性支付、定期订阅、基于使用量的计费、市场提现、托管结账页面、自定义支付表单、由webhook驱动的履约流程。

不适用场景： 加密货币支付（暂不支持）、Stripe未覆盖的地区、无需支付处理的简单静态商品销售（使用托管店面即可）。

Quick Reference

速查参考

Pattern	API	Key Points
Hosted checkout	`stripe.checkout.sessions.create()`	Stripe-hosted page, supports `payment` , `subscription` , `setup` modes
Payment Intent	`stripe.paymentIntents.create()`	Server-side, returns `client_secret` for client confirmation
Confirm payment	`stripe.confirmPayment({ elements, clientSecret })`	Client-side, requires Elements instance
Create subscription	`stripe.subscriptions.create()`	Use `payment_behavior: 'default_incomplete'` for SCA
Update subscription	`stripe.subscriptions.update()`	Set `proration_behavior` explicitly
Cancel subscription	`stripe.subscriptions.cancel()`	Use `prorate: true` to credit unused time
Customer Portal	`stripe.billingPortal.sessions.create()`	Self-service billing management, returns short-lived URL
Webhook verify	`stripe.webhooks.constructEvent()`	Requires raw body, signature header, and endpoint secret
Elements provider	`<Elements stripe={stripePromise} options={options}>`	Wraps payment components, pass `clientSecret` or `mode`
PaymentElement	`<PaymentElement />`	Renders all supported payment methods automatically
Retrieve + expand	`stripe.checkout.sessions.retrieve(id, { expand })`	Expand nested objects to reduce API calls
Search	`stripe.paymentIntents.search({ query })`	Stripe Query Language for filtering

模式	API	关键点
托管结账页面	`stripe.checkout.sessions.create()`	Stripe托管页面，支持 `payment` 、 `subscription` 、 `setup` 模式
支付意向	`stripe.paymentIntents.create()`	服务端创建，返回 `client_secret` 供客户端确认
确认支付	`stripe.confirmPayment({ elements, clientSecret })`	客户端操作，需要Elements实例
创建订阅	`stripe.subscriptions.create()`	针对SCA要求，使用 `payment_behavior: 'default_incomplete'`
更新订阅	`stripe.subscriptions.update()`	显式设置 `proration_behavior`
取消订阅	`stripe.subscriptions.cancel()`	使用 `prorate: true` 为未使用时长退款
客户门户	`stripe.billingPortal.sessions.create()`	自助式账单管理，返回短时效URL
Webhook验证	`stripe.webhooks.constructEvent()`	需要原始请求体、签名头和端点密钥
Elements提供者	`<Elements stripe={stripePromise} options={options}>`	包裹支付组件，传入 `clientSecret` 或 `mode`
PaymentElement	`<PaymentElement />`	自动渲染所有支持的支付方式
查询并展开对象	`stripe.checkout.sessions.retrieve(id, { expand })`	展开嵌套对象以减少API调用次数
搜索	`stripe.paymentIntents.search({ query })`	使用Stripe查询语言进行筛选

Common Mistakes

常见错误

Mistake	Correct Pattern
Parsing webhook body as JSON before verification	Use `express.raw({ type: 'application/json' })` to pass raw body to `constructEvent`
Hardcoding payment method types	Use `automatic_payment_methods` or let Checkout choose based on currency and region
Creating PaymentIntent client-side	Create on server, pass only `client_secret` to client
Not awaiting `elements.submit()` before confirm	Call `elements.submit()` first to trigger validation, then `confirmPayment`
Missing `return_url` in `confirmPayment`	Always provide `return_url` for redirect-based payment methods
Using test keys in production	Store keys in environment variables, validate `STRIPE_SECRET_KEY` prefix ( `sk_live_` vs `sk_test_` )
Not handling `requires_action` status	Check PaymentIntent status after confirmation, handle 3D Secure or other authentication
Creating Customer Portal session without settings	Save portal settings in Dashboard first, otherwise API returns an error
Not expanding related objects	Use `expand` parameter to include nested objects like `latest_invoice.payment_intent`
Ignoring webhook idempotency	Use `event.id` to deduplicate, webhook events can be delivered more than once

错误内容	正确做法
验证前将webhook请求体解析为JSON	使用 `express.raw({ type: 'application/json' })` 将原始请求体传入 `constructEvent`
硬编码支付方式类型	使用 `automatic_payment_methods` 或让Checkout根据货币和地区自动选择
在客户端创建PaymentIntent	在服务端创建，仅将 `client_secret` 传递给客户端
确认支付前未等待 `elements.submit()`	先调用 `elements.submit()` 触发验证，再执行 `confirmPayment`
`confirmPayment` 中缺少 `return_url`	始终为基于重定向的支付方式提供 `return_url`
生产环境使用测试密钥	将密钥存储在环境变量中，验证 `STRIPE_SECRET_KEY` 前缀（ `sk_live_` vs `sk_test_` ）
未处理 `requires_action` 状态	确认后检查PaymentIntent状态，处理3D Secure或其他认证流程
未配置设置就创建客户门户会话	先在控制台保存门户设置，否则API会返回错误
未展开关联对象	使用 `expand` 参数包含嵌套对象，例如 `latest_invoice.payment_intent`
忽略webhook幂等性	使用 `event.id` 实现去重，webhook事件可能会多次投递

Delegation

任务分工

Payment flow architecture: Use
```
Explore
```
agent to discover integration patterns
Webhook debugging: Use
```
Task
```
agent for end-to-end event tracing
Code review: Delegate to
```
code-reviewer
```
agent for security review of payment handlers

支付流架构设计：使用
```
Explore
```
代理探索集成模式
Webhook调试：使用
```
Task
```
代理进行端到端事件追踪
代码审查：委托
```
code-reviewer
```
代理对支付处理程序进行安全审查

References

参考资料

Checkout Sessions, Payment Intents, and one-time payments
Subscription lifecycle, pricing models, trials, and Customer Portal
Webhook endpoints, signature verification, and event handling
React Stripe.js, Elements provider, PaymentElement, and custom forms

Checkout Sessions、Payment Intents与一次性支付
订阅生命周期、定价模型、试用与客户门户
Webhook端点、签名验证与事件处理
React Stripe.js、Elements提供者、PaymentElement与自定义表单