Webhooks - Fluz

Webhooks let your application receive real-time notifications when events happen on the Fluz platform. Instead of polling for changes, you register an HTTPS endpoint and Fluz pushes event data to you the moment something occurs — a virtual card transaction, a declined purchase, a completed deposit, a user linking their account via OAuth, and more.

This page covers all webhook events, which span multiple platform areas (transaction activity, deposits, widget flows, and OAuth account linking) rather than belonging to any single feature.

Webhooks work across all application types on the Fluz platform: private apps operating on your own account, public OAuth apps acting on behalf of other users via API, and embedded widget apps.

How it works

You register a webhook URL on your application in the Developer Portal.
You select which event types to listen for (or subscribe to all of them).
When a matching event occurs, Fluz sends an HTTP POST to your URL with a signed JSON payload.
Your server verifies the signature, acknowledges with a 2xx, and processes the event.

If your endpoint is unavailable or returns an error, Fluz retries up to 5 times with exponential backoff before giving up on that delivery.

Webhooks by app type

How events are routed to your app depends on your application model.

Private apps — your own account

Webhooks fire for activity on your own account. Any transaction, decline, or deposit on accounts you own triggers webhooks registered on your app. Common use cases: notifications when a virtual card transaction is authorized or settled; real-time alerting on declines; monitoring deposits and balance changes on your spend accounts.

Public apps (OAuth) — acting on behalf of users

Webhooks fire for activity on accounts that have authorized your app. When a user grants your app access via OAuth, their events are routed to your registered webhooks — provided the user’s OAuth grant includes the required scopes. This works whether the user interacts through your direct API integration or an embedded widget; the key requirement is an OAuth relationship between the user and your app. Common use cases: knowing when a user has linked (or re-linked) their account to your app; monitoring virtual card spend across connected accounts; real-time decline notifications; tracking deposit completions; receiving KYC and KYB status updates. Widget apps are a specialized public app. Events route the same way (based on the OAuth relationship), and widget apps additionally support widget-specific events like transfer completions and gift card purchases.

Event types

Fluz only delivers an event if your application — and, for public/OAuth apps, the individual user’s OAuth grant — holds the required scopes. Events with no required scopes (such as OAUTH_USER_LINKED) are delivered to any subscribed public/OAuth app.

Transaction events

Staging only: externalReferenceId on transaction eventsTRANSACTION_CREATE, TRANSACTION_UPDATE and TRANSACTION_DECLINE carry externalReferenceId in the staging environment only. Production deliveries do not include it yet; this page will be updated when it is rolled out.

Cover the full transaction lifecycle. Apply to all app types.

Event	Description	Required scopes
`TRANSACTION_CREATE`	A new transaction was created (e.g., virtual card purchase, deposit, transfer).	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_UPDATE`	A transaction’s status or amount changed (e.g., settled, adjusted).	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_DECLINE`	A transaction was declined (e.g., insufficient funds, card controls).	`LIST_PAYMENT`, `LIST_PURCHASES`

Deposit events

Event	Description	Required scopes
`DEPOSIT_COMPLETE`	A deposit from a funding source to a spend account completed.	`MAKE_DEPOSIT`

KYC & KYB events

Apply to public/OAuth and widget apps. Like OAUTH_USER_LINKED, these events have no private-app equivalent — they only fire for accounts connected via an OAuth relationship, and only when your app’s (and the user’s) OAuth grant includes the required scope.

Event	Description	Required scopes
`KYC_STATUS_UPDATE`	A connected user’s identity verification (KYC) status changed.	`VERIFY_KYC`
`KYB_STATUS_UPDATE`	A connected business’s verification (KYB) status changed.	`REGISTER_BUSINESS`

Funding source events

Staging onlyFUNDING_SOURCE_STATUS_UPDATE is currently delivered only in the staging environment. It is not yet emitted in production; production apps will not receive it until it is rolled out, and this page will be updated when it is.

Apply to all app types. Delivered for users tied to your application — an OAuth user who granted LIST_PAYMENT, or any user on an account that owns a private app.

Event	Description	Required scopes
`FUNDING_SOURCE_STATUS_UPDATE`	A user added, renamed or removed a funding source.	`LIST_PAYMENT`

One event type covers all three cases; branch on changeType (ADDED, UPDATED, DELETED) rather than on the event name. The user’s Fluz cash balance is not a funding source and never produces this event. The event is emitted from the change to the funding source itself, so it fires wherever the change was made — the Fluz mobile app, the web app, or an embedded widget.

OAuth events

Apply to public/OAuth and widget apps.

Event	Description	Required scopes
`OAUTH_USER_LINKED`	A user completed OAuth linking to your application. Fires on both the initial link and subsequent updates (e.g., when the granted scopes change).	None

