Skip to main content
Use this endpoint to look up the latest data for a static or dynamic virtual account. It returns the account number, status, expiry information, and the customer profile you attached during creation.

​
Endpoint

GET {{baseURL}}/v1/virtual-account/{virtualAccountId}

​
Request headers

HeaderDescriptionRequiredExample
x-api-keyWorkspace API key for authentication.✅ YesYOUR_API_KEY
Content-TypeMedia type of the request.Optionalapplication/json

​
Path parameters

ParameterTypeDescriptionRequiredExample
virtualAccountIdStringUnique identifier returned when the account was created.✅ Yes30fe4022-09da-46fb-bafa-xxxxxxxxxxxxx
You can obtain the virtualAccountId from the response of the static or dynamic account creation endpoints.

​
Request examples

curl --request GET '{{baseURL}}/v1/virtual-account/30fe4022-09da-46fb-bafa-xxxxxxxxxxxxx' \
  --header 'x-api-key: YOUR_API_KEY'

​
Successful response

copy
{
  "message": "virtual account fetched successfully",
  "status": "success",
  "data": {
    "id": "30fe4022-09da-46fb-bafa-xxxxxxxxxxxxx",
    "firstName": "John",
    "lastName": "Jonathan",
    "email": "[email protected]",
    "phoneNumber": "+2348123XXXX",
    "reference": "REF_YERT8JPXXXXXX",
    "account": {
      "name": "NNDDD",
      "bankName": "Sterling Bank",
      "sortCode": null,
      "number": "88178XXXXX"
    },
    "status": "ACTIVE",
    "currency": "NGN",
    "country": "NG",
    "isPermanent": false,
    "expiryTime": 1751221691,
    "created": "2025-06-26T17:46:11.636Z",
    "expired": "2025-06-26T17:46:11.636Z"
  }
}

​
Response fields

FieldTypeDescription
data.account.numberStringVirtual bank account number customers use to pay you.
data.account.bankNameStringIssuing bank for the account.
data.statusStringCurrent state (ACTIVE, EXPIRED, etc.).
data.isPermanentBooleantrue for static accounts, false for dynamic.
data.expiryTimeNumberUnix timestamp when a dynamic account expires (null for static).
data.expiredStringISO timestamp set when the account expires.

​
Error responses

StatusMessageCauseNext steps
401API key missing or incorrectMissing/invalid API key in the request header.Include the correct x-api-key for the workspace/environment.
404Virtual account ID not foundThe supplied virtualAccountId does not exist or belongs to another workspace.Confirm you are using a valid ID from a created account.
500Service temporarily unavailableBackend system downtime or unexpected server error.Retry with exponential backoff or contact support if it continues.

​
Usage tips

  • Use this endpoint to refresh the account status before showing details to a customer-facing UI.
  • Combine it with payment webhooks to confirm final settlement timestamps for reconciliation.
  • Archive or anonymise responses containing PII according to your data retention policy.