Hanzo Billing - Subscription and Payment Management Portal

Overview

Why Hanzo Billing?

Feedback
Multi-org: Auto-detects org from hostname (hanzo, lux, zoo, pars) with per-org IAM, branding, and theme
Feedback
Subscription tiers: Developer (free/$5 credit), Pro ($49/mo), Team ($199/mo), Enterprise, Custom
Feedback
Web3 payments: RainbowKit + wagmi + viem for wallet-based payments across 7 chains
Feedback
IAM-integrated: OIDC/PKCE login via Casdoor (hanzo.id, lux.id, zoo.id, pars.id)
Feedback
Commerce API: Backend via api.hanzo.ai for subscriptions, invoices, credits, transactions
Feedback
Static export: next build produces static HTML served by nginx (no Node.js runtime)

Tech Stack

Feedback
Framework: Next.js 16 (static export via output: 'export')
Feedback
UI: @hanzo/ui (billing components), Tailwind CSS 4, Geist font
Feedback
Web3: RainbowKit 2, wagmi 2, viem 2 (Ethereum, Polygon, Optimism, Arbitrum, Base, Avalanche, BSC)
Feedback
Auth: Self-contained OIDC/PKCE module (lib/iam-auth.ts), no external auth package
Feedback
Serving: nginx:alpine with security headers, gzip, health check at /health
Feedback
Image: ghcr.io/hanzoai/billing:latest
Feedback
Dev port: 3005

OSS Base

When to use

Feedback
Managing subscription plans and billing for Hanzo/Lux/Zoo/Pars orgs
Feedback
Viewing and paying invoices
Feedback
Adding/managing payment methods (card + crypto wallet)
Feedback
Topping up API credits
Feedback
Viewing transaction history and usage
Feedback
Configuring spend alerts
Feedback
Managing business profile and tax compliance
Feedback
Account member management with role-based access

Hard requirements

Feedback
Hanzo IAM configured at hanzo.id (or per-org IAM server) for OIDC/PKCE auth
Feedback
Commerce API at api.hanzo.ai for backend billing operations
Feedback
GHCR access for container image (ghcr.io/hanzoai/billing)

Quick reference

One-file quickstart

Local development

git clone https://github.com/hanzoai/billing.git
cd billing
pnpm install
pnpm dev          # http://localhost:3005

Production build

pnpm build        # Static export to out/
# Serve with nginx or any static file server

Docker

# Build
docker build -t billing .

# Or use pre-built deploy image (requires out/ already built)
docker build -f Dockerfile.deploy -t billing .

# Run
docker run -p 80:80 billing

Core Concepts

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  billing.hanzo.ai│────>│  Hanzo IAM       │     │  Commerce API   │
│  (Next.js static)│     │  (hanzo.id)      │     │  (api.hanzo.ai) │
│  served by nginx │     │  OIDC/PKCE auth  │     │  billing backend│
└────────┬────────┘     └──────────────────┘     └─────────────────┘
         │
    ┌────┴──────────┐
    │  RainbowKit   │
    │  (7 EVM chains)│
    └───────────────┘

Multi-Org Configuration

Auth Flow

Feedback
User lands on billing portal, org detected from hostname
Feedback
If not logged in, starts PKCE flow: generates code_verifier, computes code_challenge
Feedback
Redirects to IAM authorize endpoint (/oauth/authorize) with S256 challenge
Feedback
On callback, exchanges authorization code for tokens via /oauth/token
Feedback
JWT stored in sessionStorage; user info parsed from JWT payload
Feedback
Also supports implicit flow (access_token in query/hash)

Subscription Plans

App Routes

Key Billing Components (lib/billing/)

Feedback
overview-dashboard.tsx - Main dashboard with balance, usage, plan summary
Feedback
subscription-portal.tsx - Plan selection and management
Feedback
payment-manager.tsx - Card and wallet payment methods
Feedback
invoice-manager.tsx - Invoice viewing and payment
Feedback
cost-explorer.tsx - Detailed cost breakdown
Feedback
credits-panel.tsx - Credit grants and balance
Feedback
transactions-panel.tsx - Transaction history
Feedback
spend-alerts.tsx - Budget alert configuration
Feedback
account-members.tsx - Team member management
Feedback
business-profile-panel.tsx - Business info for invoicing
Feedback
tax-compliance-panel.tsx - Tax ID and compliance
Feedback
card-form.tsx / square-card-form.tsx - Card input forms

Admin Access

CI/CD

Feedback
GitHub Pages: Static export with /billing basePath (for docs/preview)
Feedback
Docker (GHCR + K8s): Builds ghcr.io/hanzoai/billing:latest, deploys to hanzo namespace
Feedback
Cloudflare Pages: Optional (gated by DEPLOY_CLOUDFLARE var), credentials fetched from KMS

Troubleshooting

Related Skills

Feedback
hanzo/hanzo-id.md - IAM and authentication (OIDC/PKCE provider)
Feedback
hanzo/hanzo-commerce-api.md - Commerce API backend
Feedback
hanzo/hanzo-ui.md - Shared UI components (@hanzo/ui/billing)
Feedback
hanzo/hanzo-payments.md - Payment processing
Feedback
hanzo/hanzo-cloud.md - Cloud dashboard