API-Version 6

Dieser Artikel beschreibt die Neuerungen und Änderungen der API-Version 6 im Vergleich zur API-Version 5

Eine Einführung einer neuen Version erfolgt, wenn durch eine Änderung die Abwärtskompatibilität der API nicht mehr sichergestellt werden kann. Bitte prüfen Sie vor dem Wechsel auf diese API-Version ob die Änderungen Auswirkungen auf Ihr System haben und führen Sie die notwendigen Anpassungen durch.

Ziele

Mit der Veröffentlichung von API-Version 6 haben wir uns bewusst dazu entschieden, tiefgreifende strukturelle Änderungen vorzunehmen. Diese Version enthält deutlich mehr Anpassungen als ein üblicher API-Versionswechsel. Statt inkrementelle Änderungen über viele kleinere Updates hinweg zu verteilen, haben wir die Gelegenheit genutzt, so viele Neuerungen wie möglich in einem einzigen großen Schritt zusammenzuführen.

Unser Ziel war es, die API skalierbarer, effizienter und zukunftssicherer zu gestalten. Während unsere Plattform weiter wächst, steigen auch die Anforderungen an unsere Infrastruktur und die Erwartungen unserer Nutzer. Um diesen Herausforderungen gerecht zu werden, haben wir zentrale Funktionen implementiert, die Leistung, Zuverlässigkeit und Flexibilität verbessern.

Wir veröffentlichen neue API-Versionen nur, wenn wir es als absolut notwendig erachten. Dabei verfolgen wir das Ziel, in einem solchen Schritt möglichst viele Änderungen zu bündeln. So stellen wir sicher, dass unsere Kunden nicht durch häufige Migrationsaufwände belastet werden und eine API-Version über einen langen Zeitraum genutzt werden kann, ohne an Aktualität zu verlieren.

Wichtige Neuerungen

1. Paging: Um die Antwortzeiten zu verkürzen und den Datentransfer zu optimieren, führen wir Paging in unserer API ein. Anstatt alle Daten auf einmal zurückzugeben, liefert API Version 6 die Informationen in kleineren, handlichen Paketen von 100 Einträgen pro Seite. Dies ermöglicht eine effizientere Datenverarbeitung sowohl auf der Server- als auch auf der Client-Seite, was zu schnelleren Ladezeiten und einer verbesserten Gesamtleistung führt. Weitere Informationen hierzu finden Sie im Abschnitt Paging.

2. Rate Limiting: Um eine faire und zuverlässige Nutzung für alle Nutzer sicherzustellen, führen wir ein Ratenbegrenzungssystem (Rate Limiting) ein. Dieses System schützt unsere Infrastruktur vor Überlastung und sorgt gleichzeitig dafür, dass alle Nutzer von gleichbleibender Leistung profitieren können. Weitere Informationen hierzu finden Sie im Abschnitt Rate Limiting.

3. Fokus auf JSON: Ab API-Version 6 entfällt die Unterstützung für XML (application/xml, text/xml). Unsere API verarbeitet und liefert Daten künftig ausschließlich im JSON-Format (application/json). Diese Entscheidung wurde getroffen, da sich JSON als Standard für REST-APIs etabliert hat und die Fokussierung auf ein einheitliches Format eine effizientere Wartung sowie schnellere Weiterentwicklungen ermöglicht. Weitere Informationen hierzu finden Sie im Abschnitt Datenformate.

Warum diese Änderungen wichtig sind

Unser Ziel mit Version 6 ist es, eine API zu entwickeln, die sich nahtlos skalieren lässt, während sowohl das Datenvolumen als auch der Nutzerdurchsatz steigt. Diese Verbesserungen sorgen dafür, dass die API auch bei wachsendem Datenbestand und steigender Nutzeraktivität eine zuverlässige, schnelle und effiziente Dienstleistung erbringt. Durch die Ausrichtung unserer API an Branchengrundsätzen bieten wir Entwicklern eine konsistente und stabile Grundlage für zukünftige Entwicklungen.

Zusammengefasst ist API Version 6 ein Schritt in Richtung einer robusteren Plattform, die den sich wandelnden Anforderungen unserer Nutzer gerecht wird und größere Datenmengen sowie erhöhten Traffic bewältigen kann, ohne die Leistung zu beeinträchtigen. Wir sind überzeugt, dass diese Änderungen nicht nur die aktuelle Nutzererfahrung verbessern, sondern auch die Weichen für weiteres Wachstum und Erfolg in der Zukunft stellen.

Alle Änderungen im Überblick

Generelle Änderungen

Paging

Mit der neuen Version unserer API wurde Paging für alle API-Endpunkte eingeführt, die eine Liste von Elementen zurückgeben, um die Abfrage großer Datenmengen effizienter zu gestalten. Standardmäßig werden bei einer Anfrage 100 Einträge pro Seite zurückgegeben, wobei diese Zahl über den Parameter pageSize auf bis zu 1000 Einträge erhöht werden kann. Über den Parameter pageNumber kann festgelegt werden, welche Seite der Ergebnisse abgerufen wird. Der zurückgegebene Inhalt wird nun in einem Wrapper-Element bereitgestellt, wobei die eigentlichen Daten im Element results enthalten sind. Das Wrapper-Element selbst liefert zusätzliche Informationen wie die Anzahl der Einträge pro Seite, die aktuelle Seite, die Gesamtanzahl der Seiten und die Gesamtzahl aller Elemente über alle Seiten hinweg. Im folgenden Beispiel sehen Sie die Struktur der neuen Paging-Antwort:

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 2,
  "links": [
    {
      "href": "https://portal.konfipay.de/api/v6/Example?pageNumber=1&pageSize=100",
      "rel": "self",
      "method": "GET"
    }
  ],
  "results": [
    . . .
  ]

