painfree

JSON in, EBICS out. Self-hosted middleware that accepts authenticated HTTP requests and submits them to your banks over EBICS 3.0, so payment files stop being something a human uploads by hand.

your system  ──JSON/HTTPS──▶  painfree  ──EBICS 3.0 (H005)──▶   bank A
                (OIDC)         │                                bank B
                               │                                bank C
                               └──webhook──▶  your system

POST a payment as JSON. painfree validates it, builds a compliant pain.001, signs and encrypts it per the EBICS protocol, uploads it to the right bank connection, tracks the order to acknowledgement, and calls your webhook when the status changes. It runs the other direction too: scheduled downloads of camt.052/053/054 and pain.002, normalised to JSON.

A console at /ui handles everything that is not a payment: bank connections, EBICS initialisation, key management, order history, replay, audit.

Status

Early. Not in production. Not suitable for anyone else's money.

Run it

Four lines, against the published image. Nothing is built.

cp deploy/production.env.example .env    # pinned to ghcr.io/reyemb/painfree
deploy/init-secrets.sh                   # four secret files, generated once
docker compose up -d                     # db, api, worker, TLS proxy
docker compose exec api python -m painfree create-admin you    # no OIDC only

It comes up on https://painfree.localhost:8443, on loopback: a rootless engine may not publish a port below 1024, so the defaults are above it. A deployment on a real hostname sets PAINFREE_HTTP_PORT, PAINFREE_HTTPS_PORT and the two _BIND variables to 80 and 443, which is what ACME needs anyway.

Two things that machine needs, both once:

echo "127.0.0.1  painfree.localhost" | sudo tee -a /etc/hosts
curl -k https://painfree.localhost:8443/local-ca.crt -o painfree-local-ca.crt

glibc resolves localhost and nothing else under it, so .localhost names do not resolve on Debian, Ubuntu or WSL even though the stack is healthy and the certificate is valid. The second line fetches the local CA's public root, which the proxy serves unauthenticated; import it and the browser warning goes away. Neither is needed once PAINFREE_SITE_ADDRESS is a real hostname with a real certificate.

podman-compose works identically, and deploy/build-image.sh builds the image yourself if you would rather not run someone else's.

Everything that is not secret lives in .env. Every secret is a file under deploy/secrets/, generated once, mounted at runtime, and never baked into the image or committed. Everything that survives a restart is a directory under state/, so the deployment is this folder and no compose command can delete any of it.

Backups

deploy/snapshot.sh          # one .tar.gz that restores on another machine

state/db is owned by a uid inside the container's user namespace, so tar and cp -r run as you will skip it, keep going, and write an archive that holds the custody secret and the certificates but not the database. snapshot.sh takes the database as a pg_dump from inside the container that can read it, and refuses to write anything if that dump comes back empty.

The archive contains the custody secret and the data it opens. Encrypt it before it goes anywhere you do not control.

Submitting a payment

curl -X POST https://painfree.localhost/v1/connections/acme-ubs/payments \
     -u you:the-password-you-set \
     -H 'Idempotency-Key: caller-idem-0001' \
     -H 'Content-Type: application/json' -d @payment.json

202 Accepted with an order_id to poll at /v1/orders/{order_id}. Accepted means accepted for processing, not that the bank has it. The instruction is validated against the ISO 20022 schema and the Swiss Payment Standards rules before anything is signed, so a malformed QR reference comes back immediately naming the field, rather than from the bank two hours later.

One idempotency key stays one order, and an order can end accepted at most once.

payment.json, an ordinary transfer

One debit account, one execution date, and the transfers to make. Everything ISO 20022 needs and this service can derive — the message id, the timestamp, the transaction count, the control sum — is derived rather than demanded, because a field the caller has to compute is a field the caller computes wrongly.

{
  "debtor": {
    "name": "MUSTER AG",
    "postal_address": {"town": "SELDWYLA", "country": "CH"}
  },
  "debtor_iban": "CH5604835012345678009",
  "requested_execution_date": "2026-09-30",
  "transactions": [
    {
      "amount": "3949.75",
      "currency": "CHF",
      "creditor": {
        "name": "Robert Schneider AG",
        "postal_address": {
          "street": "Rue du Lac", "building_number": "1268",
          "postal_code": "2501", "town": "Biel", "country": "CH"
        }
      },
      "creditor_iban": "CH4431999123000889012",
      "reference": {"type": "QRR", "reference": "210000000003139471430009017"}
    }
  ]
}

reference.type is QRR for a Swiss QR reference, SCOR for an ISO 11649 creditor reference, or NONE. Which one is allowed depends on the account — a QR reference belongs to a QR-IBAN — and the pair is checked before anything is built. Use remittance_information instead for unstructured text; a structured reference and free text together is refused.

payment.json, an instant transfer

The same body with scheme added. It is the only difference:

