Stripe

ShipAny 集成了 Stripe 作为支付服务供应商，只需简单配置即可接入使用。

接入 Stripe 支付

按照以下步骤为你的项目接入 Stripe 支付。

设计价格表

默认的价格表配置在 src/config/locale/messages/{locale}/pricing.json 文件中，支持多语言，每个 locale 对应一个独立的价格表配置。

pricing.groups 字段定义了价格方案分组，默认值如下

{
  "pricing": {
    "groups": [
      {
        "name": "one-time",
        "title": "Pay as you go"
      },
      {
        "name": "monthly",
        "title": "Monthly",
        "is_featured": true,
        "label": "save 15%"
      },
      {
        "name": "yearly",
        "title": "Annually"
      }
    ]
  }
}

• name: 分组的唯一标识。在 pricing.items 中，每个价格方案通过 group 字段与分组 name 关联。
• title: 分组的显示名称。
• is_featured: 是否为推荐分组。如果为 true，则会默认展示此分组及其包含的推荐价格方案。
• label: 分组的标签。在显示名称的右上方以徽标的形式显示。

pricing.items 字段定义了价格方案列表，默认的其中一个价格方案数据结构如下：

{
  "pricing": {
    "items": [
      {
        "title": "Starter",
        "description": "Get started with your first SaaS startup.",
        "features_title": "Includes",
        "features": [
          "100 credits, valid for 1 month",
          "NextJS boilerplate",
          "SEO-friendly structure",
          "Payment with Stripe",
          "Data storage with Supabase",
          "Google Oauth & One-Tap Login",
          "i18n support"
        ],
        "interval": "one-time",
        "amount": 9900,
        "currency": "USD",
        "price": "$99",
        "original_price": "$199",
        "unit": "",
        "is_featured": false,
        "tip": "Pay once. Build unlimited projects!",
        "button": {
          "title": "Get ShipAny",
          "url": "/#pricing",
          "icon": "RiFlashlightFill"
        },
        "product_id": "starter",
        "product_name": "ShipAny Boilerplate Starter",
        "credits": 100,
        "valid_days": 30,
        "group": "one-time"
      }
    ]
  }
}

• title: 价格方案标题。
• description: 价格方案描述。
• features_title: 价格方案特性列表标题。
• features: 价格方案特性列表。
• interval: 价格方案计费周期。可设置的值为 one-time（一次性支付）、month（按月订阅）、year（按年订阅）。
• amount: 价格方案金额。这个值用于请求 Stripe 下单，单位：分。
• currency: 价格方案货币。可设置的值为 USD（美元）、CNY（人民币）等。
• price: 价格方案显示的售价。
• original_price: 价格方案显示的原价。带下划线效果。
• unit: 价格方案显示的单位。比如 / month，/ year 等。
• is_featured: 是否为推荐价格方案。设置为 true 则会在价格表中默认显示。
• tip: 下单提示。
• button: 下单按钮。可自定义显示文本 title 和图标 icon，url 目前为占位符，无实际作用。
• product_id: 价格方案唯一标识。下单时后台接口根据此参数定位价格方案，请确保每个价格方案的 product_id 唯一。
• product_name: 价格方案名称。
• credits: 购买的积分数量。如果不是购买积分的场景，可以设置为 0.
• valid_days: 积分的有效天数。按月发放积分可以设置为 30，按年一次性发放积分可以设置为 365。
• group: 价格方案所属分组。跟 pricing.groups 中的 name 关联。

请根据你的项目需求，参考默认的价格表配置，修改对应的字段内容，设计价格表。

注意：如果你的项目支持多语言，请修改每个 locale 对应的价格表配置。

选择价格方案后，请求下单的接口是 /api/payment/checkout，请求参数示例：

{
  "product_id": "starter",
  "currency": "USD",
  "locale": "en",
  "payment_provider": "stripe",
  "metadata": {}
}

• product_id: 价格方案唯一标识。下单接口根据此参数定位价格方案。
• currency: 下单币种。可以由用户自行选择，默认 USD。
• locale: 下单语言。传递用户当前选择的页面 locale，下单接口根据此参数定位价格表配置。
• payment_provider: 支付提供商。
• metadata: 支付元数据。可以传递自定义参数。