OAUTH_USER_LINKED is delivered only to public/OAuth app types — private-app subscribers do not receive it. Because it has no scope requirement, you receive it for every user who links or re-links to your app, regardless of which scopes they grant. Use it to provision or update your local record of the connected user, capture the granted scope set, and map your own user identifier via externalReferenceId. Apply to widget and OAuth integrations where users interact through Fluz-embedded flows.

Event	Description	Required scopes
`WIDGET_KYC_INITIATION`	A user initiated identity verification (KYC).	`VERIFY_KYC`
`WIDGET_DEPOSIT_COMPLETE`	A transfer from a customer to your app completed.	`MAKE_PAYOUT_TRANSFER_SEND`
`WIDGET_WITHDRAW_COMPLETE`	A transfer from your app to a customer completed.	`MAKE_PAYOUT_TRANSFER_RECEIVE`
`WIDGET_PURCHASE_GIFT_CARD`	A gift card purchase completed.	`PURCHASE_GIFTCARD`

📘 Naming note: WIDGET_DEPOSIT_COMPLETE and WIDGET_WITHDRAW_COMPLETE describe customer↔app transfers; the DEPOSIT/WITHDRAW wording is historical. Treat “deposit” as “customer → app” and “withdraw” as “app → customer.”

Setting up webhooks

1. Open the Developer Portal

Go to the Developer Portal and select your application.

2. Open the Webhooks section

OAuth apps: OAuth tab → Webhook URLs.
Widget apps: Widget tab → Webhook URLs.
API / private apps: the Webhook URLs section in your app settings.

3. Add a webhook URL

Click Add new URL and enter your HTTPS endpoint (e.g., https://api.yourapp.com/webhooks/fluz).

4. Select events

Choose the event types you want to receive.

5. Save

Click Create Webhook. Your endpoint begins receiving events immediately.

Managing webhooks

Multiple endpoints — you can register more than one webhook URL per application.
Change subscribed events — delete the webhook and recreate it with the new event selection.
Remove a webhook — click Remove next to it. The webhook is archived immediately and stops receiving events.

Receiving webhooks

Request format

Every webhook is delivered as an HTTP POST with these headers:

Header	Description
`Content-Type`	Always `application/json`.
`X-HMAC-Signature`	HMAC-SHA256 signature of the raw JSON body, signed with your app’s API key.
`X-Event-ID`	Unique UUID for this event — use it for deduplication.

The body is a JSON object, and every payload includes an eventType field identifying the event.

Endpoint requirements

HTTPS only — plain HTTP endpoints are rejected at registration time.
Publicly accessible and able to accept POST requests.
Respond with a 2xx within 30 seconds. Non-2xx responses or timeouts trigger retries.
Verify the HMAC signature on every request.

Verifying signatures

Every delivery includes an X-HMAC-Signature header — an HMAC-SHA256 hash of the raw JSON body, signed with your application’s API key. Always verify it before trusting a payload.

⚠️ Verify against the raw request body. Compute the HMAC over the exact bytes Fluz sent — do not re-serialize the parsed JSON. Re-stringifying can reorder keys or change whitespace and cause valid signatures to fail. The examples below capture the raw body for this reason.

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

Responding to webhooks

Your endpoint must:

Respond with a 2xx status within 30 seconds.
Return quickly — acknowledge first, then process asynchronously.
Be reachable over HTTPS. Your endpoint must not:
Respond with redirects (3xx).
Respond with 4xx/5xx for valid webhooks (this triggers retries).

Retry policy

Behavior	Detail
Max attempts	5
Schedule	Exponential backoff
Trigger	Any non-`2xx` response or timeout
Timeout	30 seconds per attempt
After all retries fail	Delivery is abandoned; no further attempts.

New events resume delivery automatically once your endpoint recovers. To re-send events whose retries were already exhausted, contact support with the relevant X-Event-ID.

Idempotency & ordering

Webhooks may be delivered more than once, and delivery order is not guaranteed.

Deduplicate using the X-Event-ID header. Persist processed IDs (Redis or a database in production) and skip events you’ve already handled.
Order by data, not arrival. If sequence matters, order by payload timestamps (createdAt, updatedAt, transactionDateTime) and event IDs.

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
  }
}

Identifying the app and user

User: userId is the Fluz user ID. For OAuth/widget events, externalReferenceId maps to your user identifier from the OAuth flow.
App: transaction payloads include connectedAppId and connectedAppName. If you route multiple apps to one endpoint, branch on connectedAppId. For OAUTH_USER_LINKED, the app is identified by appId.

Payload reference

Every payload includes an eventType. Field availability can vary by event; handlers should ignore unrecognized fields for forward compatibility.

📘 A note on status values. For created/updated transactions the status field takes one of PENDING, SETTLED, or FAILED. Declined transactions carry a status of DECLINED (or FAILED). Earlier drafts of this page showed COMPLETED as a status — that value is not emitted; use SETTLED to detect a finalized transaction.

