NAV Navbar
cURL

Banks/Connect Customer API

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

Kernelement der API bildet der Customer, über das Sie über Relations detailliert in die über Ihren Kunden ermittelbaren Daten eintauchen können.

Dieses Dokument enthält die API-Referenz. Doch bevor Sie sich mit den Details befassen müssen, dürfen Sie die API mit unserer Schnellstartanleitung direkt und ohne weitere Hürden ausprobieren.

Schnellstart

Mit dieser Schnellstartanleitung möchten wir Ihnen die Möglichkeit geben, die Banks/Connect Customer API auszuprobieren, ohne dass Sie sich mit Details wie der Authentifizierung oder Verschlüsselung auseinandersetzen müssen. Sie benötigen für diese ersten Schritte auch keinen API-Zugang und auch kein eigenes Konto.

Demo-Zugang

Unsere Demo-Zugang wird über den fiktiven Demo-Provider mit der ID 00000000-0000-0000-0000-000000000000 abgerufen. Der Demo-Provider ist vollständig in BANKSapi Banks/Connect integriert. Alle Schritte, die Sie hier durchführen können, gehen auf das lebendige produktive System und unterscheiden sich von anderen Providern nur dadurch, dass die Anfragen nicht weiter in die Welt hinausgehen. Somit bekommen Sie ein realistisches Bild davon, wie sich BANKSapi Banks/Connect anfühlt.

OAuth2-Token anfordern

Wie es geht, steht natürlich in der BANKSapi Auth API-Dokumenation.

Normalerweise müssten Sie jetzt einen OAuth2-Token anfordern. Aber den haben wir schon für Sie vorbereitet. Der Token ist mit der Information verknüpft, welche Funktionen Sie aufrufen dürfen. In unserem Fall sind das alle lesenden Funktionen auf den Customer. Der Token lautet 0defaced-1337-d00d-c0de-face8badcafe.

Bankzugang hinzufügen

Wie es geht, steht natürlich im entsprechenden Kapitel.

Auch das haben wir Ihnen erspart. Beim Zugriff mit dem Demo-OAuth2-Token wird für Sie automagisch ein Zugang zum Demo-Provider angelegt.

Kundendaten abfragen

$ curl https://banksapi.io/customer/v2 \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Jetzt wird es ernst. Nebenan sehen Sie den Aufruf in Curl. Die URL https://banksapi.io/customer/v2 ist der Einstiegspunkt in die Banks/Connect Customer API. Das HTTP-Verb GET sagt uns, dass Sie etwas bekommen wollen. Der HTTP-Header Expect: fordert dieses etwas in einem Rutsch an (sonst haben Sie mit curl nicht so viel Freude).

Zentral sind aber die beiden anderen HTTP-Header, authorization und accept. Ersterer enthält, wie Sie unschwer erkennen können, unseren Demo-OAuth2-Token. Der andere Token sagt unserem Server, dass Sie JSON erwarten. Beide Header sind verbindlich, sonst geht es nicht.

{
   "bankzugaenge":{
      "Demo-Bank":{
         "status":"VOLLSTAENDIG",
         "aktualisierungszeitpunkt":"2016-10-28 14:33:02",
         "timeout":"2016-10-28 14:53:02",
         "tanMedien":[
            {
               "gueltigVon":"2016-10-28 14:33:03",
               "gueltigBis":"2016-10-28 14:33:03",
               "name":"Mobil",
               "medienklasse":"MOBIL"
            }
         ],
         "sicherheitsverfahren":[
            {
               "kodierung":1,
               "name":"Mock-TAN",
               "hinweis":"Mock-TAN"
            }
         ],
         "aktivesSicherheitsverfahren":{
            "kodierung":1,
            "name":"Mock-TAN",
            "hinweis":"Mock-TAN"
         },
         "bankprodukte":[
            {
               "id":"DE00123456789012345679",
               "bezeichnung":"Tagesgeldkonto",
               "kategorie":"TAGESGELDKONTO",
               "aktualisierungszeitpunkt":"2016-10-28 14:33:03",
               "saldo":7365.56,
               "saldoDatum":"2016-01-18 00:00:00",
               "waehrung":"EUR",
               "kontonummer":"9012345679",
               "iban":"DE00123456789012345679",
               "bic":"XXX12345678",
               "blz":"12345678",
               "inhaber":"Fritz Testmüller",
               "relations":[
                  {
                     "rel":"start_ueberweisung",
                     "href":"https://banksapi.io:443/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345679"
                  },
                  {
                     "rel":"self",
                     "href":"https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345679"
                  },
                  {
                     "rel":"get_kontoumsaetze",
                     "href":"https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345679/kontoumsaetze"
                  }
               ],
               "verfuegungsrahmen":7365.56,
               "verfuegterBetrag":0.0
            }
         ],
         "relations":[
            {
               "rel":"self",
               "href":"https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank"
            }
         ]
      }
   },
   "relations":[
      {
         "rel":"self",
         "href":"https://banksapi.io:443/customer/v2"
      },
      {
         "rel":"get_bankzugaenge",
         "href":"https://banksapi.io:443/customer/v2/bankzugaenge"
      }
   ]
}

Wenn Sie (und wir) alles richtig gemacht haben, erhalten Sie das Customer-Objekt zurück, das wir auch auszugsweise rechts wiedergegeben haben.

Bankprodukt abfragen

$ curl https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345679 \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

In der API gibt es die Regel, dass wir über eine URL referenzierbare Objekte eine Relation self enthalten. In diesem Beispiel rufen wir ein einzelnes Bankprodukt ab. Probieren Sie mal!

{
   "id":"DE00123456789012345679",
   "bezeichnung":"Tagesgeldkonto",
   "kategorie":"TAGESGELDKONTO",
   "aktualisierungszeitpunkt":"2016-10-28 14:33:03",
   "saldo":7365.56,
   "saldoDatum":"2016-01-18 00:00:00",
   "waehrung":"EUR",
   "kontonummer":"9012345679",
   "iban":"DE00123456789012345679",
   "bic":"XXX12345678",
   "blz":"12345678",
   "inhaber":"Fritz Testmüller",
   "relations":[
      {
         "rel":"start_ueberweisung",
         "href":"https://banksapi.io:443/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345679"
      },
      {
         "rel":"self",
         "href":"https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345679"
      },
      {
         "rel":"get_kontoumsaetze",
         "href":"https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345679/kontoumsaetze"
      }
   ],
   "verfuegungsrahmen":7365.56,
   "verfuegterBetrag":0.0
}

Wenig überraschend erhalten Sie nur das Bankprodukt, welches Sie schon von oben kennen.

Umsätze abfragen

$ curl https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345679/kontoumsaetze \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Es wäre langeweilig, wenn alle Daten beim ersten Aufruf kämen. Daher gibt es noch einige Relations, die mehr machen als nur Datenausschnitte zu besorgen.

Mit der Relation get_kontoumsaetze z.B. erhalten Sie eine Liste von ... Kontoumsätzen.

[
   {
      "betrag":3.54,
      "verwendungszweck":"Abschluss Zinsen Kto 565915605EUR von 30.09.2014 bis 31.12.2014 Habenzinsen 0,550%  Ref. 6FF1500111827884/186|0",
      "buchungsdatum":"2014-12-31 00:00:00",
      "wertstellungsdatum":"2014-12-31 00:00:00",
      "gegenkontoInhaber":""
   },
   {
      "betrag":-1800.0,
      "verwendungszweck":"Uebertrag auf Girokonto End-to-End-Ref.: nicht angegeben Ref. HO214274M4912194/2|0",
      "buchungsdatum":"2014-10-02 00:00:00",
      "wertstellungsdatum":"2015-10-02 00:00:00",
      "gegenkontoInhaber":"Fritz TestMueller"
   }
]

Die Umsätze kommen in einem JSON-Array daher, das wieder auszugsweise zu sehen ist.

Wie geht es weiter

Haben Sie schon einen API-Zugang? Wenn nicht nehmen Sie doch Kontakt mit uns auf.

Nach diesem kurzen Rundgang haben wir Ihnen die zentralen Konzepte unserer API vorgestellt. Natürlich haben wir nur an der Oberfläche der Möglichkeiten gekratzt.

Sie finden in dieser Dokumentation alle Informationen, die Sie zur Anbindung unserer APIs brauchen. Und wenn doch mal was fehlt, schreiben Sie uns doch Ihre Fragen.

Themen & Konzepte

REG/Protect (Redirect-Lösung)

Das BANKSapi „REG/Protect-as-a-Service“, erlaubt es, Nutzer die Authorisierung komplett im FrontEnd der BANKSapi durchführen zu lassen. Die Kontoinformationen werden von BANKSapi gespeichert. Die sensiblen Zahlungsdaten werden vom Endnutzer direkt an die BANKSapi-Systeme übergeben, von BANKSapi verarbeitet und von BANKSapi gespeichert. Ein Auslesen der sensiblen Zahlungsdaten aus BANKSapi ist nicht möglich.

Neben regulierten Mandanten, können Sie so auch als Nicht-regulierter Mandant mit Hilfe des BANKSapi REG/Protect ihr Leistungsspektrum um Use-Cases erweitern, die auf der Nutzung eines Kontoinformationsdienst (KID) sowie Zahlungsauslösedienst (ZAD) basieren, allerdings ohne eigene ZAD-Lizenz sowie KID-Registrierung. Eine Registrierung/Lizensierung ist seitens der BaFin seit 2018 verpflichtend, wenn mittels Online-Banking auf die Zahlungskontodaten zugegriffen sowie Zahlungen ausgelöst werden.

