交易生命週期

使用 Fluz 發行的卡片進行的一次購買，不是一個單一事件。它是在商家、卡組織與 Fluz 之間的一段對話，可能發生在幾秒、幾小時，或有時長達數週——而且在完成前，會在你這邊產生多筆記錄。本頁說明每個階段會發生什麼、每個階段會產生哪些 Fluz 記錄與 webhook，以及天真整合最容易算錯的地方。

本頁涵蓋的是開環卡交易——使用 Fluz 發行到卡組織上的虛擬卡進行的消費。禮品卡購買、存款、提款與錢包轉帳不走這個生命週期；它們有各自的結算軌道。請見交易總覽以了解承載所有交易的統一分類帳。

三個階段

階段	發生什麼事	誰的資金在移動
授權	卡組織詢問 Fluz 該卡是否可被扣款。Fluz 檢查卡片控管與資金，並回覆。	尚未有資金移動。資金被保留，而非移轉。
清算	商家提交最終金額。Fluz 針對已保留資金完成最終記錄。	保留轉為實際借記。
結算	卡組織在收單行與發卡行之間搬動資金。	銀行對銀行。對你的整合來說是不可見的。

結算是銀行層的流程，依卡組織的排程在清算之後進行。Fluz 將清算與結算視為同一事件——當交易在 Fluz 上被清算時，就將其視為最終。

一次購買，數筆記錄

單一購買可能產生一筆授權、一或多筆清算，並可能有撤銷或退款。Fluz 透過三種查詢呈現它們，分別回答不同問題：

Feed	查詢	顯示內容
卡片動態	`getVirtualCardTransactions`	一張或多張卡的消費，包含商家、MCC、匯率與網路回應欄位
帳戶分類帳	`getTransactions`	帳戶上每一次資金變動，並附每筆記錄後的餘額快照
遭拒授權	`getDeclinedTransactions`	被拒且未成為交易的授權

三次購買，以及各自留下的記錄：

Acme Hardware — $50.00
├── Authorization        $50.00 debit      held against the card
└── Clearing             $50.00 debit      hold converted, record final

Riverside Hotel — $240.00
├── Authorization       $200.00 debit      pre-auth at check-in
├── Incremental auth     $75.00 debit      incidentals added mid-stay
└── Clearing            $240.00 debit      final folio, less than authorized

Acme Hardware — $50.00, later refunded
├── Authorization        $50.00 debit
├── Clearing             $50.00 debit
└── Refund               $50.00 credit     separate record, not a reversal

退款是新的記錄，不是對舊記錄的編輯。退款會以自己的 REFUND 交易到達。原本的 PURCHASE 記錄不會有任何變更——其金額維持不變。若你的系統在退款入帳時去減少原始購買，你會將入帳的貸項重複計入。請在記錄層級進行對帳；不要變動原始記錄。

單訊息與雙訊息流程

卡組織發送多少訊息，取決於商家與交易類型。兩種流程皆為正常狀況，而你的整合必須同時處理。

單訊息

卡組織發送一則同時授權並清算的訊息。常見於 PIN 借記、ATM 提領與交通運具。沒有待處理視窗——交易幾乎立即成為最終。

雙訊息

卡組織先發送授權，商家之後再提交清算——通常在當晚，但飯店、租車與旅遊可能延遲數日。兩者之間的間隔即為待處理視窗，而這正是多數對帳錯誤發生之處。

清算金額可能與授權金額不同。 小費、加油站自助加油、幣別轉換與分批出貨，都會產生高於或低於原本保留金額的清算。請以清算金額為準，切勿將授權金額視為最終。

錢在哪裡

從帳戶角度看同一生命週期：

Fluz 在各階段記錄什麼

卡組織訊息	意義	卡片 feed `transactionType`	分類帳 `status`	Webhook
Verification	$0.00 或$ 0.01 的探測，用來確認卡片有效	`PURCHASE`，很快被撤銷	`PENDING`，已釋放	`TRANSACTION_CREATE` + `TRANSACTION_UPDATE`
Authorization	在等待最終金額時預留資金	`PURCHASE`	`PENDING`	`TRANSACTION_CREATE`
Authorize and clear	一則訊息即核准並完成	`PURCHASE`	`SETTLED`	`TRANSACTION_CREATE` + `TRANSACTION_UPDATE`
Clearing	將先前授權的交易完成定稿	`PURCHASE`	`SETTLED`	`TRANSACTION_UPDATE`
Decline	授權被拒	`DECLINE`	無分類帳記錄	`TRANSACTION_DECLINE`
Reversal	清算前釋放授權保留款	hold released	記錄已釋放	`TRANSACTION_UPDATE`
Refund	購買清算後的金額退回	`REFUND`	`SETTLED` 貸方	`TRANSACTION_CREATE`

兩種 feed，兩套狀態字彙。

getVirtualCardTransactions 回傳 transactionStatus，例如 PROCESSING 與 CLEARED。
getTransactions 回傳 status 值為 PENDING 與 SETTLED。