Transaction created (`TRANSACTION_CREATE`)

Fired for any new transaction — virtual card purchases, deposits, transfers, and more.

{
  "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",
  "externalReferenceId": "usr_8f3d2a91",
  "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	Always `TRANSACTION_CREATE`.
`recordId`	String (UUID)	Unique webhook event record ID.
`transactionId`	String (UUID)	Identifies this transaction record. A pending authorization and its settlement share it; additional settlement legs and returns get their own. See Linking the events of one purchase.
`referenceId`	String	The Fluz purchase id. Every event that belongs to the same virtual card purchase carries the same value, so group on it to follow money end to end. May be absent on a `Virtual Card Return` that the merchant submitted as a new transaction.
`accountId`	String (UUID)	The Fluz account ID.
`userId`	String (UUID)	The Fluz user ID. May be absent on some system-generated transactions.
`externalReferenceId`	String	Optional. Staging only for now — not yet delivered in production. Your user identifier from the OAuth flow, resolved from the grant between that user and your app. Absent for private-app activity and for grants that carry no external reference.
`transactionType`	String	Transaction type, e.g. `PURCHASE`, `GIFT_CARD_PURCHASE`, `DEPOSIT`, `WITHDRAWAL`, `TRANSFER`. Treat as an open string.
`amount`	Number	Transaction amount in USD.
`originalCurrencyAmount`	Number	The amount the card issuer reports as requested, in minor units of the merchant’s currency (`6300` HKD is 63.00 HKD). On a `Virtual Card Return` it is the amount still on hold before that return, not the amount returned. Reconcile on `amount`, see Reconciling amounts.
`destination`	String	Where funds went (e.g., merchant name).
`source`	String	Funding source (e.g., `Virtual Card`).
`status`	String (enum)	One of `PENDING`, `SETTLED`, `FAILED`.
`channel`	String	Origin/channel of the transaction (e.g., `VIRTUAL_CARD`). Treat as an open string.
`connectedAppId`	String	The app the event is routed to. May be absent for private-app activity.
`connectedAppName`	String	Display name of the connected app.
`createdAt`	String (ISO 8601)	When the transaction was created.
`merchantName` / `merchantCity` / `merchantState` / `merchantCountry`	String	Merchant location details.
`cardLastFour`	String	Last four digits of the card used.
`virtualCardId`	String (UUID)	The virtual card ID, if applicable.
`digitalWalletProvider`	String (enum)	Present when a card transaction was made through a mobile wallet. One of `APPLE_PAY`, `GOOGLE_PAY` (more may be added over time). Absent or `null` for non-wallet transactions. This is the field to use to determine that a transaction was a mobile-wallet payment.
`digitalWalletToken`	String	Network token identifier for the tokenized card (e.g. `dw_...`). Not a wallet indicator on its own: it is also set for non-wallet network tokens (such as a merchant’s stored card-on-file) and may be absent on some wallet transactions. Use `digitalWalletProvider`, not the presence of this token, to decide whether a payment came from a mobile wallet.
`isReversal`	Boolean	`true` when the transaction is an authorization reversal: a released hold, whether the card issuer or Fluz released it, or a card verification void. `false` on captures and merchant refunds. Absent when we could not classify the transaction. See Reversals vs refunds below.
`cashbackRate`	Number	Decimal cashback rate (e.g., `0.05` = 5%).

Transaction updated (`TRANSACTION_UPDATE`)

Fired when a transaction’s status or details change — for example, when a pending authorization settles.

{
  "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",
  "externalReferenceId": "usr_8f3d2a91",
  "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
}

Fields match TRANSACTION_CREATE where present, plus updatedAt (ISO 8601) marking when the change occurred. userId, externalReferenceId (staging only for now), connectedAppId, and connectedAppName are carried through the same way as on TRANSACTION_CREATE, so you can identify the user and app consistently across the lifecycle. A status transition to SETTLED is the signal that a previously pending transaction has finalized. isReversal carries the same meaning here as on TRANSACTION_CREATE. See Reversals vs refunds.

Transaction declined (`TRANSACTION_DECLINE`)

Fired when a transaction is declined. Includes structured decline reasons your app can act on.

{
  "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",
  "externalReferenceId": "usr_8f3d2a91",
  "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	Total attempted amount.
`fluzAmount`	Number	Portion drawn from Fluz balance.
`externalFundingAmount`	Number	Portion drawn from external funding.
`currency`	String	ISO currency code (e.g., `USD`).
`status`	String (enum)	One of `DECLINED`, `FAILED`.
`userId`	String (UUID)	The Fluz user ID. May be absent on some system-generated transactions.
`externalReferenceId`	String	Optional. Staging only for now — not yet delivered in production. Your user identifier from the OAuth flow. Same semantics as on `TRANSACTION_CREATE`.
`isCashBalanceUsed` / `isPrepaymentBalanceUsed` / `isRewardsBalanceUsed` / `isReserveBalanceUsed`	Boolean	Which balance type(s) the attempt drew from.
`isReversal`	Boolean	`true` for an authorization reversal: a released hold, whether the card issuer or Fluz released it, or a card verification void. `false` on captures and merchant refunds. Absent when we could not classify the transaction. See Reversals vs refunds.
`transactionDateTime`	String (ISO 8601)	When the decline occurred.
`declineTitle`	String	Short, user-facing title.
`declineReason`	String	Short reason (e.g., `Insufficient funds`).
`declineDescription`	String	Longer, user-facing explanation.
`declineCtaText`	String	Suggested resolution action, when available (e.g., `Add money`).
`declineCategory`	String	High-level decline grouping. Common values include `Balance`, `Limit`, `Validation`, `Virtual Card`, and `Acquiring`. Treat as an open string and see Decline Codes for the full set and per-code detail.

Additional optional fields may be present depending on the transaction (e.g. merchantId, merchantCity, merchantState, merchantCountry, cardDisplayName, virtualCardProgram, channel, bankAccountNickname, bankAccountLastFour). Ignore any you don’t use.

Linking the events of one purchase

A virtual card purchase usually produces more than one transaction event. Two fields tie them together:

referenceId is the Fluz purchase id. The authorization, its settlement, any additional settlement leg and any return of that purchase all carry the same value. Group on it.
transactionId identifies one ledger record. A pending authorization and its settlement share it, because the settlement is delivered as a TRANSACTION_UPDATE of the same record. Anything Fluz records separately gets a new transactionId.

The sequence for a typical purchase:

Step	Event	`transactionId`	`status`	`amount`
Authorization	`TRANSACTION_CREATE`, `Virtual Card Purchase`	A	`PENDING`	negative
Settlement of that authorization	`TRANSACTION_UPDATE`, `Virtual Card Purchase`	A	`SETTLED`	negative
Additional settlement leg (the merchant cleared more than it authorized, a currency difference, or a second capture)	`TRANSACTION_CREATE`, `Virtual Card Purchase`	B	`SETTLED`	negative
Return (released hold or merchant refund)	`TRANSACTION_CREATE`, `Virtual Card Return`	C	`SETTLED`	positive

Example: an 8.54 authorization arrives as TRANSACTION_CREATE on transactionId A with status: PENDING. The merchant clears 8.56. You receive a TRANSACTION_UPDATE on A with status: SETTLED and amount: -8.54, then a TRANSACTION_CREATE on a new transactionId B with status: SETTLED and amount: -0.02. All three carry referenceId: "11323677". The net charge for the purchase is the sum of the latest amount per transactionId under that referenceId: -8.56. Rules that follow from this:

Key your records by transactionId, but reconcile by referenceId. A TRANSACTION_CREATE with status: SETTLED and no earlier pending event is normal: it is an additional leg or a return of a purchase you already hold under the same referenceId.
When an authorization is never captured and the hold is released, you receive two events: a TRANSACTION_UPDATE that moves the pending purchase to SETTLED, and a Virtual Card Return with the same referenceId and a positive amount. They net to zero. Treat the pair as the release of the pending amount, not as a purchase that completed.
A Virtual Card Return for a merchant refund that the merchant submitted as a new transaction, rather than against the original authorization, may carry no referenceId. Match those by virtualCardId, amount and merchant.

Reversals vs refunds

A reversal releases an authorization hold before any money is captured. The cardholder’s available balance goes back up, but no funds ever left and none come back. A refund happens after a capture: money moved, and the merchant sent it back. isReversal tells the two apart:

Value	Meaning
`true`	An authorization reversal. The hold was released and the amount was never captured. Released holds, whether the card issuer or Fluz released them, and card verification voids are flagged this way.
`false`	Anything we classified that is not a reversal, such as an authorization, a capture, a genuine refund, or a decline.
absent	We could not classify the transaction. Treat it as unknown, never as `false`.

Use this field instead of transactionType wherever it is present. Card issuers label these events inconsistently, so one issuer’s type value for a merchant refund is another’s for a pre-capture reversal, and the type alone cannot tell you whether money actually moved. Virtual Card Return events carry the field too: true for a released hold, false for a merchant refund. A small number of returns still arrive without it; for those use referenceId and the original authorization to tell them apart. Which event carries a reversal depends on what was reversed:

A card verification void is recorded as its own transaction, so it arrives as TRANSACTION_CREATE with a negative amount and then updates. These are the small checks a merchant runs to confirm a card is valid, which we void straight away. They carry isReversal: true.
A released pre-capture hold arrives as a separate transaction with transactionType Virtual Card Return and a positive amount, carrying the purchase’s referenceId. The original purchase is updated to SETTLED at the same time, so the two net to zero. The return carries isReversal: true whether Fluz or the card issuer released the hold.
A merchant refund also arrives with transactionType Virtual Card Return and carries isReversal: false. Match it against the original purchase by referenceId when present, otherwise by virtualCardId, amount and merchant.

A reversal is not a failure, but it does need handling: release the hold you recorded for the matching authorization, or it stays open on your side forever. Do not post it as a new outflow, since no money moved.

Reconciling amounts

Reconcile on amount. It is the USD amount that moved on that event, so the latest amount per transactionId, summed under one referenceId, is the net for the purchase however many settlement legs or returns it has. originalCurrencyAmount does not add up that way. It is the amount the card issuer reports as requested for the event. On a return that is the amount still on hold before the return, so it repeats what earlier events already carried and a sum of it double counts. Example: a 39.69 authorization whose hold is released in two steps, as when part of an order goes out of stock and the rest is released later.

Event	`amount`	`originalCurrencyAmount`
Authorization, `Virtual Card Purchase`	-39.69	3969
First release, `Virtual Card Return`	17.95	3969
Second release, `Virtual Card Return`	21.74	2174

The amount values net to 0.00 because nothing was captured. The originalCurrencyAmount values describe what was on hold at each step, not money that moved.

Deposit complete (`DEPOSIT_COMPLETE`)

Fired when a deposit from a funding source to a spend account completes.

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

OAuth user linked (`OAUTH_USER_LINKED`)

Fired when a user completes OAuth linking to your application — on both the initial link and on subsequent updates (for example, when the user re-authorizes with a different set of scopes). Public/OAuth and widget apps only. No scope is required to receive this event.

{
  "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"
  ],
  "emailAddress": "user@example.com",
  "phoneNumber": "+14155551234",
  "spendAccountAccess": {
    "restricted": true,
    "userCashBalanceIds": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ],
    "includesFutureSpendAccounts": false
  }
}

