NAV Navbar
cURL

BANKSapi Banks/Connect

Schnittstellenstrategie

Die APIs sind nach dem REST-Paradigma mit Blick auf den Architekturstil HATEOAS angelegt. Durch die damit auf den Server verlagerte Adressierungslogik ist es möglich, die API organisch zu erweitern, ohne dass sich für die Aufrufer Brüche ergeben.

Sollte sich eine Änderung doch nicht abwärtskompatibel umsetzen lassen, so werden vorherige Versionen der Schnittstelle nach Bedarf über einen fachlich sinnvollen Übergangszeitraum hinweg parallel bereitgestellt.

Der Aufruf der Schnittstelle erfolgt immer per HTTPS verschlüsselt. Als Datenaustauschformat bieten wir aktuell JSON an, aber bei Bedarf ist eine Erweiterung um weitere Formate für die Zukunft nicht ausgeschlossen.

Gliederung von Schnittstelle und Dokumentation

Die Schnittstelle gliedert sich in die drei Sub-APIs Banks/Connect Customer, Banks/Connect Providers API sowie BANKSapi Auth API, die in den folgenden Abschnitten kurz beschrieben werden. Für weitergehende Informationen sei jeweils auf die umfassende Sub-API-Dokumentation verwiesen.

Zentrale Konzepte der BANKSapi Banks/Connect-Schnittstelle wie bspw. die Authentifizierung werden innerhalb dieses Dokuments im gleichnamigen Kapitel beschrieben. Weiterhin werden für die jeweilige Sub-API zutreffende Konzepte in der jeweiligen API-Dokumentation beschrieben.

Bevor es losgeht

{
  "left":"navigation",
  "center":"prosa",
  "right":"code"
}

Neben den erläuternden Texten sind, wo es uns als hilfreich erschien, Beispiele der Daten im JSON-Format angebracht.

$ curl https://banksapi.io/hello/ \
  -X GET \
  -H 'Expect: ' \
  -H 'Accept: application/json'

Um die Aufrufe der Schnittstelle beispielhaft darzustellen, verwenden wir das Kommandozeilen-Tool curl(1) in der Version 7.43.0. Sofern nicht anders angegeben, können diese Beispiele direkt in der Kommandozeile ausgeführt werden und liefern Daten entsprechend dem Erfolgsfall zurück.

Feedback

Diese Dokumentation soll in erster Linie hilfreich sein. Wir freuen uns daher über Ihre Kritik und Anregungen, die Sie bitte an support@banksapi.de richten.

Banks/Connect Customer API

