> ## 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` 以取得經過驗證之帳戶下所有卡片的交易。

**必要範圍（scopes）：** `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

* 外匯（FX）欄位會成組回傳。要嘛全部有值，要嘛全部為 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 />