NAV Navbar
cURL

Banks/Connect Providers API

Wenn Sie sich mehr für die Kundendaten interessieren, möchten wir Ihnen unsere Schnellstartanleitung nahe legen.

Über die Banks/Connect Providers API erhalten Sie Zugriff auf eine umfassende Konfigurationsdatenbank für die durch uns unterstützten Banken und Service-Providern.

Die API ist vom Aufbau her mit den anderen BANKSapi Banks/Connect APIs vergleichbar. Das bedeutet vor allem auch, dass für diese API alles im Banks/Connect API Überblick Geschriebene gilt.

Neben allgemeinen Stammdaten wie dem Namen, der Bankengruppe, der Bankleitzahl sowie der BIC erhalten Sie auch detaillierte maschinenlesbare Informationen zu den Login-Modalitäten für Ihre Benutzer, so dass Sie das Nutzungserlebnis Ihrer Anwendung bei der Anlage von Bankzugängen optimieren können.

Ein konkretes Beispiel für diese Daten finden Sie im Abschnitt zum Provider.

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 interen 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/provider/read Es dürfen die Daten gelesen werden

Das bedeutet auch, dass es keine Relation gibt, die auf die Auflistung der Provider zeigt.

Im Gegensatz zur Banks/Connect Customer API liefert die Banks/Connect Providers API auf der obersten Ebene ein Array von Providern statt nur eines Objekts.

Die Details zu dieser Collection-Resource, welche gleichzeitig auch den zentralen Einstiegspunkt zur Banks/Connect Providers API darstellt, sind im Abschnitt Provider abrufen (mehrere) beschrieben.

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.

Das Provider-Objekt bildet die Daten eines Providers auf der Schnittstelle ab.

{
   "id":"00000000-0000-0000-0000-000000000000",
   "name":"Demo Provider",
   "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":"Der Demo Provider bietet drei Zugänge demo1/demo1, demo2/demo2 und demo3/demo3",
      "fields":[
         {
            "fieldkey":"userid",
            "label":"Demo-User",
            "secret":false,
            "hint":"demo1, demo2 oder demo3",
            "format":"|5"
         },
         {
            "fieldkey":"pin",
            "label":"Demo-Passwort",
            "secret":true,
            "hint":"demo1, demo2 oder demo3",
            "format":"|5"
         }
      ]
   }
}
Feld Typ Enthalten Beschreibung
id String Immer Eindeutiger Schlüssel für den Provider bei BANKSapi Banks/Connect
name String Immer Bezeichnung für den Provider, nicht eindeutig
group String Optional Gruppierungsbegriff für Provider. Haben mehrere Provider die gleiche Gruppe, so kann z.B. das gleiche Logo dargestellt werden
blz String Bei deutschen Banken Die Bankleitzahl der Bank war vor SEPA der Primärschlüssel für Bankinstitute in Deutschland
bic String Bei SEPA-Banken Die BIC (Business Identifier Code) der Bank
relations Array von Relations Immer Relations zeigen an, welche Operation die Provider-Ressource unterstützt
capabilities Array von Capabilities Immer Zeigt an, welche fachlichen Objekte bei dem Provider über die Banks/Connect Customer API bezogen werden können
authenticationInfo AuthenticationInfo Immer Informationen zum Anmeldeprozess beim Provider (Bei Mehr-Faktor-Authentifizierung nur der erste Faktor)

Mögliche Relations

[
  {
    "rel":"self",
    "href":"https://banksapi.io/providers/v2/00000000-0000-0000-0000-000000000000"
  },
  {
      "rel": "logo",
      "href": "https://banksapi.io/providers/v2/demo.svg"
  }
]
Relation Beschreibung
self Provider abfragen (mehrere)
logo Bankenlogo im SVG-Format

Capabilities

Die Capabilities eines Providers listen die fachlichen Objekttypen auf, die der Provider über die Banks/Connect Customer API bereitstellen kann.

Capability Beschreibung
KONTEN Der Provider unterstützt Bankkonten
KARTEN Der Provider unterstützt Kredit- bzw. Debitkarten
DEPOTS Der Provider unterstützt Depots

AuthenticationInfo

