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.

Replace sandbox.lyseis-pay.com with live.lyseis-pay.com when moving to production.

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

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

account_reference · string · required

The unique reference you assigned to the virtual account at creation (e.g. customer_123).

Example Request

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

{
  "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": "[e-mail]",
    "currency_code": "NGN",
    "metadata": { "customer_id": "123" },
    "created_at": "2026-09-01T08:00:00Z"
  }
}

---

Method 2 — Look Up by Email

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

email · string · required

The email address of the customer whose virtual account(s) you want to retrieve.

Example Request

{
  "email": "[e-mail]"
}

Example Response

{
  "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": "[e-mail]",
    "currency_code": "NGN",
    "metadata": { "customer_id": "123" },
    "created_at": "2026-09-01T08:00:00Z"
  }
}

---

Virtual Account Object Fields

account_number · string

The virtual bank account number to share with the customer for inbound transfers.

bank_name · string

The name of the partner bank or institution that issued the virtual account.

bank_code · string

The CBN-assigned sort code or bank code for the issuing bank.

account_reference · string

The merchant-defined unique reference for this virtual account.

reservation_reference · string

Paylink’s internal reference for the account reservation.

account_status · string

Current activation state of the account. Typical values: active, inactive, frozen.

customer_name · string

Full name of the customer associated with the account.

customer_email · string

Email address of the customer associated with the account.

currency_code · string

ISO 4217 currency code for the account (e.g. NGN).

metadata · object

Metadata key-value pairs attached to the account at creation.

created_at · string

ISO 8601 timestamp when the virtual account was provisioned.