مهندسی سیستم‌های بانکی و پرداختEngineering Banking & Payment Systems

Read enough job postings from banks, fintechs, PSPs and payment-infrastructure companies and a pattern jumps out: Java and Spring are treated as the baseline, and what they are actually hunting for is domain knowledge. Phrases like "familiarity with double-entry bookkeeping", "experience with ISO 8583", "reconciliation", "settlement", "idempotency in financial transactions". These are not buzzwords. They are a coherent body of knowledge that nobody taught you at university and that almost no Java course covers.

The good news is that this knowledge is learnable and it is not that large. The bad news is that without it you are exposed in the first fifteen minutes of an interview, because the screening questions in this domain are brutally simple: "Why don't you use double for money?", "You got a timeout and you don't know whether the money moved — now what?", "Where do you store the account balance?".

This chapter starts from zero. I assume you have never worked in finance and do not know what "debit" and "credit" mean. By the end you should be able to design a payment service with a correct ledger, an idempotent API boundary and a reconciliation job — and defend it in an interview.

Some topics are deliberately not re-taught here because they have their own chapters: the Saga and Transactional Outbox patterns and CQRS live in the microservices data chapter, HSM cryptography and key lifecycle detail live in the key-management chapter, transactions and ACID live in the ACID chapter, and WSDL/SOAP lives in the SOAP and SOA chapter. I reference them and focus on what exists nowhere else: the money domain.

1. The money model: the first place engineers die

1.1 Why double is banned for money

Here is what that looks like in practice:

public class WhyNotDouble {
    public static void main(String[] args) {
        System.out.println(0.1 + 0.2);            // 0.30000000000000004
        System.out.println(1.03 - 0.42);          // 0.6100000000000001
        System.out.println(0.1 + 0.1 + 0.1 == 0.3); // false

        double balance = 0.0;
        for (int i = 0; i < 10_000; i++) balance += 0.01;
        System.out.println(balance);              // 100.00000000000163
    }
}

That extra 0.00000000000163 looks harmless. It is not. In a banking system it means:

• The trial balance does not come to zero and the accounting day cannot be closed.
• The sum of line items does not match the statement total and automated reconciliation fails.
• if (balance == 0) is never true and a zeroed account is never closed.

1.2 BigDecimal — but with explicit scale and RoundingMode

BigDecimal stores a number as a big integer (unscaledValue) plus a scale (the number of decimal digits). So 12.34 is unscaledValue = 1234, scale = 2. Because the base is ten, 0.1 is exactly 0.1.

Three rules, without which BigDecimal will betray you too:

Rule one: never use the BigDecimal(double) constructor.

new BigDecimal(0.1);
// 0.1000000000000000055511151231257827021181583404541015625
new BigDecimal("0.1");          // 0.1  ✅
BigDecimal.valueOf(0.1);        // 0.1  (goes through Double.toString)

The double constructor faithfully translates the approximate binary value into decimal, so it preserves the garbage. Always use the String constructor or valueOf.

Rule two: every divide without a RoundingMode is a latent ArithmeticException.

BigDecimal one = new BigDecimal("1");
BigDecimal three = new BigDecimal("3");
one.divide(three);
// ArithmeticException: Non-terminating decimal expansion; no exact representable decimal result.
one.divide(three, 2, RoundingMode.HALF_UP);   // 0.33  ✅

Rule three: do not confuse equals with compareTo.

new BigDecimal("1.0").equals(new BigDecimal("1.00"));      // false — different scale
new BigDecimal("1.0").compareTo(new BigDecimal("1.00"));   // 0  ✅ equal in value

This one bites in Set<BigDecimal>, in Map keys, and in assertEquals tests. For value comparison always use compareTo(...) == 0.

1.3 Minor units and integer amounts

Every currency has a minor unit: the smallest tradeable denomination. For the dollar it is the cent, one hundredth. The ISO 4217 standard defines an exponent per currency:

So a 100 in a payment message means one hundred yen in JPY, one dollar in USD, and 0.1 dinar in KWD. Hard-code "always divide by 100" and your system is wrong in Japan and Kuwait.

In Java, get this from the JDK, not from a hand-maintained table:

import java.util.Currency;

Currency jpy = Currency.getInstance("JPY");
jpy.getDefaultFractionDigits();   // 0
jpy.getNumericCode();             // 392  (the ISO 4217 numeric code — the one that goes into ISO 8583)

Currency kwd = Currency.getInstance("KWD");
kwd.getDefaultFractionDigits();   // 3

There are two schools for representing an amount in code:

(a) long of minor units. The amount is always an integer: 12345 cents is 123.45 dollars. Addition and subtraction are fast and exact, comparison is trivial, JSON serialisation is safe. The downside is that the number is meaningless without a currency travelling alongside it, and percentages and rates still need exact arithmetic.

(b) BigDecimal + Currency. More readable, maps straight onto a numeric column, percentages are natural. The downside is relative slowness and the risk of forgetting scale.

In practice the best answer combines both: a value object called Money that knows both representations and keeps every rule inside itself.

package com.example.payments.money;

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.Currency;
import java.util.Objects;

/** An immutable amount that knows its own currency and scale. */
public final class Money implements Comparable<Money> {

    private final BigDecimal amount;   // always scaled to the currency's minor unit
    private final Currency currency;

    private Money(BigDecimal amount, Currency currency) {
        this.currency = Objects.requireNonNull(currency, "currency");
        int scale = currency.getDefaultFractionDigits();
        if (scale < 0) throw new IllegalArgumentException("non-decimal currency: " + currency);
        // UNNECESSARY means: if the input carried extra digits, do not stay silent — blow up
        this.amount = amount.setScale(scale, RoundingMode.UNNECESSARY);
    }

    public static Money of(String amount, String currencyCode) {
        return new Money(new BigDecimal(amount), Currency.getInstance(currencyCode));
    }

    /** Builds from minor units — ofMinor(12345, "USD") is 123.45 USD */
    public static Money ofMinor(long minorUnits, String currencyCode) {
        Currency c = Currency.getInstance(currencyCode);
        return new Money(BigDecimal.valueOf(minorUnits, c.getDefaultFractionDigits()), c);
    }

    public static Money zero(String currencyCode) {
        return ofMinor(0L, currencyCode);
    }

    public long toMinorUnits() {
        return amount.movePointRight(currency.getDefaultFractionDigits()).longValueExact();
    }