Parallele Anfragen

BANKSapi versucht so gut wie möglich Einschränkungen hinsichtlich paralleler Aufrufe zu vermeiden. Leider lassen aber einige Banken und Service-Provider keine parallelen Aufrufe zu. Daher sollte ein Client darauf achten, dass für einen Satz Zugangsdaten keine mehrfachen Geschäftsvorfälle wie z.B. Überweisungen und/oder Datenaktualisierungen parallel angestoßen werden. Andernfalls werden durch die jeweiligen Banken bereits laufende Abfragen beendet, was zu Problemen in der Weiterverarbeitung führen kann.

Hintergrundaktualisierung

Beim Hinzufügen eines Bankzugangs eine Hintergrundaktualisierung beauftragt werden. Der Bankzugang und seine Umsätze werden dann vier mal (4x) am Tag neu vom Provider abgefragt und aktualisiert.

Notifications (Webhooks)

Bei aktiver Hintergrundaktualisierung für einen Bankzugang kann ein Webhook spezifiziert werden. Für den Fall neuer Transaktionen während einer Aktualisierung kann eine externe URL aufgerufen werden mit einer Referenz auf den Bankzugang.

Notifications werden nicht garantiert: Bei nicht verfügbarem Endpunkt wird der HTTP-Call zwar in eine Queue gespeichert und es wird mehrmals versucht, ihn durchzuführen, bis der Gegenserver auf Ihrer Seite den Aufruf entgegen nehmen kann. Sollte das aber auch nach Ablauf von einigen Minuten nicht der Fall sein, wird die Notification verworfen.

Sie können durch die fortlaufende, ganzzahlige Sequenznummer serial prüfen, ob es seit der letzten Notification Lücken bzw. Ausfälle gab.

Sicherheitsverfahren

Das Sicherheitsverfahren bestimmt, wie der Endkunde seine Transaktion(en) freigibt.

Am häufigsten sind die TAN-Verfahren wie smsTAN, eTAN, chipTAN, photoTAN, pushTAN etc. im Einsatz. Daneben gibt es noch etliche weitere Verfahren wie bspw. das Biometrie-Verfahren (Fingerprint) oder das RSA-/DES-Verfahren sowie Verfahren mit elektronischer Unterschrift (Sicherheitsdatei).

Es ist zu beachten, dass nicht alle Sicherheitsverfahren durch HBCI unterstützt werden.

TAN-Medium

Das TAN-Medium hat die Funktion eines Mittlers. So wird z.B. die TAN selbst (smsTAN) oder die Anweisung zur TAN-Erzeugung/-Ermittlung an den Kunden weiterleitet.

Das TAN-Medium kann aber auch dazu dienen, die Generierung der TAN kundenspezifisch vorzunehmen (z.B. chipTAN-Verfahren durch den Einsatz der EC-Karte).

Hier ein paar Beispiele zu TAN-Verfahren und TAN-Medien:

TAN-Verfahren Medienklasse Name
mobileTAN (mTAN) Handy +49-1111-1111111
smsTAN Handy +49-1111-111111
chipTAN Generator mit EC-Karte Musterbank-Card 1234567890
Sm@rtTAN Generator mit Bankkarte Musterbank-Card 1234567890
e-TAN Generator Generator

API-Referenz

HTTP-Header

GET /customer/v2 HTTP/1.1
x-correlation-id: b8ad93a4-9b88-11e6-895a-480fcfb9550f
authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe 
accept: application/json
content-type: application/json

Die folgenden HTTP-Header werden von der API verarbeitet:

Header Pflicht Beschreibung
X-Correlation-ID Nein Diese ID wird verwendet um später die Anfrage in Logfiles wiederfinden zu können. Wenn dieser Header fehlt wird eine interne ID generiert. Es gibt auch einen gleichnamigen Response-Header mit der Correlation-ID
Authorization Ja Übermittelt den OAuth2-Token
Accept Nein Inhaltstyp für die Antwort. Aktuell wird nur application/json unterstützt
Content-Type Bei Requests mit Body Inhaltstyp für den Request-Body. Aktuell wird nur application/json unterstützt

OAuth2-Scopes

Scope Beschreibung
http://banksapi.io/customer/read Es dürfen die Daten gelesen werden
http://banksapi.io/customer/modify Es dürfen die Daten wie Bankzugänge geändert und gelöscht werden
http://banksapi.io/customer/ueberweisung Es dürfen Überweisungen ausgeführt werden

Customer

Das Customer-Objekt bildet die Daten des eindeutigen Benutzers auf der Schnittstelle ab. Es bildet damit auch den Einstiegspunkt in die tieferen Funktionen der Schnittstelle.

{
  "messages":[],
  "bankzugaenge":{},
  "relations":[]
}
Feld Typ Enthalten Beschreibung
messages Array von Messages Wenn vorhanden Meldungen transportieren sowohl Fehler als auch Hinweise.
bankzugaenge Objekt mit Bankzugaengen zu Zugangs-IDs (vgl. Bankzugänge hinzufügen) Wenn vorhanden Ein Bankzugang repräsentiert einen Onlinebanking-Zugang sowie die darunter enthalten Bankprodukte.
relations Array von Relations Wenn vorhanden Funktionen, die für den Customer zur Verfügung stehen

Mögliche 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"
  }
]
Relation Beschreibung
self Customer abfragen
get_bankzugaenge Bankzugänge abfragen
add_bankzugaenge Bankzugänge hinzufügen
delete_bankzugaenge Bankzugänge löschen

Customer abfragen

$ curl https://banksapi.io/customer/v2 \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Über diese Anfrage erhält man das Customer-Objekt des Benutzers.

Relation und Kontext
self bei Customer
HTTP-Methode
GET
Gültigkeit
Dauerhaft bis EOL API-Version 2.X
OAuth2-Scope
http://banksapi.io/customer/read

Rückgabe

Im Erfolgsfall kommt der Customer zurück.

Message

{
   "level":"ERROR",
   "code":"BA1011",
   "message":"Zugangsdaten nicht korrekt",
   "details":"Bitte überprüfen Sie Ihre Zugangsdaten und versuchen Sie es erneut. Berücksichtigen Sie, dass Ihre Zugangsdaten nach dreimaliger Falscheingabe gesperrt werden."
}

Das Message-Objekt wird an verschiedenen Stellen verwendet, um Nachrichten über den Datenabruf zu übermitteln. Dabei gilt, dass die Message immer so nahe wie möglich am Objekt, die sie betrifft, hängt.

Die Möglichen Ausprägungen für Messages sind im Abschnitt Fehler und Meldungen beschrieben. Die Struktur einer Message ist wie folgt:

Feld Typ Enthalten Beschreibung
level Enum Immer Level der Meldung, INFO oder ERROR
code String Immer Code der Meldung, lt. Fehler und Meldungen
message String Immer Fehlertext zur Anzeige beim Endkunden lt. Fehler und Meldungen
details String Wenn vorhanden Weiterführende Informationen zur Anzeige beim Endkunden, die sich von Meldung zu Meldung ändern können.

Credentials

{
   "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
   "pin":    "Hhnc+aW/eM ... 7F+XRSHasW"
}

Das Credentials-Objekt ist eine Map mit verschlüsselten und Base64-kodierten Zugangsdaten, entsprechend den Authentication-Fields des Providers. Bei der Base64-Kodierung darf kein line wrapping zum Einsatz kommen.

Das zum Einsatz kommende Verschlüsselungsverfahren ist unter Verschlüsselung beschrieben.

Bankzugang

Im Bankzugang-Objekt werden die Daten zu einem Bankzugang (i.d.R. Online-Banking-Zugang des eindeutigen Benutzers) geliefert.

{
   "status":"VOLLSTAENDIG",
   "tanMedien":[
      {
         "gueltigVon":"2016-06-03 17:17:41",
         "gueltigBis":"2016-06-03 17:17:41",
         "name":"Mobil",
         "medienklasse":"MOBIL"
      }
   ],
   "sicherheitsverfahren":[
      {
         "kodierung":2,
         "name":"mTAN",
         "hinweis":"mTAN"
      },
      {
         "kodierung":1,
         "name":"Mock-TAN",
         "hinweis":"Mock-TAN"
      }
   ],
   "aktivesSicherheitsverfahren":{
      "kodierung":1,
      "name":"Mock-TAN",
      "hinweis":"Mock-TAN"
   },
   "aktualisierungszeitpunkt":"2016-06-10 17:17:40",
   "timeout":"2016-12-24 13:37:42",
   "messages":[],
   "bankprodukte":[],
   "relations":[],
   "sync":false
}
Feld Typ Enthalten Beschreibung
status Enum Immer Abrufstatus des Bankzugangs
tanMedien Array von TanMedium Wenn vorhanden Auflistung der im Zugang verfügbaren TAN-Medien.
sicherheitsverfahren Array von Sicherheitsverfahren Wenn vorhanden Auflistung der im Zugang verfügbaren Sicherheitsverfahren
aktivesSicherheitsverfahren Sicherheitsverfahren Wenn vorhanden Das für den Zugang standardmäßige Sicherheitsverfahren
aktualisierungszeitpunkt Zeitstempel Immer Zeitpunkt der letzten Abfrage bei der Bank/Service-Provider
timeout Zeitstempel Wenn Daten nicht dauerhaft gespeichert werden Lebenszeit der Daten in Sekunden ab dem Aktualisierungszeitpunkt
messages Array von Message Wenn vorhanden Meldungen transportieren sowohl Fehler als auch Analyse-Events.
bankprodukte Array von Bankprodukt Wenn vorhanden Die im Zugang vorhandenen Bankprodukte
relations Array von Relation Wenn vorhanden Die für den Bankzugang verfügbaren Relations
sync Bool Immer Ob der Bankzugang automatisch im Hintergrund aktualisiert wird.

