Midaz events

Reference the domain events emitted by Midaz ledger, Fees, and CRM services — event topics, CloudEvents payloads, and versioning for downstream consumers.

Midaz emits domain events as CloudEvents 1.0 messages in binary content mode over Kafka, published through lib-streaming. Every event travels in the shared envelope: ce-type names the event as studio.lerian.<resource>.<event>, ce-subject carries the aggregate id, ce-tenantid the owning tenant (absent in single-tenant scope), and ce-schemaversion the payload version — 1.0.0 for every event below.

ce-source is deployment-configured through the STREAMING_CLOUDEVENTS_SOURCE environment variable and has no default: when streaming is enabled, the ledger fails to boot if it is unset. Topics do not derive from the source — Midaz routes each event to an explicit topic that folds the owning service segment into the first token (lerian.streaming.ledger_<resource>.<event> for the ledger core; the CRM and Fees capabilities below use crm_ and fee_) and normalizes hyphens to underscores in the topic tail. The ce-type keeps its hyphens (for example, balance.config-changed lands on topic lerian.streaming.ledger_balance.config_changed but keeps ce-type studio.lerian.balance.config-changed). Money amounts — balances, transaction and operation amounts — cross the wire as decimal strings, never floats.

Ledger events

Facts the ledger emits as organizations, accounts, balances, and transactions change.

Organization

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.organization.created	lerian.streaming.ledger_organization.created	An organization is created.	id, legalName, doingBusinessAs, legalDocument, address, status, createdAt
studio.lerian.organization.updated	lerian.streaming.ledger_organization.updated	An organization’s mutable fields change.	id, parentOrganizationId, legalName, doingBusinessAs, address, status, updatedAt
studio.lerian.organization.deleted	lerian.streaming.ledger_organization.deleted	An organization is deleted.	id, deletedAt

Ledger

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.ledger.created	lerian.streaming.ledger_ledger.created	A ledger is created within an organization.	id, organizationId, name, status, createdAt
studio.lerian.ledger.updated	lerian.streaming.ledger_ledger.updated	A ledger’s name or status changes.	id, organizationId, name, status, updatedAt
studio.lerian.ledger.deleted	lerian.streaming.ledger_ledger.deleted	A ledger is deleted.	id, organizationId, deletedAt

Account

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.account.created	lerian.streaming.ledger_account.created	An account is opened in a ledger.	id, organizationId, ledgerId, name, assetCode, type, alias, portfolioId, segmentId, status, createdAt
studio.lerian.account.updated	lerian.streaming.ledger_account.updated	An account’s mutable fields change.	id, organizationId, ledgerId, name, segmentId, entityId, status, blocked, updatedAt
studio.lerian.account.deleted	lerian.streaming.ledger_account.deleted	An account is deleted.	id, organizationId, ledgerId, portfolioId, deletedAt

Asset

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.asset.created	lerian.streaming.ledger_asset.created	An asset is registered in a ledger.	id, organizationId, ledgerId, name, type, code, status, createdAt
studio.lerian.asset.updated	lerian.streaming.ledger_asset.updated	An asset’s mutable fields change.	id, organizationId, ledgerId, name, type, code, status, updatedAt
studio.lerian.asset.deleted	lerian.streaming.ledger_asset.deleted	An asset is deleted.	id, organizationId, ledgerId, deletedAt

Portfolio

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.portfolio.created	lerian.streaming.ledger_portfolio.created	A portfolio is created.	id, organizationId, ledgerId, name, entityId, status, createdAt
studio.lerian.portfolio.updated	lerian.streaming.ledger_portfolio.updated	A portfolio’s mutable fields change.	id, organizationId, ledgerId, name, entityId, status, updatedAt
studio.lerian.portfolio.deleted	lerian.streaming.ledger_portfolio.deleted	A portfolio is deleted.	id, organizationId, ledgerId, deletedAt

