Sign in

v1

latestOpenAPI 3.1.02026-07-2656258207.2 KB
Virtual-Accounts

Create a virtual account

Create a virtual account

post/virtual-accounts

Headers

X-Trace-Idstring

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

X-Idempotency-Keystring

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

X-Scenario-Keystring

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.

Request body

referencestring required

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

customer_idstring required

The customer id

amountnumber required

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

expiryinteger

The expiry time of the virtual account.

currency'NGN' | 'GHS' | 'EGP' | 'KES' | 'MAD' | 'ZAR' required

ISO 4217 currency code.

account_type'static' | 'dynamic' required

The type of virtual account.

metaMeta
narrationstring

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

bvnstring

This is the customer's Bank Verification Number.

ninstring

This is the customer's National Identity Number.

customer_account_numberstring

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

merchant_vat_amountnumber
bank_codestring

The bank code.

Example request

{
  "customer_id": "cus_J0PvwvJB2n",
  "amount": 1000,
  "expiry": 360,
  "currency": "NGN",
  "account_type": "static",
  "narration": "James Burgers",
  "bvn": "12345678912",
  "nin": "12345678912",
  "customer_account_number": "123456789",
  "merchant_vat_amount": 22.7,
  "bank_code": "090772"
}

Response

OK

status'success' | 'failed'
messagestring

Example response

{
  "data": {
    "amount": 1000,
    "account_number": "7824822527",
    "reference": "htuy68787hvhyff454",
    "account_bank_name": "WEMA BANK",
    "account_type": "static",
    "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",
    "customer_reference": "AEGP2345",
    "currency": "NGN",
    "narration": "James Burgers"
  }
}