Transfer

Overview

The Transfer class provides methods for interacting with Paystack’s Transfer API. This module allows you to initiate single and bulk transfers, finalize transfers with OTP, list transfers, and verify transfer status.

Methods

initiate

Initiates a transfer to a recipient.

async initiate(input: TransferInitiateInput): Promise<TransferInitiateSuccess | TransferError>

TransferInitiateInput

required

The transfer details.

Show properties

'balance'

Source of funds (defaults to ‘balance’)

number

required

Amount to transfer in kobo/cents (minimum: 1000)

string

required

Recipient code (must start with RCP_)

string

Reason for the transfer

'NGN' | 'USD' | 'GHS' | 'ZAR' | 'KES' | 'XOF'

Currency code (defaults to NGN)

string

required

Unique transfer reference

string

Optional account reference

object

Show properties

string

Domain type

number

Transfer amount

string

Currency code

string

Transfer reference

string

Source of funds

string

Transfer reason

string

Transfer status (pending, success, failed, etc.)

string

Unique transfer code (starts with TRF_)

number

Transfer ID

number

Integration ID

number

Recipient ID

string

ISO datetime when transfer was created

Example Usage:

const { data, error } = await paystack.transfer.initiate({
  source: "balance",
  amount: 50000,
  recipient: "RCP_recipient123",
  reason: "Payment for services",
  reference: "unique-transfer-ref-123",
});

if (error) {
  // Check if OTP is required
  if (error.meta?.nextStep === "send_otp") {
    console.log("OTP required. Check your phone for OTP.");
  } else {
    console.error("Transfer failed:", error);
  }
} else {
  console.log("Transfer initiated:", data.transfer_code);
}

finalize

Finalizes a transfer with an OTP.

async finalize(input: TransferFinalizeInput): Promise<TransferFinalizeSuccess | GenericError>

TransferFinalizeInput

required

The transfer finalization details.

Show properties

string

required

Transfer code from the initiate response (must start with TRF_)

string

required

One-Time Password sent to your phone

object

Show properties

string

Domain type

number

Transfer amount

string

Currency code

string

Transfer reference

string

Transfer status

string

Transfer code

number

Transfer ID

unknown

Source details

Example Usage:

const { data, error } = await paystack.transfer.finalize({
  transfer_code: "TRF_code123",
  otp: "123456",
});

if (error) {
  console.error("Finalization failed:", error);
} else {
  console.log("Transfer finalized:", data.status);
}

initiateBulk

Initiates a bulk transfer to multiple recipients.

async initiateBulk(input: TransferBulkInitiateInput): Promise<TransferBulkInitiateSuccess | TransferError>

TransferBulkInitiateInput

required

The bulk transfer details.

Show properties

'balance'

Source of funds (defaults to ‘balance’)

array

required

Array of transfer objects

Show transfer object

number

required

Amount to transfer

string

required

Recipient code (must start with RCP_)

string

required

Unique reference for this transfer

string

Reason for the transfer

array

Array of transfer result objects

Show transfer result

string

Transfer reference

string

Recipient code

number

Transfer amount

string

Unique transfer code

string

Currency code

string

Transfer status

Example Usage:

const { data, error } = await paystack.transfer.initiateBulk({
  source: "balance",
  transfers: [
    {
      amount: 50000,
      recipient: "RCP_recipient1",
      reference: "bulk-transfer-ref-1",
      reason: "Payment 1",
    },
    {
      amount: 75000,
      recipient: "RCP_recipient2",
      reference: "bulk-transfer-ref-2",
      reason: "Payment 2",
    },
  ],
});

if (error) {
  console.error("Bulk transfer failed:", error);
} else {
  console.log(`Initiated ${data.length} transfers`);
}

list

Lists transfers made on your integration.

async list(input: TransferListInput): Promise<TransferListSuccess | GenericError>

TransferListInput

required

Query parameters for listing transfers.

Show properties

number

Number of records to fetch per page (defaults to 50)

number

Page number to retrieve (defaults to 1)

string

Start date for date range filter (ISO datetime)

string

End date for date range filter (ISO datetime)

string

Filter by recipient code (must start with RCP_)

array

Array of transfer objects

Show transfer object

number

Transfer amount

string

Currency code

string

Transfer reference

string

Transfer status

string

Transfer code

object

Recipient details including name, account details, and bank information

string

ISO datetime when transfer was created

Example Usage:

const { data, error } = await paystack.transfer.list({
  perPage: 50,
  page: 1,
});

if (error) {
  console.error("Failed to list transfers:", error);
} else {
  console.log(`Found ${data.length} transfers`);
}

getTransferById

Retrieves a single transfer by ID or code.

async getTransferById(id_or_code: string): Promise<TransferSingleSuccess | GenericError>

string

required

The ID or code of the transfer

object

Show properties

string

Domain type

number

Transfer amount

string

Currency code

string

Transfer reference

string

Transfer reason

string

Transfer status

string

Transfer code

number

Transfer ID

object

Complete recipient details including bank information

object

Session details for the transfer

number

Fees charged for the transfer

string

ISO datetime when transfer was created

string

ISO datetime when transfer was last updated

Example Usage:

const { data, error } = await paystack.transfer.getTransferById("TRF_code123");

if (error) {
  console.error("Failed to fetch transfer:", error);
} else {
  console.log("Transfer details:", data);
}

verify

Verifies the status of a transfer using its reference.

async verify(reference: string): Promise<TransferSingleSuccess | GenericError>

string

required

The reference of the transfer to verify

object

Complete transfer object with all details (same structure as getTransferById response)

Example Usage:

const { data, error } = await paystack.transfer.verify("transfer-ref-123");

if (error) {
  console.error("Verification failed:", error);
} else if (data.status === "success") {
  console.log("Transfer completed successfully");
} else {
  console.log(`Transfer status: ${data.status}`);
}

Transfer Flow

Here’s a typical flow for initiating and completing a transfer:

// Step 1: Initiate the transfer
const { data: initData, error: initError } = await paystack.transfer.initiate({
  source: "balance",
  amount: 50000,
  recipient: "RCP_recipient123",
  reason: "Payment for services",
  reference: `transfer-${Date.now()}`,
});

if (initError) {
  // Check if OTP is required
  if (initError.meta?.nextStep === "send_otp") {
    console.log("OTP has been sent to your phone");
    
    // Step 2: Get OTP from user (e.g., from input field)
    const otp = await getUserOTP(); // Your implementation
    
    // Step 3: Finalize with OTP
    const { data: finalData, error: finalError } = await paystack.transfer.finalize({
      transfer_code: initData.transfer_code,
      otp: otp,
    });
    
    if (finalError) {
      console.error("Transfer finalization failed:", finalError);
    } else {
      console.log("Transfer completed:", finalData);
    }
  } else {
    console.error("Transfer failed:", initError);
  }
} else {
  // Transfer completed without OTP requirement
  console.log("Transfer successful:", initData);
}

Core

Modules

Overview

Methods

initiate

finalize

initiateBulk

list

getTransferById

verify

Transfer Flow

​Overview

​Methods

​initiate

​finalize

​initiateBulk

​list

​getTransferById

​verify

​Transfer Flow

​Related Guides

Overview

Methods

initiate

finalize

initiateBulk

list

getTransferById

verify

Transfer Flow

Related Guides