{
   "bankzugaenge":{
      "Demo-Bank":{
         "status":"VOLLSTAENDIG",
         "aktualisierungszeitpunkt":"2016-10-27 11:20:52",
         "timeout":"2016-10-27 11:40:52",
         "tanMedien":[
            {
               "gueltigVon":"2016-10-27 11:20:53",
               "gueltigBis":"2016-10-27 11:20:53",
               "name":"Mobil",
               "medienklasse":"MOBIL"
            }
         ],
         "sicherheitsverfahren":[
            {
               "kodierung":1,
               "name":"Demo-TAN",
               "hinweis":"Die Demo-TAN ist jede gerade Zahl"
            }
         ],
         "aktivesSicherheitsverfahren":{
            "kodierung":1,
            "name":"Demo-TAN",
            "hinweis":"Die Demo-TAN ist jede gerade Zahl"
         },
         "bankprodukte":[
            {
               "id":"DE00123456789012345678",
               "bezeichnung":"Girokonto",
               "kategorie":"GIROKONTO",
               "aktualisierungszeitpunkt":"2016-10-27 11:20:53",
               "saldo":2145.78,
               "saldoDatum":"2016-01-18 00:00:00",
               "waehrung":"EUR",
               "kontonummer":"9012345678",
               "iban":"DE00123456789012345678",
               "bic":"XXX12345678",
               "blz":"12345678",
               "inhaber":"Fritz Testmüller",
               "relations":[
                  {
                     "rel":"start_ueberweisung",
                     "href":"https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345678"
                  },
                  {
                     "rel":"self",
                     "href":"https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345678"
                  },
                  {
                     "rel":"get_kontoumsaetze",
                     "href":"https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345678/kontoumsaetze"
                  }
               ],
               "ueberziehungslimit":3000.0,
               "verfuegungsrahmen":2045.78,
               "verfuegterBetrag":100.0
            },
            {
               "id":"12345678XXXX1234",
               "bezeichnung":"Visa-Karte",
               "kategorie":"KREDITKARTE",
               "aktualisierungszeitpunkt":"2016-10-27 11:20:53",
               "saldo":-89.95,
               "saldoDatum":"2015-05-11 00:00:00",
               "waehrung":"EUR",
               "kontonummer":"12345678XXXX1234",
               "kreditinstitut":"Demo Bank AG",
               "inhaber":"Fritz Testmueller",
               "relations":[
                  {
                     "rel":"self",
                     "href":"https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/12345678XXXX1234"
                  },
                  {
                     "rel":"get_kontoumsaetze",
                     "href":"https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/12345678XXXX1234/kontoumsaetze"
                  }
               ],
               "ueberziehungslimit":1000.0
            },
            {
               "id":"9012345680",
               "bezeichnung":"Investmentdepot",
               "kategorie":"DEPOT",
               "aktualisierungszeitpunkt":"2016-10-27 11:20:53",
               "saldo":23411.69,
               "saldoDatum":"2015-05-11 00:00:00",
               "waehrung":"EUR",
               "kontonummer":"9012345680",
               "bic":"XXX12345678",
               "blz":"12345678",
               "inhaber":"Fritz Testmüller",
               "relations":[
                  {
                     "rel":"self",
                     "href":"https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/9012345680"
                  },
                  {
                     "rel":"get_depotpositionen",
                     "href":"https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/9012345680/depotpositionen"
                  }
               ],
               "saldoDatenquelle":"SONSTIGE"
            }
         ],
         "relations":[
            {
               "rel":"self",
               "href":"https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank"
            },
            {
               "rel":"delete",
               "href":"https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank"
            }
         ]
      }
   },
   "relations":[
      {
         "rel":"self",
         "href":"https://banksapi.io/customer/v2"
      },
      {
         "rel":"get_bankzugaenge",
         "href":"https://banksapi.io/customer/v2/bankzugaenge"
      },
      {
         "rel":"add_bankzugaenge",
         "href":"https://banksapi.io/customer/v2/bankzugaenge"
      },
      {
         "rel":"delete_bankzugaenge",
         "href":"https://banksapi.io/customer/v2/bankzugaenge"
      }
   ]
}

Das Herzstück von BANKSapi Banks/Connect bildet die Banks/Connect Customer API, über die Ihre Endkunden innerhalb Ihres Produktes auf ihr finanzielles Leben zugreifen und Transaktionen tätigen können.

Umfassende Informationen zur API finden Sie in der Schnittstellendokumentation. Damit Sie ohne weitere Umwege einfach loslegen können, haben wir eine Schnellstartanleitung verfasst.

Banks/Connect Providers API

{
   "id":"00000000-0000-0000-0000-000000000000",
   "name":"Demo-Bank",
   "group":"demo",
   "blz":"12345678",
   "bic":"DEMO1234",
   "relations":[
      {
         "rel":"self",
         "href":"https://banksapi.io/providers/v2/00000000-0000-0000-0000-000000000000"
      }
   ],
   "capabilities":[
      "KONTEN",
      "KARTEN",
      "DEPOTS"
   ],
   "authenticationInfo":{
      "loginHint":"Die Demo-Bank bietet drei Zugänge demo1/demo1, demo2/demo2 und demo3/demo3",
      "fields":[
         {
            "fieldkey":"userid",
            "label":"Demo-User",
            "secret":false,
            "hint":"Mögliche Werte sind demo1, demo2 oder demo3",
            "format":"|5"
         },
         {
            "fieldkey":"pin",
            "label":"Demo-Passwort",
            "secret":true,
            "hint":"Mögliche Werte sind demo1, demo2 oder demo3",
            "format":"|5"
         }
      ]
   }
}

