hanzo-payments

Hanzo Payments is an open-source payment orchestration switch written in Rust.

Hanzo Payments - Payment Orchestration Switch

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-commerce.md, hanzo/hanzo-vault.md, hanzo/hanzo-kms.md

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. Based on Hyperswitch. Exposes a REST API on port 8080. Licensed Apache 2.0.

Why Hanzo Payments?

Tech Stack

OSS Base

Repo: hanzoai/payments (fork of juspay/hyperswitch).

When to use

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

| Item | Value | |------|-------| | API Port | 8080 | | Language | Rust 2021 edition | | DB | PostgreSQL (Diesel ORM) | | Cache | Redis | | Config | TOML (config/development.toml) | | Binaries | router, scheduler (consumer/producer) | | License | Apache 2.0 | | Repo | github.com/hanzoai/payments |

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

| Crate | Purpose | |-------|---------| | router | Main application server (port 8080) | | scheduler | Process tracker (consumer + producer) | | analytics | Payment analytics and reporting | | api_models | API request/response types | | cards | Card number handling and validation | | drainer | Event draining to storage | | euclid | Smart routing decision engine | | euclid_wasm | WebAssembly build of routing engine | | hyperswitch_connectors | 50+ payment processor integrations | | hyperswitch_domain_models | Core domain types | | hyperswitch_interfaces | Connector trait interfaces | | diesel_models | Database models (Diesel ORM) | | storage_impl | Storage layer implementation | | masking | PII data masking | | redis_interface | Redis client wrapper | | payment_methods | Payment method management | | payment_link | Payment link generation | | subscriptions | Recurring payment support | | kgraph_utils | Knowledge graph for routing | | smithy / smithy-core / smithy-generator | API spec generation | | currency_conversion | FX conversion |

Supported Processors

| Category | Processors | |----------|-----------| | Cards | Stripe, Adyen, Braintree, Checkout.com, Cybersource, Worldpay, NMI, Authorise.net, Square | | Bank | Plaid, GoCardless, ACH (Column, Modern Treasury), SEPA, BACS | | Wallets | Apple Pay, Google Pay, PayPal, Venmo, Cash App | | BNPL | Klarna, Affirm, Afterpay, Sezzle | | Crypto | Coinbase Commerce, BitPay, NOWPayments | | Regional | Mercado Pago, Razorpay, Paytm, Mollie, iDEAL, Bancontact | | Wire | Wise, CurrencyCloud, SWIFT, Fedwire |

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:

Integration with Hanzo Stack

Payments connects to:

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Build fails | Missing system deps | apt-get install libpq-dev libssl-dev pkg-config protobuf-compiler | | WASM build fails | Missing wasm-pack | cargo install wasm-pack then make euclid-wasm | | Clippy warnings | Strict lint config | Run cargo clippy --all-features --all-targets -- -D warnings | | Stack overflow at runtime | Default stack too small | Set RUST_MIN_STACK=6291456 |

Related Skills

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: payments, commerce, stripe, processing, routing Prerequisites: Rust, PostgreSQL, Redis