@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签名验证助手.

安装

pnpm add @alexasomba/paystack-node

代理技能

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

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 密钥认证请求 :

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

快速启动

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: "[email protected]",
    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数字 :

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

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: "[email protected]",
  amount: 5000,
};

const chargeAuthorization: TransactionChargeAuthorizationPayload = {
  email: "[email protected]",
  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对象.

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 形状因端点和页化模式而异.

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

处理错误

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

模块实例

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

交易

const tx = await paystack.transaction_initialize({
  body: { email: "[email protected]", amount: 5000 },
});

核查付款(交易核查)

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

收费

await paystack.charge_create({
  body: {
    email: "[email protected]",
    amount: 5000,
    bank: { code: "057", account_number: "0001234567" },
  },
});

散装电荷

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

子账户

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

交易分割

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

终端

const terminals = await paystack.terminal_list();

虚拟终端

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

客户

await paystack.customer_create({
  body: { email: "[email protected]", first_name: "Ada", last_name: "Lovelace" },
});

直接调试

await paystack.directdebit_initialize({
  body: { email: "[email protected]", amount: 5000, bank_code: "057" },
});

专用虚拟账户

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

苹果支付

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

计划

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

订阅

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

传输收件人

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

转账

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

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

await paystack.transfer_enableOtp();

余额

const balance = await paystack.balance_fetch();

付款请求(发票)

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

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

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

产品

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

存储前期

const storefronts = await paystack.storefront_list();

命令

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

付款页

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

定居点

const settlements = await paystack.settlement_list();

一体化

const timeout = await paystack.integration_fetchPaymentSessionTimeout();

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

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

退款

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

争端

const disputes = await paystack.dispute_list();

银行

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

杂项

const countries = await paystack.miscellaneous_listCountries();

相关 SDKs

• @alexasomba/paistack-浏览器 - 浏览器获取优化.
• @alexasomba/paystack-xios (英语) - 对于使用Axios的项目.

用户

• 更好的 Auth Paystack 插件: 一个综合性的Paystack插件,用于Better Auth.

来源

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

许可证

麻省理工学院