Ledger Event Handlers

Overview of ledger event handlers.


This is an Early Access feature.

Features in early access may undergo changes in the future. Reach out to your customer success manager or support team in case of any questions.


Ledger Event Handlers introduce an abstraction / templating layer on top of Ledgers. This allows customers to configure common ledgering patterns as templates called ledger event handlers. When transactions occur, they can be ledgered by simply triggering these templates, without having to specify the underlying double-entry transactions.

Handlers have two main components, a ledgerable event and the handler itself.

  • The Ledgerable Event represents a simple business event (such as interest accrual, billing customers, etc.) and includes all the context needed to create a ledger transaction. The minimum required fields are only the name of the event.
  • The Ledger Event Handler orchestrates the interpretation of the event into a double entry ledger transaction. Constants or fields from the ledgerable event may be pulled into the ledger transaction creation.


Customers usually want accounting to be abstracted away from the API users of the ledger. Their internal teams that are building new payment rails and services should not have to understand accounting in order to pass transaction records to the ledger.

As a payment service, I want to be able to log “User X made a $100 deposit” rather than “Write a ledger transaction crediting $100 to LA 123 (User X wallet) and debiting $100 to LA 111 (Cash)”.

Customers want the ability to pass their ledgering service raw payment events which are then translated into Ledger Transactions and Ledger Entries according to a set of event handlers. This version of rules would allow simple math to be used to convert input amounts into resulting debit and credit entries.

Being able to pass simpler payment records to the ledger also makes it significantly easier to log payments made in external services directly to the ledger.

Use Cases

  • For wallet use cases, ledgering infrastructure teams can define event handlers such as withdrawals, deposits, and P2P payments. In day-to-day transactions, a user depositing funds can be passed as a raw event to the ledger.
  • For marketplace use cases, event handlers for common transactions and accounting allocations can be defined.
  • For lending and card use cases, event handlers for repayments and authorizations can be defined.
  • For multi-currency use cases, exchange rate fields may be passed in on the raw event to the ledger.