# @alexasomba/better-auth-paystack 中文文档

规范地址：https://npmcn.com/package/%40alexasomba/better-auth-paystack/

版本：3\.1\.1
npm 元数据更新时间：2026-08-04T12:08:51.166Z
中文译文更新时间：2026-11-06T23:14:19.065Z
软件包许可：MIT

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

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

弃用说明：Deprecated: use the unscoped better-auth-paystack package instead\. Install with: npm install better-auth-paystack\. Update imports to better-auth-paystack\.

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

- 包体积（解压后）：513 kB，34 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：4 个
- peer 依赖：better-auth ^1\.6\.25
- 首次发布：2025-12-15T19:01:30.376Z
- 最新版本发布：2026-07-29T13:54:17.625Z
- 近 30 天下载量：2187（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

生产准备的Paystack计费插件,用于Better Auth. 支持订阅、一次性付款、组织收费、安全网约车等

## 安装

```sh
npm install @alexasomba/better-auth-paystack
```

也可以使用：`pnpm add @alexasomba/better-auth-paystack`、`yarn add @alexasomba/better-auth-paystack`、`bun add @alexasomba/better-auth-paystack`

## README

# 更好的 Auth Paystack 插件

将 Paystack 集成到 [更好的认证](https://www.better-auth.com/)提供制作准备的收费系统,支持订阅(本地和本地)、一次性付款、试验、组织收费以及安全网约车.

![npm downloads](https://img.shields.io/npm/dm/@alexasomba/better-auth-paystack.svg) [![GitHub stars](https://img.shields.io/github/stars/alexasomba/better-auth-paystack.svg?style=social&label=Star)](https://github.com/alexasomba/better-auth-paystack/stargazers) [![GitHub release](https://img.shields.io/github/v/release/alexasomba/better-auth-paystack)](https://github.com/alexasomba/better-auth-paystack/releases) [![bundlephobia](https://img.shields.io/bundlephobia/minzip/@alexasomba/better-auth-paystack)](https://bundlephobia.com/result?p=@alexasomba/better-auth-paystack) [![Follow on Twitter](https://img.shields.io/twitter/follow/alexasomba?style=social)](https://twitter.com/alexasomba) ![GitHub License](https://img.shields.io/github/license/alexasomba/better-auth-paystack)

[**Live Demo( 唐斯塔克启动)**](https://better-auth-paystack.gittech.workers.dev/) | [**源代码**](https://github.com/alexasomba/better-auth-paystack/tree/main/examples/tanstack)

## AI 代理技能

本套件会发布代理技能,使AI编码代理可以加载套件特定指导,用于设置,订阅,组织计费,TanStack Start集成,客户端API,webhoks,本地订阅生命周期,chema更改,以及测试等.

使用 [TanStack 意图](https://www.npmjs.com/package/@tanstack/intent) 需要明确列出或加载个人技能时:

```bash
npx @tanstack/intent@latest list
npx @tanstack/intent@latest load @alexasomba/better-auth-paystack#better-auth-paystack-setup
npx @tanstack/intent@latest load @alexasomba/better-auth-paystack#paystack-testing-fixtures
```

如果你使用人工智能代理,运行 `npx @tanstack/intent@latest install` 在您的项目中,使代理知道如何发现包的技能.

此套件还包含 npm 套件中的技能 `skills/*/SKILL.md`,因此项目可以使用 [技术-npm](https://www.npmjs.com/package/skills-npm) 用于兼容代理的同义链接软件包技能:

```bash
npm install @alexasomba/better-auth-paystack
npx skills-npm --yes
```

对于此寄存器, 维护者可以运行 `pnpm run skills:dry-run` 通过 TanStack 示例固定或 `pnpm run skills:install` 以创建本地代理技能 链接与固定.

## 特征

-   [x] **计费模式**支持Paystack-native计划、地方管理的订阅和一次性付款(产品/金额).
-   [x] **自动客户创建**: 用户注册或组织创建时可选的Paystack客户创建.
-   [x] **审判管理**: 具有内在预防虐待逻辑的可配置试验期.
-   [x] **组织账单**: 与各组织联系订阅并授权通过角色访问.
-   [x] **订阅频道控制**: 限制订阅退出特定的Paystack支付渠道,如只收卡.
-   [x] **强制限制和座位**:自动执行成员席位升级和资源限制(团队).
-   [x] **计划变化**:推迟订阅更新或取消至计费周期结束.
-   [x] **晋升**: 即时对当地计划进行周期中期按比例升级,在可能时使用已保存的卡片收费,在需要交互式付款时退票.
-   [x] **弹出潮流**: 可选支持 Paystack 的内置取出体验通过 `@alexasomba/paystack-inline`。 。 。 .
-   [x] **Webhook 安全系统**:预配置签名验证(HMAC-SHA512)和可选IP白名单.
-   [x] **交易历史**:内建支持上市和查看本地交易记录.

* * *

## 快速启动

### 先决条件

-   **节点.js**数字 : `v22.0.0` 或更高级.
-   **更好的认证**数字 : `v1.6.9` 或更高级.

### 1\. 安装插件和SDK

```bash
npm install better-auth @alexasomba/better-auth-paystack @alexasomba/paystack-node
```

#### 可选:浏览器SDK(用于弹出 Modals)

```bash
npm install @alexasomba/paystack-inline
```

### 2\. 配置环境变量

```env
PAYSTACK_SECRET_KEY=sk_test_...
BETTER_AUTH_SECRET=...
BETTER_AUTH_URL=http://localhost:8787
```

### 3\. 设置服务器插件

```ts
import { betterAuth } from "better-auth";
import { paystack } from "@alexasomba/better-auth-paystack";
import { createPaystack } from "@alexasomba/paystack-node";
import { admin } from "better-auth/plugins";

const paystackClient = createPaystack({
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
});

export const auth = betterAuth({
  plugins: [
    admin(),
    paystack({
      paystackClient,
      secretKey: process.env.PAYSTACK_SECRET_KEY!,
      createCustomerOnSignUp: true,
      subscription: {
        enabled: true,
        allowedPaymentChannels: ["card"], // Optional: enforce card-only subscriptions
        plans: [
          {
            name: "pro",
            group: "workspace", // Optional: one active/trialing subscription per group
            planCode: "PLN_pro_123", // Native: Managed by Paystack
            freeTrial: { days: 14 },
            limits: { teams: 5, seats: 10 }, // Custom resource & member limits
          },
          {
            name: "starter",
            amount: 50000, // Local: Managed by your app (500 NGN)
            currency: "NGN",
            interval: "monthly",
          },
        ],
      },
      products: {
        products: [{ name: "credits_50", amount: 200000, currency: "NGN" }],
      },
    }),
  ],
});
```

Paystack 标志 Webhook 有效载荷相同 `PAYSTACK_SECRET_KEY` 用于 API 认证; 没有单独的网路秘密。 遗产 `webhook.secret` 财务报告和审定财务报表 `paystackWebhookSecret` 选项 被接受为源兼容,但被忽略.

### 4\. 配置客户端插件

```ts
import { createAuthClient } from "better-auth/client";
import { paystackClient } from "@alexasomba/better-auth-paystack/client";
import { adminClient } from "better-auth/client/plugins";

export const client = createAuthClient({
  plugins: [adminClient(), paystackClient({ subscription: true })],
});
```

### 5\. 迁移数据库Schema

```bash
npx better-auth migrate
```

* * *

## 移徙指南

版本 `2.0.0` 包含以安全为重点的突破性变化.

-   删除了公共/客户操作员动作 :
    -   `authClient.paystack.syncProducts()`
    -   `authClient.paystack.syncPlans()`
    -   `authClient.paystack.chargeRecurringSubscription(...)`
-   已删除 :
    -   `/paystack/sync-products`
    -   `/paystack/sync-plans`
    -   `/paystack/charge-recurring`
-   添加可信任的服务器操作 :
    -   `chargeSubscriptionRenewal`
    -   `syncPaystackProducts`
    -   `syncPaystackPlans`

### 旧

```ts
await authClient.paystack.syncProducts();
await authClient.paystack.syncPlans();
await authClient.paystack.chargeRecurringSubscription({
  subscriptionId: "sub_123",
});
```

### 新设

```ts
import {
  chargeSubscriptionRenewal,
  syncPaystackPlans,
  syncPaystackProducts,
  type ChargeRecurringSubscriptionResult,
  type PaystackSyncResult,
} from "@alexasomba/better-auth-paystack";

const ctx = { context: await auth.$context } as any;
const paystackOptions = {
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
  paystackClient,
};

await syncPaystackProducts(ctx, paystackOptions);
await syncPaystackPlans(ctx, paystackOptions);
await chargeSubscriptionRenewal(ctx, paystackOptions, {
  subscriptionId: "sub_123",
});
```

这些操作是故意的只使用服务器. 不要通过浏览器触发的认证客户端调用来曝光它们 .

* * *

## 计费模式

### 1\. 订阅

#### 原生( 建议)

使用 `planCode` 从你的Paystack Dashboard。 Paystack 处理反复出现的逻辑和电子邮件.

```ts
{ name: "pro", planCode: "PLN_xxx" }
```

#### 当地

使用 `amount` 财务报告和审定财务报表 `interval`。插件在本地存储状态,允许您管理自定义的重复逻辑或一次性的“访问期”.

```ts
{ name: "starter", amount: 50000, interval: "monthly" }
```

### 2\. 一次性付款

#### 固定产品

在服务器设置中定义预配置的产品并按名称购买.

```ts
await authClient.paystack.transaction.initialize({
  product: "credits_50",
});
```

#### 临时数额

充值、提示或定制发票的动态收费金额.

```ts
await authClient.paystack.transaction.initialize({
  amount: 100000, // 1000 NGN
  currency: "NGN",
  metadata: { type: "donation" },
});
```

* * *

## 限制和座位管理

插件会自动执行跨活动订阅和测试订阅的限制. 当多个 订阅组定义相同的数值限制, 最高值获胜; 计划特性为 综合起来.

### 成员席位限制

购买的座位存放在 `subscription.seats` 字段。 插件钩入 `member.create` 财务报告和审定财务报表 `invitation.create` 一旦达到限值,将块添加.

### 资源限制(如团队)

定义计划配置中的限制, 并在创建资源时检查这些限制 :

```ts
plans: [{ name: "pro", limits: { teams: 5, seats: 10 } }];
```

插件本土检查 `teams` 如果使用更好的Auth组织插件,则限制.

### 订阅组

设定 `group` 当用户或组织拥有独立订阅时:

```ts
plans: [
  { name: "pro", group: "workspace", planCode: "PLN_pro" },
  { name: "priority-support", group: "support", planCode: "PLN_support" },
];
```

组名被修剪并小写. 参考文献可以包含一个活动或试用订阅 每组。 无计划 `group` 保留在遗留的默认组中,以无效为代表 `subscription.groupId`,因此现有配置保留其先前的单一订阅 行为.

* * *

## 货币支持

该插件支持下列货币并自动进行最低交易额验证:

| 货币 | 名称 | 最低数额 |
| :-- | :-- | :-- |
| **国家地名** | 尼日利亚奈拉 | ₦50.00 |
| **全球统一制度** | 加纳塞迪 | ₵0.10 |
| **津巴布韦** | 南非兰德 | R1.00级 |
| **凯斯** | 肯尼亚先令 | 基斯时 3.00 |
| **美元** | 美元 | 2美元(美元) |
| **十六届理事会第一期会议** | 西非法郎 | 100非洲金融共同体法郎 |

低于这些阈值的交易将予以拒绝 `BAD_REQUEST` 错误.

## 高级使用

### 组织账单

启用 `organization.enabled` 向组织而不是用户收费.

-   **自动客户**: 各组织有自己的组织 `paystackCustomerCode`。 。 。 .
-   **授权**:组织所有者和管理员可以默认管理账单. 使用 `organization.billingRoles` 以扩展可信任的角色列表,或 `subscription.authorizeReference` 当您需要完全自定义授权时.

```ts
paystack({
  subscription: {
    enabled: true,
    plans: [],
  },
  organization: {
    enabled: true,
    billingRoles: ["owner", "admin", "billing"],
  },
});
```

### 内含弹出 Modal

使用 `@alexasomba/paystack-inline` 为无缝UI.

```ts
const { data } = await authClient.subscription.upgrade({ plan: "pro" });
if (data?.kind === "checkout") {
  const paystack = createPaystack({ publicKey: "pk_test_..." });
  paystack.checkout({
    accessCode: data.accessCode,
    onSuccess: (res) => authClient.paystack.transaction.verify({ reference: res.reference }),
  });
}
```

### 计划更改取消( C)

延迟更改当前计费周期结束:

-   **升级**: 传出 `scheduleAtPeriodEnd: true` 内 `initializeTransaction()`。 。 。 .
-   **取消数**: 使用 `authClient.subscription.cancel({ subscriptionCode, atPeriodEnd: true })` 以保持订阅活动,直到期间结束.

### 中间循环推进`prorateAndCharge`(中文(简体) )

插件可以动态地计算出即时中周期升级的成本差(如增加更多的座位). 对于当地管理的计划:

-   如果订阅已经具有可重复使用的 Paystack 授权代码, 插件会收取按比例分配的 Dleta 非会话费用, 记录一个本地 `paystackTransaction`,并立即更新订阅.
-   如果没有可用的可重复使用的授权代码(例如基于转账的支付),插件会初始化一个按比例的三角洲的新出票,而不是默默升级而不支付.
-   如果按比例分配的金额低于Paystack对货币的最低收费,则请求被拒绝,以便您可以将更改时间安排在期末,而不是低收费.

```ts
const { data } = await authClient.paystack.transaction.initialize({
  plan: "pro",
  quantity: 5, // Upgrading seats
  prorateAndCharge: true, // Charges saved authorization or returns a checkout redirect for the delta
});

if (data?.kind === "checkout") {
  window.location.href = data.url;
}

if (data?.kind === "prorated") {
  console.log(data.message);
}
```

当流量回落到退账时,在付款后验证返回的交易参考. 该插件仅在成功验证后才使用所存储的按比例调整元数据来应用待定的计划/座位更改.

### 限制订阅支付通道

使用 `subscription.allowedPaymentChannels` 以限制Paystack的取出渠道可用于订阅流量. 这适用于标准的订阅取出,试运行授权流,以及交互式的延展取出倒计时.

```ts
paystack({
  subscription: {
    enabled: true,
    allowedPaymentChannels: ["card"],
    plans: [{ name: "starter", amount: 50000, currency: "NGN", interval: "monthly" }],
  },
});
```

如果订阅费后来用一个不允许的频道进行验证,插件拒绝激活而不是默默地创建订阅.

### Webhook 安全系统

插件自动验证 `x-paystack-signature` 用于确保事件真实性的页眉 。 对于额外的安全层,你可以启用 **IP 白名单** 限制Paystack官方服务器的处理.

```ts
paystack({
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
  webhook: {
    verifyIP: true, // Enable IP whitelisting (defaults to false for flexible proxy support)
    trustedIPs: ["52.31.139.75", "52.49.173.169", "52.214.14.220"], // Optional: override trusted IPs
  },
});
```

Webhook 签名总是用 `secretKey`根据佩斯特克的要求 不创建或 配置单独的 `PAYSTACK_WEBHOOK_SECRET`。 。 。 .

### 预防虐待审判

插件检查 `referenceId` 历史 如果曾经使用过一次审判(主动、过期或审判),就不会再批准,防止重新认购虐待.

### 生命周期钩

通过在配置中提供回调来对服务器上的事件计费:

#### 订阅钩`subscription.*`(中文(简体) )

-   `onSubscriptionComplete`: 在成功进行交易核实(国内或当地)后调用.
-   `onSubscriptionCreated`:在DB中首次初始化订阅记录时调用.
-   `onSubscriptionUpdate`:在持续生命周期变化后打电话.
-   `onSubscriptionCancel`:当用户或组织取消订阅时打电话.

#### 顾客虎克`top-level` 或者说 `organization.*`(中文(简体) )

-   `onCustomerCreate`: 在插件成功创建了 Paystack 客户端后调用 .
-   `getCustomerCreateParams`: 返回自定义对象来覆盖/扩展客户创建期间发送到Paystack的数据.

#### 审判虎克`subscription.plans[].freeTrial.*`(中文(简体) )

-   `onTrialStart`: 新的试用期开始后调用.
-   `onTrialEnd`:当审判转换为主动订阅时调用.
-   `onTrialExpired`:当审判结束而不转换时调用.

在计费状态持续且不会造成 其它有效的 Paystack webhook 要重放.

#### 全球虎克

-   `onEvent`:接收从Paystack发送的每个webhook事件有效载荷进行自定义处理.

### 信任的服务器操作

经常更新和Paystack目录同步不会通过浏览器认证客户端故意被曝光. 仅从信任的后端代码启动 :

```ts
import {
  chargeSubscriptionRenewal,
  reconcilePaystackTransaction,
  syncPaystackPlans,
  syncPaystackProducts,
} from "@alexasomba/better-auth-paystack";

const ctx = { context: await auth.$context } as any;

await chargeSubscriptionRenewal(ctx, paystackOptions, {
  subscriptionId: "sub_123",
});

const settlement = await reconcilePaystackTransaction(ctx, paystackOptions, {
  reference: "PAYSTACK_REFERENCE",
  source: "queue",
  referenceId: "user_or_org_id",
});

if (settlement.ok) {
  console.log(settlement.transaction.status, settlement.subscription.updated);
}

await syncPaystackProducts(ctx, paystackOptions);
await syncPaystackPlans(ctx, paystackOptions);
```

使用 `reconcilePaystackTransaction` 从webhook处理器,队列重试, cron 任务,或者当信任的服务器代码需要与浏览器验证端点相同的校验和本地交易/订阅副作用时,管理动作.

### 授权和安全( S)

#### `authorizeReference`

控制谁可以管理特定参考(用户或组织)的账单.

```ts
paystack({
  subscription: {
    authorizeReference: async ({ user, referenceId, action }) => {
      // Example: Only allow Org Admins to initialize transactions
      if (referenceId.startsWith("org_")) {
        const member = await db.findOne({
          model: "member",
          where: [
            { field: "organizationId", value: referenceId },
            { field: "userId", value: user.id },
          ],
        });
        return member?.role === "admin";
      }
      return user.id === referenceId;
    },
  },
});
```

* * *

## 客户端 SDK 引用

客户端插件在下面显示完全打入的条形文字方法 `authClient.paystack`, (中文(简体) ), `authClient.transaction`,以及 `authClient.subscription`。 。 。 .

-   `authClient.transaction.initialize`, (中文(简体) ), `verify`, (中文(简体) ), `list`
-   `authClient.subscription.create`, (中文(简体) ), `upgrade`, (中文(简体) ), `cancel`, (中文(简体) ), `restore`, (中文(简体) ), `list`, (中文(简体) ), `billingPortal`
-   `authClient.paystack.config`, (中文(简体) ), `listProducts`, (中文(简体) ), `listPlans`,加上上面的交易/订阅帮助

遗留的相容性别名仍然可供迁移使用,但新的代码应该使用犬类方法:

-   `authClient.subscription.disable(...)` - > 使用情况 `authClient.subscription.cancel(...)`
-   `authClient.subscription.enable(...)` - > 使用情况 `authClient.subscription.restore(...)`

### `authClient.subscription.upgrade` 编号 : `create`

初始化创建或升级订阅的交易.

```ts
type upgradeSubscription = {
  /**
   * The name of the plan to subscribe to.
   */
  plan: string;
  /**
   * The email of the subscriber. Defaults to the current user's email.
   */
  email?: string;
  /**
   * Amount to charge (if not using a Paystack Plan Code).
   */
  amount?: number;
  /**
   * Currency code (e.g., "NGN").
   */
  currency?: string;
  /**
   * The callback URL to redirect to after payment.
   */
  callbackURL?: string;
  /**
   * Additional metadata to store with the transaction.
   */
  metadata?: Record<string, unknown>;
  /**
   * Reference ID for the subscription owner (User ID or Org ID).
   * Defaults to the current user's ID.
   */
  referenceId?: string;
  /**
   * Number of seats to purchase (for team plans).
   */
  quantity?: number;
};
```

### `authClient.paystack.transaction.initialize`

与 `upgrade`,但也可以通过省略用于一次性付款 `plan` 和提供 `amount` 或者说 `product`。 。 。 .

```ts
type initializeTransaction = {
  /**
   * Plan name (for subscriptions).
   */
  plan?: string;
  /**
   * Product name (for one-time purchases).
   */
  product?: string;
  /**
   * Amount to charge (if sending raw amount).
   */
  amount?: number;
  /**
   * For existing locally managed subscriptions, calculate a mid-cycle delta and either
   * charge the saved authorization or return a checkout redirect for interactive payment.
   */
  prorateAndCharge?: boolean;
  // ... same as upgradeSubscription
};

type initializeTransactionResult =
  | {
      kind: "checkout";
      url: string;
      reference: string;
      accessCode: string;
      redirect: true;
    }
  | { kind: "scheduled"; status: "success"; message: string; scheduled: true }
  | { kind: "prorated"; status: "success"; message: string; prorated: true };
```

### `authClient.subscription.list`

用户或组织的订阅列表。 组织范围内的计费行动需要所有者/管理人员默认加入。 允许诸如: `billing`配置 `organization.billingRoles`对于定制资源或更深入的政策检查,配置 `subscription.authorizeReference`。 。 。 .

```ts
type listSubscriptions = {
  query?: {
    /**
     * Filter by reference ID (User ID or Org ID).
     */
    referenceId?: string;
  };
};
```

### `authClient.subscription.cancel` 编号 : `restore`

取消或恢复订阅.

-   **取消**设置 `cancelAtPeriodEnd: true`。订阅内容仍为 `active` 直至当前计费期结束,之后移动至 `canceled`。 。 。 .
-   **恢复**: 恢复预定取消的订阅.

```ts
type cancelSubscription = {
  /**
   * Optional reference owner (user ID or org ID) when managing another billing entity.
   */
  referenceId?: string;
  /**
   * The Paystack subscription code (e.g. SUB_...)
   */
  subscriptionCode: string;
  /**
   * The email token required by Paystack to manage the subscription.
   * Optional: The server will try to fetch it if omitted.
   */
  emailToken?: string;
  /**
   * When true, keep the subscription active until the current period ends.
   */
  atPeriodEnd?: boolean;
};
```

## Schema 参考

该插件以下列字段和表格扩展您的数据库 .

### `user`

| 外地 | 类型 | 需求 | 说明 |
| :-- | :-- | :-- | :-- |
| `paystackCustomerCode` | `string` | 没有 | Paystack公司唯一的客户标识. |

### `organization`

| 外地 | 类型 | 需求 | 说明 |
| :-- | :-- | :-- | :-- |
| `paystackCustomerCode` | `string` | 没有 | 组织独特的客户识别特征. |
| `email` | `string` | 没有 | 给该组织的账单 若缺席, 则会回落到组织主的电子邮件中 . |

### `subscription`

| 外地 | 类型 | 需求 | 说明 |
| :-- | :-- | :-- | :-- |
| `plan` | `string` | 对 | 活动计划中的小写名 . |
| `referenceId` | `string` | 对 | 关联用户ID或组织ID. |
| `paystackCustomerCode` | `string` | 没有 | 这个订阅的Paystack客户代码. |
| `paystackSubscriptionCode` | `string` | 没有 | 订阅的独有代码( 例如 ), `SUB_...` 或者说 `LOC_...`) (中文(简体) ). |
| `paystackTransactionReference` | `string` | 没有 | 开始订阅的交易的引用 . |
| `paystackAuthorizationCode` | `string` | 没有 | 经常性收费的存储卡授权代码(当地计划). |
| `status` | `string` | 对 | `active`, (中文(简体) ), `trialing`, (中文(简体) ), `canceled`, (中文(简体) ), `incomplete`。 。 。 . |
| `periodStart` | `Date` | 没有 | 当前计费期的起算日期. |
| `periodEnd` | `Date` | 没有 | 当前计费期结束日期. |
| `trialStart` | `Date` | 没有 | 试行期起算日期. |
| `trialEnd` | `Date` | 没有 | 试用期结束日期. |
| `cancelAtPeriodEnd` | `boolean` | 没有 | 是否在本期末取消. |
| `seats` | `number` | 没有 | 购买的座位数 为团队计费. |

### `paystackTransaction`

| 外地 | 类型 | 需求 | 说明 |
| :-- | :-- | :-- | :-- |
| `reference` | `string` | 对 | 独特的交易参考. |
| `referenceId` | `string` | 对 | 关联用户ID或组织ID. |
| `userId` | `string` | 对 | 启动交易的用户的身份 . |
| `amount` | `number` | 对 | 交易额以最小货币单位计算. |
| `currency` | `string` | 对 | 货币编码(如"NGN"). |
| `status` | `string` | 对 | `success`, (中文(简体) ), `pending`, (中文(简体) ), `failed`, (中文(简体) ), `abandoned`。 。 。 . |
| `plan` | `string` | 没有 | 与交易有关的计划名称. |
| `product` | `string` | 没有 | 与交易有关的产品名称. |
| `metadata` | `string` | 没有 | JSON 附加交易元数据串. |
| `paystackId` | `string` | 没有 | 交易的内部Paystack身份证. |
| `createdAt` | `Date` | 对 | 交易创建时间戳 . |
| `updatedAt` | `Date` | 对 | 交易上次更新时间戳 . |

### `paystackProduct`

| 外地 | 类型 | 需求 | 说明 |
| :-- | :-- | :-- | :-- |
| `name` | `string` | 对 | 产品名. |
| `description` | `string` | 没有 | 产品说明. |
| `price` | `number` | 对 | 以最小货币单位计的价格. |
| `currency` | `string` | 对 | 货币编码(如"NGN"). |
| `quantity` | `number` | 没有 | 现有库存数量. |
| `unlimited` | `boolean` | 没有 | 产品是否有无限库存. |
| `paystackId` | `string` | 没有 | 内部Paystack产品ID. |
| `slug` | `string` | 对 | 产品独有的口水. |
| `metadata` | `string` | 没有 | JSON字符串 额外的产品元数据. |
| `createdAt` | `Date` | 对 | 产品创作时间戳. |
| `updatedAt` | `Date` | 对 | 产品上一次更新时间戳 . |

* * *

## 解决问题

-   **Webhook 签名**: 确保 `PAYSTACK_SECRET_KEY` 匹配发送 Webhook 的集成。 Paystack 使用此 API 密钥用于 `x-paystack-signature`。 。 。 .
-   **电子邮件验证**: 使用 `requireEmailVerification: true` 防止未经核实的离职.
-   **重定向失败**: 请检查您的浏览器控制台; Paystack 经常返回 429 个错误, 如果你太频繁地点击测试 API .
-   **引用错配**: 确保 `referenceId` 正确的通过组织计费.
-   **拒绝授权**: 校验您的 `authorizeReference` 逻辑是正确检查用户角色或组织成员. 未经授权的核查交易的尝试现在返回 a `401 Unauthorized` 反应防止数据泄露.

### 数据库索引

插件的图案定义包括推荐索引和性能的独特性限制. 当你跑的时候 `npx better-auth migrate`,这些将自动应用到您的数据库中.

升级后运行 `npx better-auth migrate` (或 `npx better-auth generate` 计划管理 适应器)。 添加剂 `cancelAt`, (中文(简体) ), `canceledAt`, (中文(简体) ), `endedAt`,以及 `billingInterval` 订阅 列是无效的; 历史行是随着未来生命周期事件的处理而成的.

以下字段为索引 :

-   **`paystackTransaction`**数字 : `reference` (独一无二), `userId`, (中文(简体) ), `referenceId`。 。 。 .
-   **`subscription`**数字 : `paystackSubscriptionCode` (独一无二), `referenceId`, (中文(简体) ), `paystackTransactionReference`, (中文(简体) ), `paystackCustomerCode`, (中文(简体) ), `plan`。 。 。 .
-   **`user` 打开 `organization`**数字 : `paystackCustomerCode`。 。 。 .
-   **`paystackProduct`**数字 : `slug` (独一无二), `paystackId` (独活.

按比例升级和可信赖的续延收费也持续存在 `paystackTransaction` 列,所以本地交易历史与成功的会外收费保持一致.

### 同步产品

该插件提供了两种使您的产品库存与Paystack保持一致的方法:

#### 1\. 自动编目同步

每当成功一次性付款(通过webhook或手动验证)时,插件会自动调用 **`syncProductQuantityFromPaystack`**从 Paystack API 获取实时剩余数量,并更新本地数据库记录,确保您的库存始终准确.

#### 2\. 信任的手工散装同步

公众 `/paystack/sync-products` 结束点被删除于 `2.0.0`。 。 。 . 从后端代码运行可信任的服务器操作 :

```ts
import { syncPaystackProducts } from "@alexasomba/better-auth-paystack";

const ctx = { context: await auth.$context } as any;

await syncPaystackProducts(ctx, paystackOptions);
```

### SDK 兼容性说明

该插件现在瞄准了官员 `@alexasomba/paystack-node` 组客户端直接浮出水面 . 如果您注入自定义客户端, 它应该匹配插件所使用的真实 SDK 方法, 如 `transaction.initialize`, (中文(简体) ), `transaction.verify`, (中文(简体) ), `transaction.chargeAuthorization`, (中文(简体) ), `subscription.create`, (中文(简体) ), `subscription.disable`,以及 `subscription.enable`。 。 。 .

* * *

## 发展与贡献

此寄存器由 **维特+**您使用 `vp` 管理整个工作空间的CLI.

```bash
# Install dependencies
vp i

# Check project health (format, lint, types)
vp check --fix

# Build the core library
vp build

# Run tests
vp test

# Run the TanStack Start example
vp run examples/tanstack dev
```

欢迎捐款! 请打开一个问题或拉请求.

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/%40alexasomba/better-auth-paystack/LICENSE) 详细文件.

## 路线图

为未来版本规划的未来功能:

### v1.1.0 - 手动经常订阅(现在可退出)

-   [x] **存储的授权代码**: 从已核实的交易中安全地存储Paystack授权代码.
-   [x] **信任的更新操作**:服务器侧辅助器,用于充值存储的卡片以进行更新.
-   [ ] **卡片管理 UI**: 让用户查看/删除已保存的支付方法(只使用卡片数据) - _即将_
-   [ ] **更新调度器集成**: 与Cloudflare工人克龙,Vercel克龙等融合的文献 - _即将_

> **说明**: 当地管理的订阅(无) `planCode`,插件自动抓取并存储 `authorization_code`从信任的后端代码中触发更新 `chargeSubscriptionRenewal(...)`。 。 。 .

### 今后的考虑

-   [ ] 多货币支助改进
-   [ ] 发票生成
-   [ ] 无法续签的付款逻辑

## 链接

-   GitHub 仓库 : [亚历克萨松巴/优等生](https://github.com/alexasomba/better-auth-paystack)
-   全面和最新的Paystack节点SDK: [alexasomba/pastack-节点](https://github.com/alexasomba/paystack-node)
-   综合最新Paystack Inline SDK: [alexasomba/pastack-inline (英语)](https://github.com/alexasomba/paystack-inline)
-   [TanStack 启动示例](https://github.com/alexasomba/better-auth-paystack/tree/main/examples/tanstack)
-   Paystack Webhooks: (原始内容存档于2017-09-21) [https://paystack.com/docs/paying/webhooks/ 页面存档备份,存于互联网档案馆](https://paystack.com/docs/payments/webhooks/)
-   Paystack 交易 API : [https://paystack.com/docs/api/ 交易/](https://paystack.com/docs/api/transaction/)
-   付费订阅 API: [https://paystack.com/docs/api/订阅/](https://paystack.com/docs/api/subscription/)
-   Paystack 计划 API : [https://paystack.com/docs/api/plan/ (中文(简体) )](https://paystack.com/docs/api/plan/)
-   [更好的认证文档](https://www.better-auth.com/docs)

## 常见问题

### @alexasomba/better-auth-paystack 是什么？

生产准备的Paystack计费插件,用于Better Auth\. 支持订阅、一次性付款、组织收费、安全网约车等注意：该包已被作者标记为弃用——Deprecated: use the unscoped better-auth-paystack package instead\. Install with: npm install better-auth-paystack\. Update imports to better-auth-paystack\.

### 如何安装 @alexasomba/better-auth-paystack？

在项目目录运行 npm install @alexasomba/better-auth-paystack，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：better-auth（^1\.6\.25）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alexasomba/better-auth-paystack 支持 TypeScript 吗？

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

### @alexasomba/better-auth-paystack 支持 ESM 还是 CommonJS？

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

### @alexasomba/better-auth-paystack 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @alexasomba/better-auth-paystack 可以商用吗？

@alexasomba/better-auth-paystack 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @alexasomba/better-auth-paystack 的下载量有多少？

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

### @alexasomba/better-auth-paystack 还在维护吗？

最新版本 3\.1\.1 发布于 2026/07/29（3 个月前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2025/12/16。作者已将其标记为弃用，新项目建议寻找替代方案。