Virtual accounts

Create a virtual account number

Create Virtual Account Numbers for your Users

post https://api.flutterwave.com/v3/virtual-account-numbers

Body Params

email string

The email address of the customer.

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

var axios = require('axios');
var data = JSON.stringify({
  "email": "developers@flutterwavego.com",
    "is_permanent": true,
    "bvn": "12345678901",
    "tx_ref": "VA12",
    "phonenumber": "0800000000",
    "firstname": "Angela",
    "lastname": "Ashley",
    "narration": "Angela Ashley-Osuzoka"
});

var config = {
  method: 'post',
  url: 'https://api.flutterwave.com/v3/virtual-account-numbers',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{{BASE_API_URL}}/virtual-account-numbers',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "email": "developers@flutterwavego.com",
    "is_permanent": true,
    "bvn": 12345678901,
    "tx_ref": "VA12",
    "phonenumber": 0800000000,
    "firstname": "Angela",
    "lastname": "Ashley",
    "narration": "Angela Ashley-Osuzoka"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {SEC_KEY}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/virtual-account-numbers")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {SEC_KEY}"
request.body = '{\n    \"email\": \"developers@flutterwavego.com\",\n    \"is_permanent\": true,\n    \"bvn\": \"22169541783\",\n    \"tx_ref\": \"VA12\",\n    \"phonenumber\": \"0800000000\",\n    \"firstname\": \"Angela\",\n    \"lastname\": \"Ashley\",\n    \"narration\": \"Angela Ashley-Osuzoka\"\n}'

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Virtual account created",
  "data": {
    "response_code": "02",
    "response_message": "Transaction in progress",
    "flw_ref": "FLW-da93010f630240a7978e893af92fed62",
    "order_ref": "URF_1613406439309_370935",
    "account_number": "7824822527",
    "frequency": "N/A",
    "bank_name": "WEMA BANK",
    "created_at": "2021-02-15 16:27:22",
    "expiry_date": "N/A",
    "note": "Please make a bank transfer to CollinX Akpevwe Omokri",
    "amount": null
  }
}

{}

Create bulk virtual account numbers

This shows you how to create bulk virtual account numbers

post https://api.flutterwave.com/v3/bulk-virtual-account-numbers

Body Params

accounts int32

This is the number of virtual account numbers you want to generate

email string

This could be a generic email address

is_permanent boolean

This allows you create a static account number i.e. it doesn't expire

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

var axios = require('axios');
var data = JSON.stringify({
  "accounts":5,
  "email":"sam@son.com",
  "is_permanent":true,
  "tx_ref":"jhn-mndkn-012439283422"
});

var config = {
  method: 'post',
  url: 'https://api.flutterwave.com/v3/bulk-virtual-account-numbers',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/bulk-virtual-numbers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>'{\n    \"accounts\": 5,\n    \"email\": \"sam@son.com\",\n    \"is_permanent\": true,\n    \"tx_ref\": \"jhn-mndkn-012439283422\"\n}',
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: Bearer {SEC_KEY}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/bulk-virtual-numbers")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {SEC_KEY}"
request.body = "{\n    \"accounts\": 5,\n    \"email\": \"sam@son.com\",\n    \"is_permanent\": true,\n    \"tx_ref\": \"jhn-mndkn-012439283422\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Bulk virtual accounts creation queued",
  "data": {
    "batch_id": "-RND_2641579516055928",
    "response_code": "02",
    "response_message": "Request added to Queue"
  }
}

{}

Get a virtual account number

This allows you to fetch a virtual account number using order reference

get https://api.flutterwave.com/v3/virtual-account-numbers/{order_ref}

Path Params

order_ref string

This is the order reference returned in the virtual account number creation

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

var axios = require('axios');


