paystack-transfer-recipients

Paystack Transfer Recipients

The Transfer Recipients API lets you create and manage beneficiaries that receive money via transfers. You must create a recipient before initiating a transfer.

Depends on: paystack-setup for the paystackRequest helper.
Related: paystack-transfers for sending money to recipients.

Endpoints

Method	Endpoint	Description
POST	/transferrecipient	Create a recipient
POST	/transferrecipient/bulk	Bulk create recipients
GET	/transferrecipient	List recipients
GET	/transferrecipient/:id_or_code	Fetch a recipient
PUT	/transferrecipient/:id_or_code	Update a recipient
DELETE	/transferrecipient/:id_or_code	Delete (deactivate) a recipient

Recipient Types

Type	Description	Countries
nuban	Nigerian bank accounts (NUBAN)	Nigeria
ghipss	Ghana Interbank Payment & Settlement	Ghana
mobile_money	Mobile money wallets	Ghana, Kenya
basa	South African bank accounts	South Africa
authorization	Use a previous charge authorization	All

Create Transfer Recipient

POST /transferrecipient

A duplicate account number returns the existing record instead of creating a new one.

Param	Type	Required	Description
type	string	Yes	nuban, ghipss, mobile_money, or basa
name	string	Yes	Recipient name (as registered on their account)
account_number	string	Yes*	Bank account / mobile number (* Not required for authorization type)
bank_code	string	Yes*	Bank code from List Banks endpoint (* Not required for authorization type)
description	string	No	Description for this recipient
currency	string	No	Currency code (e.g. NGN, GHS, ZAR)
authorization_code	string	No	Auth code from a previous transaction
metadata	object	No	Additional structured data

Nigerian Bank Account (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"

Ghana Bank Account (GHIPSS)

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

Mobile Money

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",
  }),
});

Authorization-Based

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

Bulk Create Transfer Recipients

POST /transferrecipient/bulk

Param	Type	Required	Description
batch	array	Yes	Array of recipient objects (same params as Create)

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

List Transfer Recipients

GET /transferrecipient

Param	Type	Required	Description
perPage	integer	No	Records per page (default: 50)
page	integer	No	Page number (default: 1)
from	datetime	No	Start date
to	datetime	No	End date

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

Fetch Transfer Recipient

GET /transferrecipient/:id_or_code

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

Update Transfer Recipient

PUT /transferrecipient/:id_or_code

Param	Type	Required	Description
name	string	Yes	Updated recipient name
email	string	No	Updated recipient email

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

Delete Transfer Recipient

DELETE /transferrecipient/:id_or_code

Sets the recipient to inactive (soft delete).

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