# @convex-dev/stripe 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/stripe/

版本：0\.1\.7
npm 元数据更新时间：2026-10-10T00:57:02.224Z
中文译文更新时间：2026-11-10T17:43:46.278Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40convex-dev/stripe
原文对照：https://npmcn.com/package/%40convex-dev/stripe/?lang=original
项目主页：https://github.com/get-convex/stripe#readme
源码仓库：https://github.com/get-convex/stripe

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：333 kB，68 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，convex ^1\.29\.3
- 首次发布：2025-12-01T20:18:31.565Z
- 最新版本发布：2026-10-10T00:57:02.056Z
- 近 30 天下载量：502616（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

Convex的条纹组件.

## 安装

```sh
npm install @convex-dev/stripe
```

也可以使用：`pnpm add @convex-dev/stripe`、`yarn add @convex-dev/stripe`、`bun add @convex-dev/stripe`

## README

# @ convex-dev/ stripe (英语)

[![Integrate Stripe with Convex in 10 mins (Stripe Component)](https://thumbs.video-to-markdown.com/71e9f645.jpg)](https://youtu.be/-S4iHTAxnRw)

用于整合面额支付、订阅和计费的Convex组件 输入您的 Convex 应用程序 .

[![npm version](https://badge.fury.io/js/@convex-dev%2Fstripe.svg)](https://badge.fury.io/js/@convex-dev%2Fstripe)

需要节点.js 18 或以后, 匹配 Strede 节点 SDK v22 运行时间 页:1.

## 特征

-   🛒 **退出会话** - 建立一次性付款和订阅结账制度
-   📦 **订阅管理** - 创建、更新、取消订阅
-   👥 **客户管理** - 自动创建客户和链接
-   💳 **客户端门户** - 让用户管理账单
-   🪑 **基于座位的定价** - 更新团队账单的订阅数量
-   🔗 **用户/操作链接** - 连接用户的付款和订阅 组织
-   🔔 **Webhook 处理** - 将条纹数据自动同步到您的 Convex 数据库
-   📊 **实时数据** - 实时查询付款、订阅和发票

## 快速启动

### 1\. 安装组件

```bash
npm install @convex-dev/stripe
```

### 2\. 添加到您的 Convex 应用程序

创建或更新 `convex/convex.config.ts`数字 :

```typescript
import { defineApp } from "convex/server";
import stripe from "@convex-dev/stripe/convex.config.js";

const app = defineApp();
app.use(stripe);

export default app;
```

### 3\. 设置环境变量

把这些添加到您的 [凸起板](https://dashboard.convex.dev/) 环境变量:

| 变量 | 说明 |
| --- | --- |
| `STRIPE_SECRET_KEY` | 您的条纹密钥( E)`sk_test_...` 或者说 `sk_live_...`(中文(简体) ) |
| `STRIPE_WEBHOOK_SECRET` | Webhook 签名秘密( Name`whsec_...`\- 见步骤4 |

### 4\. 配置花纹 Webhooks

1.  转到 [Frape Dashboard – 开发者 – Webhooks 页面存档备份,存于互联网档案馆](https://dashboard.stripe.com/test/webhooks)
2.  点击 **“添加终点”**
3.  输入您的 Webhook URL :
    
    ```
    https://<your-convex-deployment>.convex.site/stripe/webhook
    ```
    
    (在Convex仪表板上找到您的部署名称 - 这是之前的部分) `.convex.cloud` 在您的 URL 中)
4.  选择这些事件 :
    -   `checkout.session.completed`
    -   `customer.created`
    -   `customer.updated`
    -   `customer.deleted`
    -   `customer.subscription.created`
    -   `customer.subscription.updated`
    -   `customer.subscription.deleted`
    -   `invoice.created`
    -   `invoice.finalized`
    -   `invoice.updated`
    -   `invoice.paid`
    -   `invoice.payment_failed`
    -   `payment_intent.succeeded`
    -   `payment_intent.payment_failed`
5.  点击 **“添加终点”**
6.  复制 **签名秘密** 并添加为 `STRIPE_WEBHOOK_SECRET` 在凸起处

### 5\. 登记Webhook路线

创建 `convex/http.ts`数字 :

```typescript
import { httpRouter } from "convex/server";
import { components } from "./_generated/api";
import { registerRoutes } from "@convex-dev/stripe";

const http = httpRouter();

// Register Stripe webhook handler at /stripe/webhook
registerRoutes(http, components.stripe, {
  webhookPath: "/stripe/webhook",
  apiVersion: "2026-04-22.dahlia", // Optional
});

export default http;
```

### 6\. 使用本构成部分

创建 `convex/stripe.ts`数字 :

```typescript
import { action } from "./_generated/server";
import { components } from "./_generated/api";
import { StripeSubscriptions } from "@convex-dev/stripe";
import { v } from "convex/values";

const stripeClient = new StripeSubscriptions(components.stripe, {});

// Create a checkout session for a subscription
export const createSubscriptionCheckout = action({
  args: { priceId: v.string() },
  returns: v.object({
    sessionId: v.string(),
    url: v.union(v.string(), v.null()),
  }),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    // Get or create a Stripe customer
    const customer = await stripeClient.getOrCreateCustomer(ctx, {
      userId: identity.subject,
      email: identity.email,
      name: identity.name,
    });

    // Create checkout session
    return await stripeClient.createCheckoutSession(ctx, {
      priceId: args.priceId,
      customerId: customer.customerId,
      mode: "subscription",
      successUrl: "http://localhost:5173/?success=true",
      cancelUrl: "http://localhost:5173/?canceled=true",
      subscriptionMetadata: { userId: identity.subject },
    });
  },
});

// Create a checkout session for a one-time payment
export const createPaymentCheckout = action({
  args: { priceId: v.string() },
  returns: v.object({
    sessionId: v.string(),
    url: v.union(v.string(), v.null()),
  }),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    const customer = await stripeClient.getOrCreateCustomer(ctx, {
      userId: identity.subject,
      email: identity.email,
      name: identity.name,
    });

    return await stripeClient.createCheckoutSession(ctx, {
      priceId: args.priceId,
      customerId: customer.customerId,
      mode: "payment",
      successUrl: "http://localhost:5173/?success=true",
      cancelUrl: "http://localhost:5173/?canceled=true",
      paymentIntentMetadata: { userId: identity.subject },
    });
  },
});
```

## API 参考

### 条纹订阅客户端

```typescript
import { StripeSubscriptions } from "@convex-dev/stripe";

const stripeClient = new StripeSubscriptions(components.stripe, {
  STRIPE_SECRET_KEY: "sk_...", // Optional, defaults to process.env.STRIPE_SECRET_KEY
  apiVersion: "2026-04-22.dahlia", // Optional Stripe API version
});
```

#### 方法

| 方法 | 说明 |
| --- | --- |
| `createCheckoutSession()` | 创建条纹检查会话 |
| `createCustomerPortalSession()` | 生成客户端 URL |
| `createCustomer()` | 创建新条纹客户端 |
| `getOrCreateCustomer()` | 获取已有客户或创建新客户 |
| `cancelSubscription()` | 取消订阅 |
| `reactivateSubscription()` | 重新启动要取消的订阅集 |
| `updateSubscriptionQuantity()` | 更新座位数 |

### 创建检查会议

```typescript
await stripeClient.createCheckoutSession(ctx, {
  priceId: "price_...",
  customerId: "cus_...",           // Optional
  mode: "subscription",             // "subscription" | "payment" | "setup"
  successUrl: "https://...",
  cancelUrl: "https://...",
  quantity: 1,                      // Optional, default 1
  metadata: {},                     // Optional, session metadata
  subscriptionMetadata: {},         // Optional, attached to subscription
  paymentIntentMetadata: {},        // Optional, attached to payment intent
  params: {
    allow_promotion_codes: true,
    ui_mode: "embedded_page",
    return_url: "https://...",
  },                                // Optional Stripe Checkout Session params
});
```

`params` 是 Strefe 取出会话字段的打出通过 组件不直接建模。 域数 `params` 覆盖已构建 默认,但 `mode`继续由高层控制 `mode` 参数。 对于非托管的UI 模式,组件省略 `successUrl` 财务报告和审定财务报表 `cancelUrl` 从 Strade 请求并期望提供重定向行为 通过条纹支持的参数,例如 `return_url`。 。 。 .

### 组件查询

通过组件的公开查询直接访问数据:

```typescript
import { query } from "./_generated/server";
import { components } from "./_generated/api";

// List subscriptions for a user
export const getUserSubscriptions = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) return [];

    return await ctx.runQuery(
      components.stripe.public.listSubscriptionsByUserId,
      { userId: identity.subject },
    );
  },
});

// List payments for a user
export const getUserPayments = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) return [];

    return await ctx.runQuery(components.stripe.public.listPaymentsByUserId, {
      userId: identity.subject,
    });
  },
});
```

### 可用的公共查询

| 查询 | 参数 | 说明 |
| --- | --- | --- |
| `getCustomer` | `stripeCustomerId` | 用花旗身份证明客户 |
| `listSubscriptions` | `stripeCustomerId` | 为客户订阅的列表 |
| `listSubscriptionsByUserId` | `userId` | 用户订阅列表 |
| `getSubscription` | `stripeSubscriptionId` | 由 ID 订阅 |
| `getSubscriptionByOrgId` | `orgId` | 获取 Org 的订阅 |
| `getPayment` | `stripePaymentIntentId` | 通过身份证明获得付款 |
| `listPayments` | `stripeCustomerId` | 客户清单付款 |
| `listPaymentsByUserId` | `userId` | 列出用户的付款 |
| `listPaymentsByOrgId` | `orgId` | 列出某矿石的付款 |
| `listInvoices` | `stripeCustomerId` | 列出客户发票 |
| `listInvoicesByUserId` | `userId` | 列出用户发票 |
| `listInvoicesByOrgId` | `orgId` | 列出一矿石的发票 |

## Webhook 事件

该组件自动处理这些 Strade webhook 事件 :

| 活动 | 行动 |
| --- | --- |
| `customer.created` | 创建客户记录 |
| `customer.updated` | 更新客户记录 |
| `customer.deleted` | 刷新客户 PII |
| `customer.subscription.created` | 创建订阅记录 |
| `customer.subscription.updated` | 更新订阅记录 |
| `customer.subscription.deleted` | 将订阅标记为已取消 |
| `payment_intent.succeeded` | 创建付款记录 |
| `payment_intent.payment_failed` | 更新付款状况 |
| `invoice.created` | 创建发票记录 |
| `invoice.finalized` | 发票记录 |
| `invoice.updated` | 镜像发票元数据更改 |
| `invoice.paid` | 预付发票 |
| `invoice.payment_failed` | 标记发票失败 |
| `checkout.session.completed` | 处理已完成的取出会话 |

### 自定义 Webhook 处理器

向 Webhook 事件添加自定义逻辑 :

```typescript
import { httpRouter } from "convex/server";
import { components } from "./_generated/api";
import { registerRoutes } from "@convex-dev/stripe";
import type Stripe from "stripe";

const http = httpRouter();

registerRoutes(http, components.stripe, {
  events: {
    "customer.subscription.updated": async (ctx, event: Stripe.CustomerSubscriptionUpdatedEvent) => {
      const subscription = event.data.object;
      console.log("Subscription updated:", subscription.id, subscription.status);
      // Add custom logic here
    },
  },
  onEvent: async (ctx, event: Stripe.Event) => {
    // Called for ALL events - useful for logging/analytics
    console.log("Stripe event:", event.type);
  },
});

export default http;
```

## 数据库Schema

该组件在其命名空间创建这些表格:

### 客户

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `stripeCustomerId` | 字符串 | 条纹客户身份 |
| `email` | 绳子? | 客户电子邮件 |
| `name` | 绳子? | 客户名称 |
| `metadata` | 对象? | 自定义元数据 |

### 订阅

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `stripeSubscriptionId` | 字符串 | 字条订阅 ID |
| `stripeCustomerId` | 字符串 | 客户身份 |
| `status` | 字符串 | 订阅状态 |
| `priceId` | 字符串 | 价格标识 |
| `quantity` | 号码? | 座位数 |
| `currentPeriodEnd` | 编号 | 期末时间戳 |
| `cancelAtPeriodEnd` | 布尔 | 将在期末取消 |
| `userId` | 绳子? | 链接用户 ID |
| `orgId` | 绳子? | 链接的 Ong ID |
| `metadata` | 对象? | 自定义元数据 |

### 检查出会话( s)

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `stripeCheckoutSessionId` | 字符串 | 退出会话编号 |
| `stripeCustomerId` | 绳子? | 客户身份 |
| `status` | 字符串 | 会议状态 |
| `mode` | 字符串 | 会话模式(付费/订阅/设置) |
| `metadata` | 对象? | 自定义元数据 |

### 付款

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `stripePaymentIntentId` | 字符串 | 付款意向标识 |
| `stripeCustomerId` | 绳子? | 客户身份 |
| `amount` | 编号 | 数额(美分) |
| `currency` | 字符串 | 货币代码 |
| `status` | 字符串 | 缴款情况 |
| `created` | 编号 | 创建时间戳 |
| `userId` | 绳子? | 链接用户 ID |
| `orgId` | 绳子? | 链接的 Ong ID |
| `metadata` | 对象? | 自定义元数据 |

### 发票

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `stripeInvoiceId` | 字符串 | 发票身份证 |
| `stripeCustomerId` | 字符串 | 客户身份 |
| `stripeSubscriptionId` | 绳子? | 订阅编号 |
| `status` | 字符串 | 发票状况 |
| `amountDue` | 编号 | 应付款 |
| `amountPaid` | 编号 | 支付金额 |
| `created` | 编号 | 创建时间戳 |
| `userId` | 绳子? | 链接用户 ID |
| `orgId` | 绳子? | 链接的 Ong ID |
| `metadata` | 对象? | 发票元数据 |

## 示例应用

请检查url=值 (帮助) [`example/`](https://npmcn.com/package/%40convex-dev/stripe/example) 目录 :

```bash
git clone https://github.com/get-convex/convex-stripe
cd convex-stripe
npm install
npm run dev
```

例子包括:

-   有产品展示的登陆页面
-   一次性付款和订阅
-   有命令历史的用户配置文件
-   订阅管理(取消,更新席位)
-   客户门户整合
-   团队/组织账单

## 认证

此组件与任何 Convex 认证提供者合作 。 示例使用 [办事员](https://clerk.com/)数字 :

1.  在 [书记员.com](https://clerk.com/)
2.  添加 `VITE_CLERK_PUBLISHABLE_KEY` 给您的 `.env.local`
3.  创建 `convex/auth.config.ts`数字 :

```typescript
export default {
  providers: [
    {
      domain: "https://your-clerk-domain.clerk.accounts.dev",
      applicationID: "convex",
    },
  ],
};
```

## 解决问题

### 退职后表格为空

确保你已经:

1.  设定 `STRIPE_SECRET_KEY` 财务报告和审定财务报表 `STRIPE_WEBHOOK_SECRET` 位于 Convex 环境中 变量
2.  配置了 Frede 中的 Webhook 端点, 并带有正确的事件
3.  已添加 `invoice.created` 财务报告和审定财务报表 `invoice.finalized` 事件(不仅仅是 `invoice.paid`(中文(简体) )

### “ 未验证” 错误

确保您的认证提供者配置 :

1.  创建 `convex/auth.config.ts` 与您的提供者
2.  运行 `npx convex dev` 来推动配置
3.  在调用动作前验证用户签名

### Webhooks 返回 400/500

请检查date=中的日期值 (帮助) Convex日志在您的仪表板中查找出错. 共同问题:

-   失踪 `STRIPE_WEBHOOK_SECRET`
-   错误的 Webhook URL( 应该是) `https://<deployment>.convex.site/stripe/webhook`(中文(简体) )
-   Webhook 配置中缺失的事件

## 许可证

阿帕奇 - 2.0

## 常见问题

### @convex-dev/stripe 是什么？

Convex的条纹组件\.

### 如何安装 @convex-dev/stripe？

在项目目录运行 npm install @convex-dev/stripe，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3\.1 \|\| ^19\.0\.0）、convex（^1\.29\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @convex-dev/stripe 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @convex-dev/stripe 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @convex-dev/stripe 可以商用吗？

@convex-dev/stripe 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convex-dev/stripe 的下载量有多少？

根据 npm 官方下载统计，@convex-dev/stripe 在 2026/10/11 – 2026/11/09 这 30 天内被下载 502,616 次，日均约 16,754 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @convex-dev/stripe 还在维护吗？

最新版本 0\.1\.7 发布于 2026/10/10（1 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2025/12/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。