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

# 交易生命週期

> 卡片消費如何從商家終端機一路抵達你的分類帳——授權、請款、結算、沖正與退款——以及 Fluz 在每一步所記錄的內容。

在 Fluz 發行的卡片上完成的一次購買並非單一事件。這是一段在商家、卡網與 Fluz 之間進行的對話，可能耗時數秒、數小時，甚至數週——在結束前，會在你的系統側產生多筆紀錄。

本頁說明各階段會發生什麼、每個階段會產生哪些 Fluz 紀錄與 webhook，以及哪些地方最容易讓天真的整合把算術做錯。

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

***

## 三個階段

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

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

***

## 一筆購買，數筆紀錄

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

| 資料源       | 查詢                           | 呈現內容                        |
| :-------- | :--------------------------- | :-------------------------- |
| **卡片活動**  | `getVirtualCardTransactions` | 一張或多張卡的消費，含商家、MCC、匯率與卡網回應欄位 |
| **帳戶分類帳** | `getTransactions`            | 帳戶上的每一筆資金移動，且每筆紀錄後附帶餘額快照    |
| **被拒授權**  | `getDeclinedTransactions`    | 被拒且從未成為交易的授權                |

三筆購買，以及每筆留下的紀錄：

```text theme={null}
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
```

<Warning>
  **退款是新的紀錄，而不是舊紀錄的編輯。**

  退款會以獨立的 `REFUND` 交易抵達。原始的 `PURCHASE` 紀錄並不會有任何變動——其金額維持不變。若你的系統在退款入帳時去減少原始購買金額，你會把貸方計入兩次。請在紀錄層級進行對帳；永遠不要竄改原始紀錄。
</Warning>

***

## 單訊息與雙訊息流程

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

### 單訊息（Single-message）

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

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant M as Merchant
    participant N as Card network
    participant F as Fluz
    participant Y as Your integration

    M->>N: Purchase, $25.00
    N->>F: Authorize and clear
    F->>F: Spend controls + funding check
    F-->>N: Approved
    N-->>M: Approved
    F->>Y: TRANSACTION_CREATE
    F->>Y: TRANSACTION_UPDATE (cleared)
```

### 雙訊息（Dual-message）

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

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant M as Merchant
    participant N as Card network
    participant F as Fluz
    participant Y as Your integration

    M->>N: Authorization request, $50.00
    N->>F: Authorize
    F->>F: Spend controls + funding check
    F-->>N: Approved, funds held
    N-->>M: Approved
    F->>Y: TRANSACTION_CREATE (pending)

    Note over M,F: Hours to days pass

    M->>N: Batch submitted, $54.00 with tip
    N->>F: Clear
    F->>F: Match to authorization, finalize
    F->>Y: TRANSACTION_UPDATE (cleared, $54.00)
```

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

### 資金的位置

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

```mermaid theme={null}
stateDiagram-v2
    [*] --> Available: Funds in the spend account
    Available --> Held: Authorization approved
    Held --> Available: Reversal or expiration
    Held --> Cleared: Clearing received
    Available --> Cleared: Single-message transaction
    Cleared --> Credited: Refund received
    Credited --> [*]
    Cleared --> [*]
```

***

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

<Warning>
  **兩種資料源，兩套狀態詞彙。**

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

  它們從兩個角度描述同一生命週期。不要撰寫假設兩處會使用同一詞彙的程式碼。→ [GraphQL API 的運作方式](/concepts/graphql)
</Warning>

<Note>
  **被拒不等於交易。** 被拒的授權不會進入帳戶分類帳，因此在任何狀態下都不會出現在 `getTransactions`。請透過 `getDeclinedTransactions` 查詢，並從[拒絕代碼](/features/decline-codes)讀取原因。
</Note>

***

## 授權（Authorization）

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