Bisher wurden Listen in einer verschachtelten Struktur zurückgegeben und waren in einem übergeordneten Element beinhaltet.

Beispiel (übergeordnetes Element: documentItems)

{
  "documentItems": [
    {
      "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
      "href": "api/v5.0/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814",
      "timestamp": "2025-02-27T09:33:43+01:00",
      "iban": "DE12345678901234567890",
      "isNew": true,
      "format": "camt.053",
      "fileName": "2025-02-26_C53_DE12345678901234567890_EUR_21-00001.xml"
    },
    {
      "rId": "fa727310-3072-4abc-a982-b511b8b81108",
      "href": "api/v5.0/Document/Camt/fa727310-3072-4abc-a982-b511b8b81108",
      "timestamp": "2025-02-27T10:45:56+01:00",
      "iban": "DE12345678901234567890",
      "isNew": true,
      "format": "camt.053",
      "fileName": "2025-02-27_C53_DE12345678901234567890_EUR_21-00002.xml"
    }
  ]
}

Mit der Einführung von Paging wird auf diese zusätzliche Ebene verzichtet. Listen werden in diesem Fall direkt im results Element zurückgegeben. Diese Änderung erstreckt sich auf alle Stellen der API.

Rate Limiting

Um eine ausgewogene Verteilung der Ressourcen sicherzustellen, haben wir in unserer API standardmäßige Rate-Limiting-Werte implementiert:

• Öffentliche Endpunkte (z.B. Authentifizierung): 100 Anfragen pro Minute

• Authentifizierte Endpunkte: 1000 Anfragen pro Minute

Diese Limits verhindern eine Überlastung der Ressourcen und gewährleisten eine stabile Leistung der API. Sollten Ihre Anforderungen über diese Standardlimits hinausgehen, bieten wir Ihnen die Möglichkeit, die Rate-Limits auf Anfrage individuell zu erhöhen. Senden Sie hierzu bitte eine entsprechende Anfrage an support@konfipay.de.

Basierend auf der aktuellen API-Nutzung werden wir bereits einige Kunden zur Veröffentlichung auf höhere Limits angeheben, um eine unterbrechungsfreie Nutzung sicherzustellen.

Wichtig: Diese Anpassung gilt API-weit und betrifft nicht nur die API-Version 6, sondern alle Versionen der API. Die Einführung des Rate Limiting erfolgt zeitgleich mit der Veröffentlichung der API-Version 6, ist jedoch von dieser unabhängig.

Wird ein Limit überschritten, antwortet der Server mit dem HTTP-Statuscode 429 - Too Many Requests, was bedeutet, dass die maximale Anzahl an Anfragen pro Minute erreicht wurde. Der Client kann spätestens nach einer Minute wieder Anfragen stellen, da die Messung der API-Requests pro Minute erfolgt.

Datenformate

Ab API-Version 6 unterstützt unsere API ausschließlich JSON (application/json). Die bisherigen XML-Formate (application/xml, text/xml) werden ab dieser Version nicht länger unterstützt – weder für Anfragen noch für Antworten.

Die Entscheidung, XML nicht länger zu unterstützen, basiert auf einer Abwägung zwischen Entwicklungsaufwand und tatsächlicher Nutzung. JSON hat sich als Standardformat für REST-APIs etabliert und wird von den meisten modernen Anwendungen bevorzugt. Durch diese Fokussierung können wir unsere Ressourcen gezielt für die Weiterentwicklung und Optimierung der API einsetzen.

Falls Ihre Anwendung bisher XML verwendet hat, ist eine Umstellung auf JSON notwendig. Dies betrifft sowohl die gesendeten Anfragen als auch die Verarbeitung der API-Antworten.

Umbenennung von Feldnamen und Elementen

In dieser API-Version wurden einige Feldnamen angepasst, um die Lesbarkeit und Verständlichkeit zu verbessern. Das Wort „Item“ wurde beispielsweise aus allen Feldnamen und Elementen entfernt, da es redundant ist und keine zusätzlichen Bedeutungen hinzufügt. Die Änderungen beziehen sich ausschließlich auf die Bezeichnungen der Felder oder Elemente, ohne die zugrunde liegende Struktur oder die Datenformate zu verändern.

Beispiel für Änderungen von Elementen:

• relatedPaymentItems ➡️relatedPayments

• errorItems ➡️ errors

• paymentInfoItems ➡️ paymentInfos

Außerdem wurden alle Vorkommen von paymentStatusItem und documentStatusItem durch das einheitliche Element status ersetzt. Um Namenskonflikte zu vermeiden, wurde das ursprüngliche status Feld in statusValueumbenannt.

Beispiel API-Version 5:

