Webhook Balance Effects

This guide is the reconciliation reference for webhook-driven balance movement.

Ledger Model

Master account balance fields: available, pending.
Card balance fields: available, pending, spent.
Correlation key: referenceId (shared across card_transaction and account_transaction).

Webhook Feeds You Receive

Event	Scope	Primary Use
`card_transaction`	Card lifecycle and spend events	Operational card state and card-side balance movement
`account_transaction`	Master-account ledger events	Treasury/accounting reconciliation

Payload Shapes

`card_transaction`

{
  "event": "card_transaction",
  "data": {
    "id": "5b2fa934-1f1d-4b71-8d5a-a3e2f61ac1af",
    "cardId": "0b1e9c6e-5d87-4f90-8c4d-0ad6f4ce4be5",
    "type": "authorization",
    "transactionAmount": "12.34",
    "transactionCurrency": "USD",
    "referenceId": "c8de3ebf-5b2d-4020-a7bb-65f88c3a37ce",
    "linkedId": "a5a9b799-b0f6-4e7a-a2db-08ce74efaa87",
    "timestamp": "2025-06-02T11:24:12Z"
  }
}

`account_transaction`

{
  "event": "account_transaction",
  "data": {
    "id": "2f2eb5f3-a28a-442d-9f56-d2fe5a9cb730",
    "accountId": "tenant-usd",
    "type": "fee",
    "subtype": "settle_fee",
    "amount": "0.35",
    "currency": "USD",
    "referenceId": "c8de3ebf-5b2d-4020-a7bb-65f88c3a37ce",
    "timestamp": "2025-06-02T11:24:13Z"
  }
}

Card Event -> Balance Effect

`card_transaction.data.type`	Card `available`	Card `pending`	Card `spent`
`issue`	`+amount`	`0`	`0`
`topup`	`+amount`	`0`	`0`
`withdraw`	`-amount`	`0`	`0`
`authorization`	`-amount`	`+amount`	`0`
`cancel`	`+amount`	`-amount`	`0`
`settle`	`0`	`-amount`	`+amount`
`refund`	`+amount`	`0`	`-amount`
`decline`	`0`	`0`	`0`
`freeze` / `unfreeze` / `close`	`0`	`0`	`0`

Account Event -> Balance Effect

`account_transaction.data.type/subtype`	Master `available`	Master `pending`	Notes
`fee/settle_fee`	`0`	`-amount`	Settlement fee entry delivered to client webhook
`fee/decline_fee`	`-amount`	`0`	Immediate fee on decline
`transfer/card_deposit`	`-amount`	`0`	Master account funds card
`transfer/card_withdraw`	`+amount`	`0`	Card returns funds to master account
`transfer/card_closed_refund`	`+amount`	`0`	Return remaining funds on card close
`transfer/card_closed_cancel`	`0`	`0`	Reserved subtype, no balance impact
`deposit/*`	`+amount`	`0`	Account topups and credits
`withdraw/*`	`-amount`	`0`	Account debits/withdrawals

card_closed_cancel is reserved and may be absent in normal client flows.
Authorization/reversal fee hold legs (pending/settle_fee, transfer/settle_fee) are not part of the standard client webhook stream.

Correlation Rules for Reconciliation

Group events by referenceId.
For each group, compare expected delta table vs received payloads.
Validate that master-account and card legs net out as expected for the flow.
If any leg is missing, keep the movement in a reconciliation queue and trigger replay (POST /v1/webhooks/resend).

Practical Flow Examples

Authorization + Settlement

Expected sequence:

card_transaction(type=authorization) -> card available -X, pending +X
card_transaction(type=settle) -> card pending -X, spent +X
account_transaction(type=fee, subtype=settle_fee) -> fee settlement entry

Authorization + Cancel

Expected sequence:

card_transaction(type=authorization)
card_transaction(type=cancel) -> hold released on card

Ingestion Checklist

Verify x-signature before processing.
Persist raw payload by data.id.
Enforce idempotency on data.id and (event, referenceId, type/subtype).
Process asynchronously and return 204 quickly.
Alert on repeated missing-leg patterns per referenceId.

For retry mechanics and signature implementation details, use Webhook Handling Patterns.