DocumentationRecipesAPI ReferencesSupportBlog
Documentation

NGN Virtual Accounts

Learn how to create and manage a Nigerian Virtual Account.

Suggest Edits

🚧

Feature Availability

This feature is currently available to Nigerian merchants only. If you're a non-Nigerian merchant, you'll need to have the feature enabled on your account. To request activation, please email [email protected].

Creating a Dynamic Virtual Account

To create a virtual account, send a request to the create virtual account endpoint, specifying an amount greater than zero and the customer's email.

The response will have a response_code of 02 and a response_message of "Transaction in progress", indicating that the account number has been successfully created, and we're ready to accept payments for you. The response body will also contain the bank name and account number. You can display these details to your customer to facilitate payment via bank transfer

curl --request POST 'https://api.flutterwave.com/v3/virtual-account-numbers' \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email":"[email protected]",
    "amount": 100,
    "tx_ref":"apex_tx-002201",
    "phonenumber":"08100000000",
    "firstname":"John",
    "lastname":"Doe",
    "narration":"Kids Foundation"
}'


{
    "status": "success",
    "message": "Virtual account created",
    "data": {
        "response_code": "02",
        "response_message": "Transaction in progress",
        "flw_ref": "FLW-d3f049dad861484a9e1504309e07f615",
        "order_ref": "URF_1726598678168_8608035",
        "account_number": "9949162075",
        "frequency": "N/A",
        "bank_name": "WEMA BANK",
        "created_at": "2024-09-17 18:44:38",
        "expiry_date": "2024-09-17 19:44:38",
        "note": "Please make a bank transfer to testing functions FLW",
        "amount": "101.40"
    }
}

Once the customer completes a payment, we will send a webhook to notify you of the transaction status.

🚧

Creating a Static NGN Virtual Account

To create a static NGN Virtual Account, you need your customer's NIN or BVN.

Creating a Static Virtual Account

You can generate a virtual account with this endpoint, which is supported in our backend SDKs. You will need to specify the email to be associated with the account number (the customer's email). If you're creating a static virtual number, their bvn will be required.

curl --request POST 'https://api.flutterwave.com/v3/virtual-account-numbers' \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email":"[email protected]",
    "tx_ref":"apex_tx_ref-002201",
    "phonenumber":"08100000000",
    "is_permanent": true,
    "firstname":"John",
    "lastname":"Doe",
    "narration":"Kids Foundation",
    "bvn": "1234567890"
}'


// Install with: composer require flutterwavedev/flutterwave-v3

$flw = new \Flutterwave\Rave(getenv('FLW_SECRET_KEY')); // Set `PUBLIC_KEY` as an environment variable
$virtualAccountsService = new \Flutterwave\VirtualAccount();
$details = [
    "email" => "[email protected]",
    "tx_ref" =>"apex_tx_ref-002201",
    "phonenumber" => "08100000000",
    "is_permanent" => true,
    "firstname" =>"Flutterwave",
    "lastname" => "Developers",
    "narration" =>"Kids Foundation",
    "bvn" => "1234567890"
];
$response = $virtualAccountsService->createVirtualAccount($details);

# Install with: pip install rave_python

import os
from rave_python import Rave

rave = Rave(os.getenv("FLW_PUBLIC_KEY"), os.getenv("FLW_SECRET_KEY"))
res = rave.VirtualAccount.create({
    "email": "[email protected]",
  	"tx_ref":"apex_tx_ref-002201",
    "phonenumber":"08100000000",
    "is_permanent": true,
    "firstname":"Flutterwave",
    "lastname":"Developers",
    "narration":"Kids Foundation",
    "bvn": "1234567890"
})
print(res)

{
    "status": "success",
    "message": "Virtual account created",
    "data": {
        "response_code": "02",
        "response_message": "Transaction in progress",
        "flw_ref": "FLW-211b4eea7b3d465d8797fa354c127f79",
        "order_ref": "URF_1726608838391_595235",
        "account_number": "8548497837",
        "frequency": "N/A",
        "bank_name": "WEMA BANK",
        "created_at": "2024-09-17 21:33:58",
        "expiry_date": "N/A",
        "note": "Please make a bank transfer to Hefa Cust No.20 FLW",
        "amount": "0.00"
    }
}

{
  "status": "error",
  "message": "BVN is required for static account number",
  "data": null
}

There are more options available when generating static virtual accounts. You can also set the following:

ParametersDefinition
amountThe amount to be collected per transaction.
frequencyThe number of times the account can be used before expiring.
narrationThe name should be shown when the account details are fetched.
tx_refThe transaction reference that should be returned whenever a transfer is made into the account.

Additionally, you can create virtual accounts in bulk and retrieve their details at any time. For more details, see the API reference.

🚧

Handling Underpayments and Overpayments

If a customer sends less than the expected amount (an underpayment) to an NGN virtual account, the amount is automatically refunded. If a customer sends more than the expected amount (an overpayment), the extra amount is refunded to the sender after the correct transaction amount is processed.

