> ## 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.

# Find a Virtual Account by Reference or Email Address

> Retrieve a virtual account by account_reference (GET) or customer email address (POST). Both endpoints return the same account object.

Paylink provides two ways to look up a virtual account: by its `account_reference` (the unique ID you defined at creation) or by the customer's email address. Both methods return an identical virtual account object.

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

## Headers (both endpoints)

| 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    |

***

## Method 1 — Look Up by Reference

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

Retrieve a single virtual account using the `account_reference` you assigned when the account was created.

### Path Parameters

<ParamField path="account_reference" type="string" required>
  The unique reference you assigned to the virtual account at creation (e.g. `customer_123`).
</ParamField>

### Example Request

```http theme={null}
GET https://sandbox.lyseis-pay.com/virtual-accounts/customer_123
X-Key-Id: mk_sandbox_xxxxxxxxxx
X-Timestamp: 1751234567
X-Signature: <hmac-sha256-signature>
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "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",
    "currency_code": "NGN",
    "metadata": { "customer_id": "123" },
    "created_at": "2026-09-01T08:00:00Z"
  }
}
```

***

## Method 2 — Look Up by Email

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

Retrieve virtual account(s) associated with a customer's email address. Useful when you do not have the `account_reference` available.

### Request Body

<ParamField body="email" type="string" required>
  The email address of the customer whose virtual account(s) you want to retrieve.
</ParamField>

### Example Request

```json theme={null}
{
  "email": "ada@example.com"
}
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "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",
    "currency_code": "NGN",
    "metadata": { "customer_id": "123" },
    "created_at": "2026-09-01T08:00:00Z"
  }
}
```

***

## Virtual Account Object Fields

<ResponseField name="account_number" type="string">
  The virtual bank account number to share 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.
</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 merchant-defined unique reference for this virtual account.
</ResponseField>

<ResponseField name="reservation_reference" type="string">
  Paylink's internal reference for the account reservation.
</ResponseField>

<ResponseField name="account_status" type="string">
  Current activation state of the account. Typical values: `active`, `inactive`, `frozen`.
</ResponseField>

<ResponseField name="customer_name" type="string">
  Full name of the customer associated with the account.
</ResponseField>

<ResponseField name="customer_email" type="string">
  Email address of the customer associated with the account.
</ResponseField>

<ResponseField name="currency_code" type="string">
  ISO 4217 currency code for the account (e.g. `NGN`).
</ResponseField>

<ResponseField name="metadata" type="object">
  Metadata key-value pairs attached to the account at creation.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the virtual account was provisioned.
</ResponseField>