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.

Note: All methods return response objects with attributes accessible via dot notation (e.g., wallet.balance, deposit.reference).

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
wallet = monei.account.me(56)  # BSC chain ID
print(wallet.balance, wallet.address)

Create Virtual Account

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

account = monei.account.create_virtual_account(
    sub_wallet_id="sub-wallet-id"
)

print(account.account_number)  # e.g. "0123456789"
print(account.bank_name)       # e.g. "Wema Bank"

Deposit Service

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

Initialize a Deposit

from monei import DEPOSIT_METHOD

deposit = monei.deposit.initialize(
    DEPOSIT_METHOD.BANK_TRANSFER,
    amount=5000,           # Amount in kobo
    currency="NGN",
    sub_wallet_id="sub-wallet-id"
)

print(deposit.reference, deposit.payment_url)

Deposit with Saved Payment Method

deposit = monei.deposit.with_payment_method(
    amount=5000,
    currency="NGN",
    payment_method_id="pm-id",
    sub_wallet_id="sub-wallet-id"
)

print(deposit.reference, deposit.status)

Authorize a Deposit (OTP / 3DS)

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.

link = monei.deposit.generate_payment_link(
    amount=10000,
    currency="NGN",
    description="Invoice #42",
    sub_wallet_id="sub-wallet-id"
)

print(link.url)

Check Deposit Status

status = monei.deposit.get_status(deposit.reference)
print(status.status)  # "pending" | "successful" | "failed"

Payout Service

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

Bank Transfer

transfer = monei.payout.bank_transfer(
    amount=5000,
    bank_code="GTBINGLA",
    account_number="0123456789",
    account_name="John Doe",
    narration="Payment for services",
    sub_wallet_id="sub-wallet-id"
)

print(transfer.reference, transfer.status)

Peer Transfer (Monei-to-Monei)

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

transfer = monei.payout.peer_transfer(
    amount=2000,
    recipient_tag="@john",   # or email / user ID
    narration="Lunch split",
    sub_wallet_id="sub-wallet-id"
)

print(transfer.reference, transfer.status)

Wallet Utility Service

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

Get All Banks

banks_response = monei.utility.get_banks()

for bank in banks_response.banks:
    print(bank.name, bank.code)

Verify Bank Account

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

verified = monei.utility.verify_bank_account(
    account_number="0123456789",
    bank_code="GTBINGLA"
)

print(verified.account_name)  # "JOHN ADEWALE DOE"

Working with Response Objects

All methods return objects with attribute access:

# Account response
wallet = monei.account.me(56)
print(wallet.balance)      # Wallet balance
print(wallet.address)      # Wallet address
print(wallet.currency)     # Currency code

# Virtual account response
account = monei.account.create_virtual_account(sub_wallet_id="...")
print(account.account_number)  # Virtual account number
print(account.bank_name)       # Bank name
print(account.account_name)    # Account holder name

# Deposit response
deposit = monei.deposit.initialize(DEPOSIT_METHOD.BANK_TRANSFER, ...)
print(deposit.reference)   # Deposit reference
print(deposit.payment_url) # Payment URL
print(deposit.status)      # Deposit status

# Payment link response
link = monei.deposit.generate_payment_link(...)
print(link.url)            # Payment link URL
print(link.reference)      # Payment reference

# Bank transfer response
transfer = monei.payout.bank_transfer(...)
print(transfer.reference)  # Transfer reference
print(transfer.status)     # Transfer status
print(transfer.fee)        # Transfer fee

# Peer transfer response
peer_transfer = monei.payout.peer_transfer(...)
print(peer_transfer.reference)  # Transfer reference
print(peer_transfer.status)     # Transfer status

# Banks response
banks_response = monei.utility.get_banks()
for bank in banks_response.banks:
    print(bank.name)   # Bank name
    print(bank.code)   # Bank code

# Verified account response
verified = monei.utility.verify_bank_account(...)
print(verified.account_name)   # Verified account name
print(verified.account_number) # Account number
print(verified.bank_name)      # Bank name

Error Handling

All wallet service calls may raise an exception if the request fails.

from monei import MoneiError

try:
    wallet = monei.account.me(56)
    print(wallet.balance)
except MoneiError as err:
    print(err.status_code)  # HTTP status code
    print(err.message)      # Error message
    print(err.code)         # Error code

Service Overview

Service	Method	Description
Account	`me(chain_id=None)`	Get wallet info
	`create_virtual_account(sub_wallet_id)`	Create virtual bank account
Deposit	`initialize(method, amount, currency, sub_wallet_id)`	Initialize a deposit
	`with_payment_method(amount, currency, payment_method_id, sub_wallet_id)`	Deposit with saved payment method
	`authorize(reference, otp)`	Authorize deposit with OTP
	`generate_payment_link(amount, currency, description, sub_wallet_id)`	Generate payment link
	`get_status(reference)`	Check deposit status
Payout	`bank_transfer(amount, bank_code, account_number, account_name, narration, sub_wallet_id)`	Send bank transfer
	`peer_transfer(amount, recipient_tag, narration, sub_wallet_id)`	Send peer-to-peer transfer
Utility	`get_banks()`	Get all supported banks
	`verify_bank_account(account_number, bank_code)`	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 attribute 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