Field	Type	Description
`eventType`	String	Always `OAUTH_USER_LINKED`.
`accountId`	String (UUID)	The Fluz account ID that linked to your app.
`userId`	String (UUID)	The Fluz user ID that linked to your app.
`appId`	String (UUID)	Your application’s ID.
`externalReferenceId`	String	Optional. Your user identifier passed through the OAuth flow. Present for widget app types and any flow that supplied one; may be absent otherwise.
`scopes`	String[]	The distinct scope keys granted by this user (e.g. `LIST_PAYMENT`, `MAKE_DEPOSIT`).
`emailAddress`	String \| null	Staging only for now — not yet delivered in production. The email address on the linked user’s Fluz profile, or `null` if the user has none.
`phoneNumber`	String \| null	Staging only for now — not yet delivered in production. The phone number on the linked user’s Fluz profile, or `null` if the user has none. The format is not normalized, so normalize it (for example, to E.164) before matching against your own records.
`spendAccountAccess`	Object	Staging only for now — not yet delivered in production. Which of the user’s spend accounts this link can act on. See Spend account access below.
`spendAccountAccess.restricted`	Boolean	`true` when the user granted your app access to specific spend accounts only; `false` when the grant covers all of the user’s spend accounts.
`spendAccountAccess.userCashBalanceIds`	String (UUID)[] \| null	Staging only for now — not yet delivered in production. The `userCashBalanceId` of each granted spend account when `restricted` is `true`. Always `null` when `restricted` is `false`.
`spendAccountAccess.includesFutureSpendAccounts`	Boolean	Whether spend accounts the user opens after linking are added to a restricted grant automatically. Only meaningful when `restricted` is `true`; see Spend account access.

