Transactions

A transaction moves money between accounts. It is made of postings, and Ledgr requires that within a transaction the debits equal the credits before it will accept it. That single rule is what keeps a ledger trustworthy: money always comes from somewhere and goes somewhere, so the books cannot drift, lose value, or invent it.

Postings are permanent. Ledgr never edits or deletes one. When you need to undo or amend something, you write a new posting that offsets it, so the complete history of what happened stays intact and can be audited later. All transaction endpoints require the program_id header.

Debits and credits

A debit lowers an account's balance and a credit raises it. In a simple transfer the payer is debited and the payee is credited for the same amount, and the two sides cancel out. A transaction can also have more than two sides. A single settlement might credit a merchant, credit a fee account, and debit a customer, all in one balanced entry, as long as the debits and credits still sum to the same total.

The lifecycle of a transaction

Status	Meaning
pending	Recorded but not settled. It reserves the payer's funds in the pending balance.
posted	Settled. The money has moved in the posted balance.
reversed	Previously settled, then undone by an equal and opposite entry.
failed, canceled	Ended without settling.
disputed	Marked as disputed.

You can post a transaction immediately, or record it as pending and settle it later once you are sure it should go through. Ledgr enforces which changes are allowed: an attempt to make an illegal change, such as reversing a transaction that has not settled, is rejected with 409 conflict.

Operations

Method and path	What it does
POST /transaction	Create a transaction, either as a simple transfer or as a multi-account entry.
PUT /transaction	Move a transaction to a new status.
GET /transactions	List transactions in the program, with filters.
GET /transaction	Retrieve a single side of a transaction.
GET /transaction/group	The full detail of one transaction: its sides, its postings, and its history.
GET /journal	The program's complete record of postings, newest first.

The API reference documents the parameters and responses for each of these. See Webhooks to be notified as transactions are created, settle, or reverse.