DEV Community: Coldtill

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.