FastSpring Quick Start

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

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

❌ FastSpring Dashboard 中还没有创建对应的产品

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

解决方案：完整配置步骤

第一步：登录 FastSpring Dashboard

1. 访问 FastSpring Dashboard
2. 使用以下凭证登录：

• Username: UAWI83UOQ2--HTJCRJ0FBQ
• Password: <从 FastSpring Dashboard 获取>

第二步：切换到 Test Mode

1. 登录后，点击右上角的账户菜单
2. 选择 Test 模式
3. 确认切换成功（通常会显示 🧪 图标或 "Test" 标签）

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

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

3.1 导航到产品页面

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

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

填写以下信息：

订阅配置：

• ✅ 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

4.1 导航到 Webhook 页面

1. 在左侧菜单，点击 Developer Tools > Webhooks
2. 点击 Add Webhook 或 New Webhook

4.2 配置 Webhook

4.3 选择事件

勾选以下事件（⭐ 必选）：

• ✅ order.completed ⭐
• ✅ subscription.activated ⭐
• ✅ subscription.charge.completed ⭐
• ✅ order.failed
• ✅ order.canceled
• ✅ subscription.deactivated
• ✅ subscription.canceled
• ✅ subscription.charge.failed
• ✅ return.created

4.4 保存 HMAC Secret

1. 点击 Save 后，FastSpring 会生成一个 HMAC Secret
2. ⚠️ 立即复制这个 Secret（只显示一次）
3. 保存到安全的地方

当前配置的 Secret:

<YOUR_HMAC_SECRET>

如果需要更新，请在 OpenDev 的 FastSpring 配置中同步更新。

第五步：验证配置

5.1 检查产品列表

在 Products 页面，你应该看到：

5.2 检查 Webhook

在 Webhooks 页面，你应该看到：

• URL: https://zinben.com/v1/payment/webhook/fastspring
• Status: ✅ Active
• Events: 9 个事件已选择

第六步：测试支付

1. 返回支付页面：https://zinben.com/member
2. 选择 专业版 或 企业版
3. 点击「管理订阅」
4. 选择 FastSpring 支付方式
5. 点击「继续前往 FastSpring 支付」

预期结果：

• ✅ 成功跳转到 FastSpring 结账页面
• ✅ 页面显示产品信息（OpenDev Pro Monthly - $9.99）
• ✅ 可以填写支付信息

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

在 FastSpring 结账页面：

点击 Complete Order 或 Pay。

完成后验证

验证 1: 支付成功

• FastSpring 页面显示「Payment Successful」或类似消息
• 自动重定向到成功页面

验证 2: Webhook 触发

查看后端日志：

tail -50 /Users/admin/AndroidStudioProjects/webapp/logs/backend.log | grep FastSpring

应该看到：

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

验证 3: 数据库记录

-- 检查订阅记录
SELECT * FROM payment_subscriptions 
WHERE user_id = '72c8533d-cf5f-417b-a82d-c0c12288bd9f' 
  AND platform = 'fastspring';

-- 检查会员等级
SELECT membership_tier, membership_expires_at 
FROM developer_accounts 
WHERE id = '72c8533d-cf5f-417b-a82d-c0c12288bd9f';

预期结果：

• 订阅记录存在且 status = 'active'
• 会员等级更新为 pro 或 enterprise

验证 4: 会员页面

访问 https://zinben.com/member，应该显示：

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

故障排查

问题：仍然显示 404

可能原因：

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

解决方案：

-- 检查 OpenDev 配置的 Product Path
SELECT product_id, JSON_EXTRACT(platform_product_ids, '$.fastspring') 
FROM payment_products 
WHERE app_id = 'opendev_platform';

确保输出的 Product Path 与 FastSpring Dashboard 中的完全一致。

问题：Webhook 未触发

检查：

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

测试 Webhook：

curl -X POST https://zinben.com/v1/payment/webhook/fastspring \
  -H "Content-Type: application/json" \
  -H "X-FS-Signature: test" \
  -d '{"events":[{"type":"order.completed"}]}'

查看后端日志是否有响应。

配置完成清单

在正式使用前，请确认：

• [ ] FastSpring Dashboard 已登录
• [ ] 已切换到 Test Mode
• [ ] 已创建 4 个产品，状态均为 Active
• [ ] Product Path 与 OpenDev 配置匹配
• [ ] Webhook 已配置，HMAC Secret 已保存
• [ ] 已选择必要的 Webhook 事件
• [ ] 测试支付流程成功
• [ ] Webhook 正常触发
• [ ] 会员状态正确更新

后续步骤

配置完成后：

1. 测试所有商品：分别测试 Pro 和 Enterprise，月付和年付
2. 测试 Webhook：确保所有事件都能正确处理
3. 准备上线：

• 切换到 Live Mode
• 更新 Storefront URL（去掉 .test）
• 重新生成 Live Mode 的 API Credentials
• 更新 OpenDev 配置

相关文档

• FastSpring 完整配置指南
• FastSpring 架构集成文档
• FastSpring Developer Documentation

文档版本: v1.0 创建日期: 2026-02-08 适用场景: FastSpring 首次配置和 404 错误排查