Issuing Virtual Accounts

Learn how to create virtual accounts.

Overview

Creating virtual bank accounts with Issuing

Learn how to create a virtual bank account via APIs in 3 simple steps. Please note that virtual accounts are delivered instantly after creation.

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": "22157914900",
      "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"
    },
    {
      "address": {
        "country": "nigeria",
        "state": "lagos",
        "lga": "ikeja",
        "city": "lagos",
        "address_line1": "banana island"
      },
      "phone": "07030841956",
      "entity": "INDIVIDUAL",
      "business": {
        "name": "Nipek",
        "id": "6172811205af5c47a1f31e49"
      },
      "app": {
        "name": "Issuing",
        "id": "60ffd3fee03417c574fa1f55"
      },
      "live": false,
      "created_at": "2021-12-01T08:45:57.227Z",
      "updated_at": "2021-12-01T08:45:57.227Z",
      "id": "61a73645c2d313658ce82d44",
      "first_name": "olayinka",
      "last_name": "isaiah"
    },
    {
      "address": {
        "country": "nigeria",
        "state": "lagos",
        "lga": "lga",
        "city": "lag",
        "address_line1": "banana island",
        "postal_code": "100001"
      },
      "phone": "08030841956",
      "entity": "INDIVIDUAL",
      "business": {
        "name": "Nipek",
        "id": "6172811205af5c47a1f31e49"
      },
      "app": {
        "name": "Issuing",
        "id": "60ffd3fee03417c574fa1f55"
      },
      "live": false,
      "created_at": "2021-12-01T08:45:52.804Z",
      "updated_at": "2021-12-01T08:45:52.804Z",
      "identity": {
        "type": "INTERNATIONAL_PASSPORT",
        "number": "212123232321",
        "url": "https://mono-business-assets.s3.eu-west-2.amazonaws.com/identity-FunVlKB_OKMHuQFLCT5ek-test_1.png"
      },
      "id": "61a73640c2d313658ce82d3e",
      "first_name": "olayinka",
      "last_name": "isaiah",
      "selfie_url": "https://mono-business-assets.s3.eu-west-2.amazonaws.com/identity-FunVlKB_OKMHuQFLCT5ek-test_1.png"
    },
    {
      "address": {
        "country": "nigeria",
        "state": "lagos",
        "lga": "island",
        "city": "lagos",
        "address_line1": "banana island",
        "address_line2": "nipek world",
        "postal_code": "10001"
      },
      "phone": "09030841956",
      "entity": "INDIVIDUAL",
      "business": {
        "name": "Nipek",
        "id": "6172811205af5c47a1f31e49"
      },
      "app": {
        "name": "Issuing",
        "id": "60ffd3fee03417c574fa1f55"
      },
      "live": false,
      "created_at": "2021-12-01T08:45:47.554Z",
      "updated_at": "2021-12-02T11:47:13.737Z",
      "bvn": "232323232323232",
      "email": "[email protected]",
      "identity": {
        "type": "INTERNATIONAL_PASSPORT",
        "number": "212123232321",
        "url": "https://mono-business-assets.s3.eu-west-2.amazonaws.com/identity-FunVlKB_OKMHuQFLCT5ek-test_1.png"
      },
      "id": "61a7363bc2d313658ce82d38",
      "first_name": "olayinka",
      "last_name": "isaiah",
      "selfie_url": "https://mono-business-assets.s3.eu-west-2.amazonaws.com/identity-FunVlKB_OKMHuQFLCT5ek-test_1.png"
    },
    {
      "address": {
        "country": "nigeria",
        "state": "lagos",
        "lga": "lga",
        "city": "lag",
        "address_line1": "banana island",
        "postal_code": "100001"
      },
      "phone": "03030841956",
      "entity": "INDIVIDUAL",
      "business": {
        "name": "Nipek",
        "id": "6172811205af5c47a1f31e49"
      },
      "app": {
        "name": "Issuing",
        "id": "60ffd3fee03417c574fa1f55"
      },
      "live": false,
      "created_at": "2021-12-01T08:45:21.354Z",
      "updated_at": "2021-12-01T08:45:21.354Z",
      "identity": {
        "type": "INTERNATIONAL_PASSPORT",
        "number": "212123232321",
        "url": "https://mono-business-assets.s3.eu-west-2.amazonaws.com/identity-FunVlKB_OKMHuQFLCT5ek-test_1.png"
      },
      "id": "61a73621c2d313658ce82d32",
      "first_name": "olayinka",
      "last_name": "isaiah",
      "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",
    "collection": false // optional
}'
{
  "status": "success",
  "message": "Virtual account creation is been processed",
  "data": {
    "id": "61a74cd4644e048825068341"
  }
}

📘

NOTES

  • Mono returns an account object upon creation, and sends the issuing.virtual_account_created webhook event.
  • All credits made to the collection virtual account will be settled to the partner's bank account at end of the day.
  • Transfer 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.

KYC level 1

KYC level 2

KYC level 3

Account balance limit

1M

10M

Unlimited

Physical Cards Request

No

Yes

Yes

Requirements

N/A

BVN

BVN, ID type, ID Number, and ID URL

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

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

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?