Developing a Lightning Network Payment Gateway
Lightning Network is not just "fast Bitcoin". This is a fundamentally different settlement model: off-chain channels with on-chain settlement. Before building a payment gateway, understand that Lightning is a liquidity network, and managing this liquidity is the main operational task absent in alternatives based on L1.
Lightning Architecture: What Engineers Need to Know
A payment on Lightning doesn't go directly from sender to receiver, but via a path through intermediate nodes. Node A → Node B → Node C → Node D: each intermediate node "forwards" HTLCs (Hash Time-Locked Contracts). If any hop lacks liquidity in needed direction — payment fails and needs retry on different path.
For payment gateway, this means: inbound liquidity is critical resource. To accept Lightning payments, your node must have inbound capacity from well-connected network nodes.
Choosing Node Implementation
LND (Lightning Labs, Go): most common, rich gRPC/REST API, good documentation. Recommended for most production gateways.
CLN (Core Lightning, Blockstream, C): more modular architecture, plugin system. Slightly more complex API.
Eclair (ACINQ, Scala): used in Phoenix wallet backend. Less common for server-side use.
For gateway we choose LND — best API and ecosystem.
LND Node Setup
lnd --bitcoin.active \
--bitcoin.mainnet \
--bitcoin.node=bitcoind \
--bitcoind.rpchost=localhost \
--bitcoind.rpcuser=rpcuser \
--bitcoind.rpcpass=rpcpassword \
--bitcoind.zmqpubrawblock=tcp://127.0.0.1:28332 \
--bitcoind.zmqpubrawtx=tcp://127.0.0.1:28333 \
--rpclisten=0.0.0.0:10009 \
--tlsextraip=YOUR_SERVER_IP \
--alias="YourGateway" \
--color=#FF6B35
For API interaction — lnd-grpc client. Certificate and macaroon (credential file) required for each request.
Creating Invoice and Awaiting Payment
package lightning
import (
"context"
"encoding/hex"
lnrpc "github.com/lightningnetwork/lnd/lnrpc"
"google.golang.org/grpc"
)
type LNDClient struct {
conn *grpc.ClientConn
client lnrpc.LightningClient
}
func (c *LNDClient) CreateInvoice(
ctx context.Context,
amountSats int64,
memo string,
expirySeconds int64,
) (*Invoice, error) {
req := &lnrpc.Invoice{
Value: amountSats,
Memo: memo,
Expiry: expirySeconds, // recommended 300–900 seconds
}
resp, err := c.client.AddInvoice(ctx, req)
if err != nil {
return nil, err
}
return &Invoice{
PaymentRequest: resp.PaymentRequest, // BOLT-11 string for client
PaymentHash: hex.EncodeToString(resp.RHash),
ExpiresAt: time.Now().Add(time.Duration(expirySeconds) * time.Second),
}, nil
}
BOLT-11 string (lnbc500u1p...) is QR code and link for client. Wallet decodes it and knows where to pay.
Subscribe to Settled Invoices
func (c *LNDClient) WatchInvoices(ctx context.Context, handler func(*lnrpc.Invoice)) error {
stream, err := c.client.SubscribeInvoices(ctx, &lnrpc.InvoiceSubscription{})
if err != nil {
return err
}
for {
invoice, err := stream.Recv()
if err != nil {
return err
}
if invoice.State == lnrpc.Invoice_SETTLED {
handler(invoice)
}
}
}
SubscribeInvoices is preferred way to get payment notifications. Avoid polling LookupInvoice in loop — creates unnecessary load.
Liquidity Management
Main operational task for production gateway. Channel has capacity (total size) and balance (distribution between sides). When receiving payments, balance shifts to your side — inbound capacity is spent. When sending — opposite.
Loop: Submarine Swaps
Lightning Loop (Lightning Labs) allows "rebalancing" channel via submarine swap — atomic exchange between on-chain BTC and off-chain Lightning sat without closing channel:
Loop Out: move Lightning sat → on-chain BTC. Recovers inbound capacity. Loop In: move on-chain BTC → Lightning sat. Recovers outbound capacity.
# Restore 500k sat inbound capacity via Loop Out
loop out --amt 500000 --channel YOUR_CHANNEL_ID
Cost: 0.1–0.3% + on-chain fee. For gateway with continuous inflow — auto Loop Out when reaching threshold (outbound balance > 80% channel capacity).
Pool: Liquidity Rental
Lightning Pool — marketplace for renting inbound liquidity. Sellers open channels to your node for fee. Rental period: 2016 blocks (~2 weeks). Alternative to self-channel management for startup.
Automatic Rebalancing
async def auto_rebalance(lnd_client: LNDClient):
channels = await lnd_client.list_channels()
for channel in channels:
balance_ratio = channel.local_balance / channel.capacity
# Too much outgoing liquidity — do Loop Out
if balance_ratio > 0.85:
amount = int((balance_ratio - 0.5) * channel.capacity)
await loop_out(amount, channel.chan_id)
# Too little — pay via this channel or do Loop In
elif balance_ratio < 0.15:
amount = int((0.5 - balance_ratio) * channel.capacity)
await rebalance_circular(amount, channel.chan_id, lnd_client)
BOLT-12 Offers: Next Generation Invoices
BOLT-11 is one-time invoice. BOLT-12 Offers are reusable payment codes:
lno1qgsyxjtl6luzd9t3pr62xr7eemp6awnejusgd4...
Client requests current invoice from receiver via onion message, receives BOLT-11 (or BOLT-12 invoice), pays. Works for subscriptions, tips, recurring payments. LND supports BOLT-12 starting from version 0.17.
Security
Watchtower: if your node goes offline, former counterparty can try broadcasting old channel state (breach attempt). Watchtower service monitors blockchain and publishes penalty transaction. LND has built-in watchtower client and server.
# Connect to public watchtower
lncli wtclient add [email protected]:9911
Channel backup: SCBs (Static Channel Backups) allow recovering funds from channels on node state loss. Automatically created by LND, store securely.
Macaroon limits: for app API access, issue limited macaroons — only invoice creation rights without ability to initiate payments:
lncli bakemacaroon invoices:write invoices:read
Backend Integration
REST API wrapper over LND for merchant applications:
POST /api/invoices - create invoice
GET /api/invoices/:hash - invoice status
WS /api/invoices/stream - real-time payment events
Webhook on payment — same scheme as on-chain payment gateway (HMAC-SHA256 signature).
Fiat conversion: when creating invoice, accept fiat amount, convert to satoshi at current rate (Kraken/Coinbase API), fix rate during invoice lifetime.
Infrastructure
- Dedicated server or VPS (not containerized without persistent storage)
- Bitcoin full node (consumes ~600GB NVMe)
- LND on top of bitcoind
- Minimum initial capital for channel opening: 0.1–0.5 BTC for small gateway
Developing basic Lightning payment gateway with invoice creation, payment monitoring, and automatic Loop Out — 6–8 weeks. With full liquidity management, BOLT-12 support, and admin dashboard — 3–4 months.