Create Virtual Account

Create a virtual account for the authenticated business. A multi_use account is permanent and must not carry an expiry; a single_use account is time bound and requires expires_at. Accounts are always provisioned in NGN, and the account settles into the business collection wallet.

Authorization

BearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

account_type*string

Value in"single_use" | "multi_use"

account_name*string

Name shown to payers on transfer.

Length3 <= length <= 250

source_reference*string

Unique reference for the source of the virtual account.

Length3 <= length <= 250

amount?|

Optional fixed amount expected on this account. Omit to accept any amount.

Formatfloat

expires_at?|

Required for single_use, prohibited for multi_use. Must be in the future and within the configured expiry window (24 hours by default).

Formatdate-time

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/virtual-account" \  -H "Content-Type: application/json" \  -d '{    "account_type": "single_use",    "account_name": "Acme Store",    "source_reference": "src_1234567890"  }'

{
  "requestId": "abcd1234-5678-90ef-ghij-1234567890kl",
  "requestTimestamp": "2026-07-20 09:15:00",
  "message": "Virtual account created successfully.",
  "statusCode": 201,
  "data": {
    "id": "019a1639-ce25-70b7-ab20-16fcb2bac023",
    "businessId": "019a1639-ce25-70b7-ab20-16fcb2bac024",
    "businessState": "TEST",
    "amount": {
      "value": 5000,
      "currency": "NGN",
      "formatted": "NGN5000"
    },
    "reference": "VA_A1B2C3D4E5F6",
    "walletId": "019a1639-ce25-70b7-ab20-16fcb2bac025",
    "sourceReference": "src_1234567890",
    "accountNumber": "1234567890",
    "accountName": "Acme Store",
    "providerName": "wema",
    "accountType": "single_use",
    "status": "active",
    "currency": "NGN",
    "expiresAt": "2026-07-21 12:00:00",
    "createdAt": "2026-07-20 09:15:00"
  }
}

{
  "requestId": "abcd1234-5678-90ef-ghij-1234567890kl",
  "requestTimestamp": "2026-07-20 09:15:00",
  "message": "Virtual account not found.",
  "statusCode": 404
}

{
  "requestId": "abcd1234-5678-90ef-ghij-1234567890kl",
  "requestTimestamp": "2026-07-20 09:15:00",
  "message": "Virtual account not found.",
  "statusCode": 404
}

{
  "requestId": "abcd1234-5678-90ef-ghij-1234567890kl",
  "requestTimestamp": "2026-07-20 09:15:00",
  "message": "Virtual account not found.",
  "statusCode": 404
}

Create Virtual Account

Authorization

Request Body

Response Body

201application/json

401application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`