Because OAUTH_USER_LINKED fires again on re-link/updates, treat it as an upsert: create the connected user on first receipt, and refresh the stored scope set and contact details on later deliveries. emailAddress and phoneNumber reflect the user’s profile at the moment of the link; a later profile change does not trigger a new event on its own.

Staging onlyemailAddress and phoneNumber on OAUTH_USER_LINKED are currently delivered only in the staging environment. Production deliveries do not include them yet; this page will be updated when they are rolled out.

In rare cases Fluz can’t load the contact details when the event is sent, and emailAddress and phoneNumber are then absent from the payload. Treat an absent field as unknown and keep any value you already store. Only an explicit null means the user has no value.

Spend account access

When a user links to your app, the permissions step lets them grant access to all of their spend accounts or only to the ones they choose. spendAccountAccess tells you which of the two the link ended up with, so you can start acting on a spend account — for example, calling getSpendAccountPaymentInstructions to produce deposit instructions — without a follow-up lookup right after the link.

Restricted grant. restricted is true and userCashBalanceIds lists the spend accounts the user selected when linking. The IDs are currently delivered in staging only; production deliveries do not include them yet. includesFutureSpendAccounts tells you whether that list is fixed:
- false — the grant covers exactly these spend accounts. The list changes only if the user re-links, which sends a new OAUTH_USER_LINKED event.
- true — the operator let the user include spend accounts they open later. Each new spend account is added to the grant automatically, but opening one does not fire this event, so userCashBalanceIds is accurate only as of the link. Call getWallet with the user’s access token for the current list.
Unrestricted grant. restricted is false and userCashBalanceIds is null. The grant covers every spend account the user has now and any they open later. Fluz does not enumerate the current spend accounts in the payload, because opening a new spend account does not fire this event and a snapshot would go stale. Call getWallet with the user’s access token for the current list.

