documentation

quick start

spin up the full stack locally in four commands:

• git clone the repository
• cp docker/.env.example .env
• just docker-up
• just smoke to verify everything is alive

after that you have a postgres, redis, api, worker, and frontend running on 127.0.0.1. crypto daemons run separately (see self-hosting).

api reference

HalcoPay exposes a fastapi-powered rest api documented via openapi 3.

• openapi spec: /openapi.json
• swagger ui: /docs
• scalar ui: /scalar

major resource families:

• auth: /token, /users/2fa/* — bearer tokens with scope-based rbac, totp + fido2
• commerce: /invoices, /products, /discounts, /stores
• treasury: /wallets, /payouts, /refunds
• extensibility: /plugins, /notifications, /templates, /files
• ops: /health/live, /health/ready, /metrics, /manage

websocket events at /ws stream invoice state transitions in real-time.

webhooks

signed merchant webhooks with retry, replay protection, and a transparency log of every delivery.

• signature header: X-MVgateway-Signature: t=<unix>,v1=<hmac_hex>
• algorithm: hmac-sha256 over {timestamp}.{raw_body}
• replay window: 5 minutes
• retry schedule: 60s → 5m → 30m → 2h → 12h (six attempts)
• permanent vs transient: 4xx (except 408/429) are permanent; 5xx and network errors retry

sdks

the rest api is the source of truth. clients we publish or recommend:

• python: generated from openapi via openapi-python-client
• typescript: generated via openapi-typescript — strict types out of the box
• go, ruby, php, rust: the openapi spec works with the standard generators for each language
• woocommerce, shopify, magento: not yet — tell us if you need one

self-hosting guide

HalcoPay is designed to be run by you, on your infrastructure. you keep the keys, the data, the customer records.

the bundled docker-compose.yml is a local-dev stack — postgres, redis, api, worker, frontend nginx. it boots in <1 min on a laptop.

for production you'll want:

• a real domain with tls (caddy, traefik, or nginx with letsencrypt in front)
• postgres on managed infra (rds, cloud sql) with daily backups
• redis with persistence (aof) for the taskiq queues
• at least one api replica and one worker replica behind a load balancer
• crypto daemons on a separate host with restrictive firewall (only the api should talk to them)
• prometheus scraping /metrics on api + worker
• sentry dsn for error tracking (optional)

the bundled grafana dashboard + alertmanager rules (docs/prometheus/mvgateway-rules.yml) cover the basics: api up, worker up, http error rate, webhook success ratio, plugin sandbox health.

security

• authentication: bearer api tokens with explicit scopes; per-resource scopes (SCOPE:model_id) for delegated access
• 2fa: totp (rfc 6238) + fido2/webauthn
• plugin sandbox: ed25519-signed packages, ast capability check at install time, audit hook at runtime, optional subprocess isolation
• webhooks: hmac-signed with replay-window
• tls everywhere: reverse proxy terminates, api can also serve tls directly
• captcha: hcaptcha or cloudflare turnstile, configurable per endpoint