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

# Create a Dedicated Virtual Bank Account for Customer

> POST /virtual-accounts provisions a dedicated virtual bank account for a customer, returning an account number, bank details, and reservation reference.

Provision a dedicated virtual bank account for a customer. Once created, the account can receive bank transfers that are automatically reconciled to your merchant wallet. Each account is tied to a unique `account_reference` you define.

```http theme={null}
POST https://sandbox.lyseis-pay.com/virtual-accounts
```

<Note>
  Replace `sandbox.lyseis-pay.com` with `live.lyseis-pay.com` when moving to production.
</Note>

## Headers

| Header         | Value                                   |
| -------------- | --------------------------------------- |
| `X-Key-Id`     | Your merchant key ID                    |
| `X-Timestamp`  | Unix timestamp of the request (seconds) |
| `X-Signature`  | HMAC-SHA256 signature of the payload    |
| `Content-Type` | `application/json`                      |

## Request Body

<ParamField body="account_reference" type="string" required>
  A unique identifier you assign to this virtual account (e.g. a customer ID or wallet ID). Must be unique across your merchant account. Used to look up the account later.
</ParamField>

<ParamField body="customer_name" type="string" required>
  The full legal name of the customer this account is provisioned for. This name is associated with the bank account.
</ParamField>

<ParamField body="customer_email" type="string" required>
  The customer's email address. Used for notifications and account lookup.
</ParamField>

<ParamField body="currency_code" type="string" required>
  ISO 4217 three-letter currency code for the account. Example: `NGN`.
</ParamField>

<ParamField body="bvn" type="string" required>
  The customer's Bank Verification Number (BVN) — an 11-digit identifier issued by the Central Bank of Nigeria. Required for regulatory compliance when provisioning NGN accounts.
</ParamField>

<ParamField body="metadata" type="object">
  Optional arbitrary key-value pairs to attach to this virtual account record. Returned on subsequent lookups and webhook notifications.

  ```json theme={null}
  { "customer_id": "123", "plan": "premium" }
  ```
</ParamField>

## Example Request

```json theme={null}
{
  "account_reference": "customer_123",
  "customer_name": "Ada Lovelace",
  "customer_email": "ada@example.com",
  "currency_code": "NGN",
  "bvn": "22222222222",
  "metadata": { "customer_id": "123" }
}
```

## Response

<ResponseField name="status" type="string">
  Indicates whether the account was successfully provisioned. A value of `"success"` means the virtual account is active and ready to receive funds.
</ResponseField>

<ResponseField name="account_number" type="string">
  The virtual bank account number assigned to this customer. Share this with the customer for inbound transfers.
</ResponseField>

<ResponseField name="bank_name" type="string">
  The name of the partner bank or institution that issued the virtual account, e.g. `"Wema Bank"`.
</ResponseField>

<ResponseField name="bank_code" type="string">
  The CBN-assigned sort code or bank code for the issuing bank.
</ResponseField>

<ResponseField name="account_reference" type="string">
  The unique reference you provided at creation. Use this to retrieve or identify the account later.
</ResponseField>

<ResponseField name="reservation_reference" type="string">
  Paylink's internal reference for the account reservation. Use this when contacting support about a specific virtual account.
</ResponseField>

<ResponseField name="account_status" type="string">
  The activation status of the virtual account, e.g. `"active"`.
</ResponseField>

<ResponseField name="customer_name" type="string">
  The customer name associated with the account, echoed from the request.
</ResponseField>

<ResponseField name="customer_email" type="string">
  The customer email associated with the account, echoed from the request.
</ResponseField>

## Example Response

```json theme={null}
{
  "status": "success",
  "account_number": "0123456789",
  "bank_name": "Wema Bank",
  "bank_code": "035",
  "account_reference": "customer_123",
  "reservation_reference": "va_res_abc123xyz",
  "account_status": "active",
  "customer_name": "Ada Lovelace",
  "customer_email": "ada@example.com"
}
```

<Note>
  Virtual account numbers are persistent — the same account number is reused for all subsequent transfers from the customer. Funds received are automatically posted to your merchant wallet and trigger a webhook if one is configured.
</Note>