DEV Community: Coldtill

USDT on Tron and the energy bill: what sweeping TRC-20 deposits really costs

Coldtill — Sun, 15 Nov 2026 10:09:06 +0000

If you take stablecoins, a lot of your customers will want to pay in USDT on Tron. Transfers are cheap for them and most exchanges support withdrawals on it. Then you build the part that moves those deposits somewhere safe, and you find out the cheap part was only cheap for the sender.

This post is about that second step: getting USDT out of per-customer deposit addresses and into a wallet you control, and why the cost of doing it on Tron behaves differently from what you might expect if you've only done this on EVM chains.

Two resources, not one gas price

On Ethereum-style chains you think in gas: a transaction uses some units, you pay a price per unit, done. Tron splits the cost into two resources:

Bandwidth, which pays for the bytes of the transaction. Every account gets a small free daily allowance, and a plain TRX transfer usually fits inside it.
Energy, which pays for running smart contract code. A USDT transfer is a call to the TRC-20 contract, so it needs energy, and quite a lot of it compared with a simple transfer.

If the account sending the transaction doesn't have enough energy, the network burns TRX from that account to cover the shortfall. That's the bit that surprises people. The fee isn't a fixed number you can read off a block explorer once and hard-code; it depends on how much energy the sender already has and on the network's current energy price.

You can get energy three ways: burn TRX each time, stake (freeze) TRX to receive energy that regenerates, or rent it from someone who has staked. Renting is often the cheapest option for a business that sweeps irregularly, because you don't have to lock up capital to stake.

Why sweeps make this worse

A checkout that gives every customer their own deposit address is the right design. It makes payments easy to match and stops one customer's payment being confused with another's. But it means money lands in many small places, and every one of them needs a contract call to move.

Some rough intuition, without pretending to exact numbers that change week to week:

Sweeping a deposit costs about the same whether it holds $5 or $5,000. The energy is spent on the contract call, not on the amount.
So the fee as a share of the amount is brutal for small deposits and close to irrelevant for large ones.
If you sweep every deposit as soon as it confirms, you pay the full cost on every small order.

The usual answer is the same one you'd use on any chain: don't sweep immediately, sweep when it's worth it. Let deposits sit until the value justifies the cost, set a cap on what you're willing to pay, and batch the work.

What the sweeper needs to decide

When I sketch a sweep job on paper it ends up with four questions:

Is there enough on this address to bother? A per-network minimum, expressed in dollars, not token units.
What will it cost right now? Estimate energy and bandwidth, then price any shortfall.
Is that under my cap? A ceiling per sweep, so a spike in energy prices pauses sweeping instead of eating the margin.
Where does the energy come from? Burn, use staked energy, or rent.

The fourth question is the Tron-specific one. On EVM chains the gas has to come from somewhere too, usually a small hot wallet that tops up deposit addresses, but there's no rental market to think about.

Keep the hot wallet small and boring

Whatever pays for sweeps is a hot wallet: its key has to be available to an automated process. That's a risk you want to shrink, not eliminate by pretending it doesn't exist.

A few rules that hold up:

The hot wallet only ever holds fuel. TRX for energy and bandwidth, ETH or the native coin for gas. Never customer funds.
Only the process that sweeps (and, if you have one, the one that pays out) can unlock it. The web-facing API shouldn't be able to.
Keep it encrypted at rest behind a passphrase, and keep the balance low enough that losing it would be annoying rather than serious.
Alert when it runs low. A sweeper that silently stops because it ran out of TRX is a quiet way to end up with funds sitting on deposit addresses for weeks.

Where the money is allowed to go matters more than the fee

Fees are an operational cost. The destination is a security question. If a compromised server can change where sweeps go, every optimisation above is irrelevant.

This is the design choice we made in Coldtill. On Ethereum-style chains, Tron and Solana, each deposit address is a contract that can only send to the merchant's cold wallet, so the sweeper can trigger a sweep but can't choose a different destination. The sweep rules are per network with fee caps, funds move in batches when the value justifies the gas, and on Tron the sweeper can rent energy instead of burning TRX. The dashboard also shows funds still sitting on deposit addresses until they're swept, which is the number you actually want to watch.

If you'd rather read the code than my description, the gateway is on GitHub: Coldtill/self-hosted-crypto-payment-gateway. The product page with the full feature list is at coldtill.com.

A checklist if you're building this yourself

Track deposits in base units as integers, and value them in dollars only for the sweep threshold.
Estimate energy before each Tron sweep and price the shortfall at the current rate.
Decide up front whether you'll burn, stake or rent, and make the choice a setting, not a code change.
Put a per-sweep fee cap in place and log every sweep that was skipped because of it.
Fund sweeps from a small, separate hot wallet that never touches customer money.
Make the sweep destination something the server can't change.
Show "money not yet swept" somewhere a human will see it.

Tron USDT is popular for good reasons, and it's worth supporting. Just budget for the second transaction, not only the first.

Pricing in dollars, paid in crypto: decimals, rounding and the one-cent problem

Coldtill — Fri, 13 Nov 2026 10:28:41 +0000

One of the most common bug reports on a crypto checkout isn't about reorgs or webhooks. It's a customer who paid exactly what the screen told them and got an order stuck in "partially paid", short by a fraction of a cent.

Nobody had stolen anything. The amount had just been through too many conversions: a USD price, a float in JavaScript, a token with six decimals, a wallet that rounded the display, and an exchange that shaved a little off for its own fee. Each step was "basically right". Together they produced an order a human had to look at.

This post is about that boring layer: turning a price in dollars into an amount on chain, and deciding when the money that arrives is "the same" as the money you asked for.

Store money as integers, in the unit the chain uses

This is the rule everyone knows and still breaks. Don't hold token amounts in floats, not even briefly.

Every asset has a smallest unit and a number of decimals:

Bitcoin: 8 decimals (satoshis)
Ether and most EVM-native coins: 18 decimals (wei)
USDC and USDT: usually 6 decimals, though check the contract on each chain rather than assuming

So an invoice for 49.99 USDC is 49990000 base units. Store that integer. Compare integers. Only format it for humans at the edge.

// amounts in base units, as bigint
function toBaseUnits(decimalString: string, decimals: number): bigint {
  const [whole, frac = ""] = decimalString.split(".");
  if (frac.length > decimals) throw new Error("too many decimal places");
  return BigInt(whole + frac.padEnd(decimals, "0"));
}

toBaseUnits("49.99", 6);  // 49990000n

If your price comes in as a number from somewhere else, convert it to a decimal string with an explicit precision before it touches this function. 0.1 + 0.2 is still 0.30000000000000004 and it will still end up on someone's invoice.

Decide who rounds, and in which direction

Converting USD to a volatile coin always produces more digits than you want. 49.99 USD at some BTC rate is a long tail of satoshi fractions. You have to round, and the direction is a business decision:

Round up and the customer occasionally pays a hair more than the sticker price. Nobody complains about a satoshi.
Round down and you occasionally receive a hair less, which, depending on how strict your matching is, can turn into a partial payment.

My preference is to round the requested amount up to the smallest unit, every time, and show the customer the exact rounded figure with a copy button. What they copy is what I compare against. That alone prevents a whole class of "I paid what it said" tickets.

Exact amounts beat "about this much"

The checkout should never show a rounded-for-humans number as the thing to send. "0.00073 BTC" on screen while the system expects 73412 sats is how you manufacture partial payments.

Show the full amount. Make it copyable. Put it in the QR code or wallet link so the customer's wallet fills it in. Coldtill's hosted checkout does exactly this: exact amounts, copy buttons and wallet links, plus live confirmation progress once the transfer is seen.

The amount on screen is the amount the system matches. No "approximately".

Stablecoins mostly make this go away (mostly)

If you settle in USDC or USDT, the conversion question nearly disappears: one dollar is roughly one token and 49.99 is 49.99. The exchange-rate step is gone, so the rounding step is gone with it.

Two things remain:

Decimals still differ. A 6-decimal token and an 18-decimal token on another chain are not interchangeable integers. Normalise per asset, per chain.
Exchanges and bridges take a slice. A customer withdrawing from an exchange may see the fee taken from the amount instead of on top of it. That's not a rounding issue, it's a genuinely short payment, and your system should treat it as one.

Pick a tolerance and write it down

Even with all of the above, you'll see payments that differ from the order by a trivially small amount. You need a rule for "close enough", and the rule needs to be explicit, small and tested.

The Coldtill WooCommerce plugin is a nice concrete example because its behaviour is documented on the listing: if the amount Coldtill reports doesn't match the order total, apart from a one-cent difference, the plugin adds an order note and leaves the status unchanged. The changelog even records the edge case being fixed, where a payment exactly one cent off had been left pending instead of marked paid. That's the kind of bug this whole post is about. The boundary condition is where it lives.

A tolerance like that has a few properties I'd copy:

it's tiny, so it can't hide a real shortfall,
it's expressed in the pricing currency (cents), not in token units that change meaning between assets,
anything outside it doesn't silently fail or silently pass. It leaves a note and waits for a human.

const TOLERANCE_CENTS = 1n;

