Get Virtual Account

The Get Virtual Account endpoint allows you to retrieve the details of a specific virtual account by using its unique ID.

Requirements

To use this endpoint, ensure that:

Your API key is active and correctly configured.
You provide the VirtualAccountId of the virtual account you wish to query.

Endpoint

GET /v1/virtual-account/{VirtualAccountId}

Headers

Header	Type	Description	Required
`x-api-key`	String	Your API key for authentication.	✅ Yes

Path Parameters

Parameter	Type	Description	Required
`VirtualAccountId`	String	The unique identifier of the virtual account you want to retrieve.	✅ Yes

💡

The {VirtualAccountId} in the endpoint URL should be replaced with the actual ID of the virtual account you want to look up.

Sample Request

curl --location '{{}baseURL}v1/virtual-account/{VirtualAccountId} \
--header 'x-api-key: YOUR_API_KEY_HERE'

Responses

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

Response (200 OK)

{
    "message": "virtual account fetched successfully",
    "status": "success",
    "data": {
        "id": "30fe4022-09da-46fb-bafa-xxxxxxxxxxxxxx",
        "firstName": "John",
        "lastName": "Jonathan",
        "email": "someexample@gmail.com",
        "phoneNumber": "+2348123XXXX",
        "bvn": "********",
        "reference": "REF_YERT8JPXXXXXX",
        "account": {
            "name": "NNDDD",
            "bankName": "Sterling BANK",
            "sortCode": null,
            "number": "88178XXXXX"
        },
        "status": "ACTIVE", 
        "currency": "NGN",
        "country": "NG",
        "isPermanent": false,
        "expiryTime": 10,
        "created": "2025-06-26T17:46:11.636164",
        "expired": "2025-06-26T17:46:11.636164"
    }
}

Response Body Breakdown

Virtual Account Data

This object contains the details of the retrieved virtual account.

Field	Type	Description
`id`	String	Unique identifier for the virtual account resource.
`firstName`	String	The first name of the account holder.
`lastName`	String	The last name of the account holder.
`email`	String	The email address of the account holder.
`phoneNumber`	String	The phone number of the account holder.
`bvn`	String	The masked Bank Verification Number (BVN) of the account holder.
`reference`	String	The unique reference associated with the account.
`account.name`	String	The name on the virtual bank account.
`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 virtual account number.
`status`	String	The current status of the account (e.g., `ACTIVE` or `INACTIVE`).
`currency`	String	The currency code for the account.
`country`	String	ISO 3166-1 alpha-2 country code.
`isPermanent`	Boolean	A flag indicating if the account is permanent (`true`) or dynamic (`false`).
`expiryTime`	Number	Unix timestamp indicating when the account will expire.
`created`	String	ISO 8601 timestamp of when the account was created.
`expired`	String	ISO 8601 timestamp of when the account expired. Only appears for dynamic accounts.

Dynamic Virtual Account Understanding Ramp