Dev BookDev Book

Wallets

As a merchant, you can create and manage Wallets for various purposes, such as customers (individuals or businesses), departments within your organization, or entities related to your organization. You are the owner of all the wallets you create and are responsible for ensuring compliance with KYC (Know Your Customer) requirements.

Think of wallets as digital bank accounts that you control. Whether you're running a marketplace that needs separate accounts for each seller, a fintech app managing user balances, or a business tracking funds across different departments—wallets give you the flexibility to organize and manage money exactly how you need it.

Default Wallet

Every merchant is assigned a Main Wallet (Default Wallet) upon onboarding.

Wallet Types

You can create two types of wallets based on your needs:

  1. Virtual Accounts

    • Assigned a unique account number.
    • Cannot hold a balance; the balance is always zero.
    • Designed to receive funds, which are automatically routed to the Main Wallet.

  2. Sub-Accounts

    • Assigned a unique account number.
    • Assigned an account name based on the name of the merchant and the name provided - i.e MERCHANT NAME/SUBACCOUNT NAME
    • Can hold a balance, allowing you to store and manage funds.
    • Capable of both receiving and sending funds.

Virtual Accounts

Create Dynamic Account

This endpoint allows you to create a dynamic virtual wallet. It accepts a POST request and requires a JSON payload containing details about the wallet to be created.

Perfect for one-time payments

Virtual accounts are like temporary bank accounts that expire after a set time or once they receive a specific amount. They're perfect for scenarios where you need a unique account number for each transaction, but don't want to create permanent accounts that clutter your system.

Common use cases

  • E-commerce checkout: Generate a unique account number for each order. Once the customer pays the exact amount, the account expires and funds route to your main wallet.
  • Invoice payments: Create a virtual account for each invoice. The account name shows your company name and invoice number, making reconciliation a breeze.
  • Event ticket sales: Each ticket purchase gets its own virtual account. When the payment is received, the account automatically closes.
  • Donation campaigns: Create time-limited accounts for fundraising. After the campaign ends or the target is reached, the account expires.
  • Escrow services: Generate temporary accounts for holding funds during transactions. Once conditions are met, funds are released.
  • Subscription setup: Use virtual accounts for initial payment collection before converting to recurring mandates.

Why virtual accounts?

  • Automatic routing: Funds go straight to your main wallet—no manual transfers needed.
  • Zero balance management: You don't need to worry about balances since virtual accounts can't hold funds.
  • Enhanced security: Each transaction gets a unique account number, reducing fraud risk.
  • Easy reconciliation: Account names can include order IDs or references, making it easy to match payments.

Request Body

  • Name
    accountName
    Type
    string
    Description

    The name associated with the account number. This will be displayed to the payer when they look up the account in their banking platform. It will have the format YourCompany /. E.g Acme LTD/payment-1938740

  • Name
    amount
    Type
    number
    Description

    The exact, fixed amount this virtual account is authorized to receive. The account will reject any payment that does not match this specific value.

  • Name
    expiryTimeInMinutes
    Type
    integer
    Description

    The duration (in minutes) this virtual account will remain active. The account will reject any payments received after this time. The maximum allowed duration is 60 minutes.

Request

POST
/wallets/virtual/dynamic
curl https://api.aellaapp.com/wallets/virtual/dynamic \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountName": "General Use Case",
    "amount": 2000,
    "expiryTimeInMinutes": 30
  }'

Response

{
  "success": true,
  "message": "Dynamic virtual wallet created successfully",
  "data": {
    "id": "97890dae-e1cc-40d3-ad25-a71f0857dda8",
    "balance": 0,
    "currency": "NGN",
    "availableBalance": 0,
    "accountName": "Merchant II/General Use Case",
    "accountNumber": "0377752164",
    "bankName": "Aella Microfinance Bank",
    "label": "Virtual Wallet",
    "virtual": true,
    "virtualAmount": 2000,
    "createdAt": "2025-06-26T07:55:34.520Z",
    "expiresAt": "2025-06-26T08:05:32.997Z"
  },
  "status": 200
}

Sub-Accounts

Create Sub-Account

This endpoint creates a new sub-account with a given account name and description. Account names can be non-unique. An optional unique external reference can be provided to uniquely track sub-accounts.

Your flexible fund management tool