function classify(expectedCents: bigint, receivedCents: bigint) {
  const diff = receivedCents - expectedCents;
  if (diff >= -TOLERANCE_CENTS && diff <= TOLERANCE_CENTS) return "paid";
  if (diff < 0n) return "partial";
  return "overpaid";
}

Write tests for -1, 0, +1 and -2. The one that bites is always on the line.

Keep one source of truth for "paid"

The last trap is having two systems that each think they know the answer. If your shop computes "paid" from the webhook body and your gateway computes it from the chain, sooner or later they'll disagree by a cent.

Let the gateway decide, and have the shop act on that decision. Coldtill prices payments in US dollars and its watcher tracks fill state (paid, partially paid, cancelled) on your own server, then sends a signed webhook. The shop's job is to verify the signature and map the state, not to redo the maths. If you're curious how that's wired, the code for the self-hosted gateway is on GitHub at github.com/Coldtill/self-hosted-crypto-payment-gateway.

Payments with their state. Partial payments stay visible instead of vanishing into "failed".

The short version

Integers in base units, never floats.
Round the requested amount up, and show exactly what you'll match.
Normalise decimals per asset and per chain.
Have a small, written, tested tolerance in the pricing currency.
One system decides "paid". Everything else listens.

None of this is clever. It's just the part of a crypto checkout that decides whether a real person gets an email saying their order is on its way, so it's worth getting boring and right.

Your own node or someone else's RPC? What a crypto payment watcher should trust

Coldtill — Wed, 11 Nov 2026 09:53:31 +0000

Every crypto checkout has a part nobody screenshots: the process that watches the chain and decides an invoice is paid. It's the least glamorous piece of the stack and the one that decides whether you ship goods for money you never received.

When I talk to people building their own checkout, the first shortcut they reach for is a hosted RPC endpoint. Sign up, paste an API key, poll eth_getLogs or a block explorer API, done. For a prototype that's fine. For the thing that flips orders to "paid", it's worth slowing down and asking what you are actually trusting.

What the watcher really decides

Strip it down and the watcher answers three questions for every invoice:

Did a transfer of the right asset arrive at the right address?
Is it big enough to cover the invoice (or is it partial, or over)?
Is it buried deep enough that it won't disappear in a reorg?

All three answers come from whatever node you are asking. If that node is wrong, slow, rate-limited, or lying, your order state is wrong. Your code can be perfect and still credit a payment that isn't there.

The failure modes of borrowed data

None of these are exotic. I've seen each of them in someone's support inbox:

Lag. A hosted endpoint behind a load balancer can serve you a block height a few blocks behind the tip from one backend and ahead from another. Your confirmation counter goes up, then down.
Rate limits at the worst moment. Busy market, lots of checkouts, and your free tier starts returning 429s. The watcher either stalls (customers stare at a spinner) or, worse, a badly written retry treats "no data" as "no payment" and expires the invoice.
Different views of the same chain. Two providers can disagree briefly about the head during a reorg. If you mix them, you get both versions.
Someone else's outage is now your outage. Your checkout is up, your database is up, and nobody can pay because a third party is having a bad afternoon.
Privacy. Every address you query tells the provider which addresses belong to your shop and when orders come in.

None of this means hosted RPC is evil. It means it's an input you should treat as a hint, not as the ledger.

A sensible split: settle on what you verify

The approach I like, and the one Coldtill takes, is simple to say: you run nodes for the networks you settle on, and the order is credited only when your own nodes see the funds arrive with full confirmations.

That sentence has a consequence people miss. You don't need a node for every coin you accept. Coldtill takes Ethereum, Base, Polygon, BNB, Tron, Solana and Bitcoin directly, and with auto-convert switched on it can accept 200+ more tokens on 35+ chains through NEAR Intents, which swaps the payment and delivers USDC or USDT to your cold wallet. For those swapped payments, the swap provider's progress reports are treated as hints. The order is only credited once your own node sees the stablecoin land in your cold wallet. You run a node for the chain you get paid on, not for every chain a customer might pay from.

That's the general rule I'd apply to any design, with or without Coldtill: the chain you settle on is the chain you verify yourself. Everything upstream of it is a status bar.

The payments list. An entry only moves to paid when the watcher on your own server has seen enough confirmations.

What "enough confirmations" means in practice

Once you own the data, you still have to decide when to believe it. A few rules that hold up:

Count from your own head, every time. Confirmations are your_tip - tx_block + 1, recomputed on each new block, never cached as a number that only goes up.
Expect the count to go backwards. A reorg can drop a transaction out of the canonical chain. Your state machine needs a path from "confirming" back to "waiting", and nothing downstream (fulfilment emails, licence keys) should fire before "confirmed".
Pick thresholds per network. A fast chain with frequent short reorgs and Bitcoin with ten-minute blocks shouldn't share one number.
Separate "seen" from "paid" in the UI. Customers calm down a lot when the checkout says "we see your payment, 2 of N confirmations" instead of nothing. Coldtill's hosted checkout shows live confirmation progress for exactly this reason.

The customer side: exact amount, QR code, and confirmation progress once the transfer is seen.

Then tell your shop, once

The watcher's last job is telling the shop. Coldtill sends a signed webhook with replay protection when a payment fills, partially fills or is cancelled. On your side that means:

verify the signature and timestamp before reading the body,
make the handler idempotent (the same payment arriving twice must not ship twice),
and if you can, re-check status when the customer lands on your return page, because the browser sometimes beats the webhook.

I wrote more about the ordering problem in an earlier post on confirmations, reorgs and out-of-order webhooks, so I won't repeat it here.

The cost side, honestly

Running your own node is real work. You need disk, you need to watch sync status, and you need an alert when it falls behind. For a single small shop that might feel like overkill compared to a free API key.

My answer is that it's the same trade you make with your database. You could rent a shared one where you can't see the logs, or you can run a boring Postgres you understand. For the component that decides whether money arrived, I want the boring thing I can inspect.

If you'd like to see how the watcher fits next to the other processes (API, sweeper, payouts) in a Docker install, the Coldtill gateway source on GitHub is the place to start. The free edition installs with one command:

curl -fsSL https://coldtill.com/install.sh | sudo bash -s -- --edition free

Whatever you build on, decide early which data you verify and which you merely accept. It's much easier to design that in than to bolt it on after the first "but the explorer said it was paid" ticket.

Updating a self-hosted payment gateway without losing a payment

Coldtill — Mon, 09 Nov 2026 10:15:16 +0000

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

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.
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.
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.
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.
Update production. Then do not walk away.
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.

Integrating a self-hosted crypto gateway without a plugin: the REST API path

Coldtill — Sat, 07 Nov 2026 10:13:31 +0000

Most crypto payment write-ups assume you run WooCommerce. Paste a plugin, flip a switch, done. That works when the cart is WooCommerce. It falls apart when the cart is a Next.js storefront, a SaaS billing page, a custom invoice tool, or a stack you wrote yourself five years ago and are not rewriting for a payment vendor.

Those shops still need a checkout. They just need it over HTTP.

This post is the REST path into Coldtill: create a payment, send the customer to a checkout link, get a signed webhook when it fills, and keep your own order state machine. No plugin required. The same API is what every Coldtill plugin (WooCommerce, PrestaShop, Magento, WHMCS, EmDash, DashCommerce) speaks under the hood — you are just calling it from your own code.

What you are integrating with

Coldtill is a self-hosted crypto payment gateway. You install it on a Linux box with Docker; the stack lands under /opt/coldtill with PostgreSQL, Caddy, and four processes: api, watcher, sweeper, payouts. Free edition install:

curl -fsSL https://coldtill.com/install.sh | sudo bash -s -- --edition free

There is no licence server and no merchant account at Coldtill. The money goes to your cold wallet. Deposit contracts on Ethereum-style chains, Tron and Solana can only send to that cold wallet; Bitcoin deposit addresses come from your own wallet pubkey. The API process holds no keys. Source and releases are on the self-hosted crypto payment gateway repo if you want to read the Compose file before you run anything.

Direct networks cover Ethereum-style (Ethereum, Base, Polygon, BNB), Tron, Solana, Bitcoin, plus USDC/USDT on those rails. Across the product that expands to 200+ coins on 35+ chains when optional auto-convert is on — that path is a separate topic; the REST flow below is the same either way.

The integration shape

Strip away the plugins and you are left with four moving parts:

Create a payment — POST /api/v1/payment with amount (USD), customer id, and a return URL.
Redirect the customer — the response includes a checkout link on your Coldtill host (or a custom checkout domain on the project).
Receive a signed webhook — when the payment fills, partially fills, or cancels, Coldtill POSTs to your endpoint with a signature and replay protection.
Optionally recheck on return — when the customer hits your return page, ask the API for the payment status again in case the webhook raced the browser.

That is the whole contract. Everything else (which coin they pick, confirmations, sweeps to cold wallet) is Coldtill's problem on your server.

Payments created over the API show up in the dashboard like any other: amount, status, network, and whether they have been swept yet.

Creating a payment

You need a project API key from the Coldtill dashboard. Keys are scoped to one project (one shop surface: wallets, branding, webhooks). Create the payment against your Coldtill base URL:

