Most of the time it matches. When it doesn't, you need answers to three questions that card checkouts never asked: what counts as paid, what happens to money that arrives after the deadline, and how do you send money back?

I'll go through how we answer them in Coldtill, the self-hosted gateway we build, and the bits that are just good practice whatever you use.

"Paid" needs a tolerance

The naive rule is received >= owed. It's wrong in both directions. A customer paying from an exchange might lose a cent to rounding and get stuck with an unpaid order over nothing. And a customer who sends 20% extra shouldn't be treated the same as one who sent the right amount, because you may owe them something.

Coldtill reports a payment as one of six states:

The 1% band is the useful bit. It absorbs rounding without you writing any, and it splits "paid" into two outcomes you can treat differently. Ship on FILLED or OVER_FILLED, nothing else.

If you're building your own gateway, I'd copy the idea even if you pick a different number. Put the tolerance in the payment server, not in every shop that talks to it, so there's one definition of paid.

Short payments: keep the door open

An underpayment isn't a failure. Usually the customer forgot a network fee, or paid from an exchange that took its withdrawal fee out of the amount. The right response is to ask for the rest, not to cancel.

That's what PARTIALLY_FILLED does. It isn't final, the checkout shows the customer what's still owed, and a second transfer to the same deposit address tops it up. Each customer gets a permanent deposit address per network family (the same customerID always gets the same addresses), so "send the rest to the same place" is an instruction customers can actually follow.

Checkout with the exact amount and a QR code. After a short payment, the same page asks for what's still owed.

On the shop side, the only job is to not ship. Put the order on hold, maybe email the customer after a while, and wait for a final event. If the payment expires while still short, it becomes CANCELLED and the money that did arrive is still yours to deal with, which brings us to refunds.

Over-payments: ship first, decide later

OVER_FILLED is final and counts as paid. The webhook carries filled_amount_in_usd next to the invoice amount, so the difference is right there:

if (ev.data.status === 'OVER_FILLED') {
  const extra = Number(ev.data.filled_amount_in_usd) - Number(ev.data.amount)
  await markOrderPaid(ev.data.invoice_id, ev.data.reference_id)
  await flagForRefundReview(ev.data.invoice_id, extra) // a human decides
}

Whether you refund 30 cents is a policy question. Gas on some networks costs more than that. I'd set a threshold below which you just note it, and above which someone sends it back. Either way, ship the order. Holding a paid order because the customer was generous is a strange way to treat them.