Bank ist nicht gleich Bank. Daher stellen wir Ihnen über die Banks/Connect Providers API eine umfassende Konfigurationsdatenbank mit Daten zu den von BANKSapi Banks/Connect unterstützten Banken und Service-Providern zur Verfügung.

Neben allgemeinen Stammdaten wie dem Name, Bankengruppe, BLZ und BIC erhalten Sie auch detaillierte maschinenlesbare Informationen zu den Login-Modalitäten, sodass Sie das Nutzungserlebnis Ihrer Anwendung bei der Anlage von Bankzugängen optimieren können.

Umfassende Informationen zur Banks/Connect Providers API finden Sie in der Schnittstellendokumentation.

BANKSapi Auth API

Der Schutz persönlicher Daten genießt bei BANKSapi die höchste Priorität. Neben dem Betrieb im Hochsicherheitsrechenzentrum der DATEV eG sind Verschlüsselung und durchgängig im gesamten Prozess genutzte Sicherheits-Tokens zentrale Bausteine unseres Sicherheitskonzepts.

Die BANKSapi Auth API stellt Funktionen zur Verwaltung von Benutzern bereit. Über das OAuth2-Protokoll erzeugen Sie Tokens, mit denen nur die Funktionen freigeschalten werden, die für den jeweiligen Anwendungsfall notwendig sind.

Umfassende Informationen zur BANKSapi Auth API finden Sie in der Schnittstellendokumentation.

Zentrale Konzepte

Authentifizierung

Authentifizierung ein sehr wichtiges Thema, am Ende aber doch nur Mittel zum Zweck. Daher haben wir in unser Schnellstartanleitung so weit es ging darauf verzichtet Sie damit zu behelligen. So können Sie sich auf den Kern Ihrer Anforderung konzentrieren und die Details auf etwas später verschieben.

Bei BANKSapi Banks/Connect gibt es grundsätzlich drei Arten der Authentifizierung:

Weiterhin gibt es für die BANKSapi Auth API einen eigenen Admin-Client, mit dem Sie Benutzer anlegen und verwalten können.

Welche Form der Authentifizierung wann greift, erfahren Sie an entsprechender Stelle in der Sub-API-Dokumentation. Grundsätzlich gilt, dass jede Anfrage an BANKSapi Banks/Connect im Kontext eines Mandanten erfolgt. Bei einigen wenigen, z.B. bei der Provider-Abfrage reicht dies bereits. Seine ganze Funktionsvielfalt entwickelt BANKSapi Banks/Connect aber erst mit einem User-Token und ein paar Bank-Zugängen.

Bank

Als Bank bezeichnen wir im Zusammenhang mit BANKSapi Banks/Connect die Bankinstitute, bei denen wir die Daten in Ihrem Auftrag abholen. Im Kontext von BANKSapi Banks/Connect werden sie zusammen mit den Service-Providern zu Providern zusammengefasst.

Die für Sie in BANKSapi Banks/Connect freigeschaltenen Banken können Sie über die Banks/Connect Providers API abrufen.

Benutzer

Der eindeutige Benutzer ist auch das zentrale Abrechnungskriterium. Näheres regelt Ihr Kooperationsvertrag.

Ein Benutzer bildet eine Klammer um die zu einer Person von den verschiedenen Banken bzw. Service-Providern abgerufenen Daten.

Bei BANKSapi Banks/Connect gehören die Benutzer Ihnen, dem Mandanten. Über die Banks/Connect Customer API erhalten Sie Zugriff auf die Finanzdaten Ihrer Benutzer.

Mit der Banks/Connect Auth API können Sie Ihre Benutzer verwalten.

Client

Wir verwenden den Begriff Client sowohl für Ihre Anwendung(en) als auch einen "Admin-Client", mit dem Sie Ihre Benutzer verwalten. Ein Client ist aus unserer Sicht also ein Satz Zugangsdaten für BANKSapi Banks/Connect.

Mit einer Client-Kennung können über die Banks/Connect Auth API lient-Tokens per OAuth2 bezogen werden mit denen dann die weiteren Funktionen in der Banks/Connect Customer API oder Banks/Connect Providers API genutzt werden können.

Correlation-ID

GET / HTTP/1.1
x-correlation-id: c129b93a-9b5c-11e6-a112-480fcfb9550f

