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

# Get Virtual Card Transactions

Retrieve transactions for one or more virtual cards, with support for filtering and pagination.

Use `getVirtualCardTransactions` to query virtual card activity by card ID, transaction type, date range, or pagination options.

* Provide `virtualCardIds` to fetch transactions for specific cards.
* Omit `virtualCardIds` to fetch transactions across all cards on the authenticated account.

**Required scopes:** `PCI_COMPLIANCE`, `REVEAL_VIRTUALCARD`

## Arguments

### `input` — `GetVirtualCardTransactionsInput`

| Field            |                                 Type | Required | Description                                                                                                                                                                          |
| ---------------- | -----------------------------------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `virtualCardIds` |                            `[UUID!]` |    No    | List of virtual card IDs to retrieve transactions for. Limited to 10 IDs when provided. If omitted, transactions are returned across all virtual cards on the authenticated account. |
| `filters`        | `VirtualCardTransactionFiltersInput` |    No    | Filters used to narrow the transaction results.                                                                                                                                      |
| `paginate`       |                        `OffsetInput` |    No    | Pagination controls for limiting and offsetting results.                                                                                                                             |

## Filters

| Field              |                                Type | Required | Description                                                                                                        |
| ------------------ | ----------------------------------: | :------: | ------------------------------------------------------------------------------------------------------------------ |
| `transactionTypes` | `[VirtualCardTransactionListType!]` |    No    | Filter by transaction type. Supported values include `PURCHASE`, `REFUND`, and `DECLINE`.                          |
| `dateRangeStart`   |                            `String` |    No    | Inclusive start of the transaction date range in ISO 8601 format. Must be used with `dateRangeEnd`.                |
| `dateRangeEnd`     |                            `String` |    No    | Inclusive end of the transaction date range in ISO 8601 format. Must be greater than or equal to `dateRangeStart`. |

## Pagination

| Field    | Type  | Description                                                |
| -------- | ----- | ---------------------------------------------------------- |
| `limit`  | `Int` | Maximum number of transactions to return. Capped at `500`. |
| `offset` | `Int` | Number of transactions to skip.                            |

**Defaults:**

* When `virtualCardIds` is omitted and `limit` is not specified, the default `limit` is **100**.
* When `virtualCardIds` is provided and `limit` is not specified, all matching transactions for each card may be returned. We recommend specifying a `limit` to control response size.

**Behavior:**

* When `virtualCardIds` is provided, `limit` and `offset` apply **per card**.
* When `virtualCardIds` is omitted, `limit` and `offset` apply **across the authenticated account**.

> **Note:** Requesting multiple cards with a high `limit` may result in large responses.

## Validation Errors

The following inputs are rejected before execution:

* `dateRangeStart` and `dateRangeEnd` must be provided together.
* `dateRangeEnd` must be greater than or equal to `dateRangeStart`.
* Both must be valid ISO 8601 timestamps.
* `paginate.limit` cannot exceed 500.
* `virtualCardIds`, when provided, must contain between 1 and 10 valid UUIDs.

## Example: Specific cards

```graphql theme={null}
query GetVirtualCardTransactions {
  getVirtualCardTransactions(
    input: {
      virtualCardIds: [
        "2ed71ba0-d457-47ed-8ceb-d3fe6ce5c900"
        "bd3be748-a0fb-4193-80a7-88419bc72dab"
      ]
      filters: {
        transactionTypes: [PURCHASE, REFUND]
      }
      paginate: {
        limit: 20
        offset: 0
      }
    }
  ) {
    virtualCardId
    transactions {
      transactionDate
      transactionType
      transactionStatus
      transactionAmount
      merchantName
      mcc
      merchantCountryCode
      originalCurrencyCode
      originalCurrencyAmount
      currencyConversionRate
    }
  }
}
```

## Example: All cards (date range)

Use this when you do not know which cards had activity during a specific time period.

```graphql theme={null}
query GetAccountTransactionsByDate {
  getVirtualCardTransactions(
    input: {
      filters: {
        dateRangeStart: "2026-04-01T00:00:00Z"
        dateRangeEnd: "2026-04-30T23:59:59Z"
      }
      paginate: {
        limit: 100
        offset: 0
      }
    }
  ) {
    virtualCardId
    transactions {
      transactionDate
      transactionType
      transactionAmount
      merchantName
      mcc
      merchantCountryCode
      originalCurrencyCode
      originalCurrencyAmount
      currencyConversionRate
    }
  }
}
```

## cURL Example

```bash theme={null}
curl -X POST \
  https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
  -d '{
    "query": "query { getVirtualCardTransactions(input: { filters: { dateRangeStart: \"2026-04-01T00:00:00Z\", dateRangeEnd: \"2026-04-30T23:59:59Z\" }, paginate: { limit: 100, offset: 0 } }) { virtualCardId transactions { transactionDate transactionType transactionAmount merchantName mcc merchantCountryCode originalCurrencyCode originalCurrencyAmount currencyConversionRate } } }"
  }'
```

## Response Fields

* `virtualCardId` (`UUID`) — The virtual card associated with the returned transactions.
* `transactions` (`[VirtualCardTransaction!]`) — List of transactions for the virtual card.
* `transactionDate` (`String`) — Date and time the transaction occurred in ISO 8601 format.
* `transactionType` (`String`) — Transaction type, such as `PURCHASE`, `REFUND`, or `DECLINE`.
* `transactionAmount` (`Float`) — Transaction amount in USD. May be `null`.
* `transactionStatus` (`String`) — Lifecycle status, such as `CLEARED` or `PROCESSING`.
* `transactionApproval` (`String`) — Approval status of the transaction.
* `transactionResponseCode` (`String`) — Card network response code.
* `merchantName` (`String`) — Merchant name when available. May be `null`.
* `paymentMethod` (`String`) — Payment method used for the transaction.
* `mcc` (`Int`) — Merchant category code. May be `null`.
* `merchantCountryCode` (`String`) — Merchant country code. May be `null`.
* `originalCurrencyCode` (`String`) — ISO 4217 currency code of the original transaction (e.g. USD, HKD, EUR). May be null when the original currency is unknown or not applicable.
* `originalCurrencyAmount` (`Float`) — Original amount in the currency’s minor units. For example, `6300` for HKD means `HK$63.00`.
* `currencyConversionRate` (`Float`) — FX conversion rate used to convert the original currency to USD. `1.0` for USD transactions.

## Notes

* FX fields are returned together. They are either all populated or all null.
* `originalCurrencyAmount` is returned in minor units:
  * HKD 6300 = HK\$63.00
  * JPY 100 = ¥100
  * KWD 1000 = 1.000 KD

### Code Example:

<Recipe slug="get-virtual-card-transactions" title="Get Virtual Card Transactions" />

<br />