Paystack Transfers

The Transfers API lets you send money from your Paystack balance to bank accounts and mobile wallets. Transfers require a pre-created transfer recipient.

Depends on: paystack-setup for the paystackRequest helper.
Related: paystack-transfer-recipients for creating recipients before transfers.

Endpoints

Method	Endpoint	Description
POST	`/transfer`	Initiate a transfer
POST	`/transfer/finalize_transfer`	Finalize transfer (OTP)
POST	`/transfer/bulk`	Initiate bulk transfer
GET	`/transfer`	List transfers
GET	`/transfer/:id_or_code`	Fetch a transfer
GET	`/transfer/verify/:reference`	Verify a transfer

Initiate Transfer

POST /transfer

Returns status pending if OTP is disabled on your account, or otp if OTP is required.

Param	Type	Required	Description
`source`	string	Yes	`balance` (only option)
`amount`	integer	Yes	Amount in subunits (kobo/pesewas)
`recipient`	string	Yes	Recipient code (e.g. `RCP_gd9vgag7n5lr5ix`)
`reference`	string	Yes	Unique identifier (16-50 chars, lowercase a-z, 0-9, `-`, `_`)
`reason`	string	No	Reason for transfer (shows in customer's credit notification)
`currency`	string	No	Currency code (defaults to `NGN`)
`account_reference`	string	No	Required in Kenya for MPESA Paybill and Till transfers

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"

Finalize Transfer

POST /transfer/finalize_transfer

Required when transfer status is otp. Submit the OTP sent to your business phone.

Param	Type	Required	Description
`transfer_code`	string	Yes	Transfer code from initiate response
`otp`	string	Yes	OTP sent to business phone

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

Initiate Bulk Transfer

POST /transfer/bulk

Batch multiple transfers in a single request. OTP must be disabled on your account to use this endpoint.

Param	Type	Required	Description
`source`	string	Yes	`balance`
`transfers`	array	Yes	Array of transfer objects

Each transfer object:

Param	Type	Required	Description
`amount`	integer	Yes	Amount in subunits
`recipient`	string	Yes	Recipient code
`reference`	string	Yes	Unique reference (16-50 chars)
`reason`	string	No	Transfer reason

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

List Transfers

GET /transfer

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

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

Fetch Transfer

GET /transfer/:id_or_code

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

Verify Transfer

GET /transfer/verify/:reference

Verify the status of a transfer using its reference.

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

Transfer Flow

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

Important Notes

You can only transfer from balance — ensure your Paystack balance has sufficient funds
Bulk transfers require OTP to be disabled (Dashboard → Settings → Preferences)
Transfer references must be unique, 16-50 characters, lowercase with - and _ only
For Kenya MPESA Paybill/Till, include account_reference in the transfer
Always verify transfer status via webhook (transfer.success, transfer.failed) rather than polling