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
helper.
Related:
paystack-transfer-recipients for creating recipients before transfers.
Returns status
if OTP is disabled on your account, or
if OTP is required.
typescript
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"
Required when transfer status is
. Submit the OTP sent to your business phone.
Batch multiple transfers in a single request. OTP must be disabled on your account to use this endpoint.
typescript
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."
Verify the status of a transfer using its reference.
typescript
// 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