Underpaid, Overpaid and Expired Crypto Invoices

Why crypto invoices end up underpaid, overpaid or expired, how to handle each case in code and in support, and how to prevent most of them.

9/11/20269 min de lectura
Underpaid invoice for 96.50 of 100 USDT, with overpaid and expired invoice cards on either side

An underpaid crypto payment is one where the customer sent less than the invoice amount, usually because their exchange deducted a withdrawal fee. An overpaid invoice received more than asked, and an expired invoice was not paid before its timer ran out. All three are normal in crypto payments, and each has a standard fix: ask for the remainder, deliver and settle the difference, or match the late payment and re-issue.

Crypto payments are push payments. The customer types or pastes the amount and sends it from their own wallet or exchange account, and nothing stops them from sending a different amount or sending it late. A gateway cannot prevent that. It can detect it, show a clear state and give the customer a way to fix it.

This guide explains why each case happens, how invoice statuses work on Zypher, what your code should do, and what your support team should reply.

Invoice statuses at a glance

Zypher invoices move through these statuses:

StatusWhat it meansWhat you do
PENDINGInvoice created, nothing received yetWait
CONFIRMINGA payment was seen on-chain and is waiting for confirmationsWait; do not deliver yet
PAIDAt least 98% of the amount arrived and was confirmedDeliver
OVERPAIDMore than 102% arrivedDeliver, then decide about the extra
UNDERPAIDLess than 98% arrivedDo not deliver; the customer can top up
EXPIREDThe timer ran out before full paymentDo not deliver; re-issue if needed
FAILEDThe invoice did not completeDo not deliver; check the invoice details

The 98% lower bound absorbs small differences from rounding and fees, so a customer who sends $99.10 for a $100 invoice is simply PAID. Anything from 98% to 102% is treated as exact.

Confirmations needed before a payment counts are: BTC 2, LTC 3, DOGE 3, XMR 5, BSC 5, Ethereum, Base and Arbitrum 6, Solana 8, TRON 10, TON 1. That is why an invoice can sit in CONFIRMING for anywhere from seconds to a few minutes.

Underpaid crypto payments

Why it happens

  • The exchange took its fee from the amount. This is the most common cause. The customer withdraws "10 USDT" from an exchange, and the exchange sends 10 minus its withdrawal fee. Binance, for example, charges about $1 to withdraw USDT on TRC20, so 10 USDT becomes about 9 USDT on arrival, which is 90%.

  • The customer rounded down. They typed 49.5 instead of 49.87.

  • The customer paid the price they saw earlier. They copied an amount from an old, expired invoice.

  • A wallet subtracted the network fee. Some wallets have a "send max" or "fee included" option that sends slightly less.

How Zypher handles it

When less than 98% arrives, the invoice becomes UNDERPAID. The payment page shows the remainder, and the customer can send it to the same unique deposit address. Partial payments add up, so once the total reaches 98% or more, the invoice becomes PAID and your webhook fires.

What your code should do

The webhook event is invoice.paid, sent only when data.status is PAID or OVERPAID. There is no webhook for UNDERPAID. So:

  • Do nothing on your side while the invoice is underpaid. When the customer tops up, the paid webhook arrives as usual.

  • If you want to show "underpaid" in your own order page, read the invoice with GET /api/v1/invoice/:id when the customer opens it. Do not poll every few seconds.

  • Never deliver on UNDERPAID, even if it is close. Your threshold is already generous.

What support should reply

Hi! We received 9.00 USDT of the 10.00 USDT on your invoice. Your exchange most likely deducted its withdrawal fee from the amount. Please open the same payment page and send the remaining 1.00 USDT to the same address, on the same network. Once it arrives, your order is completed automatically.

If the customer cannot or will not top up, agree on an outcome: refund the partial amount to an address they give you in writing, or apply it as store credit.

Overpaid crypto invoices

Why it happens

  • The customer added a fee buffer "just in case".

  • They paid twice, for example once from a phone and once from a desktop.

  • They sent the amount from a different, larger invoice.

What your code should do

Above 102%, the invoice is OVERPAID, and the invoice.paid webhook still arrives with data.status: "OVERPAID". Treat it as paid and deliver. Your handler must accept both statuses:

<?php
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha256', $raw, getenv('ZYPHER_API_SECRET')), $sig)) {
    http_response_code(401);
    exit;
}
$p = json_decode($raw, true);
if ($p['event'] === 'invoice.paid' && in_array($p['data']['status'], ['PAID', 'OVERPAID'], true)) {
    fulfill_order_once($p['data']);          // idempotent
    if ($p['data']['status'] === 'OVERPAID') {
        flag_for_review($p['data']);         // decide on the extra amount
    }
}
http_response_code(200);

