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

# 模擬卡片交易

> 在預備環境的虛擬卡放入測試消費 — 如何請求授權、清算、拒絕或退款，並透過 API 驗證結果。

預備環境的虛擬卡是真實的卡片紀錄與真實的 BIN，但不在實際支付網路上運作 — 商家無法刷卡。為了驗證你的消費、餘額與對帳邏輯，Fluz 會透過發卡處理方的測試環境，將一筆授權注入你的卡片。從那之後的所有流程都走生產程式路徑：同一個授權服務、同樣的消費控管、相同的分類帳分錄、相同的 webhook。

<Note>
  **僅限預備環境**

  模擬交易僅存在於預備環境（`https://transactional-graph.staging.fluzapp.com/api/v1/graphql`）。不會有資金移動、不會產生 interchange，也不會提交至 Mastercard。在生產環境中，交易只會來自真實商家行為。
</Note>

<Warning>
  **由 Fluz 觸發模擬**

  沒有公開的 mutation 能將交易注入卡片。授權模擬會在發卡處理方的儀表板中執行，該儀表板位於 Fluz 的 PCI 環境內，對合作夥伴不公開。請透過你的整合管道（共享 Slack 頻道或 [partnerships@fluz.app](mailto:partnerships@fluz.app)）提出你需要的交易，我們通常會在同一個工作天內對你的卡片執行。此頁其餘內容 — 發卡與讀取結果 — 皆可自行操作。
</Warning>

## 在你請求模擬之前

授權會經過完整的控管堆疊，因此若卡片設定不正確，可能因與測試無關的原因而被拒絕。

<Steps>
  <Step title="帳戶已通過 KYC">
    只有通過驗證的帳戶才能發卡並通過授權。請參考[測試 KYC 流程](/test-kyc-flows)以取得會通過的身分資料。
  </Step>

  <Step title="你有一張 ACTIVE 卡片">
    使用 `createVirtualCard` 並搭配[測試虛擬卡方案](/test-virtual-card-offers)中的 offer 發卡。請保留 `virtual_card_id` — 我們會用它來定位卡片。
  </Step>

  <Step title="卡片已注資且未上鎖">
    卡片會動用你的 Fluz 餘額。請確認消費上限涵蓋你的測試金額，且卡片未被上鎖、未過期、也未被刷到見底。`getVirtualCardBalance` 能一眼看出 `remainingBalance`。
  </Step>
</Steps>

## 你可以模擬哪些情境

可請求你所需的生命周期步驟。每一種都會對應到你端不同的紀錄與 webhook。

<AccordionGroup>
  <Accordion title="授權（核准）" icon="circle-check">
    基本情境：由你指定商家與金額的消費。卡片可用餘額會立即被占用，交易進入待處理狀態。用此驗證消費控管、餘額遞減，以及你的 `TRANSACTION_CREATE` 處理器是否正確運作。
  </Accordion>

  <Accordion title="清算（請款）" icon="receipt">
    跟在授權之後的結算步驟，在真實情境中有時會相隔數日。我們可以在授權同時一步請款，或讓授權保持開啟，讓你觀察待處理狀態，並在之後再請求請款。第二種更接近生產情境。
  </Accordion>

  <Accordion title="拒絕" icon="circle-x">
    授權服務拒絕的交易。請告知想看到哪種拒絕 — 控管導致的拒絕（超出消費上限、針對品牌鎖定的卡片但到錯誤商家、卡片被鎖）或驗證拒絕（CVV 不符）。拒絕會回傳 `declineReason` 與 `declineCategory`；完整清單請見[拒絕代碼](/features/decline-codes)。
  </Accordion>

  <Accordion title="沖正" icon="rotate-ccw">
    在清算前被釋放的授權 — 例如商家放棄交易，或終端機逾時。被占用的金額會回到卡片。若你的對帳是以授權而非清算為基礎，建議測試此案例。
  </Accordion>

  <Accordion title="退款" icon="arrow-left">
    購買清算後退回到卡片的金額，可能全額或部分。會以 `REFUND` 交易類型出現，而非原始消費的減項，因此你的分類帳需將其視為獨立紀錄處理。
  </Accordion>

  <Accordion title="零金額與 AVS 檢查" icon="shield-check">
    有些商家會先以 $0.00 或 $0.01 的授權探測卡片，之後再進行扣款。這些會以獨立紀錄出現，並在稍後自動沖正。若你的對帳會加總授權金額，請務必測試此情境 — 這是造成重複計算的常見原因。
  </Accordion>
</AccordionGroup>

## 要提供給我們的資訊

提供越多，往返次數越少。

