Hanzo Payments - Payment Orchestration Switch

Overview

Hanzo Payments is an open-source payment orchestration switch written in Rust. It routes payments across 50+ processors with smart retries, fallback cascading, and unified analytics, so a processor outage becomes a routing decision rather than an incident. One REST API on port 8080 regardless of how many processors sit behind it. Licensed Apache 2.0.

Why Hanzo Payments?

• Smart routing: Route to optimal processor based on cost, success rate, and latency
• 50+ connectors: Stripe, Adyen, Braintree, Checkout.com, PayPal, Klarna, Coinbase, and more
• Automatic retries: Cascade to backup processors on failure
• Unified API: Single integration for cards, bank transfers, wallets, BNPL, crypto
• PCI DSS: Vault-based card tokenization via hanzo/vault
• 3DS Authentication: Native 3D Secure support
• Multi-currency: 135+ currencies with automatic FX
• Decision engine: TOML-based routing rules (Euclid engine)

Tech Stack

• Language: Rust (edition 2021, MSRV 1.85.0)
• Database: PostgreSQL (via Diesel ORM)
• Cache: Redis
• Build: Cargo workspace with 35+ crates
• Monitoring: Prometheus, Grafana, Loki, Tempo, OpenTelemetry
• API spec: OpenAPI / Smithy
• Testing: Cargo test, Newman (Postman), Cypress E2E

Repo

hanzoai/payments. Rust, 39 workspace crates.

When to use

• Processing payments across multiple payment providers
• Building smart payment routing with fallback logic
• Accepting cards, bank payments, wallets, BNPL, or crypto
• PCI-compliant card tokenization and vaulting
• Multi-currency payment processing with automatic FX
• Real-time payment analytics and reporting

Hard requirements

1. Rust toolchain (1.85.0+) with protobuf compiler
2. PostgreSQL database
3. Redis for caching and process tracking
4. libpq-dev, libssl-dev system libraries

Quick reference

One-file quickstart

Docker Compose

# Start all services
docker compose up -d

# Create a payment
curl -X POST http://localhost:8080/payments/create \
  -H "Content-Type: application/json" \
  -H "api-key: dev_key" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "payment_method": "card",
    "payment_method_data": {
      "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "12",
        "card_exp_year": "2027",
        "card_cvc": "123"
      }
    },
    "connector": "stripe"
  }'

Local Development

# Build
cargo build

# Run tests
cargo test --all-features

# Format and lint
cargo +nightly fmt --all
cargo clippy --all-features --all-targets -- -D warnings

# Build release binary (stripped, LTO)
cargo build --release --no-default-features --features release --features v1

Core Concepts

Architecture

hanzo/commerce    Storefront, catalog, orders
       |
hanzo/payments    Payment routing (50+ processors)   <-- this service
       |
hanzo/treasury    Ledger, reconciliation, wallets
       |
lux/treasury      On-chain treasury, MPC/KMS wallets

Workspace Crates

Supported Processors

Decision Engine (Euclid)

Smart routing rules defined in TOML:

[[rules]]
name = "route_high_value"
condition = "amount > 10000 AND currency == 'USD'"
action = "route"
connector = "adyen"
fallback = ["stripe", "checkout"]

[[rules]]
name = "route_eu"
condition = "country IN ['DE', 'FR', 'NL', 'BE']"
action = "route"
connector = "mollie"
fallback = ["adyen"]

The Euclid engine also compiles to WebAssembly for client-side routing preview.

Binaries

The Dockerfile builds three binary targets:

1. router -- Main application server (default)
2. scheduler (consumer) -- Process tracker consumer
3. scheduler (producer) -- Process tracker producer

Observability

Full monitoring stack via config directory:

• Prometheus -- Metrics collection
• Grafana -- Dashboards and visualization
• Loki + Promtail -- Log aggregation
• Tempo -- Distributed tracing
• OpenTelemetry Collector -- Telemetry pipeline
• Vector -- Log routing

Integration with Hanzo Stack

Payments connects to:

• hanzo/commerce for order checkout and settlement
• hanzo/treasury for ledger recording and reconciliation
• hanzo/vault for PCI-compliant card tokenization
• hanzo/kms for API key and secret management

Troubleshooting

Related Skills

• hanzo/hanzo-commerce.md - E-commerce platform
• hanzo/hanzo-vault.md - PCI-compliant card tokenization
• hanzo/hanzo-kms.md - Secret management
• hanzo/hanzo-commerce-api.md - Commerce API