Werte für Status

Status Beschreibung
GESTARTET Der Datenabruf wurde gestartet
KOPFDATEN Der Datenabruf hat die Kopfdaten (Objekte und Relations) ermittelt
VOLLSTAENDIG Der Datenabruf ist vollständig abgeschlossen

Sicherheitsverfahren

{
   "kodierung":"4711",
   "name":"mTAN",
   "hinweis":"Ihre mTAN"
}

Dieses Objekt beschreibt ein Sicherheitsverfahren.

Feld Typ Vorhanden Beschreibung
kodierung String Immer Schlüssel für das Sicherheitsverfahren
name String Immer Menschenlesbare Bezeichnung für das Sicherheitsverfahren
hinweis String Wenn vorhanden Menschenlesbarer Hinweis zum Sicherheitsverfahren

TAN-Medium

{
   "gueltigVon":"2016-01-01 00:00:00",
   "gueltigBis":"2016-12-31 23:59:59",
   "name":"+49-1111-11111",
   "medienklasse":"MOBIL"
}

Dieses Objekt beschreibt ein TAN-Medium.

Feld Typ Vorhanden Beschreibung
gueltigVon Zeitstempel Wenn vorhanden Beginn der Gültigkeit.
gueltigBis Zeitstempel Wenn vorhanden Ende der Gültigkeit
name String Immer Name des TAN-Mediums wie z.B. die Mobiltelefonnummer
medienklasse Enum Immer Typ des Mediums

Medienklassen

Medienklasse Beschreibung
LISTE Papier-TAN-Liste
GENERATOR TAN-Generator
MOBIL Mobiltelefon
SECODER Matrix-TAN-Generator
PUSHTAN Push-Nachricht

Mögliche Relations

Relation Beschreibung
self Bankzugang abfragen
delete_bankzugang Bankzugang löschen

Bankzugänge abfragen

$ curl https://banksapi.io/customer/v2/bankzugaenge \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lassen sich die Bankzugänge des Customers abfragen.

Relation und Kontext
get_bankzugaenge bei Customer
HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
http://banksapi.io/customer/read

Durch den Aufruf dieser Methode erhält man eine Liste von Bankzugängen.

Rückgabe

Im Erfolgsfall kommt ein Objekt mit Bankzugängen zurück, in dem die Zugangs-ID als Schlüssel dient. Falls die Anfrage 180 Sekunden überschreitet, wird der HTTP-Status 504 (Gateway Timeout) zurückgegeben.

Bankzugänge hinzufügen

Mit dieser Funktion lassen sich zum Customer Bankzugänge hinzufügen.

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/customer/v2/bankzugaenge?refresh=false \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json' \
    -H 'content-type: application/json' \
    -d '{
          "Demo-Bank": {
            "providerId":"00000000-0000-0000-0000-000000000000",
            "credentials":{
              "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
              "pin":    "Hhnc+aW/eM ... 7F+XRSHasW"
            },
            "sync" : true
        }'
Relation und Kontext
add_bankzugaenge bei Customer
HTTP-Methode
POST
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
http://banksapi.io/customer/modify

Query-Parameter

Folgende Parameter können im Query-String mitgesendet werden (Angehängt an die URL, ?parameter1=wert1&parameter2=wert2)

Parameter Typ Pflicht Beschreibung
refresh Bool Nein Wenn der Bankzugang bereits existiert, werden unabhängig von der Hintergrundaktualisierung alle Umsätze und Informationen vom Provider neu abgefragt, wenn true

Request-Body

{
   "Demo-Bank": {
      "providerId":"00000000-0000-0000-0000-000000000000",
      "credentials":{
         "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
         "pin":    "Hhnc+aW/eM ... 7F+XRSHasW"
      },
      "sync" : true
   }
}

Der Request-Body besteht aus einem Objekt mit den Bank-Zugängen.

Der Objekt-Key ist eine vom Aufrufer vorgegebene ID (die Zugangs-ID) für den erzeugten Bankzugang.

Feld Typ Pflicht Beschreibung
providerId String Nur, wenn REG/Protect nicht verwendet wird Die ID des Zugangsproviders (Bank oder Serviceprovider) lt. der Provider-Liste
credentials Credentials Nur, wenn REG/Protect nicht verwendet wird Objekt mit den Zugangsdaten entsprechend den Authentication-Fields aus der Provider-Liste
sync Bool Nein Ob eine automatische regelmäßige Hintergrundaktualisierung durchgeführt werden soll

Rückgabe

Im Erfolgsfall wird der HTTP-Status 201 (Created) zusammen mit dem HTTP-Header Location zurückgegeben. Unter der im Header angegebenen URL können mittels eines HTTP-GET-Aufrufs die hinzugefügten Bankzugängen analog Abfrage von Bankzugängen abgefragt werden. Falls die Anfrage 180 Sekunden überschreitet, wird der HTTP-Status 504 (Gateway Timeout) zurückgegeben.

Bankzugänge löschen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/customer/v2/bankzugaenge \
    -X DELETE \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lassen sich alle Bankzugänge des Customers löschen.

Relation und Kontext
delete_bankzugaenge bei Customer
HTTP-Methode
DELETE
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
http://banksapi.io/customer/modify

Rückgabe

Im Erfolgsfall kommt der HTTP-Status 200 ohne weiteren Response-Body zurück.

Bankzugang abfragen

Mit dieser Funktion wird ein einzelner Bankzugang abgerufen.

$ curl https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'
Relation und Kontext
self bei Bankzugang
HTTP-Methode
GET
Gültigkeit
Bis Ende Timeout
OAuth2-Scope
http://banksapi.io/customer/read

Durch den Aufruf dieser Methode erhält man die Daten eines Bankzugangs.

Rückgabe

Im Erfolgsfall kommt ein Bankzugang-Objekt zurück. Falls die Anfrage 180 Sekunden überschreitet, wird der HTTP-Status 504 (Gateway Timeout) zurückgegeben.

Bankzugang löschen

Mit dieser Funktion wird ein einzelner Bankzugang gelöscht.

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank \
    -X DELETE \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'
Relation und Kontext
delete_bankzugang bei Bankzugang
HTTP-Methode
DELETE
Gültigkeit
Bis Ende Timeout
OAuth2-Scope
http://banksapi.io/customer/modify

Durch den Aufruf dieser Methode wird der Bankzugang gelöscht.

Rückgabe

Im Erfolgsfall kommt der HTTP-Status 200 ohne weiteren Response-Body zurück.

Bankprodukt

Ein Bankprodukt-Objekt entspricht einem Konto, Depot oder einer Kreditkarte.

{
  "kategorie":"GIROKONTO",
  "produktbezeichnung":"Demo-Girokonto",
  "produktId":"DE1235233452324553423442A",
  "inhaber":"Dan Cooper",
  "aktualisierungsdatum":"2016-05-23 13:37:00",
  "saldo":"200000.00",
  "waehrung":"USD",
  "saldoDatum":"2016-05-23 13:37:00",
  "kontonummer":"0123456789",
  "iban":"DE1235233452324553423442",
  "bic":"BICIS133742",
  "blz":"12345678",
  "kreditinstitut":"Demo-Bank",
  "messages":[],
  "relations":[]
}
Feld Typ Enthalten Beschreibung
id String Immer Im Zugang eindeutiger Bezeichner für das Bankprodukt. Wird vom System vergeben.
bezeichnung String Immer Bezeichnung des Bankprodukts lt. Bank/Service-Provider
kategorie Enum Immer Kategorie des Bankprodukts
saldo Decimal Wenn vorhanden Saldo/Wert des Bankprodukts mit zwei Nachkommastellen
aktualisierungszeitpunkt Zeitstempel Immer Zeitpunkt der letzten Aktualisierung des Produkts bei der Bank/Service-Provider
saldoDatum Zeitstempel Wenn vorhanden Standdatum wie von der Bank/Service-Provider gemeldet
waehrung Enum Wenn vorhanden Waehrung, in dem das Bankprodukt bewertet/geführt wird
kontonummer String Wenn vorhanden Die Konto- bzw. Kreditkartennummer. Die Kreditkartennummer wird u.U. nicht vollständig ausgegeben, sondern mit Stern z.B. "3223******4554
iban String Wenn vorhanden Die IBAN
bic String Wenn vorhanden Die BIC
blz String Wenn vorhanden Die Bankleitzahl
kreditinstitut String Wenn vorhanden Name des Kreditinstituts
inhaber String Immer Name des Produktinhabers
relations Array von Relations Wenn vorhanden Funktionen, die für den Customer zur Verfügung stehen
messages Array von Messages Wenn vorhanden Meldungen transportieren sowohl Fehler als auch Analyse-Events.
saldoDatenquelle Enum Immer Bei Depots die Datenquelle: SWIFTMSG, SONSTIGES
nur in Depot
ueberziehungslimit Decimal Wenn vorhanden Höhe des Überziehungslimits
nur in Konto
verfuegungsrahmen Decimal Wenn vorhanden Enthält den verfügbaren Saldo (i.d.R. Überziehungslimit + Saldo)
nur in Konto
verfuegterBetrag Decimal Wenn vorhanden Enthält den verfügbaren Saldo (i.d.R. Überziehungslimit + Saldo)
nur in Konto
vertragsnummer String Wenn vorhanden Bausparvertragsnummer (nicht eindeutig, kann über mehrere Produkt-IDs desUsers identisch sein)
nur in Bausparvertrag
rating Decimal Wenn vorhanden Bewertungszahl, die die Bausparkasse je nach Sparleistung undAnlagedauer vergibt
nur in Bausparvertrag
vertragssumme Decimal Wenn vorhanden
nur in Bausparvertrag
vertragstyp String Wenn vorhanden Tarifbezeichnung (z.B. „Fuchs WohnRente“ oder „LBS-F9“), kann dem Produktnamen entsprechen
nur in Bausparvertrag
sparzustand Bool Wenn vorhanden Befindet sich der Vertrag aktuell in der (An-)Sparphase?
nur in Bausparvertrag
vertragsstatus String Wenn vorhanden Vertragszustand (abh. von der Bausparkasse, mögliche Ausprägungen sind z.B.: Ansparphase, Bausparvertrag, Vorfinanzierung, Zwischenfinanzierung)
nur in Bausparvertrag
sparzinssatz Decimal Wenn vorhanden Sparzinssatz in %
nur in Bausparvertrag
schuldzinssatz Decimal Wenn vorhanden Dahrlehenszinssatz in %
nur in Bausparvertrag
vertragsDatum Zeitstempel Wenn vorhanden
nur in Bausparvertrag
sparfortschritt Decimal Wenn vorhanden Ansparstand des Bausparvertrages in %
nur in Bausparvertrag

Mögliche Werte Bankprodukt-Kategorien

Kategorie Beschreibung
GIROKONTO Konto für den Zahlungsverkehr, sowie auch für die Verrechnung/Abwicklung z.B. von depotbezogenen Buchungen, Gebühren, Zinsen etc.
SPARKONTO Verzinstes Konto mit unbefristeter Laufzeit und festgelegter Kündigungsfrist, i.d.R. ist eine sofortige Geldentnahme auf einen Maximalwert begrenzt
FESTGELDKONTO Verzinstes Konto mit vertraglich vereinbarter Laufzeit
KREDITKONTO Konto zur Verwaltung des Kreditsaldos
TAGESGELDKONTO Verzinstes Konto für eine Geldanlage mit täglicher Verfügbarkeit
BAUSPARKONTO Anspar- und evtl. Darlehenskonto für einen Bausparvertrag
SONSTIGESKONTO Konto, das weder durch den Provider noch durch unsere Produktheuristik zugeordnet werden kann
KREDITKARTE Bezahlkarte mit Kreditrahmen, Verrechnung erfolgt über ein vereinbartes Girokonto/Verrechnungskonto
SONSTIGEKARTE Bezahlkarte, die weder durch den Provider noch durch unsere Produktheuristik zugeordnet werden kann
DEPOT "Wertpapierkonto" zur Verwahrung von Wertpapieren
SONSTIGESPRODUKT Bankprodukt, das weder durch den Provider noch durch unsere Produktheuristik zugeordnet werden kann

Mögliche 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"
  }
]
Relation Beschreibung
self Bankprodukt abfragen
get_kontoumsaetze Kontoumsätze abfragen
get_depotpositionen Depot-Positionen abfragen
start_ueberweisung Überweisung anlegen

