Create Dynamic Virtual Account

The Dynamic Virtual Account endpoint allows merchants to create a temporary, time-bound virtual account number for a specific transaction. These accounts are designed for single-use payments and expire after a defined period.

Requirements

To use this endpoint, ensure that:

Your API key is active and IP whitelisting is correctly configured.
You provide a unique reference value for each creation request to ensure idempotency.
The specified amount, currency and duration are valid.

Endpoint

POST /v1/virtual-account/dynamic

Headers

Header	Type	Description	Required
`Content-Type`	String	Must be `application/json`.	✅ Yes
`x-api-key`	String	Your API key for authentication.	✅ Yes

Supported Currencies for Virtual Account

S/N	Country	Country Code	Currency
1	Nigeria 🇳🇬	NG	NGN
2	Malawi 🇲🇼	MW	MWK

💡

You can change the currency and country values in your request to match any of the supported options.

Sample Request

curl --location '{{}baseURL}v1/virtual-account/dynamic' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--data-raw '{
    "currency": "NGN",
    "country": "NG",
    "amount": 5000,
    "duration": 30,
    "reference": "TXN_REF_DYNAMIC_12345678"
}'

Request Body

Field	Type	Description	Required
`currency`	String	Currency code (defaults to `NGN`).	✅ Yes
`country`	String	Country code (defaults to `NG`).	✅ Yes
`amount`	Number	The exact amount expected for the transaction.	✅ Yes
`duration`	Integer	The time in minutes for which the account will remain active (defaults to 60).	✅ Yes
`reference`	String	A unique reference for the transaction.	✅ Yes

Responses

A successful request returns a 200 OK status and the temporary virtual account details.

Response (200 OK)

{
  "message": "virtual account created successfully",
  "status": "success",
  "data": {
    "id": "30fe4022-09da-46fb-bafa-39b97f5d9bf6",
    "reference": "TXN_REF_DYNAMIC_12345678",
    "account": {
      "bankName": "Sterling BANK",
      "sortCode": null,
      "number": "8817835350"
    },
    "expiryTime": 1751221691,
    "status": "ACTIVE",
    "currency": "NGN",
    "country": "NG",
    "created": "2025-06-26T17:46:11.636163698"
  }
}

Response Body Breakdown

Dynamic Account Data

This object contains the details of the successfully created temporary virtual account.

Field	Type	Description
`id`	String	Unique identifier for the virtual account resource.
`reference`	String	The unique reference passed during account creation.
`account.bankName`	String	The name of the bank providing the virtual account.
`account.sortCode`	String	The sort code of the bank (may be `null`).
`account.number`	String	The generated virtual account number.
`expiryTime`	Number	Unix timestamp indicating when the account will expire and become inactive.
`status`	String	The current status of the virtual account (e.g., `ACTIVE`).
`currency`	String	The currency code for the account.
`country`	String	ISO 3166-1 alpha-2 country code.
`created`	String	ISO 8601 timestamp of when the account was created.

Webhooks

While creating a dynamic virtual account does not trigger a webhook, payments made to the account do.

virtualaccount.completed: Sent when a payment to the account is successful.
virtualaccount.failed: Sent when a payment to the account fails.

Refer to the main Webhooks documentation for detailed payload structures.

Important Notes:

The reference must be unique per request to ensure idempotency.

The duration is specified in minutes.

The returned account.number is only valid for a payment matching the specified amount.

The account will become invalid for payments after the expiryTime has passed.

Static Virtual Account Understanding Ramp