A card payment is either approved for the exact amount or it isn't. A crypto transfer is whatever the sender sent. Most of the time that matches the quote to the last decimal, but a steady share of real payments arrive a little short, a little over, or in two parts. A checkout that only handles the exact case turns each of those into a support ticket.
This post explains where mismatched amounts come from, how 402pay classifies each one, and what your integration should do with the result. The short version: you rarely need to do anything special, provided your server fulfills on the right event and keeps a record of the excess.
Why amounts come in wrong
Customers almost never send the wrong amount on purpose. The usual causes are mechanical:
- An exchange takes its withdrawal fee out of the amount instead of adding it on top.
- A wallet rounds the last decimal, or the customer types the amount by hand and drops a digit.
- The customer pays from two accounts because neither held enough, so the amount arrives in parts.
- The customer sends a round number above the total rather than the exact figure.
Every one of these is attributable, because each 402pay checkout pays its own address. Whatever lands there belongs to that payment, so the question is never whose transfer it is, only whether it's enough. The post on checkout addresses explains why that matters.
The tolerance decides what counts as paid
Each quote has an expected coin amount, which the payment carries as method.expected_amount, next to method.amount for what actually arrived. Your underpayment tolerance sets how far below the expected amount a transfer can be and still count as paid in full. It starts at 0.5% and can be set to any of 0%, 0.5%, 1%, 2%, and 5% in checkout settings.
| Within tolerance | The payment succeeds as if it were exact. You receive payment.succeeded. |
|---|---|
| Short by more | The payment becomes underpaid. You receive payment.underpaid, and checkout asks the customer for the rest. |
| Over the amount | The payment succeeds, then you receive payment.overpaid with the excess. |
The default absorbs typical exchange fees and rounding on stablecoins. A business selling high-value goods might choose 0% and collect every cent; one selling low-priced digital goods might choose 5% and stop chasing shortfalls that cost more in support time than they're worth.
Underpaid: let checkout ask first
When a transfer falls short beyond the tolerance, checkout doesn't give up on the payment. It shows the customer exactly what's left and keeps watching the same address, at the same rate, for a fresh quote window, 15 minutes by default. Most customers send the rest while the page is still open, and the payment succeeds as usual. Your server sees payment.underpaid followed by payment.succeeded.


The right response to payment.underpaid is usually to hold the order and do nothing else. If the window closes without the rest, the payment stays underpaid, and you choose one of two actions:
| Request the rest | Opens a new checkout for exactly what's left, in the same coin and network, attached to the original payment. When it's paid, the original payment succeeds; no second payment is created. |
|---|---|
| Accept what arrived | Marks the payment succeeded with the amount received, records an accepted event on its timeline, and sends payment.succeeded. |
curl -X POST "https://dash.402pay.co/api/v1/payments/pmt_.../request-remainder" \ -H "Authorization: Bearer $PAY402_SECRET_KEY" \ -H "Idempotency-Key: $(uuidgen)"A remainder request needs an Idempotency-Key, and asking again while the remainder's checkout is still open returns the same checkout, so a retry never sends the customer two links. While the original quote is still live it answers 409 remainder_unavailable, because the customer can still send the rest to the original address. Both actions are also buttons on the payment in the dashboard, described in Support.
Overpaid: succeed first, report second
An overpayment is simpler, because the customer has paid at least what they owed. The payment succeeds, the whole amount lands in your wallet, and a separate payment.overpaid event follows payment.succeeded. The payment's method.overpaid_amount holds the excess in the coin that was sent. The same event fires if another transfer reaches the address after the payment has already succeeded, such as a customer who paid twice by mistake.
402pay doesn't send the excess back on its own, since it can't move funds in your wallet and the right answer depends on your business. Some businesses refund every overpayment, some credit it to the customer's next order, and some ignore excesses below a threshold.
Ask before refunding to the sending address
The address a payment came from may belong to an exchange that can't credit a deposit back to the customer. Confirm an address and network with the customer before you send anything.
Wiring it into your handler
Put together, the amount cases need three branches in a webhook handler, and only one of them ships anything:
// event is a verified delivery; payment is read again with GET /payments/{id}.switch (event.type) { case "payment.succeeded": // Paid in full, within your tolerance, the rest arrived, or you accepted it. await orders.fulfillOnce(payment.reference, payment.id); break; case "payment.underpaid": // Checkout is already asking the customer for the rest. Hold the order. await orders.markAwaitingBalance(payment.reference); break; case "payment.overpaid": // Arrives after payment.succeeded. Record the excess for a refund decision. await refunds.flagExcess(payment.id, payment.method.overpaid_amount, payment.method.asset); break;}A few details keep this correct under real traffic. Read the payment again before acting, since webhooks can arrive out of order. Make fulfillment idempotent on your own order reference, since a payment that was underpaid and then completed produces a payment.succeeded just like one that was exact. And keep the excess as its own record, separate from the order, so a refund decision doesn't reopen a fulfilled order. Our post on webhook handling covers the verification and deduplication side.
Hold on underpaid, ship on succeeded, reconcile on overpaid.
Late transfers and other reviews
One case looks like an amount problem but isn't: a transfer that arrives after the quote has expired. The money is in your wallet, but the locked rate no longer holds, so the payment becomes needs_review rather than succeeded or underpaid. Accepting it uses the same accept action as an underpayment. Our post on confirmations covers late transfers and the other review reasons, and the underpayments guide in the developer docs has every field and status in one place.
Common questions
- If the shortfall is within the business's underpayment tolerance, 0.5% by default, the payment counts as paid in full. A larger shortfall marks it underpaid, and checkout asks the customer for the rest at the same address and rate.
- The payment succeeds and the whole amount lands in the business's wallet. A payment.overpaid event follows, and the payment's method.overpaid_amount shows the excess, which the business can refund from its wallet if it chooses.
- Yes. Request the remainder from the dashboard or the API, and 402pay opens a checkout for exactly what's left, in the same coin and network, on the same payment.
- payment.succeeded. It covers exact payments, shortfalls within tolerance, completed remainders, and payments you accepted.
See what 402pay can do for you.
Discover how 402pay helps your business accept any card and get paid in crypto, straight to a wallet you control.







