> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexapay.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual accounts

# Virtual Accounts

## Create Virtual Account (API Key)

`POST /business/virtual-account/create`

### Request Body

```json theme={null}
{
  "businessId": "664b...",
  "amount": 5000,
  "reference": "NexaWallet-20260313",
  "merchantCustomerId": "cust_12345",
  "merchantReference": "order_90881",
  "sessionId": "session_7781",
  "orderId": "order_90881",
  "customerName": "John Doe",
  "customerEmail": "john@example.com",
  "customerPhone": "08055555555",
  "metadata": {
    "purpose": "wallet_topup",
    "source": "checkout"
  },
  "validityTime": "2400",
  "amountValidation": "A3"
}
```

Notes:

* `businessId`, `amount`, `reference`, `merchantCustomerId`, and `merchantReference` are required.
* `merchantCustomerId` should match the merchant's internal user/customer ID.
* `merchantReference` should match the merchant's own order/session/invoice reference.
* Any extra mapping fields are preserved in `metadata` and echoed back in the deposit webhook.

### Response (Production)

```json theme={null}
{
  "success": true,
  "msg": "Virtual account created successfully",
  "accountNumber": "4600070017",
  "reference": "NexaWallet-20260313",
  "transactionId": "NexaWallet-20260313",
  "environment": "prod",
  "simulated": false,
  "virtualAccount": {
    "businessId": "664b...",
    "merchantCustomerId": "cust_12345",
    "merchantReference": "order_90881",
    "amount": 5000,
    "validityTime": "2400",
    "amountValidation": "A3",
    "sessionId": "session_7781",
    "orderId": "order_90881",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "08055555555",
    "metadata": {
      "purpose": "wallet_topup",
      "source": "checkout"
    }
  }
}
```

### Response (Test Key)

```json theme={null}
{
  "success": true,
  "msg": "Test virtual account created successfully",
  "accountNumber": "9123456789",
  "reference": "TEST-VA-1710000000000",
  "transactionId": "TEST-VA-1710000000000",
  "environment": "test",
  "simulated": true,
  "virtualAccount": {
    "businessId": "664b...",
    "merchantCustomerId": "cust_12345",
    "merchantReference": "order_90881",
    "amount": 5000,
    "validityTime": "2400",
    "amountValidation": "A3",
    "sessionId": "session_7781",
    "orderId": "order_90881",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "08055555555",
    "metadata": {
      "purpose": "wallet_topup",
      "source": "checkout"
    }
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "msg": "businessId, amount and reference are required"
}
```

## Virtual Account History

`GET /business/virtual-account/history`

Includes `expiresAt` and `status` (ACTIVE / EXPIRED).
Also returns `merchantCustomerId` and `merchantReference` so you can map each virtual account back to the correct internal customer or order.

This endpoint is currently available in the merchant dashboard only and is not exposed for server-to-server integrations.