Idempotency, Consistency, Compensation, and Reconciliation

Goal

Show how the finance platform protects correctness when requests repeat, responses disappear, systems disagree temporarily, or a completed action needs a business correction.

The durable idea is:

Financial workflows need retry-safe behavior, compensation paths, and reconciliation because failure is part of the operating model.

The Short Version

The dangerous failure is often not a clean rejection. It is uncertainty:

send capture request
  -> provider performs capture
  -> response is lost
  -> caller cannot tell whether capture happened

A blind retry can charge twice. Giving up can leave a fulfilled order unpaid. The architecture needs four different tools:

These tools complement one another. None is a magic substitute for the others.

Idempotency: One Operation, Many Attempts

An idempotent command can be submitted more than once without creating the financial side effect more than once. The command needs a stable key that represents the business operation, not a new random value on every retry.

flowchart LR
    A["Capture command<br/>operation CAP-4815"] --> B{"Operation already known?"}
    B -- "No" --> C["Record operation and validate"]
    C --> D["Call provider with correlation"]
    D --> E["Store confirmed, rejected, or unknown result"]
    B -- "Yes" --> F["Return known status or resume same operation"]
    E --> F

A useful idempotency record includes:

• The stable command key and operation type.

• The business subject, such as order, invoice, refund, or payout.

• Amount, currency, and other request fields that must not change under the same key.

• Current state and response safe to return.

• Provider correlation and attempt history.

• Retention rules long enough to cover realistic retries and delayed callbacks.

If the same key arrives with a different amount, the system should reject the conflict. A key must not become a way to mutate a prior financial instruction.

Idempotency also applies to consumers. Messages, callbacks, and files may be delivered or processed more than once. A handler should recognize the business operation or source record and make duplicate processing safe.

Consistency Is A Designed Journey

Strong consistency inside one owned transaction can be valuable. It becomes difficult to extend across independent services, payment providers, banks, seller systems, and delayed settlement files. The design should name where immediate consistency is required and where state will converge through workflow and reconciliation.

Consider a capture:

Internal command accepted
  -> provider result pending or unknown
  -> provider result confirmed
  -> ledger evidence recorded
  -> settlement record received
  -> reconciliation matched

These stages can temporarily disagree without the architecture being broken, provided that:

• The disagreement is visible as a state, not hidden as success.

• Each stage has a time expectation and owner.

• Unsafe downstream actions wait for the required evidence.

• Recovery can resume from a durable checkpoint.

• Reconciliation eventually confirms or raises an exception.

"Eventually consistent" should never mean "we hope it sorts itself out." It means the convergence mechanism, time window, and exception path are designed.

Retry, Query, Compensate, Or Escalate

Not every failure deserves the same response.

The decision belongs in the workflow model. A generic infrastructure retry policy cannot understand whether another capture, refund, or payout is financially safe.

Compensation Is A New Business Action

Compensation is often described as "undo," but many financial actions cannot simply be erased. A void, refund, credit note, charge adjustment, or reversing entry is a new action with its own rules and evidence.

Compensation can fail too. Give it an operation ID, idempotency behavior, workflow state, authorization checks, and escalation path. Do not implement it as an operator editing a database until the numbers look right.

Reconciliation Closes The Evidence Loop

Reconciliation compares records that were produced independently.

flowchart LR
    A["Internal operations<br/>payment, refund, payout"] --> D["Match and compare"]
    B["Ledger and invoice records"] --> D
    C["Provider or settlement records"] --> D
    D --> E["Matched"]
    D --> F["Pending evidence"]
    D --> G["Exception"]
    G --> H["Investigate, adjust, compensate, or escalate"]
    H --> D

Matching may use operation IDs, provider references, order or invoice references, amount, currency, date, account, and record type. Rules also need tolerances and time windows. A record that has not arrived yet may be pending; a duplicate or material amount mismatch may require immediate investigation.

Reconciliation output should be operational data, not only a report:

• Match status and reason.

• Expected and observed values.

• Age and materiality.

• Owner and service-level expectation.

• Investigation notes and evidence.

• Resolution method and approving actor.

• Link to any correcting or compensating operation.

Example: Capture Response Lost During A Sale

During a flash sale, the platform sends capture operation CAP-4815. The provider accepts it, but the response times out.

The workflow records capture_unknown, the attempt time, and the provider correlation. A user refresh and an automated retry both reuse CAP-4815. The idempotency layer returns the existing operation rather than creating another capture.

The provider's status endpoint is temporarily unavailable, so the workflow pauses with an alert instead of retrying forever. When the provider recovers, a status query confirms the capture. The workflow records the result and creates the internal financial evidence.

Later settlement data contains the same provider reference and amount. Reconciliation marks the capture matched. If it had found two provider captures, the system would create a high-priority exception and route an approved refund or dispute response; it would not delete one record to make the report balance.

Common Mistakes

• Generating a new idempotency key for every retry. That identifies attempts, not the stable business operation.

• Assuming broker duplicate detection removes the need for application idempotency. Duplicates can originate at callers, callbacks, replays, files, and manual actions.

• Retrying an unknown financial outcome as though it were a confirmed failure.

• Using compensation as a blanket rollback. Financial correction is usually a new controlled action.

• Calling a process eventually consistent without defining convergence, timing, and exception ownership.

• Treating reconciliation as optional because the real-time path appears healthy.

• Replaying dead-lettered work without checking whether the side effect already happened.

If Someone Asks You

Why do finance workflows need both compensation and reconciliation?

A good answer is:

Compensation changes the business state after an earlier action can no longer be rolled back cleanly. Reconciliation compares independent evidence to determine whether systems agree and exposes differences that still need resolution. I also use stable operation IDs and idempotency so retries do not create duplicate money movement. Together these mechanisms protect both state and proof.

What You Should Remember

Recovery in finance must protect both state and proof.

Questions to Check Understanding

1. Why must an idempotency key identify a business operation rather than an attempt?

2. When should a workflow query or pause instead of retrying?

3. What information makes a reconciliation exception actionable?

Further Study

• Compensating Transaction pattern - Explore why compensation is business-specific, recoverable work rather than a simple database rollback.

• Saga distributed transactions pattern - Compare orchestration, choreography, local transactions, and compensation in distributed workflows.