Advance notice: transactions, deposits, fees and balances

📅

Advance notice — effective 00:00 PST July 9, 2026:

This entry describes a new real-time webhook layer for Card transaction and deposit events. No existing endpoints will be affected or deprecated. Read this page to understand how the new webhook model complements the existing transaction and balance endpoints, and to prepare your webhook handler.

Summary

After release, the platform will deliver real-time webhook notifications for every transaction and deposit event — both pending holds and final settlements. This adds a push-based event layer on top of the existing polling model; no existing endpoints are removed, renamed, or changed in behavior.

What the endpoints return (and will continue to return)

Understanding what the existing endpoints return is essential context for understanding what the new webhooks add, and how the available balance and ledger balance are constructed.

GET /cards/transactions

This endpoint returns:

• Settled, posted transactions and deposits — each debit or credit event that has already cleared and adjusted the Card's availableBalance and ledgerBalance
• Pending or authorization hold amounts — the total value of currently reserved and blocked amounts that have reduced the Card's availableBalance but not the ledgerBalance
• Pending deposit events — each deposit event that has not yet cleared for spending and has increased the Card's ledgerBalance but not the availableBalance

🚧

It's not currently possible for this endpoint to return individual pending/hold transactions because the available transaction lifecycle data is insufficient to reliably retire or replace those transactions. Instead, a single line item covers the total value of all currently pending/hold amounts reserved or blocked against the Card.

GET /cards/fees

This returns only posted fee transactions that have cleared and reduced both the availableBalance and the ledgerBalance accordingly. Fees are not charged on pending/hold amounts.

GET /cards/{cardId}/balance

This endpoint returns the current availableBalance and ledgerBalance. The ledgerBalance reflects funds that are actually in the Card's corresponding Card Account, whereas availableBalance reflects those funds that are currently available to spend.

📘

The difference between the ledgerBalance and availableBalance is the sum of all pending/hold transactions (which will reduce the ledgerBalance when they clear) and pending deposits (which will increase the availableBalance when they clear).

ledgerBalance − availableBalance = Σ(outstanding hold/pending amounts)

ledgerBalance

The ledgerBalance is the balance of the Card Account. It is reduced when transactions settle, and increased when any deposit arrives — whether or not that deposit has cleared for spending. The gap between ledgerBalance and availableBalance reflects pending/hold debit amounts (reserved but not yet settled) and cleared-but-not-yet-spendable deposit credits.

📘

The ledgerBalance at any point in time equals a known prior ledgerBalance, less all settled transactions/debits, plus all deposits/credits (whether or not cleared) since that snapshot.

ledgerBalance = ledgerBalance₀ + Σ(all deposits) − Σ(settled transactions)

Below, this is expressed in more detail as a time-indexed account balance reconciliation formula (based on the stock-flow equation in economics):

Where:

• LB_T = ledger balance (ledgerBalance) today
• LB_T-Δt = ledger balance (ledgerBalance) at a prior date
• ∃W_i = each settled/cleared withdrawal/debit transaction in the period (T-Δt, T]
• ∀D_j = all deposit/credit transactions in the period, whether or not cleared (T-Δt, T]
• n = total number of withdrawals/debits; m = total number of deposits/credits

availableBalance

The availableBalance reflects only cleared deposits and is reduced by all transactions — both pending/hold and finally settled. It can never exceed the ledgerBalance.

📘

The availableBalance at any point in time equals a known prior availableBalance, less all transactions/debits (whether pending/hold or completed), plus all cleared deposits/credits since that snapshot.

availableBalance = availableBalance₀ + Σ(cleared deposits) − Σ(all transactions)

Again, this can be expressed as a mathematical formula as follows:

Where:

• AB_T = available balance (availableBalance) today
• AB_T-Δt = available balance (availableBalance) at a prior date
• ∀W_i = all withdrawal/debit transactions in the period, whether or not cleared (T-Δt, T]
• ∃D_j = each cleared deposit/credit transaction in the period (T-Δt, T]
• n = total number of withdrawals/debits; m = total number of deposits/credits