Bankprodukt abfragen

Mit dieser Funktion wird ein einzelnes Bankprodukt abgerufen.

$ curl https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345678 \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'
Relation und Kontext
self bei Bankprodukt
HTTP-Methode
GET
Gültigkeit
Bis Ende Timeout
OAuth2-Scope
http://banksapi.io/customer/read

Durch den Aufruf dieser Methode erhält man die Daten eines Bankprodukts.

Rückgabe

Im Erfolgsfall kommt ein Bankprodukt zurück. Falls die Anfrage 180 Sekunden überschreitet, wird der HTTP-Status 504 (Gateway Timeout) zurückgegeben.

Kontoumsatz

Ein Kontoumsatz-Objekt entspricht einem Umsatz eines Kontos oder einer Kreditkarte.

{
    "betrag": -70,
    "verwendungszweck": "EC 68096654 140215204106OC3 Ref. 5CC15048A1824480/89280",
    "buchungsdatum": "2016-11-17 00:00:00",
    "wertstellungsdatum": "2016-11-15 00:00:00",
    "gegenkontoInhaber": "La Sopia GmbH München",
    "gegenkontoIban": "DE00123456789012345679",
    "gegenkontoBic": "XXX12345678",
    "primanotaNummer": "421337",
    "classifications": [{
        "category": "recreation_restaurants",
        "parentCategory": "recreation",
        "displayName": "Ausgehen und Essen",
        "confidenceLevel": 0.9
    }, {
        "category": "recreation",
        "displayName": "Freizeit und Unterhaltung",
        "confidenceLevel": 0.8
    }]
}
Feld Typ Enthalten Beschreibung
betrag Number Wenn vorhanden Betrag mit zwei Nachkommastellen.
verwendungszweck String Wenn vorhanden Der Verwendungszweck des Umsatzes
buchungstext String Wenn vorhanden Der Buchungstext des Umsatzes
gvCode String Wenn vorhanden Der ZKA-GV-Code des Umsatzes
primanotaNummer String Wenn vorhanden Primanota-Nummer des Umsatzes
buchungsdatum Zeitstempel Wenn vorhanden Datum der Buchung
wertstellungsdatum Zeitstempel Wenn vorhanden Datum der Wertstellung
gegenkontoInhaber String Wenn vorhanden Inhaber des Gegenkontos
gegenkontoIban String Wenn vorhanden IBAN des Gegenkontos
gegenkontoBic String Wenn vorhanden BIC des Gegenkontos
classifications Array von Classifications Wenn vorhanden Passende Umsatzkategorien inkl. Konfidenz

Classification (Umsatzkategorisierung)

Ein Classification-Objekt entspricht einer Klassifizierung zu einer Umsatzkategorie

{
    "category": "bills_electricity",
    "parentCategory": "bills",
    "displayName": "Strom",
    "confidenceLevel": 0.8
}
Feld Typ Enthalten Beschreibung
category String Immer Eindeutiger Systemname der Umsatzkategorie
parentCategory String Wenn vorhanden Wenn es sich um eine Subkategorie handelt, beinhaltetet dieses Feld den Systemnamen der Hauptkategorie
displayName String Immer Nutzer-freundlicher Name der Umsatzkategorie
confidenceLevel Number Wenn vorhanden Wahrscheinlichkeitswert (0-1), dass der Kontoumsatz zu dieser Kategorie gehört

Kontoumsätze abfragen

Mit dieser Funktion werden die Kontoumsätze abgerufen.

$ curl https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345678/kontoumsaetze \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'
Relation und Kontext
get_kontoumsaetze bei Bankprodukt
HTTP-Methode
GET
Gültigkeit
Bis Ende Timeout
OAuth2-Scope
http://banksapi.io/customer/read

Durch den Aufruf dieser Methode erhält man die Daten eines Bankprodukts.

Query-Parameter

Folgende Parameter können im Query-String mitgesendet werden (Angehängt an die URL, ?parameter1=wert1&parameter2=wert2)

Parameter Typ Pflicht Beschreibung
categorize Bool Nein Ob der Umsatz zur Laufzeit kategorisiert werden soll. Die resultierenden Kontoumsätze enthalten dann jeweils Classification-Objekte

Rückgabe

Im Erfolgsfall kommt ein Array von Kontoumsätzen zurück.

Depotposition

Ein Depotposition-Objekt entspricht einer Wertpapierposition eines Depots.

{
   "name":"Aberdeen Global - Emer. Markets Equity E2",
   "menge":210.819609,
   "handelseinheit":"STUECK",
   "isin":"LU0498181733",
   "wkn":"A1C5UV",
   "kurs":15.4117,
   "kursDatum":"2015-05-11 00:00:00",
   "waehrung":"EUR",
   "waehrungskurs":1.0,
   "handelsplatz":"KAG",
   "gesamtwert":3249.09
}
Feld Typ Enthalten Beschreibung
name String Wenn vorhanden Bezeichnung der Depotposition, i.d.R. Name des Finanzinstruments
menge Number Wenn vorhanden Stücke mit Nachkommastellen
handelseinheit Enum Wenn vorhanden Handelseinheit, STUECK oder NOMINAL
isin String Wenn vorhanden ISIN des Finanzinstruments
wkn String Wenn vorhanden WKN des Finanzinstruments
kurs Number Wenn vorhanden Kurs in Handelswährung
kursDatum Zeitstempel Wenn vorhanden Stand des Kurses
waehrung String Wenn vorhanden Handelswährung (Alphabetic Code ISO 4217)
waehrungskurs Number Wenn vorhanden Umrechnungskurs von der Handelswährung nach EUR
handelsplatz String Wenn vorhanden Handelsplatz der Preisfeststellung
gesamtwert Number Wenn vorhanden Gesamtwert des Bestands in Handelswährung lt. Buchungsabschluss