This applies to transfers from all NGN banks except Fidelity Bank. For Fidelity Bank, any mismatch between the expected and actual amount will cause the transaction to fail.

Virtual Account Webhooks

When ever a transfer is made to the virtual account, we'll send you a webhook that looks like this:

{
  "event": "charge.completed",
  "data": {
    "id": 1549596704,
    "tx_ref": "apex_tx_ref-002201",
    "flw_ref": "000030240917214228820592962026",
    "device_fingerprint": "N/A",
    "amount": 100,
    "currency": "NGN",
    "charged_amount": 101.4,
    "app_fee": 1.4,
    "merchant_fee": 0,
    "processor_response": "success",
    "auth_model": "AUTH",
    "ip": "::ffff:172.16.85.133",
    "narration": "Kids Foundation",
    "status": "successful",
    "payment_type": "bank_transfer",
    "created_at": "2024-09-17T20:47:20.000Z",
    "account_id": 47337,
    "customer": {
      "id": 980070204,
      "name": "Flutterwave Developers",
      "phone_number": "08100000000",
      "email": "[email protected]",
      "created_at": "2024-09-17T20:38:43.000Z"
    }
  },
  "event.type": "BANK_TRANSFER_TRANSACTION"
}

Now, your webhook handler can handle the event and credit the customer's wallet. For help setting up webhooks, see our guide on webhooks.

Creating Bulk Virtual Accounts.

You can now easily generate bulk static virtual accounts for your customers with just a single request. This is important if you’re managing a large customer base or need to streamline payment collections.

To get started, provide the following three details:

  • nin (National Identification Number) or BVN (Bank Verification Number): This verifies the customer’s identity.
  • firstname: The customer’s first name.
  • lastname: The customer’s last name.

To create bulk virtual accounts, make a POST request to the bulk virtual account endpoint with the following parameters:

  • batch_ref: A unique reference to identify the current batch.
  • narration (optional): Provides context or the reason for the request.
  • bulk_data: A list containing virtual account details for each customer. Each entry should include:
  • firstname: Customer’s first name.
  • lastname: Customer’s last name.
  • email: Customer’s email address.
  • bvn or nin: Customer’s Bank Verification Number or National Identification Number.
  • is_permanent: Set to true for a static virtual account.
curl -X POST 'https://api.flutterwave.com/v3/bulk-virtual-account-numbers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer FLWSECK_TEST-XXXXXXXXXXXXXXXXXXXXXXXXXX-X' \
--data-raw '{
    "batch_ref": "Bulk-VA-RWIESDP1",
    "narration": "Subscription Accounts 2025-01-05",
    "bulk_data": [
        {
            "bvn": "12345678912",
            "firstname": "Jane",
            "lastname": "Doe",
            "email": "[email protected]",
            "is_permanent": true
        },
        {
            "bvn": "12345678912",
            "email": "[email protected]",
            "firstname": "John",
            "lastname": "Doe",
            "is_permanent": true
        }
    ]
}
'

On a successful request, your response should include the following:

  • batch_id: A unique identifier for the batch. You can use this to retrieve the generated virtual accounts.
  • response_code: Indicates whether the request has been acknowledged. This should return the value "02".
  • response_message: Confirms that the request will be processed.
{
    "status": "success",
    "message": "Bulk virtual accounts creation queued",
    "data": {
        "batch_id": "-RND_4651739890196713",
        "response_code": "02",
        "response_message": "Request added to Queue"
    }
}

To retrieve the newly created virtual accounts, pass the batch_id returned from the bulk request as a path parameter to the get bulk account endpoint.

curl -X GET 'https://api.flutterwave.com/v3/bulk-virtual-account-numbers/-RND_4651739890196713' \
--header 'Authorization: ••••••'


{
    "status": "success",
    "message": "Bulk virtual accounts fetched",
    "data": {
        "virtual_accounts": [
            {
                "response_code": "02",
                "response_message": "Transaction in progress",
                "flw_ref": "NFKW801617398049775989437",
                "order_ref": "URF_1739804838924_8401035",
                "account_number": "8520074870",
                "account_status": "ACTIVE",
                "frequency": "N/A",
                "bank_name": "Sterling BANK",
                "created_at": "2025-02-17 16:09:37",
                "expiry_date": "N/A",
                "note": "Please make a bank transfer to Jane Doe FLW",
                "amount": "0.00"
            },
            {
                "response_code": "02",
                "response_message": "Transaction in progress",
                "flw_ref": "MSAX8174173980497760559657",
                "order_ref": "URF_1739804838924_398835",
                "account_number": "8520155462",
                "account_status": "ACTIVE",
                "frequency": "N/A",
                "bank_name": "Sterling BANK",
                "created_at": "2025-02-17 16:09:37",
                "expiry_date": "N/A",
                "note": "Please make a bank transfer to John Doe FLW",
                "amount": "0.00"
            }
       ]
    }
}

Updated 12 days ago