This guide explains the observable money movements available to API clients.

Correlation IDs

Use these fields to connect events and API responses:

  • referenceId: primary correlation key across card and account events.
  • linkedId: chain key for related card events (for example authorization -> settlement -> refund).
  • Idempotency-Key: retry safety key for write requests.

Rule: start from referenceId and join card_transaction + account_transaction events.

Flow Map (Client View)

Flow Card Event Types Account Event Types Typical Result
Card authorization authorization pending/settle_fee (if fee hold applies) Card hold placed; account fee hold may appear
Card settlement settle fee/settle_fee Hold consumed; fee finalized
Authorization reversal cancel transfer/settle_fee Hold released; fee hold released
Refund refund Optional fee reversal entries Spent amount returned to card
Decline decline fee/decline_fee (if configured) Decline recorded; decline fee may apply
Card topup topup transfer/card_deposit Funds moved from master account to card
Card withdraw withdraw transfer/card_withdraw Funds moved from card back to master account
Card close close transfer/card_closed_refund (if remaining funds exist) Remaining balance returned before closure
Account topup none deposit/* Master account funded
Account withdraw none withdraw/* Funds moved out of master account

Reconciliation Checklist

  1. Capture referenceId and linkedId from webhook payloads.
  2. Group all events by referenceId.
  3. Verify expected card and account events exist for the flow.
  4. Compare net event amounts to your internal ledger.
  5. If an event is missing, queue reconciliation and use webhook resend.

For exact per-event balance effects, see Webhook Balance Effects.