Libraries and SDKsNode.jsTransfers

Transfers

The Transfers module allows you to send money from your CashOnRails wallet to bank accounts, validate account details, and track transfer history.

Features

  • Transfer funds to bank accounts
  • Validate account details before transfers
  • Check wallet balance
  • Calculate transfer fees
  • View transfer history

Transfer to Bank Account

Send money from your CashOnRails wallet to a bank account:

const transfer = await client.transfer.toBank({
  account_number: "1234567890",
  account_name: "John Doe",
  bank_code: "000013",
  amount: "100",
  currency: "NGN",
  sender_name: "Your Business Name",
  narration: "Payment for services",
  reference: client.generateReference()
});
 
console.log('Transfer Status:', transfer.data.status);

Parameters

ParameterTypeRequiredDescription
account_numberstringYesRecipient’s account number
account_namestringYesRecipient’s account name
bank_codestringYesRecipient’s bank code
amountstringYesTransfer amount
currencystringYesTransfer currency
sender_namestringYesSender’s name
narrationstringYesTransfer narration
referencestringYesUnique transfer reference

Response

{
  status: "success",
  message: "Transfer initiated successfully",
  data: {
    reference: "TRF_1234567890",
    amount: "100",
    fee: "10",
    total_amount: "110",
    status: "processing", // or "successful", "failed", "pending"
    created_at: "2023-05-15T10:30:00Z",
    recipient: {
      account_name: "John Doe",
      account_number: "1234567890",
      bank_name: "First Bank"
    }
  }
}

Get Wallet Balance

Check your available wallet balance:

const balance = await client.transfer.getWalletBalance('NGN');
console.log('Available Balance:', balance.data.balance);

Parameters

ParameterTypeRequiredDescription
currencystringYesCurrency code (e.g., NGN)

Response

{
  status: "success",
  message: "Wallet balance retrieved",
  data: {
    balance: "10000.00",
    currency: "NGN",
    last_updated: "2023-05-15T10:30:00Z"
  }
}

Validate Account Name

Verify account details before making a transfer:

const accountInfo = await client.transfer.validateAccountName({
  account_number: "1234567890",
  bank_code: "000013",
  currency: "NGN"
});
 
console.log('Account Name:', accountInfo.data.account_name);

Parameters

ParameterTypeRequiredDescription
account_numberstringYesAccount number to validate
bank_codestringYesBank code
currencystringYesCurrency code

Response

{
  status: "success",
  message: "Account validated successfully",
  data: {
    account_number: "1234567890",
    account_name: "JOHN DOE",
    bank_code: "000013",
    bank_name: "First Bank of Nigeria"
  }
}

Get Transfer Fee

Calculate the fee for a transfer:

const fee = await client.transfer.getTransferFee({
  amount: "1000",
  currency: "NGN"
});
 
console.log('Transfer Fee:', fee.data.fee);

Parameters

ParameterTypeRequiredDescription
amountstringYesTransfer amount
currencystringYesCurrency code

Response

{
  status: "success",
  message: "Transfer fee calculated",
  data: {
    amount: "1000",
    fee: "10",
    total: "1010",
    currency: "NGN"
  }
}

Fetch Transfers History

Retrieve your transfer history with pagination support:

// Fetch transfers with pagination (page 1, 20 items per page)
const transfers = await client.transfer.fetchTransfers(1, 20);
console.log('Total Transfers:', transfers.pagination.total);
 
// Loop through transfers
transfers.data.forEach(transfer => {
  console.log(`Transfer ${transfer.reference}: ${transfer.status}`);
});

Parameters

ParameterTypeRequiredDefaultDescription
pagenumberNo1Page number
limitnumberNo10Items per page

Response

{
  status: "success",
  message: "Transfers retrieved successfully",
  data: [
    {
      reference: "TRF_1234567890",
      amount: "1000",
      fee: "10",
      status: "successful",
      created_at: "2023-05-15T10:30:00Z",
      recipient: {
        account_name: "John Doe",
        account_number: "1234567890",
        bank_name: "First Bank"
      }
    },
    // More transfers...
  ],
  pagination: {
    limit: 20,
    offset: 0,
    next_offset: 20,
    total: 150,
    total_pages: 8
  }
}

Get Bank List

Retrieve a list of available banks for transfers:

const banks = await client.transfer.bankList({
  currency: "NGN"
});
 
// Display the list of banks
banks.data.forEach(bank => {
  console.log(`${bank.name} (${bank.code})`);
});

Parameters

ParameterTypeRequiredDescription
currencystringYesCurrency code

Response

{
  status: "success",
  message: "Bank list retrieved successfully",
  data: [
    {
      code: "000013",
      name: "First Bank of Nigeria"
    },
    {
      code: "000014",
      name: "Guaranty Trust Bank"
    },
    // More banks...
  ]
}

Best Practices for Transfers

  1. Always validate account details before initiating transfers
  2. Check wallet balance to ensure sufficient funds
  3. Generate unique references for each transfer
  4. Store transfer references in your database
  5. Handle transfer failures gracefully
  6. Implement proper error handling for all transfer operations

Error Handling for Transfers

try {
  const transfer = await client.transfer.toBank({
    // Transfer details
  });
  
  // Process successful transfer
  console.log('Transfer initiated:', transfer.data.reference);
} catch (error) {
  // Handle transfer errors
  console.error('Transfer failed:', error.message);
  
  if (error.code === 'INSUFFICIENT_FUNDS') {
    console.error('Not enough funds in wallet');
  } else if (error.code === 'INVALID_ACCOUNT') {
    console.error('Invalid account details');
  }
}

For more details on error handling, see the Error Handling documentation.

Related Resources

Payment ServicesReserved Accounts