When building a crypto payment gateway, developers uncover non-obvious problems. Blockchain reorganizations can cancel transactions that were already considered confirmed. Wrong key storage model—and security is compromised. Lack of connector architecture with circuit breakers leads to SLA drops. In practice, one client lost $200k due to a reorg—we accounted for that in our architecture. Designing before writing code saves months of rework, and solid documentation forms the foundation for scaling. We bring 10+ years of blockchain development and 50+ implemented fintech projects. We build gateways that handle up to 10,000 transactions per hour. We'll assess your project in one day—get in touch.
How to Choose Between Custodial and Non-Custodial Schemes?
Before drawing diagrams, you need to answer questions that determine everything else. Compare both approaches:
| Characteristic | Custodial | Non-Custodial |
|---|---|---|
| Key control | Gateway manages client keys | Merchant manages keys, gateway only monitors |
| Legal responsibility | High, requires data processing license | Low, license not required |
| Architecture complexity | Maximum—HSM/KMS, signing service, compliance | Minimum—only blockchain monitoring |
| Time to launch | Months (license, audit) | Weeks |
Choose a custodial scheme if you need full control over user funds and are ready for regulatory requirements. Choose non-custodial if the merchant wants to manage risks themselves and the gateway only ensures payment confirmation.
Fundamental Requirements
Network selection determines infrastructure. Bitcoin's UTXO model is incompatible with the EVM account model. TON has its own VM. Each network adds operational load.
Settlement model: does the merchant receive crypto as-is, or does the gateway convert to fiat? Conversion introduces exchange rate risk and requires exchange/OTC integration.
Volume and SLA: 100 transactions/day vs 100,000 require different architectures. SLA 99.9% (8.7 hours downtime/year) vs 99.99% (52 minutes/year) are fundamentally different redundancy requirements.
Component Architecture
┌─────────────────────────────────────────────────────────────┐
│ Merchant-facing API │
│ REST / Webhooks / SDK libraries │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────────────┐
│ Core Services │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │Invoice Service│ │Address Alloc │ │ Exchange Rate │ │
│ │(create/query) │ │(HD wallet │ │ Service │ │
│ └──────────────┘ │ derivation) │ └──────────────────┘ │
│ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │Confirmation │ │Settlement │ │ Notification │ │
│ │Tracker │ │Service │ │ Service │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
└───────────┬──────────────────────────────────┬──────────────┘
│ │
┌───────────▼──────────┐ ┌────────────▼──────────────┐
│ Blockchain Layer │ │ Data Layer │
│ │ │ │
│ BTC Connector │ │ PostgreSQL (orders,txns) │
│ EVM Connector │ │ Redis (rates, sessions) │
│ TON Connector │ │ Message Queue (Kafka/RMQ) │
│ TRON Connector │ └────────────────────────────┘
└──────────────────────┘
Core Services: Invoice and Address
Invoice Service manages the state machine: created → address_assigned → payment_detected → confirming → confirmed → settled | expired | failed. Each invoice stores exchange_rate_expires_at separately from expires_at—this allows rate updates without recreating the invoice.
interface Invoice {
id: string;
merchant_id: string;
external_order_id: string;
requested_currency: 'USD' | 'EUR';
requested_amount: Decimal;
payment_currency: 'BTC' | 'ETH' | 'USDT_ERC20' | 'USDT_TRC20';
payment_network: 'bitcoin' | 'ethereum' | 'tron';
payment_address: string;
payment_amount: Decimal;
exchange_rate: Decimal;
exchange_rate_expires_at: Date;
status: InvoiceStatus;
received_amount: Decimal;
tx_hash: string | null;
confirmations: number;
required_confirmations: number;
created_at: Date;
expires_at: Date;
confirmed_at: Date | null;
settled_at: Date | null;
}
Address Allocation uses an HD wallet with BIP-44. Pre-generation in batches of 1000 addresses avoids delays when creating invoices. Critical rule: one address—one invoice. Even if an invoice expires, the address is not reused. For more on BIP-44, see the specification.
CREATE TABLE address_pool (
id BIGSERIAL PRIMARY KEY,
network VARCHAR(20) NOT NULL,
coin_type INTEGER NOT NULL,
address_index BIGINT NOT NULL,
address VARCHAR(200) NOT NULL,
allocated_at TIMESTAMPTZ,
invoice_id UUID REFERENCES invoices(id),
UNIQUE(network, address_index)
);
Blockchain Connectors: How to Ensure Reliability
All connectors implement a common interface. For EVM networks, a single instance with dynamic RPC endpoint rotation via a circuit breaker—after 3 failed attempts, it switches to a backup.
interface BlockchainConnector {
watchAddress(address: string, callback: (tx: IncomingTransaction) => void): () => void;
getTransaction(txHash: string): Promise<TransactionDetail>;
getConfirmations(txHash: string, blockNumber: number): Promise<number>;
buildSweepTransaction(from: string, to: string, amount: bigint): Promise<UnsignedTx>;
broadcastTransaction(signedTx: string): Promise<string>;
validateAddress(address: string): boolean;
estimateFee(): Promise<bigint>;
}
The EVM connector processes transactions 10 times faster than Bitcoin due to the absence of the UTXO model. For TRON, we use tronweb.
Example connector configuration with circuit breaker
When initializing the connector, a list of RPC endpoints is passed. For each endpoint, an error counter is maintained. When the threshold is exceeded, the endpoint is marked unavailable for a specified period. A health-check runs in parallel to restore the endpoint after a successful response.
Why Reorganization Handling Is Critical for a Gateway?
A reorg—blocks you already processed become non-canonical. A transaction believed to be confirmed disappears. Protection: never mark an invoice as settled with fewer confirmations than the safe threshold.
| Network | Safe Confirmations | Approximate Time |
|---|---|---|
| Bitcoin | 3 (small) / 6 (large) | 30-60 min |
| Ethereum | 12-15 | 3-4 min |
| Polygon | 128 (until checkpoint) | 5-7 min |
| Arbitrum | 1 (optimistic, L2) | 15 sec |
| TRON | 20 | 1 min |
According to Bitcoin Wiki, for large transactions 6 confirmations are recommended. Additionally: store block_hash along with tx_hash. On each confirmation check, verify that the block with that hash is still in the canonical chain.
Operations: Sweep and Webhooks
Sweep—automatic transfer of funds from the payment address to a cold wallet. A worker runs after each confirmation. If the amount is less than the fee, it logs but does not send.
Webhook system—merchant subscribes to events. Exponential backoff: 30 sec → 5 min → 30 min → 2 hours → 24 hours. After 5 failures, an alert is triggered. Each payload is HMAC-signed for verification.
interface WebhookDelivery {
id: string;
merchant_id: string;
invoice_id: string;
event_type: 'payment.detected' | 'payment.confirmed' | 'payment.settled' | 'payment.expired';
payload: object;
status: 'pending' | 'delivered' | 'failed';
attempts: number;
next_retry_at: Date;
delivered_at: Date | null;
}
Security
Keys are never stored on application servers—only HSM or KMS (AWS KMS, HashiCorp Vault). The signing service is an isolated microservice with minimal privileges. IP whitelist for the merchant's webhook endpoint (optional). Rate limiting on invoice creation: no more than 100/min per merchant. Audit of all actions via an append-only table.
What Is Included in the Work
- Architecture Decision Records for every key decision
- OpenAPI specification of all API endpoints
- ER diagram of the database schema
- Component and sequence diagrams
- Deployment and monitoring documentation
- Access to a repository with a connector template
- Team training (2-hour workshop)
- Support during the development phase (2 weeks)
Design Process
- Day 1: requirements gathering—networks, currencies, volumes, SLA, settlement model, jurisdiction.
- Day 2: data schema and core services design.
- Day 3: blockchain connectors, resilience, reorg strategy.
- Day 4: API contracts, webhook events, SDK.
- Day 5: security review, threat model, final documentation.
The result is a complete set of artifacts for development. Thanks to a well-thought-out architecture, customers save from $20,000 on rework. A typical project pays for itself in a quarter. Get a consultation for your project—contact us.