Get Virtual Card Transactions

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

Filters

Pagination

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

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.

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

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: