模擬卡片交易

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

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

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

在你請求模擬之前

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

帳戶已通過 KYC

只有通過驗證的帳戶才能發卡並通過授權。請參考測試 KYC 流程以取得會通過的身分資料。

你有一張 ACTIVE 卡片

使用 createVirtualCard 並搭配測試虛擬卡方案中的 offer 發卡。請保留 virtual_card_id — 我們會用它來定位卡片。

卡片已注資且未上鎖

卡片會動用你的 Fluz 餘額。請確認消費上限涵蓋你的測試金額，且卡片未被上鎖、未過期、也未被刷到見底。getVirtualCardBalance 能一眼看出 remainingBalance。

你可以模擬哪些情境

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

授權（核准）

基本情境：由你指定商家與金額的消費。卡片可用餘額會立即被占用，交易進入待處理狀態。用此驗證消費控管、餘額遞減，以及你的 TRANSACTION_CREATE 處理器是否正確運作。

清算（請款）

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

拒絕

授權服務拒絕的交易。請告知想看到哪種拒絕 — 控管導致的拒絕（超出消費上限、針對品牌鎖定的卡片但到錯誤商家、卡片被鎖）或驗證拒絕（CVV 不符）。拒絕會回傳 declineReason 與 declineCategory；完整清單請見拒絕代碼。

沖正

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

退款

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

零金額與 AVS 檢查

有些商家會先以

0.00 或

0.01 的授權探測卡片，之後再進行扣款。這些會以獨立紀錄出現，並在稍後自動沖正。若你的對帳會加總授權金額，請務必測試此情境 — 這是造成重複計算的常見原因。

要提供給我們的資訊

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

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

驗證結果

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

query {
  getVirtualCardTransactions(input: {
    virtualCardIds: ["<virtual_card_id>"]
    filters: { transactionTypes: [PURCHASE, REFUND, DECLINE] }
  }) {
    virtualCardId
    transactions {
      transactionId
      transactionDate
      transactionType
      transactionStatus
      transactionAmount
      transactionApproval
      transactionResponseCode
      merchantName
      merchantDescriptor
      mcc
    }
  }
}

query {
  getVirtualCardBalance(input: {
    virtualCardIds: ["<virtual_card_id>"]
  }) {
    virtualCardId
    spentAmount
    remainingBalance
    spendLimit
    spendLimitDuration
  }
}

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

卡片層級的查詢只涵蓋卡片活動。若要在帳戶的統一分類帳中與存款、轉帳並列查看相同事件，請使用 getTransactions — 參見交易總覽。

Webhooks

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

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

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

疑難排解

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

後續步驟

你的第一筆虛擬卡消費

完整的快樂路徑 — 選擇方案、發卡、揭露卡片資訊並追蹤其消費。

取得虛擬卡交易

依類型與日期篩選卡片活動，並讀取交易上的每個欄位。

拒絕代碼

全部的拒絕原因與分類，以及你的應用該如何處理各種情況。

Webhooks

訂閱交易事件、驗證簽章並處理重試。

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

快速開始

Fluz 控制台

快速入門

模擬卡片交易

在你請求模擬之前

你可以模擬哪些情境

要提供給我們的資訊

驗證結果

Webhooks

疑難排解

後續步驟

你的第一筆虛擬卡消費

取得虛擬卡交易

拒絕代碼

Webhooks

​在你請求模擬之前

​你可以模擬哪些情境

​要提供給我們的資訊

​驗證結果

​Webhooks

​疑難排解

​後續步驟

你的第一筆虛擬卡消費

取得虛擬卡交易

拒絕代碼

Webhooks

在你請求模擬之前

你可以模擬哪些情境

要提供給我們的資訊

驗證結果

Webhooks

疑難排解

後續步驟