What the new webhooks add

The new webhook layer surfaces real-time completed and settled transactions, and pending/hold events. Together, the endpoints and webhooks give a complete picture of account activity across both the settled and pending layers:

Webhooks are the right source for real-time Card activity alerts (both pending and completed transaction and deposit notifications) but they are not definitive. The GET /cards/transactions endpoint remains the right source for the cleared transaction statement and final balance reconciliation.

Balance model in full

The platform maintains two balance figures for every Card at all times. Understanding them precisely is the foundation for correct webhook handling.

The balances are updated in real time. The pending/hold amounts that make up the ledgerBalance-availableBalance gap will resolve in one of three ways:

1. Cleared/settled — a HOLD progresses to ACTTXN. Both availableBalance and ledgerBalance adjust to reflect the true settled amount (which may differ from the previously held amount — see FX spread and settlement differences below).
2. Reversed/released/cancelled — a HOLD is cancelled by the Cardholder or Merchant, or reversed/released by the Merchant, Acquirer or Card Network. No ACTTXN is produced. The availableBalance adjusts back up after the Card Network effectuates the reversal/release/cancellation (usually 5–7 days); ledgerBalance is unaffected throughout as no funds move.
3. Declined/expired — the authorization was placed but the subsequent settlement was declined. No ACTTXN is produced. The pending/hold amount will age off the availableBalance after the Card Network's expiry window (usually 5–7 days); ledgerBalance is unaffected throughout as no funds move.

🚧

The hold amount is not the final settled amount:

The ACTTXN settled amount will often differ from the HOLD amount. This may be due to interchange applied by the Card Network at settlement (typically in the range of 0.15% to 0.65%), currency conversion applied at settlement (see FX spread and settlement differences), or dynamic pricing or variable charges (e.g. hotels, car rentals, ride-hailing apps). Build your pending transaction UX accordingly — display the hold amount with a disclosure that the final amount may differ.

Webhook event structure

Every transaction webhook notification shares the same outer envelope, with the event-specific data nested inside SpData. Both HOLD and ACTTXN events use this structure; the SpData.MsgType field distinguishes them.

📘

Register a separate callback endpoint:

Transaction webhook notifications will be delivered to a separate callback endpoint from the one registered for 3D Secure OTP and certificate expiry callbacks — see Webhooks & Callback Notifications. A separate endpoint registration will be required.

🚧

Deduplicate on TransId_SC before processing:

The upstream data from the Card Network processors may include duplicate messages, and the webhook delivery system passes these on and also retries on failure. The same notification may arrive multiple times — all copies are byte-for-byte identical, including TransId_SC and DateCreated. If a notification arrives with a TransId_SC already in your data store, discard it without further processing.

Amount conventions

TransAmount in the outer envelope uses the platform-wide decimal-implied integer convention — divide by 100 to get the amount in the base currency (e.g. 1545 → $15.45). See ISO Code Conventions.

All nested amount fields are already decimal and require no conversion. The flat SpData level carries amounts as decimal strings (e.g. "15.45"); the nested SpData.OriginalDataFromSp.payload level carries them as numeric floats (e.g. 15.45). TransAmount ÷ 100 is always identical to the corresponding payload.amount — they are redundant representations of the same value in different forms and at different parse depths.

Top-level envelope fields

HOLD events (authorization/pending)

A HOLD notification may be emitted when the Card Network authorizes a transaction but it hasn't yet cleared. It represents an authorized reservation of funds. The availableBalance is reduced by the HOLD amount — but the ledgerBalance doesn't change because the transaction has not been finally posted/settled at this stage, and the final amount is unknown.

Example HOLD notification

