Kapitel 3. Verwendung

Mit der Bestellung von libsepa erhalten Sie einen Lizenzcode, der auf Ihren Namen ausgestellt ist. Um die Einschränkungen der Demoversion aufzuheben, rufen Sie nach dem Start Ihres Programmes immer die Funktion SEPA::init() wie folgt auf:

bool SEPA::init(int $option, string $value);

// PHP / Perl
SEPA::init(SEPA_INIT_LICUSER, "Ihr Benutzername");   # lizenzierter Benutzername
SEPA::init(SEPA_INIT_LICCODE, "XXXXX-XXXXX-XXXXX");  # Lizenzcode

# Perl
SEPA::init(SEPA_INIT_LICUSER, "Ihr Benutzername");   # lizenzierter Benutzername
SEPA::init(SEPA_INIT_LICCODE, "XXXXX-XXXXX-XXXXX");  # Lizenzcode

// Java
import com.libsepa.*;
SEPA.init(SEPA_INIT_LICUSER, "Ihr Benutzername");    // lizenzierter Benutzername
SEPA.init(SEPA_INIT_LICCODE, "XXXXX-XXXXX-XXXXX");   // Lizenzcode

Ohne Lizenz erlaubt libsepa lediglich bis zu drei Lastschriften oder Überweisungen in einer Datei.

libsepa kann die IBAN und BIC für gültige deutsche Bankverbindungen berechnen (siehe Hintergrund zur IBAN-Konvertierung).

string SEPA::IBAN_convert(string $country, string $account, string $bank_id [, int &$status ] );

// PHP
$iban = SEPA::IBAN_convert("DE", "4020000002", "30120764");
$iban = SEPA::IBAN_convert("DE", "4020000002", "30120764", $status);

# Perl
my $iban = SEPA::IBAN_convert("DE", "4020000002", "30120764");
my $iban = SEPA::IBAN_convert("DE", "4020000002", "30120764", \$status);

// Java
String iban = SEPA.IBAN_convert("DE", "4020000002", "30120764");

string SEPA::IBAN_getBIC(string $iban);

// PHP
$bic = SEPA::IBAN_getBIC("DE12987654320012345678");

# Perl
my $bic = SEPA::IBAN_getBIC("DE12987654320012345678");

// Java
String bic = SEPA.IBAN_getBIC("DE12987654320012345678");

Bitte beachten Sie, dass für Österreich, Schweiz und Liechtenstein keine Korrektheit der „errechneten“ BIC garantiert werden kann, da libsepa lediglich anhand der frei verfügbaren BLZ-Tabellen die dazugehörige BIC heraussuchen kann. Eine garantiert richtige BIC erhalten Sie im Rahmen des „offiziellen“ Konvertierungsprozesses über den IBANService (Österreich) bzw. das IBAN-Tool (Schweiz).

Eine weitere Besonderheit ist, dass die BIC nicht zwangsläufig den selben Ländercode tragen muss wie die IBAN. Beispiel:

Erzeugen Sie ein SEPA-Objekt mit dem Nachrichtentyp SEPA_MSGTYPE_DDI:

SEPA SEPA(int $msgtype);

// PHP
$sepa = new SEPA(SEPA_MSGTYPE_DDI);

# Perl
my $sepa = new SEPA(SEPA_MSGTYPE_DDI);

// Java
SEPA sepa = new SEPA(SEPA.SEPA_MSGTYPE_DDI);

Diesem Objekt fügen Sie dann der Reihe nach den Namen des Zahlungsempfängers (setName()), dessen Gläubiger-ID (setCreditorIdentifier()), IBAN (setIBAN()) und BIC (setBIC()) hinzu:

bool $sepa->setName(string $name);
bool $sepa->setCreditorIdentifier(string $ci);
bool $sepa->setIBAN(string $iban);
bool $sepa->setBIC(string $bic);

// PHP
$sepa->setIBAN("DE87200500001234567890");            // IBAN des Zahlungsempfängers
$sepa->setBIC("BANKDEFFXXX");                        // BIC des Zahlungsempfängers
$sepa->setName("Mustermann u. Co. KG");              // Name des Zahlungsempfängers
$sepa->setCreditorIdentifier("DE20ZZZ00987654321");  // Gläubiger-Identifikationsnummer

