[JS/TS] Next.js网站接入Stripe支付全流程：从账号注册到Webhook配置

为出海网站或应用集成支付功能时，Stripe 因其全球通用性、完善的文档和对开发者友好而成为普遍选择。它不仅支持国际信用卡，也兼容微信、支付宝等本地支付方式，为服务全球用户提供了便利。

本文将基于一个 Next.js 项目实战，详细介绍从零开始接入 Stripe 支付并成功收款的完整流程，涵盖账号配置、本地测试、生产环境部署及常见问题。

一、Stripe 账号注册与团队协作

注册 Stripe 账号是第一步。个人开发者可直接访问 Stripe Dashboard 进行注册。在团队协作场景下，主账号持有者可以在 Stripe 平台邀请成员，被邀请者通过邮件链接注册后便会自动加入团队，其权限由分配的角色决定。

注册成功后，重点关注测试模式与正式模式的切换。Stripe 为两种环境提供了独立的 API 密钥（公钥 pk_ 开头，私钥 sk_ 开头）。测试密钥以 _test_ 标识，不会产生真实交易。最直接的切换方式是通过浏览器地址栏：dashboard.stripe.com/test/... 为测试模式，去掉 test 路径即为正式模式。

二、理解 Stripe Checkout 支付流程

在动手编码前，理解其核心流程至关重要：

1. 用户在前端点击支付。
2. 你的后端服务调用 Stripe API 创建一个 Checkout Session（支付会话）。
3. 前端引导用户跳转至 Stripe 生成的安全、美观的支付页面。
4. 用户完成支付。
5. Stripe 通过 Webhook 主动向你的服务器发送支付成功通知。
6. 你的服务收到通知并验证后，更新本地订单状态。

整个过程无需自建支付页面，极大地简化了开发并提升了安全性。

三、本地开发与测试环境搭建

本地开发的最大挑战在于 Webhook 需要公网可访问的地址，而 Stripe 无法回调 localhost。解决方案是使用 Stripe CLI 进行请求转发。

1. 安装 Stripe CLI
对于 macOS 用户，推荐使用 Homebrew：

brew install stripe/stripe-cli/stripe

若因网络问题安装失败，可前往 GitHub Releases 手动下载对应系统的二进制文件，解压后放置到系统路径下。

2. 登录并转发 Webhook
在终端执行登录命令，并按提示在浏览器中完成授权：

stripe login

登录成功后，启动 Webhook 转发，将其指向你本地的后端接口（例如 Next.js API 路由）：

stripe listen --forward-to localhost:3000/api/payment/webhook

命令执行后，终端会显示一个 whsec_ 开头的 Webhook 签名密钥，请妥善保存。

3. 配置环境变量
在项目的 .env.local 文件中配置必要的密钥：

# Stripe 支付配置（测试环境）
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxx
STRIPE_SECRET_KEY=sk_test_xxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxx  # 这里填写上一步CLI生成的密钥

配置完成后重启开发服务器。

4. 使用测试卡支付
在支付测试页面，可使用 Stripe 提供的通用测试卡号：4242 4242 4242 4242，任意未来日期作为有效期，任意三位数作为 CVC。此操作将模拟一次成功的支付。

四、生产环境 Webhook 配置

线上环境需要你在 Stripe Dashboard 中手动配置 Webhook，以便 Stripe 能将实时事件通知到你的生产服务器。

1. 进入 Dashboard：Developers -> Webhooks。
2. 点击 Add endpoint。
3. 输入你的 Webhook 接收地址，例如：https://yourdomain.com/api/payment/webhook。
4. 在事件选择中，至少勾选 checkout.session.completed 事件（支付成功）。
5. 点击创建后，页面会生成一个新的 Signing secret。

务必将此生产环境的 Secret 更新到你的服务器环境变量中，并与本地测试用的密钥区分开。在后端服务中，需要使用此密钥对所有传入的 Webhook 请求进行签名验证，以确保请求来源的真实性。

五、生产环境安全最佳实践

项目正式上线前，建议采取以下安全措施：

1. 使用受限密钥：在 Developers -> API keys 页面，不要直接使用默认的超级密钥。点击“Create restricted key”，根据最小权限原则，仅为密钥分配必要的权限（例如：创建 Checkout Session、读取支付信息等）。
2. 切换正式密钥：将环境变量中的 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY 和 STRIPE_SECRET_KEY 替换为正式环境的 _live_ 密钥。
3. 金额单位注意：Stripe 大部分货币金额以最小单位传递。例如，美元是“分”，收取 39 美元应传递 amount: 3900。

六、常见问题与踩坑点

1. Webhook 验签失败：最常见的原因是混合使用了不同环境的签名密钥。请确保本地开发使用 CLI 生成的密钥，生产环境使用 Dashboard 生成的密钥。
2. 模式混淆：严防将测试环境的 API 密钥用于生产交易，反之亦然。始终通过密钥前缀（test / live）进行区分。
3. 税务与费用：对于内测或特定区域，可以在 Dashboard 中设置优惠码（Promotion Code）来减免手续费，否则每笔交易将产生约 3% + $0.3 的平台费用。
4. Webhook 端点可靠性：确保你的 Webhook 处理接口具有幂等性，并能正确处理 Stripe 的重试机制，防止因网络问题导致订单状态更新失败。这部分属于运维与DevOps的监控和告警范畴，需要给予关注。

完成以上所有步骤并进行完整的端到端测试后，你的网站便已成功接入了稳定可靠的 Stripe 支付系统。