    public Money plus(Money other) {
        requireSameCurrency(other);
        return new Money(this.amount.add(other.amount), currency);
    }

    public Money minus(Money other) {
        requireSameCurrency(other);
        return new Money(this.amount.subtract(other.amount), currency);
    }

    public Money negated() {
        return new Money(this.amount.negate(), currency);
    }

    /** Multiply by a rate (a fee, say) — rounding here is mandatory and explicit. */
    public Money multipliedBy(BigDecimal rate, RoundingMode rounding) {
        BigDecimal raw = this.amount.multiply(rate);
        return new Money(raw.setScale(currency.getDefaultFractionDigits(), rounding), currency);
    }

    public boolean isNegative()  { return amount.signum() < 0; }
    public boolean isZero()      { return amount.signum() == 0; }
    public BigDecimal amount()   { return amount; }
    public Currency currency()   { return currency; }

    private void requireSameCurrency(Money other) {
        if (!currency.equals(other.currency)) {
            throw new IllegalArgumentException(
                "currency mismatch: " + currency + " vs " + other.currency);
        }
    }

    @Override public int compareTo(Money o) { requireSameCurrency(o); return amount.compareTo(o.amount); }

    @Override public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Money m)) return false;
        return currency.equals(m.currency) && amount.compareTo(m.amount) == 0;
    }

    @Override public int hashCode() { return Objects.hash(amount.stripTrailingZeros(), currency); }

    @Override public String toString() { return amount.toPlainString() + " " + currency.getCurrencyCode(); }
}

1.4 Splitting an amount and distributing the remainder — the "missing cent" problem

Suppose 100.00 dollars must be split equally between three beneficiaries. Each gets 33.333.... Naively rounding to 33.33 gives a total of 99.99 — one cent has vanished, and that cent breaks your ledger's balance.

The standard algorithm: convert to minor units as an integer, do integer division, and hand out the remainder one unit at a time.

package com.example.payments.money;

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.ArrayList;
import java.util.List;

public final class Allocator {

    /** Even split into n parts — the output sums exactly to the input. */
    public static List<Money> allocateEvenly(Money total, int parts) {
        if (parts <= 0) throw new IllegalArgumentException("parts must be > 0");
        long minor = total.toMinorUnits();
        long base = minor / parts;
        long remainder = Math.abs(minor % parts);
        long step = minor < 0 ? -1 : 1;

        List<Money> out = new ArrayList<>(parts);
        for (int i = 0; i < parts; i++) {
            long v = base + (i < remainder ? step : 0);
            out.add(Money.ofMinor(v, total.currency().getCurrencyCode()));
        }
        return out;
    }

    /** Split proportionally to weights — the largest-remainder method. */
    public static List<Money> allocateByRatios(Money total, List<BigDecimal> weights) {
        BigDecimal sumW = weights.stream().reduce(BigDecimal.ZERO, BigDecimal::add);
        if (sumW.signum() == 0) throw new IllegalArgumentException("weights sum to zero");

        long minor = total.toMinorUnits();
        long[] floors = new long[weights.size()];
        BigDecimal[] fracs = new BigDecimal[weights.size()];
        long assigned = 0;

        for (int i = 0; i < weights.size(); i++) {
            BigDecimal exact = BigDecimal.valueOf(minor)
                    .multiply(weights.get(i))
                    .divide(sumW, 10, RoundingMode.HALF_UP);
            floors[i] = exact.setScale(0, RoundingMode.FLOOR).longValueExact();
            fracs[i] = exact.subtract(BigDecimal.valueOf(floors[i]));
            assigned += floors[i];
        }

        long remainder = minor - assigned;   // always between 0 and n-1

        // Give the remainder to the largest fractional parts — deterministic and auditable
        List<Integer> order = new ArrayList<>();
        for (int i = 0; i < weights.size(); i++) order.add(i);
        order.sort((a, b) -> fracs[b].compareTo(fracs[a]));

        for (int k = 0; k < remainder; k++) floors[order.get(k)] += 1;

        List<Money> out = new ArrayList<>(weights.size());
        String cc = total.currency().getCurrencyCode();
        for (long f : floors) out.add(Money.ofMinor(f, cc));
        return out;
    }
}

1.5 Storing money in a database

Never FLOAT, REAL, DOUBLE PRECISION or BINARY_DOUBLE. The correct type is exact decimal with explicit precision and scale.

-- Postgres: numeric(p,s) is exact and round-trips a BigDecimal faithfully
CREATE TABLE ledger_entry (
    id            bigserial     PRIMARY KEY,
    account_id    bigint        NOT NULL,
    -- 4 decimals leaves room for 3-decimal currencies and for rates
    amount        numeric(20,4) NOT NULL,
    currency      char(3)       NOT NULL,
    direction     char(1)       NOT NULL CHECK (direction IN ('D','C')),
    posted_at     timestamptz   NOT NULL DEFAULT now(),
    CONSTRAINT amount_positive CHECK (amount > 0)
);

-- Oracle: NUMBER(p,s) is exact. Never use BINARY_DOUBLE for money
CREATE TABLE ledger_entry (
    id            NUMBER(19)    GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    account_id    NUMBER(19)    NOT NULL,
    amount        NUMBER(20,4)  NOT NULL,
    currency      CHAR(3)       NOT NULL,
    direction     CHAR(1)       NOT NULL CHECK (direction IN ('D','C')),
    posted_at     TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL,
    CONSTRAINT amount_positive CHECK (amount > 0)
);

If you chose the long minor-units school, make the column bigint/NUMBER(19) and always keep the currency next to it, otherwise the number is meaningless.

CREATE TABLE payment (
    id             bigserial PRIMARY KEY,
    amount_minor   bigint    NOT NULL CHECK (amount_minor > 0),
    currency       char(3)   NOT NULL,
    -- store the exponent too, so reading historical rows does not depend on today's currency table
    currency_exp   smallint  NOT NULL CHECK (currency_exp BETWEEN 0 AND 4)
);

CREATE TABLE payment (
    id             NUMBER(19) GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    amount_minor   NUMBER(19) NOT NULL CHECK (amount_minor > 0),
    currency       CHAR(3)    NOT NULL,
    currency_exp   NUMBER(1)  NOT NULL CHECK (currency_exp BETWEEN 0 AND 4)
);

2. Double-entry bookkeeping: the heart of every financial system

This is the most important section of the chapter. If you take one thing away, take this.

