payment-integration
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePayment Integration
支付集成
Overview
概述
This skill covers implementing payment processing and subscription billing in web and mobile applications. It addresses Stripe integration (Checkout, Elements, PaymentIntents), subscription lifecycle management, webhook handling with idempotency, PCI compliance, metered and usage-based billing, tax calculation, refund processing, and RevenueCat for mobile subscriptions.
Use this skill when adding payment processing, building subscription billing, handling Stripe webhooks, implementing pricing pages, managing payment failures, or integrating mobile in-app purchases.
本技能涵盖在Web和移动应用中实现支付处理与订阅计费的相关内容,包括Stripe集成(Checkout、Elements、PaymentIntents)、订阅生命周期管理、带幂等性的Webhook处理、PCI合规性、计量和基于使用量的计费、税务计算、退款处理,以及针对移动订阅的RevenueCat集成。
当你需要添加支付处理功能、构建订阅计费系统、处理Stripe Webhook、实现定价页面、管理支付失败或集成移动应用内购买时,可使用本技能。
Core Principles
核心原则
- Never handle raw card data - Use Stripe Elements or Checkout to keep card numbers off your servers entirely. This keeps you at PCI SAQ-A (the simplest compliance level) rather than SAQ-D.
- Webhooks are the source of truth - Never trust client-side payment confirmation. A successful PaymentIntent on the client means nothing until your webhook handler confirms . Build your system around webhook events.
payment_intent.succeeded - Idempotency everywhere - Webhooks can be delivered multiple times. Every webhook handler must be idempotent. Use Stripe's event ID as a deduplication key.
- Handle failure gracefully - Payments fail for many reasons (insufficient funds, expired cards, fraud detection). Build retry flows, dunning emails, and graceful degradation into the subscription lifecycle.
- Test with Stripe's test mode - Use test API keys, test card numbers, and test clocks for subscription lifecycle testing. Never test with real payment methods.
- 绝不处理原始银行卡数据 - 使用Stripe Elements或Checkout,让银行卡号完全不经过你的服务器。这可使你处于PCI SAQ-A(最简单的合规级别),而非SAQ-D。
- Webhook是唯一可信来源 - 绝不信任客户端的支付确认信息。客户端显示PaymentIntent成功并不代表实际成功,必须等待你的Webhook处理程序确认事件。系统需围绕Webhook事件构建。
payment_intent.succeeded - 处处实现幂等性 - Webhook可能会被多次推送。每个Webhook处理程序必须具备幂等性,使用Stripe的事件ID作为去重键。
- 优雅处理失败场景 - 支付失败的原因有很多(余额不足、卡片过期、欺诈检测等)。需在订阅生命周期中构建重试流程、催缴邮件(dunning emails)和优雅降级机制。
- 使用Stripe测试模式进行测试 - 使用测试API密钥、测试卡号和测试时钟进行订阅生命周期测试。绝不要使用真实支付方式进行测试。
Key Patterns
关键模式
Pattern 1: Stripe Checkout for Subscriptions
模式1:用于订阅的Stripe Checkout
When to use: When you want Stripe to handle the entire checkout UI, including payment form, coupon codes, and tax calculation.
Implementation:
typescript
// Server - Create Checkout Session
// app/api/checkout/route.ts
import Stripe from "stripe";
import { NextRequest, NextResponse } from "next/server";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
apiVersion: "2024-06-20",
});
export async function POST(req: NextRequest) {
const { priceId, userId, email } = await req.json();
// Get or create Stripe customer
let customerId = await getStripeCustomerId(userId);
if (!customerId) {
const customer = await stripe.customers.create({
email,
metadata: { userId },
});
customerId = customer.id;
await saveStripeCustomerId(userId, customerId);
}
const session = await stripe.checkout.sessions.create({
customer: customerId,
mode: "subscription",
line_items: [{ price: priceId, quantity: 1 }],
success_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
subscription_data: {
metadata: { userId },
trial_period_days: 14,
},
// Enable automatic tax calculation
automatic_tax: { enabled: true },
// Allow promo codes
allow_promotion_codes: true,
// Collect billing address for tax
billing_address_collection: "required",
// Customer portal for self-service management
customer_update: {
address: "auto",
name: "auto",
},
});
return NextResponse.json({ url: session.url });
}tsx
// Client - Redirect to Checkout
function PricingCard({ plan }: { plan: PricingPlan }) {
const [loading, setLoading] = useState(false);
const handleSubscribe = async () => {
setLoading(true);
try {
const res = await fetch("/api/checkout", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
priceId: plan.stripePriceId,
userId: user.id,
email: user.email,
}),
});
const { url } = await res.json();
window.location.href = url; // Redirect to Stripe Checkout
} catch (error) {
toast.error("Failed to start checkout");
} finally {
setLoading(false);
}
};
return (
<div className="pricing-card">
<h3>{plan.name}</h3>
<p className="price">${plan.price}/mo</p>
<ul>
{plan.features.map((f) => (
<li key={f}>{f}</li>
))}
</ul>
<button onClick={handleSubscribe} disabled={loading}>
{loading ? "Redirecting..." : "Subscribe"}
</button>
</div>
);
}Why: Stripe Checkout handles PCI compliance, 3D Secure authentication, tax calculation, promo codes, and localization. Building your own checkout form is hundreds of hours of work and ongoing PCI compliance burden. Use Checkout unless you have a strong reason to build custom UI.
适用场景: 当你希望Stripe处理整个结账UI,包括支付表单、优惠券代码和税务计算时。
实现方式:
typescript
// Server - Create Checkout Session
// app/api/checkout/route.ts
import Stripe from "stripe";
import { NextRequest, NextResponse } from "next/server";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
apiVersion: "2024-06-20",
});
export async function POST(req: NextRequest) {
const { priceId, userId, email } = await req.json();
// Get or create Stripe customer
let customerId = await getStripeCustomerId(userId);
if (!customerId) {
const customer = await stripe.customers.create({
email,
metadata: { userId },
});
customerId = customer.id;
await saveStripeCustomerId(userId, customerId);
}
const session = await stripe.checkout.sessions.create({
customer: customerId,
mode: "subscription",
line_items: [{ price: priceId, quantity: 1 }],
success_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
subscription_data: {
metadata: { userId },
trial_period_days: 14,
},
// Enable automatic tax calculation
automatic_tax: { enabled: true },
// Allow promo codes
allow_promotion_codes: true,
// Collect billing address for tax
billing_address_collection: "required",
// Customer portal for self-service management
customer_update: {
address: "auto",
name: "auto",
},
});
return NextResponse.json({ url: session.url });
}tsx
// Client - Redirect to Checkout
function PricingCard({ plan }: { plan: PricingPlan }) {
const [loading, setLoading] = useState(false);
const handleSubscribe = async () => {
setLoading(true);
try {
const res = await fetch("/api/checkout", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
priceId: plan.stripePriceId,
userId: user.id,
email: user.email,
}),
});
const { url } = await res.json();
window.location.href = url; // Redirect to Stripe Checkout
} catch (error) {
toast.error("Failed to start checkout");
} finally {
setLoading(false);
}
};
return (
<div className="pricing-card">
<h3>{plan.name}</h3>
<p className="price">${plan.price}/mo</p>
<ul>
{plan.features.map((f) => (
<li key={f}>{f}</li>
))}
</ul>
<button onClick={handleSubscribe} disabled={loading}>
{loading ? "Redirecting..." : "Subscribe"}
</button>
</div>
);
}为什么选择此方案: Stripe Checkout可处理PCI合规性、3D Secure认证、税务计算、促销代码和本地化。自行构建结账表单需要数百小时的工作量,且需持续承担PCI合规性负担。除非有充分理由构建自定义UI,否则应使用Checkout。
Pattern 2: Webhook Handler with Idempotency
模式2:带幂等性的Webhook处理程序
When to use: Every Stripe integration. Webhooks are the only reliable way to know payment status.
Implementation:
typescript
// app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
import { NextRequest, NextResponse } from "next/server";
import { headers } from "next/headers";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
// Process each event type
const eventHandlers: Record<string, (event: Stripe.Event) => Promise<void>> = {
"checkout.session.completed": async (event) => {
const session = event.data.object as Stripe.Checkout.Session;
const userId = session.metadata?.userId ?? session.subscription?.toString();
await db.user.update({
where: { stripeCustomerId: session.customer as string },
data: {
subscriptionId: session.subscription as string,
subscriptionStatus: "active",
},
});
},
"customer.subscription.updated": async (event) => {
const subscription = event.data.object as Stripe.Subscription;
await db.user.update({
where: { stripeCustomerId: subscription.customer as string },
data: {
subscriptionStatus: subscription.status,
planId: subscription.items.data[0].price.id,
currentPeriodEnd: new Date(subscription.current_period_end * 1000),
cancelAtPeriodEnd: subscription.cancel_at_period_end,
},
});
},
"customer.subscription.deleted": async (event) => {
const subscription = event.data.object as Stripe.Subscription;
await db.user.update({
where: { stripeCustomerId: subscription.customer as string },
data: {
subscriptionStatus: "canceled",
planId: null,
},
});
},
"invoice.payment_failed": async (event) => {
const invoice = event.data.object as Stripe.Invoice;
await db.user.update({
where: { stripeCustomerId: invoice.customer as string },
data: { subscriptionStatus: "past_due" },
});
// Send dunning email
await sendDunningEmail(invoice.customer as string, {
amountDue: invoice.amount_due,
nextRetry: invoice.next_payment_attempt
? new Date(invoice.next_payment_attempt * 1000)
: null,
});
},
"invoice.paid": async (event) => {
const invoice = event.data.object as Stripe.Invoice;
await db.user.update({
where: { stripeCustomerId: invoice.customer as string },
data: { subscriptionStatus: "active" },
});
},
};
export async function POST(req: NextRequest) {
const body = await req.text();
const signature = (await headers()).get("stripe-signature")!;
let event: Stripe.Event;
// 1. Verify webhook signature (prevents spoofing)
try {
event = stripe.webhooks.constructEvent(
body,
signature,
process.env.STRIPE_WEBHOOK_SECRET!
);
} catch (err) {
console.error("Webhook signature verification failed:", err);
return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
}
// 2. Idempotency check - skip already-processed events
const alreadyProcessed = await db.stripeEvent.findUnique({
where: { eventId: event.id },
});
if (alreadyProcessed) {
return NextResponse.json({ received: true });
}
// 3. Process the event
const handler = eventHandlers[event.type];
if (handler) {
try {
await handler(event);
// 4. Record processed event for idempotency
await db.stripeEvent.create({
data: {
eventId: event.id,
type: event.type,
processedAt: new Date(),
},
});
} catch (err) {
console.error(`Error processing ${event.type}:`, err);
// Return 500 so Stripe retries
return NextResponse.json({ error: "Processing failed" }, { status: 500 });
}
}
return NextResponse.json({ received: true });
}Why: Stripe delivers webhooks at least once, meaning duplicates are possible. The idempotency check (storing processed event IDs) prevents double-processing. Signature verification prevents spoofed webhook attacks. Returning 500 on handler errors triggers Stripe's automatic retry with exponential backoff.
适用场景: 所有Stripe集成场景。Webhook是知晓支付状态的唯一可靠方式。
实现方式:
typescript
// app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
import { NextRequest, NextResponse } from "next/server";
import { headers } from "next/headers";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
// Process each event type
const eventHandlers: Record<string, (event: Stripe.Event) => Promise<void>> = {
"checkout.session.completed": async (event) => {
const session = event.data.object as Stripe.Checkout.Session;
const userId = session.metadata?.userId ?? session.subscription?.toString();
await db.user.update({
where: { stripeCustomerId: session.customer as string },
data: {
subscriptionId: session.subscription as string,
subscriptionStatus: "active",
},
});
},
"customer.subscription.updated": async (event) => {
const subscription = event.data.object as Stripe.Subscription;
await db.user.update({
where: { stripeCustomerId: subscription.customer as string },
data: {
subscriptionStatus: subscription.status,
planId: subscription.items.data[0].price.id,
currentPeriodEnd: new Date(subscription.current_period_end * 1000),
cancelAtPeriodEnd: subscription.cancel_at_period_end,
},
});
},
"customer.subscription.deleted": async (event) => {
const subscription = event.data.object as Stripe.Subscription;
await db.user.update({
where: { stripeCustomerId: subscription.customer as string },
data: {
subscriptionStatus: "canceled",
planId: null,
},
});
},
"invoice.payment_failed": async (event) => {
const invoice = event.data.object as Stripe.Invoice;
await db.user.update({
where: { stripeCustomerId: invoice.customer as string },
data: { subscriptionStatus: "past_due" },
});
// Send dunning email
await sendDunningEmail(invoice.customer as string, {
amountDue: invoice.amount_due,
nextRetry: invoice.next_payment_attempt
? new Date(invoice.next_payment_attempt * 1000)
: null,
});
},
"invoice.paid": async (event) => {
const invoice = event.data.object as Stripe.Invoice;
await db.user.update({
where: { stripeCustomerId: invoice.customer as string },
data: { subscriptionStatus: "active" },
});
},
};
export async function POST(req: NextRequest) {
const body = await req.text();
const signature = (await headers()).get("stripe-signature")!;
let event: Stripe.Event;
// 1. Verify webhook signature (prevents spoofing)
try {
event = stripe.webhooks.constructEvent(
body,
signature,
process.env.STRIPE_WEBHOOK_SECRET!
);
} catch (err) {
console.error("Webhook signature verification failed:", err);
return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
}
// 2. Idempotency check - skip already-processed events
const alreadyProcessed = await db.stripeEvent.findUnique({
where: { eventId: event.id },
});
if (alreadyProcessed) {
return NextResponse.json({ received: true });
}
// 3. Process the event
const handler = eventHandlers[event.type];
if (handler) {
try {
await handler(event);
// 4. Record processed event for idempotency
await db.stripeEvent.create({
data: {
eventId: event.id,
type: event.type,
processedAt: new Date(),
},
});
} catch (err) {
console.error(`Error processing ${event.type}:`, err);
// Return 500 so Stripe retries
return NextResponse.json({ error: "Processing failed" }, { status: 500 });
}
}
return NextResponse.json({ received: true });
}为什么选择此方案: Stripe会至少推送一次Webhook,这意味着可能会出现重复消息。幂等性检查(存储已处理的事件ID)可防止重复处理。签名验证可防止伪造的Webhook攻击。处理程序出错时返回500状态码会触发Stripe的自动指数退避重试机制。
Pattern 3: Customer Portal for Self-Service
模式3:自助服务客户门户
When to use: Let customers manage their own subscriptions (upgrade, downgrade, cancel, update payment method) without contacting support.
Implementation:
typescript
// Create portal session
// app/api/billing/portal/route.ts
export async function POST(req: NextRequest) {
const { userId } = await req.json();
const user = await db.user.findUniqueOrThrow({
where: { id: userId },
select: { stripeCustomerId: true },
});
if (!user.stripeCustomerId) {
return NextResponse.json({ error: "No billing account" }, { status: 400 });
}
const session = await stripe.billingPortal.sessions.create({
customer: user.stripeCustomerId,
return_url: `${process.env.NEXT_PUBLIC_URL}/settings/billing`,
});
return NextResponse.json({ url: session.url });
}typescript
// Configure the portal in Stripe (do this once, via API or Dashboard)
await stripe.billingPortal.configurations.create({
business_profile: {
headline: "Manage your subscription",
},
features: {
subscription_update: {
enabled: true,
default_allowed_updates: ["price", "quantity"],
proration_behavior: "create_prorations",
products: [
{
product: "prod_xxx",
prices: ["price_monthly", "price_annual"],
},
],
},
subscription_cancel: {
enabled: true,
mode: "at_period_end", // Don't cancel immediately
cancellation_reason: {
enabled: true,
options: [
"too_expensive",
"missing_features",
"switched_service",
"unused",
"other",
],
},
},
payment_method_update: { enabled: true },
invoice_history: { enabled: true },
},
});Why: Self-service billing reduces support tickets by 60-80%. Stripe's Customer Portal is a hosted solution that handles plan changes, proration, cancellation with reason capture, payment method updates, and invoice history -- all without building custom UI.
适用场景: 让客户自行管理其订阅(升级、降级、取消、更新支付方式),无需联系客服。
实现方式:
typescript
// Create portal session
// app/api/billing/portal/route.ts
export async function POST(req: NextRequest) {
const { userId } = await req.json();
const user = await db.user.findUniqueOrThrow({
where: { id: userId },
select: { stripeCustomerId: true },
});
if (!user.stripeCustomerId) {
return NextResponse.json({ error: "No billing account" }, { status: 400 });
}
const session = await stripe.billingPortal.sessions.create({
customer: user.stripeCustomerId,
return_url: `${process.env.NEXT_PUBLIC_URL}/settings/billing`,
});
return NextResponse.json({ url: session.url });
}typescript
// Configure the portal in Stripe (do this once, via API or Dashboard)
await stripe.billingPortal.configurations.create({
business_profile: {
headline: "Manage your subscription",
},
features: {
subscription_update: {
enabled: true,
default_allowed_updates: ["price", "quantity"],
proration_behavior: "create_prorations",
products: [
{
product: "prod_xxx",
prices: ["price_monthly", "price_annual"],
},
],
},
subscription_cancel: {
enabled: true,
mode: "at_period_end", // Don't cancel immediately
cancellation_reason: {
enabled: true,
options: [
"too_expensive",
"missing_features",
"switched_service",
"unused",
"other",
],
},
},
payment_method_update: { enabled: true },
invoice_history: { enabled: true },
},
});为什么选择此方案: 自助服务计费可减少60-80%的客服工单。Stripe的客户门户是一个托管解决方案,可处理计划变更、按比例计费、带原因收集的取消操作、支付方式更新和发票历史记录——所有这些都无需构建自定义UI。
Pattern 4: Usage-Based Billing
模式4:基于使用量的计费
When to use: When pricing is based on consumption (API calls, storage, compute minutes, seats) rather than flat-rate subscriptions.
Implementation:
typescript
// Report usage to Stripe
async function reportUsage(
subscriptionItemId: string,
quantity: number,
timestamp?: number
): Promise<void> {
await stripe.subscriptionItems.createUsageRecord(subscriptionItemId, {
quantity,
timestamp: timestamp ?? Math.floor(Date.now() / 1000),
action: "increment", // Add to existing usage (vs "set" to replace)
});
}
// Background job: aggregate and report usage hourly
async function reportHourlyUsage(): Promise<void> {
const activeSubscriptions = await db.subscription.findMany({
where: { status: "active", plan: { billingModel: "usage" } },
include: { user: true },
});
for (const sub of activeSubscriptions) {
const usage = await getHourlyUsage(sub.userId);
if (usage > 0) {
await reportUsage(sub.stripeSubscriptionItemId, usage);
await db.usageReport.create({
data: {
subscriptionId: sub.id,
quantity: usage,
reportedAt: new Date(),
},
});
}
}
}
// Track usage in your application
async function trackApiCall(userId: string, endpoint: string): Promise<void> {
// Increment usage counter (Redis for speed)
const key = `usage:${userId}:${getCurrentHour()}`;
await redis.incr(key);
await redis.expire(key, 86400 * 7); // Keep for 7 days
// Check if user is approaching their limit
const currentUsage = await getCurrentMonthUsage(userId);
const limit = await getUserPlanLimit(userId);
if (currentUsage >= limit * 0.8) {
await sendUsageWarningEmail(userId, currentUsage, limit);
}
if (currentUsage >= limit) {
throw new UsageLimitExceededError(userId, currentUsage, limit);
}
}Why: Usage-based billing aligns cost with value -- customers pay for what they use. Hourly aggregation reduces API calls to Stripe while keeping usage data fresh enough for invoicing. Redis-based tracking provides sub-millisecond usage checks for rate limiting.
适用场景: 定价基于使用量(API调用、存储、计算分钟数、席位)而非固定费率订阅时。
实现方式:
typescript
// Report usage to Stripe
async function reportUsage(
subscriptionItemId: string,
quantity: number,
timestamp?: number
): Promise<void> {
await stripe.subscriptionItems.createUsageRecord(subscriptionItemId, {
quantity,
timestamp: timestamp ?? Math.floor(Date.now() / 1000),
action: "increment", // Add to existing usage (vs "set" to replace)
});
}
// Background job: aggregate and report usage hourly
async function reportHourlyUsage(): Promise<void> {
const activeSubscriptions = await db.subscription.findMany({
where: { status: "active", plan: { billingModel: "usage" } },
include: { user: true },
});
for (const sub of activeSubscriptions) {
const usage = await getHourlyUsage(sub.userId);
if (usage > 0) {
await reportUsage(sub.stripeSubscriptionItemId, usage);
await db.usageReport.create({
data: {
subscriptionId: sub.id,
quantity: usage,
reportedAt: new Date(),
},
});
}
}
}
// Track usage in your application
async function trackApiCall(userId: string, endpoint: string): Promise<void> {
// Increment usage counter (Redis for speed)
const key = `usage:${userId}:${getCurrentHour()}`;
await redis.incr(key);
await redis.expire(key, 86400 * 7); // Keep for 7 days
// Check if user is approaching their limit
const currentUsage = await getCurrentMonthUsage(userId);
const limit = await getUserPlanLimit(userId);
if (currentUsage >= limit * 0.8) {
await sendUsageWarningEmail(userId, currentUsage, limit);
}
if (currentUsage >= limit) {
throw new UsageLimitExceededError(userId, currentUsage, limit);
}
}为什么选择此方案: 基于使用量的计费可使成本与价值对齐——客户只为其使用的服务付费。每小时聚合可减少对Stripe的API调用次数,同时保持使用数据足够新以用于开票。基于Redis的跟踪可提供亚毫秒级的使用量检查,用于速率限制。
Stripe Test Cards Reference
Stripe测试卡号参考
| Number | Scenario |
|---|---|
| Successful payment |
| 3D Secure required |
| Declined (insufficient funds) |
| Attaching to customer fails |
| Requires authentication |
Use any future expiry date and any 3-digit CVC.
| 卡号 | 场景 |
|---|---|
| 支付成功 |
| 需要3D Secure认证 |
| 支付被拒绝(余额不足) |
| 绑定到客户失败 |
| 需要身份验证 |
可使用任何未来到期日期和任意3位CVC码。
Anti-Patterns
反模式
| Anti-Pattern | Why It's Bad | Better Approach |
|---|---|---|
| Trusting client-side payment confirmation | Users can spoof success | Webhook handler is the source of truth |
| Handling raw card numbers on your server | PCI SAQ-D compliance (very expensive) | Use Stripe Elements or Checkout |
| No idempotency in webhook handlers | Double charges, duplicate provisioning | Deduplicate by event ID |
| Canceling subscriptions immediately | Users lose access mid-billing period | Cancel at period end ( |
| Hardcoding prices in your app | Can't change pricing without deploy | Store price IDs in database or environment |
| No dunning flow for failed payments | Silent revenue loss (involuntary churn) | Automated retry + dunning emails |
| Testing with real payment methods | Risk of real charges, no test clocks | Use Stripe test mode exclusively |
| 反模式 | 危害 | 更佳方案 |
|---|---|---|
| 信任客户端支付确认信息 | 用户可伪造成功状态 | Webhook处理程序为唯一可信来源 |
| 在服务器上处理原始银行卡号 | 需符合PCI SAQ-D合规性(成本极高) | 使用Stripe Elements或Checkout |
| Webhook处理程序未实现幂等性 | 重复收费、重复配置 | 通过事件ID去重 |
| 立即取消订阅 | 用户在计费周期中途失去访问权限 | 在计费周期结束时取消( |
| 在应用中硬编码价格 | 无需部署即可更改定价 | 将价格ID存储在数据库或环境变量中 |
| 未为失败支付设置催缴流程 | 无声的收入损失(非自愿流失) | 自动重试 + 催缴邮件 |
| 使用真实支付方式进行测试 | 存在真实收费风险,无测试时钟 | 仅使用Stripe测试模式 |
Checklist
检查清单
- Stripe API keys stored in environment variables (never in code)
- Webhook signature verification enabled
- Webhook handler is idempotent (event ID deduplication)
- All subscription status changes handled (created, updated, canceled, past_due)
- Failed payment dunning flow implemented (email + retry)
- Customer portal configured for self-service billing
- Test mode used for all development and staging
- PCI compliance level confirmed (SAQ-A with Stripe Checkout/Elements)
- Tax calculation enabled (Stripe Tax or external provider)
- Proration configured for plan changes (upgrade/downgrade)
- Webhook endpoint registered in Stripe Dashboard
- Stripe CLI installed for local webhook testing ()
stripe listen --forward-to
- Stripe API密钥存储在环境变量中(绝不要在代码中)
- 已启用Webhook签名验证
- Webhook处理程序具备幂等性(通过事件ID去重)
- 已处理所有订阅状态变更(创建、更新、取消、逾期)
- 已实现失败支付的催缴流程(邮件 + 重试)
- 已配置用于自助服务计费的客户门户
- 所有开发和 staging 环境均使用测试模式
- 已确认PCI合规级别(使用Stripe Checkout/Elements时为SAQ-A)
- 已启用税务计算(Stripe Tax或外部提供商)
- 已为计划变更(升级/降级)配置按比例计费
- 已在Stripe控制台中注册Webhook端点
- 已安装Stripe CLI用于本地Webhook测试()
stripe listen --forward-to
Related Resources
相关资源
- Skills: (user identity for billing),
authentication-patterns(dunning emails)email-systems - Skills: (payment failure alerting)
monitoring-observability - Rules: (API route patterns)
docs/reference/stacks/fullstack-nextjs-nestjs.md
- 技能: (计费相关的用户身份验证)、
authentication-patterns(催缴邮件)email-systems - 技能: (支付失败告警)
monitoring-observability - 规则: (API路由模式)
docs/reference/stacks/fullstack-nextjs-nestjs.md