paystack-transactions

Paystack Transactions

Transactions API 可让你在集成中创建和管理付款，涵盖从初始化到验证的整个交易生命周期。

依赖：paystack-setup，用于提供 paystackRequest 辅助函数和环境配置。

Transaction Lifecycle

Initialize (server) → Complete (client/redirect) → Verify (server) + Webhook

Endpoints

Method	Endpoint	Description
POST	/transaction/initialize	初始化交易
GET	/transaction/verify/:reference	验证交易
GET	/transaction	列出交易
GET	/transaction/:id	获取交易
POST	/transaction/charge_authorization	使用已保存的授权扣款
GET	/transaction/timeline/:id_or_reference	查看交易时间线
GET	/transaction/totals	获取交易总额
GET	/transaction/export	将交易导出为 CSV
POST	/transaction/partial_debit	对授权进行部分扣款

Initialize Transaction

POST /transaction/initialize

创建付款，并返回 authorization_url（用于重定向）和 access_code（用于 Popup/InlineJS）。

Parameters (Body)

Param	Type	Required	Description
amount	string	是	以最小单位（kobo）表示的金额。"50000" = NGN 500
email	string	是	客户的电子邮件地址
reference	string	否	唯一引用。仅限字母数字字符和 - . =
currency	string	否	NGN、USD、GHS、ZAR、KES。默认为集成所用货币
callback_url	string	否	覆盖控制面板中的回调 URL
channels	array	否	["card","bank","ussd","qr","mobile_money","bank_transfer","eft","apple_pay"]
plan	string	否	基于订阅的付款所用的计划代码
invoice_limit	integer	否	订阅的最大扣款次数
metadata	string	否	包含 custom_fields 数组的字符串化 JSON
subaccount	string	否	子账户代码，例如 ACCT_8f4s1eq7ml6rlzj
split_code	string	否	分账代码，例如 SPL_98WF13Eb3w
transaction_charge	integer	否	分账的固定费用覆盖值（以最小单位表示）
bearer	string	否	"account" 或 "subaccount" — 由谁支付 Paystack 费用

Response

{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/3ni8kdavz62431k",
    "access_code": "3ni8kdavz62431k",
    "reference": "re4lyvq3s3"
  }
}

Server Action Example (Next.js)

"use server";
import { paystackRequest } from "@/lib/paystack";

export async function initializePayment(email: string, amountInNaira: number) {
  const result = await paystackRequest<{
    authorization_url: string;
    access_code: string;
    reference: string;
  }>("/transaction/initialize", {
    method: "POST",
    body: JSON.stringify({
      email,
      amount: Math.round(amountInNaira * 100).toString(),
      callback_url: `${process.env.NEXT_PUBLIC_APP_URL}/payment/callback`,
    }),
  });
  return result.data;
}

Client-Side Popup (InlineJS)

"use client";
import PaystackInline from "@paystack/inline-js";

function PayButton({ email, amount }: { email: string; amount: number }) {
  const handlePay = async () => {
    // 1. Initialize on server
    const { access_code } = await initializePayment(email, amount);

    // 2. Open Popup with access_code
    const popup = new PaystackInline();
    popup.openIframe({
      accessCode: access_code,
      onSuccess: (response) => {
        // 3. Verify on server — NEVER trust this alone
        verifyTransaction(response.reference);
      },
      onClose: () => console.log("Payment window closed"),
    });
  };

  return <button onClick={handlePay}>Pay ₦{amount}</button>;
}

Redirect Method

初始化后，将用户重定向到 authorization_url。Paystack 会将用户重定向回你的 callback_url，并在查询字符串中附上 ?trxref=REFERENCE&reference=REFERENCE。请立即在服务器端进行验证。

// app/payment/callback/page.tsx
import { paystackRequest } from "@/lib/paystack";

export default async function PaymentCallback({
  searchParams,
}: {
  searchParams: Promise<{ reference?: string }>;
}) {
  const { reference } = await searchParams;
  if (!reference) return <p>No reference provided</p>;

  const result = await paystackRequest<{ status: string; amount: number }>(
    `/transaction/verify/${encodeURIComponent(reference)}`
  );

  if (result.data.status === "success") {
    return <p>Payment successful!</p>;
  }
  return <p>Payment failed: {result.data.status}</p>;
}

Verify Transaction

GET /transaction/verify/:reference

付款后务必在服务器端进行验证。reference 位于回调 URL 的查询参数中，或由 Popup 的 onSuccess 返回。