{
  "TransId_SC": "30648854",
  "OriginalTransId_SC": "0",
  "TransId_Issuer": "268624",
  "CardId": "1234567",
  "CardToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "CardholderId": "487231",
  "DateCreated": "2026-07-03T10:24:01.384",
  "TransType": 3,
  "TransResult": 1,
  "TransAmount": 4299,
  "TransMerchantName": "",
  "TransDate": "2026-07-03T00:00:00",
  "SpData": {
    "MsgType": "HOLD",
    "cif": "3000005788",
    "account": "0003003180",
    "transdate": "2026-07-03",
    "trace": "268624",
    "authId": "281891",
    "cardnum": "PAN_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "ACTIVE",
    "txntype": "0",
    "msgtype": "100",
    "amount": "42.99",
    "currency": "840",
    "hdate": "2026-07-03",
    "htime": "102401",
    "edate": "2026-07-04",
    "etime": "102401",
    "txncode": "220",
    "txnExtDesc": "Purchase (eComm)",
    "txnIntDesc": "Purchase (eComm)",
    "statusId": "0",
    "OriginalDataFromSp": {
      "cdcEvent": "HOLD",
      "payload": {
        "cif": "3000005788",
        "account": "0003003180",
        "transdate": "2026-07-03",
        "trace": 268624,
        "authId": "281891",
        "cardnum": "PAN_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "status": "ACTIVE",
        "txntype": 0,
        "msgtype": 100,
        "amount": 42.99,
        "currency": "840",
        "hdate": "2026-07-03",
        "htime": 102401,
        "edate": "2026-07-04",
        "etime": 102401,
        "txncode": "220",
        "txnExtDesc": "Purchase (eComm)",
        "txnIntDesc": "Purchase (eComm)"
      }
    }
  }
}

Key HOLD payload fields

📘

Use HOLD events to drive real-time pending/hold transaction alerts in your Cardholder-facing UX.

Due to the unpredictability of the timing, accuracy and reliability of HOLD notifications from the Card Network lifecycle, it is inadvisable to include them in the transaction statement or history.

The Card statement should be built from the GET /cards/transactions and GET /cards/fees endpoints, reconciling against ACTTXN webhook events.

ACTTXN events (settlement / posted)

An ACTTXN notification is emitted when a transaction reaches final settlement. This is the authoritative record of a posted transaction. It triggers the final posted amount to both the availableBalance and the ledgerBalance, and the transaction will appear in GET /cards/transactions from this point onward.

Some ACTTXN notifications will not have a corresponding prior HOLD. This is normal — certain transaction types post directly to settlement without a temporary authorization step (ATM cash advance fees being the primary example). Do not treat the absence of a prior HOLD as an anomaly.

Example ACTTXN notification

{
  "TransId_SC": "30747572",
  "OriginalTransId_SC": "0",
  "TransId_Issuer": "455166",
  "CardId": "1234567",
  "CardToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "CardholderId": "487231",
  "DateCreated": "2026-04-29T14:47:47.9315651",
  "TransType": 3,
  "TransResult": 3,
  "TransAmount": 1545,
  "TransMerchantName": "WWW.DAZN.COM",
  "TransDate": "2026-04-29T14:47:07.710188",
  "SpData": {
    "MsgType": "ACTTXN",
    "unique_row_id": "528646",
    "txndate": "2026-04-29",
    "txntime": "00:00",
    "postdate": "2026-04-29",
    "postime": "00:00",
    "description": "Purchase (eComm)",
    "merchantId": "797967000347236",
    "merchantCity": "Feltham",
    "merchantCountry": "GBR",
    "mcc": "5815",
    "transactionStatus": "1",
    "referenceCode": "17979676119000402446096",
    "balance": "410.58",
    "txntimestamp": "4/29/2026 10:47:07 AM -04:00",
    "term_id": null,
    "acctCif": "3000005788",
    "srcAmount": "56.49",
    "srcCurrency": "784",
    "txnMemo": null,
    "source": "EXTERNAL",
    "trace": "455166",
    "txncode": "220",
    "OriginalDataFromSp": {
      "cdcEvent": "ACTTXN",
      "payload": {
        "trace": 455166,
        "unique_row_id": 528646,
        "txndate": "2026-04-29",
        "txntime": "00:00",
        "postdate": "2026-04-29",
        "postime": "00:00",
        "description": "Purchase (eComm)",
        "cardnum": "PAN_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "acctnum": "0003003180",
        "merchantId": "797967000347236",
        "merchantName": "WWW.DAZN.COM",
        "merchantCity": "Feltham",
        "merchantCountry": "GBR",
        "mcc": "5815",
        "amount": 15.45,
        "txncode": "220",
        "currencyCode": "840",
        "currencyDesc": "840-USD",
        "type": "DR",
        "org_or_rev": "O",
        "transactionStatus": 1,
        "referenceCode": "17979676119000402446096",
        "balance": 410.58,
        "txntimestamp": "2026-04-29 10:47:07.710188",
        "term_id": null,
        "points": null,
        "txnGroup": "PURCHASE",
        "acctCif": "3000005788",
        "rec_status": null,
        "srcAmount": 56.49,
        "srcCurrency": "784",
        "txnMemo": null,
        "source": "EXTERNAL",
        "poieligible": false,
        "transactionStatusName": "POSTED"
      }
    }
  }
}