POST /api/v1/payment
Authorization: Bearer <project-api-key>
Content-Type: application/json

{
  "amount": "49.00",
  "currency": "USD",
  "customer_id": "usr_1842",
  "order_id": "inv_9911",
  "return_url": "https://app.example.com/billing/crypto/return"
}

Field names in your client may follow the OpenAPI schema exactly — Coldtill ships OpenAPI 3.1 and a TypeScript SDK generated from it, so you do not have to hand-roll types. The important bits are:

Amount in USD. Coldtill prices payments in dollars. Your storefront can display whatever you like; the invoice Coldtill creates is USD.
Customer id. Something stable in your system (user id, account id). Coldtill uses it to keep deposit addresses consistent per customer where that model applies.
Order / reference id. Whatever you need to map the webhook back to an invoice, subscription period, or cart.
Return URL. Where the checkout "done" button sends the browser. Do not treat arrival here as paid — treat it as a prompt to recheck.

The response gives you a payment id and a checkout URL. Send the customer there. They pick a network and coin, see the exact amount and deposit address, and pay.

The hosted checkout is yours: project branding, optional custom domain, coin and network picker. Your app only created the payment and redirected.

You do not poll the blockchain from the storefront. The watcher on your Coldtill box does that. Your app waits for the webhook (and optionally rechecks on return).

Signed webhooks without getting burned

Webhooks are where custom integrations usually get clever and then get hurt. Coldtill signs each delivery and includes replay protection. Practical rules that have held up:

Verify the signature with the project's webhook secret before you touch order state. Reject anything that fails.
Respect replay protection. A replayed payment.filled should be a no-op, not a second credit. Keep an idempotency key or event id and short-circuit duplicates.
Map statuses, don't invent them. Filled means enough confirmed value to cover the invoice under your rules. Partial and cancelled are first-class; handle them explicitly so support is not inventing policy in Slack.
Ship or unlock from the webhook, not from the return page. The return page is a UX nicety. Networks are slow; browsers are impatient. The webhook is the source of truth; a return-page GET that rechecks the payment is a backup when the user stares at a spinner.

A minimal receiver sketch (shape only — use the SDK or OpenAPI types in real code):

