Get Virtual Card Transactions

Use getVirtualCardTransactions in either of two modes:

Specific cards: Provide up to 10 virtualCardIds. Results are grouped by card, and pagination applies independently to each card.
All cards: Omit virtualCardIds. Fluz queries activity across the authenticated account and groups matching transactions by card.

Results are returned newest first. Each transaction includes a stable transactionId, an enriched merchantName, and the raw merchantDescriptor reported with the card activity.

Prerequisites

This query requires a Bearer user access token. Basic authentication is not supported.

Authorization: Bearer YOUR_USER_ACCESS_TOKEN

The calling application must have both of these permissions:

Permission	Purpose
`PCI_COMPLIANCE`	Confirms that the developer account is approved for PCI-sensitive data.
`REVEAL_VIRTUALCARD`	Allows the application to retrieve protected virtual card information.

See the Authentication & Authorization Guide and Application Scopes before calling this query.

Environments

Environment	GraphQL endpoint	Use
Staging	`https://transactional-graph.staging.fluzapp.com/api/v1/graphql`	Build and test with synthetic data and test credentials.
Production	`https://transactional-graph.fluzapp.com/api/v1/graphql`	Process real account activity after integration approval.

Important: Use staging while developing your integration. Do not submit production customer information, financial data, or personally identifiable information in staging. Production requests operate on real data and may have real-world consequences.

Learn more in Staging vs. Live Environment.

Arguments

The input argument is required, but every field inside it is optional.

`input: GetVirtualCardTransactionsInput!`

Field	Type	Required	Description
`virtualCardIds`	`[UUID!]`	No	One to 10 virtual card IDs. Omit this field to retrieve activity across all virtual cards on the authenticated account.
`filters`	`VirtualCardTransactionFiltersInput`	No	Narrows results by transaction type or an inclusive date range.
`paginate`	`OffsetInput`	No	Controls the maximum number of transactions and the offset. Pagination applies per card when `virtualCardIds` is supplied and across the account when it is omitted.

Filters

`filters: VirtualCardTransactionFiltersInput`

Field	Type	Required	Description
`transactionTypes`	`[VirtualCardTransactionListType!]`	No	Include one or more of `PURCHASE`, `REFUND`, or `DECLINE`. All three are included when this field is omitted.
`dateRangeStart`	`String`	No	Inclusive ISO 8601 lower bound, such as `2026-07-01T00:00:00Z`. Must be supplied with `dateRangeEnd`.
`dateRangeEnd`	`String`	No	Inclusive ISO 8601 upper bound, such as `2026-07-31T23:59:59Z`. Must be equal to or later than `dateRangeStart`.

Pagination

`paginate: OffsetInput`

The field defaults below apply when paginate is supplied. Omitting paginate entirely follows the mode-specific behavior described after the table.

Field	Type	Default	Valid range	Description
`limit`	`Int`	20	1 to 500	Maximum number of matching transactions.
`offset`	`Int`	0	0 or greater	Number of matching transactions to skip.

Pagination behavior depends on the query mode:

When virtualCardIds is provided, limit and offset apply independently to each card.
When virtualCardIds is omitted, limit and offset apply across all matching account activity before results are grouped by card.
When both virtualCardIds and paginate are omitted, account-wide queries use a default limit of 100.
When virtualCardIds is provided and paginate is omitted, all matching transactions for each requested card may be returned. Supply an explicit limit to keep responses predictable.

The response does not include totalCount or hasNextPage. For an account-wide query, add the lengths of the returned transactions arrays and request the next offset while that total equals limit. For a specific-card query, request the next offset while at least one requested card returns limit transactions.

Validation rules

Fluz rejects the request before execution when:

virtualCardIds is present but contains fewer than one or more than 10 values.
Any virtualCardIds entry is not a valid UUID.
Only one date range boundary is supplied.
Either date range boundary is not a valid ISO 8601 timestamp.
dateRangeEnd is earlier than dateRangeStart.
transactionTypes contains a value other than PURCHASE, REFUND, or DECLINE.
limit is less than 1 or greater than 500.
offset is negative.

Example: Retrieve transactions for specific cards

Use this mode when your application already knows which virtual cards it needs to inspect.

query GetVirtualCardTransactions($input: GetVirtualCardTransactionsInput!) {
  getVirtualCardTransactions(input: $input) {
    virtualCardId
    transactions {
      transactionId
      transactionDate
      transactionType
      transactionAmount
      transactionApproval
      transactionResponseCode
      transactionStatus
      merchantName
      merchantDescriptor
      paymentMethod
      mcc
      merchantCountryCode
      originalCurrencyCode
      originalCurrencyAmount
      currencyConversionRate
    }
  }
}

Variables:

{
  "input": {
    "virtualCardIds": ["2ed71ba0-d457-47ed-8ceb-d3fe6ce5c900", "bd3be748-a0fb-4193-80a7-88419bc72dab"],
    "filters": {
      "transactionTypes": ["PURCHASE", "REFUND"]
    },
    "paginate": {
      "limit": 20,
      "offset": 0
    }
  }
}

Example: Retrieve account-wide activity by date

Omit virtualCardIds when you need to discover which cards had activity during a period.

query GetAccountVirtualCardTransactions($input: GetVirtualCardTransactionsInput!) {
  getVirtualCardTransactions(input: $input) {
    virtualCardId
    transactions {
      transactionId
      transactionDate
      transactionType
      transactionAmount
      transactionApproval
      transactionResponseCode
      transactionStatus
      merchantName
      merchantDescriptor
      paymentMethod
      mcc
      merchantCountryCode
      originalCurrencyCode
      originalCurrencyAmount
      currencyConversionRate
    }
  }
}