它們從兩個角度描述相同的生命週期。不要撰寫在兩處都期待同一套字彙的程式碼。→ GraphQL API 如何運作

遭拒不是交易。 遭拒的授權不會進入帳戶分類帳，因此不會以任何狀態出現在 getTransactions。請透過 getDeclinedTransactions 查詢，並從拒絕代碼讀取原因。

授權

當卡組織要求 Fluz 批准扣款時，Fluz 會依卡片、帳戶與卡片背後的資金評估請求。這一切都在不到一秒內完成，因為卡組織會逾時。

會檢查什麼

卡片是 ACTIVE —— 未被鎖定、未過期、未過 lockDate，也未被一次性規則用過
金額符合卡片 spendLimit 與其 spendLimitDuration
若卡片發行於品牌鎖定的方案上，商家須符合卡片的品牌鎖定
帳戶持有人已通過身分驗證
卡片背後的資金來源足以支付該金額
銀行方案本身的限制未被超過

資金從哪裡來

卡片本身不持有餘額。它在授權時，依開卡時設定的資金堆疊撥用資金：

userCashBalanceId 指定的消費帳戶，或帳戶預設值
預付（禮品卡）餘額，除非 usePrepaymentBalance: false
獎勵餘額，除非 useRewardsBalance: false
外部銀行帳戶，當 primaryFundingSource 為 BANK_ACCOUNT 時

超過上述來源可支付金額的授權會被拒，即使卡片的 spendLimit 較高。→ 管理虛擬卡資金來源

核准金額 vs 請求金額

卡組織會請求一個金額；Fluz 會紀錄核准的金額。發生部分核准時兩者會不同，實際被保留的是核准金額。請從 Fluz 記錄讀取金額，而非假設它等於商家請求的金額。

遭拒

遭拒的授權會回傳一個回應碼給商家，並在 Fluz 端產生 declineReason 與 declineCategory。最常見原因包含金額超過消費上限、卡片被鎖、卡片背後資金不足、品牌鎖定卡片在不符商家使用，以及 CVV 或 AVS 不符。→ 拒絕代碼

非購買型的授權

類型	內容	該怎麼處理
$0 /$ 0.01 探測	商家在儲存卡片或之後扣款前，先確認卡片有效	預期會出現，不要計入消費。它會自行撤銷。
預授權	在最終金額未確定前先放置保留——飯店、租車、加油站	預期之後會有不同金額的清算，且常在數日後。
增額授權	疊加在未結束預授權上的額外保留	將保留相加；不要把第二筆當作第二次購買。
加油機	依卡組織規則設定的固定金額，與實際加油量無關	清算會帶有真實金額。

保留資金

核准的授權會降低卡片可支用的金額，但不會把錢自帳戶移出。在清算前：

卡片的 remainingBalance 會反映該保留
分類帳記錄處於 PENDING
expectedClearedDate 告訴你何時再查看

若始終沒收到清算，保留不會永久存在——卡組織的到期規則會釋放它，資金會回到卡片可用餘額。多數授權約一週內到期；旅遊與住宿的保留時間較長。確切時窗由卡組織與商家決定，而非 Fluz。

撤銷（Reversal）

撤銷是在清算「之前」取消授權。保留被釋放，資金回到卡片。撤銷可為全部或部分。常見原因：

商家放棄交易，或端末機逾時
商品缺貨，或持卡人在出貨前取消
發出重複授權
授權到期但未清算

清算之後的「撤銷」其實是退款。交易一旦清算，就不再有可釋放的保留。之後回來的金額會以貸項呈現——獨立的 REFUND 記錄——並應以此方式處理。有無對應的清算即為兩種情況的分界線。

清算與結算

清算是商家提交最終金額，通常作為隔夜批次的一部分。Fluz 使用卡組織的參考識別碼將其對應到開放中的授權，並將記錄定稿。需面對的現實：

金額會變動。 小費、加油、匯率與分批出貨都會改變數字。
可能不只一筆清算。 分批出貨會針對同一授權分段清算，且各段可能無序到達。
可能出現無授權的清算。 在某些情況下卡組織允許商家強制入帳——離線端末機、機上消費、交通費聚合。Fluz 會監控這些，但你的分類帳必須接受一筆直接以已清算狀態出現、且沒有待處理階段的購買。
比對不保證成功。 罕見情況下，清算上的識別碼與其所屬的授權對不上，清算會以獨立記錄出現。

不要只依卡組織參考識別碼進行對帳。 它們不保證在交易生命週期內保持一致，且跨卡組織不穩定。請在你建立訂單時，將 Fluz 的 record_id 與 reference_id 一併儲存在你的系統中。→ 與你自家系統對帳

退款

商家退回款項會透過卡組織送出貸項。Fluz 會在卡片 feed 上以 REFUND 呈現，並在分類帳上記為貸方。它可能先以授權到達，稍後清算；或直接僅有清算。兩種會讓天真配對失準的情況：