app.post("/webhooks/coldtill", async (req, res) => {
  if (!verifyColdtillSignature(req, process.env.COLDTILL_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const event = req.body;
  if (await alreadyProcessed(event.id)) {
    return res.status(200).end();
  }
  switch (event.type) {
    case "payment.filled":
      await markInvoicePaid(event.data.order_id, event.data.payment_id);
      break;
    case "payment.partial":
      await flagPartial(event.data.order_id, event.data);
      break;
    case "payment.cancelled":
      await releaseReservation(event.data.order_id);
      break;
  }
  await rememberEvent(event.id);
  res.status(200).end();
});

Point the project's webhook URL at that endpoint in the Coldtill dashboard. Each project has its own URL and signing secret, so a SaaS billing surface and a side store can land on different receivers without sharing secrets.

OpenAPI and the TypeScript SDK

Hand-writing fetch calls is fine for a spike. For anything that lives more than a weekend, use the OpenAPI 3.1 document Coldtill exposes and the TypeScript SDK built from it. You get typed request/response shapes for creating payments, fetching a payment by id (the return-page recheck), listing, and the webhook payload shapes your verifier should expect.

That also keeps you honest when you upgrade the Coldtill box: regenerate or bump the SDK, fix the type errors, ship. Plugins do the same dance behind a nicer UI; custom stacks get the raw contract.

Roles on the Coldtill side matter here. Give the engineer who owns the integration a developer role (API keys, webhooks) and keep admin for people who can change wallets and approve payouts. Read-only is for whoever watches the dashboard without touching keys.

Fitting it into a real stack

Custom storefront / headless cart

On "Pay with crypto", create the payment server-side with the project API key (never from the browser), redirect to the checkout URL, and let the webhook flip the order to paid. Your cart never sees a private key. Your cart never talks to a chain RPC.

SaaS billing / invoices

Same pattern, different nouns. Invoice id becomes order_id. When payment.filled lands, extend the subscription period or mark the invoice settled. Partials stay open with a clear "underpaid — send the remainder to the same address" state if that matches how you operate; otherwise cancel and issue a fresh invoice.

Mixed fleet

One Coldtill install can host many projects. WooCommerce shops use the WordPress plugin; the weird internal billing tool uses REST. Same server under /opt/coldtill, different project API keys and webhook secrets. The GitHub repo is the place to confirm process layout and Compose services if you are sizing the box.

What the API deliberately cannot do

A few boundaries are worth knowing before you design around the wrong assumption:

The API cannot move customer deposits to an arbitrary address. On EVM-style, Tron and Solana, deposit contracts are locked to your cold wallet. Sweeps only go there.
The API holds no keys. Gas for sweeps and the hot wallet used for payouts/refunds are unlocked by the sweeper and payouts processes behind your passphrase — not by a REST call with an API key.
Payouts are a person-shaped flow. Address book, 2FA, and for amounts over your limits an admin plus a fresh 2FA code plus an emailed OTP. Do not plan an unattended "refund any address the customer pastes" endpoint on top of Coldtill; that is not what the till is for.
Editions change sweep fee, not API surface. Free is 2%, Standard 1%, Pro 0% — one-time price, no licence check on the box. Your integration code does not change between editions.

A short checklist before you go live

Coldtill installed, project created, cold wallets set, hot wallet topped up for gas.
Project API key created; webhook URL and secret configured; signature verification tested with a deliberate bad signature.
Create-payment → checkout → testnet (or small mainnet) payment → webhook received once → return-page recheck agrees.
Partial and cancel paths exercised so support has a runbook.
Idempotency proven: replay the same webhook, confirm no double credit.
API key stored as a server secret; browser never sees it.

The short version

If you do not have a plugin for your stack, you do not need one. POST /api/v1/payment, redirect to the checkout link, verify signed webhooks with replay protection, recheck on return. OpenAPI 3.1 and the TypeScript SDK keep the contract typed. The gateway still settles to your cold wallet on your server; your app just drives the payment lifecycle over HTTP.

Docs, pricing and the install one-liner are on coldtill.com. The self-hosted crypto payment gateway repo has the source if you want to read before you curl.

Many shops, one server: running several crypto checkouts from a single Coldtill install

Coldtill — Thu, 05 Nov 2026 10:09:23 +0000

If you run more than one store, the usual crypto-payments story gets expensive fast. Each brand wants its own checkout domain, its own webhook endpoint, its own cold wallet and its own API key. Hosted processors usually solve that with another merchant account and another cut of every sale. Self-hosting solves it with another container… unless the gateway was built to keep shops apart inside one install.

Coldtill is built that way. One Linux box, one Docker stack, as many projects as the business needs. Each project is a shop: its own wallets, API keys, webhooks, branding and checkout domain. The rest of this post is how that model actually works day to day, and the few places where people get tangled.

Why projects exist

A "project" is Coldtill's word for one business surface. Think of it as the unit that a customer recognises:

Its own store name, logo, accent colour and light or dark theme on the hosted checkout
Its own checkout host, such as pay.brand-a.com or pay.brand-b.com
Its own cold wallets and deposit wallets per chain
Its own API keys and webhook endpoints
Its own payment history, customers and deposits

What is not duplicated is the server: PostgreSQL, Caddy, and the four Coldtill processes (api, watcher, sweeper, payouts) stay shared. That matters for ops. You back up one database, watch one set of containers, and upgrade once.

One install, several projects. The dashboard treats each shop as its own surface while the stack underneath is shared.

The design choice behind this is the same one as the rest of Coldtill: the money never belongs to the server. Splitting shops is about isolation of configuration and attribution, not about spinning up a new place that holds customer funds.

What stays separate (and why)

Wallets

Each project points at its own cold wallet addresses. On Ethereum-style chains, Tron and Solana, deposit contracts for that project can only send to that project's cold wallet. Bitcoin deposit addresses come from the project's own wallet pubkey. Mixing brands into one cold wallet is possible in the sense that nothing stops you pasting the same address twice, but it's usually a bookkeeping mistake. Keep them separate and your accountant will thank you later.

Sweep behaviour is also per network and per project rules: funds move in batches when the value justifies the gas, with fee caps, and Tron can rent energy instead of burning TRX. A quiet brand doesn't get swept on the same schedule as a busy one just because they share a host.

API keys

Create a project API key under API keys for each shop. The key scopes calls to that project. If a plugin on Brand A's WooCommerce store leaks its key, Brand B's payments, webhooks and wallets are not reachable with it. Rotate per shop when someone leaves, without touching the others.

Webhooks

Each project has its own webhook URL and signing secret. Brand A's store gets payment.filled events for Brand A only. Replay protection and signature checks are the same mechanism everywhere; the secret is not shared across projects. That also means you can point Brand A at a staging receiver and Brand B at production without rewriting anything global.

Branding and checkout domain

Customers notice this first. The checkout shows the shop's name and logo, not Coldtill's. Support email, help URL and a short message (up to 280 characters) are per project. The checkout can sit on the shop's own domain, so the address bar matches the store the customer just left. Two brands on one server look like two brands, which is the point.

Stats stay scoped to the project you're looking at: revenue, completion rate and where funds still sit on deposit addresses.

Team roles across shops

Coldtill has three roles: admin, developer and read-only.

Admin — full control: wallets, payouts, team, project settings.
Developer — API keys, webhooks, integration work; not the person approving large payouts.
Read-only — payments, customers, deposits and stats for reporting.

On a multi-shop install this maps cleanly onto real teams. A contractor wiring Magento for Brand B gets developer on that project and nothing on Brand A. Finance gets read-only everywhere. Admins stay few. Large payouts still need an admin, a fresh two-factor code and an emailed one-time code, on top of the address book and hourly/daily limits — that gate doesn't loosen just because you added a second project.

A practical layout

Here's a layout that has held up for people running a couple of stores plus a SaaS billing surface:

Project	Checkout domain	Integrates with	Cold wallet
Brand A shop	`pay.branda.com`	WooCommerce plugin	Hardware wallet A
Brand B shop	`pay.brandb.com`	PrestaShop / Magento	Hardware wallet B
SaaS invoices	`pay.saas.example`	REST API + TypeScript SDK	Company treasury

One install at /opt/coldtill, one Caddy, DNS for each checkout host pointed at the same box. Plugins for WooCommerce, PrestaShop, Magento, WHMCS, EmDash and DashCommerce all speak the same REST API and signed webhooks; the difference is which project API key you paste in.

Install itself is still the Free edition one-liner if you're starting fresh:

curl -fsSL https://coldtill.com/install.sh | sudo bash -s -- --edition free

The script lands the stack under /opt/coldtill (PostgreSQL, Caddy, api, watcher, sweeper, payouts). There's no licence server and no approval queue. Source and releases live on the self-hosted crypto payment gateway repo if you want to read the Compose file before you run anything.

How a payment stays in its lane

The shop calls POST /api/v1/payment with its project API key and gets a checkout link for that project.
The customer pays to their own permanent deposit address for that project/chain family.
The watcher confirms, handles reorgs and fires the project's signed webhook.
Later the sweeper moves funds to that project's cold wallet.

Nothing in that path consults another project's wallets or keys. Attribution is by project and by customerID inside the project: each customer has at most one open payment, and deposits on their address credit that payment.

Things that bite when you add a second shop

Same cold wallet pasted twice. Technically fine, operationally messy. Sweeps from two brands land in one place with no label on chain. Prefer separate cold wallets and let the dashboard show each project's unswept total.

Webhook URL copied from the wrong project. The signature will fail or the events will update the wrong store. When you set up a plugin, copy the webhook URL and secret from the project that matches the API key — both are shown in that project's settings.

One shared "ops" API key. Don't. Issue a key per integration. Revoking a compromised Magento key should not mean regenerating every WooCommerce install you run.

Forgetting checkout DNS. Each project can use its own host. If Brand B still serves checkout under Brand A's domain, customers notice, and so do browsers when cookies and HSTS enter the picture. Add the host in the project, put DNS on it, let Caddy terminate TLS.

Assuming stats are global. Open the wrong project and the dashboard looks empty. Switch project first, then panic.

When one server is enough (and when it isn't)

One install is enough when the shops trust the same ops team, share a threat model and can share upgrade windows. It's the common case for a founder with two brands, or an agency hosting a handful of client checkouts they operate.

Split onto another server when the trust boundary changes: a client who must hold their own .env and database, a region with different retention rules, or a shop whose downtime budget can't ride on someone else's upgrade. Coldtill doesn't charge per server — editions differ by sweep fee (Free 2%, Standard 1%, Pro 0%), not by how many boxes you run — so splitting for isolation is an ops choice, not a pricing one.

What I'd do on day one of a second shop

Create the project, set name/logo/colours and the checkout domain.
Attach cold wallets and confirm the first derived deposit address against your own wallet UI.
Create a project API key and a webhook endpoint aimed at that shop only.
Grant the integrator developer, not admin.
Take a testnet payment end to end before mainnet DNS goes live.

If you want to click around before installing, demo.coldtill.com is a live dashboard with made-up data. For the real thing, the install command and docs are on coldtill.com.

One server can absolutely run several crypto checkouts. The work is making sure each shop keeps its own wallets, keys, webhooks and face — and that the people with admin on any of them stay few.

What to back up (and watch) when you self-host a crypto payment gateway

Coldtill — Tue, 03 Nov 2026 10:12:52 +0000

Most self-hosting advice about backups boils down to "dump the database somewhere". For a crypto payment gateway that's necessary, but it isn't the whole story, and the parts people skip are the ones that hurt.

Here's the thing that took me a while to see clearly: on a non-custodial gateway, a dead server doesn't lose you money. The money was never on it. What a dead server loses you is the ability to prove what happened: which order a deposit belonged to, which webhooks fired, whether that $499 payment from Tuesday ever confirmed. And if you lose the wrong file, you also lose every two-factor secret and webhook secret your install ever issued.

This post is the backup and monitoring setup I'd put on any Coldtill server before it takes a real payment. Paths and commands are Coldtill's, because that's what we build, but the categories apply to any self-hosted gateway.

Four things, four different failure modes

A Coldtill install has four pieces of state worth thinking about, and they fail differently:

What	Where	If you lose it
PostgreSQL database	`pgdata` Docker volume	Payment history, settings and the encrypted hot keys. Customer funds are still safe on chain, but the records are gone
`.env`	the deploy directory	The server secret. Sessions, two-factor secrets and webhook secrets become unreadable
`secrets/`	the deploy directory	The hot-wallet identity. You'd have to re-import or replace the hot wallets
Cold wallet seed	offline, with you	Everything swept so far. No software can help you here

The row people miss is .env. It holds COLDTILL_SECRET, which seals the TOTP and webhook secrets stored in the database. Restore a database dump without the matching .env and you get a database full of encrypted blobs you can't open: every user re-enrols two-factor and every webhook endpoint gets recreated. That's not a disaster, but it's a bad afternoon you can avoid with one cp.

And the cold wallet seed isn't really a server backup at all. Coldtill never sees those keys; it only needs the address. It's on the list because it's the only one of the four that actually holds money.

Where things live

If you installed with the one-line script from the Coldtill GitHub repo, the deploy directory is /opt/coldtill. The installer makes .env readable only by root and the Coldtill user, so run Compose with sudo:

cd /opt/coldtill
sudo docker compose ps

You should see PostgreSQL, Caddy and the four Coldtill processes (api, watcher, sweeper, payouts).

Nightly database dumps

pg_dump through the running container is all you need:

#!/usr/bin/env bash
# /usr/local/bin/coldtill-backup
set -euo pipefail
cd /opt/coldtill
mkdir -p /var/backups/coldtill
docker compose exec -T postgres pg_dump -U coldtill coldtill \
  | gzip > /var/backups/coldtill/coldtill-$(date +%F).sql.gz

Run it from root's crontab (sudo crontab -e) at a quiet hour:

15 3 * * * /usr/local/bin/coldtill-backup

One thing worth knowing: running the install script again is also how you upgrade, and it saves a database dump to /opt/coldtill/backups/ before it restarts on the new image. Nice, but don't treat it as your backup strategy. It only runs when you upgrade, and it sits on the same disk.

Get the dumps off the box

A backup on the same disk as the database doesn't survive the thing you're most likely to lose: the whole server. Ship them somewhere else. The Coldtill docs use restic to an S3-compatible bucket, which I like because it's encrypted, deduplicated and has sane retention:

sudo apt install restic
export RESTIC_REPOSITORY=s3:https://s3.example.com/coldtill-backups
export RESTIC_PASSWORD_FILE=/root/.restic-pass
restic init

Then add two lines to the end of the backup script:

restic backup /var/backups/coldtill
restic forget --keep-daily 14 --keep-monthly 6 --prune

Your provider's snapshots are a good extra layer on top of this, not a replacement. Snapshots are easy to forget about, and they live with the same company as the server.

`.env` and `secrets/` go somewhere offline

These two don't change often, so they don't belong in a nightly job. Copy them once to encrypted offline storage, and again whenever they change (new hot wallet identity, rotated secret):

sudo tar czf - -C /opt/coldtill .env secrets \
  | gpg --symmetric --cipher-algo AES256 > coldtill-keys-$(date +%F).tar.gz.gpg

Put that file wherever you keep things like recovery codes. Not in the same bucket as the dumps: the whole point is that someone who gets the dumps shouldn't also get the key that unseals them.

A note on secrets/: the hot-wallet identity in there is encrypted under your passphrase, but by default the passphrase sits next to it in secrets/hot_passphrase, so the sweeper and payouts processes can restart without you. If that combination in a backup makes you uneasy, you can run without a stored passphrase (coldtill init --store-passphrase=false) and type it at start-up. The trade-off is that if sweeper or payouts restarts, sweeps and payouts wait for you.

Actually restore it

A backup you've never restored is a hope, not a backup. Rent a spare VPS for an hour, install Docker, put back .env and secrets/ from the same point in time as the dump, then:

cd /opt/coldtill
sudo docker compose up -d postgres
gunzip -c coldtill-2026-11-03.sql.gz | sudo docker compose exec -T postgres psql -U coldtill coldtill
sudo docker compose up -d

Sign in, check two-factor still works, open the Payments page and compare a few rows against the live server. If the two-factor prompt fails, your .env and dump don't match, and you've just learned that cheaply.

After a test restore, the Payments page is the quickest sanity check: same invoices, same states, same filled amounts as production.

Monitoring: what to actually alert on

Uptime is the easy part. Coldtill exposes a health endpoint:

curl -fsS https://pay.example.com/healthz   # prints: ok

Point UptimeRobot, Better Stack, Healthchecks.io or whatever you already use at it. The api container has a Docker health check too.

The more useful signals are in the logs. They're JSON, one line per event, so plain grep goes a long way:

cd /opt/coldtill
sudo docker compose logs -f --since 1h api watcher sweeper payouts
sudo docker compose logs sweeper | grep '"level":"WARN"'

Here's what I'd page on, and why:

"level":"ERROR" from any process. The obvious one.
hot wallet … needs at least and sweep not possible. The hot wallet pays gas for sweeps. When it runs dry, sweeps stop. Nothing is lost (deposits sit safely on addresses that can only send to your cold wallet), but money piles up where it shouldn't, and payouts stop too.
filled a nonce gap. Coldtill fixes this itself with a zero-value self-transfer, but if you see it often, something is failing upstream.
conversion delivery mismatch. Only relevant if you've turned on auto-convert. A swap provider reported something Coldtill's own nodes couldn't match, so a human should look.
Payouts in needs-review. Coldtill also sends a payout.needs-review webhook, so if you already have a webhook receiver, route that event to wherever your team actually reads things.

A rough watcher, if you don't have a log pipeline yet:

#!/usr/bin/env bash
# run every 5 minutes from cron
cd /opt/coldtill
hits=$(docker compose logs --since 5m api watcher sweeper payouts 2>&1 \
  | grep -E '"level":"ERROR"|needs at least|sweep not possible|nonce gap|delivery mismatch' || true)
if [ -n "$hits" ]; then
  printf '%s\n' "$hits" | mail -s "coldtill alert on $(hostname)" ops@example.com
fi

It's crude, it'll repeat itself, and it's still much better than finding out from a customer.

The quiet failure: a chain watcher falling behind

The alert that's easy to forget is the one where nothing errors. If an RPC node is rate limiting you, or quietly serving stale data, the watcher just... sees blocks late. No crash, no error line, payments sitting in "pending" longer than they should.

The dashboard shows a "last block processed" per network under Nodes & networks. If one of those stops moving while the chain keeps going, your watcher is behind. The fix is usually the same: public RPC endpoints are fine for testing and rate limited for everything else, so for mainnet use your own nodes or a paid provider, and add at least two per network so failover has somewhere to go.

The overview shows confirmed volume and recent payments at a glance. A long run of "pending" here is often the first visible sign of a node problem.

A short checklist

Before mainnet, I want to be able to say yes to all of these:

Nightly dumps run, and land off the server.
.env and secrets/ are in encrypted offline storage, separate from the dumps.
I've restored onto a spare server at least once, and two-factor worked afterwards.
An uptime monitor is watching /healthz.
Something tells me about ERROR lines, hot wallet warnings and needs-review payouts.
Someone looks at hot wallet balances, and "last block processed", more than once a month.

None of this is exotic. It's the same discipline you'd apply to any Postgres-backed service. The difference is that with a payment server, the records are the product. The coins will be fine on chain either way; the question is whether you can still tell which customer paid for what.

Break your crypto checkout on testnet before a customer does

Coldtill — Sun, 01 Nov 2026 10:18:48 +0000

The first real crypto payment on a new shop is a bad time to find out your webhook handler only works when the customer pays the exact amount. Card payments mostly fail in tidy ways. Crypto payments fail in untidy ones: people send a bit too little, pay twice, pay after the link expired, or open a second checkout in another tab.

None of that is exotic, and all of it can be rehearsed with test coins before you switch anything on for real. This post is the test plan I run, with a tiny webhook receiver you can copy. I'm using Coldtill, the self-hosted gateway we build, so the field names and statuses below are its own, but the list of cases applies to any crypto checkout.

Set up a server you're allowed to break

Coldtill installs in testnet mode unless you tell it otherwise, and a testnet install is a separate server from your mainnet one. That's deliberate: you can be careless with it.

sudo apt install docker.io docker-compose-v2 curl
curl -fsSL https://coldtill.com/install.sh | sudo bash -s -- --edition free

The script fetches the Free release from the self-hosted crypto payment gateway repo on GitHub, checks its SHA-256 and starts everything in /opt/coldtill. Finish Get started in the dashboard: two-factor on your account, a cold wallet, and at least one deposit wallet.

In testnet mode each network code maps to its test network:

Code	Testnet
`ETH`	Sepolia
`BASE`	Base Sepolia
`POLYGON`	Amoy
`BSC`	BSC testnet
`TRON`	Nile
`SOL`	Devnet
`BTC`	Signet

I'd pick one network and stick with it for the whole run. Base Sepolia USDC is the easiest, because the amounts are in dollars and you don't have to think about price movements while you're reading logs. Sepolia ETH from a faucet works too. Get the test coins into an ordinary browser wallet that plays the customer.

Then create an API key and a webhook endpoint under API keys and Webhooks. On a testnet install, webhook endpoints can be plain http://localhost URLs, which saves you a tunnel. (Mainnet only accepts public https endpoints, so don't get attached to this.)

A receiver that logs everything

You don't need your real shop for the first pass. A thirty-line receiver that verifies the signature and prints what arrived tells you more, because nothing is hidden behind your order logic.

# receiver.py  (python3 receiver.py)
import hashlib, hmac, json, os, time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ["COLDTILL_WEBHOOK_SECRET"].encode()
seen = set()

def verify(headers, raw):
    ts = headers.get("X-Coldtill-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    want = "sha256=" + hmac.new(SECRET, ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, headers.get("X-Coldtill-Signature-V2", "").lower())

class Hook(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        if not verify(self.headers, raw):
            print("REJECTED bad signature", flush=True)
            self.send_response(401); self.end_headers(); return
        delivery = self.headers.get("X-Coldtill-Delivery")
        body = json.loads(raw)
        dup = " (repeat delivery)" if delivery in seen else ""
        seen.add(delivery)
        print(f'{body.get("timestamp_ms")} {body.get("invoice_id")} {body.get("status")} '
              f'filled={body.get("filled_amount_in_usd")} '
              f'conf={body.get("confirmation_current")}/{body.get("confirmation_required")}{dup}', flush=True)
        self.send_response(200); self.end_headers()

HTTPServer(("127.0.0.1", 8099), Hook).serve_forever()

Two details in there matter more than they look. The signature is computed over the timestamp plus the raw body, so read the bytes before you parse any JSON. And decide what happened from the signed body's status, not from the X-Coldtill-Event header, which isn't signed.

Run it somewhere the Coldtill server can reach, point the webhook at it (for example http://localhost:8099/), and press Webhooks â†’ Send test. You should see one line printed. Now change one character of the secret in your environment, restart, and send the test again. You want a REJECTED line. If a receiver happily accepts a forged request in testing, it'll do the same in production.

The cases

I create each payment with curl so I control the amount and the customer:

pay() {  # pay <customerID> <invoiceID> <usd> [expire]
  curl -s -X POST "$COLDTILL_URL/api/v1/payment" \
    -H "API-Key: $COLDTILL_API_KEY" -H 'Content-Type: application/json' \
    -d "{\"customerID\":\"$1\",\"invoiceID\":\"$2\",\"amountInUSD\":$3${4:+,\"expire\":\"$4\"}}"
  echo
}

Set COLDTILL_URL to your testnet server's site URL first. Then work down this list, one payment at a time.

1. The happy path. pay c1 T-001 5, open the returned url, pay exactly 5 USDC. Watch progress lines with climbing confirmation counts, then one final FILLED. This is the only case most people test.

The customer's first step: pick a network and coin. Note the expiry countdown under the button; case 4 below is about what happens when it reaches zero.

2. Too little. pay c2 T-002 5, send 3. You should get PARTIALLY_FILLED, and the checkout should ask for the remaining amount. Check that your shop does not ship. Then send the remaining 2 and confirm it moves to FILLED. Coldtill counts anything within 1% of the amount owed as filled, so a few cents of rounding from a wallet won't strand an order.

3. Too much. pay c3 T-003 5, send 6. Expect OVER_FILLED. Treat it as paid. Whether you refund the extra is a business decision, but your code needs to know this status exists, or the order sits there looking unpaid.

4. Nobody pays. Create one that expires soon. The expire field takes an RFC 3339 time at least a minute ahead:

pay c4 T-004 5 "$(date -u -d '+3 minutes' +%Y-%m-%dT%H:%M:%SZ)"

Wait, and you should see CANCELLED. Your shop should cancel the order or offer a new link. (The default expiry is 24 hours, which is why nobody ever tests this.)

5. Pays after the deadline. Now send funds to the expired payment from case 4. The payment stays closed. You'll get a progress event showing a new filled_amount, and no FILLED. This one needs a human decision, so make sure it lands somewhere a human will see it rather than in a log nobody reads.

6. Changes their mind. pay c5 T-005 5, then immediately pay c5 T-006 7 for the same customer. A customer has at most one open payment, so the first becomes REPLACED. Ignore it in your shop; the newer one carries on.

7. Changes their mind mid-payment. Same as above, but send coins to the first one and create the second while the deposit is still confirming. The API answers 409 rather than replacing a payment with money on its way. Your checkout should show something like "try again in a few minutes" instead of a stack trace.

8. The same event twice. Under Webhooks â†’ Deliveries you can resend any delivery by hand. Resend the FILLED from case 1. The receiver will flag it as a repeat; your real handler has to make it a no-op. Final events are retried for up to two days if your endpoint doesn't answer, so idempotency isn't optional.

9. Your endpoint is down. Stop the receiver, pay a fresh invoice, and start it again a few minutes later. The final event isn't lost: after two quick retries the next attempt comes 30 minutes later, then at growing intervals for two days. (If you're impatient, resend it from Deliveries.) Progress events only retry twice, so don't build anything that depends on seeing every one of them.

10. Events out of order. Delivery order isn't guaranteed. Sort by timestamp_ms (two events can share a second) and never let an older progress event overwrite a final status.

The Payments list after a test run. Partial, over-filled and cancelled payments are all there to compare against what your shop recorded.

Then plug in the real shop

Once the receiver behaves, swap it for your shop's real endpoint and run the same ten cases again, this time checking order statuses instead of printed lines. Add one more check per case: the reference_id in the webhook must match the one you stored for that invoice_id. Without that, a late event from an old payment can mark a newer order paid.

What testnet can't tell you

A few things only show up on mainnet, so plan for them rather than assume they're covered:

Auto-convert is hidden in testnet mode, because the swap providers only run on mainnet. If you'll take coins through it, test that flow with a small real payment.
Public RPC defaults are fine for testing and rate limited for anything else. Add your own or paid nodes before go-live, ideally more than one per network.
Your real network. DNS, TLS, a firewall that only lets the office in, or a webhook URL with a stray www will all pass on localhost.

So the last step is always the same: install the mainnet server separately with --mode mainnet --site-url https://pay.yourshop.com, point the shop at it and pay yourself $1. If that dollar shows up as FILLED in your shop and in your cold wallet, you've done more testing than most crypto checkouts ever get.

The webhook and API details used above are in the Coldtill docs, if you want to check a field before relying on it.

Adding a crypto checkout to WooCommerce without signing up for a processor

Coldtill — Sat, 31 Oct 2026 10:07:23 +0000

Most guides to taking crypto in WooCommerce start the same way: create an account with a payment processor, upload your company documents, wait for a review, then install their plugin and paste in an API key. The plugin is the easy part. The account is what slows you down, and it's also the thing that can be closed later.

This walkthrough takes a different route. The plugin talks to a payment server you run yourself, so there's no account to apply for. I'll use Coldtill, the gateway we build, and its WooCommerce plugin. It's a short job, but there are a few details (store currency, webhook URLs, partial payments) that are worth knowing before a real customer finds them for you.

What you need

On the WordPress side:

WordPress 6.4 or later, WooCommerce 8.0 or later, PHP 8.1 or later
Store currency set to USD. Coldtill prices payments in US dollars, so the gateway simply doesn't show up at checkout if your store uses another currency. This is the most common "I installed it and nothing happened" moment.

On the payment side, a Coldtill server: a Linux box with Docker. 2 vCPU and 4 GB of memory is plenty, on amd64 or arm64. Put it on its own small VPS, not on the machine that runs WordPress. If a plugin vulnerability ever gets someone into your shop, it shouldn't hand them the payment server too.

1. Install the payment server

The Free edition installs with one command and doesn't need an account:

# Ubuntu or Debian
sudo apt install docker.io docker-compose-v2 curl
curl -fsSL https://coldtill.com/install.sh | sudo bash -s -- --edition free

The script pulls the latest release from the Coldtill/self-hosted-crypto-payment-gateway repository, checks its SHA-256 against the published checksums and starts the stack in /opt/coldtill. It installs on testnet by default, which is exactly what you want while wiring up the shop. When you're ready for real money, you install with --mode mainnet --site-url https://pay.yourshop.com.

Once it's up, the dashboard's Get started page walks you through adding a cold wallet and at least one deposit wallet. One habit worth forming here: when the dashboard shows you the first deposit address it derived, check it against your own wallet before you share a single payment link.

A quick sanity check from your laptop:

curl -s https://pay.yourshop.com/healthz

If that answers, the shop will be able to reach it too.

2. Install the plugin

The plugin is MIT-licensed and lives in its own repo. Grab coldtill-woocommerce.zip from the latest WooCommerce plugin release and upload it under Plugins → Add New → Upload Plugin, then activate it.

If you manage WordPress from the command line, WP-CLI can install straight from the release URL:

wp plugin install \
  https://github.com/Coldtill/woocommerce-crypto-payment-gateway/releases/latest/download/coldtill-woocommerce.zip \
  --activate

It supports both the classic checkout and the block-based checkout, and it's compatible with WooCommerce's high-performance order storage (HPOS), so you don't need to switch anything back to make it work.

3. Create an API key, and make it a payments-only one

In the Coldtill dashboard, open API keys and create a new key for the project. Coldtill keys come in two scopes:

Payments only: create payments and read their status.
Full access: everything above, plus sending payouts.

A shop plugin only needs the first. Pick payments-only here. The scope can't be changed after the key is created, so if you get it wrong, make a new key and revoke the old one. The key is shown once; paste it straight into WordPress.

In WooCommerce → Settings → Payments → Coldtill, enter your Coldtill URL (for example https://pay.yourshop.com) and the key.

4. Connect the webhook

The plugin settings show a webhook URL under "Webhook secret". It ends in /wc-api/coldtill/, something like:

https://shop.example.com/wc-api/coldtill/

Back in Coldtill, go to Webhooks, add an endpoint with that URL, copy the signing secret it gives you (also shown once) and paste it into the plugin settings.

The plugin verifies every webhook with HMAC-SHA256 over a timestamp and the body, and rejects anything with a bad signature or a timestamp outside the replay window. You don't have to write that code, but it's worth knowing it's there, because it explains one failure mode: if your WordPress server's clock is badly off, valid webhooks will be refused.

Two other things that bite here:

Redirects aren't followed. If http:// redirects to https://, or shop.example.com redirects to www.shop.example.com, the webhook won't arrive. Use the exact final URL.
On mainnet, the URL has to be public HTTPS. Coldtill refuses private and reserved addresses. On a testnet install you can point it at http://localhost while you develop.

5. What happens at checkout

When a customer chooses crypto, the plugin creates a payment on your server. It sends the order total in USD, the order number, the billing email, an internal customer id (the WordPress user id, or the order id for guests) and the order-received page address for the checkout's return button. Nothing goes to any other service.

The customer lands on your own checkout page, picks a network and coin, and gets a QR code and an exact amount.

The customer picks a network and currency on your own checkout page. The invoice number comes from the WooCommerce order.

Because the customer id is stable, a returning logged-in customer gets the same deposit addresses as before. On Ethereum, Base, Polygon, BNB Chain, Tron and Solana those addresses are deposit contracts that can only send to your cold wallet; Bitcoin goes to addresses from your own wallet's public key.

6. How order statuses map

This is the part I'd read twice. Coldtill payments have a handful of states, and the plugin maps them onto WooCommerce like this:

Coldtill payment	WooCommerce order
Filled or overpaid	Processing (payment complete)
Partially paid	On hold
Cancelled or replaced	Cancelled

A few notes from the docs that matter in practice:

Filled means the confirmed amount is within 1% of what's owed. Overpaid means more than 1% above it. Both mean "ship it". If someone overpays, the plugin notes it on the order; you can refund the difference with a payout if you want to.
Partially paid usually means the customer sent too little, often because their exchange took a withdrawal fee off the top. The checkout page asks them for the rest, and the order sits On hold until they send it.
Cancelled happens when a payment expires unpaid. The default expiry is 24 hours.
Replaced means the same customer started a new payment, which supersedes the old one.

There's also a safety check: the order only changes when the payment's reference and amount match the order. If the amount Coldtill reports doesn't match the order total, the plugin adds a note and leaves the order alone rather than guessing. (Version 1.0.2 fixed a case where a payment exactly one cent off the total was left pending; it's now marked paid as intended.)

The Payments page in the Coldtill dashboard. Each row lines up with a WooCommerce order through its invoice number, so a "partially filled" here is an "On hold" in WooCommerce.

7. When a webhook goes missing

Webhooks fail for boring reasons: a deploy, a firewall rule, a security plugin that dislikes POST requests. Coldtill retries final events on a long schedule (up to two days), and you can resend any delivery by hand under Webhooks → Deliveries.

The plugin also has a fallback: when the customer comes back to the order-received page, it asks the server for that payment's status, so the order still updates even if the webhook never arrived.

If you're debugging an order that looks stuck, you can ask the server directly with the payment's reference id. It's the last part of the checkout link (/pay/<reference_id>), which the dashboard's Payments page links to:

curl -s \
  -H "API-Key: $COLDTILL_API_KEY" \
  https://pay.yourshop.com/api/v1/payment/reference/fd09c7e5-d661-4355-9b04-7b3749b41e2e

The response includes the status and the deposits with their confirmation counts, which usually tells you straight away whether the problem is the chain (still confirming) or the shop (webhook not getting through).

8. Test before you go live

My usual order:

On the testnet install, use Webhooks → Send test to post a signed test event to the shop and confirm it's accepted.
Place a real order on the store and pay it with Base Sepolia USDC or Sepolia ETH from a faucet. Watch the order go from Pending to Processing.
Pay too little on a second order and check it lands On hold.
Let a third one expire, or create a payment with a short expiry through the API, and check it ends up Cancelled.
Reinstall on mainnet, point the plugin at it, and pay yourself $1 before you announce anything.

That last step catches more than you'd think: DNS, certificates, a firewall that only lets your office in, a webhook URL with a stray www.

Wrapping up

The plugin itself is small. Most of the work is in the server it talks to and in understanding the order states, and once those are clear there isn't much to maintain. If you'd rather read the code before installing anything on a production store, the plugin is in the woocommerce-crypto-payment-gateway repo, and the full setup docs are at coldtill.com/docs.

Never mark a crypto order paid twice: confirmations, reorgs and out-of-order webhooks

Coldtill — Thu, 29 Oct 2026 10:03:45 +0000

A classic crypto checkout bug goes like this. A webhook comes in, the shop marks the order paid, a retry of the same webhook arrives four seconds later, and a second fulfilment job goes into the queue. It's easy to write, easy to miss in testing, and it's a good reason to think properly about what "paid" means when the money moves on a blockchain.

Card payments trained most of us to treat a payment as a single yes/no event. On-chain payments are messier. A transfer is seen, then it gathers confirmations, and once in a while the block it landed in disappears. Customers send too little, or too much, or pay again an hour after the invoice expired. Your webhook receiver has to make sense of all of that, often out of order.

This post is about the order-system side of that problem. I'll use the event model from Coldtill, the self-hosted gateway we build, because it's the one I know in detail, but the ideas carry over to most gateways.

What happens between "sent" and "paid"

From the gateway's side, a single payment goes through roughly these stages:

Seen. A transfer to the customer's deposit address shows up in a block (or, for Bitcoin, in the address history from an Esplora node).
Confirming. Each new block adds a confirmation. Every network has its own required count.
Confirmed. Once there are enough, the deposit counts toward what the customer owes.
Reorged, occasionally. If the block holding the transfer drops off the canonical chain, the deposit isn't confirmed any more.

In Coldtill's watcher, a deposit whose block disappears in a reorg goes back to pending, and one whose transaction vanishes entirely is marked orphaned and reversed. Block hashes are re-checked as confirmations are counted, rather than just counting block heights.

The important thing for your shop: you should never have to reason about any of that yourself. If your order code is counting confirmations, the gateway is leaking a concern it should own. What you want is a payment-level state that only reaches "paid" after the chain-level work is done.

Payment states, not transfer events

Coldtill reduces all of the above to a small set of payment states:

State	Meaning	Final
`OPEN`	Nothing confirmed yet	no
`PARTIALLY_FILLED`	Confirmed amount below 99% of what's owed	no
`FILLED`	Confirmed amount within 1% of what's owed	yes
`OVER_FILLED`	More than 1% above what's owed	yes
`CANCELLED`	Expired before being filled (24 hours by default)	yes
`REPLACED`	Superseded by a newer payment for the same customer	yes

Ship on FILLED or OVER_FILLED. Everything else is either "keep waiting" or "this order isn't going to be paid through this link".

That 1% tolerance is worth a second look. Customers paying in a volatile coin, or paying from an exchange that shaves a little off, will rarely hit the exact figure. Deciding up front how close is close enough saves a lot of support emails.

The payments list in the Coldtill dashboard, with filled, partially filled, pending and expired payments side by side

The four things that break naive receivers

1. Retries

Webhooks are delivered at least once, not exactly once. Coldtill retries progress events after 2 and 4 seconds, and final events on a longer schedule (2 s, 4 s, 30 min, 1 h, 2 h, 4 h, 8 h, 24 h, 48 h) before marking them failed. A retry reuses the same X-Coldtill-Delivery ID, so that's your cheapest dedupe key.

2. Ordering

Delivery order isn't guaranteed. A progress event can arrive after the final one if the first attempt of the progress event failed and was retried. The payload carries timestamp_ms, and the docs say to order by that rather than timestamp, because two events can share a second.

3. Late money

Once a payment is closed, it stays closed. A deposit that lands after the payment is CANCELLED still counts toward the filled amount, but doesn't reopen it; you get a progress event with the new filled_amount. If you ignore everything after the final event, you'll never notice customers who paid late, and those are exactly the ones who email you angry.

4. Trusting the wrong field

The event name header and the delivery ID header are not signed. Only the body is. So the decision "is this order paid?" has to come from the signed body's status and reference_id, never from X-Coldtill-Event.

A receiver that survives all four

Here's the shape I'd use. It's TypeScript with Express and Postgres, and it uses the SDK's verifier as shown in the webhook docs. The SQL is the part that matters; adapt it to whatever you run.

import express from 'express'
import { verifyWebhookRequest, isPaid } from '@coldtill/sdk'
import { pool } from './db'

const app = express()

app.post('/coldtill/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  let ev
  try {
    ev = await verifyWebhookRequest(req.body, req.headers, process.env.COLDTILL_WEBHOOK_SECRET!)
  } catch {
    return res.sendStatus(401)
  }
  if (!ev.event.startsWith('payment.')) return res.sendStatus(200)

  const delivery = String(req.headers['x-coldtill-delivery'] ?? '')
  const p = ev.data

  const client = await pool.connect()
  try {
    await client.query('BEGIN')

    // Dedupe retries. The delivery ID isn't signed, so it's only used to skip work,
    // never to decide anything.
    const seen = await client.query(
      'INSERT INTO webhook_seen (delivery_id) VALUES ($1) ON CONFLICT DO NOTHING',
      [delivery]
    )
    if (seen.rowCount === 0) {
      await client.query('COMMIT')
      return res.sendStatus(200)
    }

    // Keep the newest view of the payment. Older events that arrive late can't
    // overwrite newer state.
    await client.query(
      `INSERT INTO crypto_payments (reference_id, order_id, status, filled_usd, event_ms)
       VALUES ($1, $2, $3, $4, $5)
       ON CONFLICT (reference_id) DO UPDATE
         SET status = EXCLUDED.status, filled_usd = EXCLUDED.filled_usd, event_ms = EXCLUDED.event_ms
         WHERE crypto_payments.event_ms < EXCLUDED.event_ms`,
      [p.reference_id, p.invoice_id, p.status, p.filled_amount_in_usd, p.timestamp_ms]
    )

    // Fulfil once. The unique order_id on fulfilments is what actually
    // stops a second shipment, whatever happens above.
    if (isPaid(p.status)) {
      await client.query(
        `INSERT INTO fulfilments (order_id, reference_id) VALUES ($1, $2)
         ON CONFLICT (order_id) DO NOTHING`,
        [p.invoice_id, p.reference_id]
      )
    } else if (p.status === 'CANCELLED' && Number(p.filled_amount_in_usd) > 0) {
      await client.query(
        `INSERT INTO payment_followups (reference_id, reason) VALUES ($1, 'late or short payment')
         ON CONFLICT DO NOTHING`,
        [p.reference_id]
      )
    }

    await client.query('COMMIT')
    res.sendStatus(200)
  } catch (err) {
    await client.query('ROLLBACK')
    res.sendStatus(500) // let the gateway retry
  } finally {
    client.release()
  }
})

A few choices in there are deliberate:

Three layers of idempotency. The delivery table skips cheap repeats. The event_ms guard stops stale events overwriting fresh ones. The unique constraint on fulfilments.order_id is the real safety net. If the first two have a bug, the third still holds.
Everything in one transaction. If the process dies halfway, nothing is half-recorded, and the 500 makes the gateway try again.
Late money goes to a human. I don't auto-ship on a cancelled payment with money on it, because the price, the stock or the customer's intent may have changed. A follow-up queue is cheaper than guessing.
Respond fast. Coldtill wants a 2xx within 60 seconds. If fulfilment is slow, insert a job and let a worker do it.

Replacing a payment safely

One more case that surprises people. In Coldtill, each customer has at most one open payment, and creating a new one replaces the previous (REPLACED). But if the old payment has a deposit still confirming, POST /api/v1/payment returns 409 instead, so that money isn't stranded on a dead invoice.

In practice this shows up when a customer abandons checkout, changes their basket and comes back while the first transfer is still confirming. Treat the 409 as "wait and retry", not as an error page. Something like "Your previous payment is still confirming, we'll update this page in a minute" is far better than a stack trace.

Don't fulfil from the return page

The hosted checkout has a "Return to store" button, and it's tempting to mark the order paid when the customer lands back on your thank-you page. Don't. Anyone can open that URL. The docs are blunt about it: opening the return URL tells the gateway nothing. Fulfil from the verified webhook, or from GET /api/v1/payment/reference/{reference_id} if you need to poll as a fallback.

The customer's view while a payment confirms: exact amount, QR code and confirmation progress

A quick test plan

Before going live I run through this list on testnet:

Pay the exact amount and check exactly one fulfilment row appears.
Use Webhooks â†’ Deliveries to resend the final event by hand and check nothing changes.
Pay half, then the rest, and watch the order move from partially filled to filled.
Let a payment expire, then pay it, and check it lands in the follow-up queue rather than shipping.
Stop your receiver for a few minutes during a payment and confirm the retries catch up.

None of this is glamorous, but it's the difference between a crypto checkout you trust and one you check by hand every morning. If you want to see how the states look in a real dashboard, the live demo is linked from coldtill.com, and the webhook docs have verifier snippets for Node, PHP, Go and Python. I'm happy to answer questions in the comments.

How to accept crypto payments on your own server with Docker

Coldtill — Sun, 25 Oct 2026 11:49:14 +0000

Most guides to taking crypto in a web shop start with "sign up for a processor". You paste an API key, the processor hosts the checkout, and the money lands in an account they control until they pay you out. That works, but it means an application, a review, a fee on every sale and a third party that can freeze the balance.

I wanted the opposite: a checkout that runs on a box I own, where the coins go straight into my own wallet and nothing in the middle can hold them. That's what we built with Coldtill, and this post walks through how that kind of setup works and what to watch out for when you wire it into a shop.

What "self-hosted" and "non-custodial" actually mean

They get used interchangeably, but they're different promises.

Self-hosted means the software runs on your infrastructure. Your server, your database, your logs. Customer data never leaves it.
Non-custodial means nobody but you controls the funds. Not the software vendor, and ideally not even the server the software runs on.

The second one is the hard part. A gateway can be self-hosted and still keep a hot wallet full of customer payments on the same machine that faces the internet. If someone breaks into that machine, the money goes with them.

The architecture

Coldtill ships as Docker containers and runs on an ordinary Linux VPS. Two vCPU and 4 GB of RAM is comfortable, on amd64 or arm64. Under the hood it's split into separate processes that share a PostgreSQL database and never call each other directly:

api: the merchant REST API, the dashboard and the hosted checkout page. This is the only part exposed to the internet, and it holds no private keys.
watcher: follows the chains, counts confirmations, handles reorgs and sends your webhooks.
sweeper: moves funds from deposit addresses to your cold wallet.
payouts: signs approved refunds and payouts from a small hot wallet.

The processes that hold keys accept no network connections. So the piece an attacker can reach first has nothing worth stealing.

The other half of the design is where deposits go. Every customer gets their own deposit address. On EVM chains, Tron and Solana, that address is a contract that can only send to your cold wallet. Bitcoin addresses are derived from your own wallet's public key. The server can't change the destination, which means a compromised server still can't redirect a payment.

The payment flow

From your shop's point of view it's four steps:

Your backend calls POST /api/v1/payment with an amount and your order ID and gets back a checkout URL.
You redirect the customer there. They pick a coin and network, scan a QR code and pay.
The watcher waits for confirmations and sends your shop a signed webhook.
Later, the sweeper moves the funds to your cold wallet.

Out of the box it handles native coins and USDC/USDT on the main chains. If you turn on auto-convert, customers can pay with 200+ coins across 35+ chains and you still receive a stablecoin, so you never end up holding a token you didn't choose.

Handling the webhook (the part people get wrong)

Webhooks are where shops usually get burned: they trust the JSON body, parse it before verifying, or mark an order paid twice because a delivery was retried. The rules are boring but important:

Read the raw body before any JSON parsing.
Reject timestamps that are too old, so a captured request can't be replayed.
Recompute the HMAC over the timestamp and body and compare it in constant time.
Treat events as idempotent. Retries happen, and ordering isn't guaranteed.
Decide what to do from the signed body, not from an unsigned header.

Here's an illustrative Express handler in TypeScript. It follows the signing scheme described in Coldtill's webhook docs, but check the docs for the current header names and payload before you copy it into production, and prefer the official SDK's verifier if you're on Node.

// Illustrative only. See the webhook docs for the current scheme.
import express from 'express'
import crypto from 'node:crypto'

const app = express()
const SECRET = process.env.COLDTILL_WEBHOOK_SECRET!

app.post('/coldtill/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ts = String(req.headers['x-coldtill-timestamp'] ?? '')
  const sig = String(req.headers['x-coldtill-signature-v2'] ?? '').toLowerCase()

  // 1. Reject stale or malformed timestamps (five-minute window).
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return res.sendStatus(401)
  }

  // 2. HMAC over "<timestamp>.<raw body>", compared in constant time.
  const expected = 'sha256=' + crypto
    .createHmac('sha256', SECRET)
    .update(`${ts}.`)
    .update(req.body as Buffer)
    .digest('hex')
  const ok = expected.length === sig.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))
  if (!ok) return res.sendStatus(401)

  // 3. Only now parse, and act on the signed body.
  const event = JSON.parse((req.body as Buffer).toString('utf8'))
  if (event.status === 'FILLED' || event.status === 'OVER_FILLED') {
    await markOrderPaid(event.invoice_id) // must be idempotent
  }
  res.sendStatus(200)
})

