更好的 Auth Paystack 插件

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

Live Demo( 唐斯塔克启动) | 源代码

AI 代理技能

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

使用 TanStack 意图 需要明确列出或加载个人技能时:

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 用于兼容代理的同义链接软件包技能:

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

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

特征

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

快速启动

先决条件

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

1. 安装插件和SDK

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

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

npm install @alexasomba/paystack-inline

2. 配置环境变量

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

3. 设置服务器插件

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. 配置客户端插件

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

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

旧

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

新设

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 处理反复出现的逻辑和电子邮件.

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

当地

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

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

2. 一次性付款

固定产品

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

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

临时数额

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

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

限制和座位管理

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

成员席位限制

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

资源限制(如团队)

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

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

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

订阅组

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

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

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

货币支持

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

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

高级使用

组织账单

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

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

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

内含弹出 Modal

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

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对货币的最低收费,则请求被拒绝,以便您可以将更改时间安排在期末,而不是低收费.

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的取出渠道可用于订阅流量. 这适用于标准的订阅取出,试运行授权流,以及交互式的延展取出倒计时.

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

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

Webhook 安全系统

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

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目录同步不会通过浏览器认证客户端故意被曝光. 仅从信任的后端代码启动 :

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

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

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

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

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。 。 。 .

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。 。 。 .

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

authClient.subscription.cancel 编号 : restore

取消或恢复订阅.

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

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

organization

subscription

paystackTransaction

paystackProduct

解决问题

• 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。 。 。 . 从后端代码运行可信任的服务器操作 :

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.

# 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

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

许可证

这个项目根据麻省理工学院许可证颁发——见 自由主义 详细文件.

路线图

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

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

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

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

今后的考虑

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

链接

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