交易生命週期

在 Fluz 發行的卡片上完成的一次購買並非單一事件。這是一段在商家、卡網與 Fluz 之間進行的對話，可能耗時數秒、數小時，甚至數週——在結束前，會在你的系統側產生多筆紀錄。本頁說明各階段會發生什麼、每個階段會產生哪些 Fluz 紀錄與 webhook，以及哪些地方最容易讓天真的整合把算術做錯。

本頁涵蓋開環卡交易——在卡網上由 Fluz 發行的虛擬卡之消費。禮品卡購買、存款、提領與錢包轉帳不會走這個生命週期；它們在各自的軌道上結算。參見交易總覽以瞭解承載所有交易的統一分類帳。

三個階段

階段	發生什麼事	誰的資金在移動
授權（Authorization）	卡網詢問 Fluz 是否可對該卡請款。Fluz 檢查卡片控管與資金，並回覆。	尚未移動。資金被保留，未撥付。
請款（Clearing）	商家提交最終金額。Fluz 針對先前保留的資金完成紀錄。	保留款轉為實際扣款。
結算（Settlement）	卡網在收單行與發卡行之間移轉資金。	銀行對銀行。對你的整合而言是不可見的。

結算是銀行端在請款之後、依卡網自身時程運行的流程。Fluz 將請款與結算視為同一事件——當交易在 Fluz 上已請款，便可視為最終結果。

一筆購買，數筆紀錄

單筆購買可能產生一筆授權、一次或多次請款，並且可能伴隨一筆沖正或退款。Fluz 透過三種查詢呈現它們，各自回答不同問題：

