@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 - 任何前端

安装

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

代理技能

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

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 到前端:

curl https://api.paystack.co/transaction/initialize \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "amount": "500000" }' \
  -X POST

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

2. 在浏览器中恢复交易

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从不提供完全基于客户调回的值——与 验证交易 终点.

API 参考

loadPaystack()

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

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

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

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

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

popup.resumeTransaction(accessCode, callbacks?)

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

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

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

核心选项

客户选项

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

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

const open = popup.preloadTransaction({
  key: "pk_test_xxxxxxx",
  email: "[email protected]",
  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 弹出时的对象.

const transaction = await popup.checkout({
  key: "pk_test_xxxxxxx",
  email: "[email protected]",
  amount: 200000,
  onSuccess: (res) => console.log(res),
});

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

popup.cancelTransaction(idOrTransaction)

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

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

popup.paymentRequest(options) → Promise<PopupTransaction>

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

const payment = await popup.paymentRequest({
  key: "pk_test_xxxxxxx",
  email: "[email protected]",
  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 选项

回电

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

订阅

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

popup.newTransaction({
  key: "pk_test_xxxxxxx",
  email: "[email protected]",
  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),
});

订阅选项

分期付款

分账户付款的路由:

popup.newTransaction({
  key: "pk_test_xxxxxxx",
  email: "[email protected]",
  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),
});

拆分选项

框架实例

反应

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路由器) (英语)

"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组

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

斯维尔特/斯维尔特基特

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

类型脚本引用

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

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

PopupTransactionStatus

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——接受付款
• Paystack Docs - 验证交易
• Paystack Docs — Webhooks (中文(简体) )
• 付费频道
• 付费文件-订阅

来源

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

许可证

麻省理工学院 亚历山大