Make markOrderPaid safe to call twice. A unique constraint on the order ID or the delivery ID is usually enough.

Things to sort out before you take real money

A self-hosted crypto payment gateway puts operations on you, so a short checklist:

Run it on its own server, not next to your shop. A hole in your storefront shouldn't reach the hot wallet.
Keep the dashboard off the public internet. Put the checkout on a public subdomain like pay.yourshop.com and the admin behind a VPN such as Tailscale, or at least a firewall rule.
Back up the database and take provider snapshots.
Test on testnet first and send yourself a test webhook before you flip to mainnet.

Pricing, for the curious

The Free edition takes a 2% fee, Standard is $499 one-time with a 1% fee, and Pro is $999 one-time with no fee. Bitcoin and auto-converted payments carry no fee on any edition. There's no licence server; it keeps running even if our site goes down. The WooCommerce plugin is MIT-licensed on GitHub; the core app is proprietary under an EULA.

If you want to poke around before installing anything, there's a live demo dashboard with made-up data linked from coldtill.com. Questions about the architecture are very welcome in the comments.

DEV Community: Coldtill

USDT on Tron and the energy bill: what sweeping TRC-20 deposits really costs

Two resources, not one gas price

Why sweeps make this worse

What the sweeper needs to decide

Keep the hot wallet small and boring

