# @alexasomba/paystack-node 中文文档

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

版本：1\.12\.0
npm 元数据更新时间：2026-10-10T07:17:32.589Z
中文译文更新时间：2026-11-06T07:27:55.323Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：818 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- 首次发布：2025-12-15T12:39:33.959Z
- 最新版本发布：2026-10-10T07:17:32.272Z
- 近 30 天下载量：4173（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

Paystack最全面的Node.js SDK - 完整,类型安全,并符合Spec要求,具有全面的OpenAPI覆盖范围和webhook验证.

## 安装

```sh
npm install @alexasomba/paystack-node
```

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

## README

# @alexasomba/paystack-node (英语)

[![npm version](https://img.shields.io/npm/v/@alexasomba/paystack-node.svg)](https://www.npmjs.com/package/@alexasomba/paystack-node) [![license](https://img.shields.io/npm/l/@alexasomba/paystack-node.svg)](https://github.com/alexasomba/paystack-node/blob/main/LICENSE) [![bundle size](https://img.shields.io/bundlephobia/minzip/@alexasomba/paystack-node)](https://bundlephobia.com/package/@alexasomba/paystack-node)

TypeScript-First Paystack API客户端为Node.js,由官方Paystack OpenAPI spec生成.

## 特征

-   **光谱驱动精确度**:直接由Paystack OpenAPI规格生成.
-   **100%类型安全**: 完整类型脚本支持,每个端点、请求和响应都有生成类型.
-   **智能检索**: 以指数回放和焦急值对瞬态故障自动重试.
-   **合规后重试**: 自动尊重 Paystack `Retry-After` 速率限制回复信头.
-   **精密度**:在 POST 请求上为手动,静态,或基于UUID的自动等效键提供内置支持.
-   **详细错误处理**数字 : `PaystackError` 保护 Paystack `code`, (中文(简体) ), `type`, (中文(简体) ), `meta`,请求ID,HTTP状态,以及原始响应正文.
-   **Webhook 验证**: 包括时间安全webhook签名验证助手.

## 安装

```bash
pnpm add @alexasomba/paystack-node
```

## 代理技能

这个包装船 TanStack 意向技能 代理辅助 Paystack 集成:

```bash
npx @tanstack/intent@latest list
npx @tanstack/intent@latest install --map
npx @tanstack/intent@latest load @alexasomba/paystack-node#paystack-node-api-operations
```

实用技能包括: `paystack-node-client-setup`, (中文(简体) ), `paystack-node-api-operations`, (中文(简体) ), `paystack-node-operation-discovery`, (中文(简体) ), `paystack-node-typed-payloads`, (中文(简体) ), `paystack-node-responses-errors`, (中文(简体) ), `paystack-node-retries-idempotency`, (中文(简体) ), `paystack-node-transport-testing`,以及 `paystack-node-webhooks`。 。 。 .

用您的 Paystack 密钥认证请求 :

```ts
process.env.PAYSTACK_SECRET_KEY = "sk_test_...";
```

## 快速启动

```ts
import { createPaystack, assertOk } from "@alexasomba/paystack-node";

const paystack = createPaystack({
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
  idempotencyKey: "auto",
});

const result = await paystack.transaction_initialize({
  body: {
    email: "customer@example.com",
    amount: 5000,
  },
});

const data = assertOk(result);
console.log(data.authorization_url);
```

`assertOk` 返回成功的 Paystack 有效载荷并丢出结构化 `PaystackError` 非-2xxx回复或 `{ status: false }` 信封 信封 信封.

## API 基本知识

-   基础 URL : `https://api.paystack.co`
-   所有请求都需要HTTPS.
-   请求和答复以JSON为基础.
-   最成功的对策是: `status`, (中文(简体) ), `message`, (中文(简体) ), `data`选择 `meta` 信封说明 `Paystack-API/0a-Introduction.md`。 。 。 .
-   金额通常以货币子单位如kobo,pesewas,或一分钱来发送. 请检查docs中的货币特定规则.

## 认证环境( E)

-   服务器侧 SDK 应使用您的密钥( S)`sk_test_*` 或者说 `sk_live_*`) (中文(简体) ).
-   浏览器 SDK 只能使用您的公钥( S)`pk_test_*` 或者说 `pk_live_*`) (中文(简体) ).
-   发送服务器侧 API 证书为 `Authorization: Bearer YOUR_SECRET_KEY`。 。 。 .
-   测试和活模式使用不同的密钥和孤立的环境.
-   如果密钥被曝光则旋转, 并且从不将密钥输入源控 .
-   如果您启用 Paystack 的 IP 白名单, 非白名单的 IP 请求将会被屏蔽 .