const result = await paystackRequest<{
  id: number;
  status: "success" | "failed" | "abandoned";
  reference: string;
  amount: number;
  currency: string;
  channel: string;
  paid_at: string;
  authorization: {
    authorization_code: string;
    reusable: boolean;
    card_type: string;
    last4: string;
    bank: string;
  };
  customer: { email: string; id: number };
}>(`/transaction/verify/${encodeURIComponent(reference)}`);

检查 result.data.status === "success"，并确认 result.data.amount 与预期金额相符，然后再完成订单。

List Transactions

GET /transaction

Query Parameters

Param	Type	Description
perPage	integer	每页记录数（默认值为 50）
page	integer	页码（默认值为 1）
customer	integer	按客户 ID 筛选
terminalid	string	按 Terminal ID 筛选
status	string	"success"、"failed" 或 "abandoned"
from	datetime	开始日期，例如 2024-01-01T00:00:00.000Z
to	datetime	结束日期
amount	integer	按金额筛选（以最小单位表示）

const params = new URLSearchParams({ status: "success", perPage: "20" });
const result = await paystackRequest<Transaction[]>(`/transaction?${params}`);

Fetch Transaction

GET /transaction/:id

按数字 ID 获取单笔交易。

const result = await paystackRequest<Transaction>(`/transaction/${transactionId}`);

收费授权

POST /transaction/charge_authorization

向客户之前保存的卡片收费（其中 authorization.reusable === true）。

参数	类型	必填	说明
amount	字符串	是	以子单位表示的金额
email	字符串	是	客户的邮箱
authorization_code	字符串	是	例如 AUTH_72btv547
reference	字符串	否	唯一交易引用
currency	字符串	否	货币代码
queue	布尔值	否	定时／批量收费时设为 true

const result = await paystackRequest<Transaction>(
  "/transaction/charge_authorization",
  {
    method: "POST",
    body: JSON.stringify({
      authorization_code: "AUTH_72btv547",
      email: "[email protected]",
      amount: "20000",
    }),
  }
);

交易时间线

GET /transaction/timeline/:id_or_reference

返回交易的逐步历史记录（尝试的付款方式、成功／失败状态、耗时）。

const result = await paystackRequest<{
  start_time: number;
  time_spent: number;
  attempts: number;
  errors: number;
  success: boolean;
  history: Array<{ type: string; message: string; time: number }>;
}>(`/transaction/timeline/${reference}`);

交易总额

GET /transaction/totals

返回汇总交易量和笔数。支持 from、to、perPage、page 查询参数。

const result = await paystackRequest<{
  total_transactions: number;
  total_volume: number;
  total_volume_by_currency: Array<{ currency: string; amount: number }>;
  pending_transfers: number;
}>("/transaction/totals");

导出交易

GET /transaction/export

返回 CSV 下载链接。支持所有列表筛选条件，以及 settled、settlement、payment_page。

const params = new URLSearchParams({ from: "2024-01-01", status: "success" });
const result = await paystackRequest<{ path: string }>(
  `/transaction/export?${params}`
);
// result.data.path is a time-limited S3 URL to the CSV

部分扣款

POST /transaction/partial_debit

从客户授权下的可用余额中扣除部分金额。适用于按用量计费。

参数	类型	必填	说明
authorization_code	字符串	是	之前交易中的授权码
currency	字符串	是	NGN 或 GHS
amount	字符串	是	以子单位表示的金额
email	字符串	是	与授权码关联的客户邮箱
reference	字符串	否	唯一引用
at_least	字符串	否	全额扣款失败时要收取的最低金额

const result = await paystackRequest<Transaction>(
  "/transaction/partial_debit",
  {
    method: "POST",
    body: JSON.stringify({
      authorization_code: "AUTH_72btv547",
      currency: "NGN",
      amount: "20000",
      email: "[email protected]",
      at_least: "10000",
    }),
  }
);

重要说明

• 交易 ID 是无符号 64 位整数——在 TypeScript 中应存储为 string，以避免精度损失
• 付款后始终在服务端验证——切勿仅信任客户端回调
• 金额验证：验证后始终确认 result.data.amount 与预期金额一致
• 如果 authorization.reusable === true，可以保存成功交易返回的 authorization_code，以供日后收费使用
• 元数据支持用于控制面板显示的 custom_fields——发送前请将 JSON 字符串化