FastSpring Payment Setup

This guide covers setting up FastSpring for global payment processing. FastSpring operates as a Merchant of Record (MoR), handling tax compliance, invoicing, and fraud prevention on your behalf.

Prerequisites

• FastSpring account (Create one here)
• Access to FastSpring Dashboard
• Your backend server URL for webhooks

Step 1: Create a FastSpring Account

1. Go to FastSpring and sign up
2. Complete onboarding and business verification
3. Set up your storefront

Step 2: Get API Credentials

1. Log in to FastSpring Dashboard
2. Navigate to Developer Tools > API Credentials
3. Click Create API Credential
4. Note down:

Warning: The API Password is only shown once when created. Store it securely.

Step 3: Configure Store Settings (重要！)

3.1 启用 Test Mode

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

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

⚠️ 重要: 在 Test Mode 下：

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

3.2 获取 Storefront URL

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

Step 4: Create Products

4.1 创建产品的必要性

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

4.2 使用 FastSpring Dashboard 创建产品

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: 1 month
• Yearly: 1 year

1. Trial Period (可选):

• 例如：7 days

1. Renewal Options:

• ✅ Auto-renew by default

4.4 必须创建的产品列表

根据你的系统配置，需要在 FastSpring 创建以下产品：

⚠️ Product Path 必须完全匹配: OpenDev 配置中的 platformProductIds.fastspring 必须与 FastSpring Dashboard 中的 Product Path 完全一致。

4.5 验证产品创建成功

1. 在 Products 列表中，确认产品状态为 Active
2. 点击产品查看详情，复制 Product Path
3. 确保 Product Path 与 OpenDev 配置一致

Step 5: Configure Webhooks

1. 在 FastSpring Dashboard，导航到 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:

• FastSpring 会生成一个 HMAC Secret
• 复制这个 Secret（只显示一次）
• 保存到 OpenDev 配置中

1. 点击 Save 保存 Webhook 配置

⚠️ 安全提示:

• HMAC Secret 用于验证 Webhook 签名，防止伪造请求
• 妥善保管，不要提交到代码库

Step 6: Configure in OpenDev

6.1 通过 OpenDev Dashboard 配置

1. 登录 OpenDev Platform
2. 导航到应用的 应用详情 页面
3. 切换到 支付配置 Tab
4. 找到 FastSpring 卡片，点击 配置 按钮
5. 填写配置信息：

1. Click Save

Configuration Data Structure

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

Step 6: Configure Product Tiers

Link FastSpring Product Paths to your product tiers:

1. Go to Product Tiers in OpenDev
2. For each tier, click "Enable Payment" or "Edit Payment"
3. Add the 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"
  }
}

Step 7: Checkout Flow

Redirect Checkout (Default)

The checkout flow is similar to Stripe Hosted Checkout:

1. User selects FastSpring payment method
2. Backend creates a checkout session via FastSpring Session API
3. User is redirected to FastSpring's hosted checkout page
4. FastSpring handles payment, tax calculation, and invoicing
5. On success, FastSpring sends order.completed webhook
6. Backend processes webhook and activates membership

API Endpoints

Create Checkout Session

curl -X POST "https://yourdomain.com/v1/payment/fastspring/checkout" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "appId": "opendev_platform",
    "productId": "opendev_pro_monthly",
    "successUrl": "https://yourdomain.com/payment/success",
    "cancelUrl": "https://yourdomain.com/payment/cancel"
  }'

Response:

{
  "code": 0,
  "msg": "success",
  "data": {
    "orderId": "ord_abc123",
    "sessionId": "fs_session_xxx",
    "checkoutUrl": "https://yourstore.onfastspring.com/session/xxx",
    "amount": 9.99,
    "currency": "USD",
    "expiresAt": 1738500000000
  }
}

Step 8: Webhook Processing

FastSpring webhooks are processed similarly to Stripe:

1. Signature Verification: HMAC-SHA256 verification using X-FS-Signature header
2. Idempotency: Event ID deduplication prevents double processing
3. Quick Response: Return 200 immediately, process asynchronously

故障排查指南

问题 1: FastSpring Checkout 页面显示 404 错误

症状：点击「继续前往 FastSpring 支付」后，跳转到 FastSpring 页面显示 HTTP ERROR 404

原因分析：

1. ❌ 产品未在 FastSpring Dashboard 创建（最常见）
2. ❌ Product Path 不匹配
3. ❌ Test Mode 未启用
4. ❌ Storefront URL 配置错误

解决方案：

✅ 步骤 1: 确认 FastSpring Dashboard 中已创建产品

1. 登录 FastSpring Dashboard
2. 切换到 Test Mode（右上角）
3. 导航到 Products > Products
4. 确认以下产品存在且状态为 Active：

• opendev-pro-monthly
• opendev-pro-yearly
• opendev-enterprise-monthly
• opendev-enterprise-yearly

如果产品不存在，请按照 Step 4 创建产品。

✅ 步骤 2: 验证 Product Path 匹配

FastSpring Dashboard 中的 Product Path:

