What changed?
Why did it change?
Which business event caused it?
Which accounts were affected?
Was money conserved?
Can we replay it?
Can we explain it after six months?
Can an operator repair it without hiding history?

update merchant_balance
set balance = balance + 100000
where merchant_id = 'm_123';

Journal: capture-posted-for-payment-attempt-X
Entry 1: debit  Provider Receivable      100000 IDR
Entry 2: credit Merchant Pending Payable 100000 IDR

immutable data model
+ database constraints
+ posting transaction boundary
+ idempotency keys
+ account taxonomy
+ balance projections
+ integrity checks
+ operational repair workflow

A balance table may be wrong temporarily.
A posted balanced journal must never be wrong.

IDR 100,000.00 is stored as 10000000 if scale=2.
IDR 100,000 with zero decimal minor unit may be stored as 100000 if currency exponent=0.
USD 10.25 is stored as 1025 when exponent=2.

amount_minor bigint not null,
currency_code char(3) not null,
currency_exponent smallint not null

amount_minor bigint

amount numeric(38, 12)

entry_side varchar(6) not null check (entry_side in ('DEBIT', 'CREDIT')),
amount_minor bigint not null check (amount_minor > 0)

signed_amount_minor bigint not null

Do not encode a reversal by inserting a negative debit.
Encode it by posting the opposite side.

ASSET: Provider Receivable
ASSET: Bank Settlement Cash
ASSET: Processor Clearing Receivable
LIABILITY: Merchant Pending Payable
LIABILITY: Merchant Available Payable
LIABILITY: Merchant Payout Pending
LIABILITY: Customer Wallet Balance
LIABILITY: Chargeback Payable
REVENUE: Platform Processing Fee Revenue
EXPENSE: Scheme Fee Expense
CONTRA_REVENUE: Refund Fee Reversal
RESERVE: Merchant Reserve Held
SUSPENSE: Unmatched Provider Settlement

create table ledger_account (
    account_id uuid primary key,
    account_code varchar(120) not null,
    account_name varchar(240) not null,

    account_type varchar(32) not null check (
        account_type in (
            'ASSET',
            'LIABILITY',
            'REVENUE',
            'EXPENSE',
            'EQUITY',
            'SUSPENSE',
            'RESERVE',
            'CONTRA_REVENUE',
            'CONTRA_ASSET',
            'CONTRA_LIABILITY'
        )
    ),

    normal_side varchar(6) not null check (normal_side in ('DEBIT', 'CREDIT')),

    owner_type varchar(64) not null,
    owner_id varchar(120),

    currency_code char(3) not null,
    currency_exponent smallint not null,

    provider_code varchar(64),
    payment_method_type varchar(64),
    balance_bucket varchar(64),

    status varchar(32) not null check (status in ('ACTIVE', 'SUSPENDED', 'CLOSED')),

    metadata jsonb not null default '{}'::jsonb,

    created_at timestamptz not null default now(),
    updated_at timestamptz not null default now(),

    unique (account_code),
    unique (
        owner_type,
        owner_id,
        account_type,
        currency_code,
        provider_code,
        payment_method_type,
        balance_bucket
    )
);

How much USD wallet liability do we owe customer C?
How much IDR available payable do we owe merchant M?
How much IDR is pending settlement from provider P?
How much is held as reserve for merchant M?
How much settlement cash was received in bank account B?

PAYMENT_CAPTURE_POSTED
PAYMENT_SETTLEMENT_RECEIVED
MERCHANT_FEE_RECOGNIZED
REFUND_POSTED
CHARGEBACK_OPENED
CHARGEBACK_WON
CHARGEBACK_LOST
MERCHANT_PAYOUT_CREATED
MERCHANT_PAYOUT_SETTLED
MANUAL_ADJUSTMENT_POSTED

create table ledger_journal (
    journal_id uuid primary key,

    journal_type varchar(80) not null,
    journal_status varchar(32) not null check (
        journal_status in ('POSTED', 'VOIDED_BY_REVERSAL')
    ),

    source_type varchar(80) not null,
    source_id varchar(160) not null,
    source_event_id varchar(160),

    posting_rule_code varchar(120) not null,
    posting_rule_version integer not null,

    idempotency_key varchar(240) not null,

    business_date date not null,
    occurred_at timestamptz not null,
    posted_at timestamptz not null default now(),

    created_by_type varchar(64) not null check (
        created_by_type in ('SYSTEM', 'OPERATOR', 'MIGRATION', 'RECONCILIATION_JOB')
    ),
    created_by_id varchar(120),

    reversal_of_journal_id uuid references ledger_journal(journal_id),
    reason_code varchar(120),
    reason_text text,

    metadata jsonb not null default '{}'::jsonb,

    created_at timestamptz not null default now(),

    unique (idempotency_key),
    unique (source_type, source_id, posting_rule_code, source_event_id)
);