Die Correlation-ID dient uns dazu, Anfragen über alle Systeme hinweg verfolgen zu können. Die Correlation-ID kann an die BANKSapi APIs als HTTP-Header X-Correlation-ID übergeben werden.

Wird sie nicht übergeben, dann generieren die BANKSapi APIs eine eigene ID.

In jedem Fall wird der Wert als HTTP-Response-Header X-Correlation-ID auch wieder zurück gegeben.

CORS

Mehr Informationen zu CORS auf Wikipedia.

BANKSapi Banks/Connect unterstützt "Cross Origin Resource Sharing" (CORS). Damit ist es möglich, unsere APIs direkt vom Browser aus aufzurufen, z.B. in einer Single-Page-App.

Fehler

Wikipedia hat eine ausgezeichnete Liste der HTTP-Status-Codes.

Fehler lassen sich leider nicht immer vermeiden aber behandeln. Gerade bei externen Abhängigkeiten wie den Banken und Service-Providern, die über BANKSapi/Banks Connect angebunden sind, haben wir keinen Einfluss auf deren (im Allgemeinen sehr hohe) Verfügbarkeit.

Daher liefern wir Ihnen in der Banks/Connect Customer API Message-Objekte neben einem Code, eine Fehlerbeschreibung für Ihren Endkunden sowie eine für Sie aufschlussreiche Detailmeldung. Dabei werden auch fehlerbehaftete Abfragen mit einem HTTP-Status-Code aus dem Bereich 2XX beantwortet.

Wenn es doch mal bei uns klemmt, arbeiten wir mit der ganzen Bandbreite von HTTP-Status-Codes.

Die Details zu den möglichen Message-Objekten und den HTTP-Status-Codes finden sie jeweils im Kapitel "Fehler und Meldungen" in den Sub-API-Dokumentationen.

HATEOAS

Mehr Informationen zu HATEOAS auf Wikipedia.

HATEOAS steht als Abkürzung für "Hypermedia as the Engine of Application State". Hierbei navigiert der Client einer REST-Schnittstelle ausschließlich über URLs, welche vom Server bereitgestellt werden. Demnach gibt es nur wenige feststehende URLs, die dem Aufrufenden bekannt sein müssen. Jede weitere Interaktion erfolgt über solche URLs, die innerhalb der Rückgabe der Schnittstellenaufrufe enthalten und die nur begrenzte Gültigkeit besitzen.

Diese URLs werden entweder im HTTP-Response-Header "Location" oder häufiger in Form von Relations im zurückgelieferten Dokument an den Aufrufer mitgeteilt.

JSON

{
  "aString":"Lorem ipsum dolor annat",
  "anInteger":42,
  "aFloat":42.1337,
  "aBool":true,
  "aDate":"1969-07-20",
  "aTimestamp":"2016-09-03 04:27:00",
  "anArrayOfInteger":[1,2,3],
  "anArrayOfStrings":["one", "two", "three"],
  "anObject":{
     "cat":"kitten",
     "dog":"puppy"
  }
}

Die BANKSapi Banks/Connect-Schnittstellen verwenden die JSON (JavaScript Object Notation) zum Datenaustausch. Attribute ohne Werte werden bei uns nicht als "null" geliefert, sondern "fehlen" im Dokument. Datumswerte liefern und erwarten wir nach ISO 8601 formatiert als String.

Bei den ausgetauschten JSON-Dokumenten ist weiter zur beachten, dass jeder Konsument ihm unbekannte Attribute ignorieren muss. Dies gilt insbesondere auch für Aufzählungstypen, deren Erweiterung als abwärtskompatibel angesehen wird. Ungekannte Werte in Aufzählungstypen müssen vom Client somit ebenfalls ignoriert oder auf einen allgemeineren Wert geschlüsselt werden.

Bei der Anlieferung von JSON muss immer der Content-Type-Header "Content-Type: application/json" mitgeliefert werden. Bei "null"-Werten ist es egal, ob die Felder als "null" oder gar nicht geschickt werden, sofern es sich nicht um Pflichtfelder handelt.

Mandant

Es gibt auch einen Demo-Mandanten, der z.B. in unserer Schnellstartanleitung zum Einsatz kommt.

