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

# Obtener transacciones de tarjetas virtuales

Recupera transacciones para una o más tarjetas virtuales, con soporte para filtros y paginación.

Usa `getVirtualCardTransactions` para consultar la actividad de tarjetas virtuales por ID de tarjeta, tipo de transacción, rango de fechas u opciones de paginación.

* Proporciona `virtualCardIds` para obtener transacciones de tarjetas específicas.
* Omite `virtualCardIds` para obtener transacciones de todas las tarjetas de la cuenta autenticada.

**Alcances requeridos:** `PCI_COMPLIANCE`, `REVEAL_VIRTUALCARD`

## Argumentos

### `input` — `GetVirtualCardTransactionsInput`

| Campo            |                                 Tipo | Requerido | Descripción                                                                                                                                                                                                 |
| ---------------- | -----------------------------------: | :-------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `virtualCardIds` |                            `[UUID!]` |     No    | Lista de IDs de tarjetas virtuales para recuperar transacciones. Limitado a 10 IDs cuando se proporciona. Si se omite, se devuelven transacciones de todas las tarjetas virtuales en la cuenta autenticada. |
| `filters`        | `VirtualCardTransactionFiltersInput` |     No    | Filtros utilizados para acotar los resultados de transacciones.                                                                                                                                             |
| `paginate`       |                        `OffsetInput` |     No    | Controles de paginación para limitar y compensar resultados.                                                                                                                                                |

## Filtros

| Campo              |                                Tipo | Requerido | Descripción                                                                                                          |
| ------------------ | ----------------------------------: | :-------: | -------------------------------------------------------------------------------------------------------------------- |
| `transactionTypes` | `[VirtualCardTransactionListType!]` |     No    | Filtrar por tipo de transacción. Valores admitidos incluyen `PURCHASE`, `REFUND` y `DECLINE`.                        |
| `dateRangeStart`   |                            `String` |     No    | Inicio inclusivo del rango de fechas de transacciones en formato ISO 8601. Debe usarse con `dateRangeEnd`.           |
| `dateRangeEnd`     |                            `String` |     No    | Fin inclusivo del rango de fechas de transacciones en formato ISO 8601. Debe ser mayor o igual que `dateRangeStart`. |

## Paginación

| Campo    | Tipo  | Descripción                                                  |
| -------- | ----- | ------------------------------------------------------------ |
| `limit`  | `Int` | Número máximo de transacciones a devolver. Limitado a `500`. |
| `offset` | `Int` | Número de transacciones a omitir.                            |

**Valores predeterminados:**

* Cuando se omite `virtualCardIds` y no se especifica `limit`, el `limit` predeterminado es **100**.
* Cuando se proporciona `virtualCardIds` y no se especifica `limit`, pueden devolverse todas las transacciones que coincidan para cada tarjeta. Recomendamos especificar un `limit` para controlar el tamaño de la respuesta.

**Comportamiento:**

* Cuando se proporciona `virtualCardIds`, `limit` y `offset` aplican **por tarjeta**.
* Cuando se omite `virtualCardIds`, `limit` y `offset` aplican **a través de la cuenta autenticada**.

> **Nota:** Solicitar múltiples tarjetas con un `limit` alto puede resultar en respuestas grandes.

## Errores de validación

Las siguientes entradas se rechazan antes de la ejecución:

* `dateRangeStart` y `dateRangeEnd` deben proporcionarse juntas.
* `dateRangeEnd` debe ser mayor o igual que `dateRangeStart`.
* Ambas deben ser marcas de tiempo ISO 8601 válidas.
* `paginate.limit` no puede exceder 500.
* `virtualCardIds`, cuando se proporciona, debe contener entre 1 y 10 UUIDs válidos.

## Ejemplo: Tarjetas específicas

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

## Ejemplo: Todas las tarjetas (rango de fechas)

Usa esto cuando no sabes qué tarjetas tuvieron actividad durante un período específico.

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

## Ejemplo cURL

```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 } } }"
  }'
```

## Campos de la respuesta

* `virtualCardId` (`UUID`) — La tarjeta virtual asociada con las transacciones devueltas.
* `transactions` (`[VirtualCardTransaction!]`) — Lista de transacciones para la tarjeta virtual.
* `transactionDate` (`String`) — Fecha y hora en que ocurrió la transacción en formato ISO 8601.
* `transactionType` (`String`) — Tipo de transacción, como `PURCHASE`, `REFUND` o `DECLINE`.
* `transactionAmount` (`Float`) — Monto de la transacción en USD. Puede ser `null`.
* `transactionStatus` (`String`) — Estado del ciclo de vida, como `CLEARED` o `PROCESSING`.
* `transactionApproval` (`String`) — Estado de aprobación de la transacción.
* `transactionResponseCode` (`String`) — Código de respuesta de la red de tarjetas.
* `merchantName` (`String`) — Nombre del comercio cuando esté disponible. Puede ser `null`.
* `paymentMethod` (`String`) — Método de pago utilizado para la transacción.
* `mcc` (`Int`) — Código de categoría del comercio. Puede ser `null`.
* `merchantCountryCode` (`String`) — Código de país del comercio. Puede ser `null`.
* `originalCurrencyCode` (`String`) — Código de moneda ISO 4217 de la transacción original (p. ej., USD, HKD, EUR). Puede ser null cuando la moneda original es desconocida o no aplica.
* `originalCurrencyAmount` (`Float`) — Monto original en las unidades menores de la moneda. Por ejemplo, `6300` para HKD significa `HK$63.00`.
* `currencyConversionRate` (`Float`) — Tasa de conversión FX utilizada para convertir la moneda original a USD. `1.0` para transacciones en USD.

## Notas

* Los campos de FX se devuelven juntos. O bien todos están poblados o todos son null.
* `originalCurrencyAmount` se devuelve en unidades menores:
  * HKD 6300 = HK\$63.00
  * JPY 100 = ¥100
  * KWD 1000 = 1.000 KD

### Ejemplo de código:

<Recipe slug="get-virtual-card-transactions" title="Obtener transacciones de tarjetas virtuales" />

<br />