opendev-pro-monthly

OpenDev 数据库中的配置:

SELECT product_id, JSON_EXTRACT(platform_product_ids, '$.fastspring') as fastspring_path
FROM payment_products 
WHERE product_id = 'opendev_pro_monthly';

预期结果:

product_id             | fastspring_path
-----------------------|------------------
opendev_pro_monthly    | "opendev-pro-monthly"

两者必须完全一致（不包括引号）。

✅ 步骤 3: 确认 Test Mode 已启用

1. 在 FastSpring Dashboard，点击右上角账户菜单
2. 确认当前处于 Test 环境（不是 Live）
3. Test Mode URL 格式：yourstore.test.onfastspring.com/SESSION_ID
4. Live Mode URL 格式：yourstore.onfastspring.com/SESSION_ID

在测试阶段必须使用 Test Mode。

✅ 步骤 4: 验证 Storefront URL

检查 OpenDev 配置:

SELECT id, platform, config_encrypted 
FROM payment_configs 
WHERE platform = 'fastspring' AND app_id = 'opendev_platform';

解密后的配置应包含：

{
  "apiUsername": "UAWI83UOQ2--HTJCRJ0FBQ",
  "apiPassword": "<从 FastSpring Dashboard 获取>",
  "storefront": "zinben.onfastspring.com",
  "webhookSecret": "<从 FastSpring Dashboard 获取>"
}

Storefront URL 规则:

• Test Mode: 使用 yourstore.test.onfastspring.com
• Live Mode: 使用 yourstore.onfastspring.com

问题 2: FastSpring API 返回 "required: Purchaser account or contact"

症状：后端日志显示 FastSpring API 返回 400 错误，消息为 "required"

原因：FastSpring 要求提供购买者的联系信息

解决方案：

已在代码中自动添加占位符邮箱 guest@example.com。如果问题仍然存在，确保：

1. 用户已登录（提供真实邮箱）
2. 或在 checkout 请求中传入 contact 参数：

{
  "appId": "opendev_platform",
  "productId": "opendev_pro_monthly",
  "contact": {
    "email": "user@example.com"
  }
}

问题 3: Webhook 未触发或验签失败

症状：支付成功但会员状态未更新

检查清单：

1. Webhook URL 是否配置正确：

https://yourdomain.com/v1/payment/webhook/fastspring

1. HMAC Secret 是否匹配：

• FastSpring Dashboard 和 OpenDev 配置中的 Secret 必须一致

1. 服务器是否可公网访问：

• FastSpring 无法向 localhost 发送 Webhook
• 使用 ngrok 或部署到真实服务器

验证 Webhook：

SELECT event_type, status, created_at 
FROM payment_webhook_logs 
WHERE platform = 'fastspring' 
ORDER BY created_at DESC 
LIMIT 10;

问题 4: 测试卡支付失败

FastSpring Test Mode 测试卡号：

问题 5: Session URL 格式错误

正确格式：

https://zinben.onfastspring.com/SESSION_ID

错误格式：

https://zinben.onfastspring.com/session/SESSION_ID  ❌

如果遇到此问题，检查 fastSpringProcessor.js 中的 URL 构建逻辑。

配置验证检查清单

在正式使用 FastSpring 前，请确认：

• [ ] FastSpring Dashboard 已创建所有需要的产品
• [ ] Product Path 与 OpenDev 配置完全匹配
• [ ] 处于 Test Mode（测试阶段）
• [ ] API Credentials（Username + Password）已正确配置
• [ ] Storefront URL 正确（Test Mode 使用 .test. 子域名）
• [ ] Webhook 已配置且 HMAC Secret 正确
• [ ] 至少选择了 order.completed 和 subscription.activated 事件
• [ ] 测试支付流程完整（创建 session → 支付 → 接收 webhook → 激活会员）

1. Membership Activation: Auto-activates OpenDev membership on order.completed

Webhook Event Flow

FastSpring → POST /v1/payment/webhook/fastspring
           → Verify HMAC signature
           → Check event idempotency
           → Log webhook event
           → Return 200
           → Async: Process event
              → Update order status
              → Update transaction record
              → Activate membership (if applicable)

Troubleshooting

Error: FastSpring not configured for this app

Solution: Ensure FastSpring configuration is saved in OpenDev app settings with status "active".

Error: FastSpring product not configured

Solution: Add the FastSpring product path to the product tier's platformproductids.fastspring field.

Webhook not receiving events

Solutions:

• Verify webhook URL is publicly accessible (HTTPS required)
• Check webhook configuration in FastSpring Dashboard
• Verify HMAC secret matches between FastSpring and your configuration

Payment succeeded but membership not activated

Solutions:

• Check webhook logs in database (paymentwebhooklogs table)
• Verify tags.orderId is present in FastSpring order
• Check membership activation logs for errors

Key Differences from Stripe

Related Documentation

• FastSpring Developer Hub
• FastSpring API Reference
• FastSpring Webhooks
• Stripe Payment Setup
• OpenDev Payment Configuration