A crypto payment gateway is simpler than it looks and harder than it sounds: at its core it turns "charge $49" into "watch address X for exactly 0.00051 BTC and tell the store when it arrives." This guide walks through the reference architecture of a non-custodial gateway — the same shape crypt.pe runs in production — so developers can evaluate gateways honestly or reason about building one.
the five components every gateway needs
Strip away branding and every crypto gateway is five subsystems working in a loop:
| component | job | failure mode if done badly |
|---|---|---|
| order engine | locks amount, asset, network and price at creation | stale quotes, disputed totals |
| address layer | assigns the receiving address (merchant-owned in non-custodial designs) | wrong-network payments, address reuse |
| chain watchers | one monitor per network, polling nodes/RPCs for matching transfers | missed or double-counted payments |
| confirmation logic | waits for depth proportional to amount before marking paid | reorg-faked settlements |
| webhook dispatcher | signs and delivers payment events to the merchant backend | spoofable or silently dropped events |
In a custodial gateway the address layer points at the processor's own hot wallets and a payout system is bolted on. In a non-custodial gateway like crypt.pe, the address layer points at wallets the merchant configured — settlement and custody collapse into the same step, which is why there is no payout schedule to build or trust.
the life of one order
A production flow looks like this: 1) the store POSTs an order with a fiat amount and gets back an order id plus a hosted checkout URL; 2) the gateway locks the crypto amount from a fresh rate quote and shows the payer one address with its network labelled; 3) chain watchers poll for a transfer matching the exact amount, correct asset and correct address, postdating the order; 4) small amounts confirm on first inclusion, larger ones wait for confirmation depth; 5) a signed webhook fires and the store fulfils. Every step is stateless enough to retry, and one on-chain transaction can only ever satisfy one order — the property that stops replay tricks.
Exact-amount matching is the subtle part. Two simultaneous invoices for the same merchant must never resolve to the same expected amount on the same address — gateways solve this with unique addresses per order, tiny amount offsets, or both.
webhooks: sign them or they're decoration
A webhook that isn't verifiable is a security hole: anyone who learns the endpoint can mark orders paid. The standard design — which crypt.pe implements — is an HMAC SHA-256 signature over a timestamp plus the raw body, delivered in a header (crypt.pe uses X-Cryptpe-Signature with t=<unix-ts>,v1=<hex>). The merchant recomputes the HMAC with their webhook secret, compares in constant time, and rejects stale timestamps to kill replays. Idempotency keys on the merchant side handle redelivery.
what you'd have to run yourself
Self-hosting this stack (the BTCPay Server route) means operating nodes or paid RPC endpoints per chain, keeping watchers alive 24/7, handling chain reorgs, rotating addresses, and monitoring it all. That's the honest cost behind "free and open source". A hosted non-custodial gateway keeps the same trust model — funds still settle only to your wallets — while someone else runs the watchers. Evaluate any gateway by asking: who holds keys, how are exact amounts matched, how are webhooks signed, and what happens during a reorg.
frequently asked
What is the architecture of a crypto payment gateway?
Five subsystems: an order engine that locks amount and asset at creation, an address layer that assigns the receiving address, per-network chain watchers, confirmation-depth logic, and a signed webhook dispatcher. In a non-custodial design the addresses belong to the merchant, so settlement and custody are the same step.
How does a gateway know an invoice was paid?
Chain watchers poll each network for a transfer matching the exact expected amount, the correct asset and the locked address, postdating the order. Larger amounts additionally wait for confirmation depth so a chain reorg can't fake a settlement, and one transaction can only ever satisfy one order.
How should crypto payment webhooks be secured?
With an HMAC SHA-256 signature over a timestamp and the raw request body, verified against the merchant's webhook secret in constant time, plus timestamp freshness checks against replays. crypt.pe delivers this as X-Cryptpe-Signature: t=<timestamp>,v1=<hex>.
Should I build a gateway or use one?
Building means running per-chain nodes or RPCs, 24/7 watchers, reorg handling and address management. Self-host with BTCPay Server if you want full control and accept the ops cost; use a hosted non-custodial gateway like crypt.pe if you want the same custody model — funds settle only to your wallets — without operating the infrastructure.