| 欄位                | 必填 | 備註                                |
| ----------------- | -- | --------------------------------- |
| `virtual_card_id` | 是  | 由 `createVirtualCard` 回傳。卡片末四碼也可。 |
| 金額                | 是  | 以 USD 計。                          |
| 結果                | 是  | 核准或拒絕 — 若為拒絕，請指明要測試的原因。           |
| 商家名稱              | 否  | 預設為一般測試商家。若你會比對敘述，請設定。            |
| MCC               | 否  | 若要測試基於類別的邏輯，請設定。                  |
| 單步清算              | 否  | 開啟代表立即請款；關閉代表僅保留授權為待處理。           |

## 驗證結果

一旦我們確認模擬已執行，所有內容都能透過 API 讀取。讀取模擬交易與讀取真實交易沒有任何差異。

<CodeGroup>
  ```graphql Transactions on the card theme={null}
  query {
    getVirtualCardTransactions(input: {
      virtualCardIds: ["<virtual_card_id>"]
      filters: { transactionTypes: [PURCHASE, REFUND, DECLINE] }
    }) {
      virtualCardId
      transactions {
        transactionId
        transactionDate
        transactionType
        transactionStatus
        transactionAmount
        transactionApproval
        transactionResponseCode
        merchantName
        merchantDescriptor
        mcc
      }
    }
  }
  ```

  ```graphql Balance after the spend theme={null}
  query {
    getVirtualCardBalance(input: {
      virtualCardIds: ["<virtual_card_id>"]
    }) {
      virtualCardId
      spentAmount
      remainingBalance
      spendLimit
      spendLimitDuration
    }
  }
  ```
</CodeGroup>

模擬的購買應會以 `PURCHASE` 列出現，且 `remainingBalance` 會相應下降。拒絕會以 `DECLINE` 類型顯示，且不影響餘額 — 亦可透過[取得被拒交易](/features/get-decline-transactions)單獨查詢拒絕。

<Tip>
  卡片層級的查詢只涵蓋卡片活動。若要在帳戶的統一分類帳中與存款、轉帳並列查看相同事件，請使用 `getTransactions` — 參見[交易總覽](/features/transactions-details-overview)。
</Tip>

### Webhooks

模擬交易會觸發與真實交易相同的事件，是端到端測試你端點的最佳方式：

| 事件                    | 觸發時機                                          |
| --------------------- | --------------------------------------------- |
| `TRANSACTION_CREATE`  | 授權被核准時。`status` 為 `PENDING`。                  |
| `TRANSACTION_UPDATE`  | 交易清算時。`status` 轉為 `SETTLED`。                  |
| `TRANSACTION_DECLINE` | 授權被拒時，包含 `declineReason` 與 `declineCategory`。 |

若你要求的是未啟用單步清算的授權，你應該會先看到 `TRANSACTION_CREATE`，而 `TRANSACTION_UPDATE` 只會在請款執行後才出現。Webhook 的 payload 與簽章驗證請見 [Webhooks](/fluz-dashboard/webhooks)。

## 疑難排解

| 你看到的現象         | 可能原因                                     |
| -------------- | ---------------------------------------- |
| 期望核准卻被拒絕       | 消費上限低於金額、卡片被鎖、Fluz 餘額不足，或品牌鎖定的卡片在錯誤商家使用。 |
| 卡片上沒有任何紀錄      | 模擬被執行在另一張卡。請確認你提供的 `virtual_card_id`。    |
| 交易持續為待處理       | 屬於預期 — 授權尚未請款。請求清算步驟。                    |
| 沒有收到 webhook   | 檢查訂閱與必要 scope；交易本身仍可透過 API 查看。           |
| \$0.01 扣款餘額未變動 | 屬於預期的 AVS 探測。它會自行沖正。                     |

## 後續步驟

<CardGroup cols={2}>
  <Card title="你的第一筆虛擬卡消費" icon="credit-card" href="/quickstart/create-and-spend-with-a-virtual-card">
    完整的快樂路徑 — 選擇方案、發卡、揭露卡片資訊並追蹤其消費。
  </Card>

  <Card title="取得虛擬卡交易" icon="list" href="/features/get-virtual-card-transactions">
    依類型與日期篩選卡片活動，並讀取交易上的每個欄位。
  </Card>

  <Card title="拒絕代碼" icon="circle-x" href="/features/decline-codes">
    全部的拒絕原因與分類，以及你的應用該如何處理各種情況。
  </Card>

  <Card title="Webhooks" icon="webhook" href="/fluz-dashboard/webhooks">
    訂閱交易事件、驗證簽章並處理重試。
  </Card>
</CardGroup>

**想了解更多？** 歡迎聯絡我們：[partnerships@fluz.app](mailto:partnerships@fluz.app)。與我們的專家對談以取得更多資訊或預約示範。