Overview

OpenAPI

If you are interested in API references, please check out our OpenAPI v3 documentation:

Alternatively you view the BANKS/Connect OpenAPI as a Swagger UI

Interface strategy

The APIs are created according to the REST paradigm with respect to the architectural style HATEOAS. Because of the addressing logic shifted to the server, it is possible to extend the API organically without causing breaks for the callers.

If a modification cannot be implemented in a downward-compatible manner, previous versions of the interface are provided in parallel as required over a reasonable transition period.

The interface is always called via HTTPS encryption. We currently offer JSON as a data exchange format, but if required, an extension by further formats in the future is not excluded.

Structure of interface and documentation

The interface is divided into three sub-APIs Banks/Connect Customer, Banks/Connect Providers API and Banks/Connect Auth API, which are briefly described in the following sections. For further information please refer to the comprehensive Sub-API documentation.

Central concepts of the BANKS/Connect interface like Authentication are described in the chapter of the same name within this document. Furthermore, concepts applicable to the respective sub-API are described in the respective API documentation.

Before we start

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

In addition to the explanatory texts, examples of the data in JSON format are provided where we found it helpful.

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

To show an example of the interface calls, we use the command line tool curl(1) in version 8.12.1. Unless otherwise stated, these examples can be executed directly in the command line and return data according to the success case.

Feedback

This documentation is primarily intended to be helpful. We are therefore pleased to receive your criticism and suggestions, which you can send to support@banksapi.de.

API Overview

BANKS/Connect Auth API

The protection of personal data has the highest priority at BANKSapi. Encryption and security tokens used throughout the entire process are central components of our security concept.

The BANKSapi Auth API provides functions for managing Users. Using the OAuth2 protocol, you can create tokens to enable only those functions that are necessary for the respective use case.

For comprehensive information about the BANKSapi Auth API, see the API Reference.

BANKS/Connect Customer API

{
    "1cb1126d-360d-412d-a74f-985414f57ea3": {
        "status": "VOLLSTAENDIG",
        "aktivesSicherheitsverfahren": {
            "kodierung": 1,
            "name": "Mock-TAN",
            "hinweis": "Mock-TAN"
        },
        "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
        "timeout": "2016-12-24 13:37:42",
        "bankprodukte": [],
        "sync": false,
        "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"
            }
        ],
        "messages": [{
            "level": "INFO",
            "code": "BA3010",
            "message": "SCA benötigt",
            "details": "Bitte wählen Sie eine SCA-Methode aus"
        }],
        "relations": [{
            "rel": "set_method",
            "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
        }]
    }
}

At the heart of BANKS/Connect is the BANKS/Connect Customer API, which enables your end customers to access their financial life and perform payments within your product.

Comprehensive information about the API can be found in the API Reference. So that you can get to the we have written a Quick Start Guide.

BANKS/Connect Providers API

Not all banks are the same. Therefore we provide you a comprehensive configuration database of data on the banks and service providers supported by BANKS/Connect via the BANKS/Connect Providers API

In addition to general primary data such as the name, bank group, BLZ and BIC, you also receive detailed machine-readable information on login modalities so that you can optimize the user experience of your application when creating bank accesses.

Comprehensive information about the BANKS/Connect Providers API can be found in the API Reference.

BANKS/Connect AI API

Every user is different. AI/Connect solutions translate account information for financial service providers into specific information about the customers’ finances. This allows financial service providers to offer individual financial solutions to each user. AI/Connect differs from our other APIs mainly in that it contains derived data. Through artificial intelligent this data is extrapolated and interpreted. Therefore, BANKSapi AI Endpoints first categorizes individual transactions along the dimensions of spending type, spending frequency and business partner. Later these transactions of a specific user are aggregated and used as inputs to the next level of machine learning models to categorize the user along different dimensions such as monthly budget structure, spending habits across time and across spending categories, life stages.

Comprehensive information about the BANKS/Connect Providers API can be found in the API Reference

Central Concepts

Authentication

Authentication is a very important topic, but in the end it is only a means to an end. Therefore, we avoid this topic in our Quickstart guide as far as possible without bothering you. So you can concentrate on the core of your requirement and move the details to a little later.

With BANKS/Connect there are generally three types of authentication:

Authentication as client via OAuth 2.0 client token
Authentication as user via OAuth 2.0 user token
Authentication with the bank or service provider using encrypted provider credentials

Furthermore, the BANKSapi Auth API has its own admin client with which you can create and manage users.

Which form of authentication is used when, can be found at the appropriate place in the sub-API documentation As a general rule, every inquiry is to BANKS/Connect in the context of a client. This is already sufficient for a few, e.g. for the provider query. The entire functionality is developed by BANKS/Connect using a user token and a few bank access points.

Bank

In conjunction of BANKS/Connect, we refer to the banking institutions from which we collect the data on your behalf as "bank". In the context of BANKS/Connect they are grouped together with the service providers as Providers.

The banks activated for you in BANKS/Connect can be accessed via the BANKS/Connect Providers API.

User

The unique user is also the central billing criterion. Further details are regulated by your cooperation agreement.

A user forms a bracket around the data retrieved about a person from the various banks or service providers.

With BANKS/Connect the users belong to you, the client. Access to the financial data of your users is provided via the BANKS/Connect Customer API.

With the BANKS/Connect Auth API you can manage your users.

Client

We use the term client for both, your application(s) and an "admin-client" which allows you to manage your users. From our point of view a client is therefore a set of access data for BANKS/Connect.

With a client ID, client tokens can be obtained via the BANKS/Connect Auth API via OAuth2. These tokens can then be used to access the other functions in the BANKS/Connect Customer API or BANKS/Connect Providers API.

Correlation ID

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

The Correlation-ID is used to track requests across all systems. The Correlation-ID can be passed to the BANKSapi APIs as HTTP header X-Correlation-ID.

If it is not passed, the BANKSapi APIs generate their own ID.

In any case, the value is also returned as the HTTP response header X Correlation ID.

CORS

More information about CORS on Wikipedia.

BANKS/Connect supports Cross Origin Resource Sharing (CORS). This makes it possible to call our APIs directly from the browser, for example in a single-page app.

Errors

Unfortunately, mistakes cannot always be avoided, but they can be treated. Especially with external dependencies such as banks and service providers, which are connected via BANKS/Connect, we have no influence on their (usually very high) availability.

For that reason we provide message objects in the BANKS/Connect Customer API that contain a code, a generic error description suitable for displaying to your end customer, as well as a more detailed message for your internal error handling.

For errors that are more technical in nature we work with the whole range of HTTP status codes. This encompasses errors such as syntax errors, bad authentications, parallel requests, networking problems and the like.

For details about the possible message objects and the HTTP status codes, see the Errors and Messages section in the BANKS/Connect Customer API documentation.

HATEOAS

More information about HATEOAS on Wikipedia.

HATEOAS is short for "Hypermedia as the Engine of Application State". Here the client of a REST interface navigates only to URLs that are provided by the server and that are reachable regarding the "current context". These URLs are identified by names that convey semantic information about the URL. Accordingly, there are only a few fixed URLs that must be known to the calling party.

These URLs are communicated to the caller in the form of Relations in the current document or in the HTTP response header "Location".

Timestamp

for example:
2016-09-03 04:27:00
2019-12-04 13:37:00
2010-01-01 22:03:54

Timestamps are always output without time zone information. They correspond to the format ISO 8601 in the form YYYY-MM-DD hh:mm:ss. Data is to be interpreted according to the time zone Europe/Berlin.

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"
  }
}

The BANKS/Connect interfaces use the JSON (JavaScript Object Notation) for data exchange. Attributes without values are not delivered as "null", but "missing" in the document. We deliver and expect date values according to ISO 8601 formatted as string.

In the case of exchanged JSON documents, it should also be noted that every consumer must ignore unknown attributes. This applies in particular to enumeration types whose extension is regarded as downwards compatible.

When JSON is delivered, the Content-Type header "Content-Type: application/json" must always be included. With "null" values it does not matter whether fields are sent as "null" or not at all, unless they are mandatory fields.

Client

There is also a demo client, which is used for example in our Quick Start Guide.

This is you or the company that has concluded a cooperation agreement with us. The client includes Clients and Users.

As a client you have access to our first-class support and benefits from the permanent development of BANKS/Connect. And of course you will see more data than just our demo bank.

If you are interested, please contact with us.

OAuth2

All calls to the BANKSapi interfaces must be made with a valid OAuth2 token. For some operations, a client token (without a specific user) is sufficient.

Details on user and client management are described in the BANKSapi Auth API.

Token types

BANKSapi is working in a 2-legged OAuth2 setting. This means you will be supplied a refresh token. With this, you will have to fetch a fresh access token for almost all calls within our APIs.

The refresh token (actually a set of Basic Auth credentials) is valid for a long time and used exclusively to fetch new access tokens. It is a Basic token, you will have to authenticate with Authorization: Basic <base64EncodedCredentials>

An access token has a validity of 24hrs, after which you will need to create a new token. Depending on your design and use case, we recommend that you either keep track of the validity and fetch a new token in time, or you fetch a new access token per business transaction, in which case you can go without persistence of the token. You will have to authenticate with Authorization: Bearer <bearerToken>

