How to Handle Underpaid USDT Orders Without Auto-Settling the Wrong Payment

bolt_util — Mon, 31 Aug 2026 10:43:34 +0000

A customer creates an order for 1.01 USDT, but accidentally transfers 1.00 USDT.

The payment is real and confirmed on-chain, but a strict payment gateway cannot complete the order because the received amount does not equal the expected amount.

Automatically accepting it sounds convenient. It is also dangerous.

If multiple open orders use the same wallet or have similar amounts, loose matching logic can settle the wrong order, trigger the wrong webhook, and make the accounting problem much harder to reverse.

While building BoltUtil, I designed the underpayment flow around one principle:

The system may find evidence and suggest a match, but it must never guess which order should be completed.

Why amount-only matching is unsafe

A transfer amount is not a unique order identifier.

Imagine three customers creating orders around the same time:

Order A: 1.01 USDT
Order B: 1.00 USDT
Order C: 1.02 USDT

A transfer of 1.00 USDT arrives at the merchant wallet.

Matching it to the closest amount could select Order B, even if the transfer was actually an underpayment for Order A.

The same problem becomes more serious when a wallet processes many concurrent payments.

The matching conditions

A transfer becomes a reconciliation candidate only when all important attributes agree:

Blockchain network
Token contract or asset
Receiving wallet
Order creation and expiration window
Transfer confirmation state
Allowed absolute and percentage difference
Transfer and order processing state

After filtering, the system checks how many safe candidates remain.

If there is exactly one candidate, a reconciliation case can be created.

If there are zero candidates, the transfer remains unmatched.

If there is more than one candidate, the system refuses to choose.

Preserve the blockchain evidence first

The original transfer should be stored before reconciliation begins.

Useful evidence includes:

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

This makes the process auditable and prevents the matching feature from changing or replacing the original on-chain facts.

A unique transaction constraint also helps prevent the same transfer from being processed twice.

A candidate is not a completed payment

Even after the system finds one safe candidate, it does not automatically complete the order.

Instead, it:

Creates a reconciliation case.
Links the transfer evidence and candidate order.
Notifies the merchant.
Shows the expected amount, received amount and difference.
Lets the merchant accept or reject the case.

Only an explicit merchant decision can settle the order.

Every decision is recorded so the result can be reviewed later.

Protecting the existing payment flow

The reconciliation path should be separate from the normal exact-payment path.

A correctly paid order continues through the standard process:

Detect the confirmed transfer.
Match the exact order.
Complete the order.
Deliver the signed webhook.

The underpayment logic runs only when normal matching does not complete the payment. It therefore should not delay or replace exact payment processing.

Production validation matters

The core monitoring and reconciliation architecture supports multiple networks, but each network still needs a minimal real-payment end-to-end test before being described as fully production-proven.

For my current deployment, the TRC20 payment flow has processed roughly 50 real completed orders. The remaining supported networks are being validated separately with real transfers, confirmation checks, order completion and webhook verification.

Unit tests and RPC connectivity checks are useful, but they are not substitutes for real payment acceptance testing.

The result

This approach does not make underpayments magically correct.

It does something more useful:

Finds a possible relationship safely
Preserves the original blockchain evidence
Rejects ambiguous matches
Prevents automatic settlement
Gives the merchant the final decision
Keeps the normal payment path unchanged

I am building this flow into BoltUtil, a non-custodial crypto payment API where funds go directly to the merchant wallet.

I would be interested to hear how other payment developers handle small underpayments, especially when several orders share the same receiving wallet.

DEV Community: bolt_util