# Perl
$sepa->setIBAN("DE87200500001234567890");            # IBAN des Zahlungsempfängers
$sepa->setBIC("BANKDEFFXXX");                        # BIC des Zahlungsempfängers
$sepa->setName("Mustermann u. Co. KG");              # Name des Zahlungsempfängers
$sepa->setCreditorIdentifier("DE20ZZZ00987654321");  # Gläubiger-Identifikationsnummer

// Java
sepa.setIBAN("DE87200500001234567890");              // IBAN des Zahlungsempfängers
sepa.setBIC("BANKDEFFXXX");                          // BIC des Zahlungsempfängers
sepa.setName("Mustermann u. Co. KG");                // Name des Zahlungsempfängers
sepa.setCreditorIdentifier("DE20ZZZ00987654321");    // Gläubiger-Identifikationsnummer

Optional können Sie das Einzugsdatum festlegen (Format: yyyy-mm-dd). Wird kein Datum gesetzt, so wird durch die Bank automatisch der frühestmögliche Termin gewählt. Sollte das gewünschte Datum vor dem frühestmöglichen Datum liegen (Einreichfrist!), so passt die Bank dieses i.d.R. automatisch an.

bool $sepa->setDate(string $date);

// PHP
$sepa->setDate("2013-12-14");

# Perl
$sepa->setDate("2013-12-14");

// Java
sepa.setDate("2013-12-14");

Normalerweise werden alle Lastschriften in einem Block gebucht. Mit der Funktion setBatchBooking können Sie dieses Verhalten optional auf Einzelbuchungen umstellen. Bitte beachten Sie, dass Ihre Bank dieses Verfahren in manchen Fällen erst freischalten muss.

bool $sepa->setBatchBooking(bool $enabled);

// PHP
$sepa->setBatchBooking(FALSE);

# Perl
$sepa->setBatchBooking(0);

// Java
sepa.setBatchBooking(false);

Standardmäßig erzeugt libsepa SEPA-Basislastschriften („CORE“). Mit dem Befehl setDDType() können Sie alternativ auch „COR-1“- oder „B2B“-Lastschriften erzeugen:

bool $sepa->setDDType(int $ddtype);

// PHP
$sepa->setDDType(SEPA_DDTYPE_B2B);

# Perl
$sepa->setDDType(SEPA_DDTYPE_B2B);

// Java
sepa.setDDType(SEPA.SEPA_DDTYPE_B2B);

Die einzelnen Transaktionen übergeben Sie anschließend mittels der Methode add() als Objekt/Hashreferenz:

bool $sepa->add(object $tx);

// PHP
$tx = array(
  'seq'    => 'FRST',                                // Lastschrift-Typ (hier: Ersteinzug)
  'id'     => 'R2017742-1',                          // Transaktions-ID
  'name'   => 'Karl Kunde',                          // Name des Zahlungspflichtigen
  'mref'   => 'Mandats-Referenz',                    // Mandats-Referenz
  'mdate'  => '2013-09-24',                          // Unterschrifts-Datum des Mandats
  'amount' => 123.45,                                // abzubuchender Betrag
  'iban'   => 'DE12987654320012345678',              // IBAN des Zahlungspflichtigen
  'bic'    => 'BANKDEZZXXX',                         // BIC des Zahlungspflichtigen
  'ref'    => 'Rechnung R2017742 vom 17.10.2013',    // Verwendungszweck (eine Zeile, max. 140 Zeichen)
);
$sepa->add($tx);

# Perl
my $tx = {
  'seq'    => 'FRST',                                # Lastschrift-Typ (hier: Ersteinzug)
  'id'     => 'R2017742-1',                          # Transaktions-ID
  'name'   => 'Karl Kunde',                          # Name des Zahlungspflichtigen
  'mref'   => 'Mandats-Referenz',                    # Mandats-Referenz
  'mdate'  => '2013-09-24',                          # Unterschrifts-Datum des Mandats
  'amount' => 123.45,                                # abzubuchender Betrag
  'iban'   => 'DE12987654320012345678',              # IBAN des Zahlungspflichtigen
  'bic'    => 'BANKDEZZXXX',                         # BIC des Zahlungspflichtigen
  'ref'    => 'Rechnung R2017742 vom 17.10.2013',    # Verwendungszweck (eine Zeile, max. 140 Zeichen)
};
$sepa->add($tx);