Key ACTTXN payload fields

🚧

merchantName, amount, type, txnGroup, currencyCode, and several other key fields exist only within SpData.OriginalDataFromSp.payload — they are not present at the flat SpData level. SpData and SpData.OriginalDataFromSp are both JSON-encoded strings and must each be parsed separately before accessing these fields.

Settlement currency vs source currency

Every ACTTXN carries two amount/currency pairs with distinct semantics:

When srcCurrency == currencyCode, there is no FX conversion data available and srcAmount equals amount. This may be the case where, for example, the Merchant transaction was completed in the same currency as the Card's base currency, an FX conversion occurred prior to reaching the Issuer Processor, or where the FX conversion data isn't available. One exception is ATM fee entries, where srcAmount = 0 — the fee is assessed directly in the settlement currency with no source currency concept.

When srcCurrency != currencyCode, FX conversion was applied at settlement and the data is available to the issuer parties. srcAmount reflects the pre-conversion value and can be used to calculate or display the exchange rate applied. The FX conversion may have been performed by any of the parties to the transaction (e.g. Acquirer Processor, Acquirer Bank, Issuer Processor or Issuer Bank) or by any intermediary correspondent banks within the Card Network. This may be affected by whether the Cardholder selected the Acquirer-side Dynamic Currency Conversion at the time of the transaction, or selected the Issuer-side settlement amount.

HOLD events carry no srcAmount or srcCurrency at all. The authorization amount (SpData.amount) is always already displayed in the settlement currency.

📘

Build the transaction statement exclusively from the GET /cards/transactions and GET /cards/fees endpoints, reconciling against ACTTXN webhook events. The statement should be the deduplicated, date-ordered list of all transactions for a given Card, filtered to the relevant date range. The availableBalance will always reconcile to GET /cards/transactions and GET /cards/fees.

Matching a HOLD to its ACTTXN

There is no shared key between a HOLD and its eventual ACTTXN (assuming it completes). The authId and trace values generated at authorization are independently regenerated at settlement and do not match. The ACTTXN referenceCode does not appear in the HOLD at all. If you intend to establish matches between HOLD and ACTTXN transactions for internal monitoring purposes, it must be done inferentially — but this is inherently imprecise and should not be used to construct Card statements.

Where multiple candidates exist, prefer the closest amount match, breaking ties by date proximity. Flag any match where the amount variance exceeds 2% for review — these typically represent dynamic-pricing adjustments on hotels, ride-hailing or food delivery transactions.

After each matching cycle, validate:

Σ(unmatched HOLD amounts) ≈ ledgerBalance − availableBalance

A significant divergence indicates a missed webhook or an incorrect match — investigate before the next cycle.

FX spread and settlement differences

