Virtual Accounts

Learn how to create virtual accounts.

Overview

Virtual accounts are subledgers that exist within a traditional bank account.

Issue a virtual account via APIs in 3 simple steps.

Step 1: Get Account Holder ID
Step 2: Create a Virtual Account
Step 3: Fetch Virtual Account Details


Step 1: Get Account Holder ID

The Account holder ID is required to issue a virtual bank account. If an Account Holder doesn’t exist at the moment, please visit the documentation page above to get started. As a business or developer, you can also get a list of all created Account Holders with the Get Account Holders API.

API Reference

curl --location --request GET 'https://api.withmono.com/issuing/v1/accountholders' \
--header 'mono-sec-key: live_sk_EtJWxTkkQEQn0vPrg2wc' \
--data-raw ''
{
  "status": "successful",
  "message": "Account holders fetched",
  "data": [
    {
      "address": {
        "country": "nigeria",
        "lga": "ikeja",
        "city": "ikeja",
        "state": "lagos",
        "postal_code": "100001",
        "address_line1": "banana island",
        "address_line2": "banana island"
      },
      "phone": "111109030841956",
      "entity": "INDIVIDUAL",
      "identity": {
        "type": "NIN",
        "number": "1111:10111222112",
        "url": "https://mono-business-assets.s3.eu-west-2.amazonaws.com/identity-FunVlKB_OKMHuQFLCT5ek-test_1.png"
      },
      "bvn": "22923001290",
      "email": "[email protected]",
      "business": "6172811205af5c47a1f31e49",
      "app": "60ffd3fee03417c574fa1f55",
      "live": false,
      "created_at": "2021-12-08T22:21:40.428Z",
      "updated_at": "2021-12-08T22:21:40.428Z",
      "id": "61b12ff41f933f527efc6c90",
      "first_name": "ifeoluwa",
      "last_name": "olanipekun",
      "selfie_url": "https://mono-business-assets.s3.eu-west-2.amazonaws.com/identity-FunVlKB_OKMHuQFLCT5ek-test_1.png"
    },
  ],
  "meta": {
    "total": 5,
    "pages": 1,
    "previous": null,
    "next": null
  }
}

Step 2: Create Virtual Account

Here, we will create a virtual account and assign it to an account holder. This request contains the account holder ID and the account_holder fields as required. If you’re creating a virtual account for collection(disposable or one-time use) only and not a store of value, the account_type parameter should be set to 'collection'.

API Reference

curl --location --request POST 'https://api.withmono.com/issuing/v1/virtualaccounts' \
--data-raw '{
    "account_holder": "61a7363bc2d313658ce82d38",
    "account_type": "deposit", // deposit OR collection
    "disposable": false // Optional as this applies only to collection accounts
    "provider": "" // Optional as it expects your desired virtual account provider against the default provider
}'
{
  "status": "success",
  "message": "Virtual account creation is being processed",
  "data": {
    "id": "61a74cd4644e048825068341"
  }
}

🚧

NOTES

  • Once a virtual account has been created, Mono sends the issuing.virtual_account_created webhook event.
  • All credits made to a collection virtual account will be settled to the partner's bank account at end of the day.
  • Transfers can not be done out of a collection virtual account.
  • Disposable collection virtual accounts can only receive credits and are for one-time use only.

📘

NOTE ON PROVIDER

A. For deposit account types, our supported providers are:

  • Guaranty Trust bank (gtb),
  • Fidelity bank (fidelity),
  • Providus bank (providus).

B. For collection account types, our supported providers are:

  • Guaranty Trust bank (gtb),
  • Fidelity bank (fidelity),
  • Providus bank (providus).

Step 3: Fetch Virtual Account Details

With a virtual account already created, we can get detailed information about this account via the created virtual account ID.

API Reference

