📅
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

Type	Detail
Added	Real-time `HOLD` and `ACTTXN` webhook events for Card transactions and deposits
Changed?	No — existing endpoints continue to return the same data on the same schedule
Breaking?	No
ETA	00:00 PST July 9, 2026

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 all currently reserved and blocked amounts that have reduced the Card's availableBalance but not the ledgerBalance (see the warning callout below)
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. Each HOLD and ACTTXN event (see Webhook event structure) is an isolated transaction. Instead, a single line-item covers the total value of all currently pending/hold amounts reserved or blocked against the Card's ledgerBalance.

`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 each settled transaction/debit, 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 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 each cleared deposit/credit 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:

	Balance effect	Event type
Settled transactions	`availableBalance` and `ledgerBalance` reduced	✓ `ACTTXN` completed transaction event delivered
Pending/hold transactions	`availableBalance` reduced; `ledgerBalance` unchanged	✓ `HOLD` pending transaction event delivered
Cleared deposits	`availableBalance` and `ledgerBalance` increased	✓ `CLEARED` deposit event delivered
Pending deposits	`ledgerBalance` increased; `availableBalance` unchanged	✓ `PENDING` deposit event delivered

Webhooks are the right source for real-time throwaway Card activity alerts (both pending and completed transaction and deposit notifications) but they are not definitive. The GET /cards/transactions and GET /cards/fees endpoints together remain 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.

Field	Meaning
`availableBalance`	The net spendable amount. Reflects all cleared deposits reduced by settled transactions and any pending/hold amounts that are reserved. Always reconciles `GET /cards/transactions` and `GET /cards/fees` to `GET /cards/{cardId}/balance`.
`ledgerBalance`	The full committed position held in the Card Account. Includes `availableBalance` plus all outstanding pending/hold transactions and pending deposits.

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:

Cleared/settled — a HOLD progresses to ACTTXN. In actuality, the HOLD amount is released and a final settled transaction is posted. The 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).
Reversed/cancelled — a HOLD is cancelled by the Cardholder or reversed by the Merchant, and the authorization hold amount is released by the Acquirer Bank and Issuer Bank via the Card Network. No ACTTXN is produced. The availableBalance adjusts back up after the Card Network effectuates the release (usually 5–7 days); ledgerBalance is unaffected throughout as no funds move. (Note: this is different to a refund, in which credit against the whole or a part of an already completed ACTTXN is processed later as an independent transaction.)
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 3-D 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 ingested by the platform 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, therefore, 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). This is a platform policy. See ISO Code Conventions.

All nested amount fields received from the Card Network 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

Field	Type	Description
`TransId_SC`	string	The unique identifier for this notification. Primary key and deduplication key.
`OriginalTransId_SC`	string	`"0"` for standalone events. Non-zero when this notification is a child of a prior event — for example, an ATM cash withdrawal referencing its associated fee charge.
`TransId_Issuer`	string	The issuer-side trace number. Not unique across events — do not use for deduplication.
`CardId`	string	The Card this event relates to. A Cardholder may hold multiple Cards.
`CardToken`	string	A security feature that tokenizes and obfuscates a Card's sensitive data throughout a transaction lifecycle.
`CardholderId`	string	The Cardholder whose Card this notification relates to.
`DateCreated`	string	ISO 8601 timestamp at which this notification was generated.
`TransType`	integer	See Statuses & Enums
`TransResult`	integer	`1` = authorization hold (`HOLD`) · `3` = settled (`ACTTXN`)
`TransAmount`	integer	Decimal-implied — divide by 100 for the base currency amount (e.g. `4299` → `$42.99`). For `HOLD` events the same value is available as a decimal string at `SpData.amount`; for `ACTTXN` events as a numeric decimal at `SpData.OriginalDataFromSp.payload.amount`.
`TransMerchantName`	string	Only populated for `ACTTXN` events.
`TransDate`	string	The transaction date.
`SpData`	object	The event payload — a JSON-encoded string requiring a second parse step. Contains `MsgType`, flat event fields, and `OriginalDataFromSp` (itself a third level of JSON encoding).

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

Field	Path	Notes
`MsgType`	`SpData.MsgType`	`"HOLD"`
`amount`	`SpData.amount`	Authorized amount in base currency (string). This is pre-settlement — the final settled figure may differ due to interchange and FX at clearing.
`currency`	`SpData.currency`	ISO 4217 numeric code. `"840"` = USD. The authorization amount is already denominated in the Card's base currency regardless of the merchant's billing currency.
`authId`	`SpData.authId`	Authorization ID. Not carried through to the corresponding `ACTTXN` — cannot be used to link the two events.
`txncode`	`SpData.txncode`	Transaction type code — see Statuses & Enums.
`txnExtDesc`	`SpData.txnExtDesc`	Human-readable transaction type, e.g. `"Purchase (eComm)"`, `"Foreign Purchase"`.
`hdate` / `htime`	`SpData.hdate`, `SpData.htime`	Hold placement date and time.
`edate` / `etime`	`SpData.edate`, `SpData.etime`	Authorization window expiry — typically 24 hours.

📘
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 and the availableBalance and ledgerBalance.

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 one 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:

Fields	What they represent
`payload.amount` + `payload.currencyCode`	The final settled amount in the Card's settlement currency — what is actually debited to the Card Account.
`payload.srcAmount` + `payload.srcCurrency`	The pre-conversion amount and currency — what the Merchant billed (or the intermediate currency in the conversion chain) before any FX conversion to the settlement currency, and potentially pre-interchange.

When srcCurrency == currencyCode, there is no FX conversion data available and srcAmount equals amount. This may be the case where, for example:

it was a domestic transaction denominated in the same currency as the Card's base currency
the Merchant billed or processed the transaction in the same currency as the Card's settlement currency
an FX conversion occurred somewhere in the transaction chain prior to reaching the Issuer Processor
the Acquirer-side 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 direct parties to the transaction (e.g. Acquirer Processor, Issuer Processor, Issuer Bank, etc.) or by any intermediary within the transaction chain (e.g. a correspondent bank, clearing house, etc.). This may be affected by whether the Cardholder selected Dynamic Currency Conversion at the time of the transaction, or selected the settlement amount.

HOLD events carry no srcAmount or srcCurrency at all. The authorization amount (SpData.amount) is always already displayed in the settlement currency because it is simply a temporary authorization hold applied to the Card Account, not an actual transaction.

Field	Path	Description
`MsgType`	`SpData.MsgType`	`"ACTTXN"`
`unique_row_id`	`SpData.unique_row_id`	Processor-level event ID. Distinct from `TransId_SC`.
`merchantName`	`SpData.OriginalDataFromSp.payload.merchantName`	Merchant display name. Use for the statement line item. Nested payload only.
`amount`	`SpData.OriginalDataFromSp.payload.amount`	Final settled amount in base currency (numeric decimal). Authoritative — use this figure for the transaction statement line item. Nested payload only.
`type`	`SpData.OriginalDataFromSp.payload.type`	`"DR"` (debit) or `"CR"` (credit). Credits include refunds and reversals — surface these distinctly in the statement. Nested payload only.
`txnGroup`	`SpData.OriginalDataFromSp.payload.txnGroup`	Category: `"PURCHASE"`, `"CASHADVANCE"`, `"FEES"`, `"CREDITVOUCHER"`, `"PAYMENT"`. Drives statement categorization and display logic for ATM or fee entries. Nested payload only.
`currencyCode`	`SpData.OriginalDataFromSp.payload.currencyCode`	ISO 4217 numeric code for the settled currency, e.g. `"840"` = USD. Nested payload only.
`referenceCode`	`SpData.referenceCode`	Globally unique settlement reference. Use as the canonical transaction identifier for the statement and for dispute tracking. Available at both flat `SpData` and nested payload levels.
`txndate`	`SpData.txndate`	Transaction date. Use for statement ordering.
`description`	`SpData.description`	Processor description. Most useful for ATM and fee entries where `merchantName` is generic (e.g. `"Foreign Cash Withdrawal"`, `"Foreign Cash Adv Fee"`).
`srcAmount`	`SpData.srcAmount`	Pre-conversion amount where FX conversion occurred — see FX spread and settlement differences.
`srcCurrency`	`SpData.srcCurrency`	ISO 4217 numeric code for the pre-conversion currency.
`balance`	`SpData.OriginalDataFromSp.payload.balance`	Account balance after this transaction posted (numeric decimal). Secondary reconciliation anchor. Nested payload only.

📘
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 concatenated 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

❗️
If you intend to establish matches between HOLD and ACTTXN transactions, it should be for internal logging, monitoring and auditing purposes only, and to track Cardholder activity against your AML policies, with a human-in-the-loop to investigate any flagged transactions. This is a strictly inferential methodology only — it is inherently imprecise and should not be used to construct Card statements.

There is no shared key between a HOLD and its eventual ACTTXN (assuming it completes). These are independent events. 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.

Criterion	Rule
Card	`HOLD.CardId == ACTTXN.CardId`
Amount	For same-currency merchants: `ACTTXN.amount` usually ~0.45% higher than `HOLD.amount` (accounting for interchange). For cross-currency merchants: variable but usually within 2.5% after adjusting for the expected interchange and FX — see FX spread and settlement differences.
Timing	`ACTTXN.txndate` within 3 days of `HOLD.hdate` — most transactions settle same-day.

Where multiple candidates exist, prefer the closest amount match, breaking ties by date proximity. Flag for review any match where the amount variance exceeds 2.5% — these typically represent dynamic-pricing adjustments or unpredictable charging 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:

Interchange — applied by the Card Network, Acquirer and Acquirer Processor at settlement (typically 0.15%–0.65%), not at authorization (observably ~0.45% in most cases but varies depending on the Acquirer-side parties, location, etc.)
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
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 at the settlement-side — 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 favorable 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.

	Withdrawal	Fee
`OriginalTransId_SC`	Non-zero — references the fee notification's `TransId_SC`	`"0"` (parent)
`txnGroup`	`"CASHADVANCE"`	`"FEES"`
`description`	`"Foreign Cash Withdrawal"`	`"Foreign Cash Adv Fee"`
`txncode`	`302`	`113`

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

HOLD transactions that do not settle

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

Scenario	Cause	Outcome
Customer cancellation	Cardholder cancels after authorization — common with ride-hailing and food delivery	`HOLD` placed, no `ACTTXN` follows. Hold released after network expiry (typically 5–7 days). `availableBalance` unaffected throughout.
Merchant reversal	Merchant voids before clearing	As above.
Revised authorization	Final amount differs from authorization hold amount (e.g. dynamic pricing transactions such as ride-hailing estimates)	Original `HOLD` may not match the `ACTTXN`. The ±2.5% tolerance absorbs most adjustments; larger variances may produce a new authorization.
Network expiry	No settlement within the authorization window	Hold releases automatically after 5–7 days.
Decline at settlement	Authorization succeeded but clearing was declined	`HOLD` placed, no `ACTTXN`. No explicit decline webhook is currently emitted — the hold ages off.

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:

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.
Implement deduplication on TransId_SC as the first step in your ingestion pipeline, before any other processing.
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.
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.
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.
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

Changelog

Advance notice: transactions, deposits, fees and balances

Blockchain deposit methodology