## 高级配置

这个 `createPaystack` 帮助者接受 `PaystackClientOptions`数字 :

```ts
const paystack = createPaystack({
  secretKey: "sk_...",
  timeoutMs: 30_000,
  retry: {
    retries: 3,
    minDelayMs: 500,
    retryOnStatuses: [429, 500, 503],
  },
  idempotencyKey: "auto",
  headers: {
    "X-My-App": "v1.0.0",
  },
});
```

## 稳定型出口

SDK 输出稳定的分组客户切片, 并解析请求/ query/应答化名, 因此下游集成不需要重建类型 `ReturnType<typeof createPaystack>`, (中文(简体) ), `paths`,或 `operations`。 。 。 .

```ts
import {
  createPaystack,
  type Paystack,
  type PaystackTransactionClient,
  type PaystackSubscriptionClient,
  type TransactionInitializePayload,
  type TransactionChargeAuthorizationPayload,
  type SubscriptionCreatePayload,
  type SubscriptionListQueryParams,
  type RefundCreatePayload,
} from "@alexasomba/paystack-node";

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

const transactionClient: PaystackTransactionClient = paystack.transaction;
const subscriptionClient: PaystackSubscriptionClient = paystack.subscription;

const tx: TransactionInitializePayload = {
  email: "customer@example.com",
  amount: 5000,
};

const chargeAuthorization: TransactionChargeAuthorizationPayload = {
  email: "customer@example.com",
  amount: 2500,
  authorization_code: "AUTH_123",
};

const subscriptionCreate: SubscriptionCreatePayload = {
  customer: "CUS_123",
  plan: "PLN_123",
};

const subscriptionList: SubscriptionListQueryParams = {
  customer: 123,
};

const refundCreate: RefundCreatePayload = {
  transaction: "TRX_123",
  amount: 1000,
};
```

显著的别名包括交易初始化/充电授权/验证;订阅创建/列表/禁用/启用/获取/管理链接/管理电子邮件;客户获取/创建/更新;计划列表/创建/更新/获取;产品列表/创建/更新/获取;争议列表/获取;退款创建/获取;支付请求创建/获取;终端发送事件;以及账户解析,账户验证和卡BIN查询的验证帮助.

客户端切片包括 `PaystackTransactionClient`, (中文(简体) ), `PaystackCustomerClient`, (中文(简体) ), `PaystackSubscriptionClient`, (中文(简体) ), `PaystackPlanClient`, (中文(简体) ), `PaystackProductClient`, (中文(简体) ), `PaystackDisputeClient`,以及 `PaystackRefundClient`。 。 。 .

分组方法反映了支持生成的OpenAPI操作. 不支持的帮助者, 如 `subscription.update` 故意不属于公共SDK表面.

### 网络呼号

在验证来自Paystack的服务器到服务器事件时使用 Webhook 帮助器 。 传递原始请求正文,而非解析出JSON对象.

```ts
import { verifyPaystackWebhookSignature } from "@alexasomba/paystack-node/webhooks";

const isValid = verifyPaystackWebhookSignature({
  rawBody: req.body,
  signature: req.headers["x-paystack-signature"],
  secret: process.env.PAYSTACK_SECRET_KEY!,
});
```

### 处理缓冲

列表端点通过查询参数等显示 pagination 控制 `perPage`, (中文(简体) ), `page`, (中文(简体) ), `next`,以及 `previous`。当您需要手动调试控制时,仍可使用响应头.

## 倾斜

-   Paystack 既支持相抵平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平.
-   偏移标记用途 `page` 财务报告和审定财务报表 `perPage`。 。 。 .
-   光标标记使用 `use_cursor=true` 加号 `next` 或者说 `previous` 光标返回 `meta`。 。 。 .
-   Cursor pagining对大型或频繁变化的数据集特别有用.
-   准确 `meta` 形状因端点和页化模式而异.

```ts
const result = await paystack.customer_list({ query: { perPage: 20 } });
const customers = assertOk(result);
const total = result.response.headers.get("x-total-count");
```

## 处理错误