A common bug is checking only for PAID, which leaves overpaying customers without their order. They paid more than you asked and got nothing, which is the worst possible support ticket.

What to do with the extra

Set a policy and write it down:

  • Small overpayment (for example under $5): keep it as store credit, or ignore it if you have no balance system. Tell the customer.

  • Large overpayment or a double payment: refund the difference. Ask the customer for an address and network in writing, then send a normal withdrawal, which pays the network fee. Consider deducting that fee from the refund, and say so in your policy.

Expired crypto invoices

How long an invoice lives

  • An invoice priced in a coin expires after 30 minutes.

  • An invoice priced in USD gives the customer 60 minutes to choose a coin and network, then 30 minutes to pay after choosing.

  • A payment that arrives up to 30 minutes after expiry can still be matched to the invoice.

The timer exists because coin prices move. A fiat-priced invoice locks a coin amount for a limited time, so neither you nor the customer carries the price risk for long.

Why it happens

  • The customer opened the invoice, then went to buy crypto on an exchange, and verification took longer than expected.

  • The exchange delayed the withdrawal for a security review.

  • The customer sent from a chain with slow confirmations at a busy moment.

  • They simply came back to an old tab the next day.

What to do

  1. Paid within the grace window: nothing. It is matched automatically.

  2. Paid later: look up the transaction by the deposit address and amount, confirm it arrived, then fulfill the order manually or credit the customer's balance.

  3. Never paid: let the order expire on your side too, and give the customer an easy "Pay again" button that creates a fresh invoice. Do not re-send a link to an expired invoice.

What support should reply

Hi! Your invoice expired before the payment arrived, but we've found your transaction and completed your order manually. Next time, please pay within the timer shown on the payment page, or click "Pay again" to get a fresh invoice.

Wrong network or wrong coin: not an underpayment

If a customer sends USDT on BEP20 to an invoice that asked for TRC20, the invoice does not see a partial payment. It sees nothing, because the funds went to a different blockchain. This is a separate problem with its own recovery rules, covered in what to do when a customer sends USDT on the wrong network. Each invoice has its own unique deposit address, which makes finding the transaction easier.

Prevention checklist

Most of these tickets disappear with a few changes:

  • Price in USD and let customers pick the network. The payment page then shows the exact coin amount for the chosen network.

  • Show a warning about exchange fees next to the pay button.

  • Recommend cheap networks for small amounts. On TRC20, fees depend on TRON energy; BEP20, TON and Solana are usually cheaper for customers. See our comparison of USDT networks.

  • Handle both PAID and OVERPAID in your webhook code.

  • Make fulfillment idempotent. Failed webhook deliveries are retried up to five times.

  • Give customers a "Pay again" button instead of re-sending old links.

  • Write short refund and overpayment rules and link them from checkout.

  • Prepare support templates for the three cases above.

Payment page states customers see

Customers fix most problems themselves if the payment page is clear. Zypher's hosted payment page shows a QR code, a live countdown and distinct underpaid, overpaid and expired states, in 11 languages. You can also set success and fail redirect URLs per store, so the customer lands on a page that explains what happens next.

Full request and response formats are in the API docs. Fee details are on the pricing page; if you are comparing providers, see crypto payment gateway fees compared. To try these flows on a real store, sign up. It takes a minute and needs no documents.

FAQ

What does an underpaid crypto payment mean?

It means the customer sent less than the invoice amount. On Zypher, that is less than 98% of it. The usual cause is an exchange deducting its withdrawal fee from the amount sent. The customer can send the remainder to the same address, and the partial payments add up.

Should I deliver the order if the payment is slightly short?

No, not while the invoice is underpaid. Zypher already counts 98% or more as paid, so small differences are absorbed automatically. Below that, ask the customer to top up the remainder.

What happens if a customer pays after the invoice expires?

A payment that arrives up to 30 minutes after expiry can still be matched to the invoice. Later payments need manual handling: find the transaction, confirm the amount and fulfill the order or refund it. For new attempts, create a fresh invoice.

Is there a webhook for underpaid or expired invoices?

No. Zypher sends one webhook event, invoice.paid, when the status is PAID or OVERPAID. To show other states in your own interface, read the invoice with GET /api/v1/invoice/:id.

How do I refund an overpayment?

Ask the customer in writing for a refund address and network. Send the difference as a normal withdrawal, which pays the network fee. State in your refund policy whether that fee is deducted from the refund.