Depotpositionen abfragen

Mit dieser Funktion werden die Depotpositionen abgerufen.

$ curl https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/9012345680/depotpositionen \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'
Relation und Kontext
get_depotpositonen bei Bankprodukt
HTTP-Methode
GET
Gültigkeit
Bis Ende Timeout
OAuth2-Scope
http://banksapi.io/customer/read

Rückgabe

Im Erfolgsfall kommt ein Array von Depotpositonen zurück.

Überweisung anlegen

$ curl https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345679 \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'content-type: application/json' \
    -d '{
   "credentials":{
      "userid":"mXlkGe+ukAEs+2iHjcM8PM7B94SIXgGlt95JOao+cWdWDJkzjlGhFChkNT3NsVy7oskVDq4omgkAhf84FV2udD6ObRuFla7KcTyKeVYD1+N8yegK620B920sSPb+md0Sdia85+DMbnqFTkxsG+FUzsAA3hFSHsGKUgI6awMWbPdX5eDzR7b6qnSI+uOjee4hWp+ht9ecYy5msAk6TKFwzmvfLEy52afpBdjtGNpiRFnPbyRkkPvlihA3Bcv5leBdLD8uy8+AV1l4gC+ASv/qSiR31/5ZwMUr4jrP1kE9vMfvPQK1ZE8g3x/zcvl/cqz02OYATlDQejhacuWmJtU37W1Pvcq3fltTcGZmps1dcIo9BnWA2Vwl9laecJzOejij5LL8+shk+a/973JknvAtejH8McW3zNbQf8gPpXnkINoHhS5njZ5RseQljlMcYRgpqcGwjuxfAPkguifR2st5zC2VJjlRhR/qXolYWzghy06o5gxnDeQKMCo1K1kihxzlUznk/KAcr7AmjgLHRgoftS2GOtR0GJxI49jojQ5lbIeY9CSzVae0clqMqpbeKFyYRT2F/f7ZaNMMCrEzcCRTSjJUMemPDWi0o2iVo+n3WBk8coLXXEkv0xTV2G5Pxz2lFhgJm2oFHteqFRgZktdagz+ft6uyURWRD/MOfGsd8HY=",
      "pin":"XO2jgZX9V5GvB9rg8w6px0r/gypl5fL07ne7fX5/OolxScRo9opQqrmv90Bo2fT2ej9JQ27jWF3ltrZXLrtil2NoKmwwsVB9YuW6NEr3bw/d3jwOlJEyvQawul0tSte+nL18sWXTHPB9vPv1ATQviOmxgJUmu8iBnwND1x46iwwUSZemVng2yBExZvsaCBZS+5aMi1mQyf5b70woxtaAVhkL2nXUddSQMNiqAgyETZBFzu71M0+crBPz2hcZk4s2L90EjZ35DdkW8MmxSPH5dtvccxjmuT6HjBfilSeeNicE+U7vSkmGO4LTJ/RaTNF/F2BQkDG1j8w4gnNgEzl9J1ZplJMA+/kFrQSoWVtotUO0STI0l+x0xmHP1GkYQgYxoEVvlz1PvHYDxqao4NKWQGEqAh7a34NzSBfIccpLeTyNI9DZvJLIPLw/jTHTKui0uz0UcLEYV71yJnZ5LwazZGrESYppsI6FD6Ex9Y+tF4cjkodRvjLSx1bWkyvPj1m2e0U/DaSLs5708eZj1dJTJAmpz+flOStSaY0RIF7RdbVlCfMRljd/AMfvpAyEW63tHGV/KXqryIfysNE+SI+cG8HNHwVDmPe2jAGEkAQpCTnLruEn8+KQgv9V4oWMYhE3OgHFtH1vzccqCbzjWKilAXdeBXVHC9W1Rv5GfhKpZmw="
   },
   "empfaenger":"netzpolitik.org e. V.",
   "verwendungszweck":"Spende netzpolitik.de",
   "iban":"DE62430609671149278400",
   "bic":"GENODEM1GLS",
   "waehrung":"EUR",
   "betrag":1337.42,
   "ausfuehrungsdatum":"2016-12-24",
   "sicherheitsverfahrenKodierung":"1",
   "tanMediumName":"Mobil"
}'

Mit dieser Funktion wird eine SEPA-Überweisung angestoßen.

Relation und Kontext
start_ueberweisung bei Bankprodukt
HTTP-Methode
POST
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
http://banksapi.io/customer/ueberweisung

Request-Body

{
   "credentials":{
      "userid":"mXlkGe+ukAEs+2iHjcM8PM7B94SIXgGlt95JOao+cWdWDJkzjlGhFChkNT3NsVy7oskVDq4omgkAhf84FV2udD6ObRuFla7KcTyKeVYD1+N8yegK620B920sSPb+md0Sdia85+DMbnqFTkxsG+FUzsAA3hFSHsGKUgI6awMWbPdX5eDzR7b6qnSI+uOjee4hWp+ht9ecYy5msAk6TKFwzmvfLEy52afpBdjtGNpiRFnPbyRkkPvlihA3Bcv5leBdLD8uy8+AV1l4gC+ASv/qSiR31/5ZwMUr4jrP1kE9vMfvPQK1ZE8g3x/zcvl/cqz02OYATlDQejhacuWmJtU37W1Pvcq3fltTcGZmps1dcIo9BnWA2Vwl9laecJzOejij5LL8+shk+a/973JknvAtejH8McW3zNbQf8gPpXnkINoHhS5njZ5RseQljlMcYRgpqcGwjuxfAPkguifR2st5zC2VJjlRhR/qXolYWzghy06o5gxnDeQKMCo1K1kihxzlUznk/KAcr7AmjgLHRgoftS2GOtR0GJxI49jojQ5lbIeY9CSzVae0clqMqpbeKFyYRT2F/f7ZaNMMCrEzcCRTSjJUMemPDWi0o2iVo+n3WBk8coLXXEkv0xTV2G5Pxz2lFhgJm2oFHteqFRgZktdagz+ft6uyURWRD/MOfGsd8HY=",
      "pin":"XO2jgZX9V5GvB9rg8w6px0r/gypl5fL07ne7fX5/OolxScRo9opQqrmv90Bo2fT2ej9JQ27jWF3ltrZXLrtil2NoKmwwsVB9YuW6NEr3bw/d3jwOlJEyvQawul0tSte+nL18sWXTHPB9vPv1ATQviOmxgJUmu8iBnwND1x46iwwUSZemVng2yBExZvsaCBZS+5aMi1mQyf5b70woxtaAVhkL2nXUddSQMNiqAgyETZBFzu71M0+crBPz2hcZk4s2L90EjZ35DdkW8MmxSPH5dtvccxjmuT6HjBfilSeeNicE+U7vSkmGO4LTJ/RaTNF/F2BQkDG1j8w4gnNgEzl9J1ZplJMA+/kFrQSoWVtotUO0STI0l+x0xmHP1GkYQgYxoEVvlz1PvHYDxqao4NKWQGEqAh7a34NzSBfIccpLeTyNI9DZvJLIPLw/jTHTKui0uz0UcLEYV71yJnZ5LwazZGrESYppsI6FD6Ex9Y+tF4cjkodRvjLSx1bWkyvPj1m2e0U/DaSLs5708eZj1dJTJAmpz+flOStSaY0RIF7RdbVlCfMRljd/AMfvpAyEW63tHGV/KXqryIfysNE+SI+cG8HNHwVDmPe2jAGEkAQpCTnLruEn8+KQgv9V4oWMYhE3OgHFtH1vzccqCbzjWKilAXdeBXVHC9W1Rv5GfhKpZmw="
   },
   "empfaenger":"netzpolitik.org e. V.",
   "verwendungszweck":"Spende netzpolitik.de",
   "iban":"DE62430609671149278400",
   "bic":"GENODEM1GLS",
   "waehrung":"EUR",
   "betrag":1337.42,
   "ausfuehrungsdatum":"2016-12-24",
   "sicherheitsverfahrenKodierung":"1",
   "tanMediumName":"Mobil"
}

Das Überweisung-Objekt trägt die Daten für eine SEPA-Überweisung. Es wird beim Anlegen einer Überweisung erwartet.

Feld Typ Pflichtfeld Beschreibung
credentials Credentials Ja Objekt mit den Zugangsdaten entsprechend den Authentication-Fields aus der Provider-Liste
empfaenger String Ja Empfänger der Überweisung
verwendungszweck String Ja Verwendungszweck der Überweisung.
iban String Ja IBAN des Empfängerkontos
bic String Ja BIC des Empfängerkontos
waehrung String Ja Waehrung der Überweisung (Alphabetic Code ISO 4217)
betrag Number Ja Überweisungsbetrag
ausfuehrungsdatum Date Nein Datum, zu dem die Überweisung ausgeführt werden soll
sicherheitsverfahrenKodierung String Ja Kodierung des zu verwendende Sicherheitsverfahrens, siehe Bankprodukt
tanMediumName String Nein Das zu verwendende TAN-Medium, siehe Bankprodukt

