build // Bitcoin · Infrastructure

On-chain Payment Processor

Merchant API for unique deposit addresses, confirmation policies, idempotent invoices, and signed settlement webhooks.

Advanced2 weeks

Overview

A payment processor turns "send bitcoin here" into an API merchants can integrate: create invoice → detect payment → confirm → notify.

Suggested statuses

unpaid → seen → confirmed → expired / underpaid / overpaid

Only fulfill after proven settlement. Deliver webhooks with event IDs and allow merchants to safely retry.

Learning objectives

Create payment invoices and watch for matching on-chain payments
Track confirmation depth and emit reliable status transitions
Deliver signed webhooks merchants can trust

Prerequisites

bitcoind Ops Console
Transactions
Mempool & Fees

Required skills

API designWatch-only descriptorsWebhook securityBIP-21

Part of the bitcoin roadmap.

Architecture diagram

Merchant ──► Processor API ──► Watcher ──► Node / Indexer
                 │
                 └──► signed webhooks

Requirements

Invoice create + status endpoints with clear state machine
Unique receive address (or BIP-21 URI) per invoice
Explicit under/overpayment and expiry handling
HMAC-signed webhooks with event IDs for safe retries
End-to-end regtest demo: create → pay → confirm → webhook

Stretch goals

Hosted invoice page with live status
Watch-only xpub / descriptor custody separation
Rate limits and absurd-dust rejection
CPFP / RBF guidance for stuck merchant payments

Recommended resources

Example repositories

BTCPay Server
Full-featured self-hosted payment processor reference.
lnbits
Lightweight invoice and extension patterns (also Lightning).

Submission instructions

Public repo with OpenAPI or route docs
Regtest script or Docker Compose demo
Sample webhook receiver that verifies signatures
Written confirmation policy (N confirms, amount tolerances)

Discussion

Loading page