交易生命週期

使用 Fluz 發行的卡片進行消費並非單一事件。這是商家、卡片網路與 Fluz 之間的一場對話,可能歷時數秒、數小時,有時甚至數週——而在完成之前,會在您這端產生多筆記錄。本頁說明每個階段會發生什麼事、每個階段會產生哪些 Fluz 記錄與 webhook,以及天真的整合方式容易在計算上出錯的地方。

本頁涵蓋開放迴圈卡片交易——即 Fluz 發行至卡片網路上的虛擬卡消費行為。禮品卡購買、儲值、提領與錢包轉帳並不會經過此生命週期,而是透過各自的清算管道結算。如需查看彙整所有交易的統一分類帳,請參閱交易總覽。

三個階段

階段	發生了什麼事	誰的資金會移動
授權	卡片網路詢問 Fluz 該卡片是否可以被扣款。Fluz 會檢查卡片的控管條件與資金狀況,並給予回覆。	尚未移動任何資金。資金會被保留,而非移動。
清算	商家提交最終金額。Fluz 會依據保留的資金將該筆記錄定案。	保留款項會轉為實際扣款。
結算	卡片網路在收單行與發卡行之間移動資金。	銀行對銀行。您的整合系統看不到這個過程。

結算是一項銀行作業流程,依卡片網路自身的時程,在清算之後進行。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 記錄的任何內容都不會改變——其金額維持不變。如果您的系統在退款到達時去減少原始消費金額,就會重複計算該筆貸方金額。請在記錄層級進行核對,絕不要更動原始記錄。

單訊息與雙訊息流程

卡片網路會傳送幾則訊息,取決於商家與交易類型。這兩種流程都是正常情況,您的整合系統必須同時處理這兩者。

單訊息

卡片網路會傳送一則同時完成授權與清算的訊息。常見於 PIN 金融卡、ATM 提款與大眾運輸交易。這類交易沒有待處理期間——幾乎立即就會定案。

雙訊息

卡片網路會先傳送一則授權訊息,商家稍後再提交清算——通常是當天夜間,但飯店、租車與旅遊類交易則可能長達數天。這兩者之間的間隔就是待處理期間,也是大多數核對問題的根源所在。

**清算金額可能與授權金額不同。**小費、加油站、貨幣兌換與部分出貨,都可能使清算金額高於或低於原始保留金額。請以清算金額為準,絕不要將授權金額視為最終金額。

資金所在位置

同樣的生命週期,從帳戶角度(而非網路角度)來看:

Fluz 在每個階段記錄的內容

卡片網路訊息	代表意義	卡片資訊來源 `transactionType`	分類帳 `status`	Webhook
驗證	一筆 $0.00 或 $0.01 的探測,用來確認卡片是否有效	`PURCHASE`,隨後即撤銷	`PENDING`,隨後釋出	`TRANSACTION_CREATE` + `TRANSACTION_UPDATE`
授權	在最終金額確定前先保留資金	`PURCHASE`	`PENDING`	`TRANSACTION_CREATE`
授權並清算	在同一則訊息中核准並定案	`PURCHASE`	`SETTLED`	`TRANSACTION_CREATE` + `TRANSACTION_UPDATE`
清算	將先前已授權的交易定案	`PURCHASE`	`SETTLED`	`TRANSACTION_UPDATE`
拒絕	該筆授權遭到拒絕	`DECLINE`	無分類帳記錄	`TRANSACTION_DECLINE`
撤銷	授權在清算前被釋出	保留款項釋出	記錄已釋出	`TRANSACTION_UPDATE`
退款	消費清算後款項退回	`REFUND`	`SETTLED` 貸方	`TRANSACTION_CREATE`

兩種資訊來源,兩套狀態用語。

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

這兩者是從不同角度描述同一個生命週期。請不要撰寫在兩處都預期使用同一套用語的程式碼。→ GraphQL API 的運作方式

**遭拒絕的授權不是一筆交易。**遭拒絕的授權永遠不會進入帳戶分類帳,因此無論何種狀態都不會出現在 getTransactions 中。請透過 getDeclinedTransactions 查詢這些記錄,並從拒絕代碼中了解拒絕原因。