Token levels

Access tokens can be on client or on user level. If nothing is explicitly documented in the corresponding use case, the call with a unique user is assumed. Bear in mind you can't do calls like e.g. add a new bank access on a client (i.e. management) level as these would be available for all users, but only on user level. But a user can't create new users, this must be done on a management level.

Token usage

When calling, the token must be transferred according to the OAuth2 standard in the header "Authorization: Bearer ...". If this header is missing or the token is invalid, the interface responds with the HTTP status code 401 (Unauthorized). If the token does not contain the necessary authorizations, the HTTP status code 403 (Forbidden) is reported.

Provider

As providers we refer to the connected banks and service providers in a very abstract way. The connection is made using a wide variety of technologies and at the end the collected data will be converted into a uniform format for you.

Relation

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

A relation corresponds to an application or business transaction that is supported by the surrounding data object. For every application and business transaction, there is a separate documentation that describes both the call and the return or the possible alternative response scenarios in the in detail.

Each relation consists of a keyword (e.g. "get_kontoumsaetze") and a URL. A client that is interested in the transactions of a bank product calls the specified URL with the HTTP verb specified in the documentation.

REST

Recommended reading: Roy Fielding: REST APIs must be hypertext-driven

Our APIs are implemented as REST patterns (Representational State Transfer). Consequently, they are usable via the HTTP protocol and use more HTTP verbs as GET and POST only.

Furthermore, we strive to meet the requirements of the REST inventor Roy Fielding for a REST API by reflecting on the HATEOAS architectural style to do justice to this.

Service Provider

Service providers are connected financial institutions that are not a bank. In the context of BANKS/Connect they are also more generally referred to as Provider.

Information about service providers can be obtained through the BANKS/Connect Providers API.

Language

The German banking landscape is very German-speaking, and therefore one lands in detail quite fast in the search for an appropriate translation in a dead end (or half-silk translation). However, as engineers it is also obvious to us to "program in English".

In order to get out of this dilemma, we decided to leave technical terms from the banking environment in German and to use all other terms from English to import. To avoid a too heavy "Denglish", we have decided to import German as well.

Otherwise BANKS/Connect is mainly programmed in Java and some other JVM languages.

Encryption

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

In order for BANKS/Connect to access the data of the banks, the access data must be available. Since this information is extremely sensitive, the access data is protected by strong asymmetric encryption. You will receive an RSA public key at the beginning of the cooperation. The secret counterpart lies with us. Thus the access data can be encrypted but not decrypted.

The procedure is described in detail in the documentation for the BANKS/Connect Customer API.

We check the quality of our TLS configuration with the tool Qualys SSL Labs.

Otherwise, of course, the transport route is encrypted using TLS (HTTPS).

Versioning

Semantic versioning even has its own semantically versioned manifest.

The interfaces are semantically versioned (X.Y, e.g. 2.0). If the Y value increases, a correctly implemented Client will continue to work without restrictions, but of course does not use the new functions. In the event of a change of X, the client must be adapted, since the change was not backward compatible. Previous major versions (X) will be is still supported for a while after the introduction of the incompatible subsequent versions, if this makes sense from a technical point of view.

Quick Start

What We're Going to Do

We'd like to guide you through the first steps you're probably going to take with our interface: You will probably want to create a first user and add a bank access for them. This will give you a good first impression on what data is available through our API, how to interact with it in general as well as some of the concepts we're using.

For starters, bear in mind we're basing our authentication on the (2-legged) OAuth2 protocol. Therefore, you will be supplied with a "refresh token" in order to fetch a new access token.

Create a Client Token

POST /auth/oauth2/token HTTP/1.1
Host: banksapi.io
Authorization: Basic c29<...>U=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

The first step will be to fetch a fresh access token on management level in order to be able to create a new user. For this, we will use the Create Token call. You can see the call on the right.

In order to adhere to the OAuth2 standard, this call is the only one in the API that uses content typeapplication/x-www-form-urlencoded for the payload.

The only required field of this call is grant_type, which we fill with client_credentials, because we want to create a token on management (i.e. client) level. The scope parameter can be left out, in which case we will receive the full scope. If at a later point we want to limit this for security or design reasons, we can add the scopes that we'd like this token to have.

{
    "scope": "http://banksapi.io/customer/read http://banksapi.io/provider/read http://banksapi.io/customer/modify http://banksapi.io/customer/ueberweisung auth/tenants/users/create",
    "tenant": "demotenant",
    "client": "demoTenantClient",
    "additionalData": {},
    "validTo": "2020-10-08 09:16:03",
    "access_token": "edbc0a13-19c3-4a10-ac96-bbfe900a0a06",
    "token_type": "Bearer"
}

The response we can see on the right: Together with some additional data, we receive an access_token of type Bearer, valid for 24hrs, for our tenant demotenant. Make note of the tenant name, we'll need it in the next call.

Create a User

With the new token we've just created, we will now create our first user.

POST /auth/mgmt/v1/tenants/demotenant/users HTTP/1.1
Host: banksapi.io
Content-Type: application/json
Authorization: Bearer edbc0a13-19c3-4a10-ac96-bbfe900a0a06

{
    "username": "user1",
    "password": "password1"
}

For this, we will use the Create User call. You can see the call on the right. The required fields are username and password, so we will set these values.

The Content-Type is application/json in this (as in every other) case, and we use the new Bearer token as Authorization. As a last parameter, note the tenant id in the URL, because we're creating a user for that (your) tenant. This is the same tenant that we have received in the response of the previous call.

The response will be an HTTP 201 Created success status response with no body, indicating the user has been created.

Create a User Token

POST /auth/oauth2/token HTTP/1.1
Host: banksapi.io
Authorization: Basic c29<...>U=
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=user1&password=password1

Now we need to fetch a fresh access token on the user level. As in the first call, we will use the Create Token call, but with different parameters. You can see the call on the right.

This time, as we're fetching a token on user level, we are using grant_type=password, not client_credentials. This is according to the OAuth2 password grant. Of course, for username and password we're using the values that we have specified in the previous call.

{
    "scope": "http://banksapi.io/provider/read http://banksapi.io/customer/read http://banksapi.io/customer/modify http://banksapi.io/customer/ueberweisung auth/tenants/users/create",
    "tenant": "demotenant",
    "client": "demoTenantClient",
    "user": "0049e4d6-824f-4839-823d-7a2ad4660c4e",
    "additionalData": {
        "username": "user1"
    },
    "validTo": "2020-10-08 10:56:47",
    "access_token": "0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235",
    "token_type": "Bearer"
}

As a response, we receive a similar JSON object as before. This time, as additionalData we receive the username to indicate it's a token on user level.

That's it for the Auth API, all subsequent calls we'll make with the Customer API with our new Bearer token on user (i.e. customer) level.

Create Bank Access

With the new token, we can access the full range of customer interactions. But as the user has not added a bank access yet, our options are somewhat limited. So next we're going to add a bank access for that user.

Now it gets tricky: For this operation, you will need to differentiate whether you are a regulated or a non-regulated customer. Non-regulated customers will not be allowed to receive the credentials to a provider (e.g. a bank) on their own domain. These are considered sensitive payment information and the handling of this is regulated by the authorities. Therefore, they will have to redirect the customer to us, the customer will select a bank and enter sensitive payment information on a BANKSapi frontend (REG/Protect) and complete the authorization flow, then the customer is redirected back to you.

POST /customer/v2/bankzugaenge HTTP/1.1
Host: banksapi.io
Content-Type: application/json
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

{
    "629e4510-5331-47d4-9bad-8902039ff762": {
    }
}

For adding a new bank access, we will use the Add Bank Access call. You can see the call on the right.

No surprises in the headers, Content-Type is application/json as with all the calls in the Customer API, Authorization is our new Bearer token on user level.

The payload requires a bit of explanation: A bank access is referenced by a UUID. Because it might be necessary for you to query the bank access object without any response from BANKSapi, this UUID needs to be chosen and set by you. Therefore, the UUID visible in the body is a new UUID that you need to create with a suitable UUID generator.

It is very advisable except in some very rare cases to use a a completely new UUID, rather than any UUID corresponding to the user. Don't be tempted to use the user UUID that was returned in the previous call. Although it looks simple, it will lead to problems when you add the second bank access for this user, because what will it be referenced by?

The banks access object (referenced by the UUID) is empty in this case as in {}. The reason is that in the REG/Protect case, you can neither send us a credentials object (this would require a regulatory license to handle sensitive payment data) nor a provider ID (the user will be able to select the bank in the REG/Protect wizard). The last optional flag, sync, indicates whether the bank access should be persisted on BANKSapi end. For REG/Protect clients, this must be true (which is also the default value) and can therefore be omitted.

HTTP/1.1 451 Unavailable For Legal Reasons
Location: https://banksapi.io/customer/v2/webform?session=ef2fdd3b-a087-447b-843c-670325d003f4&useCase=CREATE_ACCOUNT

The result will be an HTTP 451 Unavailable for Legal Reasons status response with no body. Admittedly used rarely, for this case it's the perfect response code, indicating you are not allowed to create a bank access yourself (for legal reasons) but will have to have us do it for you.

In the background, we have created the corresponding frontend session already and are prepared to have the user come to our domain for completing the process. The URL of our frontend will be delivered through the Location respone header.

