v1

latestOpenAPI 3.0.32026-07-26184851.6 MB

Virtual Accounts V2

Master Wallet Account Create

post/v2/wallets/{id}/virtual-accounts

Path parameters

idstring uuid required

Wallet identifier.

Request body

currencystring required

ISO 4217 virtual-account currency.

assetIdstring uuid

Stablecoin asset that receives settlements.

customerIdstring uuid

Existing customer identifier, when the provider requires one.

additionalDataobject

Values collected and validated against additionalDataSchema.

codestring

passkeyResponseobject

labelstring

Your display label for the virtual account.

providerstring required

Provider slug resolved from the requirements flow.

Example request

{
  "currency": "NGN",
  "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
  "customerId": "18d2f159-e0cd-4a45-b735-e9dfe0f7520a",
  "additionalData": {
    "bvn": "12345678901",
    "dateOfBirth": "1992-04-18"
  },
  "label": "Ada collection account",
  "provider": "example-provider"
}

Response

Created successfully.

statusCodeinteger required

messagestring required

Human-readable result.

Example response

{
  "statusCode": 201,
  "message": "Virtual account created successfully",
  "data": {
    "created": true,
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  }
}