{
   "loginHint":"Die User-ID setzt sich aus Ihrer 8-stelligen Hauptkontonummer und der 2-stelligen Unterkontonummer zusammen.",
   "fields":[
      {
         "fieldkey":"userid",
         "label":"KOMnet-Key",
         "secret":false,
         "hint":"Der DEMOnet-Key ist ist auf Ihrer DEMO-EC-Karte aufgedruckt",
         "format":"|5"
      },
      {
         "fieldkey":"pin",
         "label":"Demo-Passwort",
         "secret":true,
         "hint":"demo1, demo2 oder demo3",
         "format":"|5"
      }
   ]
}

Das AuthenticationInfo-Objekt liefert detailierte Informationen zum Anmeldeprozess beim Provider aus. Mit den enthaltenen Daten ist es möglich, die Benutzungserfahrung der eigenen Anwendung bei der Provideranlage zu optimieren, was zum einen den Nerv-Faktor für den Benutzer reduzieren aber auch die eigenen Support-Aufwendungen wegen Anmeldeproblemen minimieren kann.

Feld Typ Enthalten Beschreibung
loginHint String Optional Hinweistext zum Anmeldeprozess, der für das komplette Anmeldeverfahren gilt
fields Sortiertes Array von AuthenticationFields Immer Array mit den Anmeldeparametern

AuthenticationField

{
   "fieldkey":"pin",
   "label":"Demo-Passwort",
   "secret":true,
   "hint":"demo1, demo2 oder demo3",
   "format":"|5"
}

Ein AuthenticationField beschreibt ein Datenfeld für die Anmeldedaten des Kunden beim Provider. Die Anmeldedaten werden in Form von Credentials bei der Anbindung eines Provider-Zugangs an die Banks/Connect Customer API übergeben.

Feld Typ Enthalten Beschreibung
fieldkey String Immer Name des Parameters im Credentials-Object
label String Immer Bezeichnung des Felds für die Anzeige
secret boolean Immer Gibt an, ob das Feld ein Geheimnis enthält, also z.B. verdeckt erfasst werden oder nur optional gespeichert werden sollte
hint String Optional Ein Erläuterungstext zur Anzeige neben dem Feld
format String Immer Eine Formatbeschreibung für das Eingabefeld

AuthenticationField-Format

Einige Beispiele:

|~50
Maximal 50 beliebige Zeichen
#~10
Maximal 10 Ziffern
#3-#3-#3
3 mal 3 Ziffern (123-123-123)
|5|~5
Zwischen 5 und 10 beliebige Zeichen
###|||
3 Ziffern gefolgt von 3 beliebigen Zeichen

Mit dem AuthenticationField-Format wird eine abstrakte Formatbeschreibung für das Eingabefeld geliefert. Damit lassen sich Eingabefelder bauen, die nur passende Elemente zulassen.

|
Alphanumerisches Zeichen
#
Numerisches Zeichen
-
Trennstelle
N
Genaue Anzahl des vorherigen Tokens
~N
Maxinale Anzahl des vorherigen Tokens

Provider abfragen (mehrere)

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

Zukünftig wird es möglich sein, die gelieferten Provider mittels Query-Parametern zu filtern.

Über die Abfrage der Collection-Ressource erhält man alle angebundenen sowie freigeschaltenen Provider in einem Array.

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

Rückgabe

Im Erfolgsfall kommt ein Array von Providern zurück.

Provider abfragen (einzeln)

$ curl https://banksapi.io/providers/v2/00000000-0000-0000-0000-000000000000 \
    -X GET \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'Accept: application/json'

Über diese Abfrage erhält man einen einzelnen Provider.

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

Rückgabe

Im Erfolgsfall kommt ein Provider zurück.

Zeigt die URL nicht auf einen Provider, so erhält man den HTTP-Status 404 (Not found).

Changelog

Das Changelog enthält die Höhepunkte der einzelnen Versionen der Banks/Connect Provider API. Außerdem werden neue Features der kommenden Version angerissen.

Version 2.1 (in Planung)

Diese Version befindet sich in der Umsetzung. Der Umfang kann sich also bis zum Release noch komplett verändern

Version 2.0 (aktuell)

Version 1.2

Version 1.1

Version 1.0