In order for us to know where to redirect the user after completion, you will need to add a callbackUrl query parameter to the URL before redirecting the user there, as indicated in the docs on Adding and authenticating bank access. This callback URL needs to be URL encoded

In our example, we would therefore redirect the user to https://banksapi.io/customer/v2/webform?session=ef2fdd3b-a087-447b-843c-670325d003f4&useCase=CREATE_ACCOUNT&callbackUrl=http%3A%2F%2Fexample.com (or, for the first tests, open it in the browser ourself).

Now you can relax for a bit, the user will be completing the process on our frontend:

Step	Screenshot
Accepting our T&Cs (only once per user, for the second bank access this step will be omitted)
Selecting a provider
Entering the credentials
Confirming accounts
Being redirected back to you

The user will be redirect back to the URL you specified previously in callbackUrl, together with a query parameter baReentry indicating the result (normally ACCOUNT_CREATED).

That's it, the account has been created. In the background, we were already communicating with the user's bank or provider, fetching and analyzing data. You can now query the data, continuing with the next requests.

Query Bank Access

GET /customer/v2/bankzugaenge HTTP/1.1
Host: banksapi.io
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

Next up, let's check if the bank access is there and what options we have to go on. We'll use the Get Bank Accesses call, so query all bank accesses of that user instead of a specific one referenced by the ID you chose earlier. You can see the call on the right.

{
    "629e4510-5331-47d4-9bad-8902039ff762": {
        "id": "629e4510-5331-47d4-9bad-8902039ff762",
        "providerId": "00000000-0000-0000-0000-000000000000",
        "aktualisierungszeitpunkt": "2020-10-07 13:26:13",
        "tanMedien": [
            {
                "name": "Mobil",
                "medienklasse": "MOBIL",
                "gueltigVon": "2020-10-07 13:26:13",
                "gueltigBis": "2020-10-07 13:26:13"
            }
        ],
        "sicherheitsverfahren": [
            {
                "kodierung": 902,
                "name": "mockPhotoTAN",
                "hinweis": "Scanne das Bild. Das Ergebnis ist \"8534842\""
            },
            {
                "kodierung": 1,
                "name": "mockTAN",
                "hinweis": "Gib eine durch 2 teilbare Zahl ein"
            }
        ],
        "aktivesSicherheitsverfahren": {
            "kodierung": 1,
            "name": "mockTAN",
            "hinweis": "Gib eine durch 2 teilbare Zahl ein"
        },
        "relations": [
            {
                "rel": "self",
                "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762"
            },
            {
                "rel": "delete_bankzugang",
                "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762"
            },
            {
                "rel": "get_issues",
                "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/issues"
            }
        ],
        "status": "VOLLSTAENDIG",
        "bankprodukte": [
            {
                "id": "DE00123456789012345678",
                "status": "VOLLSTAENDIG",
                "bezeichnung": "Girokonto",
                "kategorie": "GIROKONTO",
                "saldo": 2145.78,
                "aktualisierungszeitpunkt": "2020-10-07 13:26:13",
                "saldoDatum": "2020-10-07 00:00:00",
                "waehrung": "EUR",
                "kontonummer": "9012345678",
                "iban": "DE00123456789012345678",
                "bic": "XXX12345678",
                "blz": "12345678",
                "kreditinstitut": "Demo Provider",
                "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/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678"
                    },
                    {
                        "rel": "get_kontoumsaetze",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze"
                    },
                    {
                        "rel": "get_kontoumsaetze_tagged",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=true"
                    },
                    {
                        "rel": "get_kontoumsaetze_insurances",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=insurances"
                    },
                    {
                        "rel": "get_kontoumsaetze_business_partners",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=business-partners"
                    }
                ],
                "messages": [],
                "ueberziehungslimit": 3000.0,
                "verfuegungsrahmen": 2045.78,
                "verfuegterBetrag": 100.0
            },
            {...}
        ],
        "sync": true
    }
}

As a response, the server will return the (now filled) bank access object we created earlier. Find a sample response on the right.

Wow, there's is a lot going on, so let's dissect:

Top level, we have an object representing a collection of all bank accesses of that user. In this case, we have yet only created one, so the collection has one entry with the key 629e4510-5331-47d4-9bad-8902039ff762, which is the UUID we chose earlier for the bank access.

In that object, representing this specific bank access, we have some attributes: There's the id again, no surprise there, there is a providerId, which we could use to query some info on the bank the user chose through a Get Provider call, there is an aktualisierungszeitpunkt which represents the timestamp of the last update (in which we fetched fresh data from the bank), there is some meta info on SCA (sicherheitsverfahren and aktivesSicherheitsverfahren) which is probably not interesting for you right now, a status flag which should be VOLLSTAENDIG by now and an indication of the sync flag, i.e. whether this bank access is persisted on BANKSapi side, can be queried by you any time in the future and will be refreshed from the bank up to four times a day.

Next, there is an array relations, that contains actions that you can take with this bank access and the corresponding URL. See our chapter on HATEOAS for more info on this design.

Then there is another array, bankprodukte. Remember, under one bank access can be multiple bank products, as you can have several accounts with a bank that you can all access with the same set of credentials.

{
    "id": "DE00123456789012345678",
    "status": "VOLLSTAENDIG",
    "bezeichnung": "Girokonto",
    "kategorie": "GIROKONTO",
    "saldo": 2145.78,
    "aktualisierungszeitpunkt": "2020-10-07 13:26:13",
    "saldoDatum": "2020-10-07 00:00:00",
    "waehrung": "EUR",
    "kontonummer": "9012345678",
    "iban": "DE00123456789012345678",
    "bic": "XXX12345678",
    "blz": "12345678",
    "kreditinstitut": "Demo Provider",
    "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/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678"
        },
        {
            "rel": "get_kontoumsaetze",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze"
        },
        {
            "rel": "get_kontoumsaetze_tagged",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=true"
        },
        {
            "rel": "get_kontoumsaetze_insurances",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=insurances"
        },
        {
            "rel": "get_kontoumsaetze_business_partners",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=business-partners"
        }
    ],
    "messages": [],
    "ueberziehungslimit": 3000.0,
    "verfuegungsrahmen": 2045.78,
    "verfuegterBetrag": 100.0
}

This array contains (probably multiple) bank products. Let's dissect also one of the bank products, e.g. the one on the right.

Again, there is an id, this time of this specific product, there is a status which is the same as for the bank access. Again there is a lot of meta info (see the corresponding Bank Product Schema for a complete list). And there are some relations in the relations array, indicating which actions you can take next:

Relation	Explanation	Corresponding call
`self`	Query only this bank product	Get Bank Product
`start_ueberweisung`	Initiate a wire transfer from this account. This relation is only returned for accounts from which BANKSapi supports transfers, mainly payment accounts	Create Transfer
`get_kontoumsaetze`	Get turnovers for this product	Get Transactions
`get_kontoumsaetze_tagged`	Get turnovers for this product, tagged (categorized)	Get Transactions with the "categories" as tag query param
`get_kontoumsaetze_insurances`	Get turnovers for this product, tagged with insurance tags (only the ones that are insurance turnovers of course)	Get Transactions with the "insurance-types" as tag query param
`get_kontoumsaetze_business_partners`	Get turnovers for this product, tagged with normalized business partners	Get Transactions with the "business-partners" as tag query param

We're interested in the turnovers of this account, so we'll fetch those next, using the get_kontoumsaetze relation.

Query Turnovers

GET /customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze HTTP/1.1
Host: banksapi.io
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

The turnovers we can query with a bank-product-specic URL, given to us through the get_kontoumsaetze relation earlier. We'll use that URL with the Get Transactions call. You can see the call on the right.

[
    {
        "id": "1975f080-0001-b4f7-727b-aec310895541",
        "betrag": -100.0,
        "verwendungszweck": "GA NR00006110 BLZ70020270 3 07.02/14.29UHR MÜNCHEN,KARD EUR 100,00 ENTGELT 0,00 Ref. 3QL15041A1357856/83343",
        "buchungstext": "",
        "buchungsdatum": "2020-10-05 00:00:00",
        "wertstellungsdatum": "2020-10-02 00:00:00",
        "gegenkontoInhaber": "",
        "gegenkontoIban": "",
        "gegenkontoBic": "",
        "primanotaNummer": "0",
        "hash": "1b4f7727-baec-3107-9554-1cf472933ccf"
    },
    {...}
]

As a result, we're greeted with an array of turnovers. For details on the attributes, head over to the Transaction Schema

Force a Refresh of Data From the Bank

POST /customer/v2/bankzugaenge?refresh=true HTTP/1.1
Host: banksapi.io
Content-Type: application/json
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

{
    "629e4510-5331-47d4-9bad-8902039ff762": {
    }
}

Although we refresh synced bank accesses up to four times a day, in some cases, you might want to force BANKSapi to fetch fresh data from the provider. It is therefore a good idea to implement some kind of refresh button for the user, which in turn should force an actual refresh from the bank and not just return cached data from BANKSapi.

In order to force BANKSapi to fetch fresh data, we will use the same call that we used when creating a bank access, only this time we are using the UUID of the bank access we want to refresh, and add a refresh=true as a query parameter, as in the example on the right.