var config = {
  method: 'GET',
  url: '{{BASE_API_URL}}/virtual-account-numbers/-RND_2641579516055928',
  headers: { 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/virtual-account-numbers/URF_1579513580629_5981535",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {SEC_KEY}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/virtual-account-numbers/URF_1579513580629_5981535")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer {SEC_KEY}"

response = http.request(request)
puts response.read_body

{
    "status": "success",
  "message": "Virtual nuban fetched",
  "data": {
    "response_code": "02",
    "response_message": "Transaction in progress",
    "flw_ref": "FLW-9b04c88aaf2244379f256691836fd9c9",
    "order_ref": "URF_1579513580629_5981535",
    "account_number": "7826463244",
    "frequency": "5",
    "bank_name": "WEMA BANK",
    "created_at": "2020-01-20 09:46:23",
    "expiry_date": "2020-01-25 23:59:59",
    "note": "Please make a bank transfer to Earth Gang",
    "amount": 50700
  }
}

{}

Get bulk virtual account details

This allows you to fetch bulk virtual account numbers using batch id

get https://api.flutterwave.com/v3/bulk-virtual-account-numbers/{batch_id}

Path Params

batch_id string

This is the batch ID returned in the bulk virtual account numbers creation

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

var axios = require('axios');


var config = {
  method: 'GET',
  url: '{{BASE_API_URL}}/bulk-virtual-account-numbers/-RND_2641579516055928',
  headers: { 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/bulk-virtual-numbers/-RND_2641579516055928",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {SEC_KEY}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/bulk-virtual-numbers/-RND_2641579516055928")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer {SEC_KEY}"

response = http.request(request)
puts response.read_body

{
    "status": "success",
  "message": "Bulk virtual accounts fetched",
  "data": [
    {
      "response_code": "02",
      "response_message": "Transaction in progress",
      "flw_ref": "FLW-f2be3dfeb4fb4f1eb95c236b3129ef0c",
      "order_ref": "URF_1579516057896_3120635",
      "account_number": "7827737349",
      "frequency": "N/A",
      "bank_name": "WEMA BANK",
      "created_at": "2020-01-20 10:27:38",
      "expiry_date": "N/A",
      "note": "Please make a bank transfer to Earth Gang",
      "amount": null
    },
    {
      "response_code": "02",
      "response_message": "Transaction in progress",
      "flw_ref": "FLW-6117c6e877e34f7e80b76268ce73bb69",
      "order_ref": "URF_1579516058932_17235",
      "account_number": "7827554918",
      "frequency": "N/A",
      "bank_name": "WEMA BANK",
      "created_at": "2020-01-20 10:27:39",
      "expiry_date": "N/A",
      "note": "Please make a bank transfer to Earth Gang",
      "amount": null
    },
    {
      "response_code": "02",
      "response_message": "Transaction in progress",
      "flw_ref": "FLW-590fb41034b24dcd9f822f2c02c3cf98",
      "order_ref": "URF_1579516059900_4435935",
      "account_number": "7827619600",
      "frequency": "N/A",
      "bank_name": "WEMA BANK",
      "created_at": "2020-01-20 10:27:40",
      "expiry_date": "N/A",
      "note": "Please make a bank transfer to Earth Gang",
      "amount": null
    },
    {
      "response_code": "02",
      "response_message": "Transaction in progress",
      "flw_ref": "FLW-8e3fb79bb27040d69da1dbe467da8e7c",
      "order_ref": "URF_1579516060920_1225335",
      "account_number": "7827266267",
      "frequency": "N/A",
      "bank_name": "WEMA BANK",
      "created_at": "2020-01-20 10:27:41",
      "expiry_date": "N/A",
      "note": "Please make a bank transfer to Earth Gang",
      "amount": null
    },
    {
      "response_code": "02",
      "response_message": "Transaction in progress",
      "flw_ref": "FLW-1a5264671801416ba09211d0142f0bd1",
      "order_ref": "URF_1579516061920_4339335",
      "account_number": "7827342397",
      "frequency": "N/A",
      "bank_name": "WEMA BANK",
      "created_at": "2020-01-20 10:27:42",
      "expiry_date": "N/A",
      "note": "Please make a bank transfer to Earth Gang",
      "amount": null
    }
  ]
}

{}

Update BVN

This endpoint is to be used to update the BVN of previously created virtual accounts.

put https://api.flutterwave.com/v3/virtual-account-numbers/{order_ref}

Path Params

order_ref string

This is the order reference returned in the virtual account number creation

Body Params

bvn string

This is only required for static accounts It should be BVN number tied to the user the account number is being generated for

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

var axios = require('axios');


var config = {
  method: 'PUT',
  url: '{{BASE_API_URL}}/virtual-account-numbers/URF_1614726073701_5993735',
  headers: { 
    "Content-Type": "application/json",
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
  data : JSON.stringify({"bvn":"12345678901"}),
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.flutterwave.com/v3/virtual-account-numbers/URF_1614726073701_5993735',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
    "bvn": "12345678901"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer FLWSECK-xxxxxx-X'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("https://api.flutterwave.com/v3/virtual-account-numbers/URF_1614726073701_5993735")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer FLWSECK-xxxxxx-X"
request.body = "{\n    \"bvn\": \"12345678901\"\n}"

response = https.request(request)
puts response.read_body

{
    "status": "success",
  "message": "BVN was updated for Virtual account",
  "data": null
}

{
    "status": "error",
  "message": " A BVN already linked to account. Error updating BVN",
  "data": null
}

Delete a Virtual account

post https://api.flutterwave.com/v3/virtual-account-numbers/:order_ref

Path Params

order_ref string

This is the order reference returned in the virtual account number creation

Body Params

status string

This is the status to set for the deleted virtual account. Expected value: inactive.

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

var axios = require('axios');


var config = {
  method: 'POST',
  url: 'https://api.flutterwave.com/v3/virtual-account-numbers/URF_1628865217526_1284135',
  headers: { 
    "Content-Type": "application/json",
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
  data : JSON.stringify({ "status": "inactive"}),
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

});

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.flutterwave.com/v3/virtual-account-numbers/URF_1628865217526_1284135');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer FLWSECK_TEST-8fxxxxxxxxxxxxxxxxxxxxxxxxxxxe-X',
  'Content-Type' => 'application/json'
));
$request->setBody('{\n    "status": "inactive"\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

require "uri"
require "net/http"

url = URI("https://api.flutterwave.com/v3/virtual-account-numbers/URF_1628865217526_1284135")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer FLWSECK_TEST-8fxxxxxxxxxxxxxxxxxxxxxxxxxxxe-X"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "status": "inactive"
})

response = https.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Virtual Account Number status has been updated",
  "data": {
    "status": "00",
    "status_desc": "Deactivated successfully"
  }
}

{
  "status": "error",
  "message": "status is required",
  "data": null
}

Virtual accounts

API Reference

Endpoints

Create a virtual account number

Body Params

Headers

Create bulk virtual account numbers

Body Params

Headers

Get a virtual account number

Path Params

Headers

Get bulk virtual account details

Path Params

Headers

Update BVN

Path Params

Body Params

Headers

Delete a Virtual account

Path Params

Body Params

Headers