Provider settlement file arrives on 2026-07-02 01:10.
The settlement date inside the file is 2026-07-01.
The journal is posted_at = 2026-07-02T01:10.
The business_date = 2026-07-01.

create table ledger_entry (
    entry_id uuid primary key,
    journal_id uuid not null references ledger_journal(journal_id),
    account_id uuid not null references ledger_account(account_id),

    entry_side varchar(6) not null check (entry_side in ('DEBIT', 'CREDIT')),
    amount_minor bigint not null check (amount_minor > 0),
    currency_code char(3) not null,
    currency_exponent smallint not null,

    entry_sequence integer not null,

    counterparty_account_id uuid references ledger_account(account_id),

    source_line_id varchar(160),
    description text,
    metadata jsonb not null default '{}'::jsonb,

    created_at timestamptz not null default now(),

    unique (journal_id, entry_sequence)
);

create index idx_ledger_entry_account_time
on ledger_entry (account_id, created_at, entry_id);

create index idx_ledger_entry_journal
on ledger_entry (journal_id);

begin transaction
  validate command idempotency
  build journal lines
  assert per-currency debit total == credit total
  insert ledger_journal
  insert ledger_entry rows
  update account_balance projection
  insert outbox event
commit

public PostedJournal post(PostingCommand command) {
    return transactionTemplate.execute(tx -> {
        existingJournal(command.idempotencyKey()).ifPresent(j -> {
            return j;
        });

        PostingRule rule = postingRuleCatalog.resolve(
            command.ruleCode(),
            command.ruleVersion()
        );

        DraftJournal draft = rule.build(command);

        journalValidator.assertBalanced(draft);
        journalValidator.assertSingleCurrencyPerBalanceGroup(draft);
        journalValidator.assertAccountsActive(draft);
        journalValidator.assertNoNegativeLineAmount(draft);
        journalValidator.assertBusinessDateAllowed(draft);

        PostedJournal posted = ledgerRepository.insertJournalAndEntries(draft);
        balanceProjection.apply(posted);
        outbox.publish(LedgerEvents.journalPosted(posted));

        return posted;
    });
}

Debit  Provider Receivable  100 USD
Credit Merchant Payable     100 EUR

Debit  Provider Receivable USD      100 USD
Credit FX Clearing USD              100 USD
Debit  FX Clearing EUR               92 EUR
Credit Merchant Payable EUR          92 EUR

create or replace function prevent_ledger_update_delete()
returns trigger as $$
begin
    raise exception 'ledger rows are immutable; use reversal/correction journal';
end;
$$ language plpgsql;

create trigger trg_no_update_ledger_journal
before update or delete on ledger_journal
for each row execute function prevent_ledger_update_delete();

create trigger trg_no_update_ledger_entry
before update or delete on ledger_entry
for each row execute function prevent_ledger_update_delete();

Journal J1: Capture Posted
Debit  Provider Receivable        100000 IDR
Credit Merchant Pending Payable   100000 IDR

Journal J2: Capture Reversal
Debit  Merchant Pending Payable   100000 IDR
Credit Provider Receivable        100000 IDR
reversal_of_journal_id = J1

1. Reverse incorrect journal.
2. Post correct journal.

What is the current balance?

Why did the balance temporarily become wrong?
Who corrected it?
Which evidence supported the correction?
Was the correction approved?

create table posting_rule (
    posting_rule_id uuid primary key,
    rule_code varchar(120) not null,
    rule_version integer not null,
    description text not null,
    status varchar(32) not null check (status in ('DRAFT', 'ACTIVE', 'RETIRED')),

    source_event_type varchar(120) not null,
    expected_currency_mode varchar(32) not null check (
        expected_currency_mode in ('SINGLE_CURRENCY', 'MULTI_CURRENCY')
    ),

    rule_definition jsonb not null,

    effective_from timestamptz not null,
    effective_to timestamptz,

    created_at timestamptz not null default now(),
    created_by varchar(120) not null,

    unique (rule_code, rule_version)
);

{
  "lines": [
    {
      "side": "DEBIT",
      "accountSelector": "PROVIDER_RECEIVABLE",
      "amountExpression": "capture.grossAmount"
    },
    {
      "side": "CREDIT",
      "accountSelector": "MERCHANT_PENDING_PAYABLE",
      "amountExpression": "capture.grossAmount"
    }
  ]
}

public interface PostingRule {
    RuleCode code();
    int version();
    DraftJournal build(PostingContext context);
}

Every journal must say which posting rule version produced it.