Where the money is allowed to go matters more than the fee

A checklist if you're building this yourself

Pricing in dollars, paid in crypto: decimals, rounding and the one-cent problem

Store money as integers, in the unit the chain uses

Decide who rounds, and in which direction

Exact amounts beat "about this much"

Stablecoins mostly make this go away (mostly)

Pick a tolerance and write it down

Keep one source of truth for "paid"

The short version

Your own node or someone else's RPC? What a crypto payment watcher should trust

What the watcher really decides

The failure modes of borrowed data

A sensible split: settle on what you verify

What "enough confirmations" means in practice

Then tell your shop, once

The cost side, honestly

Updating a self-hosted payment gateway without losing a payment

Two things you should know before you start

Pick your window by looking at your own payments

A checklist I'd actually follow

What to verify afterwards

Watch the plugin side too

Rolling back

The boring conclusion

Integrating a self-hosted crypto gateway without a plugin: the REST API path

What you are integrating with

The integration shape

Creating a payment

Signed webhooks without getting burned

OpenAPI and the TypeScript SDK

Fitting it into a real stack

Custom storefront / headless cart

SaaS billing / invoices

Mixed fleet

What the API deliberately cannot do

A short checklist before you go live

The short version

Many shops, one server: running several crypto checkouts from a single Coldtill install

Why projects exist

What stays separate (and why)

Wallets

API keys

Webhooks

Branding and checkout domain

Team roles across shops

A practical layout

How a payment stays in its lane

Things that bite when you add a second shop

When one server is enough (and when it isn't)

What I'd do on day one of a second shop

What to back up (and watch) when you self-host a crypto payment gateway

Four things, four different failure modes

Where things live

Nightly database dumps

Get the dumps off the box

.env and secrets/ go somewhere offline

Actually restore it

Monitoring: what to actually alert on

The quiet failure: a chain watcher falling behind

A short checklist

Break your crypto checkout on testnet before a customer does

Set up a server you're allowed to break

A receiver that logs everything

The cases

Then plug in the real shop

What testnet can't tell you

Adding a crypto checkout to WooCommerce without signing up for a processor

What you need

1. Install the payment server

2. Install the plugin

3. Create an API key, and make it a payments-only one

4. Connect the webhook

5. What happens at checkout

`.env` and `secrets/` go somewhere offline