Updating a self-hosted payment gateway without losing a payment

Running your own payment software means you are also the person who updates it. Nobody pushes a new version to you at 3 a.m. on a hosted dashboard. That is the trade, and for most shops it is a good one, but it deserves a plan, because "I'll update it when I get round to it" is how a checkout ends up three versions behind with a known bug.

This is how I think about updating a Coldtill install. Coldtill is a self-hosted crypto payment gateway that runs on a Linux server with Docker. Most of what follows is general release hygiene for any payment service you operate. Where I mention a Coldtill-specific detail, it comes from the public site and the GitHub repo. For the exact update commands, use the docs that ship with your edition rather than my paraphrase.

Two things you should know before you start

First, the only call home Coldtill makes is an update check, and you can turn it off. There is no licence server and no kill switch, so nothing stops working if you decide not to update. That is good for independence and bad for complacency. If you switch the check off, you now own the job of noticing new releases yourself.

Second, security fixes are free for every edition, always. So there is no "we can't afford the new version" excuse for staying on a build with a known hole. The question is only when you can safely take the update.

Pick your window by looking at your own payments

A payment gateway is different from a blog. A deploy that restarts it can land in the middle of a customer's transaction. The money itself is not at risk, because deposit addresses live on chain and keep existing whether or not your server is up. What you can lose is attention: a payment arrives, nobody is watching, and the order state lags.

So before updating, look at when payments actually come in. The dashboard's payments and stats pages show you this. If 80% of your orders land between 14:00 and 22:00 in your customers' time zone, do not update at 17:00 because it suits you. Pick the quietest few hours and write them down.

A checklist I'd actually follow

1. Check for pending payments. Open the payments list and look for anything not yet confirmed. If something is mid-confirmation, wait. It is a few minutes, not a reason to rush.
   

2. Take a backup you have actually tested. Not "I think the cron job runs". Confirm there is a recent one and that you know where it is. If you have not rehearsed a restore, do that on a scratch VPS first. It is cheaper than learning the procedure under stress.

3. Read the release notes. Look for anything touching webhooks, the API, or settings you rely on. A shop calling the REST API cares about request and response shapes. A WooCommerce store cares about the plugin staying compatible with the server version.

4. Update staging first, if you have one. A second small install with a testnet-style configuration is enough. You are not testing the chain, you are testing that your shop still creates a payment and still gets a signed webhook.

5. Update production. Then do not walk away.

6. Run one real small payment end to end (see below).

What to verify afterwards

"The containers are up" is not the same as "payments work". After an update I check, in this order:

• The dashboard loads and shows the same projects, wallets and API keys as before.
• A fresh payment from my shop returns a checkout link, and the checkout page renders with the right branding.
• A small payment confirms and my shop receives the signed webhook. Webhooks are signed and carry replay protection, so a webhook sent with a wrong timestamp or signature is rejected. If you suddenly see rejections, check the clock on your shop's server before you blame the update.
• The order in the shop moves to its paid state exactly once.

That last point is the one that matters most. If your handler is idempotent (I wrote about the out-of-order webhook problem in an earlier post), a replay or a retry after your update will not double-fulfil an order.

Watch the plugin side too

If you use the WordPress plugin for WooCommerce, you now have two things to keep current: the Coldtill server and the plugin. The plugin page lists a changelog, and it is worth reading before you click update in WordPress. The plugin needs WordPress 6.4 or higher and PHP 8.1 or higher, so a hosting plan stuck on an old PHP will block you before Coldtill ever does. Also note the gateway only appears at checkout when the store currency is USD, which is the first thing to check if it vanishes after a settings change.

Rolling back

Have an answer to "how do I go back?" before you need it. Usually that means the backup from step 2 and the previous version noted down. If something looks wrong and you cannot explain it in ten minutes, going back and investigating at leisure is better than debugging live on a checkout customers are using.

The boring conclusion

Self-hosting a payment gateway does not mean constant maintenance. It means a small, predictable routine: check for releases on a schedule, update in a quiet window, verify with a real payment, and keep a backup you trust. Do that monthly and it will take you less time than reading this post.

If you want to look at what you'd be running, the repo is at Coldtill/self-hosted-crypto-payment-gateway, and the live demo dashboard linked from coldtill.com has made-up data you can click through without installing anything.