Rückgabe

{
   "messages": [
      {
         "code":"BA1110",
         "level":"INFO",
         "message":"TAN-Eingabe nötig",
         "details":"Bitte geben Sie die TAN ein"
      }
   ],
   "timeout": "2017-08-31 16:08:55",
   "relations": [
      {
         "rel": "submit_text_tan",
         "href": "https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345679/c612b2f3-f797-4f66-bec4-2064812c8736"
      }
   ],
   "challenge": {
      "name": "chipTAN optisch",
      "content": {
         "HHD": "11048714955205123456789F14302C303107",
         "HHDUC": "1234567891234567891234567890,01"
      }
   }
}

Als Ergebnis kommt ein Objekt mit dem Überweisungsstatus zurück.

Feld Typ Enthalten Beschreibung
messages Array von Messages Immer Meldungen zur TAN-Eingabe oder Fehlertexte zur Überweisung
timeout Zeitstempel Wenn Folgeaktionen erwartete werden Zeitpunkt bis zu auf Folgeaktionen gewartet wird
relations Array von Relations Relations für die Folgeaktionen
challenge Challenge-Objekt bei chipTAN optisch oder photoTAN Beeinhaltet Informationen zur TAN-Generierung

Mögliche Relations

[
  {
    "rel":"submit_text_tan",
    "href":"https://banksapi.io/customer/v2/ueberweisung/DE1235233452324553423442/9b90127c-9b85-11e6-82d8-480fcfb9550f"
  }
]
Relation Beschreibung
submit_text_tan TAN übermitteln

Challenge

Das Challenge-Objekt bildet die Daten, die für eine TAN-Generierung benötigt werden. Diese unterscheiden sich zwischen den TAN-Verfahren.
Das content-Objekt enthält im Falle von ChipTAN optisch die Felder HHD und HHDUC. Aus diesen Daten muss selbstständig eine Flickergrafik generiert werden. Eine Einführung zu Flickergrafiken gibt es beispielsweise hier. Eine beispielhafte Implementierung hier. Im Falle von photoTAN wird ein Feld photo ausgegeben, das ein Base64-kodiertes Bild beinhaltet. Der Inhalt von photo lässt sich somit beispielsweise mittels <img>-Tag darstellen. In jedem Fall existiert ein instructions-Feld mit einem Hinweistext zur TAN-Eingabe.

{
   "challenge": {
      "name": "chipTAN optisch",
      "content": {
         "instructions": "Nutzen sie Ihren TAN-Generator und geben sie anschließend Ihre TAN ein.",
         "HHD": "11048714955205123456789F14302C303107",
         "HHDUC": "1234567891234567891234567890,01"
      }
   }
}
Feld Typ Enthalten Beschreibung
name Name des TAN-Verfahrens Immer Name des TAN-Verfahrens
content Objekt Immer Enthält Daten zur Tan-Generierung

TAN übermitteln

# Dieses Kommando muss analog für den Test selbst zusammengebaut werden
$ curl https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345679/b626973e-de7b-4221-be70-a87c40069566 \
    -X PUT \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe ' \
    -H 'content-type: application/json' \
    -d '{"tan":"XXXXXX"}'

Mit dieser Funktion wird eine textuelle TAN zur Validierung einer SEPA-Überweisung an die Bank übermittelt.

Relation und Kontext
submit_text_tan im Überweisungsstatus
HTTP-Methode
PUT
Gültigkeit
Bis zum Timeout des Überweisungsstatus
OAuth2-Scope
http://banksapi.io/customer/ueberweisung

Request-Body

{
   "tan":"XXXXX"
}
Feld Typ Pflichtfeld Beschreibung
tan String Ja Die TAN zur Bestätigung der Überweisung

Rückgabe

{
   "hinweis":"Bitte geben Sie die SMS-TAN ein",
   "timeout":"2016-12-24 20:00:00",
   "relations":[
      {
         "rel":"submit_text_tan",
         "href":"https://banksapi.io/customer/v2/ueberweisung/DE1235233452324553423442/9b90127c-9b85-11e6-82d8-480fcfb9550f"
      }
   ]
}

Die Rückgabe ist wieder der Überweisungsstatus. Wenn die TAN falsch war, hat sich der Hinweis entsprechend geändert und es gibt weiterhin einen Timeout und die Relation submit_text_tan. War die TAN richtig, dann verschwinden Timeout und die Relations.

Weitere Informationen finden sich im Abschnitt Überweisung anlegen

REG/Protect

Das REG/Protect stellt als Redirect-Lösung ein HTML-Frontend zum Hinzufügen von Bankzugängen sowie Auslösen von Zahlungen bereit.

Kontextinfo bei Rücksprung zu Ihrer App

Der Rücksprung des Nutzers kann aus verschiedenen Gründen erfolgen, der Grund wird im Query-Parameter baReentry mitgeteilt:

Art des Rücksprungs Grund Beispiel Wert für baReentry
Prozess erfolgreich abgeschlossen fachlich FINISHED
User stimmt AGB/DSE nicht zu fachlich LEGAL_NOT_ACCEPTED
Klick auf "Zum Kundenportal" fachlich Klick auf Seite "Bank auswählen" USER_CANCELLED
Abbruch des Prozesses fachlich Abbruch auf Seite "Ihre Konten" USER_CANCELLED
Unerwarteter HTTP-Repsonse-Code technisch HTTP 200 erwartet aber HTTP 500 geliefert BACKEND_ERROR
Unerwartete HTTP-Response (Body) technisch Gültiges JSON erwartet aber ungültiges geliefert ACKEND_ERROR
Zugangsdaten dreimal falsch eingegeben fachlich INVALID_CREDENTIALS
TAN dreimal falsch eingegeben fachlich INVALID_TAN
Allgemeiner Fehler technisch Guard verhindert Maskeneinstieg; evtl. Manipulationsversuch ERROR
Keine Konten für Überweisung gefunden fachlich Beim Einstieg in die Überweisung wurden keine Konten oder keine für die Überweisung geeigneten Konten gefunden werden NO_ACCOUNTS

Hinzufügen von Bankzugängen

$ curl https://banksapi.io/customer/v2/bankzugaenge \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json' \
    -H 'content-type: application/json' \
    -d '{"637a3945-bb02-4e82-ac9e-f7c26d2568ce": {}}'

< HTTP/1.1 451
< Content-Length: 0
< Location: https://banksapi.io/customer/v2/webform?session=b19c3937- ... -3b861be7e71e
    &useCase=CREATE_ACCOUNT

Das Hinzufügen wird beim Anlegen eines Bankzugangs automatisch angestoßen, wenn Sie als nicht-regulierter Mandant angelegt wurden.

Der POST Bankzugänge hinzufügen-Aufruf endet dann im Erfolgsfall nicht im HTTP-Status 201 (Created), sondern in 451 (Unavailable For Legal Reasons) mit Location-HTTP-Header. Der Status-Code dient als Indikator dafür, dass der Anwendungsfall im Kontext des BANKSapi RegProtects fortgeführt werden muss.

Der Location-Header enthält dann die aufzurufende URL auf BANKSapi-Seite. Der Aufruf des Web Forms sollte im gleichen Browserfenster erfolgen und den aktuellen Inhalt ersetzen und ist aus Sicherheitsgründen nur ein einziges Mal möglich. Hiermit wird der RegProtect-Prozess bei BANKSapi gestartet und der Endkunde bekommt in den folgenden von BANKSapi ausgelieferten Masken die Möglichkeit, einen Provider auszuwählen und seine Onlinebanking-Zugangsdaten einzugeben.

An diese URL muss von Ihnen noch ein Query-Parameter callbackUrlangehängt werden (URL-encoded), der von BANKSapi-Seite nach erfolgter (erfolgreicher oder fehlgeschlagener) Registrierung des Kontos des Endkunden wieder aufgerufen wird.

Die gesamten Query-Parameter des REG/Protects für das Hinzufügen eines Bankzugangs in der Übersicht:

Feld Typ Enthalten Beschreibung
useCase String Immer CREATE_ACCOUNT
callbackUrl String Immer Die URL auf Ihrer Seite, auf die der Nutzer nach dem Registrierungsprozess bei BANKSapi weitergeleitet wird. Achtung: Muss URL-kodiert sein

Die callbackUrl ist dann die URL, auf die der Nutzer nach Registrierung weitergeleitet wird. Sie wird vom Nutzer-Browser aufgerufen (in dem von Ihnen geöffneten Popup-Fenster, also als GET) mit dem gesamten von Ihnen gelieferten Query-String, Sie können also auch eigene Parameter spezifizieren, die dann von BANKSapi transparent behandelt werden. Unter der URL sollte logischerweise eine Frontend-Seite liegen, da Sie dem Nutzer dann ja angezeigt wird.

Zusätzlich zur von Ihnen spezifizierten Query-String in der callbackUrl werden außerdem folgende Query-Parameter mitgesendet (Angehängt an die URL, ?parameter1=wert1&parameter2=wert2):

Feld Typ Enthalten Beschreibung
baReentry String Immer Im Erfolgsfall FINISHED

Auslösen einer Zahlung