This time, this will be confirmed by a 201 Created HTTP status, indicating the refresh has been triggered. You can now query the bank access again and should see fresh data.

At some point, the user consent we create implicitly with the previous calls will run out. Bear in mind, this is the consent the users gave to us to fetch data from the bank, so the bank will honour this consent and we have no choice but to renew it. Usually, under PSD2, the consent is valid for 180 days, although some products from some banks require more frequent renewals (some even for every refresh) and there are always things that can prevent us from fetching fresh data from the bank, e.g. a locked account or the user manually removing the consent.

A renewal of consent is a fancy way of saying the user has to enter a TAN or going through a similar process with a TAN-less SCA method such as AppTAN.

We will indicate the necessity of SCA renewal with a start_sca relation. In this case, we might have been able to refresh some but not all bank products, or none at all, and will remain in this state until the user refreshes their consent. In the meantime, you will still be able to query data from BANKSapi, but it will not be the most recent but the last state that we were still be able to fetch.

{
    "rel": "start_sca",
    "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/consent/59f168d6-3a45-4db5-bcd5-94f29d64bbfa"
},

Therefore, if you encounter a start_sca relation, you will have to have the user go through the SCA process again, similar to when they added the bank access, but without them having to chose the provider or enter their credentials. In this case, it's just the SCA process they will have to go through

HTTP/1.1 451 Unavailable For Legal Reasons
Location: https://banksapi.io/customer/v2/webform?session=c2a71efd-71b0-47ea-951a-2abcea1c8578&useCase=AUTHENTICATE_ACCOUNT

So we realize the consent has expired and the user has to complete the SCA process, because we received a start_sca relation with the bank access. Now we proceed as documented in Operations with SCA and POST to the start_sca relation. In response, we will receive a response like the one on the right. Now, the HTTP 451 Unavailable for Legal Reasons status code seems familiar, doesn't it? Now, we follow the same procedure as before while Creating the bank access, adding a callbackUrl and sending the user over to BANKSapi. When the user returns, the bank access should be fully accessible again and start_sca gone.

Query Issues

The bank access, bank products and transactions we return are in a so-called “stable” state, meaning that this is the best data that is available to us. We update this stable state only if a refresh from a bank is successful. However, if fetching a bank access yields any issues, e.g. when the user has changed their login credentials without our knowledge, the stable state is unchanged because we do not want to taint the data with “bad” new data, potentially removing transactions from the storage you are relying on because we do not “see“ them.

Inevitably, there will be an account that is not refreshed any more. It is therefore a good practice to implement the call to fetch potentials issues as well. Best case, the list of messages is returned empty and there is nothing to do.

{
    "rel": "get_issues",
    "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/issues"
}

To fetch bank access issues, we will use get_issues relation that is returned as part of the bank access. We will receive what will look like a subset of a bank access, but in this case it is not in the "stable" state but in a state we call "tentative", i.e. containing not the best data available to us, but the latest state, and thus any issues that might have arisen during fetching updated data from the bank.

{
    "id": "629e4510-5331-47d4-9bad-8902039ff762",
    "tanMedien": [],
    "providerId": "00000000-0000-0000-0000-000000000000",
    "sicherheitsverfahren": [],
    "aktualisierungszeitpunkt": "2020-10-07 13:26:13",
    "messages": [{
        "code": "BA1011",
        "level": "ERROR",
        "details": "Ungültige Zugangsdaten",
        "message": "Zugangsdaten nicht korrekt"
    }],
    "relations": [{
        "rel": "delete_bankzugang",
        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762"
    }]
}

For all errors and issues that can arise, head over to the docs on Message codes.

Where to Go From Here

You've done the first steps with our API - why not explore a bit yourself? HATEOAS makes it very easy to start exploring the API through relations - or you can go on reading this documentation.

Some hints on what to do next:

You can try to add real bank access and see what real-world data looks like
You could implement features for brokerage accounts
You can explore our AI/Connect features to learn more about the user

EBICS

Overview

This guide is intended to help you integrate EBICS bank accesses via our API. EBICS (Electronic Banking Internet Communication Standard) is a widely adopted banking transmission protocol in several European countries, particularly in Germany, France, and Switzerland. It is primarily used by corporate clients and financial institutions to facilitate the secure transfer of payment and financial transaction data over the internet.

Designed for high-volume transactions, EBICS offers a robust and secure method for businesses to communicate with their banks. It standardizes the electronic exchange of banking business data and ensures secure, direct communication between clients and banks.

Remember, we're using the OAuth2 protocol for authentication, and you will be supplied with a "refresh token" to fetch a new access token. It's advised to read about OAuth2 protocol in our documentation if unfamiliar, then proceed with the steps mentioned here.

Create an EBICS Account

The user should create an EBICS account with their bank and receive credentials: Host-ID, Host-URL, Partner-ID, and User-ID. The account should have:

Grants for C53 (preferred) or STA for transaction retrieval
AuthorizationLevel="T" for all upload business transactions: CCT (SEPA Credit Transfer), CDB (SEPA Direct Debit for companies), CDD (SEPA Direct Debit for end users)

These need to be set by account (by bank product) usually.

Call the Add Bank Access Endpoint

POST /customer/v2/bankzugaenge HTTP/1.1
Host: banksapi.io
Content-Type: application/json
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

{
    "629e4510-5331-47d4-9bad-8902039ff762": {
        "ebics": true
    }
}

Call the endpoint at Add Bank Access with ebics: true.

HTTP/1.1 451 Unavailable For Legal Reasons
Location: https://banksapi.io/customer/v2/webform?session=ef2fdd3b-a087-447b-843c-670325d003f4&useCase=CREATE_ACCOUNT

This will result in a HTTP 451 Code, with a location header. Follow the instructions similar to Create Bank Access.

Redirect the User

Add a callbackUrl to the Location-Header and redirect the user to enter their EBICS credentials.

Step	Screenshot
Entering the EBICS credentials
Receiving the ini letter
The resulting ini letter that needs to be signed

Initialization Letter Generation

BANKSapi has at this point generated an initialization letter containing the hash of the keys generated. The user should download this letter, and the keys will not leave BANKSapi’s servers.

Verify the Bank Access

{
    "id": "189d22f6-2d1a-4fa3-a22e-8db0d7e47453",
    "providerId": "00000000-0000-0000-0000-000000000000",
    "aktualisierungszeitpunkt": "2023-09-14 13:40:20",
    "messages": [{
        "level": "INFO",
        "code": "BA2004",
        "message": "Bankzugang noch nicht freigeschaltet",
        "details": "Der EBICS Zugang ist noch nicht freigeschaltet."
    }],
    "tanMedien": [],
    "sicherheitsverfahren": [],
    "challenge": {
        "name": "EBICS Initialisierungsbrief",
        "content": {
            "instructions": "Bitte senden Sie den Initialisierungsbrief unterschrieben an die Bank.",
            "PDF": "data:application/pdf;base64,JVBERi0xLjQN ... 3MzUNCiUlRU9G"
        },
        "decoupled": false,
        "redirect": false
    },
    "relations": [{
            "rel": "self",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/189d22f6-2d1a-4fa3-a22e-8db0d7e47453"
        },
        {
            "rel": "refresh_bankzugang",
            "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
            "rel": "delete_bankzugang",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/189d22f6-2d1a-4fa3-a22e-8db0d7e47453"
        },
        {
            "rel": "get_issues",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/189d22f6-2d1a-4fa3-a22e-8db0d7e47453/issues"
        },
        {
            "rel": "get_challenge_pdf",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/189d22f6-2d1a-4fa3-a22e-8db0d7e47453/challenge/pdf"
        }
    ],
    "type": "EBICS",
    "status": "VOLLSTAENDIG",
    "bankprodukte": [],
    "sync": true
}

After redirection to the callbackUrl and the user completing the process and returning to your website, the bank access should be in a VOLLSTAENDIG state with a BA2004 message indicating that bank access is not yet activated. The ini letter can be retrieved by you as well:

By the base64 encoded string in challenge.content.PDF
By the relation get_challenge_pdf which makes the PDF available for download through Content-Disposition: attachment;

User Sends Initialization Letter to the Bank

The user needs to print, sign, and send the letter to the bank. Some banks might accept electronic versions. Once the bank confirms the hash and activates the account, BANKSapi will be able to fetch data.

If the user has permissions beyond T-grants, BANKSapi will delete the set of keys, resulting in a BA1020 message. The EBICS user needs to be re-created with the correct credentials, and the process needs to be reiterated.

Successful Connection

If all steps are successful, and the bank has confirmed the hash, the status will be VOLLSTAENDIG with an ebics: true flag, and all endpoints for fetching the bank access, transactions, and payments will be available for this account.

Comparison to Non-EBICS Bank Accesses

To summarize, the difference to non-EBICS bank accesses is primarily a more heavy interaction by the user with their bank. Primarily, the EBICS account (T-User) needs to already have been created at the time the user attempts to add the EBICS bank access / is redirected to our REG/Protect frontend. Afterwards, the bank access is not immediately available, but needs to be confirmed by the bank after the REG/Protect process.

Caveats

Initializing multiple times

Depending on the bank, an EBICS access cannot be initialized several times, but must be reset by the bank.