Variables:

{
  "input": {
    "filters": {
      "dateRangeStart": "2026-07-01T00:00:00Z",
      "dateRangeEnd": "2026-07-31T23:59:59Z"
    },
    "paginate": {
      "limit": 100,
      "offset": 0
    }
  }
}

cURL example

The following request uses the staging endpoint and synthetic identifiers:

curl --request POST \
  --url https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  --header 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "query GetVirtualCardTransactions($input: GetVirtualCardTransactionsInput!) { getVirtualCardTransactions(input: $input) { virtualCardId transactions { transactionId transactionDate transactionType transactionAmount transactionApproval transactionResponseCode transactionStatus merchantName merchantDescriptor paymentMethod mcc merchantCountryCode originalCurrencyCode originalCurrencyAmount currencyConversionRate } } }",
    "variables": {
      "input": {
        "virtualCardIds": ["2ed71ba0-d457-47ed-8ceb-d3fe6ce5c900"],
        "filters": {
          "transactionTypes": ["PURCHASE", "REFUND", "DECLINE"]
        },
        "paginate": {
          "limit": 20,
          "offset": 0
        }
      }
    }
  }'

Example response

{
  "data": {
    "getVirtualCardTransactions": [
      {
        "virtualCardId": "2ed71ba0-d457-47ed-8ceb-d3fe6ce5c900",
        "transactions": [
          {
            "transactionId": "1b277cd8-8908-4dc5-a42f-d3cdbd9318c0",
            "transactionDate": "2026-07-12T14:32:09.000Z",
            "transactionType": "PURCHASE",
            "transactionAmount": 49.95,
            "transactionApproval": "APPROVED",
            "transactionResponseCode": "00",
            "transactionStatus": "COMPLETED",
            "merchantName": "Facebook",
            "merchantDescriptor": "FACEBK *8KJ88V5MR2",
            "paymentMethod": "FLUZPAY",
            "mcc": 7311,
            "merchantCountryCode": "US",
            "originalCurrencyCode": "USD",
            "originalCurrencyAmount": 4995,
            "currencyConversionRate": 1.0
          }
        ]
      }
    ]
  }
}

Response fields

The top-level response is an array grouped by virtual card.

Field	Type	Description
`virtualCardId`	`UUID!`	Virtual card associated with the returned activity.
`transactions`	`[VirtualCardTransaction!]!`	Transactions returned for the virtual card.

Each transactions item can contain these fields:

Field	Type	Description
`transactionId`	`UUID!`	Stable identifier for the virtual card transaction. Use this value when correlating or storing transaction activity.
`transactionDate`	`String!`	Date and time associated with the transaction, returned as an ISO 8601 timestamp.
`transactionType`	`VirtualCardTransactionListType!`	Activity type. Possible schema values are `PURCHASE`, `REFUND`, and `DECLINE`.
`transactionAmount`	`Float`	Transaction amount expressed in USD. May be `null` when the underlying amount has not been settled.
`transactionApproval`	`String`	Approval result, such as `APPROVED` or `DECLINED`.
`transactionResponseCode`	`String`	Card response or internal decline reason when available.
`transactionStatus`	`String`	Current purchase or refund lifecycle status, such as `PROCESSING`, `COMPLETED`, `CLEARED`, or `PENDING_REFUND`. May be `null`.
`merchantName`	`String`	Enriched, human-readable merchant name when available.
`merchantDescriptor`	`String`	Raw merchant descriptor reported for the card activity, such as `FACEBK *8KJ88V5MR2`. May be `null`.
`paymentMethod`	`String`	Funding or payment method associated with the transaction when available.
`mcc`	`Int`	Merchant category code. May be `null` when no descriptor record or MCC is available.
`merchantCountryCode`	`String`	Merchant country code when available. May be `null`.
`originalCurrencyCode`	`String`	ISO 4217 currency code for the original transaction. May be `null` when unknown or not applicable.
`originalCurrencyAmount`	`Float`	Original transaction amount in the currency's minor units. May be `null` when `originalCurrencyCode` is `null`.
`currencyConversionRate`	`Float`	Rate used to convert the original currency to USD. Equals `1.0` for USD transactions and may be `null` when `originalCurrencyCode` is `null`.

GraphQL fields without ! are nullable.

Integration guidance

Keep the transaction ID

Use transactionId as the stable identifier when storing transactions, reconciling activity, or correlating records across API responses.

Distinguish merchant name from merchant descriptor

merchantName and merchantDescriptor serve different purposes:

merchantName is Fluz's enriched, human-readable merchant name and is the better display value.
merchantDescriptor is the raw text received with the card activity. It can contain abbreviations, locations, reference numbers, or dynamic suffixes.

Do not use merchantDescriptor as a stable transaction or merchant identifier. Use transactionId for the transaction and merchantName for display when available.

Identify declined attempts

Filter with DECLINE when retrieving declined attempts. In the response, use transactionApproval as the authoritative approval result and transactionResponseCode for the available decline reason or response code.

Interpret currency fields

transactionAmount is always expressed in USD. The original-currency fields provide the transaction in the merchant's currency:

originalCurrencyCode, originalCurrencyAmount, and currencyConversionRate are returned together. They may all be null.
originalCurrencyAmount uses the currency's ISO 4217 minor-unit exponent. Do not assume every currency has two decimal places.
Examples: 6300 HKD represents HK$63.00, 100 JPY represents ¥100, and 1000 KWD represents 1.000 KWD.

Paginate defensively

Use a consistent limit and increase offset by that limit. For account-wide queries, stop when the total number of transactions across all returned card groups is less than limit. For specific-card queries, stop when every requested card returns fewer than limit transactions.