开源免 Webhook 支付处理器

开源免 Webhook 支付处理器 | 前端进阶之旅

Full translation

完整中文译文

简介

最简单的互联网收款方式。开始使用 · 快速开始 · 网站 · 活动 · 问题 · 示例

无限定价模型、单一数据源、零 webhook。

默认无状态

告别 webhook、"subscriptions" 数据库表、customer_id 列、PRICE_ID 环境变量，或者手动将你的方案映射到价格和功能。

单一数据源：从 Flowglad 读取最新的客户账单状态，包括功能访问权限和用量表额度

使用你的 ID 访问数据：通过你的认证系统用户 ID 查询客户状态。通过你定义的 slug 引用价格、功能和用量表。

全栈 SDK：在后端使用 flowgladServer.getBilling() 访问客户数据，或在 React 前端使用 useBilling() hook

可适配：在测试模式下迭代新的定价模型，一键推送到生产环境。在你的应用中无缝切换定价模型，无需重新部署。

快速开始

首先，根据你的项目设置安装必要的 Flowglad 包：

# Next.js Projects
bun add @flowglad/nextjs

# React + Express projects:
bun add @flowglad/react @flowglad/express

# All other React + Node Projects
bun add @flowglad/react @flowglad/server

Flowglad 与你的认证系统无缝集成，在 Next.js 应用中只需几行代码即可开始使用。设置通常只需一分钟：

配置 Flowglad 服务器客户端

创建一个工具来生成你的 Flowglad 服务器实例。传递你自己的客户/用户/组织 ID——Flowglad 永远不需要在你的应用中管理自己的客户 ID：

// lib/flowglad.ts
import { FlowgladServer } from '@flowglad/nextjs/server'

export const flowglad = (customerExternalId: string) => {
  return new FlowgladServer({
    customerExternalId,
    getCustomerDetails: async (externalId) => {
      // e.g. Fetch user info from your DB using your user/org/team ID
      const user = await db.users.findOne({ id: externalId })
      if (!user) throw new Error('User not found')
      return { email: user.email, name: user.name }
    },
  })
}

暴露 Flowglad API 处理器

添加一个 API 路由，使 Flowglad 客户端可以与你的后端安全通信：

// app/api/flowglad/[...path]/route.ts
import { nextRouteHandler } from '@flowglad/nextjs/server'
import { flowglad } from '@/utils/flowglad'

export const { GET, POST } = nextRouteHandler({
  flowglad,
  getCustomerExternalId: async (req) => {
    // Extract your user/org/team ID from session/auth.
    // For B2C: return user.id from your DB
    // For B2B: return organization.id or team.id
    const userId = await getUserIdFromRequest(req)
    if (!userId) throw new Error('User not authenticated')
    return userId
  },
})

用 Provider 包装你的应用

在你的根布局（App Router）或 _app（Pages Router）中：

import { FlowgladProvider } from '@flowglad/nextjs'

// App Router example (app/layout.tsx)
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <FlowgladProvider>
          {children}
        </FlowgladProvider>
      </body>
    </html>
  )
}

就这样——Flowglad 将使用你应用的内部用户 ID 处理所有计费逻辑，并实时将账单状态集成到你的前端。

B2C 应用：使用 user.id 作为客户 ID。B2B 应用：使用 organization.id 或 team.id 作为客户 ID。

Flowglad 不需要你改变认证系统或管理 Flowglad 客户 ID。只需传递你自己的！

在前端使用 useBilling，在后端使用 flowglad(userId).getBilling()

代码示例

前端示例：检查功能访问和用量

'use client'

import { useBilling } from '@flowglad/nextjs'

export function FeatureGate({ featureSlug, children }) {
  const { loaded, errors, checkFeatureAccess } = useBilling()

  if (!loaded || !checkFeatureAccess) {
    return <p>Loading billing state…</p>
  }

  if (errors?.length) {
    return <p>Unable to load billing data right now.</p>
  }

  return checkFeatureAccess(featureSlug)
    ? children
    : <p>You need to upgrade to unlock this feature.</p>
}

import { useBilling, usePricing } from '@flowglad/nextjs'

export function PricingCards() {
  const pricingModel = usePricing()
  const { createCheckoutSession } = useBilling()

  if (!pricingModel) {
    return <p>Loading pricing…</p>
  }

  return (
    <div>
      {pricingModel.products.map((product) => {
        const defaultPrice = product.defaultPrice ?? product.prices?.[0]
        if (!defaultPrice) return null

        return (
          <div key={product.id}>
            <h3>{product.name}</h3>
            <p>{product.description}</p>
            <button
              onClick={() =>
                createCheckoutSession({
                  priceSlug: defaultPrice.slug,
                  successUrl: window.location.href,
                  cancelUrl: window.location.href,
                  autoRedirect: true,
                })
              }
            >
              Choose {defaultPrice.name ?? product.name}
            </button>
          </div>
        )
      })}
    </div>
  )
}

后端示例：服务器端功能和用量检查

import { NextResponse } from 'next/server'
import { flowglad } from '@/utils/flowglad'

const hasFastGenerations = async () => {
  // ...
  const user = await getUser()

  const billing = await flowglad(user.id).getBilling()
  const hasAccess = billing.checkFeatureAccess('fast_generations')
  if (hasAccess) {
    // run fast generations
  } else {
    // fall back to normal generations
  }
}

import { flowglad } from '@/utils/flowglad'

const processChatMessage = async (params: { chat: string }) => {
  // Extract your app's user/org/team ID,
  // whichever corresponds to your customer
  const user = await getUser()

  const billing = await flowglad(user.id).getBilling()
  const usage = billing.checkUsageBalance('chat_messages')
  if (usage.availableBalance > 0) {
    // run chat request
  } else {
    throw Error(`User ${user.id} does not have sufficient usage credits`)
  }
}

定价模型

首先，设置一个定价模型。你可以在仪表板中通过几次点击使用模板来完成，然后根据你的特定需求进行自定义。

我们目前有以下定价模型的模板：

用量限制 + 订阅混合（如 Cursor）
无限用量（如 ChatGPT 消费者版）
分级访问和用量额度（如 Midjourney）
功能门控订阅（如 Linear）

更多即将推出。如果你在我们的模板中找不到适合你的定价模型，你总是可以从头开始创建。

其他定价模型示例：

基于生成次数的订阅
分级用量门控订阅
用量限制订阅

为什么构建 Flowglad

在过去的 15 年里，市场为开发者提供了比以往任何时候都更多的技术栈选择。但涉及到支付时，几乎没有新的参与者。现有的选项很少，而且几乎所有这些选项都要求我们与销售团队联系才能建立账户。当涉及到自助支付时，选择更是少之又少。

结果是？支付的开发者体验和成本在这段时间内几乎没有改善。最佳的支付开发者体验仿佛停留在 2015 年。与此同时，我们在认证、计算、托管和几乎所有其他方面都享受到了持续改进。

Flowglad 想要改变这一切。

我们正在构建一个支付层，让你能够：

尽可能少地思考账单和支付问题
花尽可能少的时间进行集成和维护
从单一集成中获得尽可能多的价值
从单一集成中解锁更多支付提供商

实现这个使命需要时间。这将很困难。这甚至可能让一些人不满。但随着人工智能引入越来越多的开发者，并使初创公司的账单复杂性激增，这种需求比以往任何时候都更加紧迫。