Virtual Accounts

Learn how to create virtual accounts.

Overview

Creating virtual bank accounts with Mono Issuing.

Learn how to create a virtual bank account via APIs in 3 simple steps.

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


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 collection field. If you’re creating a virtual account for collection(disposable or one-time use) only and not a store of value, a collection parameter with true is required.

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
}'
{
  "status": "success",
  "message": "Virtual account creation is been 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.
  • Collection virtual accounts can only receive credits and are for one-time use only.

Step 3: Fetch a Virtual Account

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/ Identification

KYC Level 1

KYC Level 2

KYC Level 3

BVN

Required

Required

Required

Phone Number

Required

Required

Required

Intl. passport/ Driver’s license/ Voter’s ID/ NIN

Not Required

Required

Required

Residential Address

Not Required

Not Required

Required

Physical Card Request

N/A

Yes

Yes

Transaction limits

The table below shows transaction limits for each KYC level:

KYC Level 1

KYC Level 2

KYC Level 3

How much can I receive at a time?

NGN 50,000

NGN 100,000

Unlimited

What is the max. amount I can send at a time?

Disabled

NGN 100,000

NGN 1,000,000

What is the max. amount I can send in a day?

Disabled

NGN 100,000

NGN 5,000,000

Maximum account balance

NGN 300,000

NGN 500,000

Unlimited

Can I request for a card?

No

Yes

Yes

  • The requirement for KYC level 2 above requires a valid BVN on the Account Holder. The BVN field for the Account Holder can be updated via the Update Account Holder API here.
  • The requirement for KYC level 3 above is largely dependent on the identity state object of the Account Holder. These fields can be updated via the Update Account Holder API here.

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
  }
}

Fund Transfer

There are three types of fund transfer operations that can be performed within a Virtual Account:

  1. Transfer to Account Number
  2. Transfer to Virtual Account (p2p)
  3. Credit from your Issuing Wallet

1. Transfer to Account Number

A Virtual Account can initiate 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"
  }
}

📘

Transfer to Account Number Pricing

  1. For transfers greater than NGN 50,000 = NGN 50
  2. For transfers greater than NGN 5,000 but less than or equal to NGN 50,000 = NGN 26
  3. For transfers less than or equal to NGN 5,000 = NGN 10

2. Transfer to Virtual Account (p2p)

A Virtual Account can transfer funds from itself to another Virtual Account within the same business. The required fields in the body request to make this possible are the amount, narration, reference and the virtual account ID of the recipient.

API Reference

curl --location --request POST 'https://api.withmono.com/issuing/v1/virtualaccounts/61a8f60ecfb84076108ebd53/transfer' \
--data-raw '{
    "amount": 10000,
    "narration": "smile",
    "reference": "1232rwqsdq",
    "virtual_account": "61cb8b4535afa436478bcaf7"
}'
{
  "status": "successful",
  "message": "Transfer is processing",
  "data": {
    "id": "61d5de39521b8355e43e4f5a"
  }
}

3. Credit from your Issuing Wallet

As a business, you can initiate a credit transaction into an already created virtual account using your issuing wallet. The fields required for this are just the amount and the narration field.

API Reference

curl --location --request POST 'https://api.withmono.com/issuing/v1/virtualaccounts/61a8f60ecfb84076108ebd53/credit' \
--data-raw '{
    "amount": 100000,
    "narration": "Matured Investment"
}'
{
  "status": "successful",
  "message": "Credit is processing"
}

👍

NOTE

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

🚧

NOTE ON PAYMENT CONFIRMATION

  • Regarding transfers, payment value shouldn't be given to your customers instantly when the API response status response says successful. Instead, you should rely on the respective webhook events for confirmation before then giving value to your customers.

  • You can easily send the message response below to your customers below as soon as a Transfer has been initiated if need be:

"Your payment request has been made as this would be confirmed shortly. You can check your transactions records shortly."


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"
  }
}

Did this page help you?