Overview

The Wallet Services provides a comprehensive set of services for managing wallets, checking balances, transferring funds, and tracking transactions. Included services:

Account — view wallet info and create virtual accounts
Deposit — fund Naira wallet via multiple channels
Payout — send Naira to bank accounts or other Monei users
Utility — look up banks and verify account numbers

All services require a properly configured MoneiClient instance.

Account Service

monei.account provides methods to view wallet balances and create virtual bank accounts for deposits.

Get Wallet Info

// Optionally scope to a specific EVM chain
const wallet = await monei.account.me(56); // BSC chain ID
console.log(wallet.balance, wallet.address);

Create Virtual Account

Virtual accounts give users a dedicated Nigerian bank account number to fund their Naira wallet.

const account = await monei.account.createVirtualAccount({
  subWalletId: 'sub-wallet-id',
});

console.log(account.accountNumber); // e.g. "0123456789"
console.log(account.bankName);      // e.g. "Wema Bank"

Deposit Service

monei.deposit provides methods to fund the Naira wallet via multiple channels.

Initialize a Deposit

import { DEPOSIT_METHOD } from 'monei-sdk';

const deposit = await monei.deposit.initialize(
  DEPOSIT_METHOD.BANK_TRANSFER,
  {
    amount: 5000,          // Amount in kobo
    currency: 'NGN',
    subWalletId: 'sub-wallet-id',
  }
);

console.log(deposit.reference, deposit.paymentUrl);

Deposit with Saved Payment Method

const deposit = await monei.deposit.withPaymentMethod({
  amount: 5000,
  currency: 'NGN',
  paymentMethodId: 'pm-id',
  subWalletId: 'sub-wallet-id',
});

console.log(deposit.reference, deposit.status);

Authorize a Deposit (OTP / 3DS)

await monei.deposit.authorize({
  reference: deposit.reference,
  otp: '123456',
});

Generate a Payment Link

Share a payment link so anyone can fund your wallet without an account.

const link = await monei.deposit.generatePaymentLink({
  amount: 10000,
  currency: 'NGN',
  description: 'Invoice #42',
  subWalletId: 'sub-wallet-id',
});

console.log(link.url);

Check Deposit Status

const status = await monei.deposit.getStatus(deposit.reference);
console.log(status.status); // "pending" | "successful" | "failed"

Payout Service

monei.payout provides methods to send Naira to bank accounts or other Monei users.

Bank Transfer

const transfer = await monei.payout.bankTransfer({
  amount: 5000,
  bankCode: 'GTBINGLA',
  accountNumber: '0123456789',
  accountName: 'John Doe',
  narration: 'Payment for services',
  subWalletId: 'sub-wallet-id',
});

console.log(transfer.reference, transfer.status);

Peer Transfer (Monei-to-Monei)

Send funds instantly to another Monei user’s wallet — zero fees, instant settlement.

const transfer = await monei.payout.peerTransfer({
  amount: 2000,
  recipientTag: '@john',   // or email / user ID
  narration: 'Lunch split',
  subWalletId: 'sub-wallet-id',
});

console.log(transfer.reference, transfer.status);

Wallet Utility Service

monei.utility provides methods to look up banks and verify account numbers before sending.

Get All Banks

const { banks } = await monei.utility.getBanks();
banks.forEach(b => console.log(b.name, b.code));

Verify Bank Account

Always call this before a bank transfer to confirm the account name matches.

const verified = await monei.utility.verifyBankAccount({
  accountNumber: '0123456789',
  bankCode: 'GTBINGLA',
});

console.log(verified.accountName); // "JOHN ADEWALE DOE"

Working with Response Objects

All methods return objects with property access:

// Account response
const wallet = await monei.account.me(56);
console.log(wallet.balance);      // Wallet balance
console.log(wallet.address);      // Wallet address
console.log(wallet.currency);     // Currency code

// Virtual account response
const account = await monei.account.createVirtualAccount({...});
console.log(account.accountNumber);  // Virtual account number
console.log(account.bankName);       // Bank name
console.log(account.accountName);    // Account holder name

// Deposit response
const deposit = await monei.deposit.initialize(...);
console.log(deposit.reference);   // Deposit reference
console.log(deposit.paymentUrl);  // Payment URL
console.log(deposit.status);      // Deposit status

// Payment link response
const link = await monei.deposit.generatePaymentLink({...});
console.log(link.url);            // Payment link URL
console.log(link.reference);      // Payment reference

// Bank transfer response
const transfer = await monei.payout.bankTransfer({...});
console.log(transfer.reference);  // Transfer reference
console.log(transfer.status);     // Transfer status
console.log(transfer.fee);        // Transfer fee

// Peer transfer response
const peerTransfer = await monei.payout.peerTransfer({...});
console.log(peerTransfer.reference);  // Transfer reference
console.log(peerTransfer.status);     // Transfer status

// Banks response
const { banks } = await monei.utility.getBanks();
banks.forEach(bank => {
  console.log(bank.name);   // Bank name
  console.log(bank.code);   // Bank code
});

// Verified account response
const verified = await monei.utility.verifyBankAccount({...});
console.log(verified.accountName);   // Verified account name
console.log(verified.accountNumber); // Account number
console.log(verified.bankName);      // Bank name

Error Handling

All wallet service calls may throw an error if the request fails.

import { MoneiError } from 'monei-sdk';

try {
  const wallet = await monei.account.me(56);
  console.log(wallet.balance);
} catch (error) {
  if (error instanceof MoneiError) {
    console.error(error.statusCode);  // HTTP status code
    console.error(error.message);     // Error message
    console.error(error.code);        // Error code
  }
}

Service Overview

Service	Method	Description
Account	`me(chainId?)`	Get wallet info
	`createVirtualAccount(options)`	Create virtual bank account
Deposit	`initialize(method, data)`	Initialize a deposit
	`withPaymentMethod(data)`	Deposit with saved payment method
	`authorize(data)`	Authorize deposit with OTP
	`generatePaymentLink(data)`	Generate payment link
	`getStatus(reference)`	Check deposit status
Payout	`bankTransfer(data)`	Send bank transfer
	`peerTransfer(data)`	Send peer-to-peer transfer
Utility	`getBanks()`	Get all supported banks
	`verifyBankAccount(data)`	Verify bank account details

Notes

All methods require a properly configured MoneiClient instance with authentication
Amounts are in kobo (1 NGN = 100 kobo)
Virtual accounts are only available for Naira wallets
Bank transfers require verification before processing
All responses are strongly typed objects with property access

​Overview

​Account Service

​Get Wallet Info

​Create Virtual Account

​Deposit Service

​Initialize a Deposit

​Deposit with Saved Payment Method

​Authorize a Deposit (OTP / 3DS)

​Generate a Payment Link

​Check Deposit Status

​Payout Service

​Bank Transfer

​Peer Transfer (Monei-to-Monei)

​Wallet Utility Service

​Get All Banks

​Verify Bank Account

​Working with Response Objects

​Error Handling

​Service Overview

​Notes