支付成功回调处理

用户完成支付后，系统需要「知道」这笔交易已经成功，并据此更新用户的权限、订阅状态或订单信息。如果这一步出错，用户付了钱却享受不到服务，后果比支付失败本身更严重。支付成功回调处理，就是连接「钱已到账」和「服务已开通」之间的桥梁。

本文以 Stripe Checkout 为主要示例，结合国内微信支付的回调机制，梳理支付成功回调的完整链路：从 success_url 跳转，到 Session 状态查询，到用户权限更新，再到安全保障和用户体验设计。

支付成功回调的完整流程

一次支付成功后的回调处理，并不是单一动作，而是一条由前端到后端、由外部平台到内部系统的链路。整个流程可以拆解为四个阶段：

第一阶段：用户支付完成

用户在 Stripe Checkout 页面（嵌入式或跳转式）完成支付。此时 Stripe 侧会完成以下操作：

1. 标记 Checkout Session 的 payment_status 为 paid，status 为 complete
2. 向商户后端发送 checkout.session.completed Webhook 事件
3. 将用户浏览器重定向到商户预设的 success_url

这里有一个关键认知：Webhook 和 success_url 重定向是两条独立通道。Webhook 走服务端到服务端，可靠性高；success_url 走用户浏览器跳转，可能被用户关闭、网络中断或浏览器拦截。两者不能互相替代，也不能假设谁一定先到。

第二阶段：用户跳转到 success_url

Stripe 会将用户重定向到你在创建 Checkout Session 时指定的 success_url。典型的写法是在 URL 中携带 Session ID：

const session = await stripe.checkout.sessions.create({
  // ...
  success_url: 'https://yoursite.com/payment/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://yoursite.com/payment/cancel',
})

{CHECKOUT_SESSION_ID} 是 Stripe 的模板变量，会在实际跳转时替换为真实的 Session ID。你的成功页面从 URL query 中取出这个 ID，用于下一步的状态查询。

第三阶段：查询 Session 状态

拿到 Session ID 后，后端（或 Server Component）调用 Stripe API 查询 Session 的完整信息：

const session = await stripe.checkout.sessions.retrieve(sessionId)
 
if (session.status === 'complete' && session.payment_status === 'paid') {
  // 支付已确认，执行业务逻辑
}

这一步的核心目的是用 Stripe 的权威数据确认支付状态，而不是信任前端传过来的任何参数。用户可以手动修改 URL 中的 query 参数，但无法伪造 Stripe API 返回的数据。

第四阶段：更新业务状态

确认支付成功后，系统需要更新对应的业务数据：

1. 将订单状态从 pending 更新为 paid
2. 如果是订阅，激活用户的订阅权限
3. 如果是一次性购买，发放对应的商品或服务
4. 清理购物车、发送确认邮件等后续操作

这些操作需要保证幂等性——同一条支付确认可能被处理多次（Webhook 重试、用户刷新页面），系统必须确保不会重复发货或重复开通。

Session 状态查询详解

Session 状态查询是回调链路中最核心的验证环节。它解决的根本问题是：如何确认一笔支付真的成功了。

Session 的关键字段

一个 Checkout Session 对象包含多个状态字段，各有不同的含义：

判断支付是否成功，通常需要同时检查 status === 'complete' 和 payment_status === 'paid'。只检查其中一个是不够的——status 为 complete 但 payment_status 为 unpaid 的情况，可能出现在免费试用或 0 元订单中。

两种查询方式对比

实际项目中，通常两者结合：后端通过 Stripe API 确认状态并更新数据库，前端通过后端 API 获取展示所需的订单信息。

Webhook 与主动查询的关系

Stripe 的 Webhook 和 Session API 查询是互补关系：

最佳实践是：以 Webhook 为主，以 success_url + Session 查询为辅。Webhook 负责最终的业务状态更新，success_url 负责给用户提供即时的成功反馈。

用户权限更新

支付确认后的权限更新，是直接影响用户体验的环节。用户付了钱，期望的是「立即」获得服务，而不是等几分钟甚至等客服手动处理。

数据库更新策略

权限更新的核心是确保数据一致性。常见的做法是：

