# @alexasomba/paystack-inline 中文文档

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

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

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

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

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

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

## 中文简介

Paystack Popup (inline.js) 的强型,基于承诺的TypeScript包装器.

## 安装

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

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

## README

# @alexasomba/paystack-inline (英语)

A 类 **强烈类型, 以承诺为基础的类型Script 包装器** 用于 Paystack 弹出(`inline.js`) (中文(简体) ). 给予你完全的IDE自动完整和打出安全性,同时安全地将所有举重——iframe渲染,WebSockets,Apple Pay会话,PCI遵守——推迟到Paystack的官方CDN.

> **为什么不直接绑入内线?**  
> Paystack 船舶安全 和欺诈- 检测补丁 沉默通过其CDN。 通过在运行时动态地加载脚本,你的用户总是得到最新的,最安全的版本——而无需剪去新的发布.

* * *

## 特征

-   ✅ **零依赖关系** 没有npm bloat,0.91 kB gziped
-   ✅ **完整的脚本类型** 对每个选项、召回和回复
-   \* 所有记录 **财务报告和审定财务报表** 无证别名来自 `inline.js` 包含
-   ✅ `loadPaystack()` 承诺防止比赛条件和双装
-   支持 : **卡片、银行、USSD、移动货币、银行转账、QR、苹果支付、订阅、分版**
-   与 **反应, Vue, Svelte, Next.js, SvelteKit, 平面 HTML** - 任何前端

* * *

## 安装

```bash
npm install @alexasomba/paystack-inline
# or
pnpm add @alexasomba/paystack-inline
# or
yarn add @alexasomba/paystack-inline
```

## 代理技能

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

```bash
npx @tanstack/intent@latest list
npx @tanstack/intent@latest install --map
npx @tanstack/intent@latest load @alexasomba/paystack-inline#paystack-inline-checkout
```

实用技能包括: `paystack-inline-checkout`, (中文(简体) ), `paystack-inline-server-verify`, (中文(简体) ), `paystack-inline-popup-options`,以及 `paystack-inline-popup-lifecycle`。 。 。 .

* * *

## 快速启动

### 1\. 从您的服务器初始化( 需要)

永远不要从浏览器中调用Paystack的API——你的秘密密钥将会被曝光. 在后端初始化并传递 `access_code` 到前端:

```bash
curl https://api.paystack.co/transaction/initialize \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "customer@email.com", "amount": "500000" }' \
  -X POST
```

答复包括: `data.access_code`把这个送到前端.

### 2\. 在浏览器中恢复交易

```typescript
import { loadPaystack } from "@alexasomba/paystack-inline";

const PaystackPop = await loadPaystack();
const popup = new PaystackPop();

popup.resumeTransaction(accessCode, {
  onSuccess: (response) => {
    console.log("Payment successful!", response.reference);
    // Verify on your server before delivering value
  },
  onCancel: () => {
    console.log("User cancelled payment");
  },
});
```

