Consider a customer who creates an order for 1.01 USDT and transfers 1.00 USDT. The transaction is valid and confirmed, but the amount is insufficient. If several active orders share a receiving wallet, matching the transfer to the nearest amount can settle the wrong order.

The safest design is not to make the matcher more confident. It is to limit what the matcher is allowed to do.

Reconciliation may identify one defensible candidate, but only an explicit merchant decision may settle an underpaid order.

This article describes the architecture I use for that rule in BoltUtil.

Start with explicit safety invariants

Before implementing queries or tolerance calculations, define the properties that must remain true:

1. An ambiguous transfer must never settle an order.
2. A transfer can settle at most one order.
3. An order can be associated with at most one accepted reconciliation case.
4. Original blockchain evidence must remain immutable.
5. Reconciliation must not delay or replace exact-payment processing.
6. Repeated scanner events and merchant actions must be idempotent.
7. A merchant may only view and decide cases belonging to that merchant.

These invariants are more useful than a single “matching score.” They give every database constraint, state transition and test a clear purpose.

Separate transfer evidence from reconciliation decisions

I model the process with two different records.

The first record represents the observed chain transfer:

• Network and token
• Transaction hash
• From and to addresses
• Raw token amount
• Decimal-adjusted amount
• Block number
• Confirmation state
• First-seen timestamp
• Matching status

The second record represents a reconciliation case:

• Merchant and candidate order
• Transfer evidence reference
• Expected and received amounts
• Absolute and percentage difference
• Case status
• Notification status
• Decision actor and timestamp
• Rejection or acceptance reason
• Audit metadata

This separation matters. A merchant decision may change, fail or be retried, but the transaction observed on-chain must not be rewritten to fit that decision.

A unique constraint on the network and transaction identity prevents the same transfer from being imported twice. Additional uniqueness constraints prevent one transfer from being attached to multiple accepted cases.

Keep the exact-payment path first

The normal payment path should remain simple:

1. Receive or scan a confirmed transfer.
2. Persist the transfer evidence.
3. Try exact order matching.
4. Complete the order.
5. enqueue the signed merchant webhook.

Only when exact matching does not complete an order should the reconciliation service evaluate the transfer.

In simplified pseudocode:

persistTransferEvidence(transfer)

if exactMatchExists(transfer):
    completeExactOrder(transfer)
    return

candidate = findUniqueUnderpaymentCandidate(transfer)

if candidate exists:
    createReconciliationCase(transfer, candidate)
    notifyMerchant()
else:
    keepTransferUnmatched()

This ordering isolates the new feature from successful payments. Exact payments do not wait for tolerance calculations, email delivery or manual review.

Filter candidates before comparing amounts

Amount similarity should be one of the final filters, not the first.

A candidate order must first agree on:

• Blockchain network
• Token or contract
• Receiving address
• Merchant ownership
• Order state
• Creation and expiration window
• Transfer confirmation requirements
• Whether the order or transfer has already been consumed

Only then should the service calculate the shortage.

For an expected amount (E) and received amount (R):

shortage = E - R
shortageRatio = shortage / E

A candidate is eligible only when:

R < E
shortage <= absoluteLimit
shortageRatio <= percentageLimit

Using both limits prevents a percentage-only rule from accepting a large absolute loss and prevents an absolute-only rule from behaving inconsistently across order sizes.

Uniqueness is a decision boundary

After all safety filters are applied, there are only three valid outcomes:

• Zero candidates: retain the transfer as unmatched.
• One candidate: create a review case.
• More than one candidate: retain the transfer as ambiguous.

The third outcome is important. Sorting candidates by distance and selecting the first one only hides ambiguity; it does not remove it.

The matcher should therefore return a candidate only when the eligible set has exactly one member.

Use a small, guarded state machine

A reconciliation case can use states such as:

OPEN -> ACCEPTED
OPEN -> REJECTED

An accepted or rejected case is terminal.

The acceptance transaction should lock or conditionally update the relevant records and verify that:

• The case is still OPEN.
• The merchant owns the case.
• The transfer has not already been consumed.
• The order is still eligible for completion.
• No competing accepted case exists.

Only after those checks should it complete the order and enqueue the normal webhook workflow.

An update shaped like the following is safer than an unconditional write:

UPDATE reconciliation_case
SET status = 'ACCEPTED', decided_at = CURRENT_TIMESTAMP
WHERE id = ?
  AND merchant_id = ?
  AND status = 'OPEN';

The affected-row count becomes part of the concurrency control. If it is zero, another request or state transition has already won.

Treat email as notification, not settlement

Email delivery should never be part of the database transaction that records the transfer or creates the case.

The durable sequence is:

1. Commit transfer evidence and the reconciliation case.
2. Record that a notification is pending.
3. Send the email asynchronously.
4. Record success or retry information.

If the email provider is unavailable, the case still exists in the merchant dashboard and can be retried safely. Payment correctness must not depend on an external mail server.

Preserve tenant boundaries

Reconciliation endpoints need the same ownership rules as normal order endpoints.

A case lookup should be scoped by both case ID and authenticated merchant ID. Accept and reject operations should never trust a merchant identifier supplied by the browser.

Administrative visibility, if required, should use a separate privileged route and generate an audit event.

Test failure paths, not only successful matching

The most valuable tests cover situations where the system must refuse to act:

• No eligible order
• Two equally valid candidates
• Correct amount but wrong network
• Correct amount but wrong token contract
• Transfer outside the order window
• Replayed scanner event
• Two simultaneous accept requests
• Order completed before manual acceptance
• Email failure after case creation
• Merchant attempting to access another merchant’s case

A green unit test suite is still not real payment acceptance evidence. Each supported chain also needs a minimal end-to-end test covering a real transfer, confirmation depth, persistence, order completion and webhook delivery.

In my current deployment, the TRC20 path has processed roughly 50 real completed orders. Other supported network integrations are being validated separately before I describe them as production-proven.

What this architecture achieves

The system does not pretend that an underpayment is automatically correct.

Instead, it:

• Preserves the chain evidence
• Finds only a unique and defensible relationship
• Refuses ambiguous matches
• Keeps exact-payment processing unchanged
• Makes merchant approval explicit
• Records every terminal decision
• Reuses the normal order and webhook completion path

I am implementing this design in BoltUtil, a non-custodial crypto payment API where funds move directly to the merchant wallet.

The broader lesson applies beyond cryptocurrency payments: when automation cannot prove identity or intent, its safest output is a reviewable candidate—not an irreversible business decision.