2.1 The analogy: two columns instead of one number

2.2 Vocabulary: account, debit, credit

Account: a bucket. A named container that money accumulates in. Accounts fall into five families:

Debit (Dr) and credit (Cr): in accounting these words do not mean "decrease" and "increase". They are simply two sides: left and right. Their effect depends on the account type:

• On asset and expense accounts: a debit increases, a credit decreases.
• On liability, equity and revenue accounts: a credit increases, a debit decreases.

Journal entry: one complete financial event. It consists of two or more lines (postings), and the iron rule is:

Sum of debits in an entry = sum of credits in that entry

If that does not hold, the entry is invalid and must not be posted.

Ledger (general ledger): the collection of all entries. In modern systems it is an append-only table.

Trial balance: the sum of all debits against the sum of all credits across the whole ledger. If they differ, the system is broken.

The diagram below shows the model. مدل داده‌ی دفتر کل دوطرفه · The double-entry ledger data model

flowchart TD
    T[Business event<br/>payment, refund, fee] --> J[Journal entry<br/>immutable, has entry_id]
    J --> L1[Line 1 DEBIT<br/>account A, amount]
    J --> L2[Line 2 CREDIT<br/>account B, amount]
    J --> L3[Line n more lines...]
    L1 --> A[(Account A)]
    L2 --> B[(Account B)]
    A --> BAL[Balance = SUM debits - SUM credits<br/>derived, never stored raw]
    B --> BAL
    J -.invariant.-> INV[SUM debits == SUM credits<br/>per entry]

2.3 The relational ledger schema

CREATE TABLE account (
    id            bigserial    PRIMARY KEY,
    code          text         NOT NULL UNIQUE,          -- 'wallet:user:1042'
    type          text         NOT NULL CHECK (type IN ('ASSET','LIABILITY','EQUITY','REVENUE','EXPENSE')),
    currency      char(3)      NOT NULL,
    opened_at     timestamptz  NOT NULL DEFAULT now(),
    closed_at     timestamptz
);

CREATE TABLE journal_entry (
    id            bigserial    PRIMARY KEY,
    external_ref  text         NOT NULL,                 -- the business event identifier
    description   text         NOT NULL,
    posted_at     timestamptz  NOT NULL DEFAULT now(),   -- when it hit the system
    value_date    date         NOT NULL,                 -- the accounting value date
    created_by    text         NOT NULL,
    CONSTRAINT journal_entry_ref_uniq UNIQUE (external_ref)
);

CREATE TABLE journal_line (
    id            bigserial    PRIMARY KEY,
    entry_id      bigint       NOT NULL REFERENCES journal_entry(id),
    account_id    bigint       NOT NULL REFERENCES account(id),
    direction     char(1)      NOT NULL CHECK (direction IN ('D','C')),
    amount        numeric(20,4) NOT NULL CHECK (amount > 0),
    currency      char(3)      NOT NULL
);

CREATE INDEX journal_line_account_idx ON journal_line (account_id, entry_id);

-- Nobody gets UPDATE or DELETE — INSERT only
REVOKE UPDATE, DELETE ON journal_entry, journal_line FROM PUBLIC;

CREATE TABLE account (
    id            NUMBER(19)   GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    code          VARCHAR2(100) NOT NULL UNIQUE,
    type          VARCHAR2(10) NOT NULL CHECK (type IN ('ASSET','LIABILITY','EQUITY','REVENUE','EXPENSE')),
    currency      CHAR(3)      NOT NULL,
    opened_at     TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL,
    closed_at     TIMESTAMP WITH TIME ZONE
);

CREATE TABLE journal_entry (
    id            NUMBER(19)   GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    external_ref  VARCHAR2(200) NOT NULL,
    description   VARCHAR2(400) NOT NULL,
    posted_at     TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL,
    value_date    DATE         NOT NULL,
    created_by    VARCHAR2(100) NOT NULL,
    CONSTRAINT journal_entry_ref_uniq UNIQUE (external_ref)
);

CREATE TABLE journal_line (
    id            NUMBER(19)   GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    entry_id      NUMBER(19)   NOT NULL REFERENCES journal_entry(id),
    account_id    NUMBER(19)   NOT NULL REFERENCES account(id),
    direction     CHAR(1)      NOT NULL CHECK (direction IN ('D','C')),
    amount        NUMBER(20,4) NOT NULL CHECK (amount > 0),
    currency      CHAR(3)      NOT NULL
);

CREATE INDEX journal_line_account_idx ON journal_line (account_id, entry_id);

-- In Oracle you typically gate access through roles and packages
REVOKE UPDATE, DELETE ON journal_line FROM app_writer;

Enforce the per-entry balance at the database level, not only in Java:

CREATE OR REPLACE FUNCTION assert_entry_balanced() RETURNS trigger AS $$
DECLARE d numeric(20,4); c numeric(20,4);
BEGIN
    SELECT COALESCE(SUM(amount) FILTER (WHERE direction = 'D'), 0),
           COALESCE(SUM(amount) FILTER (WHERE direction = 'C'), 0)
      INTO d, c
      FROM journal_line WHERE entry_id = NEW.entry_id;
    IF d <> c THEN
        RAISE EXCEPTION 'entry % unbalanced: debits=% credits=%', NEW.entry_id, d, c;
    END IF;
    RETURN NULL;
END $$ LANGUAGE plpgsql;

CREATE CONSTRAINT TRIGGER journal_line_balanced
    AFTER INSERT ON journal_line
    DEFERRABLE INITIALLY DEFERRED
    FOR EACH ROW EXECUTE FUNCTION assert_entry_balanced();

-- Oracle has no deferrable trigger; the equivalent pattern is an end-of-entry check in a procedure
CREATE OR REPLACE PROCEDURE assert_entry_balanced(p_entry_id IN NUMBER) IS
    v_d NUMBER(20,4); v_c NUMBER(20,4);
BEGIN
    SELECT NVL(SUM(CASE WHEN direction = 'D' THEN amount END), 0),
           NVL(SUM(CASE WHEN direction = 'C' THEN amount END), 0)
      INTO v_d, v_c
      FROM journal_line WHERE entry_id = p_entry_id;
    IF v_d <> v_c THEN
        RAISE_APPLICATION_ERROR(-20001,
            'entry ' || p_entry_id || ' unbalanced: D=' || v_d || ' C=' || v_c);
    END IF;
END;
/