AccountId merchantPendingPayable = accountResolver.resolve(
    AccountSelector.builder()
        .ownerType("MERCHANT")
        .ownerId(capture.merchantId())
        .accountType(AccountType.LIABILITY)
        .bucket("PENDING_PAYABLE")
        .currency(capture.currency())
        .providerCode(capture.providerCode())
        .build()
);

Credit merchant pending payable.

For merchant M, currency IDR, provider ADYEN, the account is A-123.

ledger:<posting-rule-code>:<source-type>:<source-id>:<source-event-id>

ledger:PAYMENT_CAPTURE_POSTED:payment_attempt:pa_123:provider_event_evt_777
ledger:REFUND_POSTED:refund:r_456:provider_refund_rf_888
ledger:SETTLEMENT_RECEIVED:settlement_line:sl_999:file_20260701_line_1002

create unique index uq_ledger_journal_idempotency
on ledger_journal (idempotency_key);

try {
    return ledgerRepository.insertJournalAndEntries(draft);
} catch (DuplicateKeyException duplicate) {
    return ledgerRepository.findByIdempotencyKey(draft.idempotencyKey())
        .orElseThrow(() -> duplicate);
}

create table account_balance (
    account_id uuid primary key references ledger_account(account_id),
    currency_code char(3) not null,
    currency_exponent smallint not null,

    debit_posted_minor bigint not null default 0,
    credit_posted_minor bigint not null default 0,
    normal_balance_minor bigint not null default 0,

    last_journal_id uuid,
    last_entry_id uuid,
    last_posted_at timestamptz,

    version bigint not null default 0,
    updated_at timestamptz not null default now(),

    check (debit_posted_minor >= 0),
    check (credit_posted_minor >= 0)
);

Asset and expense accounts normally increase with debit.
Liability, revenue, and equity accounts normally increase with credit.

long signedNormalDelta(Account account, LedgerEntry entry) {
    boolean entryIncreasesNormalBalance = account.normalSide() == entry.side();
    return entryIncreasesNormalBalance
        ? entry.amountMinor()
        : -entry.amountMinor();
}

update account_balance
set
    debit_posted_minor = debit_posted_minor + :debit_delta,
    credit_posted_minor = credit_posted_minor + :credit_delta,
    normal_balance_minor = normal_balance_minor + :normal_delta,
    last_journal_id = :journal_id,
    last_entry_id = :entry_id,
    last_posted_at = :posted_at,
    version = version + 1,
    updated_at = now()
where account_id = :account_id;

insert journal
insert entries
update account_balance
commit

insert journal
insert entries
insert outbox event
commit

create table account_balance_snapshot (
    snapshot_id uuid primary key,
    account_id uuid not null references ledger_account(account_id),
    currency_code char(3) not null,
    currency_exponent smallint not null,

    as_of_business_date date not null,
    as_of_posted_at timestamptz not null,
    as_of_entry_id uuid,

    debit_posted_minor bigint not null,
    credit_posted_minor bigint not null,
    normal_balance_minor bigint not null,

    entry_count bigint not null,
    snapshot_reason varchar(80) not null check (
        snapshot_reason in ('DAILY_CLOSE', 'MONTHLY_CLOSE', 'REBUILD', 'MIGRATION', 'AUDIT')
    ),

    created_at timestamptz not null default now(),
    created_by varchar(120) not null,

    unique (account_id, as_of_business_date, snapshot_reason)
);

select
    currency_code,
    sum(case when entry_side = 'DEBIT' then amount_minor else 0 end) as debit_total,
    sum(case when entry_side = 'CREDIT' then amount_minor else 0 end) as credit_total
from ledger_entry
where created_at < :as_of
 group by currency_code
having sum(case when entry_side = 'DEBIT' then amount_minor else 0 end)
    <> sum(case when entry_side = 'CREDIT' then amount_minor else 0 end);

select
    journal_id,
    currency_code,
    sum(case when entry_side = 'DEBIT' then amount_minor else 0 end) as debit_total,
    sum(case when entry_side = 'CREDIT' then amount_minor else 0 end) as credit_total
from ledger_entry
group by journal_id, currency_code
having sum(case when entry_side = 'DEBIT' then amount_minor else 0 end)
    <> sum(case when entry_side = 'CREDIT' then amount_minor else 0 end);

create table ledger_integrity_check (
    check_id uuid primary key,
    check_type varchar(80) not null,
    scope_type varchar(80) not null,
    scope_id varchar(160),
    status varchar(32) not null check (status in ('PASSED', 'FAILED')),
    checked_from timestamptz,
    checked_to timestamptz,
    finding_count integer not null,
    findings jsonb not null default '[]'::jsonb,
    created_at timestamptz not null default now(),
    created_by varchar(120) not null
);

select j.journal_id
from ledger_journal j
left join ledger_entry e on e.journal_id = j.journal_id
group by j.journal_id
having count(e.entry_id) < 2;

