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

# 获取虚拟卡交易

检索一个或多个虚拟卡的交易，支持筛选与分页。

使用 `getVirtualCardTransactions` 按卡片 ID、交易类型、日期范围或分页选项查询虚拟卡活动。

* 提供 `virtualCardIds` 可获取特定卡片的交易。
* 省略 `virtualCardIds` 可获取已认证账户下所有卡片的交易。

**必需的作用域：** `PCI_COMPLIANCE`，`REVEAL_VIRTUALCARD`

## Arguments

### `input` — `GetVirtualCardTransactionsInput`

| Field            |                                 Type | Required | Description                                          |
| ---------------- | -----------------------------------: | :------: | ---------------------------------------------------- |
| `virtualCardIds` |                            `[UUID!]` |    No    | 要检索交易的虚拟卡 ID 列表。提供时最多 10 个 ID。若省略，将返回已认证账户下所有虚拟卡的交易。 |
| `filters`        | `VirtualCardTransactionFiltersInput` |    No    | 用于缩小交易结果的筛选条件。                                       |
| `paginate`       |                        `OffsetInput` |    No    | 用于限制与偏移结果的分页控制。                                      |

## Filters

| Field              |                                Type | Required | Description                                           |
| ------------------ | ----------------------------------: | :------: | ----------------------------------------------------- |
| `transactionTypes` | `[VirtualCardTransactionListType!]` |    No    | 按交易类型筛选。支持的值包括 `PURCHASE`、`REFUND` 和 `DECLINE`。       |
| `dateRangeStart`   |                            `String` |    No    | 交易日期范围的起始时间（含）——ISO 8601 格式。必须与 `dateRangeEnd` 搭配使用。  |
| `dateRangeEnd`     |                            `String` |    No    | 交易日期范围的结束时间（含）——ISO 8601 格式。必须大于或等于 `dateRangeStart`。 |

## Pagination

| Field    | Type  | Description          |
| -------- | ----- | -------------------- |
| `limit`  | `Int` | 返回的交易最大数量。上限为 `500`。 |
| `offset` | `Int` | 要跳过的交易数量。            |

**默认值：**

* 当省略 `virtualCardIds` 且未指定 `limit` 时，默认 `limit` 为 **100**。
* 当提供 `virtualCardIds` 且未指定 `limit` 时，可能会返回每张卡片的全部匹配交易。建议指定 `limit` 以控制响应大小。

**行为：**

* 当提供 `virtualCardIds` 时，`limit` 与 `offset` 按“每张卡片”生效。
* 当省略 `virtualCardIds` 时，`limit` 与 `offset` 按“已认证账户范围”生效。

> **注意：** 对多张卡片请求较高的 `limit` 可能导致响应体很大。

## Validation Errors

以下输入会在执行前被拒绝：

* `dateRangeStart` 与 `dateRangeEnd` 必须同时提供。
* `dateRangeEnd` 必须大于或等于 `dateRangeStart`。
* 二者都必须是有效的 ISO 8601 时间戳。
* `paginate.limit` 不得超过 500。
* 当提供 `virtualCardIds` 时，其必须包含 1 到 10 个有效的 UUID。

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

当你不清楚某一时间段内哪些卡片有活动时可使用此示例。

```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`) — 与返回交易关联的虚拟卡。
* `transactions` (`[VirtualCardTransaction!]`) — 该虚拟卡的交易列表。
* `transactionDate` (`String`) — 交易发生的日期与时间，ISO 8601 格式。
* `transactionType` (`String`) — 交易类型，如 `PURCHASE`、`REFUND` 或 `DECLINE`。
* `transactionAmount` (`Float`) — 以 USD 计价的交易金额。可能为 `null`。
* `transactionStatus` (`String`) — 生命周期状态，如 `CLEARED` 或 `PROCESSING`。
* `transactionApproval` (`String`) — 交易的审批状态。
* `transactionResponseCode` (`String`) — 卡组织响应代码。
* `merchantName` (`String`) — 商户名称（如可用）。可能为 `null`。
* `paymentMethod` (`String`) — 该笔交易使用的支付方式。
* `mcc` (`Int`) — 商户类别码。可能为 `null`。
* `merchantCountryCode` (`String`) — 商户国家代码。可能为 `null`。
* `originalCurrencyCode` (`String`) — 原始交易的 ISO 4217 货币代码（例如 USD、HKD、EUR）。当原始货币未知或不适用时可能为 null。
* `originalCurrencyAmount` (`Float`) — 原始币种的最小单位金额。例如，HKD 的 `6300` 表示 `HK$63.00`。
* `currencyConversionRate` (`Float`) — 将原始币种转换为 USD 所用的外汇汇率。USD 交易为 `1.0`。

## Notes

* 外汇相关字段会成组返回：要么全部有值，要么全部为 null。
* `originalCurrencyAmount` 以最小单位返回：
  * HKD 6300 = HK\$63.00
  * JPY 100 = ¥100
  * KWD 1000 = 1.000 KD

### Code Example:

<Recipe slug="get-virtual-card-transactions" title="获取虚拟卡交易" />

<br />