2.4 Why a mutable balance column is a bug waiting to happen

Suppose the account table has a balance numeric(20,4) column that every transaction UPDATEs. Four disasters await:

1. Lost update. Two concurrent transactions read the balance as 100, one subtracts 10 and the other 20, both write; the result is 80 or 90 instead of 70. Money was created out of thin air.
2. No history. The column only knows "now". If someone asks "what was this account's balance at the end of last month?", you have no answer.
3. Not auditable. One wrong UPDATE destroys the previous state forever. The auditor asks "where did this number come from?" and you have nothing.
4. Silent drift. The day a bug posts a ledger line without updating the balance (or vice versa), your two sources of truth diverge and nobody notices for months.

2.5 Three safe ways to derive a balance

Option one: full ledger sum. The most correct, but slow across millions of rows.

SELECT COALESCE(SUM(CASE WHEN direction = 'D' THEN amount ELSE -amount END), 0) AS balance
FROM journal_line
WHERE account_id = :accountId;

SELECT NVL(SUM(CASE WHEN direction = 'D' THEN amount ELSE -amount END), 0) AS balance
FROM journal_line
WHERE account_id = :accountId;

Option two: a running balance on every line. At insert time you also write the balance after that line. Reading the balance becomes "the last row". Excellent for statements, because every line displays the balance at its own moment. The cost is that inserts on a given account must be serialised (otherwise two lines carry the same running balance) — that is, one lock per account.

Option three: periodic snapshots. Every night (or every N lines) you record the balance in account_balance_snapshot. The live balance is the last snapshot plus the sum of lines after it.

CREATE TABLE account_balance_snapshot (
    account_id     bigint        NOT NULL,
    as_of_entry_id bigint        NOT NULL,     -- computed up to and including this entry
    balance        numeric(20,4) NOT NULL,
    taken_at       timestamptz   NOT NULL DEFAULT now(),
    PRIMARY KEY (account_id, as_of_entry_id)
);

WITH snap AS (
    SELECT balance, as_of_entry_id
    FROM account_balance_snapshot
    WHERE account_id = :accountId
    ORDER BY as_of_entry_id DESC
    LIMIT 1
)
SELECT COALESCE((SELECT balance FROM snap), 0)
     + COALESCE(SUM(CASE WHEN l.direction = 'D' THEN l.amount ELSE -l.amount END), 0) AS balance
FROM journal_line l
WHERE l.account_id = :accountId
  AND l.entry_id > COALESCE((SELECT as_of_entry_id FROM snap), 0);

CREATE TABLE account_balance_snapshot (
    account_id     NUMBER(19)   NOT NULL,
    as_of_entry_id NUMBER(19)   NOT NULL,
    balance        NUMBER(20,4) NOT NULL,
    taken_at       TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL,
    PRIMARY KEY (account_id, as_of_entry_id)
);

WITH snap AS (
    SELECT balance, as_of_entry_id
    FROM account_balance_snapshot
    WHERE account_id = :accountId
    ORDER BY as_of_entry_id DESC
    FETCH FIRST 1 ROW ONLY
)
SELECT NVL((SELECT balance FROM snap), 0)
     + NVL(SUM(CASE WHEN l.direction = 'D' THEN l.amount ELSE -l.amount END), 0) AS balance
FROM journal_line l
WHERE l.account_id = :accountId
  AND l.entry_id > NVL((SELECT as_of_entry_id FROM snap), 0);

If your project is event-sourced, this is exactly a projection: the ledger is the event stream and the balance is a rebuildable read model. CQRS and projection detail live in the microservices data chapter — here just note that the ledger model is naturally event-sourced, because a ledger line is an immutable event.

2.6 The trial balance: your daily health check

SELECT currency,
       SUM(CASE WHEN direction = 'D' THEN amount ELSE 0 END) AS total_debits,
       SUM(CASE WHEN direction = 'C' THEN amount ELSE 0 END) AS total_credits,
       SUM(CASE WHEN direction = 'D' THEN amount ELSE -amount END) AS difference
FROM journal_line
GROUP BY currency
HAVING SUM(CASE WHEN direction = 'D' THEN amount ELSE -amount END) <> 0;

SELECT currency,
       SUM(CASE WHEN direction = 'D' THEN amount ELSE 0 END) AS total_debits,
       SUM(CASE WHEN direction = 'C' THEN amount ELSE 0 END) AS total_credits,
       SUM(CASE WHEN direction = 'D' THEN amount ELSE -amount END) AS difference
FROM journal_line
GROUP BY currency
HAVING SUM(CASE WHEN direction = 'D' THEN amount ELSE -amount END) <> 0;

Any row this query returns is an incident. Wire it up as a permanent alert, not a monthly report.

3. The transaction lifecycle: where is the money, really?

3.1 The vocabulary of the stages

Authorisation. A request to the card issuer: "is this card valid and is this amount available?" The issuer responds and, if approved, places a hold on the cardholder's account (often called an open-to-buy reduction or pending authorisation). No money has moved. Only available credit has been reduced. An authorisation has a limited life — typically a few days — and expires if never captured.

Capture. The merchant declares "I delivered the goods, actually take this amount". It can equal the authorised amount, be less (partial capture), or happen in several tranches (split capture). Even here, money does not move at that instant — a capture is a recorded obligation.

Clearing. Merchant, acquirer and scheme exchange transaction files at the end of the day. The network computes how much each bank owes each other bank and reduces it to a net figure.

Settlement. The actual transfer of funds between banks based on the clearing nets, usually through a real-time gross settlement system or a clearing house. Here, and only here, does money actually move.

Refund. A new, independent transaction in the opposite direction, after the original transaction has settled. It has its own date, its own identifier and its own settlement cycle.

Reversal / void. Cancellation of a transaction that has not yet settled — an authorisation that was never captured, or a same-day void. Unlike a refund, it usually leaves no trace on the customer's statement (or simply releases the hold). In ISO 8583 it is carried by class-4 messages.

Chargeback. The cardholder complains to their own bank and the issuer forcibly takes the money back from the acquirer. It is a quasi-judicial process with strict deadlines and standard reason codes.

Dispute. The umbrella term for a customer challenge, which may end in a chargeback or be defeated by merchant evidence (representment).

چرخه‌ی عمر یک پرداخت کارتی · The lifecycle of a card payment