<AccordionGroup>
  <Accordion title="會檢查哪些項目" icon="list-checks">
    * 卡片為 `ACTIVE`——未鎖定、未到期、未過 `lockDate`，且未因單次使用規則而被消耗
    * 金額符合卡片的 `spendLimit` 與其 `spendLimitDuration`
    * 若卡片簽發於品牌鎖定計畫，商家需符合該品牌鎖定規則
    * 帳戶持有人已通過身分驗證
    * 卡片背後的資金來源可涵蓋該金額
    * 銀行計畫本身的限制未被超過
  </Accordion>

  <Accordion title="資金來源" icon="wallet">
    卡片本身不持有餘額。它會在授權時，依據發卡時設定的資金堆疊提領：

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

    若授權金額超過上述來源可涵蓋的金額，將會被拒，即使卡片的 `spendLimit` 較高。→ [管理虛擬卡資金來源](/Manage-Virtual-Card-Funding-Sources)
  </Accordion>

  <Accordion title="核准金額 vs. 請求金額" icon="equal-not">
    卡網會請求一個金額；Fluz 會記錄其核准的金額。在部分核准時兩者會不同，而被保留的是核准金額。請從 Fluz 紀錄讀取金額，不要假設它與商家請求相同。
  </Accordion>

  <Accordion title="拒絕（Declines）" icon="circle-x">
    被拒的授權會回傳一個回應碼給商家，並在 Fluz 端產生 `declineReason` 與 `declineCategory`。最常見的原因有金額超過消費上限、卡片被鎖定、卡片背後資金不足、品牌鎖定卡於錯誤商家使用、以及 CVV 或 AVS 不符。→ [拒絕代碼](/features/decline-codes)
  </Accordion>
</AccordionGroup>

### 非購買型授權

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

### 保留資金

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

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

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

***

## 沖正（Reversals）

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

常見原因：

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

<Warning>
  **在請款之後的「沖正」其實是退款。**

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

***

## 請款與結算

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

需面對的現實：

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

<Warning>
  **不要只依卡網參考識別碼進行對帳。** 它們不保證在交易生命週期中維持一致，也不在不同卡網之間穩定。請在你建立自家訂單時，將 Fluz 的 `record_id` 與 `reference_id` 一併存入。→ [與你的系統對帳](/features/transactions-details-overview#reconciling-against-your-own-system)
</Warning>

***

## 退款（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)               | 檔案代扣卡驗證，稍後即沖正         |

***

## 依據生命週期建置

<Steps>
  <Step title="將待處理與已請款視為不同狀態">
    別把待處理授權當成已完成購買，也別把授權與請款金額相加。若你需要單一數字，請彙總已請款紀錄，並將保留另行顯示。
  </Step>

  <Step title="訂閱三種交易事件">
    `TRANSACTION_CREATE`、`TRANSACTION_UPDATE` 與 `TRANSACTION_DECLINE`。只聽 create 的整合會讓每筆交易永遠停在授權金額。→ [Webhooks](/fluz-dashboard/webhooks)
  </Step>

  <Step title="以 updatedGte 而非 createdGte 進行同步">
    一筆以 `PENDING` 建立、後續請款完成的紀錄會變更其 updated 時戳，而非 created。用建立日期同步會無聲錯過所有結算。
  </Step>

  <Step title="用快照對帳餘額">
    每筆分類帳紀錄都攜帶各餘額的事後狀態。讀取這些欄位，而非自行加總金額——它們已包含手續費、現金回饋與未結保留。
  </Step>

  <Step title="讓處理常式具備冪等性">
    Webhook 會重試，且請款可能無序到達。以 Fluz 紀錄識別碼作為鍵，讓重放成為無副作用。
  </Step>
</Steps>

***

## 測試生命週期

Staging 卡片是實際的卡片紀錄，但不連接至真實卡網，因此交易是注入到它們上，而非刷卡。你可以操作授權、分開請款、拒絕、沖正、退款與零元探針——每一種都會產生與正式環境相同的紀錄與 webhook。

→ [模擬虛擬卡交易](/Simulate-Virtual-Card-Transactions)

***

## 下一步

<CardGroup cols={2}>
  <Card title="交易總覽" icon="list" href="/features/transactions-details-overview">
    統一分類帳——紀錄包含哪些內容以及如何對帳。
  </Card>

  <Card title="取得虛擬卡交易" icon="credit-card" href="/features/get-virtual-card-transactions">
    卡片層級活動、篩選、外匯欄位與分頁。
  </Card>

  <Card title="取得被拒交易" icon="circle-x" href="/features/get-decline-transactions">
    從未成為交易的授權。
  </Card>

  <Card title="拒絕代碼" icon="triangle-alert" href="/features/decline-codes">
    各種拒絕原因與分類，以及對應處置。
  </Card>

  <Card title="模擬虛擬卡交易" icon="flask-conical" href="/Simulate-Virtual-Card-Transactions">
    在 staging 卡上放入測試消費並觀察整個生命週期。
  </Card>

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