(Number() is fine for a log line. If you're doing accounting with these values, they arrive as decimal strings for a reason; keep them as decimals.)

Late payments: closed means closed

The awkward one. A payment expires (24 hours by default, or whatever you set with expire when creating it), becomes CANCELLED, and then the money arrives. Maybe the customer's transaction sat in a mempool, maybe they came back to an old tab.

Coldtill doesn't reopen the payment. It sends a progress event with the new filled_amount, and the payment stays closed. I think that's right. Reopening automatically means an order you already cancelled, and maybe restocked, flips back to paid without anyone deciding it should.

So your webhook handler needs a branch for "event on a payment I've already closed":

const order = await findOrder(ev.data.invoice_id)
if (order.reference_id !== ev.data.reference_id) return // an old payment, not this order
if (order.status === 'cancelled' && Number(ev.data.filled_amount) > 0) {
  await notifyStaff(`Late payment on ${order.id}: ${ev.data.filled_amount_in_usd} USD`)
  return
}

Then a person picks: fulfil it anyway, or refund. Both are reasonable. Silently doing nothing isn't, because the customer has paid and is waiting.

The reference_id check matters here. A customer can only have one open payment, and starting a new checkout marks the old one REPLACED. Late events from that old payment must never touch the new order.

Refunds are payouts, and payouts are deliberate

Crypto has no "refund" button that reverses a charge. You send a new transaction. In Coldtill that's a payout from the project's hot wallet, and it comes with a few constraints you should design around rather than discover:

Which chains. Payouts work on the EVM networks and Solana. Bitcoin deposits go straight to your own wallet, derived from your xpub, so there's no Coldtill hot wallet to pay from; Bitcoin refunds come out of your own wallet. Tron payouts aren't supported yet either.

Where to. Through the API, payouts only go to addresses in the project's address book, and entries can only be added in the dashboard, with two-factor. So an API key, even a leaked one, can't send money to an arbitrary address. In practice this means customer refunds are a dashboard job: Payouts → New payout accepts any valid address, still within your limits. API payouts suit regular destinations like suppliers or your exchange account.

How much without asking. Each project has a minimum payout, an auto-approve amount, and hourly and daily limits. Anything over them waits for an admin, a fresh two-factor code and a code sent by email. Annoying when you're in a hurry. Very good when it's someone else in a hurry.

Exactly once. API payouts take an Idempotency-Key. Use something derived from the order, like refund-INV-1001, and a retry after a timeout returns the original payout instead of paying twice. The same key with different parameters is refused with 409.

curl -X POST https://pay.example.com/api/v1/withdrawal/merchant \
  -H "API-Key: $COLDTILL_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: refund-INV-1001' \
  -d '{"blockchainCode":"BASE","currencyCode":"USDC","amount":"12.50","addressBookId":"..."}'

When it's unclear. If Coldtill can't tell whether a payout transaction landed, it marks it needs-review instead of guessing. Don't retry it. Check the hot wallet in a block explorer, then resolve it in the dashboard. A payout wrongly marked failed is how people pay twice.

The Stats page. The completion rate is a quick way to see whether short and expired payments are a real problem for your shop or a rare one.

Ask for the refund address

One general rule, not specific to any gateway: don't refund to the address the payment came from. If the customer paid from an exchange, that "from" address belongs to the exchange, and money sent there may never reach them. Ask the customer for an address on the same network and asset, and keep the request in your support history.

Auto-convert payments are the exception that proves it. When a customer pays with a coin you don't take directly, Coldtill's checkout asks for their refund address up front, on that coin's chain. If the swap fails or they send too little, the swap provider refunds that address and your shop isn't involved.

The short version

• Put the "what counts as paid" tolerance in one place.
• Treat short payments as unfinished, not failed.
• Ship over-payments; refund the extra by policy.
• Never let a late or replaced payment change an order on its own.
• Make refunds deliberate: known address, limits, an idempotency key, and no retries on "unknown".

If you want to look at the gateway behind these examples, the Free edition's install script and release files are in the GitHub repo, and the payout rules are written up in full in the payouts docs.

I find the most useful way to think about hardening it isn't a checklist. It's a question: if someone gets root on this box tomorrow, what do they walk away with? Everything else follows from the answer.

I'll use Coldtill, the self-hosted gateway we build, as the worked example, because I know exactly where its lines are drawn. The general approach applies to any gateway you run yourself.

Start with the blast radius

Here's how the Coldtill security docs describe it:

So a complete server compromise can, at worst, do two things: spend whatever is in the hot wallets, and tamper with payment records, for example marking an unpaid order as paid. It can't redirect deposits, because on Ethereum-style chains, Tron and Solana each deposit address is a contract that can only send to your cold wallet, and Bitcoin addresses come from your own wallet's public key.

That's a much smaller target than "all the money". But notice what's left. Both remaining risks are things you control with configuration, which is what the rest of this post is about.

The Stats page. "Waiting to sweep" shows funds still sitting on deposit addresses. They can only ever move to the cold wallet, which is why they aren't the thing you're defending.

1. Keep the hot wallet boring

The hot wallet pays gas for sweeps and sends approved payouts and refunds. It's the one wallet an attacker with root could drain, so the rule is simple: it should hold about a week of gas and payouts, no more. If losing its balance would hurt, it's too big.

Around it, set the payout controls tight:

• A low auto-approve amount, plus hourly and daily limits. Anything over the limits waits for an admin, a fresh two-factor code and an emailed one-time code.
• API payouts can only go to address-book entries, and adding to the address book needs two-factor.
• Give shop plugins payments-only API keys. A key that can create invoices but can't send money is a much less interesting thing to steal. Keep full-access keys for a backend that genuinely sends payouts.

Internally, Coldtill splits keys by job. Hot wallet keys are encrypted with age, and only the sweeper and payout containers get the identity and passphrase. The web-facing API process can encrypt an imported key but never decrypt one. That's the reason the API, the piece exposed to the internet, holds no keys at all.

By default the passphrase is stored on disk so sweeps survive a restart. If you want more, you can run without a stored passphrase and type it on every start. That's a real trade-off: an unattended reboot means sweeps wait for you.

2. Make the cold wallet properly cold

Everything swept ends up in the cold wallet, and the server only ever needs its address. That means there's no excuse for it to be a browser wallet. Use a hardware wallet, or a multisig (Safe on EVM chains, Squads on Solana).

Then do the step people skip: when the dashboard derives the first deposit address, check it against your own wallet before sharing a payment link. Do it again after any change to deposit wallets. It takes two minutes and it's the one check that proves the money is going where you think.

3. Get the dashboard off the internet

The checkout page and the merchant API have to be public. The login page doesn't. The dashboard is where payouts get approved, so the fewer people who can even load it, the better. The self-hosting guide offers three ways, roughly in order of effort:

1. A separate checkout domain. Give the project a checkout domain like pay.example.com. On that name Coldtill serves only the checkout, the API and static files; the login page and /api/dash return 404. Keep the dashboard on a name you don't publish.
2. Cloudflare in front, with Cloudflare Access (or a WAF rule) protecting the dashboard paths while leaving /pay/, /api/checkout/, /api/v1/ and the static paths open.
3. Tailscale, so the dashboard is only reachable on your private network, with the public hostname used only for checkout and the API.

The strongest setup combines Tailscale for signing in with a Cloudflare rule that blocks the dashboard on every public name. On top of that, two-factor should be on for every account, and people should get the lowest role that works: developer for integration work, read_only for support.

4. Docker will quietly ignore your firewall

This one catches experienced people. You enable ufw, allow only Cloudflare's ranges on 443, and feel good about it. But ports published by Docker Compose are opened in iptables ahead of ufw's rules, so anyone can still reach Caddy directly.

Two fixes. The better one is your hosting provider's firewall (Hetzner Cloud Firewall, DigitalOcean Cloud Firewall, AWS security groups), which filters before traffic reaches the machine. The other is the DOCKER-USER chain, which Docker consults before its own rules:

for r in $(curl -fsS https://www.cloudflare.com/ips-v4); do
  sudo iptables -I DOCKER-USER -i eth0 -s "$r" -p tcp -m multiport --dports 80,443 -j RETURN
done
sudo iptables -A DOCKER-USER -i eth0 -p tcp -m multiport --dports 80,443 -j DROP
sudo apt install iptables-persistent && sudo netfilter-persistent save

Swap eth0 for your public interface, and repeat with ip6tables. Then test it from another machine instead of trusting it:

curl -sk --resolve pay.example.com:443:<server-ip> https://pay.example.com/healthz

If you're behind Cloudflare, that should time out.

The usual basics still apply: SSH keys only, PasswordAuthentication no, unattended security upgrades, and a machine of its own. Don't run the payment server on the same box as your shop. A WordPress plugin bug shouldn't be one hop from your hot wallet.

5. Don't trust a single node

This is the risk that's easy to miss because it isn't about keys. The gateway trusts RPC nodes to report deposits honestly. A malicious or broken node could report a deposit that never happened, and the order gets marked paid.

Mitigations:

• Use nodes you run or pay for, not public endpoints (those are rate limited and meant for testing).
• Add at least two per network, from different providers, so failover works.
• Large orders: look the deposit up on a block explorer before you ship.

Coldtill helps a bit here: Bitcoin deposits are only treated as orphaned when every node agrees the transaction is gone, EVM chain IDs are signed into every transaction, and the Solana genesis hash is pinned, so a node on the wrong network can't trick the signers. Adding a node also needs a fresh two-factor code. But diversity of providers is still on you.

6. Verify what you install

The install script downloads the release and checks its SHA-256 before installing. If you install by hand instead, every release in the GitHub repo ships a SHA256SUMS file:

sha256sum -c SHA256SUMS --ignore-missing

Updates are checked once a day and shown as a banner to admins. Security advisories show up as a red banner, and critical and high ones are emailed. Re-running the installer upgrades and backs up the database first.

7. Backups you've actually restored

Two things need backing up, and they're different:

• The database. Dump it nightly and copy the dumps off the server. A backup on the same disk doesn't survive losing the disk. The docs use restic to an S3-compatible bucket as the example.
• deploy/.env and deploy/secrets/. Keep these in encrypted offline storage. Without .env, the two-factor and webhook secrets stored in the database can't be read, so a database backup alone gets you less than you'd hope.

Then test a restore on a spare server at least once. An untested backup is mostly a feeling.

8. Watch the right things

Not much, but the right things:

• An uptime monitor on /healthz.
• Alerts on "level":"ERROR" in the logs.
• Hot wallet balances. When they run dry, sweeps stop. It's not a security incident, but it looks like one at 2am.
• A webhook subscription for payout.needs-review. That status means Coldtill couldn't tell whether a payout transaction landed, and it deliberately doesn't guess. Don't retry the payout until someone has checked the hot wallet's history.

Compared with the hosted route

None of this exists if you use a hosted processor, and that's a fair point in its favour. You trade this list for an application process, a percentage of every sale and an account that can be frozen. Self-hosting doesn't remove risk; it moves it to places you can see and control.

What I like about starting from "assume it's breached" is that it tells you where effort pays off. With deposits locked to the cold wallet, almost all of the remaining exposure is the hot wallet float, the dashboard and the nodes. Keep the float small, the dashboard private and the nodes plural, and a compromise becomes an expensive inconvenience rather than a disaster.

The full threat model and security model are published at coldtill.com/docs/security, including the risks that remain.

Customers care about paying with whatever is already in their wallet. You care about what lands in yours, what it cost to get there, how long until it's final and how your accountant will feel about it. Those are separate decisions, and treating them separately makes the whole thing much simpler.

I'll walk through how I think about it, using the networks Coldtill supports directly (Ethereum, Base, Polygon, BNB Chain, Tron, Solana and Bitcoin) as the examples, since that's the gateway we build and the trade-offs are ones I deal with every week.

Separate "accept" from "settle"

It helps to split the problem in two:

• Settlement assets are what you're happy to hold. For most shops that's one or two stablecoins on one or two networks, and maybe Bitcoin if you actually want Bitcoin.
• Accepted assets are everything a customer can pay with. That list can be much longer, as long as anything outside your settlement set is converted on the way in.

In Coldtill, settlement assets live on networks where you have a deposit wallet and your own nodes watching the chain. Everything else can come in through auto-convert: a swap provider, NEAR Intents 1Click by default, turns the customer's coin into USDC or USDT and delivers it to your cold wallet. That's where the "200+ coins on 35+ chains" figure comes from. You don't run nodes for any of those; you run nodes for the networks you settle on.

So the real decision is a short one: which one or two networks do you settle on?

What to weigh for each network

Fees, for your customer and for you

There are two sets of fees in a self-hosted setup, and people often only think about the first.

1. The customer's fee to send the payment. This is their cost, but a high one means abandoned checkouts, especially on small orders.
2. Your fee to move the money onward. With per-customer deposit addresses, funds eventually have to be swept from those addresses to your cold wallet, and that costs gas.

The second one is where design matters. Coldtill batches sweeps per network and only sweeps when it's worth it: by default when the unswept total reaches $100, when 20 addresses hold funds, or when the oldest deposit has waited 24 hours, and only if gas is a small enough share of the value. On Tron, sweeps can rent energy instead of burning TRX. Bitcoin is different: addresses are derived straight from your own wallet's public key, so payments land in your wallet and there's nothing to sweep at all.

As a rule of thumb, if your average order is small, a low-fee network for both the customer and the sweep matters more than anything else on this list. Ethereum mainnet is the most widely held but usually the priciest to transact on; Base, Polygon, BNB Chain, Tron and Solana are where small stablecoin payments tend to make more sense. Check current fees yourself, since they move.

Finality: when is it actually yours?

A transfer isn't settled the moment it's seen. Each network needs a number of confirmations before a payment counts, and reorgs, while rare on most chains, do happen. In Coldtill each network has its own configured confirmation count, block hashes are re-checked, and a deposit whose block disappears goes back to pending. For auto-converted payments on Solana, the delivery has to reach finalized before the order is credited.

What this means for a merchant is simple: faster finality means a shorter wait on the checkout page. For digital goods where the customer is staring at a spinner, that wait matters. For a physical order that ships tomorrow, it barely does.

At checkout the customer picks a network and coin; settlement networks stay direct and the rest go through auto-convert

Which stablecoin, and where

USDC and USDT are both available on most of these networks, and customers have strong habits. Some will only ever hold USDT on Tron; others have USDC on Base from an exchange withdrawal. If you settle in only one, the other customers either pay a conversion or go elsewhere.

A reasonable starting point for a lot of shops is one USDC network and one USDT network, and then watching what people actually use. In Coldtill, auto-convert can settle in USDC or USDT on Ethereum, Base, Polygon, BNB Chain or Solana, so you can pick one of those as the landing spot for converted payments too.

What you can do with the money afterwards

This one gets missed. If you'll need to send refunds or pay suppliers in crypto, check where your tooling supports outgoing payments. In Coldtill, payouts run from a small hot wallet on the EVM networks and Solana, with an address book, hourly and daily limits and admin approval for large ones. If refunds matter to you, settling on one of those networks keeps things simple.

Keeping the books in dollars

Accountants don't love a ledger in 40 tokens. The easiest way to keep them happy is to make sure every payment is recorded with a dollar value at the time it was paid, and that what you hold stays in stablecoins.

A few things make reconciliation easier, whatever gateway you use:

• Price the order in USD. Coldtill payments are created with amountInUSD, and the webhook reports filled_amount_in_usd alongside the raw on-chain amounts. Stablecoins count as $1; other coins are priced from CoinGecko, with Coinbase as a fallback.
• Store the on-chain detail. Each payment event includes a payment_info list with network, currency, amount, transaction hash and block number for every deposit. Keep it. It's your audit trail, and it lets you match deposits against your cold wallet's history.
• Record conversions separately. Auto-converted payments carry a conversion array with what the customer sent (for example BTC), its USD value at the time and the stablecoin delivered. That difference is the swap cost, and it's useful to see it as its own line rather than buried in revenue.
• Expect small differences. A payment within 1% of the amount owed counts as filled, and anything more than 1% above is flagged as over-filled. Decide how you book the leftovers before they pile up.
• Only count money that actually arrived. With auto-convert, Coldtill treats the swap provider's status reports as hints, and only credits an order once your own nodes see the stablecoin land in your cold wallet with full confirmations. Your books should work the same way: revenue is what reached your wallet, not what a provider said was on its way.

The stats page splits revenue into coins kept directly and payments swapped through NEAR Intents, and shows what's still waiting to be swept

Exchanges, memos and the customers who pay from them

A surprising number of customers pay straight from an exchange account. That's fine on most direct routes, but some swap routes need a memo, which exchanges often can't add. NEAR Intents 1Click deposits need no memo, so customers can pay from an exchange; the optional THORChain fallback does need one, so those customers must pay from their own wallet. If a swap fails or the customer sends too little, the provider refunds the refund address the customer entered at checkout.

If a lot of your customers buy on exchanges, it's worth testing that path yourself before you launch.

A sensible default

If I were setting up a new shop tomorrow with no data on what customers hold, I'd do this:

1. Settle in one cheap, widely used stablecoin network, plus a second one in the other stablecoin if your customers are split.
2. Add Bitcoin directly only if you actually want to hold Bitcoin. Otherwise let it come in through auto-convert.
3. Turn auto-convert on for everything else, with a slippage limit you're comfortable with (Coldtill allows 0.1% to 3%).
4. Look at the "how customers paid" split after a month and adjust.

There's no perfect network. There's just the one that fits your order sizes, your customers and your accountant. If you want to see how these choices look in practice, there's a live demo dashboard with made-up data on coldtill.com, and the auto-convert docs go into the checks in more detail.

There are roughly three families of options. None is wrong. They just optimise for different things.

1. Hosted crypto processors

This is the "Stripe for crypto" model. You create an account, pass a business review, drop in their plugin, and they host the checkout. Customers pay to addresses the processor controls, and you get paid out on their schedule, often converted to fiat.

Where it shines: speed to launch, no servers to look after, fiat settlement if that's what your accountant wants.

What you give up:

• Someone has to approve you, and can change their mind later.
• The processor holds the money between payment and payout, so your balance can be frozen under their terms.
• There's a percentage fee on every sale for as long as you use it.
• Customer and order data is shared with a third party.

If you're testing whether customers even want to pay in crypto, a hosted processor is a perfectly reasonable place to start.

2. BTCPay Server

BTCPay Server is the project most people mean when they say "self-hosted crypto payments", and it earned that reputation. It's free, open source, runs on your own server and pays straight into your own wallet. For a Bitcoin-first shop, especially one that wants Lightning, it's hard to beat.

Where it shines: Bitcoin and Lightning, a mature ecosystem, no fees, full control.

What to think about: its core focus is Bitcoin. Other coins come through plugins, and swap plugins tend to convert altcoins into Bitcoin. If your customers mostly want to pay in USDC on Base or USDT on Tron, and you'd like your books to stay in dollars, you'll be working against the grain a bit.

3. Self-hosted multi-chain gateways

The third group runs on your own server like BTCPay, but is built around many chains and stablecoins from the start. SHKeeper, Bitcart and our own project, Coldtill, sit here, and they differ a lot in the details.

We built Coldtill because we wanted a self-hosted crypto payment gateway that took stablecoins seriously and assumed the server would one day be attacked. It runs in Docker on a small Linux box, takes native coins plus USDC and USDT on the main networks, and with auto-convert switched on accepts 200+ coins across 35+ chains while settling in a stablecoin. Every deposit address can only send to the merchant's cold wallet, so the web-facing server holds no keys that could redirect funds.

The trade-off: it isn't open source. The WooCommerce plugin is MIT-licensed, but the core app is proprietary under an EULA, with a Free edition (2% fee), Standard ($499 one-time, 1% fee) and Pro ($999 one-time, no fee). If fully open source matters to you, that's a fair reason to pick something else.

What to check before you pick one

Whatever you shortlist, these are the questions I'd ask:

Who holds the money, and when? Follow a payment from the customer's wallet to yours. If there's any point where a third party, or a hot wallet on an internet-facing server, holds the funds, know how much and for how long.

What happens if the server is compromised? For self-hosted options, this is the big one. Can an attacker with root on the box change where deposits go? Are signing keys on the same machine as the public API?

Which coins do your customers actually use? If it's mostly stablecoins on cheap networks, prioritise those. If it's Bitcoin, prioritise Bitcoin.

What do you end up holding? Accepting 50 tokens is less appealing if you then hold 50 tokens. Check whether conversion is built in and who runs it.

How are webhooks signed? Look for HMAC signatures with a timestamp for replay protection, documented retries and idempotent event IDs. Sloppy webhooks are the most common way crypto orders get marked paid when they weren't.

What's the real cost over two years? Add up the percentage fees at your expected volume and compare them with one-time licences and server costs.

Can it be switched off? Is there a licence server, a kill switch or an account that can be closed? Does it keep working if the vendor's site goes down?

Who maintains it? Look at release history, security advisories and how the project handles reported vulnerabilities.

My honest take

If you want zero operations, use a hosted processor. If you're Bitcoin-first and want fully open source, use BTCPay Server. If you want to run it yourself, take a wide range of coins and settle in stablecoins without any custody in the middle, look at the multi-chain gateways, ours included. There's a full comparison and a live demo dashboard on coldtill.com if you want to see how it looks before installing anything.