stateDiagram-v2
    [*] --> Authorised
    Authorised --> Voided
    Authorised --> Expired
    Authorised --> Captured
    Captured --> Cleared
    Cleared --> Settled
    Settled --> Refunded
    Settled --> Disputed
    Disputed --> ChargedBack
    Disputed --> Represented
    Represented --> Settled
    Voided --> [*]
    Expired --> [*]
    Refunded --> [*]
    ChargedBack --> [*]

4. Idempotency: the most important non-functional requirement in this domain

4.1 Why exactly-once is an illusion

Between two machines over an unreliable network, "exactly once" is impossible. What you actually have is:

• at-most-once: you never resend; the message may be lost.
• at-least-once: you resend until acknowledged; duplicates may arrive.

The real solution: at-least-once delivery plus idempotency at the receiver equals the effect of exactly-once. Note that this is an effect, not a delivery guarantee. If someone in an interview says "we have exactly-once", the follow-up question must be: "where do you de-duplicate?"

4.2 The idempotency key and the request fingerprint

The industry-standard contract is that the client sends an Idempotency-Key header containing a UUID it generated itself, and repeats the same key on every retry of that same operation.

The server does three things:

1. Records the key with a uniqueness constraint in the database (that constraint is the lock that decides who wins the race).
2. Stores a fingerprint of the request body — a hash of the meaningful fields.
3. Stores the final response so that replays return it without re-executing.

CREATE TABLE idempotency_record (
    idempotency_key text        PRIMARY KEY,
    request_hash    char(64)    NOT NULL,          -- SHA-256 hex
    endpoint        text        NOT NULL,
    status          text        NOT NULL CHECK (status IN ('IN_PROGRESS','COMPLETED')),
    response_code   int,
    response_body   jsonb,
    created_at      timestamptz NOT NULL DEFAULT now(),
    completed_at    timestamptz
);

CREATE INDEX idempotency_created_idx ON idempotency_record (created_at);

CREATE TABLE idempotency_record (
    idempotency_key VARCHAR2(200) PRIMARY KEY,
    request_hash    CHAR(64)      NOT NULL,
    endpoint        VARCHAR2(200) NOT NULL,
    status          VARCHAR2(20)  NOT NULL CHECK (status IN ('IN_PROGRESS','COMPLETED')),
    response_code   NUMBER(3),
    response_body   CLOB CHECK (response_body IS JSON),
    created_at      TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL,
    completed_at    TIMESTAMP WITH TIME ZONE
);

CREATE INDEX idempotency_created_idx ON idempotency_record (created_at);

The Spring implementation:

package com.example.payments.api;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;

@RestController
@RequestMapping("/v1/payments")
public class PaymentController {

    private final IdempotencyStore store;
    private final PaymentService payments;

    public PaymentController(IdempotencyStore store, PaymentService payments) {
        this.store = store;
        this.payments = payments;
    }

    @PostMapping
    public ResponseEntity<PaymentResponse> create(
            @RequestHeader("Idempotency-Key") String key,
            @RequestBody @jakarta.validation.Valid PaymentRequest req) {

        String fingerprint = Fingerprint.sha256Hex(req.canonicalForm());

        // 1) Try to claim the key — the PRIMARY KEY constraint decides the race winner
        IdempotencyStore.Claim claim = store.claim(key, "/v1/payments", fingerprint);

        switch (claim.outcome()) {
            case FRESH -> { /* we own the execution */ }
            case REPLAY_COMPLETED -> {
                return ResponseEntity.status(claim.responseCode())
                        .header("Idempotent-Replay", "true")
                        .body(claim.responseBody(PaymentResponse.class));
            }
            case IN_FLIGHT -> throw new ResponseStatusException(
                    HttpStatus.CONFLICT, "a request with this key is still in progress");
            case FINGERPRINT_MISMATCH -> throw new ResponseStatusException(
                    HttpStatus.UNPROCESSABLE_ENTITY,
                    "Idempotency-Key reused with a different request body");
        }

        PaymentResponse body = payments.execute(req, key);
        store.complete(key, HttpStatus.CREATED.value(), body);
        return ResponseEntity.status(HttpStatus.CREATED)
                .header("Idempotent-Replay", "false")
                .body(body);
    }
}

package com.example.payments.api;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;

public final class Fingerprint {
    private Fingerprint() {}

    public static String sha256Hex(String canonical) {
        try {
            MessageDigest md = MessageDigest.getInstance("SHA-256");
            return HexFormat.of().formatHex(md.digest(canonical.getBytes(StandardCharsets.UTF_8)));
        } catch (Exception e) {
            throw new IllegalStateException("SHA-256 unavailable", e);
        }
    }
}

4.3 The timeout where you do not know whether it worked

This is the hardest scenario in the domain: you sent a request to the switch and timed out. Three possibilities exist:

1. The request never arrived — no money moved.
2. It arrived and was processed but the response was lost — money moved.
3. It arrived and is still processing — outcome unknown.

For correlating the request, the outgoing message and downstream events, use the Transactional Outbox pattern (microservices data chapter): write the ledger line and the outgoing event in one database transaction and let a relay publish it. For multi-service coordination, use a Saga with compensating steps — covered in detail in the same chapter. The domain-specific note I will add here is this: a compensating step in the money world is almost never a delete, it is always a reversing entry.

5. Reconciliation: where the truth comes out

Every day you receive a file from the switch, the card scheme or the bank — usually a fixed-width file, a CSV, or nowadays a camt.053 message (a bank-to-customer statement in ISO 20022). You compare it against your own ledger.

5.1 Break categories

5.2 Real reconciliation SQL

Load the file into a staging table and use a FULL OUTER JOIN to see both sides:

CREATE TABLE settlement_file_row (
    file_id        bigint        NOT NULL,
    rrn            varchar(12)   NOT NULL,      -- Retrieval Reference Number, DE37
    stan           varchar(6)    NOT NULL,      -- System Trace Audit Number, DE11
    amount         numeric(20,4) NOT NULL,
    currency       char(3)       NOT NULL,
    txn_date       date          NOT NULL,
    response_code  char(2)       NOT NULL,
    PRIMARY KEY (file_id, rrn)
);