// Java
String[][] tx = {
  { "seq",    "FRST" },                              // Lastschrift-Typ (hier: Ersteinzug)
  { "id",     "R2017742-1" },                        // Transaktions-ID
  { "name",   "Karl Kunde" },                        // Name des Zahlungspflichtigen
  { "mref",   "Mandats-Referenz" },                  // Mandats-Referenz
  { "mdate",  "2013-09-24" },                        // Unterschrifts-Datum des Mandats
  { "amount", "123.45" },                            // abzubuchender Betrag
  { "iban",   "DE12987654320012345678" },            // IBAN des Zahlungspflichtigen
  { "bic",    "BANKDEZZXXX" },                       // BIC des Zahlungspflichtigen
  { "ref",    "Rechnung R2017742 vom 17.10.2013" },  // Verwendungszweck (eine Zeile, max. 140 Zeichen)
};
sepa.add(tx);

Sollten sich seit der letzten Abbuchung von diesem Zahlungspflichtigen Änderungen am Lastschriftmandat ergeben haben, so müssen diese mit folgenden Parametern mitgeteilt werden:

Bei Lastschriften außerhalb der EU/EWR ist gemäß der Geldtransferverordnung (EU 2015/847) mit dem Rulebook 3.1 die Anschrift des Zahlungspflichtigen mit anzugeben. Dies betrifft derzeit folgende Länder: Schweiz (CH), Monaco (MC), San Marino (SM), Jersey (JE), Guernsey (GG), Isle of Man (IM), St. Pierre und Miquelon (PM):

Am Ende erzeugen Sie mit der Methode toXML() aus den Objektdaten das gewünschte SEPA-XML:

string $sepa->toXML();

// PHP
$xml = $sepa->toXML();

# Perl
my $xml = $sepa->toXML();

// Java
String xml = sepa.toXML();

Die XML-Daten können Sie dann z.B. in einer Datei speichern und per EBICS oder FinTS/HBCI zur Buchung an Ihre Bank schicken.

Die Erstellung von Überweisungen läuft analog zur Erstellung von Lastschriften. Lediglich die Lastschrift-spezifischen Eigenschaften (Gläubiger-ID, Lastschrift-Sequenz, Mandatsinformationen) werden nicht benötigt.

Das SEPA-Objekt für Überweisungen erzeugen Sie mit dem Nachrichtentyp SEPA_MSGTYPE_CTI:

SEPA SEPA(int $msgtype);

// PHP
$sepa = new SEPA(SEPA_MSGTYPE_CTI);

# Perl
my $sepa = new SEPA(SEPA_MSGTYPE_CTI);

// Java
SEPA sepa = new SEPA(SEPA.SEPA_MSGTYPE_CTI);

Diesem Objekt fügen Sie dann der Reihe nach den Namen des Auftraggebers (setName()), dessen IBAN (setIBAN()) und BIC (setBIC()) hinzu:

bool $sepa->setName(string $name);
bool $sepa->setIBAN(string $iban);
bool $sepa->setBIC(string $bic);

// PHP
$sepa->setIBAN("DE87200500001234567890");            // IBAN des Zahlungspflichtigen
$sepa->setBIC("BANKDEFFXXX");                        // BIC des Zahlungspflichtigen
$sepa->setName("Mustermann u. Co. KG");              // Name des Zahlungspflichtigen

# Perl
$sepa->setIBAN("DE87200500001234567890");            # IBAN des Zahlungspflichtigen
$sepa->setBIC("BANKDEFFXXX");                        # BIC des Zahlungspflichtigen
$sepa->setName("Mustermann u. Co. KG");              # Name des Zahlungspflichtigen

// Java
sepa.setIBAN("DE87200500001234567890");              // IBAN des Zahlungspflichtigen
sepa.setBIC("BANKDEFFXXX");                          // BIC des Zahlungspflichtigen
sepa.setName("Mustermann u. Co. KG");                // Name des Zahlungspflichtigen

Normalerweise werden alle Überweisungen in einem Block gebucht. Mit der Funktion setBatchBooking können Sie dieses Verhalten optional auf Einzelbuchungen umstellen. Bitte beachten Sie, dass Ihre Bank dieses Verfahren in manchen Fällen erst freischalten muss.

bool $sepa->setBatchBooking(bool $enabled);