資料源	查詢	呈現內容
卡片活動	`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 紀錄並不會有任何變動——其金額維持不變。若你的系統在退款入帳時去減少原始購買金額，你會把貸方計入兩次。請在紀錄層級進行對帳；永遠不要竄改原始紀錄。

單訊息與雙訊息流程

卡網傳送幾則訊息，取決於商家與交易型態。兩種流程都屬正常，你的整合須同時支援。

單訊息（Single-message）

卡網以單一訊息同時完成授權與請款。常見於 PIN 借記、ATM 提領與運輸。沒有待處理視窗——交易幾乎立即定案。

雙訊息（Dual-message）

卡網先送授權，商家稍後再提交請款——通常是當晚，但飯店、租車與旅遊可能延遲數日。兩者之間的落差稱為待處理視窗，亦是大多數對帳錯誤產生之處。

請款金額可能與授權金額不同。 小費、加油機、幣別轉換與分批出貨都可能導致請款高於或低於原始保留金額。以請款金額為準，切勿將授權金額視為最終金額。

資金的位置

同一生命週期，從帳戶角度觀之：

Fluz 在各階段的紀錄

卡網訊息	含義	卡片資料源 `transactionType`	分類帳 `status`	Webhook
Verification	$0.00 或$ 0.01 的探針以確認卡片可用	`PURCHASE`，很快被沖正	`PENDING`，已釋放	`TRANSACTION_CREATE`
Authorization	在等待最終金額期間預留資金	`PURCHASE`	`PENDING`	`TRANSACTION_CREATE`
Authorize and clear	單一訊息完成核准並定案	`PURCHASE`	`SETTLED`	`TRANSACTION_CREATE` + `TRANSACTION_UPDATE`
Clearing	對先前授權的交易完成定案	`PURCHASE`	`SETTLED`	`TRANSACTION_UPDATE`
Decline	授權被拒	`DECLINE`	無分類帳紀錄	`TRANSACTION_DECLINE`
Reversal	在請款前釋放授權	保留已釋放	紀錄已釋放	`TRANSACTION_UPDATE`
Refund	在購買請款後退回的金額	`REFUND`	`SETTLED` 貸方	`TRANSACTION_CREATE`

兩種資料源，兩套狀態詞彙。

getVirtualCardTransactions 回傳如 PROCESSING 與 CLEARED 的 transactionStatus。
getTransactions 回傳 PENDING 與 SETTLED 的 status。

它們從兩個角度描述同一生命週期。不要撰寫假設兩處會使用同一詞彙的程式碼。→ GraphQL API 的運作方式

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

授權（Authorization）

當卡網請 Fluz 核准請款時，Fluz 會根據卡片、帳戶與卡片背後的資金來審核請求。這一切都在不到一秒內完成，因為卡網會逾時。

會檢查哪些項目

卡片為 ACTIVE——未鎖定、未到期、未過 lockDate，且未因單次使用規則而被消耗
金額符合卡片的 spendLimit 與其 spendLimitDuration
若卡片簽發於品牌鎖定計畫，商家需符合該品牌鎖定規則
帳戶持有人已通過身分驗證
卡片背後的資金來源可涵蓋該金額
銀行計畫本身的限制未被超過

資金來源

卡片本身不持有餘額。它會在授權時，依據發卡時設定的資金堆疊提領：

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

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

核准金額 vs. 請求金額

卡網會請求一個金額；Fluz 會記錄其核准的金額。在部分核准時兩者會不同，而被保留的是核准金額。請從 Fluz 紀錄讀取金額，不要假設它與商家請求相同。

拒絕（Declines）

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

非購買型授權

類型	內容	該如何處理
$0 /$ 0.01 探針	商家在儲存卡片或日後扣款前確認卡片有效	屬預期情況，且不應計入消費。會自行沖正。
預授權	在最終金額未定前先行保留——如飯店、租車、加油	預期之後會有金額不同的請款，且常在數日後。
增額授權（Incremental）	疊加於開放中的預授權之上的額外保留	將保留金額合計；不要把第二筆視為第二次購買。
加油機	依卡網規則設定的固定金額，與實際加油量無關	請款會帶有實際金額。

保留資金

核准的授權會降低卡片可用的消費額度，但不會把資金從帳戶移出。在請款前：

卡片的 remainingBalance 反映該筆保留
分類帳紀錄為 PENDING
expectedClearedDate 告知你何時再查看

若請款遲遲未到，保留不會永遠存在——卡網的到期規則會釋放它，資金會回到卡片可用餘額。多數授權約在一週內到期；旅遊與住宿的保留時間更長。確切時窗由卡網與商家設定，非 Fluz 所定。

沖正（Reversals）

沖正在請款前取消授權。保留被釋放，資金回到卡片。沖正可以是全部或部分。常見原因：

商家放棄交易，或終端逾時
商品缺貨，或持卡人在出貨前取消
重複送出授權
授權在沒有請款的情況下到期

在請款之後的「沖正」其實是退款。一旦交易已請款，就沒有可釋放的保留。之後退回的金額會以貸方入帳——一筆獨立的 REFUND 紀錄——且應以此方式處理。是否存在對應的請款，是區分兩種情況的界線。

請款與結算

請款是商家提交最終金額，通常作為隔夜批次的一部分。Fluz 使用卡網的參考識別碼將其匹配到未結的授權，並完成該筆紀錄。需面對的現實：

金額會改變。 小費、加油、匯率換算、分批出貨都會改動數字。
可能有多次請款。 分批出貨會以多段請款對應同一授權，且順序可能不一致。
可能出現無授權的請款。 在某些情況下卡網允許商家強制入帳——離線終端、機上購物、運輸票價彙總。Fluz 會監控這些情況，但你的分類帳必須接受一筆沒有待處理階段、直接已請款的購買。
匹配不保證成功。 罕見情況下，請款上的識別碼無法與其所屬授權對上，該請款會以獨立紀錄出現。

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

退款（Refunds）

商家退回金額會透過卡網以貸方送達。Fluz 在卡片資料源上以 REFUND 呈現，並在分類帳上記作貸方。它可能先以授權抵達、稍後請款，或直接以請款入帳。兩種會打破天真配對的情況：

未連結退款（Unlinked refunds）。 卡網可能在沒有引用原始購買、或帶著不同識別碼的情況下送出貸方。它會作為獨立的貸方入帳，無可連結對象。
批次退款（Batched refunds）。 多筆不同原始購買的退款可能共享卡網識別碼並一併到達。

基於上述兩點，不要假設退款與購買是一對一關係。請將退款作為獨立的卡片貸方進行對帳，並以餘額為最終準則。

外幣

以其他幣別消費會以美元請款，且原始金額保存在紀錄中：

欄位	意義
`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` without `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

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

​三個階段

​一筆購買，數筆紀錄

​單訊息與雙訊息流程

​單訊息（Single-message）

​雙訊息（Dual-message）

​資金的位置

​Fluz 在各階段的紀錄

​授權（Authorization）

​非購買型授權

​保留資金

​沖正（Reversals）

​請款與結算

​退款（Refunds）

​外幣

​常見訊息序列

​依據生命週期建置

​測試生命週期

​下一步

交易總覽

取得虛擬卡交易

取得被拒交易

拒絕代碼

模擬虛擬卡交易

Webhooks

三個階段

一筆購買，數筆紀錄

單訊息與雙訊息流程

單訊息（Single-message）

雙訊息（Dual-message）

資金的位置

Fluz 在各階段的紀錄

授權（Authorization）

非購買型授權

保留資金

沖正（Reversals）

請款與結算

退款（Refunds）

外幣

常見訊息序列

依據生命週期建置

測試生命週期

下一步