Sub-accounts are like separate bank accounts under your main wallet. They can hold balances, receive payments, and send money—giving you complete control over how you organize funds. Think of them as dedicated accounts for different purposes, customers, or business units.

Common use cases

  • Marketplace seller accounts: Create a sub-account for each seller. They receive payments directly, and you can track their earnings separately.
  • Department budgets: Allocate budgets to different departments (Marketing, Operations, etc.) with separate sub-accounts for better financial control.
  • Customer wallets: Give each customer their own sub-account to hold credits, rewards, or refunds.
  • Project funding: Create sub-accounts for specific projects, making it easy to track expenses and income per project.
  • Vendor management: Set up sub-accounts for vendors to manage payments and track outstanding balances.
  • Escrow accounts: Hold funds in sub-accounts until transaction conditions are met.
  • Multi-currency operations: Use sub-accounts to separate different currencies or payment methods.

Why use sub-accounts?

  • Better organization: Keep funds separated by purpose, making accounting and reporting much easier.
  • Independent operations: Each sub-account can send and receive money independently.
  • Real account numbers: Sub-accounts get real bank account numbers that customers can pay into.
  • Balance management: Unlike virtual accounts, sub-accounts can hold balances for future use.

Request Body

  • Name
    account_name
    Type
    string
    Description

    The name for the sub-account.

  • Name
    description
    Type
    string
    Description

    A description for the sub-account.

  • Name
    external_reference
    Type
    string
    Description

    An optional unique external reference to uniquely track sub-accounts.

Request

POST
/wallets/sub-accounts
curl https://api.aellaapp.com/wallets/sub-accounts \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_name": "Customer Account",
    "description": "Account for customer payments",
    "external_reference": "customer-12345"
  }'

Response

{
  "success": true,
  "message": "Sub-account created successfully",
  "data": {
    "id": "ba69dbd3-78b9-4755-a70b-6f96facef7f2",
    "description": "Account for customer payments",
    "balance": 0,
    "available_balance": 0,
    "account_number": "0240520328",
    "account_name": "Mint/Customer Account",
    "external_reference": "customer-12345"
  },
  "status": 200
}

Credit Sub-Account

This endpoint is used to credit an amount from the merchant's main wallet and settle into the sub-account indicated.

Move money into sub-accounts

Need to fund a sub-account? This endpoint transfers money from your main wallet to any sub-account. It's like moving money from your main checking account to a savings account—instant and seamless.

Common use cases

  • Allocating budgets: Transfer monthly budgets from your main wallet to department sub-accounts.
  • Funding customer wallets: Credit customer accounts with rewards, refunds, or promotional credits.
  • Project funding: Move funds from main wallet to project-specific sub-accounts.
  • Vendor advances: Pre-fund vendor sub-accounts for upcoming purchases.
  • Reserve accounts: Set aside funds in sub-accounts for specific purposes (taxes, emergencies, etc.).
  • Multi-party transactions: Distribute funds to different sub-accounts based on business logic.

Path Parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the sub-account.

Request Body

  • Name
    amount
    Type
    number
    Description

    The amount to credit to the sub-account.

  • Name
    narration
    Type
    string
    Description

    A description or reason for the credit.

Request

POST
/wallets/sub-accounts/{id}/credit
curl https://api.aellaapp.com/wallets/sub-accounts/b1613516-e974-40dc-b266-173ee1b711b7/credit \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "narration": "Funding sub-account"
  }'

Response

{
  "success": true,
  "message": "Transaction successful",
  "data": {
    "transaction_reference": "INTT-d0e720b75adf061ba09f4229843aae76ac019fb24a5d241cad43d5db4fcc"
  },
  "status": 200
}

Debit Sub-Account

This endpoint is used to debit an amount from the sub-account indicated and settle into the merchant's main wallet.

Consolidate funds back to main wallet

When you need to move money from a sub-account back to your main wallet, this endpoint does the job. Perfect for consolidating funds, closing accounts, or rebalancing your finances.

Common use cases

  • Consolidating revenue: Move funds from seller sub-accounts back to main wallet after deducting commissions.
  • Closing accounts: Withdraw remaining balances when closing a sub-account.
  • Rebalancing: Adjust fund distribution across sub-accounts and main wallet.
  • Emergency transfers: Quickly move funds from sub-accounts to main wallet when needed.
  • End-of-period reconciliation: Consolidate all sub-account balances for monthly or yearly reporting.
  • Refund processing: Move funds from customer sub-accounts back to main wallet for refunds.