// PHP
$sepa->setBatchBooking(FALSE);

# Perl
$sepa->setBatchBooking(0);

// Java
sepa.setBatchBooking(false);

Die einzelnen Transaktionen übergeben Sie anschließend mittels der Methode add() als Objekt/Hashreferenz:

bool $sepa->add(object $tx);

// PHP
$tx = array(
  'id'     => 'C12345-6789-0',                       // (optional) Transaktions-ID
  'name'   => 'Manfred Mitarbeiter',                 // Name des Zahlungsempfängers
  'amount' => 2345.67,                               // zu überweisender Betrag
  'iban'   => 'DE12987654320012345678',              // IBAN des Zahlungsempfängers
  'bic'    => 'BANKDEZZXXX',                         // BIC des Zahlungsempfängers
  'ref'    => 'Gehalt September 2013',               // Verwendungszweck (eine Zeile, max. 140 Zeichen)
  'purp'   => 'SALA',                                // (optional) Zahlungstyp
);
$sepa->add($tx);

# Perl
my $tx = {
  'id'     => 'C12345-6789-0',                       # (optional) Transaktions-ID
  'name'   => 'Manfred Mitarbeiter',                 # Name des Zahlungsempfängers
  'amount' => 2345.67,                               # zu überweisender Betrag
  'iban'   => 'DE12987654320012345678',              # IBAN des Zahlungsempfängers
  'bic'    => 'BANKDEZZXXX',                         # BIC des Zahlungsempfängers
  'ref'    => 'Gehalt September 2013',               # Verwendungszweck (eine Zeile, max. 140 Zeichen)
  'purp'   => 'SALA',                                # (optional) Zahlungstyp
};
$sepa->add($tx);

// Java
String[][] tx = {
  { "id",     "C12345-6789-0" },                     // (optional) Transaktions-ID
  { "name",   "Manfred Mitarbeiter" },               // Name des Zahlungsempfängers
  { "amount", "2345.67" },                           // zu überweisender Betrag
  { "iban",   "DE12987654320012345678" },            // IBAN des Zahlungsempfängers
  { "bic",    "BANKDEZZXXX" },                       // BIC des Zahlungsempfängers
  { "ref",    "Gehalt September 2013" },             // Verwendungszweck (eine Zeile, max. 140 Zeichen)
  { "purp",   "SALA" },                              // (optional) Zahlungstyp
};
sepa.add(tx);

Vermögenswirksame Leistungen

Für die Zahlung von vermögenswirksamen Leistungen (VL) muss als Zahlungszweck (Parameter „purp“) immer CBFF angegeben werden. Für den Verwendungszweck (Feld „ref“) gibt es derzeit zwei gängige Codierungsvarianten:

Für die Erzeugung von SEPA-Überweisungen (pain.001) und SEPA-Lastschriften (pain.008) gelten genaue Vorschriften, die in einem sogenannten SEPA-Rulebook festgelegt sind. libsepa unterstützt derzeit folgende Rulebooks:

Mit der Funktion SEPA::init() können Sie festlegen, welches Rulebook zur Erstellung der SEPA-XML-Datei angewendet werden soll. Seit dem 21.11.2021 verwendet libsepa automatisch das Rulebook DE-3.5.

WICHTIG: die Rulebook-Version DE-3.7 gilt ab dem 17.03.2024. Da der Gültigkeitstermin aber schonmal verschoben wurde, kann es sein, dass nicht alle Banken dieses sofort ab diesem Termin unterstützen. Aus diesem Grund ist bis auf Weiteres (Stand: libsepa 2.26) standardmäßig das Rulebook DE-3.5 aktiv. Das Rulebook 3.7 müssen Sie bei Bedarf manuell aktivieren (s.u.).

Falls Ihre Bank beim Einreichen der SEPA-XML-Dateien eine Fehlermeldung in der Form „Version/Format nicht unterstützt“ bringt, stellen Sie versuchsweise mal auf eine „ältere“ Version um:

bool SEPA::init(int $option, string $value);

// PHP / Perl
SEPA::init(SEPA_INIT_RULEBOOK, "DE-3.1");

# Perl
SEPA::init(SEPA_INIT_RULEBOOK, "DE-3.1");

// Java
SEPA.init(SEPA_INIT_RULEBOOK, "DE-3.1");