```ts
import { toPaystackApiError } from "@alexasomba/paystack-node";

const result = await paystack.transaction_initialize({/* ... */});
const error = toPaystackApiError(result);

if (error) {
  console.error(`Status ${error.status}: ${error.message}`);
  console.error(`Paystack code: ${error.code}`);
  console.error(`Paystack type: ${error.type}`);
  console.error(`Paystack Request ID: ${error.requestId}`);
  console.error(error.raw);
}
```

使用 `error.code` 财务报告和审定财务报表 `error.type` 用于在验证、处理器和API故障上进行分支。 这个 `requestId` 当将日志与Paystack支持的问题联系起来或升级时有用,同时 `error.raw` 编号 : `error.body` 保持原始反应信封可供诊断.

## 错误

-   Paystack 使用常规的 HTTP 状态代码, 如 : `200`, (中文(简体) ), `201`, (中文(简体) ), `400`, (中文(简体) ), `401`, (中文(简体) ), `404`,以及 `5xx`。 。 。 .
-   错误反应通常包括 `status`, (中文(简体) ), `message`, (中文(简体) ), `type`, (中文(简体) ), `code`和可选诊断 `meta` 资料.
-   描述错误类型 `Paystack-API/0d-Errors.md` 包含 `api_error`, (中文(简体) ), `validation_error`,以及 `processor_error`。 。 。 .
-   对于充电和核实流量,总是检查返回的响应正体和状态字段,而不仅仅是HTTP代码.

## 覆盖范围

这个SDK是由这个单列波中的SDK spec所生成的,目前追踪了Paystack-API相通合同所生成的全套打字操作.

## 模块

对于这个 SDK ,这些计划家族通过生成的 TypeScript 类型在 `src/openapi-types.ts` 和操作助手 `src/operations.ts`。 。 。 .

| 模块 | 司马/模范家族 |
| --- | --- |
| 交易 | `Transaction*` |
| 核查付款(交易核查) | `VerifyResponse / TransactionFetchResponse` |
| 收费 | `Charge*` |
| 散装电荷 | `BulkCharge*` |
| 子账户 | `Subaccount*` |
| 交易分割 | `Split*` |
| 终端 | `Terminal*` |
| 虚拟终端 | `VirtualTerminal*` |
| 客户 | `Customer*` |
| 直接调试 | `DirectDebit*` |
| 专用虚拟账户 | `DedicatedNuban* / DedicatedVirtualAccount*` |
| 苹果支付 | `ApplePay*` |
| 计划 | `Plan*` |
| 订阅 | `Subscription*` |
| 传输收件人 | `TransferRecipient*` |
| 转账 | `Transfer*` |
| 转移控制(OTP设置;转移下) | `TransferEnable* / TransferDisable* / TransferFinalize*` |
| 余额 | `Balance*` |
| 付款请求(发票) | `PaymentRequest*` |
| 校验( 解析账户 / 验证账户 / 解析卡 BIN) | `Verification*` |
| 产品 | `Product*` |
| 存储前期 | `Storefront*` |
| 命令 | `Order*` |
| 付款页 | `Page*` |
| 定居点 | `Settlement*` |
| 一体化 | `Integration*` |
| 控制面板(支付会话超时;整合下) | `ControlPanel*` |
| 退款 | `Refund*` |
| 争端 | `Dispute*` |
| 银行 | `Bank*` |
| 杂项 | `Miscellaneous* / Currency` |

## 模块实例

这些是有意的简短的例子。 将其用作切入点,然后用编辑器所显示的输入字段来扩展请求机构 `src/openapi-types.ts`。 。 。 .

### 交易

```ts
const tx = await paystack.transaction_initialize({
  body: { email: "customer@example.com", amount: 5000 },
});
```

### 核查付款(交易核查)

```ts
const verified = await paystack.transaction_verify({
  params: { path: { reference: "ref_123" } },
});
```

### 收费

```ts
await paystack.charge_create({
  body: {
    email: "customer@example.com",
    amount: 5000,
    bank: { code: "057", account_number: "0001234567" },
  },
});
```

### 散装电荷

```ts
await paystack.bulkCharge_initiate({
  body: [{ authorization: "AUTH_xxx", amount: 5000, reference: "bulk-ref-1" }],
});
```

### 子账户

```ts
await paystack.subaccount_create({
  body: {
    business_name: "Acme Stores",
    settlement_bank: "057",
    account_number: "0001234567",
    percentage_charge: 10,
  },
});
```

### 交易分割

```ts
await paystack.split_create({
  body: { name: "Main split", type: "percentage", currency: "NGN", subaccounts: [] },
});
```

### 终端