> **总是验证服务器侧** 之后 `onSuccess`从不提供完全基于客户调回的值——与 [验证交易](https://paystack.com/docs/api/transaction/#verify) 终点.

* * *

## API 参考

### `loadPaystack()`

动态注入 `https://js.paystack.co/v2/inline.js` 输入页面,并用 `PaystackPop` 建筑师。 安全可以多次调用——只创建了一个脚本标记.

```typescript
import { loadPaystack } from "@alexasomba/paystack-inline";

const PaystackPop = await loadPaystack();
const popup = new PaystackPop();
```

**掷出** 如果在浏览器外调用(例如服务器侧渲染)。 需要时在浏览器检查中环绕 :

```typescript
if (typeof window !== "undefined") {
  const PaystackPop = await loadPaystack();
}
```

* * *

### `popup.resumeTransaction(accessCode, callbacks?)`

这个 **建议** 检查流量 。 在您的服务器上初始化, 然后恢复客户端 .

```typescript
popup.resumeTransaction("br6cgmvflhn3qtd", {
  onSuccess: (res) => console.log(res.reference),
  onCancel: () => console.log("cancelled"),
  onError: (err) => console.error(err.message),
});
```

* * *

### `popup.newTransaction(options)`

使用您的公钥直接从前端启动交易 .

> \[尖叫声\] 这个 `amount` 必须是在 **最低货币面额** (例如NGN的kobo,GHS的pesewas). `500000` = 5 000个.

```typescript
const transaction = popup.newTransaction({
  key: "pk_test_xxxxxxxxx",
  email: "customer@email.com",
  amount: 500000,
  currency: "NGN",
  reference: "unique-ref-" + Date.now(),
  onSuccess: (response) => {
    console.log("Transaction ref:", response.reference);
  },
  onCancel: () => {
    console.log("Checkout closed");
  },
});
```

#### 核心选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `key` | `string` | ✅ | 你的佩斯达克 **公开** 键`pk_...`(中文(简体) ) |
| `email` | `string` | ✅ | 客户的电子邮件地址 |
| `amount` | `number` | ✅ | 以最低货币单位计算的数额(例如Kobo) |
| `currency` | `string` | —— 说 | 货币代码 : `NGN`, (中文(简体) ), `GHS`, (中文(简体) ), `ZAR`, (中文(简体) ), `KES`, (中文(简体) ), `USD` |
| `reference` | `string` | —— 说 | 独特的交易参考。 未设置时自动生成 |
| `label` | `string` | —— 说 | 退出时显示的客户名 |
| `channels` | `string[]` | —— 说 | 限制频道 : `["card", "bank", "ussd", "mobile_money", "bank_transfer", "qr", "eft"]` |
| `metadata` | `object` | —— 说 | 交易所附任意密钥值数据 |
| `language` | `string` | —— 说 | 强制退出语言( E)`en`, (中文(简体) ), `fr`, (中文(简体) ), `pt`页:1 |

#### 客户选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `firstName` | `string` | 预填客户名 |
| `lastName` | `string` | 预填客户名 |
| `phone` | `string` | 客户电话号码 |
| `customerCode` | `string` | 现有的 Paystack 客户代码 |

* * *

### `popup.preloadTransaction(options)` → `() => void`

预feet 检查出 iframe 在背景中为快取 UX 。 返回打开预装弹出功能 .

```typescript
const open = popup.preloadTransaction({
  key: "pk_test_xxxxxxx",
  email: "customer@email.com",
  amount: 100000,
  onSuccess: (res) => verifyOnServer(res.reference),
});

// Later, when user clicks "Pay":
document.getElementById("pay-btn").addEventListener("click", open);
```

* * *

### `popup.checkout(options)` → `Promise<PopupTransaction>`

约取出. 决定: `PopupTransaction` 弹出时的对象.

```typescript
const transaction = await popup.checkout({
  key: "pk_test_xxxxxxx",
  email: "customer@email.com",
  amount: 200000,
  onSuccess: (res) => console.log(res),
});

// Check status at any time:
console.log(transaction.getStatus());
```

* * *

### `popup.cancelTransaction(idOrTransaction)`

程序上关闭一个公开交易.

```typescript
const tx = popup.newTransaction({ ... });
// ... later
popup.cancelTransaction(tx); // or popup.cancelTransaction(tx.id)
```

* * *

### `popup.paymentRequest(options)` → `Promise<PopupTransaction>`

显示一个 **嵌入式支付元素** (Apple Pay按钮,钱包按钮)入到DOM容器. 适合自定义的检查.

```typescript
const payment = await popup.paymentRequest({
  key: "pk_test_xxxxxxx",
  email: "customer@email.com",
  amount: 500000,
  container: "#payment-request-container", // CSS selector or element ID
  onSuccess: (res) => console.log(res),
  onElementsMount: (elements) => {
    console.log("Payment elements mounted:", elements);
  },
  styles: {
    theme: "dark",
    applePay: {
      width: "100%",
      height: "48px",
      borderRadius: "8px",
      type: "buy", // "plain" | "buy" | "donate"
      locale: "en-US",
    },
  },
});
```

#### `paymentRequest` 选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `container` | `string` | QQ CSS 选择器或挂载目标的元素ID |
| `loadPaystackCheckoutButton` | `string` | 打开完整弹出点的自定义按钮的选择器 |
| `styles.theme` | `"dark" | "light"` | 苹果支付按钮主题 |
| `styles.applePay.type` | `string` | 苹果支付按钮标签 : `"plain"`, (中文(简体) ), `"buy"`, (中文(简体) ), `"donate"` |
| `styles.applePay.locale` | `string` | 苹果支付按钮区域 |
| `onElementsMount` | `function` | 当嵌入元素出现在 DOM 中时起火 |

* * *

## 回电

所有交易方法都接受相同的回调接口 :

| 回电 | 签署 | 说明 |
| --- | --- | --- |
| `onSuccess` | `(res: { id, reference, message }) => void` | 成功完成付款 |
| `onError` | `(err: { message: string }) => void` | 付款失败, 出错 |
| `onCancel` | `() => void` | 用户在完成前关闭弹出 |
| `onClose` | `() => void` | 弹出已关闭( 包括取消和成功) |
| `onLoad` | `(res: { id, customer, accessCode }) => void` | 弹出已装满并准备好 |
| `onBankTransferConfirmationPending` | `() => void` | 启动银行转账,等待确认 |
| `callback` | `(res: any) => void` | 遗产 v1 回调( 使用) `onSuccess` 改为) |

