rexedge/paystack-transfers

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