EN

FastSpring 快速配置指南

问题诊断：为什么出现 404 错误？

当你点击「继续前往 FastSpring 支付」后看到 HTTP ERROR 404，说明：

FastSpring 仪表盘中还没有创建对应的产品

FastSpring 的 Checkout Session 需要引用已存在的产品。如果产品不存在，Session URL 会返回 404。

解决方案：完整配置步骤

第一步：登录 FastSpring 仪表盘

  1. 访问 FastSpring 仪表盘
  2. 使用您的凭证登录

第二步：切换到 Test Mode

  1. 登录后，点击右上角的账户菜单
  2. 选择 Test 模式
  3. 确认切换成功

重要: 在测试阶段必须使用 Test Mode，否则会产生真实交易。

第三步：创建产品（必须！）

3.1 导航到产品页面

  1. 在左侧菜单，点击 Products > Products
  2. 点击 New Product 或 Create Product 按钮

3.2 创建第一个产品：Pro 月付

填写以下信息：

字段 值
Product Path opendev-pro-monthly
Display Name OpenDev Pro Monthly
Description Professional plan with advanced features - billed monthly
Product Type Subscription
Billing Frequency 1 month
Base Price 9.99
Currency USD
Fulfillment Webhook 或 None
Status Active ✅

订阅配置：

  • ✅ Auto-renew by default: 启用
  • Trial Period: 可选（如 7 days）

点击 Save 保存。

3.3 创建其他产品

重复上述步骤，创建以下产品：

产品 2: Pro 年付

  • Product Path: opendev-pro-yearly
  • Display Name: OpenDev Pro Yearly
  • Billing Frequency: 1 year
  • Base Price: 99.99 USD

产品 3: Enterprise 月付

  • Product Path: opendev-enterprise-monthly
  • Display Name: OpenDev Enterprise Monthly
  • Billing Frequency: 1 month
  • Base Price: 29.99 USD

产品 4: Enterprise 年付

  • Product Path: opendev-enterprise-yearly
  • Display Name: OpenDev Enterprise Yearly
  • Billing Frequency: 1 year
  • Base Price: 299.99 USD

第四步：配置 Webhook

  1. 导航到 Developer Tools > Webhooks
  2. 点击 Add Webhook 或 New Webhook
  3. 配置如下：
字段 值
URL https://zinben.com/v1/payment/webhook/fastspring
Description OpenDev Payment Webhook
  1. 勾选以下事件（⭐ 必选）：
  • ✅ order.completed ⭐
  • ✅ subscription.activated ⭐
  • ✅ subscription.charge.completed ⭐
  • ✅ order.failed
  • ✅ order.canceled
  • ✅ subscription.deactivated
  • ✅ subscription.canceled
  • ✅ subscription.charge.failed
  • ✅ return.created
  1. 保存后立即复制 HMAC Secret（仅显示一次）

第五步：验证配置

5.1 检查产品列表

Product Path Display Name Type Status
opendev-pro-monthly OpenDev Pro Monthly Subscription ✅ Active
opendev-pro-yearly OpenDev Pro Yearly Subscription ✅ Active
opendev-enterprise-monthly OpenDev Enterprise Monthly Subscription ✅ Active
opendev-enterprise-yearly OpenDev Enterprise Yearly Subscription ✅ Active

第六步：测试支付

  1. 返回支付页面
  2. 选择 专业版 或 企业版
  3. 选择 FastSpring 支付方式
  4. 点击「继续前往 FastSpring 支付」

预期结果：

  • ✅ 成功跳转到 FastSpring 结账页面
  • ✅ 页面显示产品信息
  • ✅ 可以填写支付信息

第七步：使用测试卡完成支付

字段 测试值
Email test@example.com
Card Number 4242 4242 4242 4242
Expiry 任意未来日期（如 12/28）
CVC 任意 3 位数（如 123）
Name Test User

完成后验证

验证 1: 支付成功

  • FastSpring 页面显示「Payment Successful」
  • 自动重定向到成功页面

验证 2: Webhook 触发

查看后端日志应包含： 

[INFO] FastSpring webhook received: order.completed
[INFO] FastSpring webhook signature verified
[INFO] User membership activated

验证 3: 会员页面

访问会员页面应显示：

  • 当前方案：专业版 或 企业版
  • 到期时间：显示正确的日期

故障排查

仍然显示 404

可能原因：

  1. Product Path 不匹配
  2. 产品状态不是 Active
  3. 未切换到 Test Mode

Webhook 未触发

检查：

  1. Webhook URL 是否正确配置
  2. 服务器是否可公网访问（不能是 localhost）
  3. HMAC Secret 是否匹配

配置完成清单

  • [ ] FastSpring 仪表盘已登录
  • [ ] 已切换到 Test Mode
  • [ ] 已创建 4 个产品，状态均为 Active
  • [ ] Product Path 与 OpenDev 配置匹配
  • [ ] Webhook 已配置，HMAC Secret 已保存
  • [ ] 已选择必要的 Webhook 事件
  • [ ] 测试支付流程成功

后续步骤

  1. 测试所有商品：分别测试 Pro 和 Enterprise，月付和年付
  2. 测试 Webhook：确保所有事件都能正确处理
  3. 准备上线：
  • 切换到 Live Mode
  • 更新 Storefront URL
  • 重新生成 Live Mode 的 API Credentials
  • 更新 OpenDev 配置

相关文档