Stripe 支付 SDK - InsForge Docs

npm install @insforge/sdk@latest

yarn add @insforge/sdk@latest

pnpm add @insforge/sdk@latest

import { createClient } from '@insforge/sdk';

const insforge = createClient({
  baseUrl: 'https://your-app.insforge.app',
  anonKey: 'your-anon-key'  // Optional: for public/unauthenticated requests
});

Find the anon key with npx @insforge/cli secrets get ANON_KEY, or in the dashboard: click Install and open API Keys.

概述

TypeScript SDK 为生成的应用前端公开 Stripe 运行时助手：

insforge.payments.stripe.createCheckoutSession(...)
insforge.payments.stripe.createCustomerPortalSession(...)

Stripe 密钥、目录管理、webhook 设置和付款监控是管理操作。在使用 SDK 之前，从仪表板或 CLI 配置它们。

npx @insforge/cli payments stripe status
npx @insforge/cli payments stripe catalog --environment test

有关设置、数据库表、webhook 投影和履行模式，请参见 Stripe 支付。

SDK 方法需要当前 InsForge 用户令牌。匿名 InsForge 令牌可用于来宾一次性结账，但 InsForge API 密钥不能替代，因为后端需要用户上下文来处理本地会话行。

createCheckoutSession()

通过 InsForge 后端创建 Stripe Checkout 会话。

参数

参数	类型	必需	描述
第一个参数	`'test' \| 'live'`	是	要定位的 Stripe 环境
`mode`	`'payment' \| 'subscription'`	是	Checkout 模式
`lineItems`	`{ priceId: string; quantity?: number }[]`	是	Stripe 价格 ID 和数量。数量默认为 `1`
`successUrl`	`string`	是	Checkout 完成后 Stripe 重定向到的 URL
`cancelUrl`	`string`	是	如果客户取消，Stripe 重定向到的 URL
`subject`	`{ type: string; id: string }`	订阅必需	应用定义的计费所有者
`customerEmail`	`string \| null`	否	Checkout 客户创建的电子邮件提示
`metadata`	`Record<string, string>`	否	复制到 Stripe Checkout 的应用元数据
`idempotencyKey`	`string`	否	用于重试安全的 Checkout 创建的稳定密钥

以 insforge_ 开头的元数据键是保留的。

{
  data: {
    checkoutSession: {
      id: string
      environment: 'test' | 'live'
      mode: 'payment' | 'subscription'
      status: 'initialized' | 'open' | 'completed' | 'expired' | 'failed'
      paymentStatus: 'paid' | 'unpaid' | 'no_payment_required' | null
      subjectType: string | null
      subjectId: string | null
      customerEmail: string | null
      checkoutSessionId: string | null
      customerId: string | null
      paymentIntentId: string | null
      subscriptionId: string | null
      url: string | null
      lastError: string | null
      createdAt: string
      updatedAt: string
    }
  } | null,
  error: Error | null
}

一次性结账

const { data, error } = await insforge.payments.stripe.createCheckoutSession('test', {
  mode: 'payment',
  lineItems: [{ priceId: 'price_123', quantity: 1 }],
  successUrl: `${window.location.origin}/checkout/success`,
  cancelUrl: `${window.location.origin}/pricing`,
  customerEmail: user?.email ?? null,
  metadata: { order_id: orderId },
  idempotencyKey: `order:${orderId}`
});

if (error) {
  console.error('Checkout failed:', error.message);
  return;
}

if (data?.checkoutSession.url) {
  window.location.assign(data.checkoutSession.url);
}

对于匿名一次性购买，省略 subject 并在可用时传递 customerEmail。如果一次性结账包含 subject 且还没有现有的 Stripe 客户映射，InsForge 让 Stripe 在 Checkout 期间创建客户，并从完成 webhook 回填主体映射。

订阅结账

const { data, error } = await insforge.payments.stripe.createCheckoutSession('test', {
  mode: 'subscription',
  subject: { type: 'team', id: teamId },
  lineItems: [{ priceId: 'price_monthly_123', quantity: 1 }],
  successUrl: `${window.location.origin}/billing/success`,
  cancelUrl: `${window.location.origin}/billing`,
  customerEmail: user.email,
  idempotencyKey: `team:${teamId}:pro-monthly`
});

