Handling failed and underpaid crypto transactions: edge cases in payment gateways

‍

The happy path is easy. What separates a production-grade crypto payment gateway from a demo is how it handles the messy few percent — the payments that arrive short, late, on the wrong chain, or not at all.

In a demo, a customer pays the exact amount, on the right network, and it confirms instantly. In production, a meaningful share of payments do something else. They arrive short, or double, or after the checkout expired, or on a chain you did not expect, or they get stuck in the mempool for an hour. Handling those edge cases — not the happy path — is what a crypto payment gateway is actually for.

01 — Why crypto has more edge cases than cards

‍

Card payments are a closed, request-and-response system. You ask the network for $50, and it approves or declines $50. The amount, the currency, and the timing are all controlled by the processor. If something is wrong, the answer is simply "declined," and no money moves.

Crypto is the opposite. It is open and user-initiated: the customer constructs and broadcasts the transaction themselves, from a wallet you do not control. They can send any amount, on any chain, at any fee, at any time. There is no "decline" step to protect you — the money can simply arrive wrong, and once it is on-chain, it has already happened.

That single difference reshapes what a gateway does. Its job is no longer to approve or decline. It is to observe reality on the blockchain and reconcile it against what was expected — and to have a defined answer for every way those two things can disagree.

02 — The edge cases, mapped

‍

A crypto payment can land in one of six states. Only the first is the happy path; the other five are what a real gateway exists to handle.

The rest of this article walks through each one — what causes it, and how a robust gateway resolves it.

03 — Underpayment

‍

Underpayment is the most common edge case, and it happens for mundane reasons: the customer's wallet deducted a network fee from the amount, they typed the wrong figure, or the price moved between quote and send. The result is a payment that is real but short of the invoice.

The wrong answer is to silently mark it as paid, or to silently reject it and strand the funds. A good gateway does neither. It exposes the expected amount versus the received amount and lets policy decide, typically with a few options:

• A tolerance threshold — accept the payment as complete if it is within a small percentage of the invoice, absorbing tiny shortfalls automatically.
• Credit as partial and request a top-up — record what arrived, and ask the customer to send the difference to complete the order.
• Refund — return the underpayment if the order cannot be fulfilled partially.

The key is that the shortfall becomes a clear status your system can act on, not a mystery your support team has to reverse-engineer.

04 — Overpayment

‍

The mirror image is when a customer sends more than the invoice asked for. The order should still be fulfilled — but the extra funds have to be accounted for, not quietly absorbed.

A robust gateway credits the order and then either refunds the difference to the sender or credits it to the customer's balance, while recording the overpayment so your accounting reconciles cleanly. Ignoring overpayments is how discrepancies pile up between what the blockchain shows and what your ledger says.

05 — Late and expired payments

‍

Checkouts have a time window, and blockchains do not always cooperate with it. A slow customer or a congested network can mean the payment lands after the checkout has already expired. The funds are real; the order is technically closed.

The worst outcome is money sitting in limbo — received, but attributed to nothing. A capable gateway still detects and attributes a late payment, then applies a policy: a grace window that accepts payments arriving shortly after expiry, an automatic reopen of the checkout, or a refund if the order can no longer be honored. What it never does is lose track of the funds because a timer ran out.

06 — Wrong network and wrong asset

‍

Because EVM-compatible chains share the same address format, a customer can send funds to the right address on the wrong chain — USDT on Polygon to an address you were watching on Ethereum, for example. They can also send the wrong token entirely.

Two things matter here. Detection: the gateway should monitor the address across chains and assets, so a wrong-network deposit is surfaced rather than lost. Recovery: if the funds landed on an EVM chain you support, they are accessible and can be recovered; if they arrived on an unsupported chain or a scheme where the keys do not apply, recovery may be manual or, in the worst case, impossible. Either way, honest, clear communication about what happened — and what can and cannot be recovered — is part of the job.

07 — Stuck and failed transactions

‍

Sometimes the payment simply does not confirm. The sender set the gas too low and the transaction sits in the mempool; it gets dropped or replaced; or it lingers at zero confirmations while everyone waits.

The cardinal rule is that a gateway must not mark a payment as paid until it is final — until it has the confirmations required for that network and amount. Until then it should show a clear pending state, wait, and correctly handle a transaction that gets replaced (RBF) or dropped. Treating "seen in the mempool" as "paid" is exactly the mistake that lets goods ship for money that never actually arrives.

08 — How a robust gateway handles all of this

‍

Every case above comes down to the same underlying capability: turning a messy on-chain reality into a clear status and a defined resolution. In practice, that means a gateway needs:

• Granular webhook statuses — not just "paid" and "failed," but pending, underpaid, overpaid, confirmed, expired, failed — so your system can branch correctly on each.
• Idempotency — so a retried or duplicated webhook never double-counts a payment.
• Expected-versus-received data on every transaction, so reconciliation is exact.
• A dashboard and reconciliation tools to resolve the exceptions a human still needs to see.
• Policy controls — tolerance thresholds, grace windows, auto-refund rules — so the common cases resolve without manual work.

This layer is invisible in a demo and decisive in production. It is, quite literally, the difference between a toy and a payment gateway.

09 — Where CPAY fits

‍

CPAY is built around these realities rather than around the happy path. It surfaces each state explicitly — underpayment, overpayment, wrong-network, expiry, pending and stuck transactions — through clear, granular webhook statuses and a dashboard, backed by policy controls and expected-versus-received data on every payment. Your integration handles what actually happens on-chain instead of assuming everything goes right, and because CPAY is non-custodial with an open API, the funds and the control stay with you throughout.

‍

10 — FAQ

‍

What happens if a customer underpays?
The payment is flagged as underpaid with the expected and received amounts. Depending on your policy, the gateway can accept it within a tolerance threshold, credit it as partial and request a top-up, or refund it — never silently mark it paid.

Can wrong-network deposits be recovered?
It depends on the chain. Funds sent on an EVM chain you support are generally accessible and recoverable; funds on an unsupported chain or an incompatible scheme may require manual recovery or, in some cases, be unrecoverable. A good gateway at least detects and reports them.

What if a transaction gets stuck?
The gateway keeps it in a pending state and waits for the required confirmations. It never marks the order paid before finality, and it correctly handles transactions that are replaced or dropped from the mempool.

Do overpayments get refunded?
The order is credited and the extra amount is refunded or credited per your policy, and the overpayment is recorded so your accounting reconciles.

How do I handle these cases in code?
Subscribe to the gateway's granular webhook statuses and make your handler idempotent. Branch on each status — pending, underpaid, overpaid, confirmed, expired, failed — instead of assuming a single paid/failed outcome.

Conclusion

‍

Any gateway can take a perfect payment. The value — and the risk — lives entirely in the imperfect ones. Underpayments, wrong-network deposits, and stuck transactions are not rare enough to ignore; at volume they are a daily reality. A gateway earns its place by turning each of those messy outcomes into a clear status and a defined resolution, so your team never has to guess where the money went.

‍