Segment

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.segment.created	lerian.streaming.ledger_segment.created	A segment is created.	id, organizationId, ledgerId, name, status, createdAt
studio.lerian.segment.updated	lerian.streaming.ledger_segment.updated	A segment’s mutable fields change.	id, organizationId, ledgerId, name, status, updatedAt
studio.lerian.segment.deleted	lerian.streaming.ledger_segment.deleted	A segment is deleted.	id, organizationId, ledgerId, deletedAt

Operation route

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.operation-route.created	lerian.streaming.ledger_operation_route.created	An operation route is created.	id, organizationId, ledgerId, title, code, operationType, account, accountingEntries, createdAt
studio.lerian.operation-route.updated	lerian.streaming.ledger_operation_route.updated	An operation route’s mutable fields change.	id, organizationId, ledgerId, title, code, operationType, account, accountingEntries, updatedAt
studio.lerian.operation-route.deleted	lerian.streaming.ledger_operation_route.deleted	An operation route is deleted.	id, organizationId, ledgerId, deletedAt

Transaction route

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.transaction-route.created	lerian.streaming.ledger_transaction_route.created	A transaction route is created.	id, organizationId, ledgerId, title, operationRouteIds, createdAt
studio.lerian.transaction-route.updated	lerian.streaming.ledger_transaction_route.updated	A transaction route’s mutable fields change.	id, organizationId, ledgerId, title, operationRouteIds, updatedAt
studio.lerian.transaction-route.deleted	lerian.streaming.ledger_transaction_route.deleted	A transaction route is deleted.	id, organizationId, ledgerId, deletedAt

Balance

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.balance.created	lerian.streaming.ledger_balance.created	A balance is created during account setup.	id, organizationId, ledgerId, accountId, alias, key, assetCode, accountType, available, onHold, allowSending, allowReceiving, createdAt
studio.lerian.balance.changed	lerian.streaming.ledger_balance.changed	A committed transaction moves a balance — one event per balance-affecting operation; values reflect the state after the operation.	organizationId, ledgerId, accountId, balanceId, assetCode, available, onHold, version, reason, direction, amount, transactionId, operationId, occurredAt
studio.lerian.balance.config-changed	lerian.streaming.ledger_balance.config_changed	A balance’s settings change, or overdraft is enabled (companion balance materialized). changeType discriminates settings_updated from overdraft_enabled.	id, organizationId, ledgerId, accountId, allowSending, allowReceiving, direction, settings, changeType, updatedAt
studio.lerian.balance.deleted	lerian.streaming.ledger_balance.deleted	A balance is deleted.	id, organizationId, ledgerId, accountId, deletedAt
studio.lerian.balance.overdraft-drawn	lerian.streaming.ledger_balance.overdraft_drawn	A debit consumes overdraft beyond available funds (action = drawn).	balanceId, accountId, organizationId, ledgerId, assetCode, transactionId, operationId, action, amount, overdraftBalance, overdraftLimit, occurredAt
studio.lerian.balance.overdraft-repaid	lerian.streaming.ledger_balance.overdraft_repaid	Overdraft usage decreases but is not fully cleared (action = repaid).	balanceId, accountId, organizationId, ledgerId, assetCode, transactionId, operationId, action, amount, overdraftBalance, overdraftLimit, occurredAt
studio.lerian.balance.overdraft-cleared	lerian.streaming.ledger_balance.overdraft_cleared	Overdraft is fully repaid — terminal signal (action = cleared).	balanceId, accountId, organizationId, ledgerId, assetCode, transactionId, operationId, action, amount, overdraftBalance, overdraftLimit, occurredAt

Transaction

The four lifecycle events share one payload schema; optional fields fill in per flow — route and routeId when the transaction was routed, parentTransactionId only on reverted.

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.transaction.posted	lerian.streaming.ledger_transaction.posted	A newly created transaction is committed to storage with all its operations persisted (no parent).	id, organizationId, ledgerId, status, amount, assetCode, source, destination, route, operations, metadata, createdAt
studio.lerian.transaction.committed	lerian.streaming.ledger_transaction.committed	A pending transaction transitions from PENDING to APPROVED.	id, organizationId, ledgerId, status, amount, assetCode, source, destination, operations, metadata
studio.lerian.transaction.canceled	lerian.streaming.ledger_transaction.canceled	A pending transaction transitions from PENDING to CANCELED.	id, organizationId, ledgerId, status, amount, assetCode, source, destination, operations, metadata
studio.lerian.transaction.reverted	lerian.streaming.ledger_transaction.reverted	A revert flow creates a child transaction; parentTransactionId correlates it to the original.	id, parentTransactionId, organizationId, ledgerId, status, amount, assetCode, source, destination, operations, metadata