WITH ours AS (
    SELECT p.rrn, p.amount, p.currency, p.value_date, p.status
    FROM payment p
    WHERE p.value_date BETWEEN :from - INTERVAL '1 day' AND :to + INTERVAL '1 day'
),
theirs AS (
    SELECT s.rrn, s.amount, s.currency, s.txn_date, s.response_code
    FROM settlement_file_row s
    WHERE s.file_id = :fileId
)
SELECT COALESCE(o.rrn, t.rrn) AS rrn,
       o.amount AS our_amount,
       t.amount AS their_amount,
       CASE
         WHEN t.rrn IS NULL                       THEN 'MISSING_AT_COUNTERPARTY'
         WHEN o.rrn IS NULL                       THEN 'MISSING_INTERNALLY'
         WHEN o.amount <> t.amount                THEN 'AMOUNT_MISMATCH'
         WHEN o.currency <> t.currency            THEN 'CURRENCY_MISMATCH'
         WHEN (o.status = 'SUCCESS') <> (t.response_code = '00') THEN 'STATUS_MISMATCH'
         WHEN ABS(o.value_date - t.txn_date) > 1  THEN 'DATE_OUT_OF_TOLERANCE'
         ELSE 'MATCHED'
       END AS break_type
FROM ours o
FULL OUTER JOIN theirs t ON o.rrn = t.rrn
ORDER BY break_type, rrn;

CREATE TABLE settlement_file_row (
    file_id        NUMBER(19)    NOT NULL,
    rrn            VARCHAR2(12)  NOT NULL,
    stan           VARCHAR2(6)   NOT NULL,
    amount         NUMBER(20,4)  NOT NULL,
    currency       CHAR(3)       NOT NULL,
    txn_date       DATE          NOT NULL,
    response_code  CHAR(2)       NOT NULL,
    PRIMARY KEY (file_id, rrn)
);

WITH ours AS (
    SELECT p.rrn, p.amount, p.currency, p.value_date, p.status
    FROM payment p
    WHERE p.value_date BETWEEN :from - 1 AND :to + 1
),
theirs AS (
    SELECT s.rrn, s.amount, s.currency, s.txn_date, s.response_code
    FROM settlement_file_row s
    WHERE s.file_id = :fileId
)
SELECT COALESCE(o.rrn, t.rrn) AS rrn,
       o.amount AS our_amount,
       t.amount AS their_amount,
       CASE
         WHEN t.rrn IS NULL                       THEN 'MISSING_AT_COUNTERPARTY'
         WHEN o.rrn IS NULL                       THEN 'MISSING_INTERNALLY'
         WHEN o.amount <> t.amount                THEN 'AMOUNT_MISMATCH'
         WHEN o.currency <> t.currency            THEN 'CURRENCY_MISMATCH'
         WHEN CASE WHEN o.status = 'SUCCESS' THEN 1 ELSE 0 END
              <> CASE WHEN t.response_code = '00' THEN 1 ELSE 0 END THEN 'STATUS_MISMATCH'
         WHEN ABS(o.value_date - t.txn_date) > 1  THEN 'DATE_OUT_OF_TOLERANCE'
         ELSE 'MATCHED'
       END AS break_type
FROM ours o
FULL OUTER JOIN theirs t ON o.rrn = t.rrn
ORDER BY break_type, rrn;

5.3 Choose the matching key carefully

RRN (DE37 in ISO 8583) is the most common matching key but it is not absolutely unique — it is typically unique within a time window and for one acquirer. STAN (DE11) is only six digits and wraps after a million transactions. So the real matching key is usually a tuple: (acquirer_id, terminal_id, stan, txn_date) or (rrn, txn_date, amount).

5.4 The reconciliation job in Spring

package com.example.payments.recon;

import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;

import java.time.Clock;
import java.time.LocalDate;
import java.util.List;

@Component
public class DailyReconciliationJob {

    private final SettlementFileClient files;
    private final ReconRepository repo;
    private final BreakHandler handler;
    private final Clock clock;

    public DailyReconciliationJob(SettlementFileClient files, ReconRepository repo,
                                  BreakHandler handler, Clock clock) {
        this.files = files; this.repo = repo; this.handler = handler; this.clock = clock;
    }

    // 03:00 in the settlement zone — not the server's local time
    @Scheduled(cron = "0 0 3 * * *", zone = "UTC")
    public void run() {
        LocalDate businessDate = LocalDate.now(clock).minusDays(1);
        // Record the run under a unique key: the job itself must be idempotent
        long runId = repo.startRun(businessDate);
        try {
            long fileId = files.downloadAndStage(businessDate);
            List<ReconBreak> breaks = repo.computeBreaks(fileId, businessDate);
            for (ReconBreak b : breaks) handler.handle(runId, b);
            repo.completeRun(runId, breaks.size());
        } catch (RuntimeException e) {
            repo.failRun(runId, e.getMessage());
            throw e;   // let alerting see it
        }
    }
}

6. Concurrency: guarding one number that everybody wants to change

The synchronisation and JMM chapter taught you in-process locking, and the ACID chapter taught you isolation levels. Here I only cover the domain decisions.

6.1 Lost updates on a balance

// ❌ The classic bug — there is a window between the read and the write
BigDecimal balance = accountRepo.findBalance(accountId);
if (balance.compareTo(amount) >= 0) {
    accountRepo.updateBalance(accountId, balance.subtract(amount));
}

Two concurrent threads with a balance of 100 and a withdrawal of 80: both pass the check, and the balance goes negative or one withdrawal is lost. Three correct fixes:

1) A conditional atomic update (the best option whenever possible).

UPDATE account_balance
   SET balance = balance - :amount,
       version = version + 1
 WHERE account_id = :accountId
   AND balance >= :amount;
-- an affected row count of 0 means insufficient funds

UPDATE account_balance
   SET balance = balance - :amount,
       version = version + 1
 WHERE account_id = :accountId
   AND balance >= :amount;
-- SQL%ROWCOUNT of 0 means insufficient funds

2) Pessimistic locking.

SELECT balance FROM account_balance
 WHERE account_id = :accountId
   FOR UPDATE;              -- exclusive lock until the transaction ends

SELECT balance FROM account_balance
 WHERE account_id = :accountId
   FOR UPDATE;              -- same behaviour; NOWAIT or WAIT n controls the wait

In JPA that becomes:

@Lock(LockModeType.PESSIMISTIC_WRITE)
@QueryHints(@QueryHint(name = "jakarta.persistence.lock.timeout", value = "3000"))
Optional<AccountBalance> findAndLockByAccountId(Long accountId);

3) Optimistic locking with @Version.

