FastSpring 支付配置

本指南介绍如何配置 FastSpring 进行全球支付处理。FastSpring 作为 Merchant of Record (MoR) 运营，代您处理税务合规、发票和防欺诈。

前置条件

• FastSpring 账号（在此注册）
• 可访问 FastSpring 仪表盘
• 用于 Webhook 的后端服务器 URL

步骤一：创建 FastSpring 账号

1. 前往 FastSpring 注册
2. 完成注册和企业验证
3. 设置您的店面

步骤二：获取 API 凭证

1. 登录 FastSpring 仪表盘
2. 导航到 Developer Tools > API Credentials
3. 点击 Create API Credential
4. 记录以下信息：

警告： API 密码仅在创建时显示一次，请安全存储。

步骤三：配置店面设置

3.1 启用 Test Mode

在开始测试前，必须先启用 Test Mode：

1. 登录 FastSpring 仪表盘
2. 点击右上角账户菜单
3. 选择 Test 模式（而不是 Live）
4. 确认切换到 Test Environment

重要: 在 Test Mode 下：

• 所有支付都是测试支付，不会产生真实交易
• Session URL 会指向 Test Storefront
• 需要使用测试信用卡号

3.2 获取 Storefront URL

1. 在 FastSpring 仪表盘中，导航到 Storefront 或 Settings
2. 找到您的 Storefront URL，格式为：yourstore.onfastspring.com 或 yourstore.test.onfastspring.com（Test Mode）
3. 记录此 URL，配置 OpenDev 时需要用到

步骤四：创建产品

4.1 创建产品的必要性

必须先在 FastSpring 仪表盘创建产品，否则 Checkout Session 会返回 404 错误。

4.2 使用 FastSpring 仪表盘创建产品

1. 确保处于 Test Mode
2. 导航到 Products > Products
3. 点击 New Product 或 Create Product
4. 填写产品信息：

1. 配置定价：

• Base Price: 9.99
• Currency: USD
• FastSpring 会自动处理货币转换和税费计算

4.3 订阅产品特定配置

对于订阅产品，需要额外配置：

1. Billing Frequency：Monthly / Yearly
2. Trial Period（可选）：例如 7 days
3. Renewal Options：✅ Auto-renew by default

4.4 必须创建的产品列表

Product Path 必须完全匹配: OpenDev 配置中的 platformProductIds.fastspring 必须与 FastSpring 仪表盘中的 Product Path 完全一致。

步骤五：配置 Webhook

1. 在 FastSpring 仪表盘，导航到 Developer Tools > Webhooks
2. 点击 Add Webhook 或 New Webhook
3. 配置 Webhook：

1. 选择监听的事件：

• ✅ order.completed — 订单完成
• ✅ order.failed — 订单失败
• ✅ order.canceled — 订单取消
• ✅ subscription.activated — 订阅激活
• ✅ subscription.deactivated — 订阅停用
• ✅ subscription.canceled — 订阅取消
• ✅ subscription.charge.completed — 订阅续费成功
• ✅ subscription.charge.failed — 订阅续费失败
• ✅ return.created — 退款创建

1. HMAC Secret: 复制生成的 Secret（仅显示一次），保存到 OpenDev 配置中

步骤六：在 OpenDev 中配置

1. 登录 OpenDev 平台
2. 导航到应用的 支付配置 页面
3. 找到 FastSpring 卡片，点击 配置
4. 填写配置信息：

配置数据结构

{
  "apiUsername": "your_api_username",
  "apiPassword": "your_api_password",
  "storefront": "yourstore.onfastspring.com",
  "storefrontPath": "yourstore.onfastspring.com/popup-yourstore",
  "webhookSecret": "your_hmac_secret"
}

步骤七：配置商品档位

关联 FastSpring Product Path 到您的商品档位：

1. 前往 OpenDev 中的 商品档位
2. 为每个档位添加 FastSpring Product Path：

{
  "productId": "opendev_pro_monthly",
  "platformProductIds": {
    "stripe": "price_xxx",
    "fastspring": "opendev-pro-monthly",
    "google_play": "com.walknote.opendev.pro.monthly",
    "apple": "opendev_pro_monthly_ios"
  }
}

步骤八：结账流程

重定向结账（默认）

结账流程类似 Stripe 托管结账：

1. 用户选择 FastSpring 支付方式
2. 后端通过 FastSpring Session API 创建结账会话
3. 用户被重定向到 FastSpring 托管结账页面
4. FastSpring 处理支付、税费计算和发票
5. 成功后 FastSpring 发送 order.completed Webhook
6. 后端处理 Webhook 并激活会员

API 端点

Webhook 处理

FastSpring Webhook 的处理与 Stripe 类似：

1. 签名验证：使用 X-FS-Signature 头进行 HMAC-SHA256 验证
2. 幂等性：事件 ID 去重防止重复处理
3. 快速响应：立即返回 200，异步处理业务

Webhook 事件流程

FastSpring → POST /v1/payment/webhook/fastspring
           → 验证 HMAC 签名
           → 检查事件幂等性
           → 记录 Webhook 事件
           → 返回 200
           → 异步：处理事件
              → 更新订单状态
              → 更新交易记录
              → 激活会员（如适用）

故障排查

错误：FastSpring not configured for this app

解决方案： 确保 FastSpring 配置已在 OpenDev 应用设置中保存且状态为 "active"。

错误：FastSpring product not configured

解决方案： 将 FastSpring Product Path 添加到商品档位的 platformproductids.fastspring 字段。

Webhook 未收到事件

解决方案：

• 验证 Webhook URL 可公网访问（需 HTTPS）
• 检查 FastSpring 仪表盘中的 Webhook 配置
• 验证 HMAC Secret 是否一致

支付成功但会员未激活

解决方案：

• 检查数据库中的 Webhook 日志（paymentwebhooklogs 表）
• 验证 FastSpring 订单中是否包含 tags.orderId
• 检查会员激活日志中的错误

FastSpring 与 Stripe 主要区别

相关文档

• FastSpring Developer Hub
• FastSpring API Reference
• FastSpring Webhooks
• Stripe 支付配置
• OpenDev 支付配置