Webhooks - Fluz

Webhooks 讓你的應用程式在 Fluz 平台上發生事件時即時接收通知。與其輪詢變更，你只需註冊一個 HTTPS 端點，Fluz 就會在事件發生當下把資料推送給你——例如虛擬卡交易、被拒交易、完成的存款、使用者透過 OAuth 連結其帳戶，等等。

本頁涵蓋所有 webhook 事件，橫跨多個平台範疇（交易活動、存款、元件流程，以及 OAuth 帳戶連結），而非屬於單一功能。

Webhooks 適用於 Fluz 平台上的所有應用程式類型：在你自己的帳戶上運作的私人應用程式、代表其他使用者透過 API 行動的公共 OAuth 應用程式，以及嵌入式元件應用程式。

運作方式

在開發者平台為你的應用程式註冊一個 webhook URL。
選擇要監聽的事件類型（或訂閱全部）。
當符合的事件發生時，Fluz 會以 HTTP POST 將簽名的 JSON 載荷送到你的 URL。
你的伺服器驗證簽章、以 2xx 回應並處理該事件。

如果你的端點不可用或回應錯誤，Fluz 會採用指數退避最多重試5 次，之後放棄該次投遞。

依應用程式類型的 Webhooks

事件如何導向到你的應用程式，取決於你的應用程式模型。

私人應用程式 — 你的自有帳戶

Webhooks 會針對你的自有帳戶的活動觸發。你所擁有的帳戶上任何交易、拒絕或存款，都會觸發在你的應用程式上註冊的 webhooks。 常見使用情境： 當虛擬卡交易被授權或結算時發送通知；即時拒絕警示；監控你的消費帳戶上的存款與餘額變化。

公共應用程式（OAuth） — 代表使用者行動

Webhooks 會針對已授權你的應用程式之帳戶的活動觸發。當使用者透過 OAuth 授與你的應用程式存取權時，他們的事件會導向到你註冊的 webhooks——前提是該使用者的 OAuth 授權包含所需的範圍（scopes）。不論使用者是透過你的直接 API 串接，還是透過嵌入式元件進行互動，皆適用；關鍵在於使用者與你的應用程式之間存在 OAuth 關係。 常見使用情境： 知道使用者已將其帳戶連結（或重新連結）到你的應用程式；監控已連結帳戶的虛擬卡消費；即時拒絕通知；追蹤存款完成；接收 KYC 與 KYB 狀態更新。

元件應用程式

元件應用程式是特殊的公共應用程式。事件的導向方式相同（基於 OAuth 關係），此外，元件應用程式還支援如轉帳完成與禮品卡購買等元件專屬事件。

事件類型

只有當你的應用程式——以及對於公共/OAuth 應用程式而言，個別使用者的 OAuth 授權——持有所需的範圍（scopes）時，Fluz 才會投遞事件。沒有必需範圍的事件（例如 OAUTH_USER_LINKED）會投遞給任何已訂閱的公共/OAuth 應用程式。

交易事件

涵蓋完整的交易生命週期。適用於所有應用程式類型。

Event	Description	Required scopes
`TRANSACTION_CREATE`	建立了一筆新交易（例如，虛擬卡購買、存款、轉帳）。	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_UPDATE`	某筆交易的狀態或金額變更（例如，結算、調整）。	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_DECLINE`	某筆交易被拒（例如，餘額不足、卡片控制）。	`LIST_PAYMENT`, `LIST_PURCHASES`

存款事件

Event	Description	Required scopes
`DEPOSIT_COMPLETE`	從資金來源至消費帳戶的存款已完成。	`MAKE_DEPOSIT`

KYC 與 KYB 事件

適用於公共/OAuth 與元件應用程式。與 OAUTH_USER_LINKED 類似，這些事件在私人應用程式中沒有對應——它們只會對透過 OAuth 關係連結的帳戶觸發，且僅在你的應用程式（與使用者）的 OAuth 授權包含所需的範圍時投遞。

Event	Description	Required scopes
`KYC_STATUS_UPDATE`	已連結使用者的身分驗證（KYC）狀態變更。	`VERIFY_KYC`
`KYB_STATUS_UPDATE`	已連結商業客戶的驗證（KYB）狀態變更。	`REGISTER_BUSINESS`

資金來源事件

僅限測試環境FUNDING_SOURCE_STATUS_UPDATE 目前僅在測試（staging）環境中投遞。正式環境尚未發出此事件；在正式推出之前，正式環境的應用程式不會收到此事件，屆時本頁也會隨之更新。

適用於所有應用程式類型。會針對與你的應用程式相關聯的使用者投遞——包括已授與 LIST_PAYMENT 的 OAuth 使用者，或私人應用程式所屬帳戶下的任何使用者。

Event	Description	Required scopes
`FUNDING_SOURCE_STATUS_UPDATE`	使用者新增、重新命名或移除了一個資金來源。	`LIST_PAYMENT`

這三種情況都由同一種事件類型涵蓋；請依 changeType（ADDED、UPDATED、DELETED）分流，而非依事件名稱。使用者的 Fluz 現金餘額並非資金來源，永遠不會產生此事件。此事件是由資金來源本身的變更所發出，因此無論變更是在哪裡進行——Fluz 行動應用程式、網頁應用程式，或嵌入式元件——都會觸發。

OAuth 事件

適用於公共/OAuth 與元件應用程式。

Event	Description	Required scopes
`OAUTH_USER_LINKED`	使用者完成與你的應用程式的 OAuth 連結。首次連結與後續更新（例如授權範圍變更）都會觸發。	None