@Entity
public class AccountBalance {
    @Id private Long accountId;
    private BigDecimal balance;
    @Version private long version;      // JPA adds it to the WHERE clause itself
}

If the version changed you get an ObjectOptimisticLockingFailureException and must replay the whole operation.

@Transactional
public void transfer(long fromId, long toId, Money amount) {
    long first  = Math.min(fromId, toId);
    long second = Math.max(fromId, toId);
    AccountBalance a = repo.findAndLockByAccountId(first).orElseThrow();
    AccountBalance b = repo.findAndLockByAccountId(second).orElseThrow();
    // ... now, with a fixed lock order, post the double-entry
}

7. Cards and switches: the ISO 8583 that still runs the rails

7.1 Message structure

Every ISO 8583 message has three parts: the MTI, the bitmap(s), and the data elements.

The MTI (Message Type Indicator) is four digits, each with meaning:

So 0100 is "authorisation request from the acquirer" and 0110 is its response. 0200 is a financial request (typically a POS purchase) and 0210 its response. 0400 is a reversal request and 0410 its response. 0800 is a network management message (echo test or key exchange) with 0810 as its response.

A bitmap is a 64-bit map (8 bytes, or 16 hex characters) that says which data elements are present. Bit n set means DE n is present. Bit 1 has a special meaning: if it is set, a secondary bitmap immediately follows covering fields 65 through 128.

7.2 ISO 8583 field cheat sheet

Formats: n numeric, a alphabetic, an alphanumeric, ans alphanumeric-special, b binary, z magnetic-stripe track data. LLVAR means variable length with a two-digit length prefix, LLLVAR with three digits.

7.3 PIN, HSMs and key exchange at an interface level

A PIN never travels the network or lives in application memory in the clear. The terminal places the PIN inside a PIN block (an ISO 9564 standard format) and encrypts it under a key. At every node along the path a translate operation happens: the PIN block is decrypted under the inbound key and re-encrypted under the outbound key — and that operation happens only inside an HSM, a hardware module that keys never leave.

From a Java engineer's point of view the practical interface is usually one of: a PKCS#11 library to reach the cryptographic module, or a text command protocol over TCP through which you issue instructions to the HSM. Your code never sees a key or a PIN; it sends an encrypted input and receives an encrypted output.

The key hierarchy has three levels whose names you should know: the LMK (Local Master Key) lives inside the HSM and protects everything; the ZMK (Zone Master Key) is exchanged between two organisations manually under a key ceremony with multiple components and multiple custodians; and the ZPK (Zone PIN Key) is the day-to-day working key, exchanged encrypted under the ZMK.

7.4 PAN masking, tokenization and PCI-DSS scope reduction

The PAN is the 13-to-19-digit card number. PCI-DSS requirement 3.4.1 states that the PAN must be masked when displayed, with at most the first six and last four digits visible, except for people with a documented business need.

public static String maskPan(String pan) {
    if (pan == null || pan.length() < 10) throw new IllegalArgumentException("invalid PAN");
    String head = pan.substring(0, 6);
    String tail = pan.substring(pan.length() - 4);
    return head + "*".repeat(pan.length() - 10) + tail;
}

Tokenization means keeping the PAN in a small isolated system (a token vault) and giving the rest of the system nothing but a meaningless identifier. The key difference from encryption is that a token bears no mathematical relationship to the PAN; it is just a mapping in a database. Its architectural effect is large: any service that only ever sees tokens falls out of PCI-DSS scope and does not have to be audited. That scope reduction is the main reason tokenization exists — not just security, but audit cost and delivery speed.

8. Core banking and integration reality

8.1 End-of-day processing and cut-off

Traditional core banking systems are built around a daily cycle. At a cut-off time — 20:00, say — the business day is closed. Transactions after that belong to the next business day, even though they physically happened today.

After cut-off, end-of-day (EOD) processing runs: interest accrual, fee application, statement generation, closing the day's books and opening the next. During that window — which can take hours — the core is typically either unavailable, read-only, or accepting only certain transaction types.

8.2 Value date versus posting date

This distinction is asked constantly in banking interviews and engineers usually do not know it.

• Posting date (booking date): the date the transaction was recorded in the system. A technical fact.
• Value date: the date on which the transaction is financially effective — the basis for interest calculation, daily limits and accounting reports.

The two can differ: a cheque booked on Friday may have a Monday value date. A transaction after cut-off is booked today but has tomorrow's value date. A correction booked today may carry last month's value date (backdating).

8.3 Real interfaces: SOAP, fixed-width files, and patience

Do not expect a core banking system to offer a clean REST API with JSON. What you actually meet:

• SOAP over HTTPS with a large WSDL and a strict schema (detail in the SOAP and SOA chapter).
• ISO 8583 over TCP with length-prefixed framing, usually over a persistent connection kept alive with periodic echo messages.
• Fixed-width files over SFTP: each record is one line at fixed offsets, no delimiters, padded with spaces or zeros.
• ISO 20022 XML in more modern rails: pain.001 for a customer credit transfer initiation, pacs.008 for the interbank transfer, camt.053 for the statement.

Parsing a fixed-width record in Java is simple but must be precise:

public record SettlementRecord(String rrn, long amountMinor, String currency, String date) {

    // Offsets follow the counterparty's specification — always work from their document
    public static SettlementRecord parse(String line) {
        if (line.length() < 35) throw new IllegalArgumentException("short record: " + line.length());
        String rrn      = line.substring(0, 12).trim();
        long amount     = Long.parseLong(line.substring(12, 24));   // no decimal point, zero-padded
        String currency = line.substring(24, 27);
        String date     = line.substring(27, 35);                    // YYYYMMDD
        return new SettlementRecord(rrn, amount, currency, date);
    }
}

9. The regulatory duties an engineer implements

Here is the list of things nobody writes in the job posting but everybody expects from day one.

Audit trail and immutability. Every state change must be recorded: who, when, from which state to which state, and why. The audit table must be append-only, with UPDATE/DELETE revoked even from the application user.

KYC and AML touchpoints. KYC (Know Your Customer) means verifying customer identity before an account is activated. AML (Anti-Money Laundering) means monitoring transactions for suspicious patterns. From an engineering perspective there are typically three touchpoints: screening at onboarding against sanctions and politically-exposed-person lists, inline screening before a transaction executes, and asynchronous behavioural monitoring across history.

Transaction limits. Per-transaction, daily, monthly, per-channel and per-verification-tier limits. The important technical point: a daily limit is an invariant over a set, so it is exactly where you need SERIALIZABLE or an atomic counter.