{
  "spendAccountAccess": {
    "restricted": false,
    "userCashBalanceIds": null
  }
}

Only IDs are included. Nicknames and balances are not, because they can change without firing this event — read them from getWallet, whose balances.userCashBalances is already filtered to the spend accounts the link permits. The event fires again with the updated value whenever the grant changes: the user re-consents, the granted scopes change, or the granted spend accounts change even when the scopes stay the same (for example, the user swaps one spend account for another). Treat the latest delivery as authoritative and replace, rather than merge, the stored ID list. Treat this field as a convenience. Webhook deliveries can arrive late or out of order, so if you need to be certain which spend accounts a link permits, call getWallet — it is the source of truth.

Staging onlyspendAccountAccess on OAUTH_USER_LINKED is currently delivered only in the staging environment. Production deliveries do not include it yet; this page will be updated when it is rolled out.

KYC initiation (`WIDGET_KYC_INITIATION`)

Fired when a user begins identity verification. Public/widget apps only.

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

Transfer completed — customer to app (`WIDGET_DEPOSIT_COMPLETE`)

Fired when a user transfers funds to your application.

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

Transfer completed — app to customer (`WIDGET_WITHDRAW_COMPLETE`)

Fired when your application transfers funds to a user.

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

Gift card purchase (`WIDGET_PURCHASE_GIFT_CARD`)

Fired when a gift card purchase completes through the widget.

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

Common widget payload fields: userId (Fluz user ID), accountId (Fluz account ID), externalReferenceId (your user identifier from the OAuth flow), and amount where applicable.

KYC status update (`KYC_STATUS_UPDATE`)

Fired when a connected user’s KYC status changes. Public/OAuth and widget apps only; requires the VERIFY_KYC scope. Every payload shares a common envelope; the verificationData object’s shape is discriminated by verificationType, shown per-type below.

Field	Type	Description
`eventType`	String	Always `KYC_STATUS_UPDATE`.
`userId`	String (UUID)	The Fluz user ID whose KYC status changed.
`accountId`	String (UUID)	The Fluz account ID.
`previousStatus` / `newStatus`	String (enum)	One of `NOT_REQUIRED`, `PENDING_DOCUMENTS`, `MISSING_1099_INFO`, `PASS`, `PASS_INTERNATIONAL`, `SOFT_DECLINE`, `HARD_DECLINE`, `FAIL`.
`externalReferenceId`	String	Optional. Your user identifier from the OAuth flow.
`verificationType`	String (enum)	One of `SSN`, `DOCUMENTS`, `SYSTEM`. Discriminates the shape of `verificationData`, shown per-type in the tabs below.

SSN
Documents
System

Emitted when the status change resulted from SSN-based verification.

