SepaQX · SEPA EPC · API

Generate SEPA EPC QR codes for invoices — in seconds.

Lightweight HTTP/HTTPS server that generates EPC-compliant SEPA QR codes as PNG images. Built for billing systems, invoices, web apps, and internal tools. Public mode or API-key access with per-client customization.

Install (Debian/Ubuntu) View on GitHub

PNG output · EPC compliant · HTTP API

Quick example

curl -X POST http://127.0.0.1:8089/sepa-qr \
  -H 'Content-Type: application/json' \
  -d '{...}' --output sepa-qr.png

PNG output ready for invoices, billing portals, and automated workflows.

Benefits

EPC069-12 compliant payloads

SEPA Credit Transfer (SCT) QR codes that validate cleanly.

Built for invoice pipelines

Fast PNG output for PDFs, billing portals, and internal tools.

Public or API-key mode

Open access or per-client control.

Branding per client

Logo, colors, gradients, and module styles by API key.

Hardened server behavior

Request limits, rate limiting, caching, and clear errors.

What is SepaQX?

SepaQX is a self-hosted SEPA QR generator that produces EPC-compliant payment payloads and renders them as PNG QR codes. When scanned, the payment form is pre-filled.

Receiver name
IBAN and BIC
Amount (EUR)
Purpose code
Remittance reference or text

Key features

Production-first

Hardened HTTP server with limits, timeouts, rate limiting, and reverse-proxy aware client IP handling.

Designed for safe public exposure.

Invoice-ready

Returns ready-to-use PNG images for invoices, PDFs, and billing portals.

One endpoint, one PNG.

Branding per client

API-key configuration supports logos, colors, gradients, and QR module styles per client.

Optional per-key customization.

EPC069-12 compliant SEPA QR codes (SCT)
Single endpoint: GET/POST /sepa-qr
Optional /sepa-qr/validate (JSON only)
Public mode or API-key based access
Consistent error handling (PNG or JSON)
Runs as a small systemd service, no external dependencies

API usage

POST is recommended for production. GET is available for simple integrations, and /sepa-qr/validate returns JSON only.

POST /sepa-qr

POST /sepa-qr
Content-Type: application/json
X-API-Key: <optional>

{
  "name": "Receiver Name",
  "iban": "DE12345678901234567890",
  "bic": "BANKDEFFXXX",
  "amount": "12.34",
  "purpose": "SALA",
  "remittance_reference": "RF18539007547034",
  "remittance_text": "Invoice 123",
  "information": "Sample EPC QR code"
}

If purpose is omitted, the default is GDDS.

Other endpoints

GET /sepa-qr?... (query params)
POST /sepa-qr/validate

GET /healthz
GET /readyz
GET /version

In public mode, HEAD /sepa-qr returns PNG headers for health checks.

Errors and formats

Invalid input returns a static PNG error image by default. Use format=json or Accept: application/json for JSON errors. You can override the image with ERROR_PNG_PATH.

Validation limits

name: max 70 characters
purpose: max 4 characters (uppercased)
remittance_reference max 25 or remittance_text max 140 (mutually exclusive)
information: max 70 characters
amount: > 0 and <= 99999999999 cents
IBANs are validated via MOD97-10

Security notes

REQUIRE_API_KEY disables public access
ALLOW_QUERY_API_KEY leaks keys via URLs; keep it off
Trusted proxies via TRUSTED_PROXY_CIDRS
No payment execution or data storage

Install

Use our APT repository or build from source.

Requirements: Linux with systemd. Build from source requires Go 1.24+.

Install via APT

curl -fsSL https://install.safe-cap.com/linux/apt/pubkey.gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/safe-cap.gpg
echo "deb [signed-by=/usr/share/keyrings/safe-cap.gpg] https://install.safe-cap.com/linux/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/safe-cap.list
sudo apt update
sudo apt install sepaqx

Build from source

git clone https://github.com/safe-cap/sepaqx sepaqx
cd sepaqx
go build -o sepaqx .
sudo install -m 0755 sepaqx /usr/bin/sepaqx
sudo install -d /etc/sepaqx /etc/sepaqx/tls
sudo cp examples/.env.example /etc/sepaqx/.env

Support the project

SepaQX is free and open-source. If it saves you time integrating SEPA QR payments or reduces invoice errors, supporting the project helps ensure long-term maintenance and continued development.

Donate via PayPal Contact

Commercial support and custom integrations available — get help tailored to your stack.

Get started

Install locally in minutes, or integrate via the HTTP/HTTPS API.

Install (Debian/Ubuntu) View on GitHub