NAV Navbar
cURL

BANKSapi Banks/Connect

Interface strategy

The APIs are created according to the REST paradigm with architectural style HATEOAS in mind. The addressing logic that is thus shifted to the server makes it possible to extend the API organically, without the callers having to Fractures yield.

If it is not possible to implement a downward compatible change, previous versions of the interface will be updated as required via a technically meaningful transitional period is provided in parallel.

The interface is always called using HTTPS encryption. We currently offer JSON as the data exchange format, but if required we also offer an extension by further formats for 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 BANKSapi Auth API, which are briefly described in the following sections. For further information please contact please refer to the comprehensive Sub-API documentation.

central concepts](#central concepts) of the BANKSapi Banks/Connect interface such as authentication are described within this document in the chapter of the same name. Furthermore, the following concepts apply for the respective Sub-API is described in the respective API documentation.

Before we go off

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

In addition to the explanatory texts, examples of the data in JSON format are given 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 7.43.0. 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 about your criticism and suggestions, which you please to support@banksapi.de.

APIs

Banks/Connect Customer API

{
   "bank access":{
      "Demo Bank":{
         "status": "VOLLSTAENDIG",
         "update date": "2016-10-27 11:20:52",
         "timeout": "2016-10-27 11:40:52",
         "tanMedien":[
            {
               "ValidFrom": "2016-10-27 11:20:53",
               "ValidUntil": "2016-10-27 11:20:53",
               "name": "Mobile",
               "media class": "MOBIL"
            }
         ],
         "Security procedures":[
            {
               "Coding":1,
               "name": "Demo-TAN",
               "Note": "The demo TAN is any even number"
            }
         ],
         "ActiveSecurityProcedure":{
            "Coding":1,
            "name": "Demo-TAN",
            "Note": "The demo TAN is any even number"
         },
         "banking products":[
            {
               "id": "DE00123456789012345678",
               "designation": "current account",
               "Category": "GIROKONTO",
               "update date": "2016-10-27 11:20:53",
               "balance": 2145.78,
               "balance date": "2016-01-18 00:00:00",
               "currency": "EUR",
               "Account number": "9012345678",
               "iban": "DE00123456789012345678",
               "bic": "XXX12345678",
               "blz": "12345678",
               "Owner": "Fritz Testmüller",
               "relations":[
                  {
                     "rel": "start_bank transfer",
                     "href": "https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345678"
                  },
                  {
                     "rel": "self",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345678"
                  },
                  {
                     "rel": "get_kontoumsaetze",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345678/kontoumsaetze"
                  }
               ],
               "Overdraft limit": 3,000.0,
               "Frame available": 2045.78,
               "Amount available": 100.0
            },
            {
               "id": "12345678XXXX1234",
               "designation": "Visa card",
               "Category": "CREDIT CARD",
               "update date": "2016-10-27 11:20:53",
               "balance":-89.95,
               "balance date": "2015-05-11 00:00:00",
               "currency": "EUR",
               "Account number": "12345678XXXX1234",
               "Credit institution": "Demo Bank AG",
               "Owner": "Fritz Testmueller",
               "relations":[
                  {
                     "rel": "self",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/12345678XXXX1234"
                  },
                  {
                     "rel": "get_kontoumsaetze",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/12345678XXXX1234/kontoumsaetze"
                  }
               ],
               "Overdraft limit":1000.0
            },
            {
               "id": "9012345680",
               "designation": "Investment Deposit",
               "Category": "DEPOT",
               "update date": "2016-10-27 11:20:53",
               "balance": 23411.69,
               "balance date": "2015-05-11 00:00:00",
               "currency": "EUR",
               "Account number": "9012345680",
               "bic": "XXX12345678",
               "blz": "12345678",
               "Owner": "Fritz Testmüller",
               "relations":[
                  {
                     "rel": "self",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/9012345680"
                  },
                  {
                     "rel": "get_depotpositionen",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/9012345680/depotpositionen"
                  }
               ],
               "balancedata source": "OTHER"
            }
         ],
         "relations":[
            {
               "rel": "self",
               "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank"
            },
            {
               "rel": "delete",
               "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank"
            }
         ]
      }
   },
   "relations":[
      {
         "rel": "self",
         "href": "https://banksapi.io/customer/v2"
      },
      {
         "rel": "get_bankzugaenge",
         "href": "https://banksapi.io/customer/v2/bankzugaenge"
      },
      {
         "rel": "add_bank_access",
         "href": "https://banksapi.io/customer/v2/bankzugaenge"
      },
      {
         "rel": "delete_bankzugaenge",
         "href": "https://banksapi.io/customer/v2/bankzugaenge"
      }
   ]
}

At the heart of BANKSapi Banks/Connect is the Banks/Connect Customer API, which allows your end customers to access your financial life and make transactions within your product.

Comprehensive information about the API can be found in the interface documentation. 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 with a comprehensive configuration database via the Banks/Connect Providers API. with data on the Banks and Service Providers supported by BANKSapi Banks/Connect.

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

Comprehensive information about the Banks/Connect Providers API can be found in the interface documentation.

BANKSapi Auth API

The protection of personal data has the highest priority at BANKSapi. In addition to operation in DATEV eG's high security data center are encryption and security tokens that are used throughout the entire process. central components of our security concept.

The BANKSapi Auth API provides functions for managing Users. Create via the OAuth2 protocol tokens with which only those functions are released that are necessary for the respective use case.

For comprehensive information about the BANKSapi Auth API, see the Interface Documentation.

Central concepts

Authentication

authentication is a very important topic, but in the end only a means to an end. That's why we have Quick Start Guide as far as it went without bothering you with it. So you can You concentrate on the core of your requirement and move the details to something later.

With BANKSapi Banks/Connect there are basically three types of authentication:

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

To find out which form of authentication applies when, refer to the appropriate section in the Sub-API documentation. As a general rule, every inquiry to BANKSapi Banks/Connect in the context of a client. For a few, e.g. the provider query, this is already sufficient. His whole Functional diversity developed BANKSapi Banks/Connect but only with a user token and a few bank accounts.

Bank

In connection with BANKSapi Banks/Connect, we use the term "bank" to refer to the banking institutions for which we collect the data in your Pick up order. In the context of BANKSapi Banks/Connect they are combined with the Service Providers to Providers.

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

User

The unique user is also the central billing criterion. Your cooperation agreement regulates more details.

A user forms a parenthesis around the data retrieved for a person by the various banks or service providers.

With BANKSapi Banks/Connect the users belong to you, the client. About the Banks/Connect Customer API you have access to the financial data of your users.

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" that allows you to Manage users. From our point of view a client is therefore a set of access data for BANKSapi Banks/Connect.

With a client ID, lient tokens can be obtained via the Banks/Connect Auth API via OAuth2 with which the further functions in the Banks/Connect Customer API or Banks/Connect Providers API can be accessed. can be used.

Correlation ID

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

The Correlation ID (UUID) enables us to track requests across all systems. The Correlation ID can be passed on 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.

BANKSapi Banks/Connect supports Cross Origin Resource Sharing (CORS). This makes it possible to access our APIs directly from your browser. in a single page app, for example.

Error

Wikipedia has an excellent list of HTTP status codes.

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 BANKSapi/Banks Connect, we have no influence on their (generally very high) availability.

Therefore we provide you in the Banks/Connect Customer API message objects next to a code, a error description for your end customer as well as an informative detail message for you. This also includes queries with errors with an HTTP status code from the Range 2XX answered.

If things get stuck with us, we work with the whole range of HTTP status codes.

For details about the possible message objects and the HTTP status codes, see the "Errors and Messages" section in the Sub-API documentation.

HATEOAS

More information about HATEOAS on Wikipedia.

HATEOAS stands for "Hypermedia as the Engine of Application State". Here the client of a REST interface navigates only via URLs provided by the server. Accordingly, there are only a few fixed URLs that must be known to the calling party. Each additional Interaction takes place via URLs that contain within the return of interface calls and have only limited validity.

These URLs are sent to the caller either in the HTTP response header "Location" or more frequently in the form of Relations in the returned document. to the police.

Timestamp

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

Time stamps are always output without time zone information. They correspond to the format ISO 8601 in the form YYYY-MM-DD hh:mm:ss. Data are 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 BANKSapi Banks/Connect interfaces use the JSON (JavaScript Object Notation) for data exchange. Attributes without Values are not delivered as "zero", but "missing" in the document. We supply 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 downward compatible. Unknown values in Enumeration types must therefore also be ignored by the Client or encrypted to a more general value.

When JSON is delivered, the Content-Type header "Content-Type: application/json" must always be included. With "zero" values, it does not matter whether the fields be sent as "zero" 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 benefit from the ongoing development of BANKSapi Banks/Connect. And of course you can also 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. If nothing is explicitly documented in the corresponding use case, the call with a unique user is assumed. Details on user and client management are described in the BANKSapi Auth API.

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 is used. (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 account transactions 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 bank. In the context of BANKSapi Banks/Connect they are also more generally referred to as Provider](#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 the detail quite fast with the search for an adequate Translation in a cul-de-sac (or in a semi-silk translation). As technicians, however, it also makes sense for us to "program in English".

In order to get out of this dilemma, we have decided to keep technical terms from the banking environment in German and to use all other terms from the English to import. To make sure that it doesn't become too crass Denglish, we also decided to use German in case of doubt.

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

Encryption

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

In order for BANKSapi 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

With this quick start guide we would like to give you the possibility to download the Banks/Connect Customer API, without having to deal with details like the Authentication](index.html#authentication) or Encryption to deal with. For these first steps you don't need a API Access and also no own account.

Demo access

Our demo account is accessible via the fictitious Demo provider with ID 0000000000-0000-0000-0000-000000000000. The demo provider is fully integrated into BANKSapi Banks/Connect. All the steps you need to take can perform here, go on to the living productive system and differ from other providers only by the fact that the inquiries do not go further out into the world. So you get a realistic picture of how BANKSapi Banks/Connect feels.

Request OAuth2 token

How it works, of course, can be found in the BANKSapi Auth API-Documentation.

Normally you would have to request an OAuth2 token now. But we already have it for you. prepared. The token is linked to the information about which functions you can call. In in our case these are all reading functions on the customer. The token is 0defaced-1337-d00d-c0de-face8badcafe.

Add bank account

How to do it is of course described in the corresponding chapter.

We spared you that, too. When you access with the demo OAuth2 token, the system automatically created an access to the demo provider.

Request customer data

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

Now it's getting serious. On the side you can see the call in Curl. The URL https://banksapi.io/customer/v2 is the entry point to the Banks/Connect Customer API. The HTTP verb **GET tells us that you want something. The HTTP header Expect: requests this something in a slide on (otherwise you won't have so much joy with curl).

However, the other two HTTP headers, authorization and accept, are central. former contains, as you can easily see, our demo OAuth2 token. The other token tells our Server that you expect JSON. Both headers are binding, otherwise it won't work.

{
   "bank access":{
      "Demo Bank":{
         "status": "VOLLSTAENDIG",
         "update date": "2016-10-27 11:20:52",
         "timeout": "2016-10-27 11:40:52",
         "tanMedien":[
            {
               "ValidFrom": "2016-10-27 11:20:53",
               "ValidUntil": "2016-10-27 11:20:53",
               "name": "Mobile",
               "media class": "MOBIL"
            }
         ],
         "sicherheitsverfahren":[
            {
               "Coding":1,
               "name": "Demo-TAN",
               "Note": "The demo TAN is any even number"
            }
         ],
         "ActiveSecurityProcedure":{
            "Coding":1,
            "name": "Demo-TAN",
            "Note": "The demo TAN is any even number"
         },
         "banking products":[
            {
               "id": "DE00123456789012345678",
               "designation": "current account",
               "Category": "GIROKONTO",
               "update date": "2016-10-27 11:20:53",
               "balance": 2145.78,
               "balance date": "2016-01-18 00:00:00",
               "currency": "EUR",
               "Account number": "9012345678",
               "iban": "DE00123456789012345678",
               "bic": "XXX12345678",
               "blz": "12345678",
               "Owner": "Fritz Testmüller",
               "relations":[
                  {
                     "rel": "start_bank transfer",
                     "href": "https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345678"
                  },
                  {
                     "rel": "self",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345678"
                  },
                  {
                     "rel": "get_kontoumsaetze",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345678/kontoumsaetze"
                  }
               ],
               "Overdraft limit": 3,000.0,
               "Frame available": 2045.78,
               "Amount available": 100.0
            },
            {
               "id": "12345678XXXX1234",
               "designation": "Visa card",
               "Category": "CREDIT CARD",
               "update date": "2016-10-27 11:20:53",
               "balance":-89.95,
               "balance date": "2015-05-11 00:00:00",
               "currency": "EUR",
               "Account number": "12345678XXXX1234",
               "Credit institution": "Demo Bank AG",
               "Owner": "Fritz Testmueller",
               "relations":[
                  {
                     "rel": "self",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/12345678XXXX1234"
                  },
                  {
                     "rel": "get_kontoumsaetze",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/12345678XXXX1234/kontoumsaetze"
                  }
               ],
               "Overdraft limit":1000.0
            },
            {
               "id": "9012345680",
               "designation": "Investment Deposit",
               "Category": "DEPOT",
               "update date": "2016-10-27 11:20:53",
               "balance": 23411.69,
               "balance date": "2015-05-11 00:00:00",
               "currency": "EUR",
               "Account number": "9012345680",
               "bic": "XXX12345678",
               "blz": "12345678",
               "Owner": "Fritz Testmüller",
               "relations":[
                  {
                     "rel": "self",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/9012345680"
                  },
                  {
                     "rel": "get_depotpositionen",
                     "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank/9012345680/depotpositionen"
                  }
               ],
               "balancedata source": "OTHER"
            }
         ],
         "relations":[
            {
               "rel": "self",
               "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank"
            },
            {
               "rel": "delete",
               "href": "https://banksapi.io/customer/v2/bankzugaenge/Demo-Bank"
            }
         ]
      }
   },
   "relations":[
      {
         "rel": "self",
         "href": "https://banksapi.io/customer/v2"
      },
      {
         "rel": "get_bankzugaenge",
         "href": "https://banksapi.io/customer/v2/bankzugaenge"
      },
      {
         "rel": "add_bank_access",
         "href": "https://banksapi.io/customer/v2/bankzugaenge"
      },
      {
         "rel": "delete_bankzugaenge",
         "href": "https://banksapi.io/customer/v2/bankzugaenge"
      }
   ]
}

If you (and we) have done everything right, you will get the Customer object which we have also reproduced in extracts on the right.

Query bank product

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

In the API, there is a rule that we use a URL to reference objects to create a Relation](index.html#relation) self. In this example, we call a single Bank product. Try it!

{
   "id": "DE00123456789012345679",
   "designation": "call money account",
   "Category": "DAY MONEY ACCOUNT",
   "update date": "2016-10-28 14:33:03",
   "balance":7365.56,
   "balance date": "2016-01-18 00:00:00",
   "currency": "EUR",
   "Account number": "9012345679",
   "iban": "DE00123456789012345679",
   "bic": "XXX12345678",
   "blz": "12345678",
   "Owner": "Fritz Testmüller",
   "relations":[
      {
         "rel": "start_bank transfer",
         "href": "https://banksapi.io:443/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345679"
      },
      {
         "rel": "self",
         "href": "https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345679"
      },
      {
         "rel": "get_kontoumsaetze",
         "href": "https://banksapi.io:443/customer/v2/bankzugaenge/Demo-Bank/DE00123456789012345679/kontoumsaetze"
      }
   ],
   "Frame available":7365.56,
   "Amount at disposal":0.0
}

Not surprisingly, you will only receive the banking product that you already know from above.

Query turnover

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

It would be a long time if all the data came at the first call. Therefore, there are still some relations, that do more than just get data snippets.

With the relation get_kontoumsaetze e.g. you get a list of ... Account Turnover](#Account Turnover).

[
   {
      "Amount":3.54,
      "Purpose": "Closing of interest account 565915605EUR from 30.09.2014 to 31.12.2014 Credit interest 0.550% Ref. 6FF1500111827884/186|0",
      "Booking date": "2014-12-31 00:00:00",
      "value date": "2014-12-31 00:00:00",
      "counter account holder":""
   },
   {
      "Amount":-1800.0,
      "Use for": "Transfer to current account end-to-end reference: not specified Ref. HO214274M4912194/2|0",
      "Booking date": "2014-10-02 00:00:00",
      "value date": "2015-10-02 00:00:00",
      "counter account holder": "Fritz TestMueller"
   }
]

The sales come in a JSON array, which can be seen in extracts again.

What to do next

Do you already have API access? If you don't take it. Contact with us.

After this short tour we presented you the central concepts of our API. Of course, we only scratched the surface of possibilities.

In this documentation you will find all the information you need to connect to our APIs. And if something is missing, write us your questions.

Banks/Connect Customer API

This API forms the core of BANKSapi 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](index.html#relation) 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.

Topics & Concepts

REG/Protect (redirect solution)

The BANKSapi "REG/Protect-as-a-Service", allows users to perform authorization completely in the front end of the 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 licence 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.

Parallel requests

BANKSapi tries as hard as possible to avoid restrictions regarding parallel calls. Unfortunately, some banks and service providers do not allow parallel calls. Therefore, a Client, make sure that no multiple business transactions, such as Transfers and/or data updates can be triggered in parallel. Otherwise, the the respective banks have already finished running queries, which leads to problems in further processing. can lead.

Background update

A background update can be requested when adding a bank account. The bank access and its turnover are then queried and updated four times (4x) a day by the provider.

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

SCA is used to determine the identity of the end customer. SCA uses two out of three factors of:

We differentiate between TAN and TAN-less security mechanisms.

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

TAN-less / decoupled methods 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 posession factor. Another name for this method is BestSign. 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.

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

TAN medium

The TAN medium has the function of an intermediary. For example, the TAN itself (smsTAN) or the instruction for generating or determining a TAN is forwarded to the customer.

The TAN medium can also be used to generate customer-specific TANs. (e.g. chipTAN procedure by using the EC card).

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

REG/Protect

The REG/Protect redirect solution provides an HTML frontend for adding bank accounts and triggering payments.

Context info when returning to your app

The return of the user can take place for different reasons, the reason is communicated in the query parameter baReentry:

Type of return Reason Example Value for baReentry
Process successfully completed professional FINISHED
User does not agree with AGB/DSE technical LEGAL_NOT_ACCEPTED
Click on "Go to customer portal" Business Click on page "Select bank" USER_CANCELLED
Termination of the process Business Termination on "Your accounts" page USER_CANCELLED
Unexpected HTTP Repsonse Code technical HTTP 200 expected but HTTP 500 delivered BACKEND_ERROR
Unexpected HTTP response (body) Technical Valid JSON expected but invalid delivered ACKEND_ERROR
Access data incorrectly entered three times technical INVALID_CREDENTIALS
TAN incorrectly entered three times domain name INVALID_TAN
General error Technical Guard prevents mask access; possible manipulation attempt ERROR
No accounts found for bank transfer Depreciation area No accounts or no accounts suitable for bank transfer were found when the bank transfer was started NO_ACCOUNTS

Adding and authenticating bank accounts

$ 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-regulkated 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. During usage, at any time one or many consents of the customer might expire. Therefore, expect a URL to the REG/Protect frontend with an authenticate relation. In this case, the use case (see parameters below) will be AUTHENTICATE_ACCOUNT, the rest will stay the same.

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 access data in the following masks 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 account.

All query parameters of the REG/Protects for adding a bank account in the overview:

Field Type Included Description
useCase String Always CREATE_ACCOUNT or AUTHENTICATE_ACCOUNT
callbackUrl String Always 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_TRANSFER

A payment is triggered in the same way as an account is added, first by calling the end point documented under Create transfer using HTTP POST. Since all payment data is determined during the process at BANKSapi, it is sufficient here to transfer only an empty JSON object as a payload.

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

To this URL you have to append a query parameter callbackUrl (URL-encoded), which is called again by BANKSapi after the successful or failed triggering of the transfer.

All query parameters of the REG/Protects for adding a bank account in the overview:

Field Type Included Description
useCase String Always START_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 transfer. 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 accounts 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 account. This is to refresh the SCA with the bank in order to get up-to-date data from the bank.
No Create a bank access When using the embedded approach (without REG/Protect), there are several steps you need to undertake.

When creating the bank access, there will may be the following relations in this order, if applicable (some might be skipped, e.g. if there is only one possible SCA method, it will be selected automatically):
  • 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 two purposes: For TAN procedures as described in Strong Customer Authentication, this hrefshould be called with PUT as described in Submit SCA Authentication Data. For TAN-less methods, POST an empty object to this href to indicate the user has completed the decoupled challenge on bank side, e.g. when he has confirmed the activity in the bank app.
  • No 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. 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.

    There are two cases what can happen, depending on which SCA approach the bank is imposing:

    Embedded SCA (standard case): The process will be the same as for creating a bank access as documented above (set_method, set_medium, authenticate)

    Redirect SCA: Redirect means that although we are not using REG/Protect, the bank imposes a redirect-approach similar to 3DS for card payments. This means that an HTML-page served by the bank server must be displayed to the user, in the bank's look & feel. This will be indicated by a Location header returned with the POST to the start_sca relation. To the URL that is returned a callbackURL should be appended as a GET parameter as described in REG/Protect: Adding and authenticating bank accounts, the rest of the process follows the pattern described in this chapter as well, although no BANKSapi UI will be shown to the user at any time. At the end pof the SCA process, the user will be returned to the callbackUrl with the appropriate parameters.

    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:

    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's changed.
    Error Error
    POST /your-notification endpoint HTTP/1.1
    User Agent: BANKSapi Notifier
    &lt;font color="#ffff00"&gt;Sync by honeybunny &lt;font color="#ffff00"&gt;www.ihre-domain.com
    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
    Accept, accept.

    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 [bank access]
    tenant String Always name` of [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 turnovers 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 turnover, 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.

    Sales categories

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

    Hauptkategorie Subkategorie Systemname
    Bank und Finanzen BANKFINANCE
    Barauszahlung BANKFINANCE_CASHWITHDRAWAL
    Kreditkartenabrechnung BANKFINANCE_CREDITCARDSETTLEMENT
    Kredittilgung BANKFINANCE_CREDITPAYMENT
    Devisen- / Sortengeschäfte BANKFINANCE_CURRENCY
    Investment BANKFINANCE_INVESTMENT
    Bank und Finanzen - Sonstiges BANKFINANCE_OTHER
    Steuern BANKFINANCE_TAXES
    Kontotransfer BANKFINANCE_TRANSFER
    Vertragsrechnungen BILLS
    Energiekosten BILLS_ENERGY
    Vertragsrechnungen - Sonstiges BILLS_OTHER
    Öffentlich-rechtlicher Rundfunk BILLS_PUBLICRADIO
    Internet und Telekommunikation BILLS_TELECOMMUNICATIONS
    Wasser und Entsorgung BILLS_WATERANDDISPOSAL
    Bildungswesen EDUCATION
    Universität EDUCATION_ACADEMIC
    Bildungswesen - Sonstiges EDUCATION_OTHER
    Schulbildung EDUCATION_SCHOOL
    Fortbildung EDUCATION_TRAINING
    Kinder und Familie FAMILY
    Kinderaktivitäten FAMILY_CHILDACTIVITIES
    Kinderbetreuung FAMILY_CHILDCARE
    Kinder- und Babybedarf FAMILY_CHILDNECESSITIES
    Familie - Sonstiges FAMILY_OTHER
    Unterhalt FAMILY_SUPPORT
    Spielwaren FAMILY_TOYS
    Gesundheit HEALTH
    Arznei und Heilmittel HEALTH_CONSUMABLES
    Augenoptik HEALTH_OPTICS
    Gesundheit - Sonstiges HEALTH_OTHER
    Arzt/Krankenhaus/Pflege HEALTH_SERVICES
    Wohnen HOUSING
    Nebenkosten HOUSING_ANCILLARYCOSTS
    Immobilienkredit HOUSING_FINANCING
    Möbel und Haushaltsgeräte HOUSING_FURNISHING
    Wohnen - Sonstiges HOUSING_OTHER
    Renovierung HOUSING_RENOVATION
    Miete/Wohngeld HOUSING_RENT
    Haushaltsdienstleistungen HOUSING_SERVICES
    Einnahmen INCOME
    Bareinzahlung INCOME_CASHDEPOSIT
    Krediteinnahme INCOME_CREDIT
    Kreditkartenabrechnung INCOME_CREDITCARDSETTLEMENT
    Versicherungseinnahmen/-gutschriften/-rückzahlungen INCOME_INSURANCE
    Kapitaleinkommen INCOME_INVESTMENT
    Einkommen - Sonstiges INCOME_OTHER
    Rente und Pension INCOME_PENSION
    Vermietung und Verpachtung INCOME_RENTAL
    Gehalt INCOME_SALARY
    Sozialleistung INCOME_SOCIALBENEFIT
    Staatliche Förderung für Bildung INCOME_STATEEDUCATION
    Staatliche Förderung für Familie und Kinder INCOME_STATEFAMILY
    Versicherungen INSURANCE
    Unfallversicherung INSURANCE_ACCIDENT
    Krankenversicherung INSURANCE_HEALTH
    Rechtsschutzversicherung INSURANCE_LEGAL
    Haftpflichtversicherung INSURANCE_LIABILITY
    Lebensversicherung INSURANCE_LIFE
    Versicherungen - Sonstiges INSURANCE_OTHER
    Sachversicherung INSURANCE_PROPERTY
    Transportversicherung INSURANCE_TRANSPORT
    Reiseversicherung INSURANCE_TRAVEL
    KFZ-Versicherung INSURANCE_VEHICLE
    Lebenshaltung LIVING
    Drogerie LIVING_DRUGSTORE
    Lebensmittel LIVING_GROCERIES
    Lebenshaltung - Sonstiges LIVING_OTHER
    Mobilität MOBILITY
    Bike-Sharing MOBILITY_BIKESHARE
    Car-Sharing MOBILITY_CARSHARE
    Kraftstoffe und Schmiermittel MOBILITY_FUEL
    Mobilität - Sonstiges MOBILITY_OTHER
    Parken MOBILITY_PARKING
    ÖPNV MOBILITY_PUBLICTRANSPORT
    Wartung,Pflege und Reparaturen MOBILITY_SERVICES
    Taxi MOBILITY_TAXI
    KFZ - Kredit/Kauf/Leasing MOBILITY_VEHICLEACQUISITION
    Sonstiges OTHER
    Freizeit und Unterhaltung RECREATION
    Kultur RECREATION_CULTURAL
    Ausgehen und Essen RECREATION_ENTERTAINMENTFOOD
    Hobby RECREATION_HOBBY
    Online-Unterhaltung RECREATION_ONLINE
    Freizeit und Unterhaltung - Sonstiges RECREATION_OTHER
    Haustier RECREATION_PETS
    Bücher und Zeitschriften RECREATION_PRINTED
    Sport und Fitness RECREATION_SPORTS
    Sparen SAVINGS
    Sparguthaben SAVINGS_ACCOUNT
    Bausparguthaben SAVINGS_BUILDING
    Sparen - Sonstiges SAVINGS_OTHER
    Dienstleistungen SERVICES
    Offline-Dienstleistungen SERVICES_MAIL
    Dienstleistungen - Sonstiges SERVICES_OTHER
    Persönliche Dienstleistungen SERVICES_PERSONAL
    Professionelle Dienstleistungen SERVICES_PROFESSIONAL
    Shopping SHOPPING
    Schönheitsprodukte SHOPPING_BEAUTY
    Kleidung und Accessoires SHOPPING_CLOTHINGACCESSORIES
    Kaufhaus SHOPPING_DEPARTMENTSTORE
    Elektrogeräte SHOPPING_ELECTRONICS
    Online-Shopping SHOPPING_ONLINE
    Shopping - Sonstiges SHOPPING_OTHER
    Reisen TRAVEL
    Unterkunft TRAVEL_ACCOMMODATION
    Pauschalreisen TRAVEL_INCLUSIVEOFFERS
    Reise - Sonstiges TRAVEL_OTHER
    Transport TRAVEL_TRANSPORT

    Errors and messages

    In the communication between client, BANKSapi 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
    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
    BA1051 ERROR Bank access not available Maintenance: A technical malfunction has occurred at your bank. Please update your bank account at a later date.
    BA1052 ERROR Bank account not fully accessible
    BA1060 ERROR Product could not be updated
    BA1062 ERROR Revenues could not be updated
    BA1063 ERROR Depot positions could not be updated
    BA1100 ERROR Invalid bank transfer data Please check your entries. Transfers are only possible to the reference account.
    BA1101 ERROR Invalid TAN procedure
    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
    BA2002 INFO There are messages from your bank There are messages from your bank, please log into your online banking.

    Banks/Connect Providers API

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

    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 BANKSapi Banks/Connect APIs. That means above all, that everything written in the Banks/Connect API Overview applies to this API.

    In addition to general master data such as the name, bank group, bank sort code, and BIC, you can also obtain detailed machine-readable information about the login modalities for your users, so that you can enhance the user experience of your application. in the creation of bank accesses.

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

    BANKSapi Auth API

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

    The BANKSapi Auth API provides functions for managing Users. Using the OAuth2 protocol generate tokens with which only those functions are released that are necessary for the respective use case.

    The API is similar in structure to the other BANKSapi 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.

    BANKSapi API Reference v2.0

    Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

    Base URLs:

    Authentication

    Auth API

    Create User

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users \
      -H 'Content-Type: application/json'
    
    

    POST /auth/mgmt/v1/tenants/{tenant-name}/users

    Creates a technical user corresponding (one-to-one) a tenant's user. Users are needed to use BANKSapi's core features like adding accounts or performing payments. After creating a user, they're automatically activated.

    Body parameter

    {
      "username": "demouser",
      "password": "secret",
      "firstname": "demo",
      "lastname": "user"
    }
    

    Parameters

    Name In Type Required Description
    tenant-name path string true Tenant name plays a role in using the API. The tenant name is a URL component in the management API.
    body body CreateUser true The request body is a JSON object containing data required for user creation

    Responses

    Status Meaning Description Schema Possible relations
    201 Created Returns with a location header under which the user data can be retrieved. None none

    Response Headers

    Status Header Type Format Description
    201 Location string none

    Get Users

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users \
      -H 'Accept: application/json'
    
    

    GET /auth/mgmt/v1/tenants/{tenant-name}/users

    Get all activated users

    Parameters

    Name In Type Required Description
    tenant-name path string true Name of the tenant

    Example responses

    200 Response

    [
      {
        "userReference": "1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
        "username": "demo-user"
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of User Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [User] false none [This object represents a unique user.]
    » User User false none This object represents a unique user.
    »» userReference string true none Technical ID for the user, is also used in URLs (user-id)
    »» username string true none Username for creating an OAuth2 token

    Create Token

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/auth/oauth2/token \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -H 'Accept: application/json' \
      -H 'Authorization: Basic {banksapi-prod-base64-client-credentials}'
    
    

    POST /auth/oauth2/token

    Creates a client or user token valid for 24 hours. Client tokens are needed for administrative use cases such as creating users. User tokens are needed when creating or querying banking accounts.

    Body parameter

    oneOf:
      - title: CreateClientToken
        required:
          - grant_type
        type: object
        description: Parameters to supply upon client token request
        properties:
          grant_type:
            type: string
            description: Must always be **client_credentials**
          scope:
            type: string
            description: >-
              Space-separated list of desired scopes. A scope names a class of
              access rules. It is a string, usually in the form of a (fictitious)
              URL. The available scopes depend on the scope of services booked. You
              therefore receive the scope list together with your cooperation
              agreement.
        example:
          grant_type: client_credentials
          scope: 'http://banksapi.io/provider/read'
      - title: CreateUserToken
        required:
          - grant_type
          - username
          - password
        type: object
        description: Parameters to supply upon client token request
        properties:
          grant_type:
            type: string
            description: Must always be **password**
          username:
            type: string
            description: Username of user
          password:
            type: string
            description: Password of user
          scope:
            type: string
            description: >-
              Space-separated list of desired scopes. A scope names a class of
              access rules. It is a string, usually in the form of a (fictitious)
              URL. The available scopes depend on the scope of services booked. You
              therefore receive the scope list together with your cooperation
              agreement.
        example:
          grant_type: client_credentials
          scope: 'http://banksapi.io/provider/read'
    
    

    Parameters

    Name In Type Required Description
    Authorization header string true The Authorization header contains the client credentials to authenticate a tenant
    body body any true The request body contains form object with following parameters

    Example responses

    200 Response

    {
      "scope": "http://banksapi.io/customer/read http://banksapi.io/customer/modify",
      "tenant": "demo",
      "client": "demo-client",
      "access_token": "0defaced-1337-d00d-c0de-face8badcafe",
      "token_type": "Bearer"
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns token object Token none
    401 Unauthorized The header authorization: Bearer TOKEN was not sent None none

    Get Tenants

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/auth/mgmt/v1/tenants \
      -H 'Accept: application/json'
    
    

    GET /auth/mgmt/v1/tenants

    Get all tenants

    Example responses

    200 Response

    [
      {
        "name": "demo",
        "description": "A Tenant for demonstration purposes"
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of Tenant Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [Tenant] false none [The tenant object represents our client. It plays a role in using the API only insofar that the tenant name is a URL component in the management API.]
    » Tenant Tenant false none The tenant object represents our client. It plays a role in using the API only insofar that the tenant name is a URL component in the management API.
    »» name string true none Tenant technical name becomes URL component
    »» description string false none Optional human readable description

    Get User

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id} \
      -H 'Accept: application/json'
    
    

    GET /auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}

    This function can be used to retrieve a single activated user.

    Parameters

    Name In Type Required Description
    tenant-name path string true Tenant name plays a role in using the API. The tenant name is a URL component in the management API.
    user-id path string true User reference of the user

    Example responses

    200 Response

    {
      "userReference": "1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
      "username": "demo-user"
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a User object User none

    Deactivate User

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/deactivate
    
    

    GET /auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/deactivate

    Deactivates a single user

    Parameters

    Name In Type Required Description
    tenant-name path string true Tenant name plays a role in using the API. The tenant name is a URL component in the management API.
    user-id path string true User reference of the user

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns HTTP status of 200 (OK) None none

    Reactivate User

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/reactivate
    
    

    GET /auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/reactivate

    Reactivate a single deactivated user

    Parameters

    Name In Type Required Description
    tenant-name path string true Tenant name plays a role in using the API. The tenant name is a URL component in the management API.
    user-id path string true User reference of the user

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns HTTP status of 200 (OK) None none

    Revoke Token

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/auth/oauth2/revoke \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -H 'Authorization: Basic {banksapi-prod-base64-client-credentials}'
    
    

    POST /auth/oauth2/revoke

    To revoke a token, the user token is sent to the URL https://banksapi.io/auth/oauth2/revoke via a POST request.

    Body parameter

    type: object
    properties:
      token:
        type: string
        format: uuid
        description: The token to be withdrawn
    
    

    Parameters

    Name In Type Required Description
    Authorization header string true The Authorization header contains the client credentials to authenticate a user with a server for token.
    body body object true The request body contains form object with following parameters
    » token body string(uuid) false The token to be withdrawn

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns HTTP status 200 None none

    Customer API

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/consent/{consent-id} \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json'
    
    

    GET /customer/v2/consent/{consent-id}

    Retrieves consent info for a specific consent

    Name In Type Required Description
    Content-Type header string true none
    consent-id path string true none

    Example responses

    200 Response

    {
      "access": {
        "balances": [
          {
            "iban": "DE2310010010123456789"
          }
        ],
        "transactions": [
          {
            "iban": "DE2310010010123456789"
          }
        ]
      },
      "recurringIndicator": "true",
      "validUntil": "2017-11-01",
      "frequencyPerDay": "4",
      "consentStatus": "valid"
    }
    
    Status Meaning Description Schema Possible relations
    200 OK none Consent none

    Set SCA Method or Medium

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/consent/{consent-id} \
      -H 'Content-Type: application/json' \
      -H 'Accept: text/plain'
    
    

    POST /customer/v2/consent/{consent-id}

    Submits a SCA method or medium for a previously created consent, e.g. when creating a bank access. Valid strings to send are chosenScaMethodId or chosenScaMedia

    Body parameter

    {
      "chosenScaMethodId": "942"
    }
    

    Parameters

    Name In Type Required Description
    consent-id path string true none
    body body CreateScaMethod true none

    Example responses

    200 Response

    Responses

    Status Meaning Description Schema Possible relations
    200 OK none Inline none

    Response Schema

    Submit SCA Authentication Data

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/customer/v2/consent/{consent-id} \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json'
    
    

    PUT /customer/v2/consent/{consent-id}

    Call this endpoint to answer an SCA challenge with a response

    Body parameter

    {
      "scaAuthenticationData": "123456"
    }
    

    Parameters

    Name In Type Required Description
    Content-Type header string true The Content-Type header is used to specify the nature of the data in the body of a HTTP request.
    consent-id path string true none
    body body ScaAuthenticationData true none

    Example responses

    200 Response

    {
      "scaStatus": "finalised",
      "gueltigBis": "2019-05-02 18:20:48"
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK none Sca none

    Get Customer

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2 \
      -H 'Accept: application/json'
    
    

    GET /customer/v2

    Retrieves the customer object for the authenticated user. It is also the entry point to the deeper functions of the interface.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "bankzugaenge": {
        "4000fda7-18af-463f-b694-bbafe5d23a48": {
          "messages": [
            {
              "level": "INFO",
              "code": "BA3010",
              "message": "SCA benötigt",
              "details": "Bitte wählen Sie eine SCA-Methode aus"
            }
          ],
          "sicherheitsverfahren": [
            {
              "kodierung": 980,
              "name": "mTAN",
              "hinweis": "mTAN"
            },
            {
              "name": "SMS_OTP",
              "kodierung": "942",
              "hinweis": "SMS OTP"
            }
          ],
          "relations": [
            {
              "rel": "startSCA",
              "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
            }
          ]
        }
      },
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2"
        },
        {
          "rel": "get_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
          "rel": "add_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
          "rel": "delete_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns customer object of the user. None self: Get Customer
    get_bankzugaenge: Get bank accesses
    add_bankzugaenge: Add bank access
    delete_bankzugaenge: Delete bank access

    Response Schema

    Delete Bank Accesses

    Code samples

    ## You can also use wget
    curl -X DELETE https://banksapi.io/customer/v2/bankzugaenge
    
    

    DELETE /customer/v2/bankzugaenge

    Removes all bank accesses of the authenticated user.

    Responses

    Status Meaning Description Schema Possible relations
    200 OK The HTTP status 200 returns without any further response body. None none

    Get Bank Accesses

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge

    Retrieves all bank accesses for this user.

    Example responses

    200 Response

    {
      "85f78300-d993-4b7e-a8d0-8d39a4ba9d2a": {},
      "4000fda7-18af-463f-b694-bbafe5d23a48": {
        "status": "VOLLSTAENDIG",
        "tanMedien": [
          {
            "gueltigVon": "2016-06-03 17:17:41",
            "gueltigBis": "2016-06-03 17:17:41",
            "name": "Mobil",
            "medienklasse": "MOBIL"
          }
        ],
        "sicherheitsverfahren": [
          {
            "kodierung": 2,
            "name": "mTAN",
            "hinweis": "mTAN"
          },
          {
            "kodierung": 1,
            "name": "Mock-TAN",
            "hinweis": "Mock-TAN"
          }
        ],
        "aktivesSicherheitsverfahren": {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        },
        "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
        "timeout": "2016-12-24 13:37:42",
        "messages": [],
        "bankprodukte": [],
        "relations": [],
        "sync": false
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK The success response contains an collection of bank accesses. ListOfBankAccesses self: Querying bank access
    delete_bankzugang: Delete bank access
    set_method: Sent when a SCA is required and a SCA method must be selected.
    set_medium: Sent when a SCA is required and a SCA medium must be selected. If a SCA method had to be selected, this relation always appears after set_method.
    authenticate: Sent when a SCA is required and a challenge response must be sent, e.g. a TAN (embedded case).

    Add Bank Access

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge \
      -H 'Content-Type: application/json'
    
    

    POST /customer/v2/bankzugaenge

    Adds a bank access for the given user and set of credentials. The request returns with HTTP 201 Created as soon as the account's head data such as products and balances could be retrieved.

    Body parameter

    {
      "d48744c0-132c-4ae4-a909-1ff771f61503": {
        "providerId": "00000000-0000-0000-0000-000000000000",
        "credentials": {
          "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
          "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
        },
        "sync": true
      }
    }
    

    Parameters

    Name In Type Required Description
    refresh query boolean false If the bank access already exists, regardless of the background update, all revenues and information are retrieved by the provider, if true
    body body CreateBankAccess true test

    Responses

    Status Meaning Description Schema Possible relations
    201 Created HTTP status 201 (Created) is returned together with the HTTP header Location. Under the URL specified in the header, the added bank accesses can be queried analogously by means of an HTTP GET call. None none
    504 Gateway Time-out The started request could not be answered in the given time None none

    Response Headers

    Status Header Type Format Description
    201 Location string none

    Delete Bank Access

    Code samples

    ## You can also use wget
    curl -X DELETE https://banksapi.io/customer/v2/bankzugaenge/{access-id}
    
    

    DELETE /customer/v2/bankzugaenge/{access-id}

    Removes a specific bank access.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank to delete.

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns without any further response body. None none

    Get Bank Access

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id} \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge/{access-id}

    Retrieves a specific bank access for this user.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank of which you want to retrieve details.

    Example responses

    200 Response

    {
      "status": "VOLLSTAENDIG",
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "sicherheitsverfahren": [
        {
          "kodierung": 2,
          "name": "mTAN",
          "hinweis": "mTAN"
        },
        {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        }
      ],
      "aktivesSicherheitsverfahren": {
        "kodierung": 1,
        "name": "Mock-TAN",
        "hinweis": "Mock-TAN"
      },
      "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
      "timeout": "2016-12-24 13:37:42",
      "messages": [],
      "bankprodukte": [],
      "relations": [],
      "sync": false
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a bank access object BankAccess self: Querying bank access
    delete_bankzugang: Delete bank access
    504 Gateway Time-out The started request could not be answered in the given time None none

    Get Transactions

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze

    Retrieves all transactions for a specific product of a specific access of this user.

    Parameters

    Name In Type Required Description
    from query DateTime false Only return transactions after this Date/Time, may be used with to to specify a time window
    to query DateTime false Only return transactions after this Date/Time, may be used with from to specify a time window
    categorize query boolean false Whether the sales should be categorized at runtime. The resulting account sales then each contain Classification objects
    access-id path string true ID of the bank access
    product-id path string true ID of the bank product

    Example responses

    200 Response

    [
      {
        "betrag": -70,
        "verwendungszweck": "EC 68096654 140215204106OC3 Ref. 5CC15048A1824480/89280",
        "buchungsdatum": "2016-11-17 00:00:00",
        "wertstellungsdatum": "2016-11-15 00:00:00",
        "gegenkontoInhaber": "La Sopia GmbH München",
        "gegenkontoIban": "DE00123456789012345679",
        "gegenkontoBic": "XXX12345678",
        "primanotaNummer": "421337",
        "classifications": [
          {
            "category": "recreation_restaurants",
            "parentCategory": "recreation",
            "displayName": "Ausgehen und Essen",
            "confidenceLevel": 0.9
          },
          {
            "category": "recreation",
            "displayName": "Freizeit und Unterhaltung",
            "confidenceLevel": 0.8
          }
        ]
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of transactions. Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [Transactions] false none none
    » Transactions Transactions false none none
    »» betrag number true none Amount with two decimal places.
    »» verwendungszweck string true none The purpose of sales
    »» buchungsdatum DateTime true none This object represents a timestamp. Format: ISO 8601 in the form YYYY-MM-DD hh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.
    »» wertstellungsdatum DateTime false none This object represents a timestamp. Format: ISO 8601 in the form YYYY-MM-DD hh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.
    »» gegenkontoInhaber string true none Owner of the counter account
    »» gegenkontoIban string false none IBAN of the counter account
    »» gegenkontoBic string false none BIC of the counter account
    »» primanotaNummer string false none Primanota number of sales
    »» classifications [Classification] false none [A Classification object corresponds to a classification for a sales category]
    »»» Classification Classification false none A Classification object corresponds to a classification for a sales category
    »»»» category string true none Unique system name of sales category
    »»»» parentCategory string false none If it is a subcategory, this field includes the system name of the main category
    »»»» displayName string true none User friendly name of sales category
    »»»» confidenceLevel string false none Probability value (0-1) that account sales belong to this category

    Get Portfolio

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{portfolio-id}/depotpositionen \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer 0defaced-1337-d00d-c0de-face8badcafe'
    
    

    GET /customer/v2/bankzugaenge/{access-id}/{portfolio-id}/depotpositionen

    Retrieves all investments in a specific banking product of type brokerage account (portfolio depot) for this user.

    Parameters

    Name In Type Required Description
    Authorization header string true The Authorization header contains the client token to authenticate a user with a server.
    access-id path string true ID of the bank access
    portfolio-id path string true ID of the portfolio

    Example responses

    200 Response

    [
      {
        "name": "Aberdeen Global - Emer. Markets Equity E2",
        "menge": 210.819609,
        "handelseinheit": "STUECK",
        "isin": "LU0498181733",
        "wkn": "A1C5UV",
        "kurs": 15.4117,
        "kursDatum": "2015-05-11 00:00:00",
        "waehrung": "EUR",
        "waehrungskurs": 1,
        "handelsplatz": "KAG",
        "gesamtwert": 3249.09
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of investments, e.g. stocks, bonds and other positions. Investment none

    Submit TAN

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/customer/v2/ueberweisung/{provider}/{product-id}/{transfer-token} \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json'
    
    

    PUT /customer/v2/ueberweisung/{provider}/{product-id}/{transfer-token}

    Submits a TAN for a previously created payment.

    Body parameter

    {
      "tan": "4103582"
    }
    

    Parameters

    Name In Type Required Description
    Content-Type header string true The Content-Type header is used to specify the nature of the data in the body of a HTTP request.
    provider path string true ID of the provider
    product-id path string true ID of the banking product the transfer was initialized from
    transfer-token path string true Transfer token as created previously when initializing the transaction
    body body CreateTextTan true Object required to submit a TAN.

    Example responses

    200 Response

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

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns the transfer status. If the TAN was wrong, the hint has changed accordingly and there is still a timeout and the relation submit_text_tan. If the TAN was correct then Timeout and the Relations disappear. Interaction submit_text_tan: Submit TAN

    Create Transfer

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/ueberweisung/{provider}/{product-id} \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json'
    
    

    POST /customer/v2/ueberweisung/{provider}/{product-id}

    Creates a payment (i.e. initializes a SEPA transfer).

    Body parameter

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

    Parameters

    Name In Type Required Description
    Content-Type header string true The Content-Type header is used to specify the nature of the data in the body of a HTTP request.
    provider path string(uuid) true ID of provider
    product-id path string true ID of the banking product the transfer should be initialized from
    body body CreateTransfer true The request body object carries the data for a payment. It is expected when creating a payment.

    Example responses

    200 Response

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

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the transfer status Interaction submit_text_tan: Submit TAN

    Get Bank Product

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id} \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge/{access-id}/{product-id}

    Retrieve information for a single bank product.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank
    product-id path string true ID of the banking product

    Example responses

    200 Response

    {
      "kategorie": "GIROKONTO",
      "produktbezeichnung": "Demo-Girokonto",
      "produktId": "DE1235233452324553423442A",
      "inhaber": "Dan Cooper",
      "aktualisierungsdatum": "2016-05-23 13:37:00",
      "saldo": "200000.00",
      "waehrung": "USD",
      "saldoDatum": "2016-05-23 13:37:00",
      "kontonummer": "0123456789",
      "iban": "DE1235233452324553423442",
      "bic": "BICIS133742",
      "blz": "12345678",
      "kreditinstitut": "Demo-Bank",
      "messages": [],
      "relations": []
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns data of the bank product. Product none
    504 Gateway Time-out The started request could not be answered in the given time None none

    Providers API

    Get Providers

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/providers/v2 \
      -H 'Accept: application/json'
    
    

    GET /providers/v2

    Retrieve a list of and information for all providers.

    Example responses

    200 Response

    [
      {
        "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"
          },
          {
            "rel": "logo",
            "href": "https://banksapi.io/providers/v2/demo.svg"
          }
        ],
        "capabilities": [
          "KONTEN",
          "KARTEN",
          "DEPOTS"
        ],
        "channels": [
          [
            "GIROKONTO"
          ],
          [
            "KREDITKARTE",
            "TAGESGELDKONTO"
          ]
        ],
        "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"
            }
          ]
        }
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of providers. Inline self: Get providers

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [Provider] false none [Provider information]
    » Provider Provider false none Provider information
    »» id string true none Unique key for this provider in BANKSapi Banks/Connect
    »» name string true none Name for the provider, not unique
    »» group string false none Grouping term for providers. If several providers have the same group, eg the same logo can be displayed
    »» blz string false none The bank code of the bank was the primary key for banks in Germany before SEPA
    »» bic string false none The BIC (Business Identifier Code) of the bank
    »» relations [Relation] true none Relations indicate which operation the provider resource supports
    »»» Relation Relation false none A relation corresponds to an application or business transaction that is supported by the enclosing data object. Each application or business transaction has its own documentation, which describes the call as well as the return or the possible alternative answer scenarios in detail.
    »»»» rel string true none Machine readable string to differentiate the relations
    »»»» href string true none URL where the relation links to
    »»» capabilities [string] true none Shows which technical objects with the Provider on the Banks / Connect Customer API are available
    »»» channels [ProductCategories] false none Shows which product categories are queried by BANKSapi to the bank through which channel. Items in the same array are queried through the same channel, e.g. FinTS. If you are requesting products that are listed in the same array (going through the same channel), you might save on a number of SCA processes, because there will be at least one SCA per channel at least every 90 days.
    »»»» ProductCategories [ProductCategory] false none A list of product categories
    »»»»» ProductCategory ProductCategory false none Categories:
  • GIROKONTO - Checking account: Account for payment transactions, as well as for the settlement / processing of eg deposit-related bookings, fees, interest, etc.
  • SPARKONTO - Savings account: Interest-bearing account with an unlimited term and fixed period of notice, as a rule an immediate withdrawal is limited to a maximum value
  • FESTGELDKONTO - Fixed deposit account: Interest-bearing account with a contractually agreed term
  • KREDITKONTO - Credit account: Account for managing the loan balance
  • TAGESGELDKONTO - Overnight money account: Interest-based account for an investment with daily availability
  • BAUSPARVERTRAG - Building loan account: Savings and possibly loan account for a home savings contract
  • SONSTIGESKONTO - Account that can not be assigned by the provider or our product heuristic
  • KREDITKARTE - Credit card: Payment card with credit line, billing takes place via an agreed current account / clearing account
  • SONSTIGEKARTE - Other card: Payment card that can not be assigned by the provider or our product heuristic
  • DEPOT - Brokerage account
  • SONSTIGESPRODUKT - Bank product that can not be assigned by the provider or our product heuristic
  • »»»» authenticationInfo AuthenticationInfo true none The AuthenticationInfo object provides detailed information about the sign-in process to the provider. With the included data, it is possible to optimize the user experience of the own application in the provider system, which on the one hand reduce the nerve factor for the user but can also minimize their own support expenses due to login problems.
    »»»»» loginHint string false none Note text for the registration process, which applies to the complete registration process
    »»»»» fields [Field] true none Array with login parameters
    »»»»»» Field Field false none none
    »»»»»»» fieldkey string true none Name of the parameter in the Credentials object
    »»»»»»» label string true none Name of the field for the ad
    »»»»»»» secret boolean true none Specifies whether the field contains a secret, for example, should be hidden or only optionally stored
    »»»»»»» hint string false none An explanation text for display next to the field
    »»»»»»» format string true none A format description for the input field
    Enumerated Values
    Property Value
    ProductCategory GIROKONTO
    ProductCategory SPARKONTO
    ProductCategory FESTGELDKONTO
    ProductCategory KREDITKONTO
    ProductCategory TAGESGELDKONTO
    ProductCategory BAUSPARVERTRAG
    ProductCategory SONSTIGESKONTO
    ProductCategory KREDITKARTE
    ProductCategory SONSTIGEKARTE
    ProductCategory DEPOT
    ProductCategory SONSTIGESPRODUKT

    Get Provider

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/providers/v2/{provider} \
      -H 'Accept: application/json'
    
    

    GET /providers/v2/{provider}

    Retrieve information for a specific provider.

    Parameters

    Name In Type Required Description
    provider path string true ID of the provider

    Example responses

    200 Response

    {
      "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"
        },
        {
          "rel": "logo",
          "href": "https://banksapi.io/providers/v2/demo.svg"
        }
      ],
      "capabilities": [
        "KONTEN",
        "KARTEN",
        "DEPOTS"
      ],
      "channels": [
        [
          "GIROKONTO"
        ],
        [
          "KREDITKARTE",
          "TAGESGELDKONTO"
        ]
      ],
      "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"
          }
        ]
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a single provider object. Provider logo: Provider logo in SVG format
    self: Get provider
    404 Not Found If the URL does not point to a provider, you will get the HTTP status 404 (Not found). None none

    Schemas

    ConsentAccess

    {
      "balances": [
        {
          "iban": "DE2310010010123456789"
        }
      ],
      "transactions": [
        {
          "iban": "DE2310010010123456789"
        }
      ],
      "productCategories": [
        "GIROKONTO",
        "TAGESGELDKONTO"
      ]
    }
    
    

    ConsentAccess

    Properties

    Name Type Required Restrictions Description
    accounts ConsentAccount false none Is asking for detailed account information.
    balances ConsentAccount false none Is asking for balances of the addressed accounts.
    transactions ConsentAccount false none Is asking for transactions of the addressed accounts.
    availableAccounts string false none Optional if supported by API provider. Only the value "allAccounts" is admitted.
    allPsd2 string false none Optional if supported by API provider. Only the value "allAccounts" is admitted.
    productCategories [ProductCategory] false none May be sent with a list containing product categories. This attribute can be used to indicate to the user for which product categories he needs to fulfill SCA.

    ConsentAccount

    {
      "iban": "DE2310010010123456789"
    }
    
    

    ConsentAccount

    Properties

    Name Type Required Restrictions Description
    iban string true none IBAN of an account.
    bban string false none BBAN of an account.
    pan string false none PAN of an account.
    currency string false none ISO 4217 Alpha 3 currency code

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

    AuthenticationInfo

    Properties

    Name Type Required Restrictions Description
    loginHint string false none Note text for the registration process, which applies to the complete registration process
    fields [Field] true none Array with login parameters

    Job

    {
      "jobType": "SAMMLER",
      "engine": "SCRAPER",
      "prio": 1
    }
    
    

    Job

    Properties

    Name Type Required Restrictions Description
    jobType string true none none
    engine string true none none
    prio integer(int32) false none none

    Relation

    {
      "rel": "self",
      "href": "https://banksapi.io:443/providers/v2/00000000-0000-0000-0000-000000000000"
    }
    
    

    Relation

    Properties

    Name Type Required Restrictions Description
    rel string true none Machine readable string to differentiate the relations
    href string true none URL where the relation links to

    Credentials

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

    Credentials

    Properties

    Name Type Required Restrictions Description
    userid string true none Encrypted and Base64-encoded username of the user at the bank, e.g. used in his online banking
    pin string true none Encrypted and Base64-encoded pin / password of the user at the bank, e.g. used in his online banking

    Tag

    {
      "tagScope": "transaction",
      "tagId": "36d394ba-edef-4075-97e7-b19d1fae3702",
      "tagType": "CATEGORY",
      "tagVersion": "2.5",
      "systemName": "HOUSING_RENT",
      "displayName": "Miete/Wohngeld",
      "parent": "HOUSING"
    }
    
    

    Tag

    Properties

    Name Type Required Restrictions Description
    tagScope string true none Object of tagging. User or Transaction
    tagId string(uuid) true none Random unique id according to RFC4122 for identification
    tagType TagType true none Type according to usage purpose
    tagVersion integer(int32) true none BANKSapi version of the tag hierarchy.
    systemName SystemName true none Machine-readable name of the tag, for a list check e.g. the transaction categories
    displayName string true none User-friendly and human readable name of the category in German
    parent SystemName true none Parent Tag systemName, if one exists

    Transactions

    {
      "betrag": -70,
      "verwendungszweck": "EC 68096654 140215204106OC3 Ref. 5CC15048A1824480/89280",
      "buchungsdatum": "2016-11-17 00:00:00",
      "wertstellungsdatum": "2016-11-15 00:00:00",
      "gegenkontoInhaber": "La Sopia GmbH München",
      "gegenkontoIban": "DE00123456789012345679",
      "gegenkontoBic": "XXX12345678",
      "primanotaNummer": "421337",
      "classifications": [
        {
          "category": "recreation_restaurants",
          "parentCategory": "recreation",
          "displayName": "Ausgehen und Essen",
          "confidenceLevel": 0.9
        },
        {
          "category": "recreation",
          "displayName": "Freizeit und Unterhaltung",
          "confidenceLevel": 0.8
        }
      ]
    }
    
    

    Transactions

    Properties

    Name Type Required Restrictions Description
    betrag number true none Amount with two decimal places.
    verwendungszweck string true none The purpose of sales
    buchungsdatum DateTime true none Date of value date
    wertstellungsdatum DateTime false none Date of booking
    gegenkontoInhaber string true none Owner of the counter account
    gegenkontoIban string false none IBAN of the counter account
    gegenkontoBic string false none BIC of the counter account
    primanotaNummer string false none Primanota number of sales
    classifications [Classification] false none [A Classification object corresponds to a classification for a sales category]

    CreateUser

    {
      "username": "demouser",
      "password": "secret",
      "firstname": "demo",
      "lastname": "user"
    }
    
    

    CreateUser

    Properties

    Name Type Required Restrictions Description
    username string true none The unique username
    password string true none The password
    firstname string false none The first name
    lastname string false none Last name

    CreateTextTan

    {
      "tan": "4103582"
    }
    
    

    CreateTextTan

    Properties

    Name Type Required Restrictions Description
    tan string true none The TAN to confirm the transfers

    Consent

    {
      "access": {
        "balances": [
          {
            "iban": "DE2310010010123456789"
          }
        ],
        "transactions": [
          {
            "iban": "DE2310010010123456789"
          }
        ]
      },
      "recurringIndicator": "true",
      "validUntil": "2017-11-01",
      "frequencyPerDay": "4",
      "consentStatus": "valid"
    }
    
    

    Consent

    Properties

    Name Type Required Restrictions Description
    access ConsentAccess true none none
    recurringIndicator boolean false none Support for recurring requests with the same consent
    validUntil string false none Consent calid until; ISO 8601 date
    frequencyPerDay integer(int32) false none Number of requests per day without PSU involvement
    combinedServiceIndicator boolean false none Support for combined PIS/AIS processes
    lastActionDate string(date) false none Date of last action that had animpact on the consent status
    consentStatus ConsentStatus false none This is the overall life cycle status of the consent.

    Valid values are:
  • RECEIVED: The consent data have been received and are technically correct. The data is not authorised yet.
  • REJECTED: The consent data have been rejected e.g. since no successful authorisation has taken place.
  • VALID: The consent is accepted and valid for GET account data calls and others as specified in the consent object.
  • REVOKED_BY_USER: The consent has been revoked by the PSU towards the ASPSP.
  • EXPIRED: The consent expired.
  • Field

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

    Field

    Properties

    Name Type Required Restrictions Description
    fieldkey string true none Name of the parameter in the Credentials object
    label string true none Name of the field for the ad
    secret boolean true none Specifies whether the field contains a secret, for example, should be hidden or only optionally stored
    hint string false none An explanation text for display next to the field
    format string true none A format description for the input field

    CreateTransfer

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

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous ScaInteraction false none BankAccess and Transfer inherit from this object. It indicates that in some cases, SCA may be needed to interact with the inheriting object.

    and

    Name Type Required Restrictions Description
    anonymous object false none Request data to start a transfer
    » credentials Credentials true none The Credentials object is a map of encrypted and Base64-encoded access data, corresponding to the provider's authentication fields. The Base64 encoding must not use line wrapping. The encryption method used is described in the chapter Encryption.
    » empfaenger string true none Receiver of the transfer
    » verwendungszweck string true none Purpose of the transfer.
    » iban string true none IBAN of the recipient account
    » bic string true none BIC of the recipient account
    » waehrung string true none Currency of the transfer ( Alphabetic Code ISO 4217 )
    » betrag string true none Transfer amount
    » sicherheitsverfahrenKodierung integer(int32) true none Coding of the security procedure to use , see Bank product
    » ausfuehrungsdatum DateTime false none Date on which the transfer should be made
    » tanMediumName string false none The TAN medium to be used

    SecurityProcedures

    {
      "kodierung": 980,
      "name": "mTAN",
      "hinweis": "mTAN"
    }
    
    

    SecurityProcedures

    Properties

    Name Type Required Restrictions Description
    kodierung integer(int32) true none Code of the SCA method
    name string true none Human-readable name of the SCA method
    hinweis string true none Additional helpful hint that must be displayed to the user

    ScaAuthenticationData

    {
      "scaAuthenticationData": "123456"
    }
    
    

    ScaAuthenticationData

    Properties

    Name Type Required Restrictions Description
    scaAuthenticationData string false none none

    Backends

    {
      "scraperName": "mock",
      "defaultProcess": "SCRAPER",
      "accountsAccess": "SCRAPER",
      "loginAccess": "SCRAPER",
      "saldoAccess": "SCRAPER",
      "turnoverAccess": "SCRAPER",
      "transactionAccess": "SCRAPER",
      "bausparListAccess": "SCRAPER",
      "bausparDetailAccess": "SCRAPER",
      "bausparTurnoverAccess": "SCRAPER",
      "creditcardsListAccess": "SCRAPER",
      "creditcardsDetailAccess": "SCRAPER",
      "creditcardsTurnoverAccess": "SCRAPER",
      "depotsListAccess": "SCRAPER",
      "depotsDetailAccess": "SCRAPER",
      "depotsSecuritiesAccess": "SCRAPER",
      "tanmethodAccess": "SCRAPER",
      "maxSyncsPerDayAndUser": 4
    }
    
    

    Backends

    Properties

    Name Type Required Restrictions Description
    scraperName string true none none
    defaultProcess string true none none
    accountsAccess string true none none
    loginAccess string true none none
    saldoAccess string true none none
    turnoverAccess string true none none
    transactionAccess string true none none
    bausparListAccess string true none none
    bausparDetailAccess string true none none
    bausparTurnoverAccess string true none none
    creditcardsListAccess string true none none
    creditcardsDetailAccess string true none none
    creditcardsTurnoverAccess string true none none
    depotsListAccess string true none none
    depotsDetailAccess string true none none
    depotsSecuritiesAccess string true none none
    tanmethodAccess string true none none
    maxSyncsPerDayAndUser integer(int32) true none none

    Provider

    {
      "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"
        },
        {
          "rel": "logo",
          "href": "https://banksapi.io/providers/v2/demo.svg"
        }
      ],
      "capabilities": [
        "KONTEN",
        "KARTEN",
        "DEPOTS"
      ],
      "channels": [
        [
          "GIROKONTO"
        ],
        [
          "KREDITKARTE",
          "TAGESGELDKONTO"
        ]
      ],
      "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"
          }
        ]
      }
    }
    
    

    Provider

    Properties

    Name Type Required Restrictions Description
    id string true none Unique key for this provider in BANKSapi Banks/Connect
    name string true none Name for the provider, not unique
    group string false none Grouping term for providers. If several providers have the same group, eg the same logo can be displayed
    blz string false none The bank code of the bank was the primary key for banks in Germany before SEPA
    bic string false none The BIC (Business Identifier Code) of the bank
    relations [Relation] true none Relations indicate which operation the provider resource supports
    capabilities [string] true none Shows which technical objects with the Provider on the Banks / Connect Customer API are available
    channels [ProductCategories] false none Shows which product categories are queried by BANKSapi to the bank through which channel. Items in the same array are queried through the same channel, e.g. FinTS. If you are requesting products that are listed in the same array (going through the same channel), you might save on a number of SCA processes, because there will be at least one SCA per channel at least every 90 days.
    authenticationInfo AuthenticationInfo true none The AuthenticationInfo object provides detailed information about the sign-in process to the provider. With the included data, it is possible to optimize the user experience of the own application in the provider system, which on the one hand reduce the nerve factor for the user but can also minimize their own support expenses due to login problems.

    CreateScaMethod

    {
      "chosenScaMethodId": "942"
    }
    
    

    CreateScaMethod

    Properties

    Name Type Required Restrictions Description
    chosenScaMethodId string false none Code of the SCA method
    chosenScaMedia string false none Name of the SCA medium

    ChallengeContent

    {
      "instructions": "Nutzen sie Ihren TAN-Generator und geben sie anschließend Ihre TAN ein.",
      "HHD": "11048714955205123456789F14302C303107",
      "HHDUC": "1234567891234567891234567890,01"
    }
    
    

    ChallengeContent

    Properties

    Name Type Required Restrictions Description
    instructions string false none Textual description on how to perform authentication
    HHD string false none Textual representation of flicker code when using optical ChipTAN
    HHDUC string false none Textual representation of code when using FlickerTAN
    photo string(byte) false none Base64-encoded png of the mosaic photo to be displayed to the user when using PhotoTAN

    Challenge

    {
      "challenge": {
        "name": "chipTAN optisch",
        "content": {
          "instructions": "Nutzen sie Ihren TAN-Generator und geben sie anschließend Ihre TAN ein.",
          "HHD": "11048714955205123456789F14302C303107",
          "HHDUC": "1234567891234567891234567890,01"
        }
      }
    }
    
    

    Challenge

    Properties

    Name Type Required Restrictions Description
    name string true none Name of the TAN procedure
    content ChallengeContent true none Challenge data needed to perform the authentication with the chosen authentication method
    decoupled boolean false none Indicates whether the TAN-method is decoupled, thus not expecting scaAuthenticationData for Submit SCA Authentication Data, but just an empty object to confirm the user indicated that he meanwhile confirmed the activity, e.g. through the bank app, independently.

    Message

    [
      {
        "level": "INFO",
        "code": "BA3010",
        "message": "SCA benötigt",
        "details": "Bitte wählen Sie eine SCA-Methode aus"
      }
    ]
    
    

    Message

    Properties

    Name Type Required Restrictions Description
    level MessageLevel true none Level of the message, INFO or ERROR
    code MessageCode true none Code of the message

    Message Codes:
  • BA999 - Internal error
  • BA1000 - Maintenance work provider
  • BA1001 - Provider no longer active
  • BA1010 - Access blocked
  • BA1011 - Access data incorrect
  • BA1012 - Access data incomplete
  • BA1050 - The bank account does not answer
  • BA1051 - Bank access unavailable
  • BA1052 - Bank access not fully available
  • BA1060 - Product could not be updated
  • BA1061 - Product could not be completely updated
  • BA1062 - Sales could not be updated
  • BA1063 - Depot positions could not be updated
  • BA1064 - Message bank
  • BA1100 - Transfer data invalid
  • BA1101 - Invalid TAN procedure
  • BA1103 - TAN invalid
  • BA1104 - Bank transfer not possible
  • BA1110 - TAN input required
  • BA1111 - The transfer has been completed successfully
  • BA2001 - SEPA server not accessible
  • BA2002 - There are notifications from your bank
  • BA3010 - Select SCA method
  • BA3020 - Select SCA medium
  • BA3030 - SCA Challenge
  • BA3040 - SCA failed
  • BA3060 - No supported SCA method found
  • message string true none Error text for display by the end customer according to errors and messages
    details string false none Further information on the display at the end customer, which can change from message to message.

    ListOfBankAccesses

    {
      "85f78300-d993-4b7e-a8d0-8d39a4ba9d2a": {},
      "4000fda7-18af-463f-b694-bbafe5d23a48": {
        "status": "VOLLSTAENDIG",
        "tanMedien": [
          {
            "gueltigVon": "2016-06-03 17:17:41",
            "gueltigBis": "2016-06-03 17:17:41",
            "name": "Mobil",
            "medienklasse": "MOBIL"
          }
        ],
        "sicherheitsverfahren": [
          {
            "kodierung": 2,
            "name": "mTAN",
            "hinweis": "mTAN"
          },
          {
            "kodierung": 1,
            "name": "Mock-TAN",
            "hinweis": "Mock-TAN"
          }
        ],
        "aktivesSicherheitsverfahren": {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        },
        "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
        "timeout": "2016-12-24 13:37:42",
        "messages": [],
        "bankprodukte": [],
        "relations": [],
        "sync": false
      }
    }
    
    

    ListOfBankAccesses

    Properties

    Name Type Required Restrictions Description
    UUID BankAccess true none none

    CreateBankAccess

    {
      "d48744c0-132c-4ae4-a909-1ff771f61503": {
        "providerId": "00000000-0000-0000-0000-000000000000",
        "credentials": {
          "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
          "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
        },
        "sync": true
      }
    }
    
    

    CreateBankAccess

    Properties

    Name Type Required Restrictions Description
    {access-id} CreateBankAccessData true none none

    MessageCode

    "BA999"
    
    

    MessageCode

    Properties

    Name Type Required Restrictions Description
    MessageCode string false none Code of the message

    Message Codes:
  • BA999 - Internal error
  • BA1000 - Maintenance work provider
  • BA1001 - Provider no longer active
  • BA1010 - Access blocked
  • BA1011 - Access data incorrect
  • BA1012 - Access data incomplete
  • BA1050 - The bank account does not answer
  • BA1051 - Bank access unavailable
  • BA1052 - Bank access not fully available
  • BA1060 - Product could not be updated
  • BA1061 - Product could not be completely updated
  • BA1062 - Sales could not be updated
  • BA1063 - Depot positions could not be updated
  • BA1064 - Message bank
  • BA1100 - Transfer data invalid
  • BA1101 - Invalid TAN procedure
  • BA1103 - TAN invalid
  • BA1104 - Bank transfer not possible
  • BA1110 - TAN input required
  • BA1111 - The transfer has been completed successfully
  • BA2001 - SEPA server not accessible
  • BA2002 - There are notifications from your bank
  • BA3010 - Select SCA method
  • BA3020 - Select SCA medium
  • BA3030 - SCA Challenge
  • BA3040 - SCA failed
  • BA3060 - No supported SCA method found
  • Enumerated Values
    Property Value
    MessageCode BA999
    MessageCode BA1000
    MessageCode BA1001
    MessageCode BA1010
    MessageCode BA1011
    MessageCode BA1012
    MessageCode BA1050
    MessageCode BA1051
    MessageCode BA1052
    MessageCode BA1060
    MessageCode BA1061
    MessageCode BA1062
    MessageCode BA1063
    MessageCode BA1064
    MessageCode BA1100
    MessageCode BA1101
    MessageCode BA1103
    MessageCode BA1104
    MessageCode BA1110
    MessageCode BA1111
    MessageCode BA2001
    MessageCode BA2002
    MessageCode BA3010
    MessageCode BA3020
    MessageCode BA3030
    MessageCode BA3040
    MessageCode BA3060

    Product

    {
      "kategorie": "GIROKONTO",
      "produktbezeichnung": "Demo-Girokonto",
      "produktId": "DE1235233452324553423442A",
      "inhaber": "Dan Cooper",
      "aktualisierungsdatum": "2016-05-23 13:37:00",
      "saldo": "200000.00",
      "waehrung": "USD",
      "saldoDatum": "2016-05-23 13:37:00",
      "kontonummer": "0123456789",
      "iban": "DE1235233452324553423442",
      "bic": "BICIS133742",
      "blz": "12345678",
      "kreditinstitut": "Demo-Bank",
      "messages": [],
      "relations": []
    }
    
    

    Product

    Properties

    Name Type Required Restrictions Description
    id string true none In access unique identifier for the bank product. Is assigned by the system.
    bezeichnung string true none Name of bank product according to bank / service provider
    productCategories [ProductCategory] false none May be sent with a list of contain product categories. This attribute can be used to reduce the number of necessary SCAs by concentrating on product categories we fetch through the same channel.
    status BankProductStatus false none Retrieval status for product data
    saldo integer(int32) true none Balance / value of bank product with two decimal places
    aktualisierungszeitpunkt string(date) true none Time of the last product update at the bank / service provider
    saldoDatum string(date) true none Date of expiry as reported by the bank / service provider
    waehrung string true none Currency in which the bank product is valued / managed
    kontonummer string true none The account or credit card number. The credit card number may not be issued completely, but with a star eg "3223 ****** 4554"
    iban string true none The IBAN
    blz string true none The bank code
    bic string true none The BIC
    kreditinstitut string true none Name of institute of credit
    inhaber string true none Name of the product owner
    messages [Message] true none Messages transport both errors and analysis events.
    relations [Relation] true none Functions available to the customer
    verfuegungsrahmen integer(int32) true none Contains the available balance (usually overdraft limit + balance)
    verfuegterBetrag integer(int32) true none Contains the available balance (usually overdraft limit + balance)

    ProductCategory

    "GIROKONTO"
    
    

    ProductCategory

    Properties

    Name Type Required Restrictions Description
    ProductCategory string false none Categories:
  • GIROKONTO - Checking account: Account for payment transactions, as well as for the settlement / processing of eg deposit-related bookings, fees, interest, etc.
  • SPARKONTO - Savings account: Interest-bearing account with an unlimited term and fixed period of notice, as a rule an immediate withdrawal is limited to a maximum value
  • FESTGELDKONTO - Fixed deposit account: Interest-bearing account with a contractually agreed term
  • KREDITKONTO - Credit account: Account for managing the loan balance
  • TAGESGELDKONTO - Overnight money account: Interest-based account for an investment with daily availability
  • BAUSPARVERTRAG - Building loan account: Savings and possibly loan account for a home savings contract
  • SONSTIGESKONTO - Account that can not be assigned by the provider or our product heuristic
  • KREDITKARTE - Credit card: Payment card with credit line, billing takes place via an agreed current account / clearing account
  • SONSTIGEKARTE - Other card: Payment card that can not be assigned by the provider or our product heuristic
  • DEPOT - Brokerage account
  • SONSTIGESPRODUKT - Bank product that can not be assigned by the provider or our product heuristic
  • Enumerated Values
    Property Value
    ProductCategory GIROKONTO
    ProductCategory SPARKONTO
    ProductCategory FESTGELDKONTO
    ProductCategory KREDITKONTO
    ProductCategory TAGESGELDKONTO
    ProductCategory BAUSPARVERTRAG
    ProductCategory SONSTIGESKONTO
    ProductCategory KREDITKARTE
    ProductCategory SONSTIGEKARTE
    ProductCategory DEPOT
    ProductCategory SONSTIGESPRODUKT

    ProductCategories

    [
      "GIROKONTO",
      "TAGESGELDKONTO"
    ]
    
    

    ProductCategories

    Properties

    Name Type Required Restrictions Description
    ProductCategories [ProductCategory] false none A list of product categories

    TagType

    "CATEGORY"
    
    

    TagType

    Properties

    Name Type Required Restrictions Description
    TagType string false none Type according to usage purpose
    Enumerated Values
    Property Value
    TagType null

    ScaInteraction

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

    ScaInteraction

    Properties

    Name Type Required Restrictions Description
    messages [Message] true none Messages transport both errors and analysis events.
    sicherheitsverfahren [SecurityProcedures] false none Listing of security procedures available in the gateway
    relations [Relation] true none The relations available for bank access
    tanMedien [TANMedium] false none List of available TAN media in the access

    BankAccess

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

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous ScaInteraction false none BankAccess and Transfer inherit from this object. It indicates that in some cases, SCA may be needed to interact with the inheriting object.

    and

    Name Type Required Restrictions Description
    anonymous object false none Im Bankzugang-Objekt werden die Daten zu einem Bankzugang (i.d.R. Online-Banking-Zugang des eindeutigen Benutzers) geliefert.
    » status BankAccessStatus false none Retrieval status of the bank account

    Status list :
  • GESTARTET - Started: The data retrieval was started
  • INTERAKTION - Interaction: User intervention required, e.g. SCA required, see messages and relations
  • SAMMELN - Collection: All required data is entered, we are still fetching the account through multiple requests, should be finished within seconds, poll back soon.
  • VOLLSTAENDIG - Finished: The data retrieval is completed
  • » aktivesSicherheitsverfahren SecurityProcedure false none The security procedure determines how the end user releases his transaction (s).
    » aktualisierungszeitpunkt DateTime false none Time of the last query at the bank / service provider
    » timeout DateTime false none Lifetime of the data in seconds from the time of the update
    » bankprodukte [Product] false none The banking products available in the access
    » sync boolean false none Whether the bank account is automatically updated in the background.

    MessageLevel

    "ERROR"
    
    

    MessageLevel

    Properties

    Name Type Required Restrictions Description
    MessageLevel string false none Level of the message, INFO or ERROR
    Enumerated Values
    Property Value
    MessageLevel INFO
    MessageLevel ERROR

    Interaction

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

    Interaction

    Properties

    Name Type Required Restrictions Description
    messages [Message] true none Messages for TAN input or error texts for transfer
    relations [Relation] true none Relations for follow-up actions
    timeout string(date) false none Time to wait for follow-up actions
    challenge Challenge false none Contains information about TAN generation

    ConsentStatus

    "received"
    
    

    ConsentStatus

    Properties

    Name Type Required Restrictions Description
    ConsentStatus string false none This is the overall life cycle status of the consent.

    Valid values are:
  • RECEIVED: The consent data have been received and are technically correct. The data is not authorised yet.
  • REJECTED: The consent data have been rejected e.g. since no successful authorisation has taken place.
  • VALID: The consent is accepted and valid for GET account data calls and others as specified in the consent object.
  • REVOKED_BY_USER: The consent has been revoked by the PSU towards the ASPSP.
  • EXPIRED: The consent expired.
  • Enumerated Values
    Property Value
    ConsentStatus RECEIVED
    ConsentStatus REJECTED
    ConsentStatus VALID
    ConsentStatus EXPIRED
    ConsentStatus REVOKED_BY_USER

    SystemName

    "BANKFINANCE"
    
    

    SystemName

    Properties

    Name Type Required Restrictions Description
    SystemName string false none Machine-readable name of the tag, for a list check e.g. the transaction categories

    Sca

    {
      "scaStatus": "finalised",
      "gueltigBis": "2019-05-02 18:20:48"
    }
    
    

    Sca

    Properties

    Name Type Required Restrictions Description
    scaStatus string true none finalised
    gueltigBis string true none none

    CreateBankAccessData

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

    Create Bank Access Data

    Properties

    Name Type Required Restrictions Description
    providerId string(uuid) true none The ID of the access provider (bank or service provider ) according to the provider list
    credentials Credentials true none The Credentials object is a map of encrypted and Base64-encoded access data, corresponding to the provider's authentication fields. The Base64 encoding must not use line wrapping. The encryption method used is described in the chapter Encryption.
    sync boolean false none Whether an automatic regular background update is to be performed

    CreateClientToken

    {
      "grant_type": "client_credentials",
      "scope": "http://banksapi.io/provider/read"
    }
    
    

    CreateClientToken

    Properties

    Name Type Required Restrictions Description
    grant_type string true none Must always be client_credentials
    scope string false none Space-separated list of desired scopes. A scope names a class of access rules. It is a string, usually in the form of a (fictitious) URL. The available scopes depend on the scope of services booked. You therefore receive the scope list together with your cooperation agreement.

    CreateUserToken

    {
      "grant_type": "client_credentials",
      "scope": "http://banksapi.io/provider/read"
    }
    
    

    CreateUserToken

    Properties

    Name Type Required Restrictions Description
    grant_type string true none Must always be password
    username string true none Username of user
    password string true none Password of user
    scope string false none Space-separated list of desired scopes. A scope names a class of access rules. It is a string, usually in the form of a (fictitious) URL. The available scopes depend on the scope of services booked. You therefore receive the scope list together with your cooperation agreement.

    Token

    {
      "scope": "http://banksapi.io/customer/read http://banksapi.io/customer/modify",
      "tenant": "demo",
      "client": "demo-client",
      "user": "1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
      "access_token": "0defaced-1337-d00d-c0de-face8badcafe",
      "token_type": "Bearer"
    }
    
    

    Token

    Properties

    Name Type Required Restrictions Description
    scope string true none Space-separated list of OAuth2 scopes. A scope names a class of access rules. It is a string, usually in the form of a (fictitious) URL. The available scopes depend on the scope of services booked. You therefore receive the scope list together with your cooperation agreement.
    tenant string true none Technical name of the tenant
    client string true none Technical name of the client
    user string false none User reference, only set if this is a user token
    access_token string true none The token
    token_type string true none Always "Bearer"

    Customer API

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "bankzugaenge": {
        "4000fda7-18af-463f-b694-bbafe5d23a48": {
          "messages": [
            {
              "level": "INFO",
              "code": "BA3010",
              "message": "SCA benötigt",
              "details": "Bitte wählen Sie eine SCA-Methode aus"
            }
          ],
          "sicherheitsverfahren": [
            {
              "kodierung": 980,
              "name": "mTAN",
              "hinweis": "mTAN"
            },
            {
              "name": "SMS_OTP",
              "kodierung": "942",
              "hinweis": "SMS OTP"
            }
          ],
          "relations": [
            {
              "rel": "start_sca",
              "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
            }
          ]
        }
      },
      "relations": [
        {
          "rel": "start_sca",
          "href": "https://banksapi.io/customer/v2"
        },
        {
          "rel": "authenticate",
          "href": "https://banksapi.io/customer/v2"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/{consent-id}"
        },
        {
          "rel": "set_medium",
          "href": "https://banksapi.io/customer/v2/consent/{consent-id}"
        },
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2"
        },
        {
          "rel": "get_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
          "rel": "add_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
          "rel": "delete_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        }
      ]
    }
    
    

    Customer API

    Properties

    Name Type Required Restrictions Description
    messages [Message] false none [Messages transport both errors and analysis events.]
    bankzugaenge ListOfBankAccesses false none Collection of bank accesses
    relations [Relation] false none [A relation corresponds to an application or business transaction that is supported by the enclosing data object. Each application or business transaction has its own documentation, which describes the call as well as the return or the possible alternative answer scenarios in detail.]

    BankAccessStatus

    "STARTED"
    
    

    BankAccessStatus

    Properties

    Name Type Required Restrictions Description
    BankAccessStatus string false none Retrieval status of the bank account

    Status list :
  • GESTARTET - Started: The data retrieval was started
  • INTERAKTION - Interaction: User intervention required, e.g. SCA required, see messages and relations
  • SAMMELN - Collection: All required data is entered, we are still fetching the account through multiple requests, should be finished within seconds, poll back soon.
  • VOLLSTAENDIG - Finished: The data retrieval is completed
  • Enumerated Values
    Property Value
    BankAccessStatus GESTARTET
    BankAccessStatus INTERAKTION
    BankAccessStatus SAMMELN
    BankAccessStatus VOLLSTAENDIG

    BankProductStatus

    "STARTED"
    
    

    BankProductStatus

    Properties

    Name Type Required Restrictions Description
    BankProductStatus string false none Retrieval status of the bank product

    Status list :
  • GESTARTET - Started: The data retrieval was started
  • VOLLSTAENDIG - Finished: The data retrieval is completed
  • Enumerated Values
    Property Value
    BankProductStatus GESTARTET
    BankProductStatus VOLLSTAENDIG

    TANMedium

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

    TANMedium

    Properties

    Name Type Required Restrictions Description
    gueltigVon DateTime false none Start of validity.
    gueltigBis DateTime false none End of validity.
    name string false none Name of the TAN medium such as the mobile phone number
    medienklasse MediaClass false none Media Classes:
  • LIST - Paper-TAN list
  • GENERATOR - TAN generator
  • MOBILE - mobile phone
  • SECODER - TAN matrix generator
  • PUSHTAN - Push message
  • MediaClass

    "MOBILE"
    
    

    MediaClass

    Properties

    Name Type Required Restrictions Description
    MediaClass string false none Media Classes:
  • LIST - Paper-TAN list
  • GENERATOR - TAN generator
  • MOBILE - mobile phone
  • SECODER - TAN matrix generator
  • PUSHTAN - Push message
  • Enumerated Values
    Property Value
    MediaClass LIST
    MediaClass GENERATOR
    MediaClass MOBILE
    MediaClass SECODER
    MediaClass PUSHTAN

    SecurityProcedure

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

    SecurityProcedure

    Properties

    Name Type Required Restrictions Description
    kodierung string false none Key to the security procedure
    name string false none Human readable name for the security procedure
    hinweis string false none Human readable reference to the security procedure

    Classification

    {
      "category": "bills_electricity",
      "parentCategory": "bills",
      "displayName": "Strom",
      "confidenceLevel": 0.8
    }
    
    

    Classification

    Properties

    Name Type Required Restrictions Description
    category string true none Unique system name of sales category
    parentCategory string false none If it is a subcategory, this field includes the system name of the main category
    displayName string true none User friendly name of sales category
    confidenceLevel string false none Probability value (0-1) that account sales belong to this category

    Investment

    {
      "name": "Aberdeen Global - Emer. Markets Equity E2",
      "menge": 210.819609,
      "handelseinheit": "STUECK",
      "isin": "LU0498181733",
      "wkn": "A1C5UV",
      "kurs": 15.4117,
      "kursDatum": "2015-05-11 00:00:00",
      "waehrung": "EUR",
      "waehrungskurs": 1,
      "handelsplatz": "KAG",
      "gesamtwert": 3249.09
    }
    
    

    Investment

    Properties

    Name Type Required Restrictions Description
    name string false none Name of the deposit position, usually the name of the financial instrument
    menge number false none Pieces with decimal places
    handelseinheit string false none Trade item, STUECK or NOMINAL
    isin string false none ISIN of the financial instrument
    wkn string false none WKN of the financial instrument
    kurs number false none Price in trading currency
    kursDatum DateTime false none State of the course
    waehrung string false none Trading currency ( Alphabetic Code ISO 4217 )
    waehrungskurs number false none Conversion rate from the trading currency to EUR
    handelsplatz string false none Trading place of the price determination
    gesamtwert string false none Total value of the stock in trading currency as at the end of the financial statements
    Enumerated Values
    Property Value
    handelseinheit STUECK
    handelseinheit NOMINAL

    Tenant

    {
      "name": "demo",
      "description": "A tenant for demonstration purposes"
    }
    
    

    Tenant

    Properties

    Name Type Required Restrictions Description
    name string true none Tenant technical name becomes URL component
    description string false none Optional human readable description

    User

    {
      "userReference": "1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
      "username": "demo-user"
    }
    
    

    User

    Properties

    Name Type Required Restrictions Description
    userReference string true none Technical ID for the user, is also used in URLs (user-id)
    username string true none Username for creating an OAuth2 token

    DateTime

    "2019-20-04 13:37:00"
    
    

    DateTime

    Properties

    Name Type Required Restrictions Description
    DateTime string false none This object represents a timestamp. Format: ISO 8601 in the form YYYY-MM-DD hh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.

    Frequently Asked Questions

    How do I get the banking products for my customer?

    The bank products are available via the Banks/Connect Customer API. After you have assigned your user you need to add a bank account. You will need the online banking access data (credentials) of your customer, which you provide us with asymmetrically encrypted.

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

    What are credentials?

    Credentials here mean the access data of the customer to his online banking. The access data consists of usually consists of a user ID/login name and a password/PIN. The concrete specification is per Provider different and can be accessed via the Banks/Connect Providers API can be queried.

    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 required for the transfer process.

    After the transfer data has been transferred to the provider, the TAN or the instruction for generating the TAN (e.g. chip card reader) is sent from the Provider sent directly to the customer. The TAN must then again be requested by the customer and sent to Banks/Connect Customer API to confirm the order.

    Is there a test account or a demo account?

    Yeah, there's a demo bank. This is a fictitious bank with fictitious but not unrealistic banking products. This test access illustrates the possibilities offered by our API. A connection to the there's no real world to it. Further information can be found in our Quick Start Guide

    What is BANKSapi Banks/Connect?

    BANKSapi Banks/Connect is an interface via which a large number of providers can

    for your customers.

    Where and how is the data stored?

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

    How much does BANKSapi Banks/Connect cost me?

    Information about our price model can be found on the website.

    How do I get API access?

    Contact us!