For cross-currency transactions — where the Merchant's billing currency differs from the Card's base currency — the settled ACTTXN amount will typically differ from the authorization HOLD amount. This difference has three components:

1. Interchange — applied by the Card Network, Acquirer and Acquirer Processor at settlement (typically 0.15%–0.65%), not at authorization
2. Currency conversion — the FX rate applied at settlement may differ from the rate at authorization, and the conversion spread is applied at the settlement stage
3. Dynamic or variable pricing — holds placed for estimated amounts (hotels, car rentals, ride-hailing) are replaced at settlement by the actual charge, which may be higher or lower

srcAmount and srcCurrency in the ACTTXN payload record the pre-conversion amount and currency, which can be used to identify where currency conversion has occurred.

This is expected behavior. Pending transaction UX should include a disclosure: "The final settled amount may differ from the pending amount due to network fees, currency conversion and variable pricing."

Transactions in the Card's base currency will also carry interchange at settlement but will not be subject to currency conversion — the HOLD and ACTTXN amounts will typically be closer, though not always identical.

Dynamic Currency Conversion (DCC). Where a Cardholder accepts a conversion rate offered at an ATM or point-of-sale rather than allowing the Issuer to convert, the transaction is submitted to the Card Network already denominated in the Card's base currency. In this case srcCurrency in the ACTTXN payload will equal the settled currencyCode, confirming no issuer-side conversion occurred. DCC rates are typically less favourable than the issuer's spread — where DCC was applied, display a disclosure to the Cardholder recommending they decline DCC in future.

📘

The above information about Dynamic Currency Conversion applies equally to Card transactions online or at a point-of-sale.

ATM transactions

ATM cash withdrawals produce two simultaneous ACTTXN notifications and no prior HOLD. Both arrive at the same time and are linked via OriginalTransId_SC.

Link the two via OriginalTransId_SC and display as a single grouped statement entry (withdrawal + fee) rather than two independent line items.

HOLDs that do not settle

Not every HOLD will produce a subsequent ACTTXN. The following are expected and normal:

Deposit webhooks

The same HOLD/ACTTXN pattern applies to inbound deposits:

• GET /cards/{cardId}/balance and the balance fields returned via polling reflect only cleared, credited deposits in availableBalance.
• A deposit that is pending or being processed will appear in the ledgerBalance but not yet in availableBalance.
• A webhook notification will be delivered when a deposit hold is placed, and again when it clears.

Full payload documentation for deposit webhook events will be published at launch and linked from Webhooks & Callback Notifications.

Integration guidance

There is no mandatory migration — existing polling integrations continue to work without modification. To take advantage of the new real-time event layer:

1. Register a callback endpoint if you haven't already — see Webhooks & Callback Notifications. Transaction and deposit events will be delivered to the webhook URL you register.
2. Implement deduplication on TransId_SC as the first step in your ingestion pipeline, before any other processing.
3. Parse SpData in two steps — it is a JSON-encoded string, and OriginalDataFromSp within it is a third encoding layer. Key fields including merchantName, amount, type, and txnGroup are only accessible after both parse steps.
4. Decide on HOLD handling. The simplest approach is to consume HOLD events purely for Cardholder alerts (push notifications, in-app pending transaction display) and continue relying on GET /cards/transactions for the statement and balance reconciliation.
5. If you build HOLD-to-ACTTXN matching, store HOLD and ACTTXN events separately and match asynchronously using the CardId, amount tolerance and date-proximity criteria above — use only for audit and monitoring purposes, not for constructing Card statements.
6. Do not include HOLD transactions in the transaction statement. The statement is built from GET /cards/transactions and GET /cards/fees, reconciling against ACTTXN events.

What's next

• Webhooks & Callback Notifications — callback endpoint setup and configuration
• Transactions & Fees — current endpoint behavior and the fee structure
• Accounts, Wallets & Deposit Addresses — balance fields and deposit model
• Reconcile Transactions & Fees — reconciliation guide