Path Parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the sub-account.

Request Body

  • Name
    amount
    Type
    number
    Description

    The amount to debit from the sub-account.

  • Name
    narration
    Type
    string
    Description

    A description or reason for the debit.

Request

POST
/wallets/sub-accounts/{id}/debit
curl https://api.aellaapp.com/wallets/sub-accounts/b1613516-e974-40dc-b266-173ee1b711b7/debit \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "narration": "Withdrawal from sub-account"
  }'

Response

{
  "success": true,
  "message": "Transaction successful",
  "data": {
    "transaction_reference": "INTT-d0e720b75adf061ba09f4229843aae76ac019fb24a5d241cad43d5db4fcc"
  },
  "status": 200
}

Get Sub-Account

This endpoint retrieves the details of a specific sub-account.

Check sub-account status anytime

Need to know the balance, account number, or details of a sub-account? This endpoint gives you everything you need in one call. Perfect for dashboards, balance checks, or account verification.

Common use cases

  • Balance checks: Display current balance and available balance for users or in your admin panel.
  • Account verification: Verify sub-account details before processing transactions.
  • Dashboard displays: Show account information in customer or admin dashboards.
  • Reconciliation: Retrieve account details for accounting and reconciliation purposes.
  • Account lookup: Find sub-accounts using ID, external reference, or wallet ID.

Path Parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier, external reference, or wallet ID of the sub-account.

Request

GET
/wallets/sub-accounts/{id}
curl https://api.aellaapp.com/wallets/sub-accounts/b1613516-e974-40dc-b266-173ee1b711b7 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Subaccount retrieved successfully",
  "data": {
    "id": "b1613516-e974-40dc-b266-173ee1b711b7",
    "description": "Global",
    "balance": 470,
    "available_balance": 470,
    "account_number": "0242438865",
    "account_name": "Mint/Global",
    "wallet_id": "e3981836-8a47-493e-9f92-165312e98220",
    "external_reference": "customer-12345"
  },
  "status": 200
}

Get Sub-Account Transactions

This endpoint retrieves the transactions for a specific sub-account.

Track all sub-account activity

See every transaction that's happened in a sub-account—credits, debits, transfers, and payments. This is your transaction history for any sub-account, perfect for auditing, reporting, or showing users their activity.

Common use cases

  • Transaction history: Show users all transactions in their wallet or sub-account.
  • Audit trails: Review all activity for compliance and auditing purposes.
  • Financial reporting: Generate reports on sub-account activity for accounting.
  • Dispute resolution: Review transaction history when resolving customer disputes.
  • Analytics: Analyze transaction patterns for business insights.
  • Reconciliation: Match transactions with your internal records.

Path Parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the sub-account.

Request

GET
/wallets/sub-accounts/{id}/transactions
curl https://api.aellaapp.com/wallets/sub-accounts/b1613516-e974-40dc-b266-173ee1b711b7/transactions \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Transactions retrieved successfully",
  "data": [
    {
      "id": "7c633319-cead-4eeb-be89-f70e009ff215",
      "amount": 20000.0,
      "currency": "NGN",
      "walletId": "e3981836-8a47-493e-9f92-165312e98220",
      "type": "cr",
      "date": "2024-12-01T20:41:51.998Z",
      "metadata": {
        "senderName": "Palmpay - MUSTAPHA GARBA",
        "senderBank": "PalmPay",
        "senderAccountNumber": 4394378232,
        "recieverName": "Aella MFB - Merchant Name",
        "recieverBank": "Aella MFB",
        "recieverAccountNumber": 26732793203,
        "sessionId": "100033221219102347000266816492",
        "narration": "Payment description"
      }
    }
  ],
  "meta": {
    "previousPage": null,
    "nextPage": null,
    "total": 11,
    "totalPages": 2,
    "currentPage": 1
  }
}

Get All Sub-Accounts

This endpoint retrieves a list of sub-accounts associated with the user's wallet.

View all your sub-accounts at once

Get a paginated list of all your sub-accounts. Perfect for displaying accounts in a dashboard, managing multiple accounts, or generating reports across all sub-accounts.