```ts
const terminals = await paystack.terminal_list();
```

### 虚拟终端

```ts
await paystack.virtualTerminal_create({
  body: { name: "Web checkout terminal" },
});
```

### 客户

```ts
await paystack.customer_create({
  body: { email: "customer@example.com", first_name: "Ada", last_name: "Lovelace" },
});
```

### 直接调试

```ts
await paystack.directdebit_initialize({
  body: { email: "customer@example.com", amount: 5000, bank_code: "057" },
});
```

### 专用虚拟账户

```ts
await paystack.dedicatedAccount_assign({
  body: { customer: 12345, preferred_bank: "wema-bank" },
});
```

### 苹果支付

```ts
await paystack.applePay_registerDomain({
  body: { domainName: "example.com" },
});
```

### 计划

```ts
await paystack.plan_create({
  body: { name: "Starter", amount: 500000, interval: "monthly" },
});
```

### 订阅

```ts
await paystack.subscription_create({
  body: { customer: "CUS_xxx", plan: "PLN_xxx" },
});
```

### 传输收件人

```ts
await paystack.transferrecipient_create({
  body: {
    type: "nuban",
    name: "Ada Lovelace",
    account_number: "0001234567",
    bank_code: "057",
    currency: "NGN",
  },
});
```

### 转账

```ts
await paystack.transfer_create({
  body: { source: "balance", amount: 5000, recipient: "RCP_xxx", reason: "Vendor payout" },
});
```

### 转移控制(OTP设置;转移下)

```ts
await paystack.transfer_enableOtp();
```

### 余额

```ts
const balance = await paystack.balance_fetch();
```

### 付款请求(发票)

```ts
await paystack.paymentRequest_create({
  body: { customer: "CUS_xxx", amount: 5000, description: "Consulting invoice" },
});
```

### 校验( 解析账户 / 验证账户 / 解析卡 BIN)

```ts
await paystack.bank_resolveAccountNumber({
  params: { query: { account_number: "0001234567", bank_code: "057" } },
});
```

### 产品

```ts
await paystack.product_create({
  body: { name: "T-shirt", description: "Cotton tee", price: 5000, currency: "NGN" },
});
```

### 存储前期

```ts
const storefronts = await paystack.storefront_list();
```

### 命令

```ts
await paystack.order_create({
  body: { customer: "CUS_xxx", items: [] },
});
```

### 付款页

```ts
await paystack.page_create({
  body: { name: "Event Ticket", amount: 5000, description: "Landing page for ticket sales" },
});
```

### 定居点

```ts
const settlements = await paystack.settlement_list();
```

### 一体化

```ts
const timeout = await paystack.integration_fetchPaymentSessionTimeout();
```

### 控制面板(支付会话超时;整合下)

```ts
await paystack.integration_updatePaymentSessionTimeout({
  body: { timeout: 20 },
});
```

### 退款

```ts
await paystack.refund_create({
  body: { transaction: 123456789, amount: 5000 },
});
```

### 争端

```ts
const disputes = await paystack.dispute_list();
```

### 银行

```ts
const banks = await paystack.bank_list({ params: { query: { country: "nigeria" } } });
```

### 杂项

```ts
const countries = await paystack.miscellaneous_listCountries();
```

## 相关 SDKs

-   [@alexasomba/paistack-浏览器](https://github.com/alexasomba/paystack-browser) - 浏览器获取优化.
-   [@alexasomba/paystack-xios (英语)](https://github.com/alexasomba/paystack-axios) - 对于使用Axios的项目.

## 用户

-   **[更好的 Auth Paystack 插件](https://github.com/alexasomba/better-auth-paystack)**: 一个综合性的Paystack插件,用于Better Auth.

## 来源

-   Monorepo 来源 : [阿列克萨松巴/帕斯塔克-波拿皮](https://github.com/alexasomba/paystack-openapi)
-   独立的 SDK repo : [https://github.com/alexasomba/paystack-node 页面存档备份,存于互联网档案馆](https://github.com/alexasomba/paystack-node)

## 许可证

麻省理工学院

## 常见问题

### @alexasomba/paystack-node 是什么？

Paystack最全面的Node\.js SDK - 完整,类型安全,并符合Spec要求,具有全面的OpenAPI覆盖范围和webhook验证\.

### 如何安装 @alexasomba/paystack-node？

在项目目录运行 npm install @alexasomba/paystack-node，或使用 pnpm add / yarn add / bun add。

### @alexasomba/paystack-node 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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