{
  "scheme": "instant_or_normal",
  "debtor": {"name": "MUSTER AG"},
  "debtor_iban": "CH5604835012345678009",
  "requested_execution_date": "2026-09-30",
  "transactions": [
    {
      "amount": "42.00",
      "currency": "CHF",
      "creditor": {"name": "Robert Schneider AG"},
      "creditor_iban": "CH4821966000009613388",
      "remittance_information": "Invoice 2026-114"
    }
  ]
}

Payment schemes. A payment carries normal, instant, or instant_or_normal, which tries instant and sends an ordinary transfer if the bank definitively refuses. A timeout, a dropped connection or an answer that will not parse is an unknown outcome rather than a refusal: the order is retried carrying the message it already had, so nothing is sent twice. scheme may also be set per transfer, but every transfer in one message has to end up on the same scheme: one upload carries one BTF.

Instant needs a profile your bank actually publishes, and the default is a guess. An instant upload is announced with a BTF triplet, and the one shipped here is the EPC SEPA convention — service option INST, SvcLvl/Cd SEPA, LclInstrm/Cd INST. That is the euro scheme. A Swiss bank on SIC instant publishes its own triplet and may use LclInstrm/Prtry instead, and plenty of banks publish none at all, because their EBICS catalogue has one upload row and it is pain.001.

So check your bank's EBICS parameter sheet before asking for instant, and set the profile on the connection to whatever it lists. If the bank has no instant row, clear the instant profile in the console: with it left populated, instant fails at the bank with 091112 EBICS_INVALID_ORDER_PARAMS and instant_or_normal spends a wasted round trip on every payment before falling back. With it cleared, both are decided locally — instant is refused before anything is signed, and instant_or_normal goes out as an ordinary transfer first time.

/ui/api renders the request body, every endpoint and the privilege it demands, generated from the router rather than written down, and links the OpenAPI documents beside it.

How it works

Two processes, one image. api serves HTTP and is refused the custody secret. worker holds it, and does every upload, download and key operation. An api process handed the secret does not start, and production refuses to run both halves in one process. That is a security boundary rather than a scaling one: the process answering requests has nothing to decrypt a private key with.

Authentication. OIDC where you have a provider (browser SSO with PKCE, JWT bearer for machines), and HTTP Basic against local accounts where you do not. Production refuses to start in development mode. A process accepts one kind of credential and never two.

Authorisation. Two roles: admin, which may grant access, and member, which may not. Everything a member holds is a grant naming a subject, a bank connection and a level. viewer reads; operator also submits payments, replays orders and manages schedules. Grants are read from the database on every request, so revoking somebody takes effect on their next request. A connection a caller holds no grant on answers 404, exactly like one that was never registered.

Webhooks. At-least-once. The event is written in the same transaction as the fact it reports, so a crash cannot lose it, and a redelivery carries the same event_id: deduplicate on that. Each request is signed X-Painfree-Signature: v1=<hex>, an HMAC-SHA256 over "<timestamp>.<raw body>" with the subscription's own secret. Verify over the bytes you received, not over a re-serialisation.

Keys. INI, HIA and HPB from the console, with a printable INI letter, renewal and suspension. The bank's keys are trusted only once you have compared their fingerprints against the letter the bank sent, on a page where nothing is pre-filled and declining is as easy as accepting.

Configuration

Every setting is an environment variable, and any of them can be read from a file instead by setting PAINFREE_X_FILE. The ones a deployment sets are in deploy/production.env.example; the rest are documented where they are defined, in painfree/config.py.

Logs are one JSON object per line on stdout. No token, authorization code, session id or client secret ever reaches the stream.

Backup, and the one thing no backup covers

deploy/backup.sh dumps the database and deploy/restore.sh restores it. That covers the sealed keys, the order history, the idempotency ledger and the audit trail.

It does not cover PAINFREE_KEY_ENCRYPTION_SECRET, which is in no backup and which nothing recovers. Lose it and every sealed key is unreadable by anyone, and each bank connection has to be re-keyed on paper. Rotating it is python -m painfree rekey, run with both secrets present, which re-seals every row and fails loudly on any it could not move.

Develop

uv sync --extra dev
uv run python -m painfree     # SQLite, migrated at startup, on :8000
uv run pytest

Development mode authenticates from X-Painfree-Dev-Principal and X-Painfree-Dev-Roles, so a checkout runs and the suite passes with no provider to point at. It is still an authentication step, and production refuses to start in it.

There is one importable package, painfree; the EBICS 3.0 engine is the subpackage painfree/ebics3/, which imports nothing from the service around it and needs only lxml and cryptography.

Licence

MIT. Copyright (c) 2026 reyemb. The full text is in LICENSE.

The EBICS 3.0 engine in painfree/ebics3/ is a Python port of ebics-api/ebics-client-php, which is MIT too. Its notice is reproduced in full in NOTICE, which every copy has to keep, and both files ship inside the wheel, the source distribution and the container image.