Common use cases

  • Account management dashboard: Display all sub-accounts with their balances in your admin panel.
  • Bulk operations: Retrieve all sub-accounts to perform batch operations or updates.
  • Reporting: Generate reports across all sub-accounts for financial analysis.
  • Account search: List all accounts and filter by name, reference, or other criteria.
  • Balance overview: Get a quick overview of all sub-account balances.

Query Parameters

  • Name
    page
    Type
    integer
    Description

    Specifies the page number of the results to retrieve.

  • Name
    limit
    Type
    integer
    Description

    Defines the maximum number of sub-accounts to return per page.

Request

GET
/wallets/sub-accounts
curl "https://api.aellaapp.com/wallets/sub-accounts?page=1&limit=10" \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Sub-accounts retrieved successfully",
  "data": [
    {
      "id": "b1613516-e974-40dc-b266-173ee1b711b7",
      "description": "Global",
      "balance": 470,
      "available_balance": 470,
      "account_number": "0242438865",
      "account_name": "Mint/Global",
      "external_reference": "customer-12345"
    }
  ],
  "meta": {
    "total": 5,
    "currentPage": 1,
    "totalPages": 1
  },
  "status": 200
}

Single Transfer

This endpoint allows you to transfer funds from a sub-account to another bank account.

Send money directly from sub-accounts

Transfer funds from a specific sub-account to any Nigerian bank account. This is perfect when you want to pay out from a specific account rather than your main wallet.

Common use cases

  • Seller payouts: Pay marketplace sellers directly from their earnings sub-account.
  • Vendor payments: Settle invoices from vendor-specific sub-accounts.
  • Customer withdrawals: Allow customers to cash out from their wallet sub-account.
  • Department expenses: Pay bills or expenses from department-specific sub-accounts.
  • Project payments: Make payments related to a specific project from its sub-account.

Path Parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the sub-account.

Request Body

  • Name
    bankCode
    Type
    string
    Description

    The NIBSS code of the bank receiving the transfer.

  • Name
    accountNumber
    Type
    string
    Description

    The recipient's account number.

  • Name
    amount
    Type
    number
    Description

    The amount to transfer.

  • Name
    currency
    Type
    string
    Description

    The currency of the transfer (e.g., NGN).

  • Name
    narration
    Type
    string
    Description

    A description or reason for the transfer.

Request

POST
/wallets/sub-accounts/{id}/transfer
curl https://api.aellaapp.com/wallets/sub-accounts/b1613516-e974-40dc-b266-173ee1b711b7/transfer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "bankCode": "000013",
    "accountNumber": "0480813345",
    "amount": 100.00,
    "currency": "NGN",
    "narration": "Payment to customer"
  }'

Response

{
  "success": true,
  "message": "Transfer initiated successfully",
  "data": {
    "id": "1d3b9482-835c-453e-ae14-07bbaf719e1c",
    "status": "Pending",
    "amount": 100.00,
    "currency": "NGN"
  },
  "status": 200
}

Bulk Transfer

This endpoint allows for processing multiple bank transfers from a sub-account in a single request.

Efficient batch payments from sub-accounts

Process multiple transfers from a sub-account in one API call. Perfect for paying multiple recipients from a specific sub-account without multiple API calls.

Common use cases

  • Bulk seller payouts: Pay multiple marketplace sellers from a single sub-account simultaneously.
  • Batch vendor payments: Settle multiple vendor invoices from a vendor management sub-account.
  • Mass customer withdrawals: Process multiple customer cash-outs from a customer funds sub-account.
  • Department expense payments: Pay multiple bills or expenses from a department sub-account.

Path Parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the sub-account.

Request Body

  • Name
    transfers
    Type
    array
    Description

    Array of transfer objects, each containing:

    • bankCode (string): The NIBSS code of the bank receiving the transfer.
    • accountNumber (string): The recipient's account number.
    • amount (number): The amount to transfer.
    • currency (string): The currency of the transfer.
    • narration (string): A description or reason for the transfer.
    • externalReference (string, optional): A unique reference for the transfer.

Request