curl --location --request GET 'https://api.withmono.com/issuing/v1/virtualaccounts/61b1c54887902462b5f2890d'
{
  "status": "successful",
  "message": "Virtual Account fetched successfully",
  "data": {
    "currency": "NGN",
    "balance": 0,
    "status": "active",
    "app": "61b12e9c9d6aa15bfd22700c",
    "business": "60cc8f95ba1772018c5c6b1d",
    "id": "61b1c54887902462b5f2890d",
    "bank_name": "Tangerine Money",
    "bank_code": "100685",
    "kyc_level": "3",
    "account_name": "KING AHMED",
    "account_number": "1100241532"
  }
}

Virtual Account Upgrade

A virtual account can be upgraded (from kyc_level 1 to 3) to higher levels so as to perform higher-order functions. This upgrade can be done by passing in the Virtual account ID to our Upgrade Account API.
The table below shows all documents and information needed to create a virtual account:

Documents/ IdentificationKYC Level 1KYC Level 2KYC Level 3
BVNRequiredRequiredRequired
Phone NumberRequiredRequiredRequired
NINNot RequiredRequiredRequired

Transaction limits

The table below shows transaction limits for each KYC level:

KYC Level 1KYC Level 2KYC Level 3
ID TypesBVNBVN + NINBVN + NIN + CAC ID
How much can you receive per day?UnlimitedUnlimitedUnlimited
Maximum Account BalanceUnlimitedUnlimitedUnlimited
The withdrawal limit per dayNGN 1,000,000NGN 2,000,000Unlimited
What is the maximum amount that can be sent at a time?NGN 1,000,000NGN 2,000,000Unlimited

API Reference

curl --location --request PATCH 'https://api.withmono.com/issuing/v1/virtualaccounts/61a8f60ecfb84076108ebd53/upgrade'
{
  "status": "successful",
  "message": "Account upgrade is processing",
  "data": {
    "id": "61a8f60ecfb84076108ebd53",
    "kyc_level": 2
  }
}

📘

NOTE FOR BUSINESS VIRTUAL ACCOUNT

Kindly note that to create a business virtual account, it's mandatory to provide identity information as well business details on the business account holder for a successful virtual account creation.

Fund Transfer

Fund transfer operations can be performed within a Virtual Account:

  1. Transfer to Account Number

Transfer to Account Number

A Virtual Account can initiate a bank transfer into any Nigerian Bank Account Number via API by passing the desired amount, a narration, a reference, the destination account number, and the bank code. (A list of all bank codes can be found here)

API Reference

curl --location --request POST 'https://api.withmono.com/issuing/v1/virtualaccounts/61b1bff887902462b5f288a9/transfer' \
--data-raw '{
    "amount": 10000,
    "narration": "repayment",
    "reference": "easrwsdwqsdq",
    "account_number": "0029873434",
    "bank_code": "044"
}'
{
  "status": "successful",
  "message": "Transfer is processing",
  "data": {
    "id": "61b9de61622a2dc1e5301e17"
  }
}

👍

NOTE

Please do not include any special characters while setting a payment reference.

Virtual Account Pricing

Account TypeCreation FeeInward transfer feeOutward transfer feeAccount to an Account transfer feeCredit a deposit account
DepositNGN 00.6%, capped at 1,000NGN 20 per transfer, VAT inclusiveNGN 20 VAT inclusiveNGN 20 VAT inclusive
CollectionNGN 00.7% + NGN 12, capped at 1,000Not available for collectionNot available for collectionNot available for collection

Mock Transaction

In a sandbox environment, you can perform mock debit or credit transactions on Virtual accounts created in Sandbox via the ID.

API Reference

curl --location --request POST 'https://api.withmono.com/issuing/v1/virtualaccounts/61a8f60ecfb84076108ebd53/mocktransaction' \
--data-raw '{
    "amount": "2000",
    "type": "credit"
}'
{
  "status": "successful",
  "message": "Mock Transaction Sent Successfully",
  "data": {
    "id": "61a8f60ecfb84076108ebd53"
  }
}