Fees events

Midaz’s Fees capability manages fee and billing packages and records when fees are applied to a transaction. Its events are emitted by the consolidated ledger service, so they share the ledger’s ce-source — but they keep their own topic segment, landing under lerian.streaming.fee_*. Fees resources carry the fee- domain prefix in their keys and ce-types; the topic fold strips that prefix before adding the fee_ service segment, so fee-packages lands on fee_packages — never fee_fee_packages — unlike CRM, whose resource names carry no domain prefix.

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.fee-packages.created	lerian.streaming.fee_packages.created	A fee package is created.	id, organizationId, ledgerId, segmentId, transactionRoute, enable, createdAt, updatedAt
studio.lerian.fee-packages.updated	lerian.streaming.fee_packages.updated	A fee package’s mutable fields change.	id, organizationId, ledgerId, segmentId, transactionRoute, enable, createdAt, updatedAt
studio.lerian.fee-packages.deleted	lerian.streaming.fee_packages.deleted	A fee package is deleted.	id, organizationId, ledgerId, deletedAt
studio.lerian.fee-billing-packages.created	lerian.streaming.fee_billing_packages.created	A billing package is created.	id, organizationId, ledgerId, type, pricingModel, countMode, enable, createdAt, updatedAt
studio.lerian.fee-billing-packages.updated	lerian.streaming.fee_billing_packages.updated	A billing package’s mutable fields change.	id, organizationId, ledgerId, type, pricingModel, countMode, enable, createdAt, updatedAt
studio.lerian.fee-billing-packages.deleted	lerian.streaming.fee_billing_packages.deleted	A billing package is deleted.	id, organizationId, ledgerId, deletedAt
studio.lerian.fee-charge.applied	lerian.streaming.fee_charge.applied	A fee package is applied to a committed transaction.	transactionId, organizationId, ledgerId, feePackageId, appliedAt

CRM events

Midaz’s CRM capability manages account holders and their instruments. Its events are emitted by the consolidated ledger service: they share the ledger’s ce-source but keep their own topic segment, landing under lerian.streaming.crm_*, and they follow the same envelope and versioning as every other Midaz event.

Holder

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.holder.created	lerian.streaming.crm_holder.created	A holder is created.	id, organizationId, type, externalId, createdAt
studio.lerian.holder.updated	lerian.streaming.crm_holder.updated	A holder’s mutable fields change.	id, organizationId, type, externalId, updatedAt
studio.lerian.holder.deleted	lerian.streaming.crm_holder.deleted	A holder is deleted.	id, organizationId, deletionType, deletedAt

Instrument

An instrument is a regulated entity, so document, banking details, and regulatory fields are PII and never cross the wire — only stable identifiers, the org/holder/ledger/account scope, the type classification, and a reduced related-party list (each entry carries just relatedPartyId and a non-PII role).

Event (ce-type)	Topic	Fires when	Key payload
studio.lerian.instrument.created	lerian.streaming.crm_instrument.created	An instrument is created for a holder and account.	id, holderId, organizationId, ledgerId, accountId, type, relatedParties, createdAt
studio.lerian.instrument.updated	lerian.streaming.crm_instrument.updated	An instrument’s mutable fields change.	id, holderId, organizationId, ledgerId, accountId, type, relatedParties, updatedAt
studio.lerian.instrument.deleted	lerian.streaming.crm_instrument.deleted	An instrument is deleted.	id, holderId, organizationId, deletionType, deletedAt
studio.lerian.instrument.related-party-deleted	lerian.streaming.crm_instrument.related_party_deleted	A single related party is removed from an instrument (ce-subject is the instrument id).	instrumentId, holderId, organizationId, relatedPartyId, deletedAt