* * *

## 订阅

向客户收取经常性计划费用:

```typescript
popup.newTransaction({
  key: "pk_test_xxxxxxx",
  email: "customer@email.com",
  amount: 500000,
  plan: "PLN_xxxxxxxxx", // or planCode
  quantity: 1, // number of seats/plan units
  interval: "monthly", // or planInterval
  invoice_limit: 12, // stop after N billing cycles
  start_date: "2025-01-01T00:00:00Z",
  onSuccess: (res) => console.log(res),
});
```

#### 订阅选项

| 选项 | 类型 | 别名 | 说明 |
| --- | --- | --- | --- |
| `planCode` | `string` | `plan` | Paystack 计划代码 (`PLN_...`(中文(简体) ) |
| `subscriptionCount` | `number` | `quantity` | 订阅次数/席位 |
| `planInterval` | `string` | `interval` | `hourly`, (中文(简体) ), `daily`, (中文(简体) ), `weekly`, (中文(简体) ), `monthly`, (中文(简体) ), `annually` |
| `subscriptionLimit` | `number` | `invoice_limit` | 停止前的最大计费周期 |
| `subscriptionStartDate` | `string` | `start_date` | ISO 8601 第一次充电的日期 |

* * *

## 分期付款

分账户付款的路由:

```typescript
popup.newTransaction({
  key: "pk_test_xxxxxxx",
  email: "customer@email.com",
  amount: 500000,
  subaccount: "ACCT_xxxxxxxxx", // or subaccountCode
  bearer: "account", // who bears transaction charges
  transaction_charge: 2000, // flat charge for the main account (kobo)
  onSuccess: (res) => console.log(res),
});
```

#### 拆分选项

| 选项 | 类型 | 别名 | 说明 |
| --- | --- | --- | --- |
| `subaccountCode` | `string` | `subaccount` | 要拆分的子账户代码 |
| `split_code` | `string` |  | 引用一个预配置的拆分组 |
| `split` | `object` |  | 内置分割配置对象 |
| `connect_split` | `string[]` |  | 多分解连接账户代码阵列 |
| `bearer` | `"account" | "subaccount"` |  | 交易费由谁承担 |
| `transactionCharge` | `string | number` | `transaction_charge` | 主账户留存的平价费用(以可博计) |

* * *

## 框架实例

### 反应

```typescript
import { loadPaystack } from "@alexasomba/paystack-inline";

function CheckoutButton({ accessCode }: { accessCode: string }) {
  const handlePay = async () => {
    const PaystackPop = await loadPaystack();
    const popup = new PaystackPop();

    popup.resumeTransaction(accessCode, {
      onSuccess: (response) => {
        // Call your API to verify + fulfill the order
        fetch("/api/verify", {
          method: "POST",
          body: JSON.stringify({ reference: response.reference }),
        });
      },
      onCancel: () => console.log("Payment cancelled"),
    });
  };

  return <button onClick={handlePay}>Pay Now</button>;
}
```

### Next.js (App路由器) (英语)

```typescript
"use client"; // Required — loadPaystack() is browser-only

import { loadPaystack } from "@alexasomba/paystack-inline";

export default function PayButton({ accessCode }: { accessCode: string }) {
  const handlePay = async () => {
    const PaystackPop = await loadPaystack();
    const popup = new PaystackPop();
    popup.resumeTransaction(accessCode, {
      onSuccess: (res) => console.log(res.reference),
    });
  };

  return <button onClick={handlePay}>Complete Payment</button>;
}
```

### 第3组

```typescript
<script setup lang="ts">
import { loadPaystack } from "@alexasomba/paystack-inline";

const props = defineProps<{ accessCode: string }>();

const handlePay = async () => {
  const PaystackPop = await loadPaystack();
  const popup = new PaystackPop();
  popup.resumeTransaction(props.accessCode, {
    onSuccess: (res) => console.log(res.reference),
  });
};
</script>

<template>
  <button @click="handlePay">Pay Now</button>
</template>
```

### 斯维尔特/斯维尔特基特

```typescript
<script lang="ts">
  import { loadPaystack } from "@alexasomba/paystack-inline";

  export let accessCode: string;

  async function handlePay() {
    const PaystackPop = await loadPaystack();
    const popup = new PaystackPop();
    popup.resumeTransaction(accessCode, {
      onSuccess: (res) => console.log(res.reference),
    });
  }
</script>

<button on:click={handlePay}>Pay Now</button>
```

* * *

## 类型脚本引用

所有出口类型均可直接进口:

```typescript
import type {
  PaystackPopGeneralOptions,
  PaystackPopCallbacks,
  PaystackPopNewTransactionOptions,
  PaystackPopCheckoutOptions,
  PaystackPopPaymentRequestOptions,
  PaystackPopSplitOptions,
  PaystackPopSubscriptionOptions,
  PaystackPopInstance,
  PopupTransaction,
  PopupTransactionStatus,
} from "@alexasomba/paystack-inline";
```

### `PopupTransactionStatus`

```typescript
interface PopupTransactionStatus {
  status: "null" | "error" | "abandoned" | "auth" | "failed" | "success" | "pending";
  id?: string;
  errors?: any[];
  response?: any;
  checkoutUrl?: string;
}
```

* * *

## 完整支付流程

```
┌─────────────────┐      POST /transaction/initialize      ┌─────────────────┐
│   Your Backend  │ ─────────────────────────────────────► │  Paystack API   │
│  (Secret Key)   │ ◄───────────────────────────────────── │                 │
└────────┬────────┘            { access_code }             └─────────────────┘
         │
         │  access_code
         ▼
┌─────────────────┐       loadPaystack() + resumeTransaction()
│   Your Frontend │ ─────────────────────────────────────► Paystack Popup UI
│  (Public Key)   │ ◄─────────────── onSuccess({ reference }) ──────────────
└────────┬────────┘
         │
         │  Verify reference on YOUR server (never trust client callbacks alone)
         ▼
┌─────────────────┐      GET /transaction/verify/:reference
│   Your Backend  │ ─────────────────────────────────────► Paystack API
│                 │ ◄─────────────── { status: "success" } ─────────────────
└─────────────────┘
         │
         │  Deliver value to customer ✅
```

* * *

## 安全说明

-   **不要在前端用你的密钥.** 只使用您的公钥( O)`pk_...`) (中文(简体) ).
-   **总是验证交易服务器侧** 在提供价值之前—— `onSuccess` 召回可以被欺骗.
-   脚本在 `https://js.paystack.co/v2/inline.js` 由Paystack的CDN装入HTTPS 并装有安全性头条.

* * *

## 相关资源

-   [Paystack Docs——接受付款](https://paystack.com/docs/payments/accept-payment/)
-   [Paystack Docs - 验证交易](https://paystack.com/docs/api/transaction/#verify)
-   [Paystack Docs — Webhooks (中文(简体) )](https://paystack.com/docs/payments/webhooks/)
-   [付费频道](https://paystack.com/docs/payments/payment-channels/)
-   [付费文件-订阅](https://paystack.com/docs/payments/subscriptions/)

* * *

## 来源

-   Monorepo 来源 : [阿列克萨松巴/帕斯塔克-波拿皮](https://github.com/alexasomba/paystack-openapi)
-   独立的 SDK repo : [https://github.com/alexasomba/paystack-inline 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/alexasomba/paystack-inline)

* * *

## 许可证

麻省理工学院 [亚历山大](https://github.com/alexasomba)

## 常见问题

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

Paystack Popup \(inline\.js\) 的强型,基于承诺的TypeScript包装器\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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