1. 乐观更新：在 success_url 页面中先展示「处理中」，后端完成实际更新后再展示最终状态
2. 数据库事务：将订单状态更新和权限开通放在同一个数据库事务中，确保要么都成功，要么都失败
3. 幂等标记：在订单表中增加 processed_at 字段，处理前先检查该字段是否已有值

async function handlePaymentSuccess(sessionId: string) {
  const session = await stripe.checkout.sessions.retrieve(sessionId)
 
  // 幂等检查：如果已处理则直接返回
  const order = await db.order.findUnique({
    where: { stripeSessionId: sessionId },
  })
  if (order?.processedAt) {
    return { success: true, alreadyProcessed: true }
  }
 
  // 事务更新
  await db.$transaction(async (tx) => {
    // 更新订单状态
    await tx.order.update({
      where: { stripeSessionId: sessionId },
      data: {
        status: 'paid',
        processedAt: new Date(),
      },
    })
 
    // 开通用户权限
    if (session.subscription) {
      await tx.userSubscription.upsert({
        where: { userId: order.userId },
        create: {
          userId: order.userId,
          stripeSubscriptionId: session.subscription,
          status: 'active',
          currentPeriodEnd: new Date(session.current_period_end * 1000),
        },
        update: {
          status: 'active',
          currentPeriodEnd: new Date(session.current_period_end * 1000),
        },
      })
    }
  })
}

缓存刷新

如果用户权限信息被缓存在 Redis、JWT Token 或前端状态中，权限更新后需要同步刷新：

安全问题

支付回调是攻击者的高价值目标。伪造支付成功通知、篡改 Session ID、重放旧请求——这些攻击手段都可能导致未付费用户获得服务。

核心安全威胁

Webhook 签名验证

Stripe 的每个 Webhook 请求都带有 Stripe-Signature 头，包含时间戳和签名。验证过程如下：

import Stripe from 'stripe'
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET
 
function handleWebhook(rawBody: string, signature: string) {
  const event = stripe.webhooks.constructEvent(
    rawBody,
    signature,
    webhookSecret
  )
  // 签名验证通过，event 是可信的
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object
    // 处理业务逻辑
  }
}

签名验证确保了：请求确实来自 Stripe，且内容在传输过程中没有被篡改。这个步骤不能省略——没有签名验证的 Webhook endpoint 等于向所有人开放。

Session 归属校验

仅仅验证 Session ID 存在还不够，还需要确认这个 Session 属于当前用户：

const session = await stripe.checkout.sessions.retrieve(sessionId)
 
if (session.customer !== currentUser.stripeCustomerId) {
  // Session 不属于当前用户，拒绝处理
  throw new Error('Session ownership mismatch')
}

这防止了用户 A 使用用户 B 的 Session ID 来「骗取」支付成功状态。

用户体验设计

支付成功页面是用户完成支付后看到的第一个页面，它承担着确认、引导和安抚三重职责。

成功页面的核心要素

一个设计良好的支付成功页面应该包含以下信息：

1. 明确的成功状态：用清晰的视觉信号（绿色图标、对勾）告知用户支付已完成
2. 订单摘要：展示购买的商品、金额、订单号等关键信息
3. 下一步指引：告诉用户接下来会发生什么——是立即可以使用，还是等待邮件通知
4. 联系方式：如果出了问题（虽然概率很低），用户知道如何找到帮助

自动跳转与轮询策略

在某些场景下，success_url 页面加载时，后端的 Webhook 可能还没有处理完成。此时需要在前端做轮询：

推荐的做法是轮询 + 超时兜底：

// 前端轮询逻辑
async function pollPaymentStatus(sessionId: string, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const result = await fetchOrderStatus(sessionId)
 
    if (result.status === 'processed') {
      return { success: true, order: result.order }
    }
 
    if (i < maxAttempts - 1) {
      await sleep(1500) // 等待 1.5 秒后重试
    }
  }
 
  // 超时兜底：展示「处理中」并提供联系方式
  return { success: false, message: '支付已确认，订单正在处理中...' }
}

邮件通知

无论成功页面的体验做得多好，邮件通知仍然是必要的补充：

1. 作为支付凭证：用户可能关闭浏览器，邮件是持久的记录
2. 作为提醒：包含订单详情、订阅信息、续费日期等
3. 作为联系方式：如果支付出现问题，用户可以通过邮件回复寻求帮助

