Invoice Ninja v5: Kontoinhaber im SEPA-QR-Code sauber überschreiben

Bürokram, Code

Bei Invoice Ninja v5 (selbst gehostet) wird der SEPA-QR-Code für Überweisungen und Lastschriften automatisch erzeugt. Dabei nutzt Invoice Ninja standardmäßig den Firmennamen als Kontoinhaber / Empfängername im EPC-QR-Code.

In meinem Fall ist das fachlich nicht korrekt: Der Kontoinhaber ist eine natürliche Person, der Firmenname darf dort nicht erscheinen. Eine Einstellung dafür gibt es im UI nicht.

Diese kurze Doku beschreibt eine saubere, minimal-invasive Lösung, die updatefähig bleibt.

Ziel

  • Firmenname bleibt unverändert (Rechnungen, UI, Reports)
  • SEPA-QR-Codes verwenden einen frei definierbaren Kontoinhaber
  • Umsetzung über .env, mit klarem Fallback
  • Nur eine kleine Core-Anpassung, leicht wiederherstellbar

Überblick der Änderungen

Es sind genau drei Stellen betroffen:

  1. .env
  2. config/ninja.php
  3. app/Helpers/Epc/EpcQrGenerator.php

Kontoinhaber in der .env definieren

Die .env bleibt bei Updates erhalten und ist der richtige Ort für personenbezogene Daten.

SEPA_QR_ACCOUNT_HOLDER="René Terruhn"

Dieser Wert wird später zentral abgefragt.

Konfiguration verfügbar machen

In config/ninja.php wird der neue Wert einmalig registriert:

'sepa_qr_account_holder' => env('SEPA_QR_ACCOUNT_HOLDER'),

Damit steht der Kontoinhaber überall per config() zur Verfügung.

QR-Code-Name gezielt überschreiben

Die eigentliche Logik sitzt im EPC-Generator in der Datei app/Helpers/Epc/EpcQrGenerator.php.

Änderung 1: Konfigurationswert einlesen

$accountHolder = config('ninja.sepa_qr_account_holder');

Änderung 2: Namen gezielt ersetzen, mit sauberem Fallback

Der relevante Codeblock sieht danach so aus:

$name = $this->company->present()->name();
$accountHolder = config('ninja.sepa_qr_account_holder');

if (
    isset($this->company->e_invoice->Invoice->PaymentMeans)
    && ($pm = $this->company->e_invoice->Invoice->PaymentMeans[0] ?? false)
    && in_array($pm->PaymentMeansCode->value, ['30', '58'])
) {
    $iban = $pm->PayeeFinancialAccount->ID->value;
    $bic  = $pm->PayeeFinancialAccount
                ->FinancialInstitutionBranch
                ->FinancialInstitution
                ->ID->value ?? '';

    if (isset($pm->PayeeFinancialAccount->Name)
        && strlen($pm->PayeeFinancialAccount->Name ?? '') > 0
    ) {
        $name = $accountHolder ?: $pm->PayeeFinancialAccount->Name;
    }
    ...
}

Neu bzw. modifiziert sind nur die Zeilen mit $accountHolder.

Wirkung

  • Ist SEPA_QR_ACCOUNT_HOLDER gesetzt → dieser Wert wird verwendet
  • Ist er nicht gesetzt → Invoice Ninja verhält sich exakt wie vorher
  • Keine Nebenwirkungen für eInvoice, PaymentMeans oder andere Exporte

Cache leeren

Nach der Änderung einmal ausführen:

php artisan config:clear
php artisan cache:clear
php artisan optimize:clear

Update-Strategie

  • .env bleibt erhalten
  • config/ninja.php bleibt in der Regel erhalten
  • Nur eine Datei (EpcQrGenerator.php) muss nach Updates geprüft oder erneut gepatcht werden

Empfehlung: Den Diff als Patchfile aufbewahren und nach Updates gezielt wieder anwenden.

Ergebnis

  • SEPA-QR-Codes zeigen den korrekten Kontoinhaber
  • Banking-Apps interpretieren die Zahlung korrekt
  • Firmenname bleibt dort, wo er hingehört
  • Lösung ist nachvollziehbar, wartbar und reversibel

Noch ein Haken

Solange der Wert so in .env steht greift der Account Holder für ALLE Companies im Invoice Ninja und damit it das nicht voll mandantenfähig. Um das sauber zu machen, ist etwas mehr Aufwand nötig.

Zuletzt aktualisiert am 2. Januar 2026.