Back

Reconciliation

  • Product Designer
  • Juspay Hyperswitch
  • Exception Resolution
Reconciliation app, Exception Detail screen: a settlement entry recorded in the wrong direction, with the OMS and Adyen entry tables below
Why Reconciliation Exists

One transaction. Multiple versions of the truth.

When a customer makes a payment, merchants, payment providers, and banks each record their own version of the same transaction.

Transaction
OMS
Merchant records it
PSP
Provider settles it
Bank
Bank receives it

As transaction volumes grow, even small discrepancies become difficult to investigate at scale, so reconciliation solves this by comparing each system against another and verifying that every version tells the same story about where the money went.

Layer 1
OMS
What we recorded
⇄
PSP
What Adyen settled
→
Matched
Both sources agreed
Layer 2
PSP
What Adyen sent
⇄
Bank
What bank received
→
Matched
Both sources agreed

Accounts are paired using a common identifier, such as an Order ID or Batch ID, and validated against a predefined rule set. Depending on how the transaction flows through each system, a single transaction may span multiple accounts and many underlying entries.

What's an Exception

Sometimes the records don't agree.

When two records don't agree, an exception is created. That's where the investigation begins.

OMS
What we recorded
⇄
PSP
What Adyen settled
→
Exception
Records don't agree

Although every exception may look similar on the surface, the reason behind them can be entirely different requiring different investigation and resolution paths.

Amount mismatch
Numbers don't match
Currency mismatch
Different currencies
Balance direction
Debit vs credit flipped
Metadata mismatch
Reference fields differ
Missing entry
One side has no record
Unknown
Can't be categorised
Why Resolution Slows Down

One mismatch can hide many different stories.

The mismatch type only tells part of the story. Understanding how accounts and entries are connected is what determines how it's resolved.

Transactions don't always map one-to-one. A single order can split into multiple settlement entries, while several orders can eventually settle into one bank record. That means two exceptions with the same mismatch reason can have entirely different structures underneath.

Before they can act, analysts first need to reconstruct how those accounts and entries relate to one another.

One-to-one
One order matches one settlement entry. The simplest and most common case.
One-to-many
One order splits into multiple settlement entries, such as capture, fee, and refund.
Many-to-one
Multiple orders settle into a single bank entry, usually through batching.
Many-to-many
Several accounts on each side, each paired with exactly one counterpart.

The exception label tells you what failed, but not how the records relate underneath.

Analysts need to understand both layers before they can act:

  • Who is being compared (Account level)
  • What is being compared underneath (Entry level)
Account level
Shows who is being compared.
Entry level
Shows what is being compared underneath.

Why resolution slows down

  • The exception label hides the structure beneath it.
  • The same mismatch can require entirely different resolutions.
Designing the Investigation

Analysts shouldn't have to rebuild the story every time.

Every exception already contained the information analysts needed to make a decision. It was simply buried across accounts, entries, relationships, and metadata.

Because analysts handle exceptions repeatedly, even small amounts of reconstruction effort compound quickly at scale.

Before they could act, analysts needed to understand four things:

  • Which transaction was affected?
  • Which accounts and entries were involved?
  • Where did the discrepancy occur?
  • What caused the mismatch?
Designing for Resolution

We simplified the path from investigation to resolution.

We structured the experience around a simple principle: understand the exception first, then resolve it.

Understand the exception

One experience. Many structures

Regardless of how accounts and entries were connected underneath, analysts followed the same investigation experience, and the interface adapted to each topology while preserving a familiar workflow.

Browser chrome
Navigation sidebar
One-to-One exception detail
Browser chrome
Navigation sidebar
One-to-Many exception detail
Browser chrome
Navigation sidebar
Many-to-One exception detail
Browser chrome
Navigation sidebar
Many-to-Many exception detail
Browser chrome
Navigation sidebar
One-to-One and Many-to-Many exception detail
One to One
Click to flip
Take action

Make resolution obvious

Once the discrepancy was understood, the interface surfaced only the actions relevant to that exception, allowing analysts to resolve issues without leaving the investigation.

Edit an entry

Update incorrect values directly within the investigation.

Add a missing entry

Create the missing record and restore the expected relationship.

Swap the match

Move an entry to the transaction where it belongs.

Ignore an entry

Remove entries that shouldn't participate in reconciliation.


Thanks for following along.