Das sind Sie bzw. die Firma, die mit uns einen Kooperationsvertrag geschlossen hat. Zum Mandanten gehören Clients und Benutzer.

Als Mandant haben Sie Zugriff auf unseren erstklassigen Support und profitieren von der permanenten Weiterentwicklung von BANKSapi Banks/Connect. Und natürlich sehen Sie auch mehr Daten als nur die unserer Demo-Bank.

Bei Interesse nehmen Sie doch Kontakt mit uns auf.

OAuth2

Alle Aufrufe der BANKSapi-Schnittstellen müssen mit einem gültigen OAuth2-Token erfolgen. Für einige Operationen reicht hierbei ein Client-Token (ohne konkreten Benutzer). Sofern am entsprechenden Anwendungsfall diesbezüglich nichts explizit dokumentiert ist, wird der Aufruf mit einem eindeutigen Benutzer vorausgesetzt. Details zur Benutzer- und Client-Verwaltung sind in der BANKSapi Auth API beschrieben.

Beim Aufruf muss der Token entsprechend dem OAuth2-Standard im Header "Authorization: Bearer ..." übertragen werden. Fehlt dieser Header oder ist der Token ungültig, so antwortet die Schnittstelle mit dem HTTP-Status-Code 401 (Unauthorized). Sofern der Token nicht die nötigen Berechtigungen enthält, wird der HTTP-Status-Code 403 (Forbidden) gemeldet.

Provider

Als Provider bezeichnen wir ganz abstrakt die angebundenen Banken und Service-Provider. Die Anbindung erfolgt über verschiedenste Technologien und am Ende werden die erfassten Daten für Sie in ein einheitliches Format gebracht.

Relation

{
    "rel":"say_hello",
    "href":"https://banksapi.io/hello/"
}

Eine Relation entspricht einem Anwendungs- bzw. Geschäftsvorfall, der vom jeweils umschließenden Daten-Objekt unterstützt wird. Für jeden Anwendungs- bzw. Geschäftsvorfall existiert eine eigenständige Dokumentation, die jeweils sowohl den Aufruf als auch die Rückgabe bzw. die möglichen alternativen Antwortszenarien im Detail beschreibt.