Balance Retrieval Limitation

In EBICS, there's no way to get the balance of an account without fetching its transactions. There might not be any transactions, i.e. also no balance, because of the historical transaction limitation

Historical Transaction Limitation

With EBICS, we might not be able to get transactions that are older than when the bank access was created.

Transaction History Range

Currently, we will fetch transactions up to 90 days back.

BANKS/Connect Auth API

If you are more interested in the customer data, we would like to recommend our quick start guide.

The BANKSapi Auth API provides functions for managing Users. Using the OAuth2 protocol you can create tokens to enable only those functions that are necessary for the respective use case.

The API is similar in structure to the other BANKS/Connect APIs. That means above all, that everything written in the BANKS/Connect API Overview applies to this API.

The use of this API is a basic requirement for the connection of all APIs offered by BANKSapi.

BANKS/Connect Customer API

This API forms the core of BANKS/Connect. This allows your end customers to access your financial life and make transactions within your product.

The core element of the API is the Customer, which you can use to Relations dive in detail into the data that can be determined about your customer can.

This document contains the API Reference. But before you get into the details. you may use the API with our Quick Start Guide directly and without any further hurdles.

Concepts

REG/Protect (redirect solution)

The BANKSapi "REG/Protect-as-a-Service", allows users to perform authorization completely in a frontend provided by BANKSapi. The account information is stored by BANKSapi. The sensitive payment data is transferred directly from the end user to the BANKSapi systems, processed by BANKSapi and stored by BANKSapi. It is not possible to read the sensitive payment data from BANKSapi.

In addition to regulated clients, as a non-regulated client you can also use BANKSapi REG/Protect to extend your range of services to include use cases based on the use of an account information service (KID) and a payment initiation service (ZAD), but without your own ZAD license or KID registration. Since 2018, BaFin has been obliged to register/license payment accounts if online banking is used to access payment account data and trigger payments.

Background update

A background update can be requested when adding a bank access. The bank access and its products and transactions are then queried and updated up to four times (4x) a day. The amount of background updates regresses over time if the user activity declines.

Notifications (Webhooks)

If the background update for a bank access is active, a webhook can be specified. In case of new transactions during an update, an external URL can be called with a reference to the bank access.

Notifications are not guaranteed: If the endpoint is not available, the HTTP call is stored in a queue and the system tries to execute it several times until the remote server on your side can accept the call. However, if this is not the case even after a few minutes, the notification will be discarded.

You can use the sequential integer sequence number serial to check whether there have been gaps or failures since the last notification.

Strong customer authentication

A Strong Customer Authentication (SCA) ensures that accesses to a user's payment account online and initiations of electronic payment transactions are performed with multi-factor authentication. An SCA uses two out of three factors of:

Knowledge
Possession
Inherence

We differentiate between TAN (i.e. embedded) and TAN-less (i.e. decoupled) security procedures.

TAN procedures such as smsTAN, eTAN, chipTAN, photoTAN, pushTAN etc. are most frequently used.

TAN-less procedures include apps provided by the banks to the end customers that can be used to just approve of activities. In this case the phone itself is the possession factor. For Submit SCA Authentication Data, this means that an empty object can be submitted to indicate the user indicated that he meanwhile confirmed the activity, e.g. through the bank app.

There is also the case of a redirect SCA, which is a special type of a decoupled SCA, which redirects from your application directly to a bank interface, where the user will authenticate himself. This authentication can include a TAN, but since the user is on the bank interface it is still considered a decoupled procedure from your application's or BANKSapi's point of view.

Please note that not all safety procedures are supported by FinTS/HBCI.

TAN medium

The TAN medium is used to generate (e.g. chipTAN) or receive (e.g. smsTAN) TANs. BANKSapi will provide you with a list of TAN Media, while an SCA is in progress and if an SCA demands it.

Here are a few examples of TAN procedures and TAN media:

TAN procedure	Media class	Name
mobileTAN (mTAN)	Mobile phone	+49-1111-1111111
smsTAN	Mobile	+49-1111-111111
chipTAN	Generator with EC Card	Sample Bank Card 1234567890
Sm@rtTAN	Generator with bank card	Sample bank card 1234567890
e-TAN	Generator	Generator
photoTAN	App or generator	Phone of User X
PushTAN / appTAN	App	Phone of User X

Customer IP Address

Post-PSD2, we can do interactive actions with the bank only if supplying the IP address of the user. In order to support manual refreshs, adding bank access, and other actions with user interaction, we need to indicate that the user is active (interactive calls). As proof of user interaction, the banks require the current IP address of the user.

In order to supply this to the banks, as we do not have direct interaction with the user, you will have to supply this IP address. You may supply it at any time (we will not persist this and ignore if not needed), but should supply when doing the following requests:

add_bankzugang
start_ueberweisung
delete_bankzugang
delete_bankzugaenge
start_sca

The header should be sent as a standard HTTP request header in the following format:

Customer-Ip-Address: 123.234.123.234

REG/Protect

The REG/Protect redirect solution provides a web frontend for adding bank accesses and triggering payments and therefore handling complex interactions with the provider for you.

Context info when returning to your app

The return of the user can happen for different reasons. The reason is provided in the query parameter baReentry.

Type of return	Example	Value for baReentry
Process successfully completed		FINISHED
User does not agree with terms and conditions		LEGAL_NOT_ACCEPTED
Termination of the process	User terminated process	USER_CANCELLED
Unexpected HTTP Response	Unhandled and unexpected backend error	BACKEND_ERROR
Access data incorrectly entered three times		INVALID_CREDENTIALS
TAN incorrectly entered three times		INVALID_TAN
General error	Guard prevents mask access; possible manipulation attempt; various errors	ERROR
No accounts found for bank transfer	No accounts or no accounts suitable for bank transfer were found when the bank transfer was started	NO_ACCOUNTS
Account successfully created		ACCOUNT_CREATED
Error creating initial letter		ERROR_CREATING_INI_LETTER
Initial letter created		INI_LETTER_CREATED
Invalid bank transfer data		INVALID_BANK_TRANSFER_DATA
Invalid callback URL		INVALID_CALLBACK_URL
No callback URL provided		NO_CALL_BACK_URL
No security method provided		NO_SECURITY_METHOD
Session timed out		SESSION_TIMEOUT

Adding and authenticating a bank access

$ 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

When you create a bank access as a non-regulated client, you will receive the URL for this call with a 451 HTTP-Response in the Location-Header. The status code serves as an indicator that the use case must be continued in the context of the BANKSapi REG/Protect.

When BANKSapi synchronizes your account data with your banking provider, we might encounter an expired consent (cf. Operations with SCA). A consent renewal has to be performed then, which we will communicate with an authenticate relation.

The location header then contains the URL to be called on the BANKSapi page. The web form should be called up in the same browser window and replace the current content. For security reasons, it can only be called up once. This starts the RegProtect process at BANKSapi and the end customer has the possibility to select a provider and enter his online banking credentials in the following forms delivered by BANKSapi.

You must append a query parameter callbackUrl to this URL (URL-encoded), which is called again by BANKSapi after the successful (or failed) registration of the end customer's bank access.

Overview of all REG/Protect query parameters:

Field	Type	Required	Description
refresh	Boolean	false	Refresh an existing account
callbackUrl	String	true	The URL on your page that the user will be redirected to after registering with BANKSapi. Warning: Must be URL-encoded *

The callbackUrl is then the URL to which the user is forwarded after registration. It is called by the user's browser (in the popup window you open, as GET) with the entire query string you supply, so you can also specify your own parameters, which are then handled transparently by BANKSapi. Logically, there should be a frontend page under the URL, since it is then displayed to the user.

In addition to the query string you specified in the callbackUrl, the following query parameters are also sent (appended to the URL, ?parameter1=value1&parameter2=value2):

Field	Type	Included	Description
baReentry	String	Always	If successful `FINISHED`

Triggering a payment

&lt;font color="#ffff00"&gt;-=https://banksapi.io/customer/v2/ueberweisung/e1f30693-=- proudly presents -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_PAYMENT_SINGLE_TRANSFER

A payment is triggered in the same way as an bank access is added, first by calling a payment endpoint (e.g. Initiate Single Transfer) using HTTP POST. Since all payment data can be determined in REG/Protect, it is sufficient here to send an empty JSON object as a payload only. You can also prefill payment data and define whether the prefilled data will be editable in REG/Protect, this behaviour is enforced by all bulk payments.

As in the use case before, a 451 (Unavailable For Legal Reasons) is delivered in the Location-HTTP header.

