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

# List and Filter Virtual Account Transactions by Date

> GET /merchants/virtual-accounts/transactions — paginated inbound transfers across your virtual accounts, filterable by account, status, and date range.

Retrieve a paginated list of all inbound transactions received by virtual accounts on your merchant account. Filter by a specific account reference, status, or date range to support reconciliation and reporting workflows.

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

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

## Query Parameters

<ParamField query="account_reference" type="string">
  Filter results to transactions received by a specific virtual account. If omitted, transactions across all your virtual accounts are returned.
</ParamField>

<ParamField query="status" type="string">
  Filter by transaction status. Common values: `success`, `processing`, `failed`. Omit to include all statuses.
</ParamField>

<ParamField query="start_date" type="string">
  ISO 8601 datetime (inclusive) marking the start of the date range, e.g. `2026-09-01T00:00:00Z`. Filters on `created_at`.
</ParamField>

<ParamField query="end_date" type="string">
  ISO 8601 datetime (inclusive) marking the end of the date range, e.g. `2026-09-30T23:59:59Z`. Filters on `created_at`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  The page number to retrieve, starting from `1`.
</ParamField>

<ParamField query="page_size" type="integer" default="10">
  Number of records to return per page. Minimum `1`, maximum `100`.
</ParamField>

## Example Request

```http theme={null}
GET https://sandbox.lyseis-pay.com/merchants/virtual-accounts/transactions?account_reference=customer_123&status=success&page=1&page_size=10
X-Key-Id: mk_sandbox_xxxxxxxxxx
X-Timestamp: 1751234567
X-Signature: <hmac-sha256-signature>
```

## Response

<ResponseField name="status" type="string">
  Top-level API response status. `"success"` indicates the request was processed and results are included.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of transactions matching the applied filters, across all pages.
</ResponseField>

<ResponseField name="page" type="integer">
  The current page number returned.
</ResponseField>

<ResponseField name="pageSize" type="integer">
  Number of records included on this page.
</ResponseField>

<ResponseField name="data" type="array">
  Array of virtual account transaction objects.

  <Expandable title="Transaction object fields">
    <ResponseField name="data[].transaction_id" type="string">
      Paylink's internal unique identifier for this inbound transfer.
    </ResponseField>

    <ResponseField name="data[].account_reference" type="string">
      The merchant-defined reference of the virtual account that received the funds.
    </ResponseField>

    <ResponseField name="data[].account_number" type="string">
      The virtual account number that received the transfer.
    </ResponseField>

    <ResponseField name="data[].amount" type="number">
      The transfer amount received, in the smallest currency unit (e.g. kobo for NGN).
    </ResponseField>

    <ResponseField name="data[].currency" type="string">
      ISO 4217 currency code (e.g. `NGN`).
    </ResponseField>

    <ResponseField name="data[].status" type="string">
      The status of this inbound transfer (e.g. `success`, `processing`, `failed`).
    </ResponseField>

    <ResponseField name="data[].sender_name" type="string">
      The name of the individual or entity that sent the transfer, as reported by the banking rail.
    </ResponseField>

    <ResponseField name="data[].sender_bank" type="string">
      The bank name from which the transfer originated.
    </ResponseField>

    <ResponseField name="data[].narration" type="string">
      The payment narration or description provided by the sender.
    </ResponseField>

    <ResponseField name="data[].metadata" type="object">
      Metadata key-value pairs associated with the virtual account at the time of this transaction.
    </ResponseField>

    <ResponseField name="data[].created_at" type="string">
      ISO 8601 timestamp when the transaction was recorded.
    </ResponseField>

    <ResponseField name="data[].updated_at" type="string">
      ISO 8601 timestamp of the most recent status update.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "status": "success",
  "total": 38,
  "page": 1,
  "pageSize": 10,
  "data": [
    {
      "transaction_id": "vat_00abc123def",
      "account_reference": "customer_123",
      "account_number": "0123456789",
      "amount": 15000.00,
      "currency": "NGN",
      "status": "success",
      "sender_name": "Ngozi Okafor",
      "sender_bank": "First Bank of Nigeria",
      "narration": "Payment for invoice #INV-00789",
      "metadata": { "customer_id": "123" },
      "created_at": "2026-09-10T14:32:00Z",
      "updated_at": "2026-09-10T14:32:45Z"
    },
    {
      "transaction_id": "vat_00abc123deg",
      "account_reference": "customer_123",
      "account_number": "0123456789",
      "amount": 5000.00,
      "currency": "NGN",
      "status": "success",
      "sender_name": "Emeka Eze",
      "sender_bank": "Access Bank",
      "narration": "Wallet top-up",
      "metadata": { "customer_id": "123" },
      "created_at": "2026-09-12T09:15:00Z",
      "updated_at": "2026-09-12T09:15:30Z"
    }
  ]
}
```