邮件应该在 Webhook 处理完成后立即发送，而不是在 success_url 页面中触发——因为用户可能不会等待页面加载完成就关闭了浏览器。

完整流程：Mermaid 流程图

案例分析

案例一：SaaS 订阅服务的回调处理

一个 AI 写作工具提供月付 $29 的 Pro 订阅。用户点击「升级 Pro」后跳转到 Stripe Checkout，支付完成后需要立即获得 Pro 权限。

实现方案：

1. 创建 Checkout Session 时设置 mode: 'subscription'，success_url 携带 session_id
2. 后端监听 checkout.session.completed Webhook，收到后：
   • 从 Session 中提取 customer 和 subscription 字段
   • 根据 customer 找到对应的用户记录
   • 更新用户的 plan 为 pro，记录 subscriptionId 和 currentPeriodEnd
   • 清除 Redis 中的用户权限缓存
3. 前端 success 页面加载后，调用 /api/me 接口获取最新用户信息
4. 由于 Webhook 通常在 1-2 秒内到达，前端在 success_url 页面做一次 1.5 秒的延迟请求即可拿到最新状态
5. 同时发送一封「欢迎升级 Pro」的邮件，包含新功能介绍和使用指引

关键决策： 选择以 Webhook 为主、前端轮询为辅的方案。因为 SaaS 场景对权限生效的时效性要求高，但又不愿意冒「用户看到免费版」的风险，所以前端做了 1.5 秒的延迟请求，而不是立即展示。

案例二：数字商品一次性购买的回调处理

一个设计素材商店出售单个 $5 的图标包。用户购买后需要立即下载文件。

实现方案：

1. 创建 Checkout Session 时设置 mode: 'payment'，在 metadata 中记录 productId
2. 后端监听 checkout.session.completed Webhook，收到后：
   • 从 Session 的 metadata 中取出 productId
   • 在订单表创建一条记录，状态为 paid
   • 生成一个带过期时间的下载链接（如 24 小时有效）
3. 前端 success 页面通过 session_id 查询后端，获取下载链接
4. 邮件中包含下载链接和订单详情

关键决策： 一次性购买场景下，幂等性更加重要——Webhook 重试不能生成多个下载链接。方案是在订单表中用 stripeSessionId 做唯一索引，重复的 Webhook 会因为唯一约束而跳过。

对比总结

回调处理方案对比

安全检查清单对比

用户体验方案对比

权限更新策略对比

实践检查清单

在上线支付成功回调功能前，逐项检查以下内容：

• success_url 中包含 {CHECKOUT_SESSION_ID} 模板变量
• 后端通过 Stripe API 查询 Session 状态，而非信任前端传参
• 同时检查 status === 'complete' 和 payment_status === 'paid'
• Webhook endpoint 验证 Stripe-Signature 签名
• 校验 Session 的 customer 与当前登录用户匹配
• 业务处理逻辑具备幂等性（重复 Webhook 不会重复执行）
• 订单状态更新和用户权限更新在同一数据库事务中
• 前端 success 页面有轮询或兜底逻辑处理 Webhook 延迟
• 支付确认邮件在 Webhook 处理后发送，而非在 success 页面中发送
• Webhook endpoint 返回 HTTP 200 表示处理成功，避免 Stripe 不必要的重试
• 日志记录了所有回调事件和处理结果，便于排查问题
• 监控覆盖了 Webhook 失败率、处理延迟和权限更新成功率

参考资料

1. Stripe — Customize redirect behavior — 官方文档，介绍如何配置 success_url 和自定义成功页面。
2. Stripe — The Checkout Sessions API — Checkout Session 的生命周期、状态字段和过期机制。
3. Stripe — Types of events — Webhook 事件类型列表，包含 checkout.session.completed 等关键事件。
4. 微信支付 — 支付成功回调通知 — 微信支付回调通知的验签和处理流程，对比 Stripe 的 Webhook 机制。
5. 微信支付 — 支付回调和查单实现指引 — 回调通知和主动查单的配合使用，幂等处理的最佳实践。
6. Stripe — Accept a payment — Stripe 支付接入的完整指南，包含 Checkout、Payment Intent 和 Webhook 的使用。