What an overpayment is
Every invoice states an amount that has to be paid to settle it. An overpayment happens when the value actually received is larger than that figure — the bill is covered, and there is money left over on top. The opposite case, where the deposit falls short of the amount owed, is an underpayment; an exact match settles the invoice cleanly. Overpayment is the third outcome: paid in full, with a surplus.
On a crypto invoice this is decided against a single fixed number. The invoice locks the crypto amount the customer must send, and the deposit is compared to that locked amount rather than to a price that has since moved on the market. If the on-chain value received is greater than the locked amount, the difference is the overpayment. Because the reference is pinned, a payment is not reclassified as an overpayment just because the asset's market price rose after the customer paid.
Overpayments are common in crypto for ordinary reasons: a customer rounds the amount up, a wallet adds a buffer, a fee is added on top of the transfer instead of taken out of it, or someone simply mistypes a figure. None of these means the payment failed — the bill is satisfied. What matters is that the surplus is recorded rather than lost, so it can be reconciled or returned.
What it means in a crypto payment
For a merchant, an overpayment is a paid invoice with a tail to handle. The obligation is met, so the sale can proceed, but the customer has sent more than they owed and the difference belongs to them. Treating an overpayment as just paid would quietly absorb that excess; treating it as a distinct outcome lets the merchant see the surplus and decide what to do with it — refund it, credit it, or hold it — rather than have it disappear into the books.
This is why a crypto payment system distinguishes overpaid from paid. The amount received and the amount owed are both recorded, the gap between them is explicit, and the merchant's integration is told which case occurred. A clean comparison against a locked amount is what makes that possible: without a fixed reference, it would be unclear whether a deposit was an overpayment or simply a payment quoted at a different rate.
Overpayment on halfin
halfin invoices are fiat-anchored and lock the crypto amount when the invoice is activated, so every deposit is measured against an exact figure. When a confirmed deposit exceeds that locked amount, halfin records the full value received — it does not discard the surplus — and surfaces the outcome as an overpaid invoice rather than a plain paid one. The amount owed and the amount received are both retained, so the excess is auditable.
The mechanism the merchant integrates against is the webhook. halfin emits an invoice.overpaid event for this case, distinct from invoice.paid for an exact settlement and invoice.underpaid for a short payment. The event is part of the HMAC-signed envelope, so the merchant verifies the signature before acting on it, then reads the amounts to see how large the surplus is. From there the excess can be handled on the merchant's terms — including returning it through a refund — because halfin has preserved the difference rather than rounding it away.
- Measured against the locked amount — the deposit is compared to the exact crypto figure the invoice fixed, not the live market rate.
- Full value credited — halfin records the entire deposit, including the surplus above the amount owed.
- Surfaced as its own outcome — overpaid is distinct from paid and underpaid, so the excess is visible, not absorbed.
- Driven by a signed webhook — invoice.overpaid arrives in the HMAC-signed envelope; verify the signature, then read the amounts.