paystack-transfer-recipients

Paystack 转账收款人

转账收款人 API 可用于创建和管理通过转账收款的受益人。发起转账前，必须先创建收款人。

依赖：paystackRequest 辅助函数需要 paystack-setup。
相关：paystack-transfers 用于向收款人转账。

端点

方法	端点	说明
POST	/transferrecipient	创建收款人
POST	/transferrecipient/bulk	批量创建收款人
GET	/transferrecipient	列出收款人
GET	/transferrecipient/:id_or_code	获取收款人信息
PUT	/transferrecipient/:id_or_code	更新收款人
DELETE	/transferrecipient/:id_or_code	删除（停用）收款人

收款人类型

类型	说明	国家/地区
nuban	尼日利亚银行账户（NUBAN）	尼日利亚
ghipss	加纳银行间支付与结算	加纳
mobile_money	移动支付钱包	加纳、肯尼亚
basa	南非银行账户	南非
authorization	使用之前的扣款授权	全部

创建转账收款人

POST /transferrecipient

如果账户号码重复，API 会返回已有记录，而不是创建新记录。

参数	类型	必填	说明
type	string	是	nuban、ghipss、mobile_money 或 basa
name	string	是	收款人姓名（与账户登记姓名一致）
account_number	string	是*	银行账户号码/手机号码（* authorization 类型不需要）
bank_code	string	是*	来自银行列表端点的银行代码（* authorization 类型不需要）
description	string	否	此收款人的说明
currency	string	否	货币代码（例如 NGN、GHS、ZAR）
authorization_code	string	否	之前交易的授权码
metadata	object	否	附加结构化数据

尼日利亚银行账户（NUBAN）

const recipient = await paystackRequest<{
  recipient_code: string;
  name: string;
  type: string;
}>("/transferrecipient", {
  method: "POST",
  body: JSON.stringify({
    type: "nuban",
    name: "Tolu Robert",
    account_number: "0123456789",
    bank_code: "058",    // GTBank — get codes from List Banks endpoint
    currency: "NGN",
  }),
});
// recipient.data.recipient_code → "RCP_m7ljkv8leesep7p"

加纳银行账户（GHIPSS）

await paystackRequest("/transferrecipient", {
  method: "POST",
  body: JSON.stringify({
    type: "ghipss",
    name: "Kwame Asante",
    account_number: "0551234987",
    bank_code: "GH010100",
    currency: "GHS",
  }),
});

移动支付

await paystackRequest("/transferrecipient", {
  method: "POST",
  body: JSON.stringify({
    type: "mobile_money",
    name: "Ama Serwah",
    account_number: "0551234987",
    bank_code: "MTN",      // Mobile money provider code
    currency: "GHS",
  }),
});

基于授权的收款人

await paystackRequest("/transferrecipient", {
  method: "POST",
  body: JSON.stringify({
    type: "authorization",
    name: "Customer Refund",
    authorization_code: "AUTH_ekk8t49ogj",
  }),
});

批量创建转账收款人

POST /transferrecipient/bulk

参数	类型	必填	说明
batch	array	是	收款人对象数组（参数与创建收款人时相同）

const result = await paystackRequest("/transferrecipient/bulk", {
  method: "POST",
  body: JSON.stringify({
    batch: [
      {
        type: "nuban",
        name: "Habenero Mundane",
        account_number: "0123456789",
        bank_code: "033",
        currency: "NGN",
      },
      {
        type: "nuban",
        name: "Soft Merry",
        account_number: "9876543210",
        bank_code: "50211",
        currency: "NGN",
      },
    ],
  }),
});
// result.data.success[] — successfully created recipients
// result.data.errors[] — failed recipients

列出转账收款人

GET /transferrecipient

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

const recipients = await paystackRequest("/transferrecipient?perPage=20&page=1");

获取转账收款人信息

GET /transferrecipient/:id_or_code

const recipient = await paystackRequest(
  `/transferrecipient/${encodeURIComponent("RCP_m7ljkv8leesep7p")}`
);

更新转账收款人

PUT /transferrecipient/:id_or_code

参数	类型	必填	说明
name	string	是	更新后的收款人姓名
email	string	否	更新后的收款人邮箱

await paystackRequest(
  `/transferrecipient/${encodeURIComponent("RCP_m7ljkv8leesep7p")}`,
  {
    method: "PUT",
    body: JSON.stringify({ name: "Rick Sanchez" }),
  }
);

删除转账收款人

DELETE /transferrecipient/:id_or_code

将收款人设为非活跃状态（软删除）。

await paystackRequest(
  `/transferrecipient/${encodeURIComponent("RCP_m7ljkv8leesep7p")}`,
  { method: "DELETE" }
);