注意：修改完价格表配置后，访问 /pricing 页面查看新的价格表。选择一个价格方案下单，支付成功后，在 /settings/payments 页面查看支付记录，检查支付金额、币种、付费周期，是否与配置的价格方案一致。 在 /settings/credits 页面查看积分发放记录，检查积分数量、过期时间（支付时间 + 有效天数），是否与配置的价格方案一致。

配置支付回调

用户在价格表页面选择价格方案下单成功后，会跳转到 Stripe 支付页面，支付成功后，会跳转到项目的回调接口：/api/payment/callback。

在回调接口中，会根据订单号更新订单状态，再跳转到配置的 callbackUrl。

这个配置的 callbackUrl 是在下单接口：/api/payment/checkout 中指定的：

const callbackUrl =
  paymentType === PaymentType.SUBSCRIPTION
    ? `${callbackBaseUrl}/settings/billing`
    : `${callbackBaseUrl}/settings/payments`;

按照默认配置，如果是一次性支付，最终会跳转到 /settings/payments 页面；如果是订阅支付，最终会跳转到 /settings/billing 页面。

你可以根据项目需求，自行修改用户支付完成后的跳转地址。

注意：支付回调是同步跳转的，如果用户在 Stripe 支付页面确认支付，在页面跳转前关闭了浏览器，未能正常跳转到项目回调接口，订单状态无法更新，用户在个人中心无法看到已支付的订单。此类情况叫做：丢单。

为了避免支付回调的 丢单 情况，建议项目上线运营时，在 Stripe 后台配置支付通知。

配置支付通知

# 下单完成
checkout.session.completed
# 支付成功
invoice.payment_succeeded
# 支付失败
invoice.payment_failed
# 订阅更新
customer.subscription.updated
# 订阅取消
customer.subscription.deleted

https://{your-domain.com}/api/payment/notify/stripe

本地调试支付通知

在上一步配置支付通知时，填写的 Endpoint URL 必须是一个可以公网访问的 https 地址。

项目部署上线前，需要先在本地调试，接收支付通知内容，进行必要的修改和验证。

通过 内网穿透，可以把一个公网地址映射到本地开发机，下面的步骤主要演示使用 ngrok 实现 内网穿透。

brew install ngrok

ngrok config add-authtoken {your-authtoken}

pnpm dev --port 8080

ngrok http 8080

https://9d897275dabf.ngrok-free.app/api/payment/notify/stripe

在按照以上步骤配置支付通知后，在价格表页面选择一个价格方案下单，就可以在本地接收 Stripe 的支付通知了。

默认的支付通知处理逻辑在 src/app/api/payment/notify/[provider]/route.ts 文件中。你可以根据项目需求，自行修改相应的逻辑。

自定义支付选项

你可以根据项目需求，根据以下列举的例子，自定义支付选项。

多币种支付

设计价格表 时，在价格方案中使用 currency 字段指定下单的币种。比如 原价 199 美元，标价 99 美元，对应的价格方案配置是：

{
  "amount": 9900,
  "currency": "USD",
  "price": "$99",
  "original_price": "$199"
}

如果要在价格表页面，允许用户选择不同的币种下单，可以参考以下配置：

{
  "amount": 9900,
  "currency": "usd",
  "price": "$99",
  "original_price": "$199",
  "currencies": [
    {
      "currency": "cny",
      "amount": 69900,
      "price": "¥699",
      "original_price": "¥1399"
    }
  ]
}

配置之后，可以看到价格方案多了一个切换币种的选项。价格方案配置中，外层的 currency 是默认币种，currencies 里面的 currency 是可切换的币种。

注意：currency 字段不区分大小写，amount 单位是：分。

微信 / 支付宝 支付

按照以下步骤，在你的项目启用 微信 / 支付宝 支付。

{
  "amount": 69900,
  "currency": "cny",
  "price": "¥699",
  "original_price": "¥1399"
}

{
  "amount": 9900,
  "currency": "usd",
  "price": "$99",
  "original_price": "$199",
  "currencies": [
    {
      "currency": "cny",
      "amount": 69900,
      "price": "¥699",
      "original_price": "¥1399"
    }
  ]
}