{
  "status": "KON_REJECTED",
  "uploadTimestamp": "2025-01-08T13:55:50+01:00",
  "orderID": "A1BC",
  "reasonCode": "TD02",
  "reason": "The file cannot be read (unknown format)",
  "additionalInformation": "Additional information 1",
  "errorItem": {
    "errorCode": "ERR-00-0000",
    "errorMessage": "ErrorMessage1",
    "errorDetails": "ErrorDetails1",
    "timestamp": "2025-01-08T13:55:50+01:00"
  }

Beispiel API-Version 6:

{
  "statusValue": "KON_REJECTED",
  "uploadTimestamp": "2025-01-08T13:55:50+01:00",
  "orderID": "A1BC",
  "reasonCode": "TD02",
  "reason": "The file cannot be read (unknown format)",
  "additionalInformation": "Additional information 1",
  "error": {
    "errorCode": "ERR-00-0000",
    "errorMessage": "ErrorMessage1",
    "errorDetails": "ErrorDetails1",
    "timestamp": "2025-01-08T13:55:50+01:00"
  }

API-Endpunkte: Vereinheitlichung & Umstrukturierung

Mit der Einführung von API-Version 6 haben wir verschiedene Anpassungen an den Endpunkten vorgenommen, um die Struktur und Lesbarkeit der API zu verbessern. Die Änderungen orientieren sich an allgemeinen REST-API-Standards und verbessern die Einheitlichkeit sowie die Konsistenz der API.

1. Entfernen des Zusatzes „item“

In vorherigen API-Versionen wurde für einzelne Ressourcen der Zusatz „item“ verwendet (z. B. paymentItem). Um die API klarer und einheitlicher zu gestalten, haben wir diesen Zusatz entfernt. Einzelne Ressourcen sind nun durch ihren Namen eindeutig erkennbar.

Beispiel:

• Vorher: api/v5/Document/Camt/{rid}/item

• Jetzt: api/v6/transaction-files/{rid}

Diese Änderung sorgt für eine schlankere und intuitivere API, ohne überflüssige Begriffe in den URLs.

2. Pluralisierung von Ressourcen

Um den allgemeinen REST-Standards besser zu entsprechen, wurden alle Ressourcen pluralisiert. Eine Ressource stellt eine Sammlung von Objekten dar, daher verwenden wir nun durchgehend Pluralformen für Ressourcennamen.

Beispiel:

• Vorher: api/v5/payment

• Jetzt: api/v6/payments

Diese Änderung verbessert die Konsistenz und sorgt für eine einheitliche Benennung innerhalb der API.

3. Einheitliche Kleinbuchstaben & Bindestriche in URLs

Wir haben alle Endpunkte in Kleinbuchstaben umgestellt und Bindestriche (-) als Trennzeichen eingeführt, um die Lesbarkeit zu verbessern.

Beispiel:

• Vorher: api/v5/ExchangeRates

• Jetzt: api/v6/exchange-rates

Diese Änderungen entsprechen modernen REST-API-Best Practices und sorgen für eine leichtere Handhabung, insbesondere für Entwickler, die mit verschiedenen APIs arbeiten.

Vereinheitlichung von Query-Parameter

Im Zuge der Vereinheitlichung der URLs wurden auch die Query-Parameter entsprechend angepasst. Diese Anpassungen umfassen die konsequente Verwendung von Kleinbuchstaben sowie die Nutzung von Bindestrichen in den Query-Parametern.

Beispiel:

• Vorher: api/v5/PayPal/Transaction/{rId}?forceUpdate=true

• Jetzt: api/v6/paypal/transactions/{rid}?force-update=true

Die konsequente Anwendung dieser Regeln verbessert die Lesbarkeit von API-Requests und fördert eine saubere, gut verständliche API-Struktur.

Darüber hinaus wurden häufig genutzte Query-Parameter über unterschiedliche Endpunkte hinweg vereinheitlicht. Diese Änderung betrifft hauptsächlich den Abruf von historischen Daten. Anstelle der bisherigen Parameter start und end müssen nun min-date und max-date angegeben werden. Die konsistente Nutzung einheitlicher Begriffe in der gesamten API vereinfacht die Arbeit mit verschiedenen Endpunkten. Zudem sind die Begriffe min-date und max-date präziser und definieren eindeutig die Grenzen eines Datumsbereichs.

Änderung der Quittierungslogik ab API-Version 6

Bis zur API-Version 5 wurde bei jedem Abruf von Daten (z. B. PayPal-Transaktionen, Kontoumsätze) automatisch ein Status gesetzt, der den jeweiligen Datensatz als "abgerufen" markierte. Zusätzlich wurden API-Endpunkte bereitgestellt, die ausschließlich Datensätze zurücklieferten, die noch nicht als abgerufen markiert waren. Dadurch mussten Clients nicht selbst nachverfolgen, welche Datensätze bereits verarbeitet wurden – diese Information wurde direkt in konfipay hinterlegt.

Ergänzend gab es die Möglichkeit, die automatische Quittierung durch Setzen des optionalen Parameters ack=false zu unterdrücken. In diesem Fall konnte die Quittierung über einen separaten API-Endpunkt erfolgen. Das Problem hierbei war, dass im Standardfall die Quittierung automatisch mit dem Abruf erfolgte. Trat während der Verarbeitung auf der Client-Seite ein Fehler auf, war der Datensatz in konfipay trotzdem bereits als abgerufen markiert – unabhängig davon, ob er erfolgreich verarbeitet wurde oder nicht.

Ab API-Version 6 wird die Quittierung nicht mehr automatisch beim Abruf gesetzt. Die neue Standardvorgehensweise erfordert eine zweistufige Verarbeitung:

1. Abruf des Datensatzes: Der Datensatz bleibt weiterhin als nicht abgerufen markiert.

2. Explizite Quittierung: Erst nach erfolgreicher Verarbeitung muss eine separate API-Anfrage zur Quittierung erfolgen.

Diese Änderung stellt eine fundamentale Anpassung des bisherigen Workflows dar. Wird dies beim Wechsel auf API-Version 6 nicht berücksichtigt, bleiben alle Datensätze als nicht abgerufen markiert und werden bei jeder Abfrage erneut zurückgeliefert.

Clients müssen daher sicherstellen, dass sie nach der erfolgreichen Verarbeitung eines Datensatzes die Quittierung explizit durchführen, um eine korrekte Statusverwaltung in konfipay zu gewährleisten.

Filtern und Suchen

Bis zur API-Version 5 war die API so aufgebaut, dass es für den Abruf von Daten (z. B. PayPal-Transaktionen oder Kontoumsatzdateien) immer zwei separate Endpunkte gab:

• Abruf neuer Daten: Liefert nur Datensätze zurück, die noch nicht als abgerufen markiert sind.

• Abruf historischer Daten: Ermöglicht den Abruf aller Datensätze innerhalb eines angegebenen Zeitraums (z. B. 01.01.2023 – 01.01.2024), unabhängig vom Quittierungsstatus.

Mit API-Version 6 wurde diese Trennung aufgehoben. Stattdessen gibt es nun einen einzigen API-Endpunkt für den Abruf von Daten in Listenform, der über flexible Filter-Parameter gesteuert wird.

Die bisherigen Filter für "neue" Datensätze oder für den historischen Abruf nach Zeitraum müssen (bzw. können, da sie optional sind) jetzt explizit als Filter-Parameter angegeben werden. Dadurch sind auch neue Kombinationen möglich, wie z. B.:

• Abruf aller neuen Transaktionen innerhalb eines bestimmten Zeitraums

• Abruf aller bereits quittierten Transaktionen in einem definierten Zeitraum

Diese Änderung bietet mehr Flexibilität und ermöglicht es Clients, weiterhin das bisherige Verhalten der API nachzubilden, indem sie die Filter-Parameter entsprechend setzen.

In diesem Rahmen wurde generell eine Reihe neuer Möglichkeiten zum Filtern und Suchen hinzugefügt. Zu diesen Parametern zählen (unter anderem):

• Beträge (minimaler Betrag / maximaler Betrag)

• Kontodaten (Bezeichnung, Iban, Kontoinhaber)

• Bankfachliche Informationen (Verwendungszweck, Kundenreferenz, Zahlungsart)

Eine vollständige Liste der jeweiligen Parameter kann der API Dokumentation entnommen werden.

Es ist insbesondere möglich, mehrere Parameter miteinander zu kombinieren. Bei der Kombination von Parametern sollte jedoch beachtet werden, dass sie sich unter Umständen gegenseitig ausschließen können. In diesem Fall führt die Abfrage zu keinem Ergebnis (204 - No Content).

Änderungen an bestehenden API-Endpunkten

Authentifizierung

Verpflichtende Angabe des Clients

In der neuen API-Version ist das Element client, welches Informationen über den Namen und die Version der Client-Software enthält, die den Authentifizierungs-Request sendet, nun verpflichtend.

Bisher war dieses Element optional. Die verpflichtende Angabe dieser Informationen ermöglicht es, eine bessere Unterstützung bei Problemen oder API-Integrationen zu leisten. Neben der schnelleren Identifikation von versionsspezifischen Fehlern können wir durch diese Angaben auch allgemeine Trends, Nutzungsmuster oder Probleme der verschiedenen Client-Versionen analysieren. Dies hilft uns, neue Features gezielt für die am häufigsten genutzten Versionen zu optimieren. Zudem erlaubt es eine bessere Dokumentation von Versionen und Kompatibilitäten, was zukünftige Migrationsprozesse für Kunden deutlich vereinfachen kann.

Beispiel eines Authentifizierungs-Requests:

{
  "apiKey": "JGtjzzFfDoU5UWFl14yalcpj2pwtd0kXHGfBDDBELMPbwcqLyRKBeuiYZ7BxTHi5",
  "client": {
    "name": "ClientApplicationName",
    "version": "1.0.0.0"
  }
}

Ende der Unterstützung für Cookie-Authentifizierung

Im Rahmen der Modernisierung unserer API haben wir uns dazu entschieden, die Unterstützung für die Cookie-Authentifizierung zu entfernen. Diese Entscheidung basiert auf gestiegenen Sicherheitsanforderungen, da Cookies anfällig für Angriffe wie Cross-Site Scripting (XSS) und Cross-Site Request Forgery (CSRF) sind. Stattdessen setzen wir auf die sicherere und flexiblere Bearer-Token-Authentifizierung, die sich in der Praxis als moderner Standard etabliert hat. Bearer Tokens bieten nicht nur einen besseren Schutz, sondern sind auch unabhängig von der Browser-Umgebung und ermöglichen so eine breitere Anwendbarkeit in modernen Anwendungen, wie mobilen Apps oder serverseitigen Diensten.

Restrukturierung der API-Endpunkte

Aufgrund der nicht länger unterstützten Cookie-Authentifizierung ab API-Version 6 (Auth/Login) wurden die API-Endpunkte für die Authentifizierung restrukturiert. Die bisherigen Endpunkte unter Auth/* wurden durch eine neue, klarere und konsistentere Namenskonvention ersetzt, die sich stärker an RESTful-Prinzipien orientiert.

Anpassung der Scopes

Aufgrund der Anpassung der API-Endpunkte, der Einführung neuer Endpunkte und der Entfernung nicht mehr benötigter Endpunkte wurden die API-Scopes aktualisiert.

Besonderheiten:

• Bei der Erstellung eines neuen API-Schlüssels über API-Version 5 oder älter:

  • Der Scope "PaymentStatus" wird verworfen und in "Payments" übersetzt.

  • Der Scope "Document" wird automatisch in "Documents" und "Transactions" aufgeteilt.

• Beim Abrufen von Scopes für bestehende API-Schlüssel:

  • Für API-Versionen ≤ 5 gibt die API weiterhin die alten Scope-Namen zurück.

  • Ab Version 6 werden ausschließlich die neuen Scopes verwendet.

Bankkonten

Neues Feld: Währung

In der API-Version 6 wird die Funktionalität zur Erstellung und Aktualisierung von Bankkonten erweitert, sodass künftig die Währung als zusätzlicher Parameter angegeben werden kann. Diese Erweiterung erleichtert die Implementierung von „Multi-Währungs-Funktionalitäten“ und sorgt für eine eindeutige Definition und Zuordnung während der Kontoerstellung oder -Aktualisierung.

Asynchrone Löschung von Bankkonten

In früheren API-Versionen konnten Bankkonten synchron gelöscht werden. Aufgrund der zunehmenden Abhängigkeiten im System, der wachsenden Datenmengen sowie der daraus resultierenden längeren Wartezeiten und höheren Systembelastung wurde der Prozess so optimiert, dass das Löschen von Bankkonten nun asynchron erfolgt. Diese Änderung erhöht die Skalierbarkeit, reduziert Timeouts und sorgt für eine bessere Systemstabilität sowie eine optimierte Benutzererfahrung. Nach erfolgreicher Initiierung des Löschprozesses gibt der API-Endpunkt eine Tracking-Kennung des Vorgangs zusammen mit dem initialen Status zurück.

Beispiel Antwort:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "statusCode": 1,
  "statusName": "Scheduled",
  "details": "Additional information 1",
  "operationStatusUrl": "https://portal.konfipay.de/api/v6.0/delete/status/5d12c087-be1e-456c-a33f-4f8750fa7814",
  "operationStatusMethod": "GET"
}

Statusabfrage des Löschvorgangs

Aufgrund der Einführung des asynchronen Löschvorgangs wird zusätzlich ein neuer API-Endpunkt bereitgestellt, welcher es ermöglicht, den aktuellen Status einer ausstehenden Löschung eines Bankkontos zu überprüfen. Dieser Endpunkt liefert Statusinformationen darüber, ob die Löschung in Bearbeitung, abgeschlossen oder ob ein Fehler aufgetreten ist.

Beispiel Antwort:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "statusCode": 3,
  "statusName": "Finished",
  "details": "Additional information 1"
}

Weitere Informationen zu dieser neuen API-Schnittstelle können der API-Dokumentation entnommen werden.

Aktivieren/Deaktivieren von Bankkonten

In dieser API-Version besteht die Möglichkeit, Bankkonten beim Erstellen oder Aktualisieren zu aktivieren oder zu deaktivieren. Falls ein Bankkonto aktiviert werden soll, so muss das Feld isActive auf true gesetzt werden. Falls das Feld auf false gesetzt wird, so wird das Bankkonto deaktiviert.

Inaktive Bankkonten werden in allen automatischen Prozessen (z. B. beim Abruf von Kontoumsätzen) nicht berücksichtigt. Für inaktive Konten können keine Zahlungsaufträge erstellt oder eingereicht werden.

Dokumente und Transaktionen

Neue Endpunkte

Mit API-Version 6 wurden zwei neue API-Endpunkte eingeführt, um eine klare Trennung zwischen bankfachlichen Dateien und den daraus extrahierten Transaktionsdaten (= Buchungen) zu schaffen:

• Transactions API: Ermöglicht den direkten Abruf von Buchungen in strukturierter Form als JSON. Damit entfällt die Notwendigkeit, Kontoumsatzdateien selbst auszuwerten.

• Transaction Files API: Bietet weiterhin den Zugriff auf die originalen Kontoumsatzdateien (z. B. camt.053) und Vormerkposten, falls diese benötigt werden.

Bisher war es bei Nutzung der Documents API notwendig, Kontoumsatzdateien abzurufen und manuell auszuwerten. Die neue Transactions API übernimmt diesen Schritt, indem konfipay die enthaltenen Buchungen extrahiert und direkt als JSON bereitstellt. Dadurch ist keine eigene Verarbeitung bankfachlicher Dateien mehr erforderlich.

Die Transaction Files API übernimmt in diesem Zusammenhang die Funktion der Documents API für Kontoumsatzdateien und Vormerkposten und ersetzt diese in diesem Bereich. Andere bankfachliche Dokumente bleiben weiterhin über die Documents API verfügbar.

Zusätzlich wurde die bisherige Trennung der Endpunkte für MT94X und camt aufgehoben. Beide Formate sind nun über die Transaction Files API verfügbar. Falls erforderlich, kann die Formatunterscheidung über die Filter-Parameter der Transaction Files API erfolgen.

Quittierung von Kontoumsatzdaten

Um die potenziell große Menge an Kontoumsatzdaten und die damit verbundene hohe Anzahl an API-Requests zu minimieren, wird in dieser API-Version vorerst auf eine separate Quittierung pro Transaktion verzichtet.

Stattdessen wird in dieser Version die Möglichkeit geschaffen, vollständige Listen der abgerufenen Ergebnisse mit einer Quittierung zu versehen.

Dafür wird beim Abruf von Kontoumsatzdaten der Liste von Kontoumsätzen (transactions) eine temporäre ID (acknowledgementID) zugewiesen. Diese ID bleibt für eine Stunde gültig oder wird nach der Quittierung gelöscht. Die ID fasst die Kontoumsätze zusammen, welche auf einer Seite der Abfrage gruppiert wurden und kann genutzt werden, um die Umsätze auf dieser Seite zu quittieren. In diesem Fall ändert sich der Status der Transaktionen von isNew=true zu isNew=false.

Beispiel:

{
  "pageNumber": 1,
  "pageSize": 1000,
  "totalPages": 1,
  "totalItems": 2,
  "links": [
    {
      "href": "https://portal.konfipay.de/api/v6/Example?pageNumber=1&pageSize=1000",
      "rel": "self",
      "method": "GET"
    }
  ],
  "results": {
    "acknowledgementId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
    "transactions": [
      {
        "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
        "timestamp": "2025-02-18T08:53:51+01:00",
        "amount": 10.99,
        "currency": "EUR",
        "creditDebitIndicator": "CRDT",
        "electronicSequenceNumber": "74",
        "name": "Alice Mayer",
        "iban": "DE12345678901234567890",
        "bic": "ABCDEFG1CBA",
        "bookingText": "SAMMELÜBERWEISUNG",
        "bookingDate": "2025-02-18T10:06:04+01:00",
        "valueDate": "2025-02-18T10:06:04+01:00",
        "isNew": false,
        "bankReference": "bankRefernceNumber",
        "paymentIdentificationId": "konfipay-1-11111",
        "primaNota": "9301",
        "document": {
          "rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
          "timestamp": "2025-02-18",
          "isNew": true,
          "format": "camt.052"
        },
        "bankAccount": {
          "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
          "iban": "DE09876543210987654321",
          "currency": "EUR"
        }
      },
      {
        "rId": "fa727310-3072-4abc-a982-b511b8b81108",
        "timestamp": "2025-02-18T08:53:51+01:00",
        "amount": 500,
        "currency": "EUR",
        "creditDebitIndicator": "DBIT",
        "electronicSequenceNumber": "82",
        "name": "Alice Mayer",
        "iban": "DE12345678901234567890",
        "bic": "ABCDEFG1CBA",
        "bookingText": "GUTSCHRIFT ÜBERWEISUNG",
        "bookingDate": "2025-02-18T10:06:04+01:00",
        "valueDate": "2025-02-18T10:06:04+01:00",
        "isNew": true,
        "bankReference": "bankRefernceNumber",
        "paymentIdentificationId": "konfipay-1-11112",
        "primaNota": "9301",
        "document": {
          "rId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
          "timestamp": "2025-02-18",
          "isNew": true,
          "format": "camt.053"
        },
        "bankAccount": {
          "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
          "iban": "DE09876543210987654321",
          "currency": "EUR"
        }
      }
    ]
  }
}

Neue Felder: Auszugsnummer und elektronische Auszugsnummer bei Camt und MT940

Beim Abruf bankfachlicher Kontoumsatzdokumente (camt und MT94X) wurde die Antwort um zwei neue Felder erweitert: die Auszugsnummer (legalSequenceNumber) und die elektronische Auszugsnummer (electronicSequenceNumber). Beide Felder sind optional und spiegeln die Angaben wider, die in den von der jeweiligen Bank bereitgestellten Dokumenten enthalten sind.

Neues Element: Informationen über den Kontoinhaber bei Camt und MT940

In den älteren API-Versionen konnte die IBAN zur Abfrage von Kontoumsatzdokumenten verwendet werden. Da die IBAN jedoch mittlerweile nicht mehr eindeutig ist, können beim Abruf ggf. die Umsätze von zwei verschiedenen Konten ausgeliefert werden. Aus diesem Grund wird in dieser API-Version die Antwort von bankfachlichen Kontoumsatzdokumenten (camt und MT940) um ein neues Element erweitert: die Informationen über das zugrundeliegende Bankkonto (bankAccount). Dieses neue Element umfasst wichtige Informationen wie RID, IBAN und Währung (currency) des Bankkontos. Es sorgt für eine transparentere und genauere Zuordnung zu einem bestehenden Bankkonto, selbst bei der Verwendung verschiedener Währungen.

Beispiel:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "href": "api/v6.0/transaction-files/5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2025-02-26T11:14:25+01:00",
  "isNew": false,
  "format": "camt.053",
  "fileName": "2025-02-25_C53_DE12345678901234567890_EUR_21-00001.xml",
  "electronicSequenceNumber": 1,
  "legalSequenceNumber": 1,
  "bankAccount": {
    "rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
    "iban": "DE12345678901234567890",
    "currency": "EUR"
  }
}

Zahlungen und Zahlungsdateien

Abruf der Zahlungsübersicht

Mit der API-Version 6 wird eine Erweiterung im Zahlungsbereich eingeführt, welche eine Auflistung der vorhandenen Zahlungsdateien ermöglicht. Bei der Abfrage können diverse Parameter genutzt werden, um die Ergebnisliste nach verschiedenen Kriterien zu filtern. So lassen sich Zahlungen gezielt nach Zahlungsart (purpose), Zahlungstyp (payment-type) (z. B. Überweisungen, Lastschriften usw.), Zahlungsstatus (status), Erstellungsdatum (min-date/max-date) oder Ausführungsdatum (min-execution-date/max-execution-date) filtern. Weitere Informationen zu dieser neuen API-Schnittstelle können der API-Dokumentation entnommen werden.

Zusammenfassen der API-Endpunkte von Zahlungen

Die Neustrukturierung der Endpunkte für Zahlungen umfasst das Zusammenfassen verschiedener API-Schnittstellen zur Übermittlung und zum Abruf von Zahlungsdateien. Folgende Endpunkte wurden zusammengefasst:

Im Standard erkennt konfipay automatisch das Format von eingereichten Zahlungsaufträgen. Die automatische Erkennung kann über den scopeparameter überschrieben werden.

Einreichung ohne Übertragung

Mit dieser API-Version wurde die Möglichkeit hinzugefügt, Zahlungsdateien beim Import in konfipay nicht sofort an die Bank zu übertragen, sondern zunächst nur im System zu speichern. Um diese flexible Verarbeitung zu ermöglichen, wurde ein neuer API-Endpunkt eingeführt: POST /api/v6/payment-files/{rid}/submit.

Dieser Endpunkt ermöglicht die manuelle Übertragung einer zuvor erstellten Zahlungsdatei an das Rechenzentrum der Bank. Falls eine Datei bereits übermittelt wurde, erfolgt keine erneute Übertragung. Eine erneute Übermittlung kann jedoch erzwungen werden, indem der Query-Parameter force=true gesetzt wird.

Eine erneute Übermittlung bereits gesendeter Zahlungsdateien wird nur empfohlen, wenn diese von der Bank abgelehnt wurden. In solchen Fällen ermöglicht der force-Parameter einen erneuten Versuch, ohne eine neue Zahlungsdatei erstellen zu müssen.

Weitere Informationen zu dieser neuen API-Schnittstelle können der API-Dokumentation entnommen werden.

Extrahieren von Einzelzahlungen aus Zahlungsdateien in die offenen Aufträge

Die API-Version 6 bietet die Möglichkeit Zahlungsaufträge aus einer Zahlungsdatei direkt in die offenen Aufträge zu übernehmen, ohne dass eine Dateiübertragung an die Bank oder eine Speicherung der Zahlungsdatei erfolgt ( POST/api/v6/payment-files/extract). Sobald die Zahlungen aus der Zahlungsdatei extrahiert wurden, können diese bearbeitet werden und zu neuen Zahlungsdateien kombiniert werden. Darüber hinaus werden die gemeinsam importierten Aufträge mit einer eindeutigen Batch-RID versehen, um auch nachträglich eine Zuordnung zur ursprünglichen Zahlungsdatei sicherzustellen.

Beispiel Antwort:

[
  {
    "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
    "timestamp": "2025-02-18T08:53:48+01:00",
    "batch": {
      "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
      "numberOfElements": 2
    },
    ...
  },
  {
    "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
    "timestamp": "2025-02-18T08:53:48+01:00",
    "batch": {
      "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
      "numberOfElements": 2
    },
    ...
  }
]

Einreichung von Zahlungsaufträgen als (ehemals “ccft”)

In API-Version 6 wurde der bisherige Endpunkt /api/v5/Payment/Custom/Windata/Ccft durch /api/v6/payments ersetzt. Gleichzeitig wurde der Workflow für die Übertragung von Zahlungen zur Bank überarbeitet.

Bisher wurden eingereichte Zahlungen direkt in SEPA-Dateien umgewandelt und unmittelbar an die Bank übermittelt. Ab API-Version 6 erfolgt dies nun in zwei separaten Schritten:

1. Zahlungen einreichen:

   • Zahlungen werden über POST /api/v6/payments erstellt und zunächst im System gespeichert.

   • Vor der Übertragung können die Zahlungen über die API oder das Webportal noch bearbeitet werden.

2. Manuelle Übertragung zur Bank:

   • Über den neuen API-Endpunkt POST /api/v6/payments/submit können gezielt ausgewählte Zahlungen anhand ihrer RID an die Bank übermittelt werden.

   • konfipay erstellt automatisch die erforderlichen SEPA-Pain-Dateien und überträgt diese.

Diese Änderung ermöglicht mehr Flexibilität und verhindert, dass Zahlungen direkt nach dem Einreichen übertragen werden, bevor sie final geprüft oder bearbeitet wurden.

Falls die Erstellung der Zahlungsdatei im Rahmen der Übertragung nicht erfolgreich ist, wird der Prozess abgebrochen und die Zahlungen verbleiben als Pending in den Zahlungsaufträgen. Gelingt die Erstellung der Zahlungsdatei, werden die Zahlungen dieser Datei zugewiesen und können weder bearbeitet noch gelöscht werden – unabhängig davon, ob die Dateiübertragung erfolgreich ist oder nicht. In diesem Fall ändert sich der Status der Zahlungen von Open zu Pending.

Weitere Informationen zu dieser neuen API-Schnittstelle können der API-Dokumentation entnommen werden.

Beispiel Request:

{
  "batchBooking": true,
  "paymentRids": [
    "5d12c087-be1e-456c-a33f-4f8750fa7814",
    "fa727310-3072-4abc-a982-b511b8b81108"
  ],
  "failOnSubmittedPayments": false
}

Abruf von Zahlungsaufträgen

In dieser API-Version wird die Funktionalität eingeführt, Zahlungsaufträge anhand der optionalen Batch-RID (batch-rid) oder ihrem Status (status) abzurufen. Bei der Abfrage der Zahlungsaufträge wird eine Liste an Aufträgen zurückgegeben, die entweder in einem Batch importiert wurden oder einem gewissen Status (Processed/Pending) zugeordnet sind. Wenn kein Filterparameter angegeben ist, wird die vollständige Liste aller Zahlungsaufträge zurückgegeben. Ein Zahlungsauftrag wird als offen betrachtet, wenn weder eine Zahlungsdatei erstellt noch eine Dateiübertragung an die Bank durchgeführt wurde.

Abruf von Zahlungen

Die neue API-Schnittstelle GET /api/v6/payments/{rid} ermöglicht den Abruf von Zahlungsinformationen. Dieser Endpunkt liefert sowohl Daten zum Batch (batch) als auch detaillierte Informationen zur Zahlung (transaction). Zusätzlich können die Kontodaten des Auftraggebers (initPartyBankAccount) und des Empfängers (otherPartyBankAccount) eingesehen werden. Falls eine Zahlungsdatei vorhanden ist, steht auch diese zur Verfügung (paymentFile).

Eine umfassende Beschreibung der enthaltenen Elemente und Felder ist in der zugehörigen API-Dokumentation verfügbar.

Beispiel:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2025-02-18T08:53:48+01:00",
  "batch": {
    "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
    "numberOfElements": 5
  },
  "transaction": {
    "type": "TRF",
    "amount": 10055,
    "currency": "EUR",
    "country": "DE",
    "executionDate": "2025-02-17",
    "endToEndId": "NOTPROVIDED",
    "purposeCode": "SALA",
    "chargeBearer": "SLEV",
    "instrId": "ABC123456789",
    "rmtInfoUStrd": "Reference from the payer to the bank"
  },
  "initPartyBankAccount": {
    "rId": "fa727310-3072-4abc-a982-b511b8b81108",
    "iban": "DE12345678901234567890",
    "description": "Alice Mayer"
  },
  "otherPartyBankAccount": {
    "rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
    "iban": "DE09876543210987654321",
    "description": "Bob Mayer"
  },
  "paymentFile": {
    "rId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
    "timestamp": "2025-02-18T08:53:48+01:00",
    "format": "pain.001",
    "executionDate": "2025-02-18",
    "paymentType": "CBTRF",
    "status": {
      "statusValue": "FIN_CONFIRMED",
      "uploadTimestamp": "2025-02-18T10:06:01+01:00",
      "orderID": "A1BC",
      "reasonCode": "TS01",
      "reason": "The transfer of the file was successful",
      "additionalInformation": "Additional information 1"
    }
  }
}

Löschen von Zahlungen

Der neue API-Endpunkt DELETE /api/v6/payments/{rid} ermöglicht es Zahlungen zu löschen. Nur nicht verarbeitete Zahlungen können gelöscht werden. Sobald eine Zahlung verarbeitet und in eine SEPA konvertiert wurde, ist eine Löschung nicht mehr möglich.

Genaue Spezifikation der Formate

In den vorherigen API-Versionen wurden bei den Zahlungsdateien nur das allgemeine Format wie beispielsweise „pain“ oder „container“ zurückgegeben. Ab API-Version 6 wird das spezifische Format, wie z. B. „pain.001“ oder „pain.008“, in der Antwort übermittelt.

Antwort bis API-Version 5:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2024-10-18T13:30:48+02:00",
  "type": "pain",
  "paymentStatusItem": {
    "status": "FIN_CONFIRMED",
    "uploadTimestamp": "2024-10-18T14:43:01+02:00",
    "orderID": "A1BC",
    "reasonCode": "TS01",
    "reason": "The transfer of the file was successful",
    "additionalInformation": "Additional information 1"
  }
}

Antwort ab API-Version 6:

{
  "paymentInfo": {
    "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
    "timestamp": "2025-01-09T14:36:50+01:00",
    "format": "pain.001",
    "executionDate": "2025-01-09",
    "paymentType": "TRF",
    "status": {
      "statusValue": "FIN_CONFIRMED",
      "uploadTimestamp": "2025-01-09T15:49:03+01:00",
      "orderID": "A1BC",
      "reasonCode": "TS01",
      "reason": "The transfer of the file was successful",
      "additionalInformation": "Additional information 1"
    }
  }
}

Ablehnung von Dateien mit mehreren SEPA-Sammelaufträgen

Ab API-Version 6 ist die Einreichung von Dateien, welche mehr als einen SEPA-Sammelauftrag (Element: <PmtInf>) enthalten nicht länger zulässig. Diese Anpassung dient dazu, eine konsistente und verlässliche Verarbeitung über alle Prüf-, Anzeige- und Verarbeitungsschritte hinweg sicherzustellen.

PayPal

Unterstützung von Sandbox Konten

In dieser API-Version ist die Nutzung von PayPal-Sandbox-Konten möglich. Über das Feld isSandbox kann bei der Erstellung oder Aktualisierung festgelegt werden, ob das PayPal-Konto in der Sandbox-Umgebung betrieben wird. Standardmäßig ist dieser Wert auf false gesetzt. Wenn der Wert auf true gesetzt ist, kann das Konto flexibel für Test- und Entwicklungszwecke genutzt werden.

Beispiel Anfrage:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "description": "Description1",
  "clientId": "Adsf-sdffgghghjhklkj_xOFZDwIjP-qeryuioplkjhgfdcvbnu2SfHM0_mnbvcx",
  "clientSecret": "akcvkfriooi$^&dfd=dsfdsf=-dsfsdljllerejjlgl;r",
  "isActive": true,
  "startFetchDate": "2025-01-18T08:53:51+01:00",
  "isSandbox": false
}

Beispiel Antwort:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "description": "Description1",
  "clientId": "Ysnf-tQW8usdfsdfsdf_xOFZDwIjP-qsfsdfdfreerkuyiu2SfHM0_ghjghjghD",
  "isActive": true,
  "timestamp": "2025-02-18T08:53:51+01:00",
  "startFetchDate": "2025-01-18T08:53:51+01:00",
  "payPalBalances": [
    ...
  ],
  "isSandbox": false
}

Entfallene API-Endpunkte

Bis API-Version 5 wurden alle Zahlungsformate über einen eigenständigen API-Endpunkt abgebildet. Damit der Status einer Zahlung über alle Formate hinweg zentral abgerufen werden konnte, wurde bis API-Version 5 die PaymentStatus API bereitgestellt ( GET /api/{version}/PaymentStatus/{rid}). Mit der Zusammenfassung der API Endpunkte für Zahlungen zu einem gemeinsamen Endpunkt (/api/{version}/payment-files) entfällt die Notwendigkeit der Bereitstellung eines eigenständigen API Endpunktes. Der Status einer Zahlung kann ab API Version 6 über den Endpunkt GET /api/v6/payment-files/{rid}abgerufen werden.