paystack-transfers

Paystack 转账

Transfers API 可让你将 Paystack 余额中的资金转入银行账户和移动钱包。转账需要预先创建转账收款人。

依赖：用于提供 paystackRequest 助手的 paystack-setup。
相关：用于在转账前创建收款人的 paystack-transfer-recipients。

端点

方法	端点	说明
POST	/transfer	发起转账
POST	/transfer/finalize_transfer	完成转账（OTP）
POST	/transfer/bulk	发起批量转账
GET	/transfer	列出转账
GET	/transfer/:id_or_code	获取转账信息
GET	/transfer/verify/:reference	验证转账

发起转账

POST /transfer

如果你的账户已停用 OTP，将返回状态 pending；如果需要 OTP，则返回 otp。

参数	类型	必填	说明
source	string	是	balance（唯一选项）
amount	integer	是	以最小货币单位表示的金额（kobo/pesewas）
recipient	string	是	收款人代码（例如 RCP_gd9vgag7n5lr5ix）
reference	string	是	唯一标识符（16-50 个字符，仅限小写 a-z、0-9、-、_）
reason	string	否	转账原因（会显示在客户的入账通知中）
currency	string	否	货币代码（默认为 NGN）
account_reference	string	否	在肯尼亚使用 MPESA Paybill 和 Till 转账时必填

const transfer = await paystackRequest<{
  transfer_code: string;
  status: string;
  reference: string;
  amount: number;
}>("/transfer", {
  method: "POST",
  body: JSON.stringify({
    source: "balance",
    amount: 100000,          // ₦1,000
    recipient: "RCP_gd9vgag7n5lr5ix",
    reference: `txf_${crypto.randomUUID()}`,
    reason: "Vendor payment for January",
  }),
});
// transfer.data.status → "pending" or "otp"
// transfer.data.transfer_code → "TRF_v5tip3zx8nna9o78"

完成转账

POST /transfer/finalize_transfer

当转账状态为 otp 时必须调用。提交发送到你商用手机的 OTP。

参数	类型	必填	说明
transfer_code	string	是	发起转账响应中返回的转账代码
otp	string	是	发送到商用手机的 OTP

await paystackRequest("/transfer/finalize_transfer", {
  method: "POST",
  body: JSON.stringify({
    transfer_code: "TRF_v5tip3zx8nna9o78",
    otp: "928783",
  }),
});

发起批量转账

POST /transfer/bulk

通过单个请求批量处理多笔转账。使用此端点时，账户必须停用 OTP。

参数	类型	必填	说明
source	string	是	balance
transfers	array	是	转账对象数组

每个转账对象：

参数	类型	必填	说明
amount	integer	是	以最小货币单位表示的金额
recipient	string	是	收款人代码
reference	string	是	唯一引用（16-50 个字符）
reason	string	否	转账原因

const result = await paystackRequest("/transfer/bulk", {
  method: "POST",
  body: JSON.stringify({
    source: "balance",
    currency: "NGN",
    transfers: [
      {
        amount: 20000,
        recipient: "RCP_gd9vgag7n5lr5ix",
        reference: `txf_${crypto.randomUUID()}`,
        reason: "Bonus for the week",
      },
      {
        amount: 35000,
        recipient: "RCP_m7ljkv8leesep7p",
        reference: `txf_${crypto.randomUUID()}`,
        reason: "January salary",
      },
    ],
  }),
});
// result.message → "2 transfers queued."

列出转账

GET /transfer

参数	类型	必填	说明
perPage	integer	否	每页记录数（默认值：50）
page	integer	否	页码（默认值：1）
recipient	integer	否	按收款人 ID 筛选
from	datetime	否	开始日期
to	datetime	否	结束日期

const transfers = await paystackRequest("/transfer?perPage=20&page=1");

获取转账信息

GET /transfer/:id_or_code

const transfer = await paystackRequest(
  `/transfer/${encodeURIComponent("TRF_v5tip3zx8nna9o78")}`
);

验证转账

GET /transfer/verify/:reference

使用转账引用验证转账状态。

const result = await paystackRequest(
  `/transfer/verify/${encodeURIComponent(reference)}`
);
// result.data.status → "success" | "failed" | "pending" | "reversed"

转账流程

// 1. Create recipient (see paystack-transfer-recipients skill)
// 2. Initiate transfer
const transfer = await paystackRequest("/transfer", {
  method: "POST",
  body: JSON.stringify({
    source: "balance",
    amount: 500000,
    recipient: "RCP_gd9vgag7n5lr5ix",
    reference: `txf_${crypto.randomUUID()}`,
  }),
});

// 3. If OTP required, finalize
if (transfer.data.status === "otp") {
  const otp = await getOTPFromUser();
  await paystackRequest("/transfer/finalize_transfer", {
    method: "POST",
    body: JSON.stringify({
      transfer_code: transfer.data.transfer_code,
      otp,
    }),
  });
}

// 4. Listen for webhooks: transfer.success, transfer.failed, transfer.reversed

重要说明

• 你只能从 balance 转账，请确保 Paystack 余额充足
• 批量转账要求停用 OTP（Dashboard → Settings → Preferences）
• 转账引用必须唯一，长度为 16-50 个字符，且只能使用小写字母以及 - 和 _
• 在肯尼亚使用 MPESA Paybill/Till 转账时，请在转账中填写 account_reference
• 务必通过 webhook（transfer.success、transfer.failed）验证转账状态，而不要轮询