OAUTH_USER_LINKED 僅投遞給公共/OAuth 應用程式——私人應用程式訂閱者不會收到。由於它沒有範圍需求，你會對每個與你的應用程式連結或重新連結的使用者收到此事件，無論他們授與了哪些範圍。可用於建立或更新你本地的已連結使用者紀錄、擷取授與的範圍集合，並透過 externalReferenceId 對應你自己的使用者識別碼。

元件專屬事件

適用於使用者透過 Fluz 嵌入流程互動的元件與 OAuth 串接。

Event	Description	Required scopes
`WIDGET_KYC_INITIATION`	使用者已啟動身分驗證（KYC）。	`VERIFY_KYC`
`WIDGET_DEPOSIT_COMPLETE`	從客戶到你的應用程式的轉帳已完成。	`MAKE_PAYOUT_TRANSFER_SEND`
`WIDGET_WITHDRAW_COMPLETE`	從你的應用程式到客戶的轉帳已完成。	`MAKE_PAYOUT_TRANSFER_RECEIVE`
`WIDGET_PURCHASE_GIFT_CARD`	禮品卡購買已完成。	`PURCHASE_GIFTCARD`

📘 命名注意： WIDGET_DEPOSIT_COMPLETE 與 WIDGET_WITHDRAW_COMPLETE 描述的是客戶↔應用程式之間的「轉帳」；DEPOSIT/WITHDRAW 的用語是歷史沿用。請將「deposit」視為「客戶 → 應用程式」，「withdraw」視為「應用程式 → 客戶」。

設定 webhooks

1. 開啟開發者平台

前往開發者平台並選擇你的應用程式。

2. 開啟 Webhooks 區段

OAuth 應用程式： OAuth 分頁 → Webhook URLs。
元件應用程式： Widget 分頁 → Webhook URLs。
API / 私人應用程式： 應用程式設定中的 Webhook URLs 區段。

3. 新增 webhook URL

點擊 Add new URL 並輸入你的 HTTPS 端點（例如，https://api.yourapp.com/webhooks/fluz）。

4. 選擇事件

選擇你想接收的事件類型。

5. 儲存

點擊 Create Webhook。你的端點會立即開始接收事件。

管理 webhooks

多個端點 — 每個應用程式可以註冊多個 webhook URL。
變更訂閱事件 — 刪除該 webhook，並以新的事件選擇重新建立。
移除 webhook — 點擊其旁的 Remove。該 webhook 會立即封存並停止接收事件。

接收 webhooks

請求格式

每個 webhook 都以 HTTP POST 傳遞，包含以下標頭：

Header	Description
`Content-Type`	永遠為 `application/json`。
`X-HMAC-Signature`	以你的應用程式 API 金鑰簽署之原始 JSON 主體的 HMAC-SHA256 簽章。
`X-Event-ID`	此事件的唯一 UUID——用於去重。

主體為 JSON 物件，且每個載荷都包含 eventType 欄位來識別事件。

端點需求

僅限 HTTPS — 僅使用 HTTP 的端點會在註冊時被拒絕。
能公開存取 並可接受 POST 請求。
在 30 秒內以 2xx 回應。 非 2xx 回應或逾時會觸發重試。
驗證每個請求的 HMAC 簽章。

驗證簽章

每次投遞都包含 X-HMAC-Signature 標頭——以你應用程式的 API 金鑰，對原始 JSON 主體計算出的 HMAC-SHA256 雜湊值。請在信任任何載荷前，一律先行驗證。

⚠️ 請針對原始請求主體驗證。 對 Fluz 傳送的完全相同位元組計算 HMAC——不要以已解析的 JSON 重新序列化。重新字串化可能會重排鍵值順序或變更空白字元，導致有效簽章驗證失敗。以下範例會擷取原始主體，原因即在此。

Node.js (Express)

const express = require('express');
const crypto = require('crypto');
const app = express();
 
// Capture the raw body so the HMAC is computed over the exact bytes Fluz sent.
app.use('/webhooks/fluz', express.raw({ type: 'application/json' }));
 
function verifyFluzWebhook(rawBody, signature, apiKey) {
  const expected = crypto.createHmac('sha256', apiKey).update(rawBody).digest('hex');
  const received = Buffer.from(signature || '', 'hex');
  const computed = Buffer.from(expected, 'hex');
  return received.length === computed.length &&
         crypto.timingSafeEqual(received, computed);
}
 
app.post('/webhooks/fluz', (req, res) => {
  const signature = req.headers['x-hmac-signature'];
  const eventId = req.headers['x-event-id'];
 
  // req.body is a Buffer because of express.raw above
  if (!verifyFluzWebhook(req.body, signature, process.env.FLUZ_API_KEY)) {
    return res.status(401).send('Invalid signature');
  }
 
  // Acknowledge immediately, then process asynchronously
  res.status(200).send('OK');
 
  const event = JSON.parse(req.body.toString('utf8'));
  handleEvent(eventId, event).catch(err =>
    console.error('Webhook processing error:', err)
  );
});

Python (Flask)

import hmac, hashlib
from flask import Flask, request
 
app = Flask(__name__)
 