curl https://banksapi.io/customer/v2/ueberweisung/e1f30693- ... -bab3bc2/DE00123456789012345679 \
    -X POST \
    -H 'authorization: bearer 9df54960-f678-47ec-84dc-6c771f9c980c' \
    -H 'content-type: application/json' \
    -d '{}'

< HTTP/1.1 451
< Content-Length: 0
< Location: https://banksapi.io/customer/v2/webform?session=b19c3937- ... -3b861be7e71e
    &useCase=START_TRANSFER

Das Auslösen einer Zahlung erfolgt analog dem Hinzufügen eines Konto zunächst durch Aufruf des unter Überweisung anlegen dokumentierten Endpunkts mittes HTTP POST. Da sämtliche Zahlungsdaten im Verlaufe des Prozesses bei BANKSapi ermittelt werden, ist es hier ausreichend, lediglich ein leeres JSON-Objekt als Payload zu übermitteln.

Wie im Anwendungsfall zuvor wird ein 451 (Unavailable For Legal Reasons) mit Location-HTTP-Header geliefert.

An diese URL muss von Ihnen noch ein Query-Parameter callbackUrl angehängt werden (URL-encoded), der von BANKSapi-Seite nach erfolgter (erfolgreicher oder fehlgeschlagener) Auslösen der Überweisung wieder aufgerufen wird.

Die gesamten Query-Parameter des REG/Protects für das Hinzufügen eines Bankzugangs in der Übersicht:

Feld Typ Enthalten Beschreibung
useCase String Immer START_TRANSFER
callbackUrl String Immer Die URL auf Ihrer Seite, auf die der Nutzer nach dem Überweisungsprozess bei BANKSapi weitergeleitet wird. Achtung: Muss URL-kodiert sein

Die callbackUrl ist dann die URL, auf die der Nutzer nach der Überweisung weitergeleitet wird. Sie wird vom Nutzer-Browser aufgerufen (in dem von Ihnen geöffneten Fenster, also als GET) mit dem gesamten von Ihnen gelieferten Query-String, Sie können also auch eigene Parameter spezifizieren, die dann von BANKSapi transparent behandelt werden. Unter der URL sollte logischerweise eine Frontend-Seite liegen, da Sie dem Nutzer dann ja angezeigt wird.

Zusätzlich zur von Ihnen spezifizierten Query-String in der callbackUrl werden außerdem folgende Query-Parameter mitgesendet (Angehängt an die URL, ?parameter1=wert1&parameter2=wert2):

Feld Typ Enthalten Beschreibung
baReentry String Immer Im Erfolgsfall FINISHED

Verschlüsselung

Zur Verschlüsselung der Credentials wird das asymmetrische Kryptoverfahren RSA eingesetzt. Wenn Sie unser Kunde werden, bekommen Sie von uns einen öffentlichen Schlüssel geliefert, mit dem die Verschlüsselung vorgenommen wird.