alter table ledger_journal
add column previous_journal_hash text,
add column journal_hash text;

journal_id
journal_type
source_type
source_id
posted_at
ordered entry lines
previous_journal_hash

ledger_journal: partition by posted_at or business_date
ledger_entry: partition aligned with journal posted_at/business_date
account_balance: not partitioned initially, indexed by account_id
snapshots: partition by as_of_business_date

Find journal by idempotency key.
Find journals for payment attempt.
Find entries for account between dates.
Find all journals from settlement file.
Find all entries affecting merchant payable.
Find balance by account.
Find reversal of journal.
Find journals posted by an operator.

create unique index uq_ledger_journal_idempotency
on ledger_journal (idempotency_key);

create index idx_ledger_journal_source
on ledger_journal (source_type, source_id);

create index idx_ledger_journal_source_event
on ledger_journal (source_event_id)
where source_event_id is not null;

create index idx_ledger_journal_business_date
on ledger_journal (business_date, journal_type);

create index idx_ledger_journal_reversal
on ledger_journal (reversal_of_journal_id)
where reversal_of_journal_id is not null;

create index idx_ledger_entry_account_created
on ledger_entry (account_id, created_at, entry_id);

create index idx_ledger_entry_account_journal
on ledger_entry (account_id, journal_id);

create table ledger_outbox (
    outbox_id uuid primary key,
    aggregate_type varchar(80) not null,
    aggregate_id varchar(160) not null,
    event_type varchar(120) not null,
    event_version integer not null,
    event_key varchar(160) not null,
    payload jsonb not null,
    status varchar(32) not null check (status in ('NEW', 'PUBLISHING', 'PUBLISHED', 'FAILED')),
    attempt_count integer not null default 0,
    next_attempt_at timestamptz not null default now(),
    created_at timestamptz not null default now(),
    published_at timestamptz
);

create table ledger_adjustment_request (
    adjustment_request_id uuid primary key,
    requested_by varchar(120) not null,
    request_status varchar(32) not null check (
        request_status in ('DRAFT', 'PENDING_APPROVAL', 'APPROVED', 'REJECTED', 'POSTED', 'CANCELLED')
    ),
    reason_code varchar(120) not null,
    reason_text text not null,
    evidence_uri text,
    risk_level varchar(32) not null check (risk_level in ('LOW', 'MEDIUM', 'HIGH', 'CRITICAL')),
    created_at timestamptz not null default now(),
    approved_by varchar(120),
    approved_at timestamptz,
    posted_journal_id uuid references ledger_journal(journal_id)
);

Never change what an old journal meant.
Add a new rule version.

com.company.payment.ledger
  api
    LedgerPostingService.java
    LedgerQueryService.java
  domain
    LedgerAccount.java
    LedgerJournal.java
    LedgerEntry.java
    PostingRule.java
    DraftJournal.java
    PostedJournal.java
    AccountSelector.java
    MoneyAmount.java
  application
    DefaultLedgerPostingService.java
    PostingRuleCatalog.java
    AccountResolver.java
    JournalValidator.java
    BalanceProjectionService.java
  infrastructure
    JdbcLedgerRepository.java
    JdbcAccountRepository.java
    LedgerOutboxRepository.java
  integrity
    TrialBalanceJob.java
    JournalBalanceCheck.java
    ProjectionRebuildJob.java

Payment Core may request a posting.
Payment Core may not insert ledger entries directly.

public interface LedgerPostingService {
    PostedJournal post(PostingCommand command);
}

public record PostingCommand(
    String idempotencyKey,
    String sourceType,
    String sourceId,
    String sourceEventId,
    String postingRuleCode,
    int postingRuleVersion,
    LocalDate businessDate,
    Instant occurredAt,
    Actor actor,
    Map<String, Object> facts
) {}

public record CapturePostedCommand(
    PaymentAttemptId attemptId,
    ProviderEventId providerEventId,
    MerchantId merchantId,
    ProviderCode providerCode,
    MoneyAmount grossAmount,
    Instant capturedAt
) {}

merchant_balance(balance)

payment_ledger(payment_id, amount, fee, status)

update ledger_entry set amount = ...

Debit USD, Credit EUR, pretend they offset.

insert into ledger_entry ...

if (payment.status == SUCCESS) {
    // insert debit/credit here
}

sum(debits) == sum(credits) per currency
projection == sum(entries)
reversal returns balance to original value
idempotent replay does not change balance

projection.normal_balance_minor == reconstructed.normal_balance_minor

business event
-> posting rule
-> balanced draft journal
-> immutable posted journal
-> immutable entries
-> derived balance projection
-> integrity checks
-> explainable reports

Can we just update the balance?

No. We post a journal that explains why the balance changed.