Skip to main content
POST
/
virtual-accounts
Create a virtual account
curl --request POST \
  --url https://developersandbox-api.flutterwave.com/virtual-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference": "<string>",
  "customer_id": "cus_J0PvwvJB2n",
  "amount": 1000,
  "currency": "NGN",
  "account_type": "static",
  "expiry": 360,
  "meta": {},
  "narration": "James Burgers",
  "bvn": "12345678912",
  "nin": "12345678912",
  "customer_account_number": "123456789"
}
'
{
  "status": "success",
  "message": "<string>",
  "data": {
    "id": "",
    "amount": 1000,
    "account_number": "7824822527",
    "reference": "htuy68787hvhyff454",
    "account_bank_name": "WEMA BANK",
    "account_type": "static",
    "status": "active",
    "account_expiration_datetime": "2025-12-03T13:54:21.546559974Z",
    "note": "Please make a bank transfer to James Burgers",
    "customer_id": "cus_J0PvwvJB2n",
    "created_datetime": "2024-12-03T13:54:21.546559974Z",
    "meta": {},
    "customer_reference": "AEGP2345",
    "currency": "NGN"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Trace-Id
string

A unique identifier to track this operation. It must be between 12 and 255 characters in length.

Required string length: 12 - 255
​
X-Idempotency-Key
string

A unique identifier to prevent duplicate requests. It must be between 12 and 255 characters in length.

Required string length: 12 - 255
​
X-Scenario-Key
string

An optional scenario key that can be used to simulate specific behaviors or test different scenarios within the API. Providing this header allows you to trigger predefined responses or alter data based on the key's value, which can be useful for testing, development, or demonstrating specific functionalities. The key should be a string of 1 to 1000 characters.

Body

application/json
​
reference
string
required

A custom identifier to track the transaction, This must be unique across all your transactions.

Required string length: 6 - 42
Pattern: ^[a-zA-Z0-9\-]+$
​
customer_id
string
required

The customer id

Example:

"cus_J0PvwvJB2n"

​
amount
number<decimal>
required

The amount to be collected. Specify 0 for static accounts.

Example:

1000

​
currency
enum<string>
required

ISO 4217 currency code.

Available options:
NGN,
GHS,
EGP,
KES
Example:

"NGN"

​
account_type
enum<string>
required

The type of virtual account.

Available options:
static,
dynamic
Example:

"static"

​
expiry
integer

The expiry time of the virtual account.

Required range: 60 <= x <= 31536000
Example:

360

​
meta
object
​
narration
string

This allows you specify the name shown when the account is resolved.

Example:

"James Burgers"

​
bvn
string

This is the customer's Bank Verification Number.

Pattern: ^[1-9][0-9]{10}$
Example:

"12345678912"

​
nin
string

This is the customer's National Identity Number.

Pattern: ^[1-9][0-9]{10}$
Example:

"12345678912"

​
customer_account_number
string

This is the bank account the transfer will originate from. required for EGP and KES

Example:

"123456789"

Response

OK

​
status
enum<string>
Available options:
success,
failed
​
message
string
​
data
object