Da die konkrete Umsetzung der Verschlüsselung in den verschiedenen Programmierumgebungen voneinander abweicht, werden hier die charakterisierenden Eigenschaften des Verfahrens (spezifiziert in PKCS #1) aufgezählt, mit denen die Umsetzung in Ihrer bevorzugten Entwicklungsumgebung kein Problem darstellen sollte:

Notifications

Webhook-Calls ("Notifications") können auf Wunsch als POST bei folgenden Vorkomnissen während einer Hintergrundaktualisierung durchgeführt werden (unabhängig voneinander):

Event Beschreibung
Transaction Neue Transaktion(en) gefunden
Balance Der Kontostand hat sich geändert
Error Bei der Hintergrundaktualisierung ist ein Fehler aufgetreten
POST /ihr-notification-endpunkt HTTP/1.1
User-Agent: BANKSapi Notifier
Host: www.ihre-domain.com
Content-Type: application/json
Accept: */*
Connection: close

Der POST-HTTP-Call sieht während des Aufrufs wie folgt aus:

Header Wert
User-Agent BANKSapi Notifier
Content-Type application/json
Accept */*

Notification Objekt

Die Payload, also der BODY des POST-Requests enthält bei allen Arten von Notifications mindestens folgende Felder:

Feld Typ Enthalten Beschreibung
userId String Immer userid des Users als OAuth-Token
accountId String Immer id des Bankzugangs
tenant String Immer name des Tenants
notificationType String Immer Enthält den Notification Type
occurred Zeitstempel Immer Zeitpunkt des Auslösens der Notification
serial Integer Immer Fortlaufende, ganzzahlige Sequenznummer der Notification zur Überprüfung von verpassten Benachrichtigungen

Notification Type

Event Type
Transaction TRANSACTION
Balance BALANCE
Error ERROR

Transaction Notification

{
    "userId": "mOd2uKYr+2 ... TWOPCAt5zP",
    "accountId": " 3671fbf6-c752-4107-a9c0-61ea77cd7f5e",
    "tenant": "demo",
    "notificationType": "TRANSACTION",
    "occurred": "2019-05-11 09:05:00",

    "productId": "DE1235233452324553423442A",
    "newTransactions": [{
        "payeeName": "La Sopia GmbH München",
        "amount": -70
    }, {
        "payeeName": "netzpolitik.org e. V.",
        "amount": -1337.42
    }]
}

Im Falle, dass eine oder mehrere neue Transaktionen gefunden wurden, wird dieses Objekt vom Notifier versendet. Es enthält zusätzlich zu den Feldern des Notification-Objekts:

Feld Typ Enthalten Beschreibung
productId String Immer Enthält die id des Bankprodukts
newTransactions Array von Transaction-Objekten Immer Enthält die neuen Umsätze in Form von Transaction-Objekten

Transaction-Objekt

{
    "payeeName": "La Sopia GmbH München",
    "amount": -70
}
Feld Typ Enthalten Beschreibung
payeeName String Immer Enthält die id des Bankprodukts
amount Number Wenn vorhanden Höhe des Umsatzes, ggf. negativ für Ausgänge

Request-Body

Der Request-Body besteht aus einem Transaction-Notification-Objekt.

Balance Notification

{
    "userId": "mOd2uKYr+2 ... TWOPCAt5zP",
    "accountId": " 3671fbf6-c752-4107-a9c0-61ea77cd7f5e",
    "tenant": "demo",
    "notificationType": "BALANCE",
    "occurred": "2019-05-11 09:05:00",

    "productId": "DE1235233452324553423442A",
    "oldBalance": 200000.00,
    "newBalance": 205000.00
}

Im Falle, dass sich der Kontostand bzw. Bestand eines Bankprodukts geändert hat, wird dieses Objekt vom Notifier versendet. Es enthält zusätzlich zu den Feldern des Notification-Objekts

Feld Typ Enthalten Beschreibung
productId String Immer Entält die id des Bankprodukts
oldBalance Number Immer Enthält den alten Kontostand bzw. Bestand vor der letzten Hintergrundaktualisierung.
newBalance Number Immer Enthält den neuen Kontostand bzw. Bestand, der durch die aktuelle Hintergrundaktualsierung ermittelt wurde.

Request-Body

Der Request-Body besteht aus einem Balance-Notification-Objekt.

Error Notification

{
    "userId": "mOd2uKYr+2 ... TWOPCAt5zP",
    "accountId": " 3671fbf6-c752-4107-a9c0-61ea77cd7f5e",
    "tenant": "demo",
    "notificationType": "ERROR",
    "occurred": "2019-05-11 09:05:00",

    "level": "ERROR",
    "code": "BA1010",
    "message": "Zugang gesperrt"
}

Im Falle, dass bei der Hintergrundaktualisierung ein Fehler aufgetreten ist, wird dieses Objekt vom Notifier versendet. Es enthält zusätzlich zu den Feldern des Notification-Objekts

Feld Typ Enthalten Beschreibung
level String Immer Eines von INFO, WARNING, ERROR
code String Immer Siehe Fehler und Meldungen
message String Immer Siehe Fehler und Meldungen
data String Wenn vorhanden Ggf. weitere Informationen als String

Request-Body

Der Request-Body besteht aus einem Error-Notification-Objekt.

Umsatzkategorien

Die aktuelle Liste von Kategorien für die Klassifizierung kann sich jederzeit ändern, auch ohne Änderung der Versionsnummer der API.

Hauptkategorie Subkategorie Systemname
Lebenshaltung LIVING
Lebensmittel LIVING_GROCERIES
Drogerie LIVING_DRUGSTORE
Verbrauchsgüter für die Haushaltsführung LIVING_CONSUMABLES
Sonstige LIVING_OTHER
Wohnen HOUSING
Miete/Wohngeld HOUSING_RENT
Immobilienkredit HOUSING_FINANCING
Nebenkosten HOUSING_ANCILLARYCOSTS
Haushaltdienstleistungen HOUSING_SERVICES
Möbel und Haushaltsgeräte HOUSING_FURNISHING
Sonstige HOUSING_OTHER
Vertragsrechnungen (Utilities) BILLS
Strom BILLS_ELECTRICITY
Wärme BILLS_HEATING
Internet und Festnetz BILLS_FIXEDINTERNET
Handy BILLS_MOBILE
Sonstige BILLS_OTHER
Gesundheit HEALTH
Artzbesuch / Krankenhaus / Pflege HEALTH_SERVICES
Arznei und Heilmittel HEALTH_CONSUMABLES
Sonstige HEALTH_OTHERS
Mobilität MOBILITY
KFZ - Kredit/Kauf/Leasing MOBILITY_VEHICLEACQUISITION
Kraft- und Fahrräder - Kredit/Kauf/Leasing MOBILITY_BIKEACQUISITION
Kraftstoffe und Schmiermittel MOBILITY_FUEL
Wartung, Pflege und Reparaturen MOBILITY_SERVICES
Parken MOBILITY_PARKING
ÖPNV MOBILITY_PUBLICTRANSPORT
Car-Share MOBILITY_CARSHARE
Bike-Share MOBILITY_BIKESHARE
Taxi MOBILITY_TAXI
Sonstige MOBILITY_OTHER
Reisen TRAVEL
Unterkunft TRAVEL_ACCOMMODATION
Transport TRAVEL_TRANSPORT
Aktivitäten TRAVEL_ACTIVITIES
Pauschalreisen TRAVEL_INCLUSIVEOFFERS
Sonstige TRAVEL_OTHER
Kinder und Familie FAMILY
Kinderbetreung FAMILY_CHILDCARE
Kinder und Babybedarf FAMILY_CHILDNECESSITIES
Spielwaren FAMILY_TOYS
Kinderaktivitäten FAMILY_CHILDACTIVITIES
Unterhalt FAMILY_SUPPORT
Sonstige FAMILY_OTHER
Bildungswesen EDUCATION
Fortbildung EDUCATION_TRAINING
Uni EDUCATION_ACADEMIC
Sonstige EDUCATION_OTHER
Dienstleistungen SERVICES
Finanzielle SERVICES_FINANCIAL
Online SERVICES_ONLINE
Offline SERVICES_OFFLINE
Sonstige SERVICES_OTHER
Freizeit und Unterhaltung RECREATION
Ausgehen und Essen RECREATION_ENTERTAINMENTFOOD
Sport und Fitness RECREATION_SPORTS
Kulturrelle Aktivitäten RECREATION_CULTURAL
Hobby RECREATION_HOBBY
Garten RECREATION_GARDEN
Bücher und Zeitschriften RECREATION_ONLINE
Online Entertainment RECREATION_PRINTED
Haustier RECREATION_PETS
Bücher und Zeitschriften RECREATION_OTHER
Shopping SHOPPING
Kleidung und Accesories SHOPPING_CLOTHINGACCESSORIES
Schönheitsprodukten SHOPPING_BEAUTY
Unterhaltunsgselektronik SHOPPING_ELECTRONICS
Digital Content SHOPPING_DIGITALCONTENT
Sonstige SHOPPING_OTHER
Versicherungen INSURANCE
KfZ INSURANCE_VEHICLE
Hapftflicht INSURANCE_LIABILITY
Haus INSURANCE_HOME
Kranken INSURANCE_HEALTH
Reise INSURANCE_TRAVEL
Speziel INSURANCE_SPECIAL
Vorsorge INSURANCE_PROVISIONARY
Berufsunfähihkeit INSURANCE_INCAPACITY
Sonstige INSURANCE_OTHER
Bank und Finanzen BANKFINANCE
Geldautomat Einzahlung BANKFINANCE_ATMDEPOSIT
Geldautomat Auszahlung BANKFINANCE_ATMWITHDRAWAL
Bareinzahlung BANKFINANCE_CASHDEPOSIT
Barauszahlung BANKFINANCE_CASHWITHDRAWAL
Kontotransfer BANKFINANCE_TRANSFER
Krediteinnahme BANKFINANCE_CREDITINCOME
Kreditzinsen BANKFINANCE_CREDITPAYMENT
Investment BANKFINANCE_INVESTMENT
Kreditzinsen BANKFINANCE_OTHER
Sparen SAVINGS
Lebensversicherung SAVINGS_LIFEINSURANCE
Bauspartguthaben SAVINGS_LIFEBUILDING
Spartguthaben SAVINGS_ACCOUNT
Wertpapiere SAVINGS_SECURITIES
Sonstige SAVINGS_OTHER
Einnahmen INCOME
Gehalt INCOME_SALARY
Kapitaleinkommen INCOME_INVESTMENT
Vermietung und Verpachtung INCOME_RENTAL
Rente und Pension INCOME_PENSION
Staatliche Förderung für Familie und Kinder INCOME_STATE_FAMILY
Staatliche Förderung für Bildende INCOME_STATE_EDUCATION
Sonstige INCOME_OTHER
Steuern TAXES
Sonstige OTHER
Einnahme OTHER_INCOME
Ausgabe OTHER_SPENDING
Spende OTHER_DONATION
Unterhalt OTHER_SUPPORT

Fehler und Meldungen

In der Kommunikation zwischen Mandant, BANKSapi Banks/Connect und den Providern können Fehler auftreten, die durch unterschiedlichste Konstellationen verursacht sein können. Wir sind stets bemüht, die Ursache eines Fehlers so informativ wie möglich an Sie zu transportieren, damit entsprechend schnell darauf reagiert werden kann.

Ein einfacher Anwendungsfall ist z.B., dass der Login eines Kunden zu seiner Bank nicht funktionierte. Als Fehlermeldung wird dann z.B. zurückgeliefert, dass die Benutzerkennung nicht 10-stellig war und damit die Logindaten nicht korrekt waren. Der Kunde ist so in der Lage, das „Problem“ schnell zu beheben.

HTTP-Status-Codes

Status Name Bedeutung API Behandlung
200 OK Die Anfrage wurde erfolgreich ausgeführt -
201 Created Die Anfrage wurde erfolgreich ausgeführt und das Datenobjekt wurde angelegt Location-Header auswerten und aufrufen
400 Bad Request Die Anfrage ist syntaktisch falsch Programmfehler beim Aufrufer, manuelle Intervention nötig
401 Unauthorized Der Header authorization: bearer TOKEN wurde nicht mitgeschickt Header mitschicken
403 Forbidden Der OAuth2-Token ist abgelaufen, ungültig oder der benötigte Scope fehlt Neuen Token anfordern, Scopes erweitern
404 Not found Die URL zeigt auf kein gültiges Objekt Erneuten Datenabruf starten und Relations aktualisieren
451 Unavailable for Legal Reasons Die angeforderte Ressource kann aus regulatorischen Gründen nicht zurück gegeben werden. Wird im Zuge des REG/Protects verwendet, die HTTP-Response enthält dann einen Location-Header mit der URL für den Redirect
500 Internal Server Error Das hätte nicht passieren dürfen Wir arbeiten bereits daran
504 Gateway Timeout Die gestartete Anfrage konnte nicht in der vorgegebenen Zeit beantwortet werden Anfrage kurze Zeit später wiederholen

Message-Codes

{
   "level":"ERROR",
   "code":"BA1011",
   "message":"Zugangsdaten nicht korrekt ",
   "details":"Bitte überprüfen Sie Ihre Zugangsdaten und versuchen Sie es erneut. Berücksichtigen Sie, dass Ihre Zugangsdaten nach dreimaliger Falscheingabe gesperrt werden."
}
Code Level Message Details
BA999 ERROR Interner Fehler
BA1010 ERROR Zugang gesperrt Ihre PIN für das Internet-Banking wurde dreimal falsch eingegeben. Daher haben wir Ihren Zugang aus Sicherheitsgründen vorübergehend gesperrt
BA1011 ERROR Zugangsdaten nicht korrekt Bitte überprüfen Sie Ihre Zugangsdaten und versuchen Sie es erneut. Berücksichtigen Sie, dass Ihre Zugangsdaten nach dreimaliger Falscheingabe gesperrt werden.
BA1012 ERROR Zugangsdaten unvollständig Folgende Zugangsdaten werden benötigt: Authfields 1 = Bsp. Benutzername 2 = Bsp. PIN 3 = Bsp. Key
BA1051 ERROR Bankzugang nicht erreichbar Wartungsarbeiten: Es ist eine technische Störung bei Ihrer Bank aufgetreten. Bitte aktualisieren Sie Ihren Bankzugang zu einem späteren Zeitpunkt noch einmal.
BA1052 ERROR Bankzugang nicht vollständig abrufbar
BA1060 ERROR Produkt konnte nicht aktualisiert werden
BA1062 ERROR Umsätze konnten nicht aktualisiert werden
BA1063 ERROR Depotpositionen konnten nicht aktualisiert werden
BA1100 ERROR Überweisungsdaten ungültig Bitte überprüfen Sie Ihre Eingaben. Überweisungen sind nur auf das Referenzkonto möglich.
BA1101 ERROR Ungültiges TAN Verfahren
BA1103 ERROR TAN ungültig Fehler bei der Übertragung, bzw. mTan nicht (mehr) gültig
BA1104 ERROR Überweisung nicht möglich Ueberweisungen werden nur bei Girokonten unterstützt bzw. HBCI Meldung 9390 Auftrag wegen Doppeleinreichung abgelehnt.
BA1110 INFO TAN-Eingabe nötig Bitte geben Sie die SMS-TAN ein
BA1111 INFO Die Überweisung wurde erfolgreich abgeschlossen
BA2002 INFO Es liegen Mitteilungen Ihrer Bank vor Es liegen Mitteilungen Ihrer Bank vor, bitte melden Sie sich in Ihrem Online-Banking an.