A crypto payment isn't a single event. A customer sends a transfer, the network records it, more blocks pile on top of it, and only then is it safe to treat as money that can't come back. In between, the amount can be a little short, the customer can be late, or the coin can arrive on a different network than the one they were shown.
This post walks through how 402pay handles each of those moments, from the second a checkout opens to the webhook your server receives, and why we made the choices we did. None of it requires us to hold your money: every step below happens while the funds sit in your own wallet.
A quote, an address and a clock
Every crypto payment starts with three things. The first is a quote: checkout converts the price into the exact amount of the coin the customer picked, at the current exchange rate. The second is an address made for this checkout alone, so the transfer that lands there can only belong to this payment. The third is a clock, the rate lock, which holds the quote for 15 minutes unless the business sets it to another of 5, 10, 15, 30 and 60 minutes.
The fresh address does most of the hard work. On a shared address, matching a transfer to an order means guessing by amount and time, and two customers paying the same price a minute apart look identical. With one address per checkout, there is nothing to guess. Our post on addresses explains how we make them without ever holding a private key.
The clock exists because crypto prices move. A quote that held forever would let a customer pay tomorrow at today's rate, which is fine for stablecoins and a real cost on Bitcoin or Ether. The lock is long enough to open a wallet app and send, and short enough that the rate still means something.
Seeing the transfer
As soon as the customer sends, the transfer shows up on the network before it's final. We show it on the checkout straight away, so the customer knows it was received, and mark the payment as pending. Nothing is fulfilled yet; a transfer that has only just appeared can still, in principle, be replaced or dropped.
Showing the transfer early matters more than it sounds. A customer staring at a page that hasn't changed tends to send again, or close the tab and email support. A page that says “we see it, waiting for the network” keeps them calm while the confirmations arrive.
Counting confirmations
Each new block on top of the one holding the transfer is a confirmation, and every extra one makes the transfer harder to reverse[1]. Networks reach that point differently: Ethereum finalizes blocks in checkpoints a few minutes apart[2], and Solana lets a reader choose how settled a block must be before it counts[3]. We wait for a fixed number on each network, chosen for how that network finalizes, before the payment succeeds:
| Solana | 2 confirmations, usually about 2 seconds. |
|---|---|
| Polygon | 4 confirmations, usually about 8 seconds. |
| Ethereum | 4 confirmations, usually about 48 seconds. |
| Tron | 3 confirmations, usually about 9 seconds. |
| Bitcoin | 2 confirmations, usually about 20 minutes. |
These are typical times. A busy network, or a customer who sends with a low fee, can take longer, Bitcoin above all. Checkout keeps watching and counts the confirmations for the customer, and the payment succeeds the moment the last one lands.
Fulfill on the confirmation, never on the first sighting.
When the amount is off
Customers rarely send the wrong amount on purpose. Most often an exchange takes its withdrawal fee out of the transfer, or a wallet rounds the last decimal. Treating a payment that is a few cents short as unpaid would frustrate everyone, so each business has an underpayment tolerance: 0.5% to start, adjustable from 0%, 0.5%, 1%, 2% and 5%.
A transfer then lands in one of three places:
- Within the tolerance, it counts as paid in full and the payment succeeds.
- Short by more than that, the payment becomes underpaid, and checkout asks the customer for the rest, to the same address at the same rate.
- Over the amount, the payment succeeds and every bit of it lands in the business's wallet.
An underpaid payment never quietly disappears. The business can accept what arrived as the full payment, or, once the quote has expired, send the customer a new checkout for exactly what's left. The help center covers both.
When it arrives late, or on the wrong network
Some transfers arrive after the quote has expired. The money is real, and it's already in the business's wallet, but the locked rate no longer applies, so we don't decide on our own whether it settles the payment. We keep watching the address for 7 days after the quote ends, and a transfer that lands in that window marks the payment as needing review.
The same status covers the other cases a person should look at:
| Late | The transfer arrived after the quote expired, so the locked rate no longer held. |
|---|---|
| Wrong network | The right address received it, but on another network than the one checkout showed. |
| Reported by the customer | The customer told checkout they'd paid and gave their transaction's hash. |
Reviewing takes a minute: check what arrived, from where, on the network's explorer, then accept it as paid or send it back from the wallet. A longer rate lock means fewer late payments, at the cost of more price movement on volatile coins.
Telling your server
Every one of these outcomes is an event, and every event can reach your server as a signed webhook: payment.succeeded when it's final, payment.underpaid, payment.overpaid and payment.needs_review when it needs a decision, and payment.expired when a checkout ran out of time with nothing sent.
Webhooks follow the Standard Webhooks specification[4], so any of its libraries can verify the signature. If your server doesn't answer, we try again: 8 attempts in all, spread over about 28 hours, so a deploy or a brief outage never costs you a paid order. Make your handler idempotent, look up the order by the reference you gave the payment, and fulfill it once.
Fulfill on payment.succeeded
It's the only event that means the money is final. Every other payment event is a reason to look, not to ship.
What we never do
Through all of this, the funds sit in the business's own wallet. 402pay watches addresses derived from public keys; it can't move a payment, hold one back or reverse one. Accepting an underpayment or a late transfer changes a payment's status, not where the money is.
That is also why refunds are a send from the business's wallet rather than a button on our side. The refunds guide walks through it, and the quickstart shows the webhook handler from a blank project to a fulfilled order.
Common questions
- When its network has confirmed it the number of times 402pay waits for on that network. Until then it shows as pending, and the payment succeeds as soon as the last confirmation lands.
- A shortfall within the business's underpayment tolerance, 0.5% by default, counts as paid in full. A larger one marks the payment as underpaid, and checkout asks for the rest at the same rate.
- 402pay keeps watching the address for 7 days. A late transfer marks the payment as needing review, and the business decides whether to accept it or send it back.
- payment.succeeded. It's the only payment event that means the money is final; the others ask for a decision.
- No. Payments go straight to the business's own wallet, and 402pay can't move, hold or reverse them.
References
- [1]Block chain. Bitcoin Developer Guide.
- [2]Proof-of-stake (PoS). ethereum.org.
- [3]Configuring state commitment. Solana Documentation.
- [4]Standard Webhooks. Standard Webhooks.
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.