def verify_fluz_webhook(raw_body: bytes, signature: str, api_key: str) -> bool:
    expected = hmac.new(api_key.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")
 
@app.post("/webhooks/fluz")
def fluz_webhook():
    signature = request.headers.get("X-HMAC-Signature")
    event_id = request.headers.get("X-Event-ID")
 
    # request.get_data() returns the raw bytes — do NOT use request.json for verification
    if not verify_fluz_webhook(request.get_data(), signature, FLUZ_API_KEY):
        return "Invalid signature", 401
 
    enqueue(event_id, request.get_json())  # process asynchronously
    return "OK", 200

回應 webhooks

你的端點必須：

在 30 秒內以 2xx 狀態回應。
迅速回應——先確認，然後再非同步處理。
能透過 HTTPS 存取。你的端點不得：
回應重新導向（3xx）。
對有效的 webhooks 回應 4xx/5xx（這會觸發重試）。

重試政策

Behavior	Detail
Max attempts	5
Schedule	指數退避
Trigger	任一非 `2xx` 回應或逾時
Timeout	每次嘗試 30 秒
After all retries fail	放棄投遞；不再嘗試。

一旦你的端點恢復，新的事件會自動恢復投遞。若要重新傳送已耗盡重試的事件，請聯絡支援並提供相關的 X-Event-ID。

冪等性與順序

Webhooks 可能會被投遞多次，且不保證投遞順序。

使用 X-Event-ID 標頭進行去重。將已處理的 ID 儲存（正式環境使用 Redis 或資料庫），對已處理的事件跳過不處理。
依資料排序而非到達順序。 若順序很重要，請依載荷中的時間戳（createdAt、updatedAt、transactionDateTime）與事件 ID 排序。

const seen = new Set(); // use Redis or a database in production
 
async function handleEvent(eventId, event) {
  if (seen.has(eventId)) return;  // already processed — skip
  seen.add(eventId);
 
  switch (event.eventType) {
    case 'TRANSACTION_CREATE':    await onTransactionCreated(event); break;
    case 'TRANSACTION_UPDATE':    await onTransactionUpdated(event); break;
    case 'TRANSACTION_DECLINE':   await onTransactionDeclined(event); break;
    case 'DEPOSIT_COMPLETE':      await onDepositComplete(event); break;
    case 'OAUTH_USER_LINKED':     await onUserLinked(event); break;
    case 'KYC_STATUS_UPDATE':     await onKycStatusUpdate(event); break;
    case 'KYB_STATUS_UPDATE':     await onKybStatusUpdate(event); break;
    case 'FUNDING_SOURCE_STATUS_UPDATE':
                                  await onFundingSourceChange(event); break;
    case 'WIDGET_KYC_INITIATION': await onKycInitiated(event); break;
    // ...handle remaining widget events
  }
}

識別應用程式與使用者

使用者： userId 為 Fluz 使用者 ID。對於 OAuth/元件事件，externalReferenceId 對應到你在 OAuth 流程中的「你自己的」使用者識別碼。
應用程式： 交易載荷包含 connectedAppId 與 connectedAppName。若你將多個應用程式導向同一端點，請依 connectedAppId 分流。對於 OAUTH_USER_LINKED，應用程式以 appId 識別。

載荷參考

每個載荷都包含 eventType。欄位可用性會依事件而異；為了前向相容，處理器應忽略未識別的欄位。

📘 關於 status 值的說明。 對已建立/已更新的交易，status 欄位為 PENDING、SETTLED 或 FAILED 之一。被拒的交易會帶有 DECLINED（或 FAILED）的 status。本頁較早的草稿曾顯示 COMPLETED 為一種狀態——實際上不會發出該值；請使用 SETTLED 來判定交易已最終完成。

交易已建立（`TRANSACTION_CREATE`）

對任何新交易觸發——虛擬卡購買、存款、轉帳等。

{
  "eventType": "TRANSACTION_CREATE",
  "recordId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "transactionType": "PURCHASE",
  "amount": 42.99,
  "destination": "Coffee Shop",
  "source": "Virtual Card",
  "status": "PENDING",
  "channel": "VIRTUAL_CARD",
  "connectedAppId": "your-app-id",
  "connectedAppName": "Your App",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "merchantName": "Coffee Shop",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantCountry": "US",
  "cardLastFour": "1234",
  "virtualCardId": "vc-uuid-here",
  "digitalWalletProvider": "APPLE_PAY",
  "digitalWalletToken": "dw_2204zdpwi8352fa1jvhs2nl0ikgvdgnism",
  "isReversal": false,
  "cashbackRate": 0.05
}

Field	Type	Description
`eventType`	String	永遠為 `TRANSACTION_CREATE`。
`recordId`	String (UUID)	唯一的 webhook 事件記錄 ID。
`transactionId`	String (UUID)	識別此筆交易紀錄。待處理授權與其結算共用同一個值；額外的結算分段與退款則各自擁有自己的值。見串接單筆購買的事件。
`referenceId`	String	Fluz 的購買 ID。屬於同一筆虛擬卡購買的每個事件都帶有相同的值，因此可依此欄位分組，完整追蹤資金流向。若商家將 `Virtual Card Return` 當作新交易提交，此欄位可能缺席。
`accountId`	String (UUID)	Fluz 帳戶 ID。
`userId`	String (UUID)	Fluz 使用者 ID。對某些系統產生的交易可能不存在。
`transactionType`	String	交易類型，例如 `PURCHASE`、`GIFT_CARD_PURCHASE`、`DEPOSIT`、`WITHDRAWAL`、`TRANSFER`。視為開放字串。
`amount`	Number	以 USD 計之交易金額。
`originalCurrencyAmount`	Number	發卡機構回報的請求金額，以商家貨幣的最小單位表示（`6300` HKD 即 63.00 HKD）。在 `Virtual Card Return` 中，這是該次退款前仍在保留中的金額，而非實際退回的金額。請以 `amount` 對帳，詳見對帳金額。
`destination`	String	資金去向（例如，商家名稱）。
`source`	String	資金來源（例如，`Virtual Card`）。
`status`	String (enum)	`PENDING`、`SETTLED`、`FAILED` 之一。
`channel`	String	交易來源/通道（例如，`VIRTUAL_CARD`）。視為開放字串。
`connectedAppId`	String	事件導向到的應用程式。對私人應用程式活動可能不存在。
`connectedAppName`	String	已連結應用程式的顯示名稱。
`createdAt`	String (ISO 8601)	交易建立時間。
`merchantName` / `merchantCity` / `merchantState` / `merchantCountry`	String	商家地點資訊。
`cardLastFour`	String	使用之卡片末四碼。
`virtualCardId`	String (UUID)	若適用，虛擬卡 ID。
`digitalWalletProvider`	String (enum)	透過行動錢包進行之卡交易時存在。可能為 `APPLE_PAY`、`GOOGLE_PAY`（未來可能新增）。非錢包交易則缺席或為 `null`。此欄位用於判斷交易是否來自行動錢包。
`digitalWalletToken`	String	代碼化卡片的網路代碼識別（如 `dw_...`）。它本身不是錢包指標：對非錢包的網路代碼（例如商家儲存的卡片資訊）也會設定，且在某些錢包交易中可能缺席。請使用 `digitalWalletProvider`，而非此代碼的存在與否，來判斷付款是否來自行動錢包。
`isReversal`	Boolean	當交易為授權撤銷時為 `true`：即已釋放的保留（無論由發卡機構或 Fluz 釋放），或卡片驗證作廢。請款與商家退款時為 `false`。當我們無法分類該筆交易時，此欄位缺席。見下方撤銷與退款。
`cashbackRate`	Number	十進位現金回饋比率（例如，`0.05` = 5%）。

交易已更新（`TRANSACTION_UPDATE`）

當交易的狀態或細節變更時觸發——例如，待處理授權轉為結算。

{
  "eventType": "TRANSACTION_UPDATE",
  "recordId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "transactionType": "PURCHASE",
  "referenceId": "11323677",
  "amount": 42.99,
  "status": "SETTLED",
  "connectedAppId": "your-app-id",
  "connectedAppName": "Your App",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-16T08:00:00.000Z",
  "isReversal": false
}

欄位與 TRANSACTION_CREATE 相同之處沿用，另包含 updatedAt（ISO 8601）標示變更發生時間。userId、connectedAppId、connectedAppName 與 TRANSACTION_CREATE 中一致，以便你能在整個生命週期中一致識別使用者與應用程式。status 轉為 SETTLED 即代表先前待處理的交易已經定案。 isReversal 在此處與 TRANSACTION_CREATE 中意義相同。見撤銷與退款。

交易被拒（`TRANSACTION_DECLINE`）

當交易被拒時觸發。包含結構化的拒絕原因，供你的應用程式採取行動。

{
  "eventType": "TRANSACTION_DECLINE",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "transactionType": "PURCHASE",
  "amount": 500.00,
  "fluzAmount": 500.00,
  "externalFundingAmount": 0,
  "currency": "USD",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DECLINED",
  "merchantName": "Electronics Store",
  "cardLastFour": "1234",
  "virtualCardId": "vc-uuid-here",
  "isCashBalanceUsed": true,
  "isPrepaymentBalanceUsed": false,
  "isRewardsBalanceUsed": false,
  "isReserveBalanceUsed": false,
  "isReversal": false,
  "transactionDateTime": "2025-01-15T10:30:00.000Z",
  "declineTitle": "Transaction Declined",
  "declineReason": "Insufficient funds",
  "declineDescription": "Your account balance was not sufficient for this transaction.",
  "declineCategory": "Balance"
}

Field	Type	Description
`amount`	Number	嘗試的總金額。
`fluzAmount`	Number	從 Fluz 餘額動用的部分。
`externalFundingAmount`	Number	從外部資金動用的部分。
`currency`	String	ISO 貨幣代碼（例如 `USD`）。
`status`	String (enum)	`DECLINED`、`FAILED` 之一。
`userId`	String (UUID)	Fluz 使用者 ID。對某些系統產生的交易可能不存在。
`isCashBalanceUsed` / `isPrepaymentBalanceUsed` / `isRewardsBalanceUsed` / `isReserveBalanceUsed`	Boolean	該次嘗試動用了哪些餘額類型。
`isReversal`	Boolean	授權撤銷時為 `true`：即已釋放的保留（無論由發卡機構或 Fluz 釋放），或卡片驗證作廢。請款與商家退款時為 `false`。當我們無法分類該筆交易時，此欄位缺席。見撤銷與退款。
`transactionDateTime`	String (ISO 8601)	拒絕發生時間。
`declineTitle`	String	簡短、面向使用者的標題。
`declineReason`	String	簡短原因（例如，`Insufficient funds`）。
`declineDescription`	String	較長、面向使用者的說明。
`declineCtaText`	String	可用時的建議行動（例如，`Add money`）。
`declineCategory`	String	高層次拒絕分類。常見值包含 `Balance`、`Limit`、`Validation`、`Virtual Card` 與 `Acquiring`。視為開放字串，完整集合與各代碼細節請見拒絕代碼。

依交易狀況可能會出現其他選用欄位（例如 merchantId、merchantCity、merchantState、merchantCountry、cardDisplayName、virtualCardProgram、channel、bankAccountNickname、bankAccountLastFour）。用不到的可以忽略。

串接單筆購買的事件

一筆虛擬卡購買通常會產生不只一個交易事件。有兩個欄位可以將它們串在一起：

referenceId 是 Fluz 的購買 ID。該筆授權、其結算、任何額外的結算分段，以及該筆購買的任何退款，都會帶有相同的值。請依此欄位分組。
transactionId 用於識別單一帳務紀錄。待處理授權與其結算會共用同一個值，因為結算是以同一筆紀錄的 TRANSACTION_UPDATE 傳送。任何 Fluz 另外記錄的項目，都會有一個新的 transactionId。

一筆典型購買的事件順序：

Step	Event	`transactionId`	`status`	`amount`
授權	`TRANSACTION_CREATE`，`Virtual Card Purchase`	A	`PENDING`	負數
該筆授權的結算	`TRANSACTION_UPDATE`，`Virtual Card Purchase`	A	`SETTLED`	負數
額外的結算分段（商家請款金額超過授權金額、幣別差異，或第二次請款）	`TRANSACTION_CREATE`，`Virtual Card Purchase`	B	`SETTLED`	負數
退款（保留釋放或商家退款）	`TRANSACTION_CREATE`，`Virtual Card Return`	C	`SETTLED`	正數

範例：一筆 8.54 的授權以 transactionId A 的 TRANSACTION_CREATE 到達，status: PENDING。商家請款 8.56。你會收到 A 上的 TRANSACTION_UPDATE，帶有 status: SETTLED 與 amount: -8.54，接著是新 transactionId B 的 TRANSACTION_CREATE，帶有 status: SETTLED 與 amount: -0.02。這三筆事件都帶有 referenceId: "11323677"。這筆購買的淨扣款金額，是同一個 referenceId 下、每個 transactionId 最新金額的加總：-8.56。由此衍生出以下規則：

以 transactionId 作為紀錄的鍵值，但依 referenceId 對帳。一筆帶有 status: SETTLED 且沒有先前待處理事件的 TRANSACTION_CREATE 是正常的：它是你已在同一個 referenceId 下持有的購買的額外分段或退款。
當授權從未被請款、保留被釋放時，你會收到兩個事件：一筆將待處理購買更新為 SETTLED 的 TRANSACTION_UPDATE，以及一筆帶有相同 referenceId 與正數 amount 的 Virtual Card Return。兩者相互抵銷為零。請將這組事件視為待處理金額的釋放，而非一筆已完成的購買。
若商家將退款以新交易（而非針對原始授權）的形式提交，該筆 Virtual Card Return 可能不帶有 referenceId。請以 virtualCardId、amount 與商家進行比對。

撤銷與退款

撤銷會在任何資金被請款前釋放授權保留。持卡人的可用餘額會回升，但沒有資金曾經離開，也沒有資金回來。退款則發生在請款之後：資金已經移動，商家再將其退回。 isReversal 用來區分兩者：

Value	Meaning
`true`	授權撤銷。保留已釋放，且該筆金額從未被請款。已釋放的保留（無論由發卡機構或 Fluz 釋放），以及卡片驗證作廢，都會標記為此值。
`false`	我們分類為非撤銷的任何情況，例如授權、請款、真正的退款，或拒絕交易。
absent	我們無法分類該筆交易。請將其視為未知，切勿視為 `false`。

只要此欄位存在，請優先使用它而非 transactionType。各發卡機構對這些事件的標記並不一致，因此某發卡機構用於商家退款的類型值，可能是另一家發卡機構用於收款前撤銷的類型值，僅憑類型無法判斷資金是否真的移動。 Virtual Card Return 事件同樣帶有此欄位：已釋放的保留為 true，商家退款為 false。仍有少數退回事件不帶有此欄位；對於這些事件，請改用 referenceId 與原始授權來區分。哪個事件會帶有撤銷標記，取決於被撤銷的是什麼：

卡片驗證作廢會記錄為其自身的交易，因此會以帶有負數 amount 的 TRANSACTION_CREATE 到達，之後再更新。這是商家用來確認卡片有效性的小額測試，我們會立即將其作廢。它們會帶有 isReversal: true。
收款前保留的釋放，會以獨立交易的形式到達，transactionType 為 Virtual Card Return，amount 為正數，並帶有該筆購買的 referenceId。原始購買會同時更新為 SETTLED，因此兩者相互抵銷為零。無論保留是由 Fluz 或發卡機構釋放，該筆退回都會帶有 isReversal: true。
商家退款同樣會以 transactionType 為 Virtual Card Return 的形式到達，並帶有 isReversal: false。若存在 referenceId，請以此比對原始購買；否則請以 virtualCardId、amount 與商家進行比對。

撤銷不是失敗，但仍需要處理：請釋放你為對應授權所記錄的保留，否則它會在你的系統中一直維持開啟狀態。請勿將其登記為新的支出，因為並沒有資金移動。

對帳金額

請以 amount 對帳。它是該事件實際移動的 USD 金額，因此不論一筆購買有多少結算分段或退款，同一個 referenceId 下、每個 transactionId 的最新 amount 加總，就是該筆購買的淨額。 originalCurrencyAmount 不能用同樣的方式加總。它是發卡機構針對該事件回報的請求金額。在退款事件中，這是該次退款前仍在保留中的金額，因此會重複先前事件已經帶有的數值，加總會造成重複計算。範例：一筆 39.69 的授權，其保留分兩個步驟釋放，例如訂單有部分品項缺貨，其餘品項稍後才釋放。

Event	`amount`	`originalCurrencyAmount`
授權，`Virtual Card Purchase`	-39.69	3969
第一次釋放，`Virtual Card Return`	17.95	3969
第二次釋放，`Virtual Card Return`	21.74	2174

amount 的加總為 0.00，因為沒有任何金額被請款。originalCurrencyAmount 的數值描述的是每個步驟當下的保留金額，而不是實際移動的資金。

存款完成（`DEPOSIT_COMPLETE`）

當從資金來源至消費帳戶的存款完成時觸發。

{
  "eventType": "DEPOSIT_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 50.00
}

OAuth 使用者已連結（`OAUTH_USER_LINKED`）

當使用者完成與你的應用程式的 OAuth 連結時觸發——包含首次連結與後續更新（例如使用者以不同範圍重新授權）。僅適用於公共/OAuth 與元件應用程式。接收此事件不需要任何範圍。

{
  "eventType": "OAUTH_USER_LINKED",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "appId": "55555555-5555-4555-8555-555555555555",
  "externalReferenceId": "your-reference-123",
  "scopes": [
    "LIST_PAYMENT",
    "MAKE_DEPOSIT"
  ]
}

Field	Type	Description
`eventType`	String	永遠為 `OAUTH_USER_LINKED`。
`accountId`	String (UUID)	連結到你的應用程式的 Fluz 帳戶 ID。
`userId`	String (UUID)	連結到你的應用程式的 Fluz 使用者 ID。
`appId`	String (UUID)	你的應用程式 ID。
`externalReferenceId`	String	選用。你在 OAuth 流程中傳遞的使用者識別碼。對元件應用程式類型與任何有提供此值的流程皆存在；其餘情況下可能缺席。
`scopes`	String[]	該使用者授與的範圍鍵集合（例如 `LIST_PAYMENT`、`MAKE_DEPOSIT`）。

由於 OAUTH_USER_LINKED 會在重新連結/更新時再次觸發，請將其視為 upsert：首次收到時建立已連結使用者，之後每次投遞時刷新已儲存的範圍集合。

KYC 啟動（`WIDGET_KYC_INITIATION`）

當使用者開始身分驗證時觸發。僅適用於公共/元件應用程式。

{
  "eventType": "WIDGET_KYC_INITIATION",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123"
}

轉帳完成 — 客戶至應用程式（`WIDGET_DEPOSIT_COMPLETE`）

當使用者向你的應用程式轉入資金時觸發。

{
  "eventType": "WIDGET_DEPOSIT_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 25.50
}

轉帳完成 — 應用程式至客戶（`WIDGET_WITHDRAW_COMPLETE`）

當你的應用程式向使用者轉出資金時觸發。

{
  "eventType": "WIDGET_WITHDRAW_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 15.00
}

禮品卡購買（`WIDGET_PURCHASE_GIFT_CARD`）

當透過元件完成禮品卡購買時觸發。

{
  "eventType": "WIDGET_PURCHASE_GIFT_CARD",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 25.00
}

常見元件載荷欄位： userId（Fluz 使用者 ID）、accountId（Fluz 帳戶 ID）、externalReferenceId（你在 OAuth 流程中的使用者識別碼），以及在適用時的 amount。

KYC 狀態更新（`KYC_STATUS_UPDATE`）

當已連結使用者的 KYC 狀態變更時觸發。僅適用於公共/OAuth 與元件應用程式；需要 VERIFY_KYC 範圍。每個載荷共享一個通用外層；verificationData 物件的結構由 verificationType 區分，見下方各類型所示。

Field	Type	Description
`eventType`	String	永遠為 `KYC_STATUS_UPDATE`。
`userId`	String (UUID)	KYC 狀態變更的 Fluz 使用者 ID。
`accountId`	String (UUID)	Fluz 帳戶 ID。
`previousStatus` / `newStatus`	String (enum)	`NOT_REQUIRED`、`PENDING_DOCUMENTS`、`MISSING_1099_INFO`、`PASS`、`PASS_INTERNATIONAL`、`SOFT_DECLINE`、`HARD_DECLINE`、`FAIL` 之一。
`externalReferenceId`	String	選用。你在 OAuth 流程中的使用者識別碼。
`verificationType`	String (enum)	`SSN`、`DOCUMENTS`、`SYSTEM` 之一。用於區分下方各類型的 `verificationData` 結構。

SSN
Documents
System

當狀態變更源自於基於 SSN 的驗證時發出。

{
  "eventType": "KYC_STATUS_UPDATE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "previousStatus": "PENDING_DOCUMENTS",
  "newStatus": "PASS",
  "externalReferenceId": "your-reference-123",
  "verificationType": "SSN",
  "verificationData": {
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "userDateOfBirth": "1990-01-15T00:00:00.000Z",
    "lastFourSSNDigits": "6789",
    "legalAddress": {
      "streetAddressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}

Field	Type	Description
`verificationData.userFirstName`	String	使用者法定名。
`verificationData.userLastName`	String	使用者法定姓。
`verificationData.userDateOfBirth`	String (ISO 8601)	選用。使用者生日。
`verificationData.lastFourSSNDigits`	String	選用。用於驗證的 SSN 末四碼。
`verificationData.legalAddress`	Object	選用。見下方結構。

當狀態變更源自於基於文件的身分驗證時發出。

{
  "eventType": "KYC_STATUS_UPDATE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "previousStatus": "PENDING_DOCUMENTS",
  "newStatus": "PASS",
  "externalReferenceId": "your-reference-123",
  "verificationType": "DOCUMENTS",
  "verificationData": {
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "userDateOfBirth": "1990-01-15T00:00:00.000Z",
    "documentType": "PASSPORT",
    "documentId": "b3f8b6d0-1234-4a5b-9c3d-abcdefabcdef",
    "documentIssuer": "US",
    "documentIssueDate": "2020-05-01T00:00:00.000Z",
    "documentExpireDate": "2030-05-01T00:00:00.000Z",
    "legalAddress": {
      "streetAddressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}

Field	Type	Description
`verificationData.userFirstName`	String	使用者法定名。
`verificationData.userLastName`	String	使用者法定姓。
`verificationData.userDateOfBirth`	String (ISO 8601)	選用。使用者生日。
`verificationData.documentType`	String	選用。提交的文件類型（例如 `PASSPORT`）。
`verificationData.documentId`	String (UUID)	選用。 Fluz 對該文件的 ID。
`verificationData.documentIssuer`	String	選用。發證國/機關。
`verificationData.documentIssueDate`	String (ISO 8601)	選用。文件核發日期。
`verificationData.documentExpireDate`	String (ISO 8601)	選用。文件到期日。
`verificationData.legalAddress`	Object	選用。見下方結構。

用於非綁定於特定 SSN 或文件提交的系統驅動狀態變更（例如自動重新審查）。此處 verificationData 本身為選用——可能完全缺席。

{
  "eventType": "KYC_STATUS_UPDATE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "previousStatus": "SOFT_DECLINE",
  "newStatus": "HARD_DECLINE",
  "externalReferenceId": "your-reference-123",
  "verificationType": "SYSTEM",
  "verificationData": {
    "reason": "Failed secondary AML screening"
  }
}

Field	Type	Description
`verificationData`	Object	選用。可能完全缺席。
`verificationData.reason`	String	選用。系統驅動變更的自由文字原因。

legalAddress 若存在（僅 SSN 與 DOCUMENTS 類型），其結構為 { streetAddressLine1, streetAddressLine2 (optional), city, state, postalCode, country }。

KYB 狀態更新（`KYB_STATUS_UPDATE`）

當已連結企業的 KYB 狀態變更時觸發。僅適用於公共/OAuth 應用程式；需要 REGISTER_BUSINESS 範圍。

{
  "eventType": "KYB_STATUS_UPDATE",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "previousStatus": "IN_PROGRESS",
  "newStatus": "PASS",
  "externalReferenceId": "your-reference-123"
}

Field	Type	Description
`eventType`	String	永遠為 `KYB_STATUS_UPDATE`。
`accountId`	String (UUID)	該企業的 Fluz 帳戶 ID。
`userId`	String (UUID)	選用。與該企業關聯的 Fluz 使用者 ID（若可用）。
`previousStatus` / `newStatus`	String (enum)	`IN_PROGRESS`、`SUBMITTED_FOR_APPROVAL`、`PASS`、`REVIEW`、`FAILED`、`SOFT_DECLINE`、`HARD_DECLINE`、`PENDING_FORMATION`、`PENDING_DOCUMENTS`、`PASS_INTERNATIONAL`、`WAITING_FOR_SCREENING_RESULT` 之一。
`externalReferenceId`	String	選用。你在 OAuth 流程中的使用者識別碼。

資金來源狀態更新（`FUNDING_SOURCE_STATUS_UPDATE`）

當使用者新增、重新命名或移除資金來源——銀行帳戶、銀行卡，或 PayPal 帳戶時觸發。需要 LIST_PAYMENT 範圍。目前僅限測試環境——正式環境尚未投遞。

{
  "eventType": "FUNDING_SOURCE_STATUS_UPDATE",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "changeType": "ADDED",
  "fundingSourceId": "9f8b7a6c-5d4e-3f21-0a9b-8c7d6e5f4a3b",
  "fundingSourceType": "BANK_CARD",
  "brand": "VISA",
  "lastFour": "4242",
  "nickname": "Travel card",
  "status": "ACTIVE",
  "createdAt": "2026-09-14T17:04:10.000Z",
  "updatedAt": "2026-09-14T17:04:11.000Z",
  "changedAt": "2026-09-14T17:04:12.481Z"
}

Field	Type	Description
`eventType`	String	永遠為 `FUNDING_SOURCE_STATUS_UPDATE`。
`accountId`	String (UUID)	該資金來源所屬的 Fluz 帳戶。
`userId`	String (UUID)	可為 null。該資金來源所屬的使用者。對卡片與 PayPal 帳戶一律存在；對某些以帳戶層級持有的銀行帳戶則為 `null`。請依 `accountId` 分流，而非 `userId`。
`changeType`	String (enum)	`ADDED`、`UPDATED`、`DELETED` 之一。
`fundingSourceId`	String (UUID)	該資金來源的 Fluz ID——銀行帳戶 ID、銀行卡 ID，或 PayPal vault ID。在這三種變更類型中保持穩定不變。
`fundingSourceType`	String (enum)	`BANK_ACCOUNT`、`BANK_CARD`、`PAYPAL` 之一。
`brand`	String	可為 null。 `BANK_CARD` 為卡片組織，`BANK_ACCOUNT` 為機構名稱，PayPal 帳戶則為 `PAYPAL`。
`lastFour`	String	可為 null。卡片或銀行帳戶的末四碼。`PAYPAL` 一律為 `null`。
`nickname`	String	可為 null。使用者看到的此來源名稱。`PAYPAL` 一律為 `null`。
`status`	String	可為 null。變更當下該來源自身的狀態，例如 `ACTIVE`。數值依類型而異：卡片使用 `ACTIVE` / `INACTIVE` / `PENDING_REMOVAL`，銀行帳戶使用 `ENABLED` / `DISABLED`，PayPal 使用 `ACTIVE` / `REMOVED`。
`createdAt` / `updatedAt`	String (ISO 8601)	可為 null。該資金來源本身的建立時間與最後修改時間。
`changedAt`	String (ISO 8601)	此次變更發生的時間。可用於為同一個 `fundingSourceId` 的事件排序。

只有當此載荷中的欄位確實發生變化時，才會觸發 UPDATED——重新命名來源或狀態變更會觸發，但例行的內部記錄維護不會。移除資金來源並不會刪除該筆紀錄，而是將其標記為未啟用，因此 DELETED 事件會帶有終態的 status（INACTIVE、DISABLED 或 REMOVED），而不是缺少紀錄。請依 changeType 判斷來源是否已經移除。此載荷中永遠不會包含完整的卡號或銀行帳號。

最佳實務

快速回應，稍後處理。 立即回傳 200，並以非同步方式處理事件，以避免逾時與不必要的重試。
驗證每個請求。 在處理前，使用你的 API 金鑰，針對原始主體驗證 X-HMAC-Signature。
以事件 ID 去重。 追蹤 X-Event-ID，以處理重試或重複的投遞。
將類 enum 欄位視為開放字串。 新的 transactionType、channel 與 declineCategory 值可能隨時間出現；只針對你在意的值進行分支處理，並容忍未知值。
對 OAUTH_USER_LINKED 採用 upsert。 每位使用者可能觸發不只一次；每次都刷新已儲存的範圍集合，而非假設只會在首次連結時觸發。
以 fundingSourceId 為鍵值識別資金來源。 同一種事件類型涵蓋所有三種變更；請依 changeType 分流，並依 changedAt 為同一來源的事件排序。
接受未知欄位。 載荷可能隨時間新增欄位；請忽略無法辨識的欄位，而非直接失敗。
監控你的端點。 對連續的非 2xx 回應發出警示——在 5 次嘗試失敗後，該事件的投遞就會被放棄。

疑難排解

Symptom	Likely cause	Fix
未收到任何 webhooks	端點無法連線或回傳錯誤	確認 URL 正確、可透過 HTTPS 公開存取，且回傳 `2xx`。
缺少某些事件類型	應用程式缺少所需範圍	確保你的應用程式持有該事件所列的範圍。
公共應用程式未收到某使用者的事件	使用者未授與所需的範圍	確認該使用者的 OAuth 授權包含所需範圍。
未收到 `OAUTH_USER_LINKED`	訂閱於私人應用程式，或根本未訂閱	此事件僅適用於公共/OAuth。請在 OAuth 或元件應用程式上訂閱（或使用全選）。
簽章驗證失敗	使用錯誤的 API 金鑰，或對重新序列化的主體驗證	使用你的應用程式 API 金鑰，並針對原始請求主體驗證。
發生重複投遞	逾時後的重試	以 `X-Event-ID` 實作冪等性。
事件停止送達	連續 5 次失敗已耗盡重試	修復你的端點；新的事件會自動恢復。聯絡支援以重播已耗盡重試的事件。

需要協助？

技術問題： 檢查你的端點日誌並連絡支援，提供 X-Event-ID。
範圍問題： 參閱 Application Scopes 與 Decline Codes。

​運作方式

​依應用程式類型的 Webhooks

​私人應用程式 — 你的自有帳戶

​公共應用程式（OAuth） — 代表使用者行動

​元件應用程式

​事件類型

​交易事件

​存款事件

​KYC 與 KYB 事件

​資金來源事件

​OAuth 事件

​元件專屬事件

​設定 webhooks

​1. 開啟開發者平台

​2. 開啟 Webhooks 區段

​3. 新增 webhook URL

​4. 選擇事件

​5. 儲存

​管理 webhooks

​接收 webhooks

​請求格式

​端點需求

​驗證簽章

​Node.js (Express)

​Python (Flask)

​回應 webhooks

​重試政策

​冪等性與順序

​識別應用程式與使用者

​載荷參考

​交易已建立（TRANSACTION_CREATE）

​交易已更新（TRANSACTION_UPDATE）

​交易被拒（TRANSACTION_DECLINE）

​串接單筆購買的事件

​撤銷與退款

​對帳金額

​存款完成（DEPOSIT_COMPLETE）

​OAuth 使用者已連結（OAUTH_USER_LINKED）

​KYC 啟動（WIDGET_KYC_INITIATION）

​轉帳完成 — 客戶至應用程式（WIDGET_DEPOSIT_COMPLETE）

​轉帳完成 — 應用程式至客戶（WIDGET_WITHDRAW_COMPLETE）

​禮品卡購買（WIDGET_PURCHASE_GIFT_CARD）

​KYC 狀態更新（KYC_STATUS_UPDATE）

​KYB 狀態更新（KYB_STATUS_UPDATE）

​資金來源狀態更新（FUNDING_SOURCE_STATUS_UPDATE）

​最佳實務

​疑難排解

​需要協助？

運作方式

依應用程式類型的 Webhooks

私人應用程式 — 你的自有帳戶

公共應用程式（OAuth） — 代表使用者行動

元件應用程式

事件類型

交易事件

存款事件

KYC 與 KYB 事件

資金來源事件

OAuth 事件

元件專屬事件

設定 webhooks

1. 開啟開發者平台

2. 開啟 Webhooks 區段

3. 新增 webhook URL

4. 選擇事件

5. 儲存

管理 webhooks

接收 webhooks

請求格式

端點需求

驗證簽章

Node.js (Express)

Python (Flask)

回應 webhooks

重試政策

冪等性與順序

識別應用程式與使用者

載荷參考

交易已建立（`TRANSACTION_CREATE`）

交易已更新（`TRANSACTION_UPDATE`）

交易被拒（`TRANSACTION_DECLINE`）

串接單筆購買的事件

撤銷與退款

對帳金額

存款完成（`DEPOSIT_COMPLETE`）

OAuth 使用者已連結（`OAUTH_USER_LINKED`）

KYC 啟動（`WIDGET_KYC_INITIATION`）

轉帳完成 — 客戶至應用程式（`WIDGET_DEPOSIT_COMPLETE`）

轉帳完成 — 應用程式至客戶（`WIDGET_WITHDRAW_COMPLETE`）

禮品卡購買（`WIDGET_PURCHASE_GIFT_CARD`）

KYC 狀態更新（`KYC_STATUS_UPDATE`）

KYB 狀態更新（`KYB_STATUS_UPDATE`）

資金來源狀態更新（`FUNDING_SOURCE_STATUS_UPDATE`）

最佳實務

疑難排解

需要協助？