To this URL you have to append a query parameter callbackUrl (https://de.wikipedia.org/wiki/URL-Encoding), which is called again by BANKSapi after the successful or failed triggering of the payment.

Overview of all query parameters for REG/Protect when triggering a payment:

Field	Type	Included	Description
useCase	String	Always	REG/Protect use case, which is already provided by the Location field in HTTP 451 response, e.g. `START_PAYMENT_SINGLE_TRANSFER`
callbackUrl	String	Always	The URL on your page that the user will be redirected to after the BANKSapi referral process. Warning: Must be URL-encoded *

The callbackUrl is then the URL to which the user is redirected after the payment. It is called by the user's browser (in the window you open, as GET) with the entire query string you provide, so you can also specify your own parameters, which are then handled transparently by BANKSapi. Logically, there should be a frontend page under the URL, since it is then displayed to the user.

In addition to the query string you specified in the callbackUrl, the following query parameters are also sent (appended to the URL, ?parameter1=value1&parameter2=value2):

Field	Type	Included	Description
baReentry	String	Always	If successful `FINISHED`

Operations with SCA

Due to the PSD2 requirements in respect to SCA, there is a multi-step process involved in order to add a bank access.

The process differs depending on whether you are using REG/Protect or not:

REG/Protect	Task	Process description
Yes	Create a bank access	When creating a bank access, the multi-step process will be covered by us through the REG/Protect frontend. Find the documentation in Adding bank access with REG/Protect
Yes	Refresh a bank access	During usage, the consent of the customer might expire at some point and new data can't be fetched from the bank. You can refresh with new data from the bank with a `refresh`-flag as documented. Whenever there is a relation `start_sca`, `POST` to the `start_sca` relation to indicate the user is ready to start an SCA process. You will receive a `451` status with a `Location`-header. Display the contents of the `Location`-Header to the user in the same way you would with the `Location`-Header when adding a bank access. This is to refresh the SCA with the bank in order to get up-to-date data from the bank.
No	Create or update a bank access	When using the embedded approach (without REG/Protect), there are several steps you need to follow. When creating or updating the bank access and in case of an SCA, there will be one of the following relations: set_method: This relation is sent with appropriate `sicherheitsverfahren` in the bank access. Use it as documented in Set SCA Method set_medium: Not to be confused with `set_method`, this relation is sent with appropriate `tanMedien` in the bank access. Use it as documented in Set SCA Method authenticate: This relation serves the purpose to resolve TAN procedures as described in Strong Customer Authentication, this `href` should be called with `POST` as described in Submit SCA Authentication Data. authentication_decoupled: This relation is for TAN-less i.e. decoupled methods, send a `GET` request to the `authentication_decoupled`-relation to poll for the status of the SCA. This relation appears together with the `authentication`-relation, but should always be preferred. redirect_url: When this relation is available the authentication will be performed on the bank interface. The user therefore needs to be redirected to the URL in this relation and will reenter your application at the given `callbackUrl`, that was provided as a query parameter in the POST request. If the redirected authentication ends prematurely and the user cannot finish the authentication, we offer a `cancel`-relation There can be multiple SCAs for a single bank access, so your application needs to be able to handle any of the above mentioned relations at any point of the creation/update. If any of the SCAs fail, there will be `start_sca` relation when the bank access reaches the status `VOLLSTAENDIG`
No	Background update of a bank access	The consent of the customer might expire at some point and new data can't be fetched from the bank. In this case, the BankAccess object will contain a relation `start_sca`. `POST` an empty object to this relation in order to indicate that the user is ready to start an SCA process and renew the consent.

Encryption

To encrypt the Credentials, the asymmetric crypto procedure RSA is used. If you become our customer, you will receive a public key from us with which the encryption is performed.

Since the concrete implementation of encryption in the different programming environments is different from each other the characterizing properties of the process (specified in the following table) are used. PKCS #1), with which the conversion in your preferred development environment should not be a problem:

Encryption algorithm: RSA
Operating mode: none (pure block encryption)
Padding: OAEP (Optimal Asymmetric Encryption Padding) with SHA-1 (hash function) and MGF1 (mask generation function)

The description of the method used is described in the Java-specific JCA Standard Algorithm Name Documentation as follows: RSA/NONE/OAEPWithSHA1AndMGF1padding

Notifications

Webhook calls ("notifications") can be made as POST in the following incidents during a background update (independently of each other):

Event	Description
Transaction	New transaction(s) found
Balance	The balance of a user has changed.
Error	Error

POST /your-notification-endpoint HTTP/1.1
User Agent: BANKSapi Notifier
Content-Type: application/json
Accept: */*
Connection: close

The POST-HTTP call looks like this during the call:

Header	Value
User-Agent	`BANKSapi Notifier`
Content-Type	`application/json`

Notification object

The payload, i.e. the BODY of the POST-Requests contains at least the following fields for all types of notifications:

Field	Type	Included	Description
userId	String	Always	`userid` of the user as OAuth-Token
accountId	String	Always	`id` of the bank access
tenant	String	Always	`name` of the tenant
notificationType	String	Always	Contains the Notification Type
occurred	timestamp	Always	Time of triggering the notification
serial	Integer	Always	Consecutive, integer sequence number of the notification for checking missed notifications

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 Munich",
        "amount": -70
    }, {
        "payeeName": "netzpolitik.org e. V.",
        "amount": -1337.42
    }]
}

In the event that one or more new transactions are found, this object is sent by the notifier. It contains additional to the fields of the Notification object:

Field	Type	Included	Description
productId	String	Always	Contains the `id` of the bank product
newTransactions	Array of Transaction objects	Always	Contains the new transactions in the form of Transaction objects

Transaction object

{
    "payeeName": "La Sopia GmbH Munich",
    "amount": -70
}

Field	Type	Included	Description
payeeName	String	Always	Contains the `id` of the bank product
amount	Number	If available	Amount of transaction, negative for outputs if applicable

Request-Body

The request body consists of a Transaction Notification Object.

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
}

If the account balance or position of a bank product has changed, this object is sent by the notifier. It contains additional to the fields of the Notification object

Field	Type	Included	Description
productId	String	Always	Always
oldBalance	Number	Always	Contains the old account balance or balance before the last background update.
newBalance	Number	Always	Contains the new account balance or position determined by the current background update.

Request-Body

The request body consists of a Balance Notification Object.

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": "Access blocked"
}

If an error occurred during the Background update, this object is sent by the notifier. It contains additional to the fields of the Notification object

Field	Type	Included	Description
level**	String	Always one of `INFO`, `WARNING`, `ERROR`
code	String	Always	See Errors and Messages
message	String	Always	See Errors and Messages
data	String	If available	Further information as String

Request-Body

The request body consists of an Error Notification Object.

Transactions older than 90 days

It is possible to fetch transactions older than 90 days from the banks. This makes sense to do especially in the case of the initial addition of the bank access, as there is no history yet in the BANKSapi storage.

We are able to fetch transactions back as far as the bank will serve (in some cases years) for new customers, and up to October 15th 2020 for existing customers. Please be aware that this functionality is best effort and while > 90d is possible for the majority of accounts, there are banks that still only return 90d.

The obvious drawback is that there is the need of theoretically up to three additional SCA processes the customer has to undergo. Usually though none or only one additional SCA process will be required. This of course depends on the bank, and there is no way yet to foresee the number of SCAs. We recommend to use this functionality in cases where it is vital to fetch a history for the user.

To indicate you would like BANKSapi to try and fetch > 90d, you can use the optional parameter maxTransactions as a query parameter when adding or refreshing a bank access. If indicating paymentAccounts, > 90d will only be fetched for payment accounts (GIROKONTO), if indicating all this will be tried for all kinds of bank products. Whenever sending this parameter, be prepared for SCA requests to come up for the bank access, so this should be used whenever the user is active on your page / app.

Please note that for fetching transactions > 90 days from the BANKSapi storage, you will additionally have to indicate the from parameter when fetching transactions, otherwise although we have a history > 90d for the user, you will not get it from BANKSapi storage as the default from is 90d in the past.

Transaction tags (categorization)

The current list of categories for the categorization can change at any time, even without changing the version number of the API.

Parent Category	Category	Display Name (de_DE)
	`BANKFINANCE`	Bank und Finanzen
`BANKFINANCE`	`BANKFINANCE_CASHWITHDRAWAL`	Barauszahlung
`BANKFINANCE`	`BANKFINANCE_CREDITPAYMENT`	Kredittilgung
`BANKFINANCE`	`BANKFINANCE_CURRENCY`	Devisen- / Sortengeschäfte
`BANKFINANCE`	`BANKFINANCE_FEES`	Bankgebühren
`BANKFINANCE`	`BANKFINANCE_INVESTMENT`	Investment
`BANKFINANCE`	`BANKFINANCE_OTHER`	Bank und Finanzen - Sonstiges
	`BILLS`	Vertragsrechnungen
`BILLS`	`BILLS_ENERGY`	Energiekosten
`BILLS`	`BILLS_OTHER`	Vertragsrechnungen - Sonstiges
`BILLS`	`BILLS_PUBLICRADIO`	Öffentlich-rechtlicher Rundfunk
`BILLS`	`BILLS_TELECOMMUNICATIONS`	Internet und Telekommunikation
`BILLS`	`BILLS_WATERANDDISPOSAL`	Wasser und Entsorgung
	`BUSINESS`	Geschäftlich
`BUSINESS`	`BUSINESS_ADVERTISEMENT`	Werbekosten
`BUSINESS`	`BUSINESS_ASSOCIATION`	Berufsverbandsbeiträge
`BUSINESS`	`BUSINESS_CONSULTING`	Beratungskosten (geschäftlich)
`BUSINESS`	`BUSINESS_CREDITPAYMENT`	Kredittilgung (geschäftlich)
`BUSINESS`	`BUSINESS_ENERGY`	Energiekosten (geschäftlich)
`BUSINESS`	`BUSINESS_EQUIPMENT`	Arbeitsmittel
`BUSINESS`	`BUSINESS_HOSPITALITY`	Bewirtungskosten (geschäftlich)
`BUSINESS`	`BUSINESS_INVESTMENT`	Investment (geschäftlich)
`BUSINESS`	`BUSINESS_LEASING`	Leasinggebühren (geschäftlich)
`BUSINESS`	`BUSINESS_LEGAL`	Anwaltskosten (geschäftlich)
`BUSINESS`	`BUSINESS_MOBILITY`	Mobilität (geschäftlich)
`BUSINESS`	`BUSINESS_OTHER`	Geschäftlich - Sonstiges
`BUSINESS`	`BUSINESS_RENT`	Miete (geschäftlich)
`BUSINESS`	`BUSINESS_SALARY`	Personalkosten
`BUSINESS`	`BUSINESS_TAXES`	Betriebssteuern
`BUSINESS`	`BUSINESS_TELECOMMUNICATIONS`	Internet und Telekommunikation (geschäftlich)
`BUSINESS`	`BUSINESS_TRAINING`	Fortbildungs- und Schulungskosten (geschäftlich)
`BUSINESS`	`BUSINESS_TRAVEL`	Geschäftsreisekosten
`BUSINESS`	`BUSINESS_WATERANDDISPOSAL`	Wasser- und Entsorgungsgebühren (geschäftlich)
	`EDUCATION`	Bildungswesen
`EDUCATION`	`EDUCATION_ACADEMIC`	Universität
`EDUCATION`	`EDUCATION_OTHER`	Bildungswesen - Sonstiges
`EDUCATION`	`EDUCATION_SCHOOL`	Schulbildung
`EDUCATION`	`EDUCATION_TRAINING`	Fortbildung
	`FAMILY`	Kinder und Familie
`FAMILY`	`FAMILY_CHILDACTIVITIES`	Kinderaktivitäten
`FAMILY`	`FAMILY_CHILDCARE`	Kinderbetreuung
`FAMILY`	`FAMILY_CHILDNECESSITIES`	Kinder- und Babybedarf
`FAMILY`	`FAMILY_OTHER`	Familie - Sonstiges
`FAMILY`	`FAMILY_SUPPORT`	Unterhalt
`FAMILY`	`FAMILY_TOYS`	Spielwaren
	`HEALTH`	Gesundheit
`HEALTH`	`HEALTH_CONSUMABLES`	Arznei und Heilmittel
`HEALTH`	`HEALTH_OPTICS`	Augenoptik
`HEALTH`	`HEALTH_OTHER`	Gesundheit - Sonstiges
`HEALTH`	`HEALTH_SERVICES`	Arzt/Krankenhaus/Pflege
	`HOUSING`	Wohnen
`HOUSING`	`HOUSING_ANCILLARYCOSTS`	Nebenkosten
`HOUSING`	`HOUSING_FINANCING`	Immobilienkredit
`HOUSING`	`HOUSING_FURNISHING`	Möbel und Haushaltsgeräte
`HOUSING`	`HOUSING_OTHER`	Wohnen - Sonstiges
`HOUSING`	`HOUSING_RENOVATION`	Renovierung & Reparatur
`HOUSING`	`HOUSING_RENT`	Miete/Wohngeld
`HOUSING`	`HOUSING_SERVICES`	Haushaltsdienstleistungen
	`INCOME`	Einnahmen
`INCOME`	`INCOME_BUSINESS`	Geschäftseinnahmen
`INCOME`	`INCOME_CASHDEPOSIT`	Bareinzahlung
`INCOME`	`INCOME_CREDIT`	Krediteinnahme
`INCOME`	`INCOME_INSURANCE`	Versicherungseinnahmen/-gutschriften/-rückzahlungen
`INCOME`	`INCOME_INVESTMENT`	Kapitaleinkommen
`INCOME`	`INCOME_OTHER`	Einnahmen - Sonstiges
`INCOME`	`INCOME_PENSION`	Rente und Pension
`INCOME`	`INCOME_REFUND`	Gutschriften und Erstattungen
`INCOME`	`INCOME_RENTAL`	Vermietung und Verpachtung
`INCOME`	`INCOME_RETURNDEBIT`	Rücklastschriften
`INCOME`	`INCOME_SALARY`	Gehalt
`INCOME`	`INCOME_SALES`	Verkaufseinnahmen
`INCOME`	`INCOME_SAVINGS`	Spareinnahmen
`INCOME`	`INCOME_SOCIALBENEFIT`	Sozialleistung
`INCOME`	`INCOME_STATEEDUCATION`	Staatliche Förderung für Bildung
`INCOME`	`INCOME_STATEFAMILY`	Staatliche Förderung für Familie und Kinder
`INCOME`	`INCOME_TAXES`	Steuerrückzahlungen und -erstattungen
	`INSURANCE`	Versicherungen
`INSURANCE`	`INSURANCE_ACCIDENT`	Unfallversicherung
`INSURANCE`	`INSURANCE_BUSINESS`	Gewerbliche Versicherung
`INSURANCE`	`INSURANCE_HEALTH`	Krankenversicherung
`INSURANCE`	`INSURANCE_LEGAL`	Rechtsschutzversicherung
`INSURANCE`	`INSURANCE_LIABILITY`	Haftpflichtversicherung
`INSURANCE`	`INSURANCE_LIFE`	Lebensversicherung
`INSURANCE`	`INSURANCE_OTHER`	Versicherungen - Sonstiges
`INSURANCE`	`INSURANCE_PROPERTY`	Sachversicherung
`INSURANCE`	`INSURANCE_TRANSPORT`	Transportversicherung
`INSURANCE`	`INSURANCE_TRAVEL`	Reiseversicherung
`INSURANCE`	`INSURANCE_VEHICLE`	KFZ-Versicherung
	`LIVING`	Lebenshaltung
`LIVING`	`LIVING_CHARITY`	Spenden & Wohltätigkeit
`LIVING`	`LIVING_DRUGSTORE`	Drogerie
`LIVING`	`LIVING_GROCERIES`	Lebensmittel
`LIVING`	`LIVING_OTHER`	Lebenshaltung - Sonstiges
	`MOBILITY`	Mobilität
`MOBILITY`	`MOBILITY_BIKESHARE`	Bike-Sharing
`MOBILITY`	`MOBILITY_CARSHARE`	Car-Sharing
`MOBILITY`	`MOBILITY_FUEL`	Kraftstoffe und Schmiermittel
`MOBILITY`	`MOBILITY_OTHER`	Mobilität - Sonstiges
`MOBILITY`	`MOBILITY_PARKING`	Parken
`MOBILITY`	`MOBILITY_PUBLICTRANSPORT`	ÖPNV
`MOBILITY`	`MOBILITY_SERVICES`	Wartung, Pflege und Reparaturen
`MOBILITY`	`MOBILITY_TAXES`	KFZ-Steuer
`MOBILITY`	`MOBILITY_TAXI`	Taxi
`MOBILITY`	`MOBILITY_VEHICLEACQUISITION`	KFZ - Kredit/Kauf/Leasing
	`OTHER`	Sonstiges
`OTHER`	`OTHER_OTHER`	Sonstiges
	`RECREATION`	Freizeit und Unterhaltung
`RECREATION`	`RECREATION_CULTURAL`	Kultur
`RECREATION`	`RECREATION_FOODANDDRINKS`	Ausgehen und Essen
`RECREATION`	`RECREATION_GAMBLING`	Glücksspiel
`RECREATION`	`RECREATION_HOBBYANDSOCIAL`	Hobbys und soziale Aktivitäten
`RECREATION`	`RECREATION_ONLINE`	Spiele und Online-Unterhaltung
`RECREATION`	`RECREATION_OTHER`	Freizeit und Unterhaltung - Sonstiges
`RECREATION`	`RECREATION_PETS`	Haustier
`RECREATION`	`RECREATION_PRINTED`	Bücher und Zeitschriften
`RECREATION`	`RECREATION_SPORTS`	Sport und Fitness
`RECREATION`	`RECREATION_STREAMING`	Streaming und Pay-TV
	`SAVINGS`	Sparen
`SAVINGS`	`SAVINGS_ACCOUNT`	Sparguthaben
`SAVINGS`	`SAVINGS_BUILDING`	Bausparguthaben
`SAVINGS`	`SAVINGS_OTHER`	Sparen - Sonstiges
	`SERVICES`	Dienstleistungen
`SERVICES`	`SERVICES_MAIL`	Porto- und Versandkosten
`SERVICES`	`SERVICES_ONLINE`	Software und Online-Dienstleistungen
`SERVICES`	`SERVICES_OTHER`	Dienstleistungen - Sonstiges
`SERVICES`	`SERVICES_PERSONAL`	Persönliche Dienstleistungen
`SERVICES`	`SERVICES_PROFESSIONAL`	Professionelle Dienstleistungen
	`SHOPPING`	Shopping
`SHOPPING`	`SHOPPING_BEAUTY`	Schönheitsprodukte
`SHOPPING`	`SHOPPING_CLOTHINGACCESSORIES`	Kleidung und Accessoires
`SHOPPING`	`SHOPPING_DEPARTMENTSTORE`	Kaufhaus
`SHOPPING`	`SHOPPING_ELECTRONICS`	Elektrogeräte
`SHOPPING`	`SHOPPING_ONLINE`	Online-Shopping
`SHOPPING`	`SHOPPING_OTHER`	Shopping - Sonstiges
	`TAXES`	Steuern
`TAXES`	`TAXES_CAPITALGAINS`	Kapitalertragsteuer
`TAXES`	`TAXES_CHURCH`	Kirchensteuer
`TAXES`	`TAXES_FLAT`	Abgeltungsteuer
`TAXES`	`TAXES_INCOME`	Einkommensteuer
`TAXES`	`TAXES_OTHER`	Steuern - Sonstiges
`TAXES`	`TAXES_PROPERTY`	Grundsteuer
`TAXES`	`TAXES_SALES`	Umsatzsteuer
	`TRANSFER`	Transfer
`TRANSFER`	`TRANSFER_BANKFINANCE`	Kontotransfer
`TRANSFER`	`TRANSFER_CREDITCARDSETTLEMENT`	Kreditkartenabrechnung
`TRANSFER`	`TRANSFER_OTHER`	Transfer - Sonstiges
`TRANSFER`	`TRANSFER_SAVINGS`	Transfer - Sparen
	`TRAVEL`	Reisen
`TRAVEL`	`TRAVEL_ACCOMMODATION`	Unterkunft
`TRAVEL`	`TRAVEL_INCLUSIVEOFFERS`	Pauschalreisen
`TRAVEL`	`TRAVEL_OTHER`	Reise - Sonstiges
`TRAVEL`	`TRAVEL_TRANSPORT`	Transport

Errors and messages

In the communication between client, BANKS/Connect and the providers, errors can occur. which can be caused by a wide variety of constellations. We are always makes every effort to transport the cause of an error to you as informatively as possible so that can be reacted to accordingly quickly.

A simple use case is, for example, that the login of a customer to his bank is not worked. As an error message, the system returns, for example, that the user ID is not was 10 digits long and so the login data was not correct. The customer is thus in a position to "problem" quickly.

HTTP status codes

Status	Name	Meaning API	Handling
200	OK	The request has been successfully executed	-
201	Created	The request was executed successfully and the data object was created	Evaluate and call location header
400	Bad Request	The request is syntactically wrong	Program error at the caller, manual intervention necessary
401	Unauthorized	The authorization: bearer TOKEN header was not sent	Send header
403	Forbidden	The OAuth2 token has expired, is invalid or the required scope is missing	Request new token, extend scopes
404	Not found	The URL does not point to a valid object	Start new data retrieval and update relations
451	Unavailable for Legal Reasons	The requested resource cannot be returned for regulatory reasons.	This is used in the course of the REG/Protects, the HTTP response contains a `Location` header with the URL for the redirect
500	Internal Server Error	This shouldn't have happened	We're already working on it
504	Gateway Timeout	The started request could not be answered within the specified time	Repeat request shortly

Message codes

{
   "level": "ERROR",
   "code": "BA1011",
   "message": "Access data not correct ",
   "details": "Please check your access data and try again. Please note that your access data will be blocked if you enter it incorrectly three times."
}

Code	Level	Message	Details
BA999	ERROR	Internal error
BA1000	ERROR	Maintenance work provider
BA1001	ERROR	Provider no longer active
BA1010	ERROR	Access blocked	Your PIN for Internet banking was entered incorrectly three times. So we've temporarily suspended your access for security reasons
BA1011	ERROR	Access data not correct	Please check your access data and try again. Please note that your access data will be blocked after three incorrect entries.
BA1012	ERROR	Incomplete access data	The following access data is required: Authfields 1 = Example user name 2 = Example PIN 3 = Example key
BA1013	ERROR	Bank access not activated
BA1014	ERROR	Too many unsuccessful logins
BA1020	ERROR	Account has improper permissions
BA1051	ERROR	Bank access not available	Maintenance: A technical malfunction has occurred at your bank. Please update your bank access at a later date.
BA1052	ERROR	Bank access not fully accessible
BA1053	ERROR	Access exceeded
BA1060	ERROR	Product could not be updated
BA1062	ERROR	Revenues could not be updated
BA1063	ERROR	Depot positions could not be updated
BA1064	ERROR	Message bank
BA1100	ERROR	Invalid bank transfer data	Please check your entries. Transfers are only possible to the reference account.
BA1101	ERROR	Invalid TAN procedure
BA1102	ERROR	Invalid TAN medium
BA1103	ERROR	TAN invalid	Error during transmission, or mTan not (any longer) valid
BA1104	ERROR	Bank transfer not possible	Bank transfers are only supported for checking accounts or HBCI message 9390 Order rejected due to double submission.
BA1110	INFO	TAN input required	Please enter the SMS-TAN
BA1111	INFO	The transfer was successfully completed
BA1112	INFO	The transfer was successfully submitted
BA1200	ERROR	Invalid debit data	Please check your input data.
BA1204	ERROR	Debit not supported
BA1212	INFO	The debit was successfully submitted
BA2002	INFO	There are messages from your bank	There are messages from your bank, please log into your online banking.
BA2003	INFO	Product type not supported
BA2004	INFO	Bank access not activated yet
BA3000	INFO	SCA required	SCA required
BA3005	INFO	SCA redirect required
BA3010	INFO	Select SCA method	Select SCA method
BA3020	INFO	Select SCA medium	Select SCA medium
BA3030	INFO	SCA Challenge	SCA Challenge
BA3040	ERROR	SCA failed	SCA failed
BA3060	ERROR	No supported SCA method found	No supported SCA method found

BANKS/Connect Providers API

If you are more interested in the customer data, we would like to recommend our quick start guide.

Via the BANKS/Connect Providers API you get access to a comprehensive configuration database for the banks and service providers supported by us.

The API is similar in structure to the other BANKS/Connect APIs. That means above all, that everything written in the BANKS/Connect API Overview applies to this API.

In addition to general primary data such as name, bank group, bank code and BIC, you also receive detailed machine-readable information on the login modalities for your users, so that you can optimize the user experience of your application when creating bank accesses.

A concrete example of this data can be found in the Provider section.

Frequently Asked Questions

How do I get API access?

Get your free trial here. For more information: Contact us!

How do I get the banking products for my customer?

The banking products are available via the BANKS/Connect Customer API. The end user must add a Bank Access before.

If the data retrieval is successful, the data is ready for retrieval via the API.

What are credentials?

Credentials are here defined as the customer's access data to his online banking. The credentials usually consist of a user ID/login name and a password/PIN. The concrete specification is different per provider and can be queried via the BANKS/Connect Providers API.

What's a TAN?

A TAN (transaction number) is a random code that can only be used once. In the BANKS/Connect Customer API the TAN is needed for the transfer process.

After the transfer data has been transmitted to the provider, the TAN or the instruction for TAN generation (e.g. chip card reader) is then sent directly from the provider to the customer. The TAN must then be queried by the customer and forwarded to BANKS/Connect Customer API to confirm the order.

Is there a test account or a demo account?

Yes, there is a demo bank. It is a fictitious bank with fictitious but not unrealistic banking products. This test access demonstrates the possibilities our API offers you. There is no connection to the real world. For further information please refer to our Quickstart Guide

What is BANKS/Connect?

BANKS/Connect is an interface through which a large number of providers can obtain their customers'

accounts including account details, account transactions and transfers
custody accounts incl. total custody account holdings, valued individual custody account holdings and custody account risk
credit cards including credit card details and credit card transactions

Where and how is the data stored?

Depending on the selected range of services, we store the data for you permanently or only for a few minutes, but in any case in the high-security data center of DATEV eG or your own.

Overview

OpenAPI

Interface strategy

Structure of interface and documentation

Before we start

Feedback

API Overview

BANKS/Connect Auth API

BANKS/Connect Customer API

BANKS/Connect Providers API

BANKS/Connect AI API

Central Concepts

Authentication

Bank

User

Client

Correlation ID

CORS

Errors

HATEOAS

Timestamp

JSON

Client

OAuth2

Token types

Token levels

Token usage

Provider

Relation

REST

Service Provider

Language

Encryption

Versioning

Quick Start

What We're Going to Do

Create a Client Token

Create a User

Create a User Token

Create Bank Access

Query Bank Access

Query Turnovers

Force a Refresh of Data From the Bank

Renew Consent with SCA / TANs

Query Issues

Where to Go From Here

EBICS

Overview

Create an EBICS Account

Call the Add Bank Access Endpoint

Redirect the User

Initialization Letter Generation

Verify the Bank Access

User Sends Initialization Letter to the Bank

Successful Connection

Comparison to Non-EBICS Bank Accesses

Caveats

Initializing multiple times

Balance Retrieval Limitation

Historical Transaction Limitation

Transaction History Range

BANKS/Connect Auth API

BANKS/Connect Customer API

Concepts

REG/Protect (redirect solution)

Background update

Notifications (Webhooks)

Strong customer authentication

TAN medium

Customer IP Address

REG/Protect

Context info when returning to your app

Adding and authenticating a bank access

Triggering a payment

Operations with SCA

Encryption

Notifications

Notification object

Notification Type

Transaction Notification