未連結退款。 卡組織可能在貸項上不附帶原始購買的參考，或使用不同的識別碼。它會以獨立貸項到達，無從關聯。
批次退款。 多筆來自不同原始購買的退款，可能共享卡組織識別碼並被彙整到一起到達。

因上述情形，請不要假設退款與購買之間為一對一關係。將退款視為針對卡片的獨立貸項對帳，並以餘額作為單一真實來源。

外幣

以其他貨幣進行的購買，會以美元清算，並在記錄上保留原始金額：

欄位	意義
`originalCurrencyCode`	商家收取之貨幣的 ISO 4217 代碼
`originalCurrencyAmount`	原始金額，為最小單位——`6300` HKD 代表 HK$63.00
`currencyConversionRate`	換算為美元所使用的匯率。國內交易為 `1.0`

這三個欄位會同時回傳——要嘛全部有值，要嘛全部為 null。換匯發生在清算時，因此外幣授權與其清算即使商家收取相同金額，換算成美元後通常也會不同。

常見訊息序列

除了兩條順利路徑外，下列序列值得納入測試涵蓋。

序列	內容
`AUTHORIZE_AND_CLEAR`	PIN 借記、ATM、交通——沒有待處理視窗
`AUTHORIZE` → `CLEAR`	標準購買
`AUTHORIZE` → `CLEAR`（較高）	餐廳在刷卡後新增小費
`AUTHORIZE` → `CLEAR`（較低）	分批出貨，或飯店帳單低於預授權
`AUTHORIZE` → `AUTHORIZE` → `CLEAR`	預授權加增額授權，清算一次完成
`AUTHORIZE` → `CLEAR` → `CLEAR`	分批出貨，分段清算
`AUTHORIZE` → `REVERSAL`	清算前放棄交易
`AUTHORIZE` → `REVERSAL`（部分）→ `CLEAR`	部分保留被釋放，其餘清算
`AUTHORIZE` → (expiry)	從未收到清算；到期後保留被釋放
`CLEAR` 無 `AUTHORIZE`	強制入帳——離線端末機、機上消費、交通費聚合
`AUTHORIZE` → `CLEAR` → `REFUND`	購買後續被全部或部分退款
`VERIFICATION` ($0.00)	卡號儲存驗證，稍後即被撤銷

依生命週期進行開發

將待處理與已清算視為不同事物

切勿將待處理授權顯示為已完成購買，且永遠不要把授權與清算加總在一起。若需要單一數字，請加總已清算記錄，並將保留款分開顯示。

訂閱三種交易事件

TRANSACTION_CREATE、TRANSACTION_UPDATE 與 TRANSACTION_DECLINE。只監聽 create 的整合，會讓每筆交易永遠停留在授權金額。→ Webhooks

以 updatedGte 同步，而非 createdGte

一筆以 PENDING 建立、之後清算的記錄，會變更的是 updated 時戳，而非 created。用建立日期同步會悄悄漏掉每一次結算。

用快照對帳餘額

每筆分類帳記錄都帶有每個餘額的事後狀態。讀取那些欄位，而不是自行加總金額——它們已包含手續費、現金回饋與未清保留。

讓處理常式具備冪等性

Webhook 會重試，且清算可能無序到達。以 Fluz 記錄識別碼為鍵，讓重播成為無副作用。

測試生命週期

Staging 卡是實際的卡片記錄，但不在真實卡組織網路上，因此交易是注入到它們上，而非刷卡。你可以測試授權、分開的清算、拒絕、撤銷、退款與零元探測——其產生的記錄與 webhook 與正式環境相同。 → 模擬虛擬卡交易

下一步

交易總覽

統一分類帳——記錄包含什麼，以及如何對帳。

取得虛擬卡交易

卡層級動態、篩選、外匯欄位與分頁。

取得遭拒交易

從未成為交易的授權。

拒絕代碼

每個拒絕原因與分類，以及各自的處理方式。

模擬虛擬卡交易

在 staging 卡放入測試消費，觀察生命週期運行。

Webhooks

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

​三個階段

​一次購買，數筆記錄

​單訊息與雙訊息流程

​單訊息

​雙訊息

​錢在哪裡

​Fluz 在各階段記錄什麼

​授權

​非購買型的授權

​保留資金

​撤銷（Reversal）

​清算與結算

​退款

​外幣

​常見訊息序列

​依生命週期進行開發

​測試生命週期

​下一步

交易總覽

取得虛擬卡交易

取得遭拒交易

拒絕代碼

模擬虛擬卡交易

Webhooks

三個階段

一次購買，數筆記錄

單訊息與雙訊息流程

單訊息

雙訊息

錢在哪裡

Fluz 在各階段記錄什麼

授權

非購買型的授權

保留資金

撤銷（Reversal）

清算與結算

退款

外幣

常見訊息序列

依生命週期進行開發

測試生命週期

下一步