POST
/wallets/sub-accounts/{id}/bulk-transfer
curl https://api.aellaapp.com/wallets/sub-accounts/b1613516-e974-40dc-b266-173ee1b711b7/bulk-transfer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "transfers": [
      {
        "bankCode": "000004",
        "accountNumber": "2156859903",
        "amount": 30.00,
        "currency": "NGN",
        "narration": "Payment 1",
        "externalReference": "ref-001"
      },
      {
        "bankCode": "000004",
        "accountNumber": "2119347041",
        "amount": 10.00,
        "currency": "NGN",
        "narration": "Payment 2",
        "externalReference": "ref-002"
      }
    ]
  }'

Response

{
  "success": true,
  "message": "Bulk transfer initiated successfully",
  "data": {
    "transfers": [
      {
        "id": "645500ff-cd5a-414e-91bd-12e724533d3d",
        "amount": 30,
        "fee": 100,
        "reference": "b74d9973-4182-4872-8237-3b46e8e6cb56",
        "status": "Pending",
        "receiverBankCode": "000004",
        "currency": "NGN"
      }
    ]
  },
  "status": 200
}

Main Wallet

Get Wallet

This endpoint is used to fetch a specific wallet identified by its id.

Check your main wallet details

Get all the details about your main wallet—balance, account number, account name, and more. This is your go-to endpoint for checking wallet status and displaying wallet information.

Common use cases

  • Balance display: Show current wallet balance in your dashboard or app.
  • Account verification: Verify wallet details before processing transactions.
  • Status checks: Check wallet status and available balance.
  • Account information: Display account number and name to users.

Path Parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the wallet.

Request

GET
/wallets/{id}
curl https://api.aellaapp.com/wallets/e3981836-8a47-493e-9f92-165312e98220 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Wallet retrieved successfully",
  "data": {
    "id": "e3981836-8a47-493e-9f92-165312e98220",
    "balance": 100000,
    "available_balance": 100000,
    "currency": "NGN",
    "account_number": "0242438865",
    "account_name": "Merchant Name"
  },
  "status": 200
}

Get Wallet Transactions

This endpoint retrieves a paginated list of transactions for a specific wallet, filtered by optional date range and pagination parameters.

Your complete transaction history

Get all transactions for your main wallet with powerful filtering options. Filter by date range, paginate through results, and see every credit, debit, and transfer. Perfect for transaction logs, financial reports, and audit trails.

Common use cases

  • Transaction logs: Display all wallet transactions in your admin panel or user dashboard.
  • Financial reporting: Generate monthly, quarterly, or yearly transaction reports.
  • Audit trails: Review all wallet activity for compliance and auditing.
  • Reconciliation: Match transactions with your accounting records.
  • Analytics: Analyze transaction patterns and trends.
  • Dispute resolution: Review transaction history when resolving issues.

Path Parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the wallet.

Query Parameters

  • Name
    page
    Type
    number
    Description

    The page number for pagination (default: 1).

  • Name
    limit
    Type
    number
    Description

    The number of transactions per page (default: 10).

  • Name
    from
    Type
    string
    Description

    Start date for filtering transactions (YYYY-MM-DD).

  • Name
    to
    Type
    string
    Description

    End date for filtering transactions (YYYY-MM-DD).

Request

GET
/wallets/{id}/transactions
curl "https://api.aellaapp.com/wallets/e3981836-8a47-493e-9f92-165312e98220/transactions?page=1&limit=10&from=2024-12-01&to=2024-12-31" \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Transactions retrieved successfully",
  "data": [
    {
      "id": "7c633319-cead-4eeb-be89-f70e009ff215",
      "amount": 20000.0,
      "currency": "NGN",
      "walletId": "e3981836-8a47-493e-9f92-165312e98220",
      "type": "cr",
      "date": "2024-12-01T20:41:51.998Z",
      "metadata": {
        "senderName": "Palmpay - MUSTAPHA GARBA",
        "senderBank": "PalmPay",
        "senderAccountNumber": 4394378232,
        "recieverName": "Aella MFB - Merchant Name",
        "recieverBank": "Aella MFB",
        "recieverAccountNumber": 26732793203,
        "sessionId": "100033221219102347000266816492",
        "narration": "Payment description"
      }
    }
  ],
  "meta": {
    "previousPage": null,
    "nextPage": null,
    "total": 11,
    "totalPages": 2,
    "currentPage": 1
  }
}

Was this page helpful?