Custom Crypto Payment Gateway Development & Integration

We often hear from clients: "We want to accept cryptocurrency on our website like a regular Stripe, but without intermediaries." It seems straightforward — just hook up a blockchain listener and generate addresses. But in production, problems emerge: detecting payments without constant polling, volatility during conversion, partial payments, confirmation thresholds in different networks, and idempotency during failures. We tackle volatility by fixing the exchange rate through Chainlink Price Feed. We've broken down each of these issues in production and offer a turnkey architecture. Our team has over 5 years of blockchain development experience and has implemented over 20 payment gateway integrations, processing over $10M in crypto transactions. Savings from eliminating intermediaries can reach 2% of turnover (average $20,000 per year for a $1M annual volume). Contact us for a consultation to evaluate your project.

How a Crypto Payment Gateway Works

A minimal viable payment gateway consists of four components:

[Client] → [API Gateway] → [Payment Service] ↓ [Blockchain Listener] ↓ [Event Queue (Redis/Kafka)] ↓ [Settlement Service] → [ERP/CRM] 

Payment Service — creates an order, generates a unique address (or payment ID), and returns payment data to the client. Stateful — stores a mapping address → order. Blockchain Listener — monitors incoming transactions. This is the most critical component for reliability. Two approaches:

1. WebSocket subscription (eth_subscribe("logs", filter) or eth_subscribe("newHeads")) — low latency (10x faster than polling), but connections break; needs reconnect with backoff and replay of missed blocks.
2. Polling + cursor — less elegant but predictable. Store the last processed block, poll eth_getLogs with a filter by addresses. More resilient to network failures.

For production: a hybrid approach — WebSocket for low latency, polling as a fallback with cursor-based recovery.

Event Queue — a buffer between listener and settlement. Kafka for high loads, Redis Streams for medium loads. Key point: the listener publishes a TransactionDetected event, the settlement service subscribes. This decouples components and guarantees processing even if the settlement service temporarily goes down.

Settlement Service — checks confirmations, converts amounts, updates order status, and notifies the upstream system (webhook).

Why Custom Crypto Payment Gateway Detection Is the Hardest Component

EVM Networks (ETH, BNB, Polygon, Arbitrum, ...) and EVM Transaction Detection

Native ETH transfers: monitor via eth_subscribe("newHeads") + eth_getBlockByNumber and filter transactions by to address.

ERC-20 tokens (USDT, USDC, DAI): monitor the Transfer(address indexed from, address indexed to, uint256 value) event via eth_getLogs with a filter:

const filter = { fromBlock: 'latest', topics: [ ethers.id('Transfer(address,address,uint256)'), null, // from: any ethers.zeroPadValue(paymentAddress, 32), // to: our address ], }; 

Important for USDT (Tether): it has a non-standard ERC-20 — the transfer function does not return a bool. Calling through the standard interface will revert. Use safeTransfer or a low-level call with return data check.

Bitcoin Payment Gateway and UTXO Model

For BTC there is no "address → transaction" concept at the node level. Use either:

• Electrum Server (Electrs) — indexes UTXOs by addresses, allows subscription to an address
• BlockCypher / Blockcypher WebHook API — hosted solution but third-party dependency
• Bitcoin Core with importaddress — add the address to the wallet node, receive notifications via ZMQ

Minimum confirmations for BTC: 1 for small amounts (<$100), 3 for medium, 6 for large. For Ethereum, 12–20 blocks are sufficient.

TON Payment

TON transactions are asynchronous: an incoming transfer is a bounce-able message, and you must verify it is a transfer and not a bounce. Use TonAPI or TON Center API with a webhook on the address.

How to Ensure Webhook Idempotency (100% Idempotency Guarantee)

Notifications to the upstream system via webhook must be idempotent — duplicate deliveries on retry are possible. Include payment_id (unique) + tx_hash + status in the payload. The upstream system must check if it has already processed that payment_id. Retry policy: exponential backoff, 5–10 attempts, then a dead letter queue for manual inspection.

Confirmation Threshold and Double-Spend Protection

Never consider a payment completed after first detecting a transaction in the mempool — that is a pending state, not confirmed. Minimum thresholds:

Partial Payments and Overpayments

Real users sometimes pay the wrong amount — exchanges deduct fees, people make mistakes. A policy is needed:

• Underpayment: if 99–100% of amount received — treat as paid (1% tolerance). If less — partially_paid, wait 30 minutes for top-up, then expired.
• Overpayment: automatically accept, refund the difference (requires a refund flow) or credit as a credit note.

Comparison of Detection Approaches

# config.yml listener: networks: - name: ethereum rpc: wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY polling_interval: 12s confirmations: 12 addresses: - 0xYourPaymentAddress - name: bitcoin rpc: http://user:pass@localhost:18332 confirmations: 3 addresses: - bc1q... - name: polygon rpc: wss://polygon-mainnet.infura.io/ws/v3/YOUR_KEY confirmations: 128 addresses: - 0x...