{
  "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	User’s legal first name.
`verificationData.userLastName`	String	User’s legal last name.
`verificationData.userDateOfBirth`	String (ISO 8601)	Optional. User’s date of birth.
`verificationData.lastFourSSNDigits`	String	Optional. Last four digits of the SSN used for verification.
`verificationData.legalAddress`	Object	Optional. See shape below.

Emitted when the status change resulted from document-based identity verification.

{
  "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	User’s legal first name.
`verificationData.userLastName`	String	User’s legal last name.
`verificationData.userDateOfBirth`	String (ISO 8601)	Optional. User’s date of birth.
`verificationData.documentType`	String	Optional. Type of document submitted (e.g., `PASSPORT`).
`verificationData.documentId`	String (UUID)	Optional. Fluz’s ID for the submitted document.
`verificationData.documentIssuer`	String	Optional. Issuing country/authority.
`verificationData.documentIssueDate`	String (ISO 8601)	Optional. When the document was issued.
`verificationData.documentExpireDate`	String (ISO 8601)	Optional. When the document expires.
`verificationData.legalAddress`	Object	Optional. See shape below.

Emitted for system-driven status changes not tied to a specific SSN or document submission (e.g., automated re-review). verificationData itself is optional here — it may be entirely absent.

{
  "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	Optional. May be entirely absent.
`verificationData.reason`	String	Optional. Free-text reason for the system-driven change.

legalAddress, when present (SSN and DOCUMENTS types only), has the shape { streetAddressLine1, streetAddressLine2 (optional), city, state, postalCode, country }.

KYB status update (`KYB_STATUS_UPDATE`)

Fired when a connected business’s KYB status changes. Public/OAuth apps only; requires the REGISTER_BUSINESS scope.

{
  "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	Always `KYB_STATUS_UPDATE`.
`accountId`	String (UUID)	The business’s Fluz account ID.
`userId`	String (UUID)	Optional. The Fluz user ID associated with the business, when available.
`previousStatus` / `newStatus`	String (enum)	One of `IN_PROGRESS`, `SUBMITTED_FOR_APPROVAL`, `PASS`, `REVIEW`, `FAILED`, `SOFT_DECLINE`, `HARD_DECLINE`, `PENDING_FORMATION`, `PENDING_DOCUMENTS`, `PASS_INTERNATIONAL`, `WAITING_FOR_SCREENING_RESULT`.
`externalReferenceId`	String	Optional. Your user identifier from the OAuth flow.

Funding source status update (`FUNDING_SOURCE_STATUS_UPDATE`)

Fired when a user adds, renames or removes a funding source — a bank account, a bank card, or a PayPal account. Requires the LIST_PAYMENT scope. Staging only for now — not yet delivered in production.

{
  "eventType": "FUNDING_SOURCE_STATUS_UPDATE",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "externalReferenceId": "usr_8f3d2a91",
  "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	Always `FUNDING_SOURCE_STATUS_UPDATE`.
`accountId`	String (UUID)	The Fluz account the funding source belongs to.
`userId`	String (UUID)	Nullable. The user the funding source belongs to. Always present for cards and PayPal accounts; `null` for some bank accounts, which are held at the account level. Route on `accountId`, not `userId`.
`externalReferenceId`	String	Optional. Your user identifier from the OAuth flow. Absent for private-app deliveries and wherever `userId` is `null`.
`changeType`	String (enum)	One of `ADDED`, `UPDATED`, `DELETED`.
`fundingSourceId`	String (UUID)	The funding source’s Fluz ID — a bank account ID, bank card ID, or PayPal vault ID. Stable across all three change types.
`fundingSourceType`	String (enum)	One of `BANK_ACCOUNT`, `BANK_CARD`, `PAYPAL`.
`brand`	String	Nullable. The card network for `BANK_CARD`, the institution name for `BANK_ACCOUNT`, `PAYPAL` for a PayPal account.
`lastFour`	String	Nullable. Last four digits of the card or bank account. Always `null` for `PAYPAL`.
`nickname`	String	Nullable. The name the user sees for this source. Always `null` for `PAYPAL`.
`status`	String	Nullable. The source’s own status at the time of the change, such as `ACTIVE`. Values differ by type: cards use `ACTIVE` / `INACTIVE` / `PENDING_REMOVAL`, bank accounts `ENABLED` / `DISABLED`, PayPal `ACTIVE` / `REMOVED`.
`createdAt` / `updatedAt`	String (ISO 8601)	Nullable. When the funding source itself was created and last modified.
`changedAt`	String (ISO 8601)	When this change happened. Use it to order events for the same `fundingSourceId`.

UPDATED fires only when a field in this payload actually changed — renaming a source or a status change produces one; routine internal record-keeping does not. Removing a funding source does not delete the row, it marks it inactive, so a DELETED event carries the terminal status (INACTIVE, DISABLED or REMOVED) rather than the absence of a record. Rely on changeType to decide that a source is gone. Full card and bank account numbers are never included in this payload.

Best practices

Respond fast, process later. Return 200 immediately and handle the event asynchronously to avoid timeouts and unnecessary retries.
Verify every request. Validate X-HMAC-Signature against the raw body using your API key before processing.
Deduplicate with event IDs. Track X-Event-ID to handle retried/duplicate deliveries.
Treat enum-like fields as open strings. New transactionType, channel, and declineCategory values can appear over time; branch on the values you care about and tolerate unknowns.
Upsert on OAUTH_USER_LINKED. It can fire more than once per user; refresh the stored scope set and spendAccountAccess each time rather than assuming first-link-only semantics.
Key funding sources by fundingSourceId. One event type carries all three change types; branch on changeType and order same-source events by changedAt.
Accept unknown fields. Payloads may gain fields over time; ignore unrecognized ones rather than failing.
Monitor your endpoint. Alert on repeated non-2xx responses — after 5 failed attempts an event’s delivery is abandoned.

Troubleshooting

Symptom	Likely cause	Fix
Not receiving any webhooks	Endpoint unreachable or returning errors	Confirm the URL is correct, publicly accessible over HTTPS, and returns `2xx`.
Missing certain event types	App lacks the required scopes	Ensure your app holds the scopes listed for that event.
Public app not receiving events for a user	User hasn’t authorized the required scopes	Confirm the user’s OAuth grant includes the needed scopes.
Not receiving `OAUTH_USER_LINKED`	Subscribed on a private app, or not subscribed at all	This event is public/OAuth only. Subscribe to it (or use catch-all) on an OAuth or widget app.
Signature verification fails	Wrong API key, or verifying a re-serialized body	Use your app’s API key and verify against the raw request body.
Duplicate deliveries	Retry after a timeout	Implement idempotency using `X-Event-ID`.
`spendAccountAccess.userCashBalanceIds` is `null`	The grant is unrestricted (`restricted: false`)	The link covers all of the user’s spend accounts, current and future. Call `getWallet` with the user’s access token to list them.
A restricted grant’s `userCashBalanceIds` is missing a spend account the user opened after linking	`includesFutureSpendAccounts` is `true`, and opening a spend account does not fire the event	The new spend account is already in the grant. Call `getWallet` with the user’s access token for the current list.
`externalReferenceId` missing on transaction events	Production delivery, private-app delivery, or an OAuth grant created without an external reference	Transaction events carry it in staging only for now. Private apps never carry it. For OAuth apps, supply `external_id` at authorization time — see Managing External Reference IDs.
Events stopped coming	5 consecutive failures exhausted retries	Fix your endpoint; new events resume automatically. Contact support to replay events whose retries were exhausted.

Need help?

Technical issues: check your endpoint logs and contact support with the X-Event-ID.
Scope questions: see Application Scopes and Decline Codes.

​How it works

​Webhooks by app type

​Private apps — your own account

​Public apps (OAuth) — acting on behalf of users

​Widget apps

​Event types

​Transaction events

​Deposit events

​KYC & KYB events

​Funding source events

​OAuth events

​Widget-specific events

​Setting up webhooks

​1. Open the Developer Portal

​2. Open the Webhooks section

​3. Add a webhook URL

​4. Select events

​5. Save

​Managing webhooks

​Receiving webhooks

​Request format

​Endpoint requirements

​Verifying signatures

​Node.js (Express)

​Python (Flask)

​Responding to webhooks

​Retry policy

​Idempotency & ordering

​Identifying the app and user

​Payload reference

​Transaction created (TRANSACTION_CREATE)

​Transaction updated (TRANSACTION_UPDATE)

​Transaction declined (TRANSACTION_DECLINE)

​Linking the events of one purchase

​Reversals vs refunds

​Reconciling amounts

​Deposit complete (DEPOSIT_COMPLETE)

​OAuth user linked (OAUTH_USER_LINKED)

​Spend account access

​KYC initiation (WIDGET_KYC_INITIATION)

​Transfer completed — customer to app (WIDGET_DEPOSIT_COMPLETE)

​Transfer completed — app to customer (WIDGET_WITHDRAW_COMPLETE)

​Gift card purchase (WIDGET_PURCHASE_GIFT_CARD)

​KYC status update (KYC_STATUS_UPDATE)

​KYB status update (KYB_STATUS_UPDATE)

​Funding source status update (FUNDING_SOURCE_STATUS_UPDATE)

​Best practices

​Troubleshooting

​Need help?

How it works

Webhooks by app type

Private apps — your own account

Public apps (OAuth) — acting on behalf of users

Widget apps

Event types

Transaction events

Deposit events

KYC & KYB events

Funding source events

OAuth events

Widget-specific events

Setting up webhooks

1. Open the Developer Portal

2. Open the Webhooks section

3. Add a webhook URL

4. Select events

5. Save

Managing webhooks

Receiving webhooks

Request format

Endpoint requirements

Verifying signatures

Node.js (Express)

Python (Flask)

Responding to webhooks

Retry policy

Idempotency & ordering

Identifying the app and user

Payload reference

Transaction created (`TRANSACTION_CREATE`)

Transaction updated (`TRANSACTION_UPDATE`)

Transaction declined (`TRANSACTION_DECLINE`)

Linking the events of one purchase

Reversals vs refunds

Reconciling amounts

Deposit complete (`DEPOSIT_COMPLETE`)

OAuth user linked (`OAUTH_USER_LINKED`)

Spend account access

KYC initiation (`WIDGET_KYC_INITIATION`)

Transfer completed — customer to app (`WIDGET_DEPOSIT_COMPLETE`)

Transfer completed — app to customer (`WIDGET_WITHDRAW_COMPLETE`)

Gift card purchase (`WIDGET_PURCHASE_GIFT_CARD`)

KYC status update (`KYC_STATUS_UPDATE`)

KYB status update (`KYB_STATUS_UPDATE`)

Funding source status update (`FUNDING_SOURCE_STATUS_UPDATE`)

Best practices

Troubleshooting

Need help?