if (error) throw error;
if (data?.checkoutSession.url) {
  window.location.assign(data.checkoutSession.url);
}

订阅结账需要 subject，因为定期访问属于应用定义的计费所有者，如用户、团队、组织、工作区、租户或群组。

不要将成功 URL 视为付款证明。使用已验证的 webhook 事件来履行订单和授予订阅访问权限。

createCustomerPortalSession()

为映射的计费主体创建 Stripe 计费门户会话。

参数

参数	类型	必需	描述
第一个参数	`'test' \| 'live'`	是	要定位的 Stripe 环境
`subject`	`{ type: string; id: string }`	是	应用定义的计费所有者
`returnUrl`	`string`	否	客户离开门户时 Stripe 重定向到的 URL
`configuration`	`string`	否	Stripe 计费门户配置 ID

{
  data: {
    customerPortalSession: {
      id: string
      environment: 'test' | 'live'
      status: 'initialized' | 'created' | 'failed'
      subjectType: string
      subjectId: string
      customerId: string | null
      returnUrl: string | null
      configuration: string | null
      url: string | null
      lastError: string | null
      createdAt: string
      updatedAt: string
    }
  } | null,
  error: Error | null
}

示例

const { data, error } = await insforge.payments.stripe.createCustomerPortalSession('test', {
  subject: { type: 'team', id: teamId },
  returnUrl: `${window.location.origin}/billing`
});

if (error) {
  if ('statusCode' in error && error.statusCode === 404) {
    return;
  }

  throw error;
}

if (data?.customerPortalSession.url) {
  window.location.assign(data.customerPortalSession.url);
}

客户门户会话需要经过身份验证的用户和主体的现有客户映射。该映射通常在 Checkout 会话完成且 Stripe 返回客户后创建。

授权和 RLS

SDK 方法使用当前 InsForge 令牌调用运行时路由。后端使用调用者上下文插入本地会话行：

payments.stripe_checkout_sessions 用于 Checkout 尝试
payments.stripe_customer_portal_sessions 用于计费门户尝试

如果用户可以传递共享主体（如团队或组织），请在公开结账、订阅或客户门户 UI 之前添加授权边界。例如，在 Stripe 运行时表上启用带有检查团队成员资格策略的 RLS，或通过您自己的服务器端点调用支付，先检查成员资格。 PostgreSQL 将 SELECT 策略应用于 INSERT ... RETURNING 返回的行和幂等重试查找。如果即使存在 INSERT 策略也出现 RLS 错误，请为同一计费主体和幂等密钥添加匹配的 SELECT 策略。

除非您的应用检查用户可以管理该计费主体，否则不要让用户提交任意的 subject.type 和 subject.id 值。

读取付款状态

支付 SDK 不为 payments.customers、payments.stripe_subscriptions 或 payments.transactions 公开通用的终端用户读取。这些表是用于仪表板可见性和报告的操作记录。对于面向用户的计费状态，创建带有 RLS 的应用拥有的表，并从提供商 webhook 事件触发器填充它们：

public.orders
public.credit_ledger
public.user_entitlements
public.team_billing_status

有关履行示例，请参见 Stripe 支付。

生产/测试环境

在开发时将 'test' 作为第一个 SDK 参数传递。仅在开发者明确批准生产 Stripe 更改并配置了生产价格后才切换到 'live'。

永远不要将 Stripe 密钥放在前端代码或公共部署环境变量中。通过 InsForge 仪表板或 CLI 配置 Stripe 密钥。

​概述

​createCheckoutSession()

​参数

​返回

​一次性结账

​订阅结账

​createCustomerPortalSession()

​参数

​返回

​示例

​授权和 RLS

​读取付款状态

​生产/测试环境

概述

createCheckoutSession()

参数

返回

一次性结账

订阅结账

createCustomerPortalSession()

参数

返回

示例

授权和 RLS

读取付款状态

生产/测试环境