Jede Relation besteht aus einem Schlüsselwort (z.B. "get_kontoumsaetze" und einer URL. Ein Client der an den Kontoumsätzen interessiert ist, ruft die angegebene URL mit dem in der Dokumentation angegebenen HTTP-Verb auf.

REST

Leseempfehlung: Roy Fielding: REST APIs must be hypertext-driven

Unsere APIs sind als REST-Muster (Representational State Transfer) implementiert. Folglich sind sie über das HTTP-Protokoll nutzbar und verwenden mehr HTTP-Verben als nur GET und POST.

Weiterhin bemühen wir uns, den Anforderungen des REST-Erfinders Roy Fielding an eine REST-API durch das Besinnen auf den HATEOAS-Architekturstil gerecht zu werden.

Service-Provider

Service-Provider sind angebundene Finanzinstitute, die keine Bank sind. Im Kontext von BANKSapi Banks/Connect werden sie auch allgemeiner als Provider zusammengefasst.

Informationen über Service-Provider können über die Banks/Connect Providers API abgerufen werden.

Sprache

Die deutsche Bankenlandschaft ist sehr deutschsprachig, und daher landet man im Detail recht schnell bei der Suche nach einer angemessenen Übersetzung in einer Sackgasse (oder bei einer halbseidenen Übersetzung). Als Techniker liegt es uns allerdings auch nahe, "in englisch zu programmieren".

Um aus diesem Dilemma herauszukommen, haben wir uns entschieden, Fachbegriffe aus dem Bankenumfeld in Deutsch zu belassen und alle anderen Begriffe aus dem Englischen zu importieren. Damit es kein zu krasses Denglish wird, haben wir uns im Zweifel auch für Deutsch entschieden.

Ansonsten ist BANKSapi Banks/Connect vor allem in Java und einigen anderen JVM-Sprachen programmiert.

Verschlüsselung

{
  "plaintext":"BANKSapi",
  "ciphertext":"ONAXFncv"
}

Damit BANKSapi Banks/Connect auf die Daten der Banken zugreifen kann, müssen die Zugangsdaten vorliegen. Da es sich hierbei um extrem schutzwürdige Angaben handelt, werden die Zugangsdaten mittels starker asymmetrischer Verschlüsselung geschützt. Sie erhalten zu Beginn der Kooperation einen RSA-Public-Key. Das geheime Gegenstück liegt bei uns. Somit können die Zugangsdaten bei Ihnen ver- aber nicht mehr entschlüsselt werden.

Das Verfahren wird im Detail in der Dokumentation der Banks/Connect Customer API beschrieben.

Die Qualität unserer TLS-Konfiguration prüfen wir mit dem Tool Qualys SSL Labs.

Ansonsten ist natürlich der Transportweg per TLS (HTTPS) verschlüsselt.

Versionierung

Semantische Versionierung hat sogar ein eigenes semantisch versioniertes Manifest.

Die Schnittstellen werden semantisch versioniert (X.Y, z.B. 2.0). Erhöht sich Y, so wird ein richtig implementierter Client ohne Einschränkungen weiter funktionieren, nutzt aber natürlich die neuen Funktionen nicht. Bei einer Änderung von X muss der Client angepasst werden, da die Änderung nicht abwärtskompatibel war. Frühere Hauptversionen (X) werden nach Einführung der inkompatiblen Folgeversionen noch eine Zeit lang unterstützt, sofern dies fachlich sinnvoll ist.

Häufig gestellte Fragen

Wie erhalte ich die Bankprodukte für meinen Kunden?

Die Bankprodukte erhalten Sie über die Banks/Connect Customer API. Nachdem Sie Ihren Benutzer authentifziert haben, müssen Sie einen Bankzugang hinzufügen. Dabei benötigen Sie die Online-Banking-Zugangsdaten (Credentials) Ihres Kunden, die Sie uns asymmetrisch verschlüsselt übermitteln.

Hat der Datenabruf geklappt, stehen die Daten über die API zur Abholung bereit.

Was sind Credentials?

Unter Credentials werden hier die Zugangsdaten des Kunden zu dessen Online-Banking verstanden. Die Zugangsdaten bestehen meistens aus einer Benutzerkennung/Anmeldenamen sowie einem Passwort/PIN. Die konkrete Ausprägung ist pro Provider unterschiedlich und kann über die Banks/Connect Providers API abgefragt werden.

Was ist eine TAN?

Eine TAN (Transaktionsnummer) ist ein Zufallscode, der nur einmalig verwendet werden kann. In der Banks/Connect Customer API wird die TAN für den Überweisungsprozess benötigt.

Nach Übermittlung der Überweisungsdaten an den Provider wird dann die TAN oder die Instruktion zur TAN-Generierung (z.B. Chipkartenleser) vom Provider direkt an den Kunden gesendet. Die TAN muss dann wiederum vom Kunden abgefragt und an Banks/Connect Customer API zur Bestätigung des Auftrages weitergeleitet werden.

Gibt es einen Testzugang bzw. einen Demo-Zugang?

Ja, es gibt eine Demo-Bank. Es handelt sich dabei um eine fiktive Bank mit fiktiven aber nicht unrealistischen Bankprodukten. Über diesen Testzugang wird veranschaulicht, welche Möglichkeiten Ihnen unsere API bietet. Eine Anbindung an die reale Welt gibt es dabei nicht. Nähere Informationen gibt unsere Schnellstartanleitung

Was ist BANKSapi Banks/Connect?

BANKSapi Banks/Connect ist eine Schnittstelle, über die für eine Vielzahl von Providern die

für Ihre Kunden bezogen werden können.

Wo und wie werden die Daten gespeichert?

Je nach gewähltem Leistungsspektrum speichern wir die Daten für Sie dauerhaft oder nur für die Dauer von wenigen Minuten, in jedem Fall aber im Hochsicherheitsrechenzentrum der DATEV eG oder Ihrem eigenen.

Was kostet mich BANKSapi Banks/Connect?

Informationen zum unserem Preismodell finden Sie auf der Website.

Wie bekomme ich einen API-Zugang?

Kontaktieren Sie uns!