-- Daily usage counter with an atomic upsert
INSERT INTO daily_usage (customer_id, usage_date, used_amount)
VALUES (:customerId, :date, :amount)
ON CONFLICT (customer_id, usage_date)
DO UPDATE SET used_amount = daily_usage.used_amount + EXCLUDED.used_amount
WHERE daily_usage.used_amount + EXCLUDED.used_amount <= :dailyLimit
RETURNING used_amount;
-- returning no row means the limit would be exceeded

MERGE INTO daily_usage d
USING (SELECT :customerId AS customer_id, :date AS usage_date, :amount AS amt FROM dual) s
   ON (d.customer_id = s.customer_id AND d.usage_date = s.usage_date)
 WHEN MATCHED THEN UPDATE SET d.used_amount = d.used_amount + s.amt
      WHERE d.used_amount + s.amt <= :dailyLimit
 WHEN NOT MATCHED THEN INSERT (customer_id, usage_date, used_amount)
      VALUES (s.customer_id, s.usage_date, s.amt);
-- SQL%ROWCOUNT of 0 means the limit would be exceeded

Data retention. Financial data usually must be kept for years, while personal data must be deleted after its purpose ends under privacy law. These conflict, and the standard resolution is separation: the ledger keeps a synthetic identifier, and personal information lives in a separate service with its own lifecycle. Deleting personal data must not break the ledger.

Four-eyes approval and segregation of duties. High-risk operations — changing a limit, a manual refund, posting an adjustment entry — must be initiated by one person and approved by a different person. Segregation of duties means no single role can create an operation, approve it, and also erase its log.

@Service
public class ManualAdjustmentService {

    @PreAuthorize("hasRole('OPS_MAKER')")
    @Transactional
    public long propose(AdjustmentRequest req, String actor) {
        return repo.saveProposal(req, actor);   // a proposal only — no financial effect
    }

    @PreAuthorize("hasRole('OPS_CHECKER')")
    @Transactional
    public void approve(long proposalId, String approver) {
        Proposal p = repo.load(proposalId);
        if (p.proposedBy().equals(approver)) {
            throw new IllegalStateException("four-eyes violation: proposer cannot approve");
        }
        ledger.post(p.toJournalEntry(), approver);   // here and only here does money move
    }
}

10. Failure handling in a domain where failure is expensive

The resilience chapter covers the generic patterns (circuit breaker, bulkhead, retry with backoff). Here are the domain-specific differences:

1) Retry only idempotent operations. You cannot blindly resend an authorisation request that timed out — you might place two holds on the customer's account. Reverse or query first, then decide.

2) A circuit breaker must produce "unknown", not "failed". When the breaker is open and a request is rejected, that transaction was never sent, so it genuinely failed. But a request that was sent and timed out is UNKNOWN. Do not conflate the two in code.

3) Partial settlement. A settlement file may carry an amount lower than the authorised amount — because of partial capture, a scheme fee deduction, or an FX adjustment. The system must recognise this as a valid state and post the difference to the appropriate account rather than counting it as a break.

4) Stuck transactions and manual-intervention tooling. There will always be transactions that no automation resolves. You need a tool that lists stuck transactions by age and amount, shows the complete event history and raw messages, offers the operations permitted by the current state, and performs each one under four-eyes with full logging.

11. A reference architecture: a payment service with Spring

The main components and their responsibilities:

معماری یک سرویس پرداخت · Reference architecture of a payment service

flowchart TD
    C[Client] -->|POST with Idempotency-Key| API[Payment API<br/>validation + idempotency]
    API --> SVC[Payment orchestrator]
    SVC --> LED[(Ledger<br/>append-only journal)]
    SVC --> OBX[(Outbox table)]
    SVC --> SW[Switch adapter<br/>ISO 8583 over TCP]
    OBX --> REL[Outbox relay] --> MQ[[Message broker]]
    MQ --> NOTIF[Notification service]
    MQ --> RPT[Reporting projection]
    FILE[Settlement file] --> RECON[Reconciliation job]
    RECON --> LED
    RECON --> OPS[Ops console<br/>four-eyes actions]
    OPS --> LED

• The API boundary does validation, idempotency and translation into the domain model. No financial logic lives here.
• The orchestrator drives the transaction state machine and decides which entries are posted.
• The ledger is the only financial source of truth, append-only.
• The outbox writes events in the same transaction as the ledger so publishing and posting share a fate (pattern in the microservices data chapter).
• The switch adapter is the only place that understands ISO 8583. The rest of the system sees the domain model — the port/adapter boundary from the hexagonal architecture chapter.
• Reconciliation matches external truth against the ledger and posts compensating entries.
• The ops console is the only route for human intervention, with four-eyes and full logging.

جریان یک پرداخت موفق · Sequence of a successful payment

sequenceDiagram
    participant C as Client
    participant A as Payment API
    participant L as Ledger DB
    participant S as Switch
    participant R as Outbox relay
    C->>A: POST /payments (Idempotency-Key)
    A->>L: INSERT idempotency IN_PROGRESS
    A->>L: INSERT journal entry (authorised)
    A->>S: 0200 financial request
    S-->>A: 0210 response code 00
    A->>L: INSERT journal entry (captured) + outbox row
    A->>L: UPDATE idempotency COMPLETED
    A-->>C: 201 Created
    R->>R: poll outbox and publish event

جریان یک پرداخت شکست‌خورده که با مغایرت‌گیری حل می‌شود · Sequence of a failed payment resolved by reconciliation

sequenceDiagram
    participant C as Client
    participant A as Payment API
    participant L as Ledger DB
    participant S as Switch
    participant J as Recon job
    C->>A: POST /payments (Idempotency-Key)
    A->>L: INSERT journal entry (authorised)
    A->>S: 0200 financial request
    S--xA: timeout, no response
    A->>L: mark payment UNKNOWN
    A-->>C: 202 Accepted, result pending
    A->>S: 0400 reversal advice (retried)
    Note over J: next morning batch
    J->>J: load settlement file
    J->>L: found in file, not settled in ledger
    J->>L: INSERT compensating journal entry
    J->>L: mark payment SETTLED

12. The interview reality

Questions in this space come in two layers. The first is the screen: get it wrong and the interview ends there. The second is senior judgment: a correct answer is not enough, you must show you understand the trade-off.