授權

當卡片網路要求 Fluz 核准一筆扣款時,Fluz 會針對卡片、帳戶,以及卡片背後的資金來源評估這項請求。整個過程會在遠低於一秒的時間內完成,因為卡片網路會逾時。

會檢查哪些項目

卡片狀態為 ACTIVE——未鎖定、未過期、未超過其 lockDate,且尚未因單次使用規則而被消耗
金額在卡片 spendLimitDuration 期間內符合 spendLimit 限制
若卡片是在品牌鎖定方案下發行,商家須符合卡片的品牌鎖定條件
帳戶持有人已通過身分驗證
卡片背後的資金來源足以支付該金額
未超出銀行方案本身的限制

資金來源為何

卡片本身並不持有餘額。在授權當下,會依照卡片發行時設定的資金堆疊順序來扣款:

userCashBalanceId 中指定的消費帳戶,或帳戶預設值
預付(禮品卡)餘額,除非 usePrepaymentBalance: false
現金回饋餘額,除非 useRewardsBalance: false
當 primaryFundingSource 為 BANK_ACCOUNT 時,使用外部銀行帳戶

若授權金額超出這些資金來源所能支付的範圍,即使卡片的 spendLimit 較高,該筆授權仍會遭到拒絕。→ 管理虛擬卡資金來源

核准金額與請求金額的差異

卡片網路會請求一個金額;Fluz 則會記錄其核准的金額。在部分核准的情況下,兩者會不同,而遭保留的金額是核准後的金額。請以 Fluz 記錄中的金額為準,不要假設它與商家請求的金額相同。

拒絕

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

並非消費行為的授權

類型	說明	該如何處理
$0 /$ 0.01 探測	商家在儲存卡片或稍後扣款之前,確認卡片仍然有效	屬正常情況,請勿計入消費金額,它會自行撤銷。
預先授權	在最終金額確定前所設下的保留款項——常見於飯店、租車與加油站	預期清算金額會不同,且往往會延遲數天才發生。
追加授權	在既有的預先授權上疊加的額外保留款項	應加總所有保留款項;不要將第二筆視為另一筆獨立消費。
加油站油槍	依卡片網路規則設定的固定金額,與實際加油量無關	清算時會帶入實際金額。

保留款項

經核准的授權會降低卡片仍可消費的額度,但不會將資金移出帳戶。在清算完成之前:

卡片的 remainingBalance 會反映該筆保留款項
分類帳記錄會維持在 PENDING 狀態
expectedClearedDate 會告訴您何時該再次查看

如果清算始終沒有到來,保留款項也不會永遠留在那裡——卡片網路的過期規則會將其釋出,資金會回到卡片的可用餘額中。大多數授權會在約一週內過期;旅遊與住宿類的保留款項則會維持更久。確切的期限是由卡片網路與商家設定,而非由 Fluz 決定。

撤銷

撤銷會在授權_尚未_清算前將其取消。保留款項會被釋出,資金會回到卡片上。撤銷可以是全額,也可以是部分撤銷。常見原因:

商家放棄了該筆交易,或端末機逾時
商品缺貨,或持卡人在出貨前取消訂單
傳送了重複的授權
授權已過期但未收到清算

清算之後的「撤銷」實際上是退款。一旦交易完成清算,就沒有保留款項可供釋出。此後回來的資金會以貸方形式出現——也就是獨立的 REFUND 記錄——並應以此方式處理。是否存在對應的清算記錄,正是區分這兩種情況的分界點。

清算與結算

清算是指商家提交最終金額,通常屬於夜間批次處理的一部分。Fluz 會使用卡片網路的參照識別碼,將其與待處理的授權配對,並將該筆記錄定案。開發時必須考量的實際情況:

**金額會改變。**小費、燃油、外匯與部分出貨,都會使金額產生變動。
**可能會有不只一筆清算。**分批出貨會針對同一筆授權分次清算,且各筆清算到達的順序可能不一致。
**清算可能在沒有授權的情況下出現。**卡片網路在某些情況下允許商家強制入帳(force-post)——例如離線端末機、飛行途中的消費,或大眾運輸票價彙總扣款。Fluz 會監控這類情況,但您的分類帳必須能接受一筆「看似已清算、卻沒有待處理階段」的消費。
**配對並非保證成功。**在少數情況下,清算上的識別碼與其所屬的授權對不上,該筆清算就會以獨立記錄的形式出現。

**請勿只依賴卡片網路的參照識別碼來進行核對。**這些識別碼並不保證在交易的整個生命週期中維持一致,在不同卡片網路之間也不穩定。請在建立自己的訂單當下,將 Fluz 的 record_id 與 reference_id 一併儲存。→ 與您自己的系統進行核對

退款

商家退回款項時,會透過卡片網路送回一筆貸方款項。Fluz 會在卡片資訊來源中將其記錄為 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` → (過期)	始終未收到清算;保留款項於過期時釋出
沒有 `AUTHORIZE` 的 `CLEAR`	強制入帳——離線端末機、飛行途中、大眾運輸彙總扣款
`AUTHORIZE` → `CLEAR` → `REFUND`	消費之後全額或部分退款
`VERIFICATION`($0.00)	卡片存檔驗證,隨後不久即撤銷

針對此生命週期進行開發

將待處理與已清算視為不同的狀態

絕不要將待處理的授權顯示為已完成的消費,也絕不要將授權與清算加總在一起。如果需要單一數字,請只加總已清算的記錄,並將保留款項另外顯示。

訂閱全部三種交易事件

TRANSACTION_CREATE、TRANSACTION_UPDATE 與 TRANSACTION_DECLINE。只監聽建立事件的整合系統,會讓每筆交易永遠卡在其授權金額上。→ Webhooks

以 updatedGte 而非 createdGte 進行同步

記錄建立時為 PENDING、之後完成清算時,改變的是其更新時間戳記,而非建立時間戳記。以建立日期進行同步,會在不知不覺中漏掉每一筆結算。

根據快照核對餘額

每一筆分類帳記錄都帶有所有餘額的異動後狀態。請直接讀取這些欄位,而不要自行加總金額——這些欄位已經考量了手續費、現金回饋與尚未結清的保留款項。

讓處理程式具備冪等性

Webhook 會重試,清算也可能不按順序到達。請以 Fluz 記錄識別碼作為鍵值,並讓重複執行不產生任何效果。

測試此生命週期

預備環境(staging)卡片是真實的卡片記錄,但不在正式運作的卡片網路上,因此交易是以注入方式產生,而非透過刷卡產生。您可以測試授權、獨立清算、拒絕、撤銷、退款,以及零元探測——每一種都會產生與正式環境相同的記錄與 webhook。 → 模擬虛擬卡交易

後續步驟

交易總覽

統一分類帳——記錄包含哪些內容,以及如何進行核對。

取得虛擬卡交易

卡片層級的活動、篩選條件、外匯欄位與分頁。

取得遭拒絕的交易

從未成為交易的授權。

拒絕代碼

每一種拒絕原因與分類,以及各自的處理方式。

模擬虛擬卡交易

在預備環境卡片上進行測試消費,觀察整個生命週期的運作過程。

Webhooks

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

​三個階段

​一筆消費,多筆記錄

​單訊息與雙訊息流程

​單訊息

​雙訊息

​資金所在位置

​Fluz 在每個階段記錄的內容

​授權

​並非消費行為的授權

​保留款項

​撤銷

​清算與結算

​退款

​外幣交易

​常見的訊息序列

​針對此生命週期進行開發

​測試此生命週期

​後續步驟

交易總覽

取得虛擬卡交易

取得遭拒絕的交易

拒絕代碼

模擬虛擬卡交易

Webhooks

三個階段

一筆消費,多筆記錄

單訊息與雙訊息流程

單訊息

雙訊息

資金所在位置

Fluz 在每個階段記錄的內容

授權

並非消費行為的授權

保留款項

撤銷

清算與結算

退款

外幣交易

常見的訊息序列

針對此生命週期進行開發

測試此生命週期

後續步驟