# Virtual Accounts

Virtual accounts are temporary bank accounts that let you receive payments via standard bank transfer. When a customer transfers money to a virtual account, the payment is automatically detected and settled to your ZevPay account.

## How It Works

1. **Create** a virtual account via the [API](/api/virtual-account) or dashboard
2. You receive an **account number** at VFD Microfinance Bank
3. **Share** the account details with your customer
4. Customer makes a **bank transfer** to the account number from any bank
5. Payment is **automatically detected** and settled to your account
6. A **webhook notification** is sent to your configured webhook URL

## Creating a Virtual Account

```bash
curl -X POST https://api.zevpaycheckout.com/v1/checkout/virtual-account \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_test_your_secret_key" \
  -d '{
    "amount": "5000.00",
    "validity_minutes": 1440
  }'
```

The response includes the `account_number` that your customer should transfer to:

```json
{
  "success": true,
  "data": {
    "public_id": "abc123def456ghi78",
    "account_number": "4601234567",
    "merchant_name": "My Business",
    "amount": "5000.00",
    "status": "pending",
    "expires_at": "2026-03-09T12:00:00.000Z"
  }
}
```

See the full [Virtual Account API reference](/api/virtual-account).

## Status Lifecycle

```
pending → completed   (payment received)
pending → expired     (validity period elapsed)
cancelled             (creation failed at provider)
```

| Status | Description |
|--------|-------------|
| `pending` | Account is active and waiting for a transfer |
| `completed` | Payment has been received and settled |
| `expired` | Account expired without receiving payment |
| `cancelled` | Account could not be created at the banking provider |

## Expiry

Virtual accounts have a configurable validity period:

- **Default:** 4320 minutes (72 hours)
- **Maximum:** 4320 minutes (72 hours)
- **Minimum:** 1 minute

After the validity period, the account expires and can no longer receive payments. If you need to extend the window, create a new virtual account.

## Virtual Accounts vs Checkout Sessions

Both can accept bank transfer payments, but they serve different purposes:

| | Checkout Session | Virtual Account |
|---|---|---|
| **UI** | Full hosted checkout page | No UI — just account details |
| **Payment methods** | Bank transfer + PayID | Bank transfer only |
| **Use case** | Customer-facing checkout | Backend/API-driven payment collection |
| **Expiry** | 30 minutes | Up to 72 hours |
| **Amount** | Required | Required |

Use **checkout sessions** when you want a complete payment UI for your customers. Use **virtual accounts** when you need to generate bank account details programmatically (e.g., for POS systems, invoice payments, or custom payment flows).

## Dashboard

Virtual accounts can be viewed and created from the [Virtual Accounts](https://business.zevpay.ng/virtual-accounts) section of your dashboard.