NAV Navbar
cURL

BANKSapi BANKS/Connect

OpenAPI and Swagger

Please check out our OpenAPI v3 documentation:

You may also have a look at BANKS/Connect's Swagger UI.

Interface strategy

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

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

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

Structure of interface and documentation

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

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

Before it gets started

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

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

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

To show an example of the interface calls, we use the command line tool curl(1) in version 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 to receive your criticism and suggestions, which you can send to support@banksapi.de.

APIs

BANKS/Connect Auth API

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

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

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

BANKS/Connect Customer API

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

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

Comprehensive information about the API can be found in the 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 a comprehensive configuration database of data on the banks and service providers supported by BANKSapi BANKS/Connect via the BANKS/Connect Providers API

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

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

BANKS/Connect AI API

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

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

Central Concepts

Authentication

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

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

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

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

Bank

In conjunction of BANKSapi BANKS/Connect, we refer to the banking institutions from which we collect the data on your behalf as "bank". In the context of BANKSapi BANKS/Connect they are grouped together with the service providers as 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. Further details are regulated by your cooperation agreement.

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

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

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

Client

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

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

Correlation ID

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

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

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

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

CORS

More information about CORS on Wikipedia.

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

Errors

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

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

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

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

HATEOAS

More information about HATEOAS on Wikipedia.

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

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

Timestamp

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

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

JSON

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

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

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

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

Client

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

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

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

If you are interested, please contact with us.

OAuth2

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

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

Token types

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

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

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

Token levels

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

Token usage

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

Provider

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

Relation

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

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

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

REST

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

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

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

Service Provider

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

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

Language

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

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

Otherwise 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

What We're Going to Do

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

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

Create a Client Token

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

grant_type=client_credentials

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

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

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

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

Create a User

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

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

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

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

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

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

Create a User Token

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

grant_type=password&username=user1&password=password1

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

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

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

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

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

Create Bank Access

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Query Bank Access

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Query Turnovers

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

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

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

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

Force a Refresh of Data From the Bank

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

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

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

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

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

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

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

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

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

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

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

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

Query Issues

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

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

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

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

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

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

Where to Go From Here

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

Some hints on what to do next:

EBICS

Overview

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

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

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

Create an EBICS Account

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

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

Call the Add Bank Access Endpoint

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

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

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

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

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

Redirect the User

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

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

Initialization Letter Generation

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

Verify the Bank Access

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

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

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

User Sends Initialization Letter to the Bank

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

Successful Connection

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

Comparison to Non-EBICS Bank Accesses

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

Caveats

Initializing multiple times

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

Balance Retrieval Limitation

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

Historical Transaction Limitation

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

Transaction History Range

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

BANKSapi Auth API

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

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

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

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 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 a frontend provided by BANKSapi. The account information is stored by BANKSapi. The sensitive payment data is transferred directly from the end user to the BANKSapi systems, processed by BANKSapi and stored by BANKSapi. It is not possible to read the sensitive payment data from BANKSapi.

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

Background update

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

Notifications (Webhooks)

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

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

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

Strong customer authentication

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

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

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

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

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

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

TAN medium

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

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

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

Customer IP Address

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

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

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

Customer-Ip-Address: 123.234.123.234

REG/Protect

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

Context info when returning to your app

The return of the user can 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 BACKEND_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 a bank access

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

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

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

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

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

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

Overview of all REG/Protect query parameters:

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

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

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

Field Type Included Description
baReentry String Always If successful FINISHED

Triggering a payment

&lt;font color="#ffff00"&gt;-=https://banksapi.io/customer/v2/ueberweisung/e1f30693-=- proudly presents -bab3bc2/DE00123456789012345679 \
    -X POST \
    -H 'authorization: Bearer 9df54960-f678-47ec-84dc-6c771f9c980c' \
    -H 'content-type: application/json' \
    -d '{}'

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

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

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

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

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

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

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

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

Field Type Included Description
baReentry String Always If successful FINISHED

Operations with SCA

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

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

REG/Protect Task Process description
Yes Create a bank access When creating a bank access, the multi-step process will be covered by us through the REG/Protect frontend. Find the documentation in Adding bank access with REG/Protect
Yes Refresh a bank access During usage, the consent of the customer might expire at some point and new data can't be fetched from the bank. You can refresh with new data from the bank with a refresh-flag as documented. Whenever there is a relation start_sca, POST to the start_sca relation to indicate the user is ready to start an SCA process. You will receive a 451 status with a Location-header. Display the contents of the Location-Header to the user in the same way you would with the Location-Header when adding a bank access. This is to refresh the SCA with the bank in order to get up-to-date data from the bank.
No Create or update a bank access When using the embedded approach (without REG/Protect), there are several steps you need to follow.

When creating or updating the bank access and in case of an SCA, there will be one of the following relations:
  • set_method: This relation is sent with appropriate sicherheitsverfahren in the bank access. Use it as documented in Set SCA Method
  • set_medium: Not to be confused with set_method, this relation is sent with appropriate tanMedien in the bank access. Use it as documented in Set SCA Method
  • authenticate: This relation serves the purpose to resolve TAN procedures as described in Strong Customer Authentication, this href should be called with POST as described in Submit SCA Authentication Data.
  • authentication_decoupled: This relation is for TAN-less i.e. decoupled methods, send a GET request to the authentication_decoupled-relation to poll for the status of the SCA. This relation appears together with the authentication-relation, but should always be preferred.
  • redirect_url: When this relation is available the authentication will be performed on the bank interface. The user therefore needs to be redirected to the URL in this relation and will reenter your application at the given callbackUrl, that was provided as a query parameter in the POST request. If the redirected authentication ends prematurely and the user cannot finish the authentication, we offer a cancel-relation
There can be multiple SCAs for a single bank access, so your application needs to be able to handle any of the above mentioned relations at any point of the creation/update. If any of the SCAs fail, there will be start_sca relation when the bank access reaches the status VOLLSTAENDIG
No Background update of a bank access The consent of the customer might expire at some point and new data can't be fetched from the bank. In this case, the BankAccess object will contain a relation start_sca. POST an empty object to this relation in order to indicate that the user is ready to start an SCA process and renew the consent.

Encryption

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

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

Notifications

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

Event Description
Transaction New transaction(s) found
Balance The balance of a user has changed.
Error Error
POST /your-notification-endpoint HTTP/1.1
User Agent: BANKSapi Notifier
Content-Type: application/json
Accept: */*
Connection: close

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

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

Notification object

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

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

Notification Type

Event Type
Transaction TRANSACTION
Balance BALANCE
Error ERROR

Transaction Notification

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

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

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

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

Transaction object

{
    "payeeName": "La Sopia GmbH Munich",
    "amount": -70
}
Field Type Included Description
payeeName String Always Contains the id of the bank product
amount Number If available Amount of transaction, negative for outputs if applicable

Request-Body

The request body consists of a Transaction Notification Object.

Balance Notification

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

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

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

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

Request-Body

The request body consists of a Balance Notification Object.

Error Notification

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

    "level": "ERROR",
    "Code": "BA1010",
    "message": "Access blocked"
}

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

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

Request-Body

The request body consists of an Error Notification Object.

Transactions older than 90 days

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

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

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

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

Transaction tags (categorization)

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

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

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

BANKS/Connect Providers API

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

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

The API is similar in structure to the other 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 primary data such as name, bank group, bank code and BIC, you also receive detailed machine-readable information on the login modalities for your users, so that you can optimize the user experience of your application when creating bank accesses.

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


title: BANKS/

BANKS/Connect 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

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' \
  -H 'Authorization: Bearer {access-token}'

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 a user

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' \
  -H 'Authorization: Bearer {access-token}'

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

Get all activated users

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.
includeInactive query boolean false Whether or not to also include inactive users

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 user]
» User User false none This object represents a user
»» id 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
»» roles [string] false none Roles this user has

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'

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

grant_type: client_credentials
scope: 'http://banksapi.io/provider/read'

Parameters

Name In Type Required Description
body body CreateToken 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",
  "user": "1fad71ee-6dbf-49c7-9cb2-fff588de011f",
  "additionalData": {
    "username": "demouser"
  },
  "validTo": "2021-10-16 10:46:47",
  "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 basic authorization header was not sent or the value was incorrect. 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' \
  -H 'Authorization: Bearer {access-token}'

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' \
  -H 'Authorization: Bearer {access-token}'

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

Delete User

Code samples

## You can also use wget
curl -X DELETE https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id} \
  -H 'Authorization: Bearer {access-token}'

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

Deletes a single user. The user must be deactivated beforehand.

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
reftype query string false Reference type of user ID ("id" (default) or "username")

Responses

Status Meaning Description Schema Possible relations
200 OK Returns HTTP status of 200 (OK) None none
405 Method Not Allowed Returns HTTP status of 405 (Method Not Allowed) if user has not been deactivated. None none

Change user details

Code samples

## You can also use wget
curl -X PUT https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

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

Changes user details, such as username, first name or last name

Body parameter

{
  "username": "demouser",
  "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.
user-id path string true User reference of the user
reftype query string false Reference type of user ID ("id" (default) or "username")
body body ChangeUserDetails false none

Responses

Status Meaning Description Schema Possible relations
200 OK Change successful None none
409 Conflict Username already exists None none

Deactivate User

Code samples

## You can also use wget
curl -X PUT https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/deactivate \
  -H 'Authorization: Bearer {access-token}'

PUT /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
reftype query string false Reference type of user ID ("id" (default) or "username")

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 POST https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/reactivate \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

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

Reactivate a single deactivated user

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.
user-id path string true User reference of the user
reftype query string false Reference type of user ID ("id" (default) or "username")
body body CreateUser true The request body is a JSON object containing data required for a 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'

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 revoked

Parameters

Name In Type Required Description
body body object true The request body contains form object with following parameters
» token body string(uuid) false The token to be revoked

Responses

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

Introspect Token

Code samples

## You can also use wget
curl -X GET https://banksapi.io/auth/oauth2/introspect?token=0defaced-1337-d00d-c0de-face8badcafe \
  -H 'Accept: application/json'

GET /auth/oauth2/introspect

Returns information about a token

Parameters

Name In Type Required Description
token query string(uuid) true The Token to introspect

Example responses

200 Response

{
  "scope": "http://banksapi.io/customer/read http://banksapi.io/customer/modify",
  "tenant": "demo",
  "client": "demo-client",
  "user": "CN=Demo User,OU=Personal,DC=banksapi,DC=io",
  "additionalData": {
    "username": "demouser"
  },
  "validTo": "2021-10-16 10:46:47",
  "access_token": "0defaced-1337-d00d-c0de-face8badcafe",
  "token_type": "Bearer"
}

Responses

Status Meaning Description Schema Possible relations
200 OK Returns token object Token none
400 Bad Request No token was provided. None none
401 Unauthorized The basic authorization header was not sent or the value was incorrect. None none
403 Forbidden The provided token is not valid. None none

Providers

Get Providers

Code samples

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

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",
    "consumerRelevant": true,
    "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": "^.{1,50}$"
        },
        {
          "fieldkey": "pin",
          "label": "Demo-Passwort",
          "secret": true,
          "hint": "demo1, demo2 oder demo3",
          "format": "^.{1,50}$"
        }
      ]
    }
  }
]

Responses

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

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
»» consumerRelevant boolean true none Whether this provider should be displayed to the customer for the provider selection or not
»» group string false none Grouping term for providers. If several providers have the same group the same logo could be displayed, e.g.
»» 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 180 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
  • KREDITKARTENKONTO - Credit card acount:
  • 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 regular expression (regex) pattern specifying the format 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 KREDITKARTENKONTO
    ProductCategory SONSTIGEKARTE
    ProductCategory DEPOT
    ProductCategory SONSTIGESPRODUKT

    Get Providers core data

    Code samples

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

    GET /providers/v2/coredata

    Retrieve a list of core data for all providers.

    Parameters

    Name In Type Required Description
    capability query string false Filter providers by capability
    iban query string false Filter providers by iban
    useCache query boolean false Flag to control cache usage
    Enumerated Values
    Parameter Value
    capability KONTEN
    capability KARTEN
    capability DEPOTS
    capability BAUSPAR

    Example responses

    200 Response

    [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Demo Provider",
        "group": "demo",
        "blz": "12345678",
        "bic": "DEMO1234",
        "logo": "https://banksapi.io/providers/v2/demo.svg"
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of core data for providers. Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [ProviderCoreData] false none [Provider core information]
    » ProviderCoreData ProviderCoreData false none Provider core 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 the same logo could be displayed, e.g.
    »» 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
    »» logo string false none Returns the path to the provider logo in SVG-format

    Get Providers job statistics

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/providers/v2/statistics/jobs \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    GET /providers/v2/statistics/jobs

    Retrieve a list of provider logos with statistical data about the data jobs. If there were no successful data jobs or no data jobs at all in the specified time period, no entry is returned for the corresponding logo.

    Parameters

    Name In Type Required Description
    days query integer(int32) false Specifies the number of past days for fetching job statistics. When used together with "hours", their values are summed. If none of the parameters are specified, 2 hours are fetched.
    hours query integer(int32) false Specifies the number of past hours for fetching job statistics. When used together with "days", their values are summed. If none of the parameters are specified, 2 hours are fetched.
    ebics query boolean false If only EBICS jobs should be considered for the response.
    sca query boolean false If only provider logos with at least one job including a strong customer authentication (SCA) should be considered for the response. In case of false it will not be checked whether there was an SCA or not.

    Example responses

    200 Response

    [
      {
        "logo": "demo",
        "latestSuccessDate": "2023-09-20 11:21:02",
        "averageDuration": 29962,
        "successRate": 1
      },
      {
        "logo": "sparkasse",
        "latestSuccessDate": "2023-09-20 11:28:57",
        "averageDuration": 54186,
        "successRate": 0.99
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a list of job statistics for providers. Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [ProviderJobStatistics] false none [Provider job statistics]
    » ProviderJobStatistics ProviderJobStatistics false none Provider job statistics
    »» logo string true none Logo of the provider.
    »» latestSuccessDate string(YYYY-MM-DD hh:mm:ss) true none Date of the latest successful data job for providers with the corresponding logo.
    »» averageDuration number true none The average duration of data jobs in ms for providers with the corresponding logo.
    »» successRate number true none The success rate of data jobs for providers with the corresponding logo.

    Get Provider

    Code samples

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

    GET /providers/v2/{provider-id}

    Retrieve information for a specific provider.

    Parameters

    Name In Type Required Description
    provider-id path string(uuid) true ID of a provider

    Example responses

    200 Response

    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Demo Provider",
      "consumerRelevant": true,
      "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": "^.{1,50}$"
          },
          {
            "fieldkey": "pin",
            "label": "Demo-Passwort",
            "secret": true,
            "hint": "demo1, demo2 oder demo3",
            "format": "^.{1,50}$"
          }
        ]
      }
    }
    

    Responses

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

    Get Provider EBICS Info

    Code samples

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

    GET /providers/v2/{provider-id}/ebics

    Retrieve EBICS information for a specific provider (if available).

    Parameters

    Name In Type Required Description
    provider-id path string(uuid) true ID of a provider

    Example responses

    200 Response

    {
      "hostId": "HOSTIDXY",
      "hostUrl": "https://ebics.bank.com/ebics"
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an EBICS info object for a specific provider. ProviderEbicsInfo none
    404 Not Found If the URL does not point to a provider, you will get the HTTP status 404 (Not found). None none

    Check Instant Payment Support

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/providers/v2/{provider-id}/instant-payment-supported \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /providers/v2/{provider-id}/instant-payment-supported

    Determines whether instant payments from a specific provider are supported based on the recipient IBANs and the transfer type. If the recipientIbans are not provided, it will only be determined if the provider supports sending instant payments.

    Body parameter

    {
      "type": "object",
      "properties": {
        "recipientIbans": {
          "type": "array",
          "description": "The recipient's IBANs. If not provided, it will only be determined if the provider supports sending instant payments.",
          "items": {
            "type": "string"
          },
          "example": [
            "DE92123456789876543210"
          ]
        },
        "transferType": {
          "type": "string",
          "description": "The type of transfer. This type is required if `recipientIbans` is not provided.",
          "enum": [
            "SINGLE",
            "BULK"
          ],
          "example": "SINGLE"
        }
      }
    }
    

    Parameters

    Name In Type Required Description
    provider-id path string(uuid) true ID of a provider
    body body CheckInstantPaymentSupport true none

    Example responses

    200 Response

    {
      "type": "object",
      "required": [
        "senderProviderId",
        "transferType",
        "instantPaymentSupported"
      ],
      "properties": {
        "senderProviderId": {
          "type": "string",
          "description": "The ID of the provider sending the instant payment.",
          "example": "00000000-0000-0000-0000-000000000000"
        },
        "recipientIbans": {
          "type": "array",
          "description": "The IBANs of the recipients.",
          "items": {
            "type": "string"
          },
          "example": [
            "DE92123456789876543210"
          ]
        },
        "transferType": {
          "type": "string",
          "description": "The type of transfer.",
          "enum": [
            "SINGLE",
            "BULK"
          ],
          "example": "SINGLE"
        },
        "instantPaymentSupported": {
          "type": "boolean",
          "description": "Indicates if instant payment is supported.",
          "example": true
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns information about whether instant payments are supported. InstantPaymentSupportResult none
    400 Bad Request Bad request if the input parameters are incorrect. None none
    404 Not Found If the URL does not point to a provider, you will get the HTTP status 404 (Not found). None none

    Customer

    Get Customer

    Code samples

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

    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

    {
      "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. Customer self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_bankzugaenge: Lists all bank accesses of the user
    add_bankzugaenge: adds a new bank access to the user
    delete_bankzugaenge: Delete all bank accesses of the user
    delete_regprotect_sessions: Deletes all current REG/Protect sessions for the user
    get_contracts: Returns the contracts of the user
    get_sales_triggers: Returns the sales trigger of the user
    get_life_events: Returns the life events of the user
    get_life_stages: Returns the life stages of the user
    get_cashflow: Returns the cashflow of the user
    get_credit_check: Returns the credit check of the user
    get_disposable_money: Returns the disposable money of the user
    get_affinities: Returns the affinities of the user
    get_credit_attributes: Returns the credit attributes of the user
    get_tagging_rules: Returns the manually created tagging rules of the user
    delete_tagging_rules: Deletes all tagging rules of the user
    add_tagging_rules: Adds a new tagging rule to the user

    Customer Bank Access

    Add Bank Access

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge?callbackUrl=https%3A%2F%2Fdemo-tenant.com%2Fcallback%3Fstate%3D123 \
      -H 'Content-Type: application/json' \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/bankzugaenge

    Adds a bank access for the given user and set of credentials.

    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,
        "selectedBankProducts": [
          "DE00123456789012345679"
        ]
      }
    }
    

    Parameters

    Name In Type Required Description
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)
    callbackUrl query string(url) true A callback URL.
    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
    queryTanSettings query boolean false Flag to ignore saved TAN-settings and query them.
    headOnly query boolean false Flag to solely fetch header data of the account without balances and transactions (e.g. to get the list of selectable bank products). If this flag is true the flag sync in the request payload has to be false and no selectedBankProducts can be specified.
    maxTransactions query MaxTransactions false Indicator if transactions older than 90 days should be fetched.
    paymentAccountsOnly query boolean false Flag to solely fetch payment accounts. Other accounts will be ignored, which can result in fewer SCAs.
    body body CreateBankAccess true The body contains information about the bank access. REG/Hosting tenants need to provide credentials in case this is not a "refresh"-request. In case of a REG/Protect tenant or a "refresh"-request the value for the access-id-key should be an empty object.
    Enumerated Values
    Parameter Value
    maxTransactions none
    maxTransactions all
    maxTransactions paymentAccounts

    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
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location 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 URL to get the created bank access using GET method
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Get Bank Accesses

    Code samples

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

    GET /customer/v2/bankzugaenge

    Retrieves all bank accesses for this user.

    Example responses

    200 Response

    {
      "0b7f4783-4c93-4820-8e73-354a0f1c469e": {
        "id": "0b7f4783-4c93-4820-8e73-354a0f1c469e",
        "providerId": "00000000-0000-0000-0000-000000000000",
        "aktualisierungszeitpunkt": "2021-10-15 09:13:44",
        "tanMedien": [
          {
            "name": "Mobil",
            "medienklasse": "MOBIL",
            "gueltigVon": "2021-10-15 09:13:44",
            "gueltigBis": "2021-10-15 09:13:44"
          }
        ],
        "sicherheitsverfahren": [
          {
            "kodierung": 1,
            "name": "mockTAN",
            "hinweis": "Gib eine durch 2 teilbare Zahl ein"
          },
          {
            "kodierung": 999,
            "name": "iTAN",
            "hinweis": "Gib die TAN \"12\" an."
          }
        ],
        "aktivesSicherheitsverfahren": {
          "kodierung": 999,
          "name": "iTAN",
          "hinweis": "Gib die TAN \"12\" an."
        },
        "relations": [
          {
            "rel": "self",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/0b7f4783-4c93-4820-8e73-354a0f1c469e"
          },
          {
            "rel": "delete_bankzugang",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/0b7f4783-4c93-4820-8e73-354a0f1c469e"
          }
        ],
        "status": "VOLLSTAENDIG",
        "bankprodukte": [
          {
            "id": "DE00123456789012345679",
            "status": "VOLLSTAENDIG",
            "bezeichnung": "Tagesgeldkonto",
            "kategorie": "TAGESGELDKONTO",
            "saldo": 27365.56,
            "aktualisierungszeitpunkt": "2021-10-15 09:13:44",
            "saldoDatum": "2021-10-15 00:00:00",
            "waehrung": "EUR",
            "kontonummer": "9012345679",
            "iban": "DE00123456789012345679",
            "bic": "XXX12345678",
            "blz": "12345678",
            "kreditinstitut": "Demo Provider",
            "inhaber": "Fritz Testmüller",
            "transferSupport": true,
            "relations": [
              {
                "rel": "get_kontoumsaetze",
                "href": "https://banksapi.io/customer/v2/bankzugaenge/0b7f4783-4c93-4820-8e73-354a0f1c469e/DE00123456789012345679/kontoumsaetze"
              },
              {
                "rel": "initiate_single_transfer",
                "href": "https://banksapi.io/customer/v2/payment/single-transfer"
              },
              {
                "rel": "initiate_bulk_transfer",
                "href": "https://banksapi.io/customer/v2/payment/bulk-transfer"
              }
            ],
            "messages": [],
            "verfuegungsrahmen": 27365.56,
            "verfuegterBetrag": 0
          }
        ],
        "sync": true
      },
      "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 none
    401 Unauthorized The bearer authorization header was not sent or the value was incorrect. None none

    Delete All Bank Accesses

    Code samples

    ## You can also use wget
    curl -X DELETE https://banksapi.io/customer/v2/bankzugaenge \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Authorization: Bearer {access-token}'
    
    

    DELETE /customer/v2/bankzugaenge

    Removes all bank accesses of the authenticated user.

    Parameters

    Name In Type Required Description
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)

    Responses

    Status Meaning Description Schema Possible relations
    200 OK The HTTP status 200 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' \
      -H 'Authorization: Bearer {access-token}'
    
    

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

    Retrieves a specific bank access for this user.

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access

    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: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    delete_bankzugang: Deletes a bank access of the user
    get_issues: Shows issues for the given bank access
    get_challenge_pdf: Returns the PDF file from the challenge if available
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    redirect_url: Contains link to the website, that the user needs to follow for the completion of the SCA
    refresh_bankzugang: refreshes an existing bank access
    504 Gateway Time-out The started request could not be answered in the given time None none

    Delete Bank Access

    Code samples

    ## You can also use wget
    curl -X DELETE https://banksapi.io/customer/v2/bankzugaenge/{access-id} \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Authorization: Bearer {access-token}'
    
    

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

    Deletes a specific bank access.

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns without any further response body. None none
    404 Not Found The bank access with the given access-id was not found / does not exist. None none

    Get Bank Access Issues

    Code samples

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

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

    Retrieves last known issues for a specific bank access for this user.

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access

    Example responses

    200 Response

    {
      "id": "815251d6-c062-4f61-bec0-182bc14a48fb",
      "providerId": "00000000-0000-0000-0000-000000000000",
      "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"
      },
      "challenge": {
        "name": "Mock-TAN-Verfahren",
        "content": {
          "instructions": "Enter a TAN that is divisible by 2"
        },
        "decoupled": false,
        "redirect": false
      },
      "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
      "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"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a bank access issues object BankAccessIssues self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    delete_bankzugang: Deletes a bank access of the user
    get_issues: Shows issues for the given bank access
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    redirect_url: Contains link to the website, that the user needs to follow for the completion of the SCA

    Get Bank Access Challenge PDF

    Code samples

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

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

    Retrieves the PDF file from the bank access challenge if available.

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access

    Example responses

    200 Response

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns the PDF file from the bank access challenge if available. string none
    404 Not Found The PDF file for the given access-id was not found / does not exist. None none

    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' \
      -H 'Authorization: Bearer {access-token}'
    
    

    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(uuid) true ID of the bank access
    product-id path string true ID of a 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": [
        {
          "rel": "get_kontoumsaetze",
          "href": "https://test.banksapi.io/customer/v2/bankzugaenge/cba09da4-57fb-4262-b11c-3192b3438265/DE00123456789012345679/kontoumsaetze"
        },
        {
          "rel": "initiate_single_transfer",
          "href": "https://banksapi.io/customer/v2/payment/single-transfer"
        },
        {
          "rel": "initiate_bulk_transfer",
          "href": "https://banksapi.io/customer/v2/payment/bulk-transfer"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns data of the bank product. Product self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_kontoumsaetze: Lists all transactions of the given banking product, default are transactions of the last 90 days, available if product has transactions
    initiate_single_transfer: Initiates a single transfer
    initiate_bulk_transfer: Initiates a bulk transfer
    initiate_single_transfer_with_saved_credentials: Initiates a single transfer with previously saved credentials
    initiate_bulk_transfer_with_saved_credentials: Initiates a bulk transfer with previously saved credentials
    get_depotpositionen: Lists all depot positions of the given banking product, available if product has kategorie set to DEPOT and if depot positions are available
    get_kontoumsaetze_categories: Acts the same as get_kontoumsaetze, but with added category tags
    get_kontoumsaetze_business_partners: Acts the same as get_kontoumsaetze, but with added business partner tags
    get_kontoumsaetze_periods: Acts the same as get_kontoumsaetze, but with added period tags
    get_kontoumsaetze_insurance_types: Acts the same as get_kontoumsaetze, but with added insurance type tags
    get_kontoumsaetze_freelancer_categories: Acts the same as get_kontoumsaetze, but with added freelancer category tags
    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' \
      -H 'Authorization: Bearer {access-token}'
    
    

    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
    access-id path string(uuid) true ID of the bank access
    product-id path string true ID of a banking product
    from query string(date-time) false Only return transactions with a booking date after this Date/Time (ISO 8601 formatted timestamp); may be used with to to specify a time window
    to query string(date-time) false Only return transactions with a booking date before this Date/Time (ISO 8601 formatted timestamp); may be used with from to specify a time window
    tag query any false The resulting transactions will each contain Categorization objects of the corresponding tag type
    filter query string false Filter to apply to result set. Filter expression must be URL-encoded. Filter expression must be in the form <field-selector><predicate><value>.
    Enumerated Values
    Parameter Value
    tag categories
    tag business-partners
    tag periods
    tag insurance-types
    tag freelancer-categories
    tag custom-categories

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

    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 [allOf] false none none

    allOf

    Name Type Required Restrictions Description
    » anonymous object false none none
    »» id string(uuid) false none The unique id of this transaction.
    »» hash string(uuid) false none none

    and

    Name Type Required Restrictions Description
    » anonymous TransactionData false none none
    »» betrag number true none Amount with two decimal places.
    »» waehrung string false none Currency of the transaction.
    »» verwendungszweck string true none The purpose of the transaction.
    »» buchungstext string false none A text for the entry of the transaction
    »» buchungsdatum string(YYYY-MM-DD hh:mm:ss) true none The date of the entry of the transaction
    »» wertstellungsdatum string(YYYY-MM-DD hh:mm:ss) false none Date of booking
    »» gegenkontoInhaber string false none Owner of the counter account
    »» gegenkontoIban string false none IBAN of the counter account
    »» gegenkontoBic string false none BIC of the counter account
    »» gegenkontoInhaberAbweichend string false none Ultimate owner of the counter account
    »» primanotaNummer string false none Primanota number of sales
    »» gvCode string false none Provider specific code, that denotes transaction use cases
    »» identifier object false none none
    »»» endToEndId string false none none
    »»» proprietaryCode string false none Used for example for PayPal's proprietary transaction ID
    »»» entryReference string false none none
    »»» ownerRef string false none none
    »»» bookingRef string false none none
    »»» balance number false none none
    »»» mandateId string false none Contains the SEPA mandate reference
    »»» batchId string false none none
    »» tags [TagInstanceSchema] false none none
    »»» entity EntitySchema true none none
    »»»» displayName string true none Display name of the entity
    »»»» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »»»» id string true none Transaction UUID or USER UUID.
    »»»» userId string false none UUID of the USER. Same as id field for USER entities.
    »»» id string true none Unique Universal Identifier (UUID)
    »»» relations [RelationSchema] false none List of relations
    »»»» href string true none Link of the relation
    »»»» rel string true none Name of the relation
    »»» tagTreeItem TagTreeItemSchema true none none
    »»»» description string false none Gives a description of the tagTreeItem
    »»»» displayName string false none User-friendly name shown to the end-users
    »»»» relations [RelationSchema] false none List of relations
    »»»» systemId integer false none Unique internal id of the tag tree item
    »»»» systemName string true none Unique name of the tag tree item
    »»»» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »»»» tagTree BusinessPartnerTagTreeItemSchemaTagTree true none tagTree that the tagTreeItem belongs to
    »»»»» description string false none Gives a description of the tag tree
    »»»»» displayName string false none User-friendly name shown to the end-users
    »»»»» isTenantGenerated boolean false none Boolean flag, set TRUE if the tag was manually set
    »»»»» relations [RelationSchema] false none List of relations
    »»»»» systemId integer false none Unique internal id of the tag tree
    »»»»» systemName string true none Unique name of the tag tree
    »»»»» version number false none Version of the tag tree

    modify categorisation of transactions

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze/{transaction-id} \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    PUT /customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze/{transaction-id}

    This method applies corrections to the categorization of transactions. Initial categorization is required before recategorization.

    Input contains the tag tree item that should be used for recategorization. A valid tag tree item has to be provided.

    The flag createRule creates a user specific rule that automatically categorizes this counterparty with the provided tag tree item in all future transactions. This is a smart solution to eradicate a recurring recategorization process.

    The flag changeExisting recategorizes all existing transactions of the same counterparty.

    The tagTreeItem has to include a tagTree and has to be wrapped in tags: [].

    The recategorization currently relies on the systemName value of tagTreeItem and tagTree, but as this might change in the future, both systemName and systemId should be included in the payload, all other fields are ignored.

    To get a full list of tag tree items, use: GET https://banksapi.io/tags/v1/tags/tag_trees/1/tag_tree_items/

    Body parameter

    {
      "type": "object",
      "properties": {
        "tags": {
          "type": "array",
          "items": {
            "properties": {
              "entity": {
                "properties": {
                  "displayName": {
                    "description": "Display name of the entity",
                    "example": "TRANSACTION",
                    "type": "string"
                  },
                  "entityClass": {
                    "description": "Class of the entity, such as TRANSACTION or USER",
                    "example": "TRANSACTION",
                    "type": "string"
                  },
                  "id": {
                    "description": "Transaction UUID or USER UUID.",
                    "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
                    "type": "string"
                  },
                  "userId": {
                    "description": "UUID of the USER. Same as id field for USER entities.",
                    "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
                    "type": "string"
                  }
                },
                "required": [
                  "displayName",
                  "entityClass",
                  "id"
                ],
                "type": "object"
              },
              "id": {
                "description": "Unique Universal Identifier (UUID)",
                "example": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
                "type": "string"
              },
              "relations": {
                "description": "List of relations",
                "items": {
                  "properties": {
                    "href": {
                      "description": "Link of the relation",
                      "example": "https://banksapi.io/.../tags/tag-trees/1/",
                      "type": "string"
                    },
                    "rel": {
                      "description": "Name of the relation",
                      "example": "tag_trees",
                      "type": "string"
                    }
                  },
                  "required": [
                    "href",
                    "rel"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "tagTreeItem": {
                "properties": {
                  "description": {
                    "description": "Gives a description of the tagTreeItem",
                    "example": "Expenses from daily grocery purchases",
                    "type": "string"
                  },
                  "displayName": {
                    "description": "User-friendly name shown to the end-users",
                    "example": "Groceries",
                    "type": "string"
                  },
                  "relations": {
                    "description": "List of relations",
                    "items": {
                      "properties": {
                        "href": {
                          "description": "Link of the relation",
                          "example": "https://banksapi.io/.../tags/tag-trees/1/",
                          "type": "string"
                        },
                        "rel": {
                          "description": "Name of the relation",
                          "example": "tag_trees",
                          "type": "string"
                        }
                      },
                      "required": [
                        "href",
                        "rel"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "systemId": {
                    "description": "Unique internal id of the tag tree item",
                    "example": 17,
                    "type": "integer"
                  },
                  "systemName": {
                    "description": "Unique name of the tag tree item",
                    "example": "LIVING_GROCERIES",
                    "type": "string"
                  },
                  "systemNameParent": {
                    "description": "Unique name of the parent of the tagTreeItem",
                    "example": "LIVING",
                    "type": "string"
                  },
                  "tagTree": {
                    "allOf": [
                      {
                        "example": {
                          "description": "Two level categorization tree.",
                          "displayName": "Kategorien",
                          "isClientGenerated": false,
                          "relations": [
                            {
                              "href": "https://banksapi.io/tags/v1/tag-trees/1/",
                              "rel": "self"
                            },
                            {
                              "href": "https://banksapi.io/tags/v1/tag-trees/",
                              "rel": "tag_trees"
                            },
                            {
                              "href": "https://banksapi.io/tags/v1/tag-trees/1/tag-tree-items/",
                              "rel": "tag_tree_items"
                            }
                          ],
                          "systemId": 1,
                          "systemName": "CATEGORIES",
                          "version": 3.7
                        },
                        "properties": {
                          "description": {
                            "description": "Gives a description of the tag tree",
                            "example": "Detailed inusrance categories.",
                            "type": "string"
                          },
                          "displayName": {
                            "description": "User-friendly name shown to the end-users",
                            "example": "Kategorien",
                            "type": "string"
                          },
                          "isTenantGenerated": {
                            "description": "Boolean flag, set TRUE if the tag was manually set",
                            "example": true,
                            "type": "boolean"
                          },
                          "relations": {
                            "description": "List of relations",
                            "items": {
                              "properties": {
                                "href": {
                                  "description": "Link of the relation",
                                  "example": "https://banksapi.io/.../tags/tag-trees/1/",
                                  "type": "string"
                                },
                                "rel": {
                                  "description": "Name of the relation",
                                  "example": "tag_trees",
                                  "type": "string"
                                }
                              },
                              "required": [
                                "href",
                                "rel"
                              ],
                              "type": "object"
                            },
                            "type": "array"
                          },
                          "systemId": {
                            "description": "Unique internal id of the tag tree",
                            "example": 1,
                            "type": "integer"
                          },
                          "systemName": {
                            "description": "Unique name of the tag tree",
                            "example": "CATEGORIES",
                            "type": "string"
                          },
                          "version": {
                            "description": "Version of the tag tree",
                            "example": 1.5,
                            "minimum": 0,
                            "type": "number"
                          }
                        },
                        "required": [
                          "systemName"
                        ],
                        "type": "object"
                      }
                    ],
                    "description": "tagTree that the tagTreeItem belongs to",
                    "type": "object"
                  }
                },
                "required": [
                  "systemName",
                  "tagTree"
                ],
                "type": "object"
              }
            },
            "required": [
              "entity",
              "id",
              "tagTreeItem"
            ],
            "type": "object"
          }
        }
      }
    }
    

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    product-id path string true ID of a banking product
    transaction-id path string(uuid) true ID of a transaction
    changeExisting query boolean false none
    createRule query boolean false none
    body body WrappedTags true none

    Example responses

    400 Response

    {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "HTTP Code",
          "example": "400"
        },
        "message": {
          "type": "string",
          "description": "error message",
          "example": "Tag with system name INSURANCE_LIF does not exist for tag tree CATEGORIES"
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK transaction was successfully modified None none
    400 Bad Request error in request body ErrorMessage none
    404 Not Found transaction was not found None none

    Get Portfolio

    Code samples

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

    GET /customer/v2/bankzugaenge/{access-id}/{product-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
    access-id path string(uuid) true ID of the bank access
    product-id path string true ID of a banking product

    Example responses

    200 Response

    [
      {
        "name": "Aberdeen Global - Emer. Markets Equity E2",
        "menge": 210.819609,
        "handelseinheit": "STUECK",
        "isin": "LU0498181733",
        "wkn": "A1C5UV",
        "kurs": 15.4117,
        "kursDatum": "2021-10-15 15:50:20",
        "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. Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [Investment] false none [A securities account item corresponds to a security position of a securities account.]
    » Investment Investment false none A securities account item corresponds to a security position of a securities account.
    »» name string false none Name of the deposit position, usually the name of the financial instrument
    »» menge number false none Amount 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 string(YYYY-MM-DD hh:mm:ss) false none The quote date
    »» waehrung string false none Trading currency (Alphabetic Code ISO 4217)
    »» waehrungskurs number false none Conversion rate from EUR to the trading currency
    »» handelsplatz string false none Trading place of the price determination
    »» gesamtwert number false none Total value of the stock in the currency given in 'waehrung' as at the end of the financial statements
    Enumerated Values
    Property Value
    handelseinheit STUECK
    handelseinheit NOMINAL

    Start SCA

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge/{access-id}/consent?callbackUrl=https%3A%2F%2Fdemo-tenant.com%2Fcallback%3Fstate%3D123 \
      -H 'Content-Type: application/json' \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Authorization: Bearer {access-token}'
    
    

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

    Starts the SCA renewal process

    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,
        "selectedBankProducts": [
          "DE00123456789012345679"
        ]
      }
    }
    

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)
    callbackUrl query string(url) true A callback URL.
    queryTanSettings query boolean false Flag to ignore saved TAN-settings and query them.
    maxTransactions query MaxTransactions false Indicator if transactions older than 90 days should be fetched.
    body body CreateBankAccess false Login data for the access. Only needed if access is not being automatically synchronized with the provider (sync=false).
    Enumerated Values
    Parameter Value
    maxTransactions none
    maxTransactions all
    maxTransactions paymentAccounts

    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
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None none

    Response Headers

    Status Header Type Format Description
    201 Location string URL to get the created bank access using GET method
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Code samples

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

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

    Submits a SCA method, medium or authentication data for the current SCA (e.g. when creating a bank access).

    Body parameter

    {
      "chosenScaMethodId": "942"
    }
    
    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    consent-id path string(uuid) true ID of the consent
    body body SubmitScaData true none

    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
    }
    
    Status Meaning Description Schema Possible relations
    200 OK Returns a bank access object BankAccess set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it

    Code samples

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

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

    Can be used for the decoupled SCA approach to check if the SCA has already been confirmed.

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    consent-id path string(uuid) true ID of the consent

    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
    }
    
    Status Meaning Description Schema Possible relations
    200 OK Returns a bank access object BankAccess set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it

    Code samples

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

    POST /customer/v2/bankzugaenge/{access-id}/consent/{consent-id}/cancel

    Cancels an SCA redirect and stops the corresponding access synchronization. This request is permitted only for the redirect SCA approach.

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    consent-id path string(uuid) true ID of the consent

    Example responses

    200 Response

    {
      "id": "815251d6-c062-4f61-bec0-182bc14a48fb",
      "providerId": "00000000-0000-0000-0000-000000000000",
      "aktualisierungszeitpunkt": "2022-02-02 22:22:22",
      "messages": [
        {
          "level": "ERROR",
          "code": "BA3040",
          "message": "SCA fehlgeschlagen",
          "details": "Redirect-SCA wurde abgebrochen"
        },
        {
          "level": "INFO",
          "code": "BA3000",
          "message": "SCA notwendig"
        }
      ],
      "tanMedien": [],
      "sicherheitsverfahren": [],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/bankzugaenge/815251d6-c062-4f61-bec0-182bc14a48fb"
        },
        {
          "rel": "delete_bankzugang",
          "href": "https://banksapi.io/customer/v2/bankzugaenge/815251d6-c062-4f61-bec0-182bc14a48fb"
        },
        {
          "rel": "get_issues",
          "href": "https://banksapi.io/customer/v2/bankzugaenge/815251d6-c062-4f61-bec0-182bc14a48fb/issues"
        },
        {
          "rel": "start_sca",
          "href": "https://banksapi.io/customer/v2/bankzugaenge/815251d6-c062-4f61-bec0-182bc14a48fb/consent"
        }
      ],
      "status": "VOLLSTAENDIG",
      "bankprodukte": [],
      "sync": false
    }
    
    Status Meaning Description Schema Possible relations
    200 OK Returns a bank access object BankAccess none

    Customer Bank Access Payment

    Initiate a single transfer

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/payment/single-transfer?callbackUrl=https%3A%2F%2Fdemo-tenant.com%2Fcallback%3Fstate%3D123 \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Rejection-NoFunds-Preferred: true' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/bankzugaenge/{access-id}/{product-id}/payment/single-transfer

    Initiates a payment for the given bank access, without providing access credentials

    Body parameter

    {
      "instant": false,
      "requestedExecutionDate": "2024-09-19",
      "transferDetails": {
        "recipient": "netzpolitik.org e. V.",
        "purpose": "Spende netzpolitik.de",
        "iban": "DE62430609671149278400",
        "bic": "GENODEM1GLS",
        "currency": "EUR",
        "amount": 1337.42,
        "endToEndId": "be7649876d5f439886fa816993ac9f9f"
      }
    }
    

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    product-id path string true ID of a banking product
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)
    Rejection-NoFunds-Preferred header boolean false If set to "true", the bank should reject the payment if there are insufficient funds. If set to "false", the bank may wait for a certain period for funds to arrive. This parameter may be ignored by the bank.
    callbackUrl query string(url) true A callback URL.
    editableDetails query boolean false Flag for REG/Protect to control whether fields on the frontend are editable
    autoConfirm query boolean false Flag for REG/Protect to control whether transfers can be entered without interaction
    body body BasicSingleTransferData false The request body object carries the data for a payment. It is expected when creating a payment. It is not required for REG/Protect tenants when requesting with editableDetails=true.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/single-transfer/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        }
      ],
      "transfer": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "ebics": false,
        "instant": false,
        "requestedExecutionDate": "2024-09-19",
        "transferDetails": {
          "recipient": "netzpolitik.org e. V.",
          "purpose": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "currency": "EUR",
          "amount": 1337.42,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the transfer status SingleTransferResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    404 Not Found Bank Access Credentials could not be found None none
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_webform: Contains link to the REG/Protect web application

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Initiate a bulk transfer

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/payment/bulk-transfer?callbackUrl=https%3A%2F%2Fdemo-tenant.com%2Fcallback%3Fstate%3D123 \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Rejection-NoFunds-Preferred: true' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/bankzugaenge/{access-id}/{product-id}/payment/bulk-transfer

    Initiates a payment for the given bank access, without providing access credentials

    Body parameter

    {
      "description": "Request data to start a transfer",
      "required": [
        "transferDetails"
      ],
      "title": "BulkTransferData",
      "type": "object",
      "properties": {
        "instant": {
          "type": "boolean",
          "description": "If set to true, the transfer will be executed as an instant payment.\nPlease note that instant payments may not be supported\nor may incur additional costs depending on the bank.\n"
        },
        "requestedExecutionDate": {
          "type": "string",
          "format": "YYYY-MM-DD",
          "description": "The requested execution date of the transfer.\nPlease note that transfers with execution date may not be supported depending on the bank.\n"
        },
        "transferDetails": {
          "type": "array",
          "items": {
            "title": "TransferDetails",
            "required": [
              "recipient",
              "purpose",
              "iban",
              "amount",
              "currency"
            ],
            "type": "object",
            "properties": {
              "recipient": {
                "type": "string",
                "description": "Receiver of the transfer"
              },
              "purpose": {
                "type": "string",
                "description": "Purpose of the transfer"
              },
              "iban": {
                "type": "string",
                "description": "IBAN of the recipient account"
              },
              "bic": {
                "type": "string",
                "description": "BIC of the recipient account"
              },
              "currency": {
                "type": "string",
                "description": "Currency of the transfer (Alphabetic Code ISO 4217)"
              },
              "amount": {
                "type": "number",
                "description": "Transfer amount"
              },
              "endToEndId": {
                "type": "string",
                "description": "End-to-end identification of the transfer"
              },
              "purposeCode": {
                "type": "string",
                "description": "Code to further classify payment using an [ISO20022 External Code](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)",
                "example": "SALA, DIVD, PENS, LOAN, ..."
              },
              "ultimateDebtor": {
                "type": "string",
                "description": "Ultimate debtor if deviating from account holder"
              },
              "ultimateCreditor": {
                "type": "string",
                "description": "Ultimate creditor if deviating from recipient"
              }
            },
            "description": "TransferDetails are used in InitiateSingleTransfer and InitiateBulkTransfer"
          }
        }
      }
    }
    

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    product-id path string true ID of a banking product
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)
    Rejection-NoFunds-Preferred header boolean false If set to "true", the bank should reject the payment if there are insufficient funds. If set to "false", the bank may wait for a certain period for funds to arrive. This parameter may be ignored by the bank.
    callbackUrl query string(url) true A callback URL.
    autoConfirm query boolean false Flag for REG/Protect to control whether transfers can be entered without interaction
    body body object true The request body object carries the data for a payment. It is expected when creating a payment.
    » instant body boolean false If set to true, the transfer will be executed as an instant payment.
    » requestedExecutionDate body string(YYYY-MM-DD) false The requested execution date of the transfer.
    » transferDetails body [TransferDetails] true [TransferDetails are used in InitiateSingleTransfer and InitiateBulkTransfer]
    »» TransferDetails body TransferDetails false TransferDetails are used in InitiateSingleTransfer and InitiateBulkTransfer
    »»» recipient body string true Receiver of the transfer
    »»» purpose body string true Purpose of the transfer
    »»» iban body string true IBAN of the recipient account
    »»» bic body string false BIC of the recipient account
    »»» currency body string true Currency of the transfer (Alphabetic Code ISO 4217)
    »»» amount body number true Transfer amount
    »»» endToEndId body string false End-to-end identification of the transfer
    »»» purposeCode body string false Code to further classify payment using an ISO20022 External Code
    »»» ultimateDebtor body string false Ultimate debtor if deviating from account holder
    »»» ultimateCreditor body string false Ultimate creditor if deviating from recipient
    Detailed descriptions

    » instant: If set to true, the transfer will be executed as an instant payment. Please note that instant payments may not be supported or may incur additional costs depending on the bank.

    » requestedExecutionDate: The requested execution date of the transfer. Please note that transfers with execution date may not be supported depending on the bank.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/bulk-transfer/fdc61bcd-d0ee-4999-9c77-eff3ba8db0ce"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/fdc61bcd-d0ee-4999-9c77-eff3ba8db0ce"
        }
      ],
      "transfer": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "ebics": false,
        "instant": false,
        "requestedExecutionDate": "2024-09-19",
        "transferDetails": [
          {
            "recipient": "UNICEF",
            "purpose": "Spende UNICEF",
            "iban": "DE57370205000000300000",
            "bic": "BFSWDE33XXX",
            "currency": "EUR",
            "amount": 150,
            "endToEndId": "be7649876d5f439886fa816993ac9f9f"
          },
          {
            "recipient": "netzpolitik.org e. V.",
            "purpose": "Spende netzpolitik.de",
            "iban": "DE62430609671149278400",
            "bic": "GENODEM1GLS",
            "currency": "EUR",
            "amount": 75,
            "endToEndId": "be7649876d5f439886fa816993ac9f9f"
          }
        ]
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the transfer status BulkTransferResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    404 Not Found Bank Access Credentials could not be found None none
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_webform: Contains link to the REG/Protect web application

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Initiate a single debit

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/payment/single-debit \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/bankzugaenge/{access-id}/{product-id}/payment/single-debit

    Initiates a payment for the given bank access, without providing access credentials

    Body parameter

    {
      "allOf": [
        {
          "required": [
            "creditorSchemeIdentification",
            "requestedCollectionDate"
          ],
          "type": "object",
          "properties": {
            "business": {
              "type": "boolean",
              "description": "Indicates whether the debit should be submitted for business or private customers.<br/><br/> It is recommended to assign this field together with `sequenceType` on the top layer (here) and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time."
            },
            "sequenceType": {
              "title": "DebitSequenceType",
              "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
              "enum": [
                "FRST",
                "RCUR",
                "FNAL",
                "OOFF"
              ],
              "type": "string"
            },
            "creditorSchemeIdentification": {
              "type": "string",
              "description": "The scheme identification of the creditor."
            },
            "requestedCollectionDate": {
              "type": "string",
              "format": "YYYY-MM-DD",
              "description": "The requested collection date of the debit."
            }
          }
        },
        {
          "description": "Request data to start a single debit",
          "required": [
            "debitDetails"
          ],
          "title": "SingleDebitDataBankAccess",
          "type": "object",
          "properties": {
            "debitDetails": {
              "allOf": [
                {
                  "title": "DebitDetails",
                  "required": [
                    "amount",
                    "currency",
                    "purpose",
                    "endToEndId",
                    "debtorName",
                    "debtorIban",
                    "mandateIdentification",
                    "mandateDateOfSignature"
                  ],
                  "type": "object",
                  "properties": {
                    "amount": {
                      "type": "number",
                      "format": "double",
                      "description": "Debit amount"
                    },
                    "currency": {
                      "type": "string",
                      "description": "Currency of the debit"
                    },
                    "purpose": {
                      "type": "string",
                      "description": "Purpose of the debit."
                    },
                    "endToEndId": {
                      "type": "string",
                      "description": "End to End Identification of the debit."
                    },
                    "debtorName": {
                      "type": "string",
                      "description": "Name of the debtor."
                    },
                    "debtorIban": {
                      "type": "string",
                      "description": "IBAN of the debtor."
                    },
                    "debtorAccountNumber": {
                      "type": "string",
                      "description": "Account number of the debtor."
                    },
                    "debtorBankCode": {
                      "type": "string",
                      "description": "Bank code of the debtor."
                    },
                    "debtorBic": {
                      "type": "string",
                      "description": "BIC of the debtor."
                    },
                    "mandateIdentification": {
                      "type": "string",
                      "description": "Identification of the mandate."
                    },
                    "mandateDateOfSignature": {
                      "type": "string",
                      "format": "YYYY-MM-DD",
                      "description": "The signature date of the mandate."
                    },
                    "business": {
                      "type": "boolean",
                      "description": "Indicates whether the debit should be submitted for business or private customers.<br/><br/> The mixing of true / false is not allowed in the same request.<br/><br/> It is recommended to assign this field together with `sequenceType` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time."
                    },
                    "sequenceType": {
                      "title": "DebitSequenceType",
                      "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
                      "enum": [
                        "FRST",
                        "RCUR",
                        "FNAL",
                        "OOFF"
                      ],
                      "type": "string"
                    }
                  },
                  "description": "DebitDetails are used in InitiateSingleDebit and InitiateBulkDebit"
                }
              ]
            }
          }
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    product-id path string true ID of a banking product
    body body SingleDebitDataBankAccess true The request body object carries the data for a payment. It is expected when creating a payment.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/single-debit/07788639-abd7-4009-9c9d-2d79079f3f26"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/07788639-abd7-4009-9c9d-2d79079f3f26"
        }
      ],
      "debit": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "business": false,
        "sequenceType": "OOFF",
        "creditorSchemeIdentification": "GlauebigerId",
        "requestedCollectionDate": "2022-02-22",
        "debitDetails": {
          "amount": 1337.42,
          "currency": "EUR",
          "purpose": "Verwendungszweck",
          "endToEndId": "123",
          "debtorName": "Max Mustermann",
          "debtorIban": "DE62430609671149278400",
          "debtorAccountNumber": "1149278400",
          "debtorBankCode": "43060967",
          "debtorBic": "GENODEM1GLS",
          "mandateIdentification": "MandatsId",
          "mandateDateOfSignature": "2022-02-02"
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the debit status SingleDebitResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    404 Not Found Bank Access Credentials could not be found None none
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_webform: Contains link to the REG/Protect web application

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Initiate a bulk debit

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/payment/bulk-debit \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/bankzugaenge/{access-id}/{product-id}/payment/bulk-debit

    Initiates a payment for the given bank access, without providing access credentials

    Body parameter

    {
      "allOf": [
        {
          "required": [
            "creditorSchemeIdentification",
            "requestedCollectionDate"
          ],
          "type": "object",
          "properties": {
            "business": {
              "type": "boolean",
              "description": "Indicates whether the debit should be submitted for business or private customers.<br/><br/> It is recommended to assign this field together with `sequenceType` on the top layer (here) and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time."
            },
            "sequenceType": {
              "title": "DebitSequenceType",
              "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
              "enum": [
                "FRST",
                "RCUR",
                "FNAL",
                "OOFF"
              ],
              "type": "string"
            },
            "creditorSchemeIdentification": {
              "type": "string",
              "description": "The scheme identification of the creditor."
            },
            "requestedCollectionDate": {
              "type": "string",
              "format": "YYYY-MM-DD",
              "description": "The requested collection date of the debit."
            }
          }
        },
        {
          "description": "Request data to start a bulk debit",
          "required": [
            "debitDetails"
          ],
          "title": "BulkDebitDataBankAccess",
          "type": "object",
          "properties": {
            "debitDetails": {
              "type": "array",
              "items": {
                "allOf": [
                  {
                    "title": "DebitDetails",
                    "required": [
                      "amount",
                      "currency",
                      "purpose",
                      "endToEndId",
                      "debtorName",
                      "debtorIban",
                      "mandateIdentification",
                      "mandateDateOfSignature"
                    ],
                    "type": "object",
                    "properties": {
                      "amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Debit amount"
                      },
                      "currency": {
                        "type": "string",
                        "description": "Currency of the debit"
                      },
                      "purpose": {
                        "type": "string",
                        "description": "Purpose of the debit."
                      },
                      "endToEndId": {
                        "type": "string",
                        "description": "End to End Identification of the debit."
                      },
                      "debtorName": {
                        "type": "string",
                        "description": "Name of the debtor."
                      },
                      "debtorIban": {
                        "type": "string",
                        "description": "IBAN of the debtor."
                      },
                      "debtorAccountNumber": {
                        "type": "string",
                        "description": "Account number of the debtor."
                      },
                      "debtorBankCode": {
                        "type": "string",
                        "description": "Bank code of the debtor."
                      },
                      "debtorBic": {
                        "type": "string",
                        "description": "BIC of the debtor."
                      },
                      "mandateIdentification": {
                        "type": "string",
                        "description": "Identification of the mandate."
                      },
                      "mandateDateOfSignature": {
                        "type": "string",
                        "format": "YYYY-MM-DD",
                        "description": "The signature date of the mandate."
                      },
                      "business": {
                        "type": "boolean",
                        "description": "Indicates whether the debit should be submitted for business or private customers.<br/><br/> The mixing of true / false is not allowed in the same request.<br/><br/> It is recommended to assign this field together with `sequenceType` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time."
                      },
                      "sequenceType": {
                        "title": "DebitSequenceType",
                        "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
                        "enum": [
                          "FRST",
                          "RCUR",
                          "FNAL",
                          "OOFF"
                        ],
                        "type": "string"
                      }
                    },
                    "description": "DebitDetails are used in InitiateSingleDebit and InitiateBulkDebit"
                  }
                ]
              }
            }
          }
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    product-id path string true ID of a banking product
    body body BulkDebitDataBankAccess true The request body object carries the data for a payment. It is expected when creating a payment.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/bulk-debit/0b1937c7-82eb-49d4-99cb-6fdca765c450"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/0b1937c7-82eb-49d4-99cb-6fdca765c450"
        }
      ],
      "debit": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "business": false,
        "sequenceType": "OOFF",
        "creditorSchemeIdentification": "GlauebigerId",
        "requestedCollectionDate": "2022-02-22",
        "debitDetails": [
          {
            "amount": 1337.42,
            "currency": "EUR",
            "purpose": "Verwendungszweck",
            "endToEndId": "123",
            "debtorName": "Max Mustermann",
            "debtorIban": "DE62430609671149278400",
            "debtorAccountNumber": "1149278400",
            "debtorBankCode": "43060967",
            "debtorBic": "GENODEM1GLS",
            "mandateIdentification": "MandatsId",
            "mandateDateOfSignature": "2022-02-02"
          },
          {
            "amount": 42,
            "currency": "EUR",
            "purpose": "Verwendungszweck 2",
            "endToEndId": "124",
            "debtorName": "Maxi Mustermann",
            "debtorIban": "DE00123456789012345678",
            "debtorAccountNumber": "9012345678",
            "debtorBankCode": "12345678",
            "debtorBic": "SSKMDEMMXXX",
            "mandateIdentification": "MandatsId",
            "mandateDateOfSignature": "2022-02-02"
          }
        ]
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the debit status BulkDebitResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    404 Not Found Bank Access Credentials could not be found None none
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_webform: Contains link to the REG/Protect web application

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Customer Ueberweisung

    Legacy endpoints, that will be replaced by the endpoints in 'Customer Payment'

    Create Transfer

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/ueberweisung/{provider-id}/{product-id}?callbackUrl=https%3A%2F%2Fdemo-tenant.com%2Fcallback%3Fstate%3D123 \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Authorization: Bearer {access-token}'
    
    

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

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

    Body parameter

    {
      "allOf": [
        {
          "allOf": [
            {
              "title": "UeberweisungDetails",
              "required": [
                "empfaenger",
                "verwendungszweck",
                "iban",
                "betrag",
                "waehrung"
              ],
              "type": "object",
              "properties": {
                "empfaenger": {
                  "type": "string",
                  "description": "Receiver of the transfer"
                },
                "verwendungszweck": {
                  "type": "string",
                  "description": "Purpose of the transfer."
                },
                "iban": {
                  "type": "string",
                  "description": "IBAN of the recipient account"
                },
                "bic": {
                  "type": "string",
                  "description": "BIC of the recipient account"
                },
                "waehrung": {
                  "type": "string",
                  "description": "Currency of the transfer (Alphabetic Code ISO 4217)"
                },
                "betrag": {
                  "type": "number",
                  "description": "Transfer amount"
                }
              },
              "description": "UeberweisungDetails are used in CreateTransfer and CreateBulkTransfer"
            }
          ]
        },
        {
          "title": "CreateTransfer",
          "required": [
            "empfaenger",
            "verwendungszweck",
            "iban",
            "betrag",
            "bic",
            "waehrung"
          ],
          "type": "object",
          "properties": {
            "credentials": {
              "title": "Credentials",
              "description": "The Credentials object is a map of encrypted and Base64-encoded access data, corresponding\nto the provider's authentication fields. The Base64 encoding must not use line wrapping.\n\nThe encryption method used is described in the chapter Encryption.\n\nThe Credentials object is not required for REG/Protect tenants only.",
              "required": [
                "userid",
                "pin"
              ],
              "type": "object",
              "properties": {
                "userid": {
                  "type": "string",
                  "example": "cust0815",
                  "description": "Encrypted and Base64-encoded username of the user at the bank, e.g. used in his online banking.<br/>EBICS: The User-ID (Teilnehmer-ID) as provided by the bank must be transmitted."
                },
                "pin": {
                  "type": "string",
                  "example": "verySecret",
                  "description": "Encrypted and Base64-encoded pin / password of the user at the bank, e.g. used in his online banking.<br/>EBICS: A pin must not be transmitted."
                },
                "partnerid": {
                  "type": "string",
                  "example": "PID0001",
                  "description": "Encrypted and Base64-encoded partner id (Kunden-ID) only required for EBICS."
                },
                "corporateid": {
                  "type": "string",
                  "example": 123456,
                  "description": "Encrypted and Base64-encoded corporate id required by some banks for business accounts."
                }
              },
              "example": {
                "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
                "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
              }
            },
            "sicherheitsverfahrenKodierung": {
              "type": "integer",
              "description": "Coding of the security procedure to use , see Bank product",
              "format": "int32"
            },
            "ausfuehrungsdatum": {
              "title": "DateTime",
              "description": "This object represents a timestamp. Format: `YYYY-MM-DD hh:mm:ss`. Data will be interpreted according to the time zone Europe/Berlin.",
              "type": "string",
              "example": "2019-12-04 13:37:00"
            },
            "tanMediumName": {
              "type": "string",
              "description": "The TAN medium to be used"
            }
          },
          "description": "Request data to start a transfer",
          "example": {
            "credentials": {
              "userid": "mXlkGe+ukA ... MOfGsd8HY=",
              "pin": "XO2jg ... 5GfhKpZmw="
            },
            "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"
          }
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    provider-id path string(uuid) true ID of a provider
    product-id path string true ID of a banking product
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)
    callbackUrl query string(url) true A callback URL.
    editableDetails query boolean false Flag for REG/Protect to control whether fields on the frontend are editable
    body body CreateTransfer false The request body object carries the data for a payment. It is expected when creating a payment. It is not required for REG/Protect tenants when requesting with editableDetails=true.

    Example responses

    200 Response

    {
      "ueberweisung": {
        "empfaenger": "netzpolitik.org e. V.",
        "verwendungszweck": "Spende netzpolitik.de",
        "iban": "DE62430609671149278400",
        "bic": "GENODEM1GLS",
        "waehrung": "EUR",
        "betrag": 1337.42
      },
      "ausfuehrungsdatum": "2016-12-24",
      "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/customer/v2/ueberweisung/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7/consent"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the transfer status ScaInteraction set_method: Set SCA method

    Create Bulk Transfer

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/ueberweisung/bulk/{provider-id}/{product-id}?callbackUrl=https%3A%2F%2Fdemo-tenant.com%2Fcallback%3Fstate%3D123 \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Authorization: Bearer {access-token}'
    
    

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

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

    Body parameter

    {
      "payments": [
        {
          "empfaenger": "UNICEF",
          "verwendungszweck": "Spende UNICEF",
          "iban": "DE57370205000000300000",
          "bic": "BFSWDE33XXX",
          "waehrung": "EUR",
          "betrag": 150
        },
        {
          "empfaenger": "netzpolitik.org e. V.",
          "verwendungszweck": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "waehrung": "EUR",
          "betrag": 75
        }
      ],
      "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/customer/v2/ueberweisung/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7/consent"
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    provider-id path string(uuid) true ID of a provider
    product-id path string true ID of a banking product
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)
    callbackUrl query string(url) true A callback URL.
    body body CreateBulkTransferLegacy true The request body object carries the data for a payment. It is expected when creating a payment.

    Example responses

    200 Response

    {
      "payments": [
        {
          "empfaenger": "UNICEF",
          "verwendungszweck": "Spende UNICEF",
          "iban": "DE57370205000000300000",
          "bic": "BFSWDE33XXX",
          "waehrung": "EUR",
          "betrag": 150
        },
        {
          "empfaenger": "netzpolitik.org e. V.",
          "verwendungszweck": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "waehrung": "EUR",
          "betrag": 75
        }
      ],
      "ausfuehrungsdatum": "2016-12-24",
      "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/customer/v2/ueberweisung/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7/consent"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the transfer status ScaInteraction set_method: Set SCA method

    Submit TAN

    Code samples

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

    PUT /customer/v2/ueberweisung/{provider-id}/{product-id}/{payment-id}

    Submits a TAN for a previously created payment.

    Body parameter

    {
      "tan": "4103582"
    }
    

    Parameters

    Name In Type Required Description
    provider-id path string(uuid) true ID of a provider
    product-id path string true ID of a banking product
    payment-id path string(uuid) true ID of the payment
    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

    Submit TAN (Bulk)

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/customer/v2/ueberweisung/bulk/{provider-id}/{product-id}/{payment-id} \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    PUT /customer/v2/ueberweisung/bulk/{provider-id}/{product-id}/{payment-id}

    Submits a TAN for a previously created bulk payment. Confer Submit TAN for details.

    Parameters

    Name In Type Required Description
    provider-id path string(uuid) true ID of a provider
    product-id path string true ID of a banking product
    payment-id path string(uuid) true ID of the 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"
        },
        "decoupled": false,
        "redirect": false
      }
    }
    

    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 none

    Customer Payment

    Initiate Single Transfer

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/payment/single-transfer?callbackUrl=https%3A%2F%2Fdemo-tenant.com%2Fcallback%3Fstate%3D123 \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Rejection-NoFunds-Preferred: true' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/payment/single-transfer

    Initiates a single transfer (e.g. a SEPA transfer).

    Body parameter

    {
      "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iH ... D/MOfGsd8HY=",
        "pin": "XO2jgZ ... 5GfhKpZmw="
      },
      "product": "DE89370400440532013000",
      "instant": false,
      "requestedExecutionDate": "2024-09-19",
      "transferDetails": {
        "recipient": "netzpolitik.org e. V.",
        "purpose": "Spende netzpolitik.de",
        "iban": "DE62430609671149278400",
        "bic": "GENODEM1GLS",
        "currency": "EUR",
        "amount": 1337.42,
        "endToEndId": "be7649876d5f439886fa816993ac9f9f"
      }
    }
    

    Parameters

    Name In Type Required Description
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)
    Rejection-NoFunds-Preferred header boolean false If set to "true", the bank should reject the payment if there are insufficient funds. If set to "false", the bank may wait for a certain period for funds to arrive. This parameter may be ignored by the bank.
    callbackUrl query string(url) true A callback URL.
    queryTanSettings query boolean false Flag to ignore saved TAN-settings and query them.
    editableDetails query boolean false Flag for REG/Protect to control whether fields on the frontend are editable
    body body SingleTransferData true The request body object carries the data for a payment. It is expected when creating a payment. It is not required for REG/Protect tenants when requesting with editableDetails=true.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/single-transfer/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        }
      ],
      "transfer": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "ebics": false,
        "instant": false,
        "requestedExecutionDate": "2024-09-19",
        "transferDetails": {
          "recipient": "netzpolitik.org e. V.",
          "purpose": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "currency": "EUR",
          "amount": 1337.42,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the transfer status SingleTransferResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_webform: Contains link to the REG/Protect web application

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Get Single Transfer

    Code samples

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

    GET /customer/v2/payment/single-transfer/{payment-id}

    Get the current status of the single transfer.

    Parameters

    Name In Type Required Description
    payment-id path string(uuid) true ID of the payment

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/single-transfer/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/payment/single-transfer/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7/consent"
        }
      ],
      "transfer": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "ebics": false,
        "instant": false,
        "requestedExecutionDate": "2024-09-19",
        "transferDetails": {
          "recipient": "netzpolitik.org e. V.",
          "purpose": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "currency": "EUR",
          "amount": 1337.42,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns the current status of the single transfer. SingleTransferResult none

    Initiate Bulk Transfer

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/payment/bulk-transfer?callbackUrl=https%3A%2F%2Fdemo-tenant.com%2Fcallback%3Fstate%3D123 \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Customer-IP-Address: 154.25.45.133' \
      -H 'Rejection-NoFunds-Preferred: true' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/payment/bulk-transfer

    Initiates a bulk transfer (e.g. a SEPA bulk transfer).

    Body parameter

    {
      "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iH... D/MOfGsd8HY=",
        "pin": "XO2jgZ... 5GfhKpZmw="
      },
      "product": "DE89370400440532013000",
      "instant": false,
      "requestedExecutionDate": "2024-09-19",
      "transferDetails": [
        {
          "recipient": "UNICEF",
          "purpose": "Spende UNICEF",
          "iban": "DE57370205000000300000",
          "bic": "BFSWDE33XXX",
          "currency": "EUR",
          "amount": 150,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        },
        {
          "recipient": "netzpolitik.org e. V.",
          "purpose": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "currency": "EUR",
          "amount": 75,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    Customer-IP-Address header string true The IP address of the customer. Must be a public IP address (IPv4, IPv6)
    Rejection-NoFunds-Preferred header boolean false If set to "true", the bank should reject the payment if there are insufficient funds. If set to "false", the bank may wait for a certain period for funds to arrive. This parameter may be ignored by the bank.
    callbackUrl query string(url) true A callback URL.
    queryTanSettings query boolean false Flag to ignore saved TAN-settings and query them.
    body body BulkTransferData true The request body object carries the data for a payment. It is expected when creating a payment.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/bulk-transfer/fdc61bcd-d0ee-4999-9c77-eff3ba8db0ce"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/fdc61bcd-d0ee-4999-9c77-eff3ba8db0ce"
        }
      ],
      "transfer": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "ebics": false,
        "instant": false,
        "requestedExecutionDate": "2024-09-19",
        "transferDetails": [
          {
            "recipient": "UNICEF",
            "purpose": "Spende UNICEF",
            "iban": "DE57370205000000300000",
            "bic": "BFSWDE33XXX",
            "currency": "EUR",
            "amount": 150,
            "endToEndId": "be7649876d5f439886fa816993ac9f9f"
          },
          {
            "recipient": "netzpolitik.org e. V.",
            "purpose": "Spende netzpolitik.de",
            "iban": "DE62430609671149278400",
            "bic": "GENODEM1GLS",
            "currency": "EUR",
            "amount": 75,
            "endToEndId": "be7649876d5f439886fa816993ac9f9f"
          }
        ]
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the transfer status BulkTransferResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_webform: Contains link to the REG/Protect web application

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Get Bulk Transfer

    Code samples

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

    GET /customer/v2/payment/bulk-transfer/{payment-id}

    Get the current status of the bulk transfer.

    Parameters

    Name In Type Required Description
    payment-id path string(uuid) true ID of the payment

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/bulk-transfer/fdc61bcd-d0ee-4999-9c77-eff3ba8db0ce"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/payment/bulk-transfer/fdc61bcd-d0ee-4999-9c77-eff3ba8db0ce/consent"
        }
      ],
      "transfer": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "ebics": false,
        "instant": false,
        "requestedExecutionDate": "2024-09-19",
        "transferDetails": [
          {
            "recipient": "UNICEF",
            "purpose": "Spende UNICEF",
            "iban": "DE57370205000000300000",
            "bic": "BFSWDE33XXX",
            "currency": "EUR",
            "amount": 150,
            "endToEndId": "be7649876d5f439886fa816993ac9f9f"
          },
          {
            "recipient": "netzpolitik.org e. V.",
            "purpose": "Spende netzpolitik.de",
            "iban": "DE62430609671149278400",
            "bic": "GENODEM1GLS",
            "currency": "EUR",
            "amount": 75,
            "endToEndId": "be7649876d5f439886fa816993ac9f9f"
          }
        ]
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns the current status of the bulk transfer. BulkTransferResult none

    Initiate Single Debit

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/payment/single-debit \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/payment/single-debit

    Initiates a single debit (e.g. a SEPA debit).

    Body parameter

    {
      "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iH ... D/MOfGsd8HY=",
        "pin": "XO2jgZ ... 5GfhKpZmw="
      },
      "product": "DE89370400440532013000",
      "business": false,
      "sequenceType": "OOFF",
      "creditorSchemeIdentification": "GlauebigerId",
      "requestedCollectionDate": "2022-02-22",
      "debitDetails": {
        "amount": 1337.42,
        "currency": "EUR",
        "purpose": "Verwendungszweck",
        "endToEndId": "123",
        "debtorName": "Max Mustermann",
        "debtorIban": "DE62430609671149278400",
        "debtorAccountNumber": "1149278400",
        "debtorBankCode": "43060967",
        "debtorBic": "GENODEM1GLS",
        "mandateIdentification": "MandatsId",
        "mandateDateOfSignature": "2022-02-02"
      }
    }
    

    Parameters

    Name In Type Required Description
    queryTanSettings query boolean false Flag to ignore saved TAN-settings and query them.
    body body SingleDebitData true The request body object carries the data for a payment. It is expected when creating a payment.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/single-debit/07788639-abd7-4009-9c9d-2d79079f3f26"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/07788639-abd7-4009-9c9d-2d79079f3f26"
        }
      ],
      "debit": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "business": false,
        "sequenceType": "OOFF",
        "creditorSchemeIdentification": "GlauebigerId",
        "requestedCollectionDate": "2022-02-22",
        "debitDetails": {
          "amount": 1337.42,
          "currency": "EUR",
          "purpose": "Verwendungszweck",
          "endToEndId": "123",
          "debtorName": "Max Mustermann",
          "debtorIban": "DE62430609671149278400",
          "debtorAccountNumber": "1149278400",
          "debtorBankCode": "43060967",
          "debtorBic": "GENODEM1GLS",
          "mandateIdentification": "MandatsId",
          "mandateDateOfSignature": "2022-02-02"
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the debit status SingleDebitResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_webform: Contains link to the REG/Protect web application

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Get Single Debit

    Code samples

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

    GET /customer/v2/payment/single-debit/{payment-id}

    Get the current status of the single debit.

    Parameters

    Name In Type Required Description
    payment-id path string(uuid) true ID of the payment

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/single-debit/07788639-abd7-4009-9c9d-2d79079f3f26"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/07788639-abd7-4009-9c9d-2d79079f3f26"
        }
      ],
      "debit": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "business": false,
        "sequenceType": "OOFF",
        "creditorSchemeIdentification": "GlauebigerId",
        "requestedCollectionDate": "2022-02-22",
        "debitDetails": {
          "amount": 1337.42,
          "currency": "EUR",
          "purpose": "Verwendungszweck",
          "endToEndId": "123",
          "debtorName": "Max Mustermann",
          "debtorIban": "DE62430609671149278400",
          "debtorAccountNumber": "1149278400",
          "debtorBankCode": "43060967",
          "debtorBic": "GENODEM1GLS",
          "mandateIdentification": "MandatsId",
          "mandateDateOfSignature": "2022-02-02"
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the debit status SingleDebitResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it

    Initiate Bulk Debit

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/payment/bulk-debit \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    POST /customer/v2/payment/bulk-debit

    Initiates a bulk debit (e.g. a SEPA debit).

    Body parameter

    {
      "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iH ... D/MOfGsd8HY=",
        "pin": "XO2jgZ ... 5GfhKpZmw="
      },
      "product": "DE89370400440532013000",
      "business": false,
      "sequenceType": "OOFF",
      "creditorSchemeIdentification": "GlauebigerId",
      "requestedCollectionDate": "2022-02-22",
      "debitDetails": [
        {
          "amount": 1337.42,
          "currency": "EUR",
          "purpose": "Verwendungszweck",
          "endToEndId": "123",
          "debtorName": "Max Mustermann",
          "debtorIban": "DE62430609671149278400",
          "debtorAccountNumber": "1149278400",
          "debtorBankCode": "43060967",
          "debtorBic": "GENODEM1GLS",
          "mandateIdentification": "MandatsId",
          "mandateDateOfSignature": "2022-02-02"
        },
        {
          "amount": 42,
          "currency": "EUR",
          "purpose": "Verwendungszweck 2",
          "endToEndId": "124",
          "debtorName": "Maxi Mustermann",
          "debtorIban": "DE00123456789012345678",
          "debtorAccountNumber": "9012345678",
          "debtorBankCode": "12345678",
          "debtorBic": "SSKMDEMMXXX",
          "mandateIdentification": "MandatsId",
          "mandateDateOfSignature": "2022-02-02"
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    queryTanSettings query boolean false Flag to ignore saved TAN-settings and query them.
    body body BulkDebitData true The request body object carries the data for a payment. It is expected when creating a payment.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/bulk-debit/0b1937c7-82eb-49d4-99cb-6fdca765c450"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/0b1937c7-82eb-49d4-99cb-6fdca765c450"
        }
      ],
      "debit": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "business": false,
        "sequenceType": "OOFF",
        "creditorSchemeIdentification": "GlauebigerId",
        "requestedCollectionDate": "2022-02-22",
        "debitDetails": [
          {
            "amount": 1337.42,
            "currency": "EUR",
            "purpose": "Verwendungszweck",
            "endToEndId": "123",
            "debtorName": "Max Mustermann",
            "debtorIban": "DE62430609671149278400",
            "debtorAccountNumber": "1149278400",
            "debtorBankCode": "43060967",
            "debtorBic": "GENODEM1GLS",
            "mandateIdentification": "MandatsId",
            "mandateDateOfSignature": "2022-02-02"
          },
          {
            "amount": 42,
            "currency": "EUR",
            "purpose": "Verwendungszweck 2",
            "endToEndId": "124",
            "debtorName": "Maxi Mustermann",
            "debtorIban": "DE00123456789012345678",
            "debtorAccountNumber": "9012345678",
            "debtorBankCode": "12345678",
            "debtorBic": "SSKMDEMMXXX",
            "mandateIdentification": "MandatsId",
            "mandateDateOfSignature": "2022-02-02"
          }
        ]
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the debit status BulkDebitResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    get_webform: Contains link to the REG/Protect web application

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Get Bulk Debit

    Code samples

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

    GET /customer/v2/payment/bulk-debit/{payment-id}

    Get the current status of the bulk debit.

    Parameters

    Name In Type Required Description
    payment-id path string(uuid) true ID of the payment

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/bulk-debit/0b1937c7-82eb-49d4-99cb-6fdca765c450"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/0b1937c7-82eb-49d4-99cb-6fdca765c450"
        }
      ],
      "debit": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "5208b5cb-2f88-4bba-87a5-c5e0356c460c",
        "business": false,
        "sequenceType": "OOFF",
        "creditorSchemeIdentification": "GlauebigerId",
        "requestedCollectionDate": "2022-02-22",
        "debitDetails": [
          {
            "amount": 1337.42,
            "currency": "EUR",
            "purpose": "Verwendungszweck",
            "endToEndId": "123",
            "debtorName": "Max Mustermann",
            "debtorIban": "DE62430609671149278400",
            "debtorAccountNumber": "1149278400",
            "debtorBankCode": "43060967",
            "debtorBic": "GENODEM1GLS",
            "mandateIdentification": "MandatsId",
            "mandateDateOfSignature": "2022-02-02"
          },
          {
            "amount": 42,
            "currency": "EUR",
            "purpose": "Verwendungszweck 2",
            "endToEndId": "124",
            "debtorName": "Maxi Mustermann",
            "debtorIban": "DE00123456789012345678",
            "debtorAccountNumber": "9012345678",
            "debtorBankCode": "12345678",
            "debtorBic": "SSKMDEMMXXX",
            "mandateIdentification": "MandatsId",
            "mandateDateOfSignature": "2022-02-02"
          }
        ]
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the debit status BulkDebitResult self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it

    Code samples

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

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

    Get the current status of the consent, without polling the provider

    Name In Type Required Description
    consent-id path string(uuid) true ID of the consent

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3020",
          "message": "SCA Medium auswählen",
          "details": "Bitte wählen Sie ein SCA-Medium aus"
        }
      ],
      "scaMediums": [
        {
          "name": "Handy Eins",
          "mediaClass": "MOBILE"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        },
        {
          "rel": "set_medium",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        }
      ]
    }
    
    Status Meaning Description Schema Possible relations
    200 OK Returns the current status of the consent. Consent self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    get_single_transfer: Returns the corresponding single transfer, if available
    get_bulk_transfer: Returns the corresponding bulk transfer, if available
    get_single_debit: Returns the corresponding single debit, if available
    get_bulk_debit: Returns the corresponding bulk debit, if available

    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: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

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

    Submits a SCA method, medium or authentication data for the current SCA.

    Body parameter

    {
      "chosenScaMethodId": "942"
    }
    
    Name In Type Required Description
    consent-id path string(uuid) true ID of the consent
    body body SubmitScaData true none

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3020",
          "message": "SCA Medium auswählen",
          "details": "Bitte wählen Sie ein SCA-Medium aus"
        }
      ],
      "scaMediums": [
        {
          "name": "Handy Eins",
          "mediaClass": "MOBILE"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        },
        {
          "rel": "set_medium",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        }
      ]
    }
    
    Status Meaning Description Schema Possible relations
    200 OK Returns the current status of the consent. Consent self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    get_single_transfer: Returns the corresponding single transfer, if available
    get_bulk_transfer: Returns the corresponding bulk transfer, if available
    get_single_debit: Returns the corresponding single debit, if available
    get_bulk_debit: Returns the corresponding bulk debit, if available

    Code samples

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

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

    Can be used for the decoupled SCA approach to check if the SCA has already been confirmed.

    Name In Type Required Description
    consent-id path string(uuid) true ID of the consent

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3030",
          "message": "SCA Challenge",
          "details": "Bitte autorisieren Sie den Vorgang"
        }
      ],
      "challenge": {
        "name": "Entkoppelte Authentifizierung",
        "content": {
          "instructions": "Bitte führen Sie die entkoppelte Authentifizierung durch."
        },
        "decoupled": true,
        "redirect": false
      },
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        },
        {
          "rel": "authenticate",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7"
        },
        {
          "rel": "authenticate_decoupled",
          "href": "https://banksapi.io/customer/v2/consent/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7/poll"
        }
      ]
    }
    
    Status Meaning Description Schema Possible relations
    200 OK Returns the current status of the consent. Consent self: Returns the corresponding entity (e.g. bank access, single transfer, consent...)
    set_method: Sets chosenScaMethodId, available if current SCA requires it
    set_medium: Sets chosenScaMedia, available if current SCA requires it
    authenticate: Sends scaAuthenticationData, available if current SCA requires it
    authenticate_decoupled: Polls current authentication status, available if current SCA requires to be completed on a different device or app
    cancel: Cancels current SCA, available if current SCA allows it
    get_single_transfer: Returns the corresponding single transfer, if available
    get_bulk_transfer: Returns the corresponding bulk transfer, if available
    get_single_debit: Returns the corresponding single debit, if available
    get_bulk_debit: Returns the corresponding bulk debit, if available

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/consent/{consent-id}/cancel \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

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

    Cancels an SCA redirect and stops the corresponding access synchronization. This request is permitted only for the redirect SCA approach.

    Name In Type Required Description
    consent-id path string(uuid) true ID of the consent

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "ERROR",
          "code": "BA3040",
          "message": "SCA fehlgeschlagen",
          "details": "Redirect-SCA wurde abgebrochen"
        }
      ]
    }
    
    Status Meaning Description Schema Possible relations
    200 OK Returns the current status of the consent. Consent none

    Customer REG/Protect

    Delete all REG/Protect sessions

    Code samples

    ## You can also use wget
    curl -X DELETE https://banksapi.io/customer/v2/regprotect/sessions \
      -H 'Authorization: Bearer {access-token}'
    
    

    DELETE /customer/v2/regprotect/sessions

    Invalidates all REG/Protect sessions 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

    Change bank product selection

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/customer/v2/bankzugaenge/{access-id}/selectedbankproducts \
      -H 'Authorization: Bearer {access-token}'
    
    

    PUT /customer/v2/bankzugaenge/{access-id}/selectedbankproducts

    Change the selected products of the given bank access

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access

    Responses

    Status Meaning Description Schema Possible relations
    451 Unavailable For Legal Reasons This response is for REG/Protect tenants. It contains a link to the REG/Protect application in the HTTP header Location None none

    Response Headers

    Status Header Type Format Description
    451 Location string Link to the REG/Protect application. Append a callbackUrl query-parameter to the URL

    Encrypt

    Encrypt plaintexts

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/encrypt \
      -H 'Content-Type: application/octet-stream+base64' \
      -H 'Accept: application/octet-stream+base64' \
      -H 'Authorization: Bearer {access-token}'
    
    

    PUT /encrypt

    Encrypt a given plaintext for the tenant identified by the given bearer token.

    Body parameter

    type: string
    
    

    Parameters

    Name In Type Required Description
    body body string true Plaintext to encrypt encoded in Base64

    Example responses

    200 Response

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Ciphertext (encrypted plaintext) encoded in Base64 string none

    Customer Bank Access Builder

    Push transactions for the given product

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

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

    Pushes transactions for the given product identified by an access and a product ID

    Body parameter

    {
      "type": "array",
      "items": {
        "title": "Transaction Data",
        "required": [
          "betrag",
          "verwendungszweck",
          "buchungsdatum"
        ],
        "type": "object",
        "properties": {
          "betrag": {
            "type": "number",
            "description": "Amount with two decimal places.",
            "example": -64.55
          },
          "waehrung": {
            "type": "string",
            "description": "Currency of the transaction.",
            "example": "EUR"
          },
          "verwendungszweck": {
            "type": "string",
            "description": "The purpose of the transaction.",
            "example": "EC 68096654 140215204106OC3 Ref. 5CC15048A1824480/89280"
          },
          "buchungstext": {
            "type": "string",
            "description": "A text for the entry of the transaction"
          },
          "buchungsdatum": {
            "type": "string",
            "description": "The date of the entry of the transaction",
            "format": "YYYY-MM-DD hh:mm:ss",
            "example": "2016-05-23 13:37:00"
          },
          "wertstellungsdatum": {
            "type": "string",
            "description": "Date of booking",
            "format": "YYYY-MM-DD hh:mm:ss",
            "example": "2016-11-15 00:00:00"
          },
          "gegenkontoInhaber": {
            "type": "string",
            "description": "Owner of the counter account",
            "example": "La Sopia GmbH München"
          },
          "gegenkontoIban": {
            "type": "string",
            "description": "IBAN of the counter account",
            "example": "DE00123456789012345679"
          },
          "gegenkontoBic": {
            "type": "string",
            "description": "BIC of the counter account",
            "example": "XXX12345678"
          },
          "gegenkontoInhaberAbweichend": {
            "type": "string",
            "description": "Ultimate owner of the counter account",
            "example": "La Sopia GmbH München"
          },
          "primanotaNummer": {
            "type": "string",
            "description": "Primanota number of sales",
            "example": "421337"
          },
          "gvCode": {
            "type": "string",
            "description": "Provider specific code, that denotes transaction use cases",
            "example": "302"
          },
          "identifier": {
            "type": "object",
            "properties": {
              "endToEndId": {
                "type": "string"
              },
              "proprietaryCode": {
                "type": "string",
                "description": "Used for example for PayPal's proprietary transaction ID"
              },
              "entryReference": {
                "type": "string"
              },
              "ownerRef": {
                "type": "string"
              },
              "bookingRef": {
                "type": "string"
              },
              "balance": {
                "type": "number"
              },
              "mandateId": {
                "type": "string",
                "description": "Contains the SEPA mandate reference"
              },
              "batchId": {
                "type": "string"
              }
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "properties": {
                "entity": {
                  "properties": {
                    "displayName": {
                      "description": "Display name of the entity",
                      "example": "TRANSACTION",
                      "type": "string"
                    },
                    "entityClass": {
                      "description": "Class of the entity, such as TRANSACTION or USER",
                      "example": "TRANSACTION",
                      "type": "string"
                    },
                    "id": {
                      "description": "Transaction UUID or USER UUID.",
                      "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
                      "type": "string"
                    },
                    "userId": {
                      "description": "UUID of the USER. Same as id field for USER entities.",
                      "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
                      "type": "string"
                    }
                  },
                  "required": [
                    "displayName",
                    "entityClass",
                    "id"
                  ],
                  "type": "object"
                },
                "id": {
                  "description": "Unique Universal Identifier (UUID)",
                  "example": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
                  "type": "string"
                },
                "relations": {
                  "description": "List of relations",
                  "items": {
                    "properties": {
                      "href": {
                        "description": "Link of the relation",
                        "example": "https://banksapi.io/.../tags/tag-trees/1/",
                        "type": "string"
                      },
                      "rel": {
                        "description": "Name of the relation",
                        "example": "tag_trees",
                        "type": "string"
                      }
                    },
                    "required": [
                      "href",
                      "rel"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "tagTreeItem": {
                  "properties": {
                    "description": {
                      "description": "Gives a description of the tagTreeItem",
                      "example": "Expenses from daily grocery purchases",
                      "type": "string"
                    },
                    "displayName": {
                      "description": "User-friendly name shown to the end-users",
                      "example": "Groceries",
                      "type": "string"
                    },
                    "relations": {
                      "description": "List of relations",
                      "items": {
                        "properties": {
                          "href": {
                            "description": "Link of the relation",
                            "example": "https://banksapi.io/.../tags/tag-trees/1/",
                            "type": "string"
                          },
                          "rel": {
                            "description": "Name of the relation",
                            "example": "tag_trees",
                            "type": "string"
                          }
                        },
                        "required": [
                          "href",
                          "rel"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "systemId": {
                      "description": "Unique internal id of the tag tree item",
                      "example": 17,
                      "type": "integer"
                    },
                    "systemName": {
                      "description": "Unique name of the tag tree item",
                      "example": "LIVING_GROCERIES",
                      "type": "string"
                    },
                    "systemNameParent": {
                      "description": "Unique name of the parent of the tagTreeItem",
                      "example": "LIVING",
                      "type": "string"
                    },
                    "tagTree": {
                      "allOf": [
                        {
                          "example": {
                            "description": "Two level categorization tree.",
                            "displayName": "Kategorien",
                            "isClientGenerated": false,
                            "relations": [
                              {
                                "href": "https://banksapi.io/tags/v1/tag-trees/1/",
                                "rel": "self"
                              },
                              {
                                "href": "https://banksapi.io/tags/v1/tag-trees/",
                                "rel": "tag_trees"
                              },
                              {
                                "href": "https://banksapi.io/tags/v1/tag-trees/1/tag-tree-items/",
                                "rel": "tag_tree_items"
                              }
                            ],
                            "systemId": 1,
                            "systemName": "CATEGORIES",
                            "version": 3.7
                          },
                          "properties": {
                            "description": {
                              "description": "Gives a description of the tag tree",
                              "example": "Detailed inusrance categories.",
                              "type": "string"
                            },
                            "displayName": {
                              "description": "User-friendly name shown to the end-users",
                              "example": "Kategorien",
                              "type": "string"
                            },
                            "isTenantGenerated": {
                              "description": "Boolean flag, set TRUE if the tag was manually set",
                              "example": true,
                              "type": "boolean"
                            },
                            "relations": {
                              "description": "List of relations",
                              "items": {
                                "properties": {
                                  "href": {
                                    "description": "Link of the relation",
                                    "example": "https://banksapi.io/.../tags/tag-trees/1/",
                                    "type": "string"
                                  },
                                  "rel": {
                                    "description": "Name of the relation",
                                    "example": "tag_trees",
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "href",
                                  "rel"
                                ],
                                "type": "object"
                              },
                              "type": "array"
                            },
                            "systemId": {
                              "description": "Unique internal id of the tag tree",
                              "example": 1,
                              "type": "integer"
                            },
                            "systemName": {
                              "description": "Unique name of the tag tree",
                              "example": "CATEGORIES",
                              "type": "string"
                            },
                            "version": {
                              "description": "Version of the tag tree",
                              "example": 1.5,
                              "minimum": 0,
                              "type": "number"
                            }
                          },
                          "required": [
                            "systemName"
                          ],
                          "type": "object"
                        }
                      ],
                      "description": "tagTree that the tagTreeItem belongs to",
                      "type": "object"
                    }
                  },
                  "required": [
                    "systemName",
                    "tagTree"
                  ],
                  "type": "object"
                }
              },
              "required": [
                "entity",
                "id",
                "tagTreeItem"
              ],
              "type": "object"
            }
          }
        },
        "example": {
          "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"
        }
      }
    }
    

    Parameters

    Name In Type Required Description
    access-id path string(uuid) true ID of the bank access
    product-id path string true ID of a banking product
    body body array[object] true List of transactions for this product

    Responses

    Status Meaning Description Schema Possible relations
    201 Created Created None none

    Create Bank Access Builder

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/customer/v2/bankzugaenge/builder \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer {access-token}'
    
    

    PUT /customer/v2/bankzugaenge/builder

    Creates a builder instance for a bank access.

    Body parameter

    {
      "id": "815251d6-c062-4f61-bec0-182bc14a48fb",
      "providerId": "00000000-0000-0000-0000-000000000000",
      "bankprodukte": [
        {
          "id": "DE89370400440532013000",
          "status": "VOLLSTAENDIG",
          "bezeichnung": "Tagesgeldkonto",
          "kategorie": "TAGESGELDKONTO",
          "saldo": 27365.56,
          "aktualisierungszeitpunkt": "2021-10-15 09:13:44",
          "saldoDatum": "2021-10-15 00:00:00",
          "waehrung": "EUR",
          "kontonummer": "9012345679",
          "iban": "DE89370400440532013000",
          "bic": "XXX12345678",
          "blz": "12345678",
          "kreditinstitut": "Demo Provider",
          "inhaber": "Fritz Testmüller"
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    body body CreateBankAccessBuilder true The body contains information about the bank access to create the builder for.

    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

    Response Headers

    Status Header Type Format Description
    201 Location string URL to get the created bank access using GET method

    Schemas

    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": "^.{1,50}$"
        },
        {
          "fieldkey": "pin",
          "label": "Demo-Passwort",
          "secret": true,
          "hint": "demo1, demo2 oder demo3",
          "format": "^.{1,50}$"
        }
      ]
    }
    
    

    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

    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

    Balance

    {
      "title": "Balance",
      "type": "object",
      "properties": {
        "saldo": {
          "type": "number",
          "description": "Balance/value of bank product",
          "example": "200000.13"
        },
        "waehrung": {
          "type": "string",
          "description": "Currency in which the bank product is valued/managed (Alphabetic Code ISO 4217)",
          "example": "EUR"
        },
        "saldoDatum": {
          "type": "string",
          "format": "YYYY-MM-DD hh:mm:ss",
          "description": "Balance/value date as reported by the bank/service provider",
          "example": "2023-02-23 13:37:00"
        }
      }
    }
    
    

    Balance

    Properties

    Name Type Required Restrictions Description
    saldo number false none Balance/value of bank product
    waehrung string false none Currency in which the bank product is valued/managed (Alphabetic Code ISO 4217)
    saldoDatum string(YYYY-MM-DD hh:mm:ss) false none Balance/value date as reported by the bank/service provider

    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/bankzugaenge/4c45b12f-ae68-4933-86df-ff2578a7a203/consent/0dd14633-1853-4d22-92f9-776429850a6b"
        }
      ]
    }
    
    

    Properties

    Name Type Required Restrictions Description
    id string(uuid) true none The id of the bank access in UUID format.
    providerId string(uuid) true none The id of the provider the bank access belongs to, in UUID format.
    aktualisierungszeitpunkt string(YYYY-MM-DD hh:mm:ss) true none Date and time of the last query at the bank / service provider
    messages [Message] false none List of messages that show which steps are required to continue further.
    tanMedien [TanMedium] false none Lis tof available TAN media.
    sicherheitsverfahren [SecurityProcedure] false none List of possible security procedures for this account.
    aktivesSicherheitsverfahren SecurityProcedure false none The security procedure determines how end users authenticate their transaction(s).
    challenge Challenge false none Contains information about TAN generation
    relations [Relation] true none List of relations that are available as next steps.
    type string false none Type of the bank access. This field will not be returned if the value is 'DEFAULT'.

    Type list:
  • DEFAULT
  • EBICS
  • BUILDER
  • status string true none Retrieval status of the bank account

    Status list:
  • INTERAKTION - Interaction: User intervention required, e.g. SCA required, see messages and relations
  • VOLLSTAENDIG - Finished: The data retrieval is completed
  • timeout string(YYYY-MM-DD hh:mm:ss) false none Lifetime of the data in seconds from the time of the update.
    bankprodukte [Product] true none The banking products available in the access.
    sync boolean true none Whether the bank account is automatically updated in the background or not.
    Enumerated Values
    Property Value
    type DEFAULT
    type EBICS
    type BUILDER
    status INTERAKTION
    status VOLLSTAENDIG

    BankAccessIssues

    {
      "id": "815251d6-c062-4f61-bec0-182bc14a48fb",
      "providerId": "00000000-0000-0000-0000-000000000000",
      "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"
      },
      "challenge": {
        "name": "Mock-TAN-Verfahren",
        "content": {
          "instructions": "Enter a TAN that is divisible by 2"
        },
        "decoupled": false,
        "redirect": false
      },
      "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
      "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 The issues endpoint holds the last known issues for a bank access (useful to retrieve the reason for delayed / failed background or manual sync) This method communicates all messages, also errors, that are not displayed in the stable bank access
    » aktivesSicherheitsverfahren SecurityProcedure false none The security procedure determines how end users authenticate their transaction(s).
    » aktualisierungszeitpunkt any false none Time of the last query at the bank / service provider
    » id string false none ID of the bank access
    » providerId string false none ID of the provider
    » challenge Challenge false none Contains information about TAN generation

    BankProductStatus

    "VOLLSTAENDIG"
    
    

    BankProductStatus

    Properties

    Name Type Required Restrictions Description
    BankProductStatus string false none Retrieval status of the bank product, which always equals the status of the corresponding bank access

    Status list :
  • INTERAKTION - Interaction: User intervention required, e.g. SCA required, see messages and relations
  • VOLLSTAENDIG - Finished: The data retrieval is completed
  • Enumerated Values
    Property Value
    BankProductStatus INTERAKTION
    BankProductStatus VOLLSTAENDIG

    BulkDebitData

    {
      "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iH ... D/MOfGsd8HY=",
        "pin": "XO2jgZ ... 5GfhKpZmw="
      },
      "product": "DE89370400440532013000",
      "business": false,
      "sequenceType": "OOFF",
      "creditorSchemeIdentification": "GlauebigerId",
      "requestedCollectionDate": "2022-02-22",
      "debitDetails": [
        {
          "amount": 1337.42,
          "currency": "EUR",
          "purpose": "Verwendungszweck",
          "endToEndId": "123",
          "debtorName": "Max Mustermann",
          "debtorIban": "DE62430609671149278400",
          "debtorAccountNumber": "1149278400",
          "debtorBankCode": "43060967",
          "debtorBic": "GENODEM1GLS",
          "mandateIdentification": "MandatsId",
          "mandateDateOfSignature": "2022-02-02"
        },
        {
          "amount": 42,
          "currency": "EUR",
          "purpose": "Verwendungszweck 2",
          "endToEndId": "124",
          "debtorName": "Maxi Mustermann",
          "debtorIban": "DE00123456789012345678",
          "debtorAccountNumber": "9012345678",
          "debtorBankCode": "12345678",
          "debtorBic": "SSKMDEMMXXX",
          "mandateIdentification": "MandatsId",
          "mandateDateOfSignature": "2022-02-02"
        }
      ]
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous PaymentInitializationDetails false none none

    and

    Name Type Required Restrictions Description
    anonymous DebitBaseInfo false none none

    and

    Name Type Required Restrictions Description
    anonymous object false none Request data to start a debit
    » debitDetails [DebitDetails] true none none

    BulkDebitDataBankAccess

    {
      "allOf": [
        {
          "required": [
            "creditorSchemeIdentification",
            "requestedCollectionDate"
          ],
          "type": "object",
          "properties": {
            "business": {
              "type": "boolean",
              "description": "Indicates whether the debit should be submitted for business or private customers.<br/><br/> It is recommended to assign this field together with `sequenceType` on the top layer (here) and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time."
            },
            "sequenceType": {
              "title": "DebitSequenceType",
              "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
              "enum": [
                "FRST",
                "RCUR",
                "FNAL",
                "OOFF"
              ],
              "type": "string"
            },
            "creditorSchemeIdentification": {
              "type": "string",
              "description": "The scheme identification of the creditor."
            },
            "requestedCollectionDate": {
              "type": "string",
              "format": "YYYY-MM-DD",
              "description": "The requested collection date of the debit."
            }
          }
        },
        {
          "description": "Request data to start a bulk debit",
          "required": [
            "debitDetails"
          ],
          "title": "BulkDebitDataBankAccess",
          "type": "object",
          "properties": {
            "debitDetails": {
              "type": "array",
              "items": {
                "allOf": [
                  {
                    "title": "DebitDetails",
                    "required": [
                      "amount",
                      "currency",
                      "purpose",
                      "endToEndId",
                      "debtorName",
                      "debtorIban",
                      "mandateIdentification",
                      "mandateDateOfSignature"
                    ],
                    "type": "object",
                    "properties": {
                      "amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Debit amount"
                      },
                      "currency": {
                        "type": "string",
                        "description": "Currency of the debit"
                      },
                      "purpose": {
                        "type": "string",
                        "description": "Purpose of the debit."
                      },
                      "endToEndId": {
                        "type": "string",
                        "description": "End to End Identification of the debit."
                      },
                      "debtorName": {
                        "type": "string",
                        "description": "Name of the debtor."
                      },
                      "debtorIban": {
                        "type": "string",
                        "description": "IBAN of the debtor."
                      },
                      "debtorAccountNumber": {
                        "type": "string",
                        "description": "Account number of the debtor."
                      },
                      "debtorBankCode": {
                        "type": "string",
                        "description": "Bank code of the debtor."
                      },
                      "debtorBic": {
                        "type": "string",
                        "description": "BIC of the debtor."
                      },
                      "mandateIdentification": {
                        "type": "string",
                        "description": "Identification of the mandate."
                      },
                      "mandateDateOfSignature": {
                        "type": "string",
                        "format": "YYYY-MM-DD",
                        "description": "The signature date of the mandate."
                      },
                      "business": {
                        "type": "boolean",
                        "description": "Indicates whether the debit should be submitted for business or private customers.<br/><br/> The mixing of true / false is not allowed in the same request.<br/><br/> It is recommended to assign this field together with `sequenceType` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time."
                      },
                      "sequenceType": {
                        "title": "DebitSequenceType",
                        "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
                        "enum": [
                          "FRST",
                          "RCUR",
                          "FNAL",
                          "OOFF"
                        ],
                        "type": "string"
                      }
                    },
                    "description": "DebitDetails are used in InitiateSingleDebit and InitiateBulkDebit"
                  }
                ]
              }
            }
          }
        }
      ]
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous DebitBaseInfo false none none

    and

    Name Type Required Restrictions Description
    anonymous object false none Request data to start a bulk debit
    » debitDetails [DebitDetails] true none none

    BulkDebitResult

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/bulk-debit/0b1937c7-82eb-49d4-99cb-6fdca765c450"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/payment/bulk-debit/0b1937c7-82eb-49d4-99cb-6fdca765c450/consent"
        }
      ],
      "debit": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "business": false,
        "sequenceType": "OOFF",
        "creditorSchemeIdentification": "GlauebigerId",
        "requestedCollectionDate": "2022-02-22",
        "debitDetails": [
          {
            "amount": 1337.42,
            "currency": "EUR",
            "purpose": "Verwendungszweck",
            "endToEndId": "123",
            "debtorName": "Max Mustermann",
            "debtorIban": "DE62430609671149278400",
            "debtorAccountNumber": "1149278400",
            "debtorBankCode": "43060967",
            "debtorBic": "GENODEM1GLS",
            "mandateIdentification": "MandatsId",
            "mandateDateOfSignature": "2022-02-02"
          },
          {
            "amount": 42,
            "currency": "EUR",
            "purpose": "Verwendungszweck 2",
            "endToEndId": "124",
            "debtorName": "Maxi Mustermann",
            "debtorIban": "DE00123456789012345678",
            "debtorAccountNumber": "9012345678",
            "debtorBankCode": "12345678",
            "debtorBic": "SSKMDEMMXXX",
            "mandateIdentification": "MandatsId",
            "mandateDateOfSignature": "2022-02-02"
          }
        ]
      }
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous Consent false none none

    and

    Name Type Required Restrictions Description
    anonymous object false none Current status of debit
    » debit any true none none

    allOf

    Name Type Required Restrictions Description
    »» anonymous DebitBaseInfo false none none

    and

    Name Type Required Restrictions Description
    »» anonymous object false none none
    »»» provider string(uuid) true none none
    »»» product string true none none
    »»» paymentId string(uuid) true none Unique id generated for each payment.
    »»» ebics boolean true none Whether this debit was submitted via EBICS or not.
    »»» debitDetails [DebitDetails] true none none

    BulkTransferData

    {
      "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iH... D/MOfGsd8HY=",
        "pin": "XO2jgZ... 5GfhKpZmw="
      },
      "product": "DE89370400440532013000",
      "instant": false,
      "requestedExecutionDate": "2024-09-19",
      "transferDetails": [
        {
          "recipient": "UNICEF",
          "purpose": "Spende UNICEF",
          "iban": "DE57370205000000300000",
          "bic": "BFSWDE33XXX",
          "currency": "EUR",
          "amount": 150,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        },
        {
          "recipient": "netzpolitik.org e. V.",
          "purpose": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "currency": "EUR",
          "amount": 75,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        }
      ]
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous PaymentInitializationDetails false none none

    and

    Name Type Required Restrictions Description
    anonymous BasicBulkTransferData false none none

    TransferDataBase

    {
      "type": "object",
      "required": [
        "transferDetails"
      ],
      "properties": {
        "instant": {
          "type": "boolean",
          "description": "If set to true, the transfer will be executed as an instant payment.\nPlease note that instant payments may not be supported\nor may incur additional costs depending on the bank.\n"
        },
        "requestedExecutionDate": {
          "type": "string",
          "format": "YYYY-MM-DD",
          "description": "The requested execution date of the transfer.\nPlease note that transfers with execution date may not be supported depending on the bank.\n"
        }
      }
    }
    
    

    Properties

    Name Type Required Restrictions Description
    instant boolean false none If set to true, the transfer will be executed as an instant payment. Please note that instant payments may not be supported or may incur additional costs depending on the bank.
    requestedExecutionDate string(YYYY-MM-DD) false none The requested execution date of the transfer. Please note that transfers with execution date may not be supported depending on the bank.

    BasicBulkTransferData

    {
      "instant": false,
      "requestedExecutionDate": "2024-09-19",
      "transferDetails": [
        {
          "recipient": "UNICEF",
          "purpose": "Spende UNICEF",
          "iban": "DE57370205000000300000",
          "bic": "BFSWDE33XXX",
          "currency": "EUR",
          "amount": 150,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        },
        {
          "recipient": "netzpolitik.org e. V.",
          "purpose": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "currency": "EUR",
          "amount": 75,
          "endToEndId": "be7649876d5f439886fa816993ac9f9f"
        }
      ]
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous TransferDataBase false none none

    and

    Name Type Required Restrictions Description
    anonymous object false none Request payload to start a bulk transfer
    » transferDetails [TransferDetails] false none [TransferDetails are used in InitiateSingleTransfer and InitiateBulkTransfer]

    BasicSingleTransferData

    {
      "instant": false,
      "requestedExecutionDate": "2024-09-19",
      "transferDetails": {
        "recipient": "netzpolitik.org e. V.",
        "purpose": "Spende netzpolitik.de",
        "iban": "DE62430609671149278400",
        "bic": "GENODEM1GLS",
        "currency": "EUR",
        "amount": 1337.42,
        "endToEndId": "be7649876d5f439886fa816993ac9f9f"
      }
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous TransferDataBase false none none

    and

    Name Type Required Restrictions Description
    anonymous object false none Request payload to start a single transfer
    » transferDetails TransferDetails false none TransferDetails are used in InitiateSingleTransfer and InitiateBulkTransfer

    BulkTransferResult

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA Methode auswählen",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "scaMethods": [
        {
          "code": 2,
          "name": "mTAN",
          "hint": "mTAN"
        },
        {
          "code": 1,
          "name": "Mock-TAN",
          "hint": "Mock-TAN"
        }
      ],
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2/payment/bulk-transfer/fdc61bcd-d0ee-4999-9c77-eff3ba8db0ce"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/payment/bulk-transfer/fdc61bcd-d0ee-4999-9c77-eff3ba8db0ce/consent"
        }
      ],
      "transfer": {
        "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
        "product": "DE89370400440532013000",
        "paymentId": "df5afff2-43e7-4fca-95fa-0d06251c9ce9",
        "ebics": false,
        "instant": false,
        "requestedExecutionDate": "2024-09-19",
        "transferDetails": [
          {
            "recipient": "UNICEF",
            "purpose": "Spende UNICEF",
            "iban": "DE57370205000000300000",
            "bic": "BFSWDE33XXX",
            "currency": "EUR",
            "amount": 150,
            "endToEndId": "be7649876d5f439886fa816993ac9f9f"
          },
          {
            "recipient": "netzpolitik.org e. V.",
            "purpose": "Spende netzpolitik.de",
            "iban": "DE62430609671149278400",
            "bic": "GENODEM1GLS",
            "currency": "EUR",
            "amount": 75,
            "endToEndId": "be7649876d5f439886fa816993ac9f9f"
          }
        ]
      }
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous Consent false none none

    and

    Name Type Required Restrictions Description
    anonymous object false none Current status of transfer
    » transfer object true none none
    »» provider string(uuid) true none none
    »» product string true none none
    »» paymentId string(uuid) true none Unique id generated for each payment.
    »» ebics boolean true none Whether this transfer was submitted via EBICS or not.
    »» instant boolean false none Whether this transfer was initiated as an instant payment or not.
    »» requestedExecutionDate string(YYYY-MM-DD) false none The requested execution date of the transfer. Please note that transfers with execution date may not be supported depending on the bank.
    »» transferDetails [TransferDetails] true none [TransferDetails are used in InitiateSingleTransfer and InitiateBulkTransfer]

    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"
        },
        "decoupled": false,
        "redirect": false
      }
    }
    
    

    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 SCA approach is decoupled, thus not expecting scaAuthenticationData within Submit SCA Data, but just an empty object to confirm the user indicated that he meanwhile confirmed the activity, e.g. through the bank app, independently.
    redirect boolean false none Indicates whether the SCA approach is redirect.

    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 false none Base64-encoded png of the mosaic photo to be displayed to the user when using PhotoTAN
    PDF string false none Base64-encoded PDF needed for the challenge

    Categorization

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

    Categorization

    Properties

    Name Type Required Restrictions Description
    category string true none Unique category name of sales category
    systemName string false none Unique system name of sales category
    displayName string true none User friendly name of sales category
    parentCategory string false none If it is a subcategory, this field includes the name of the main category
    parent string false none If it is a subcategory, this field includes the system name of the main category
    tagScope string false none The scope of the tag
    tagType string false none The type of the tag
    tagId string false none Unique id of the tag
    tagVersion string false none The version of the tag

    ChangeUserDetails

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

    ChangeUserDetails

    Properties

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

    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,
        "selectedBankProducts": [
          "DE00123456789012345679"
        ]
      }
    }
    
    

    CreateBankAccess

    Properties

    Name Type Required Restrictions Description
    additionalProperties CreateBankAccessData false none none

    CreateBankAccessBuilder

    {
      "id": "815251d6-c062-4f61-bec0-182bc14a48fb",
      "providerId": "00000000-0000-0000-0000-000000000000",
      "bankprodukte": [
        {
          "id": "DE89370400440532013000",
          "status": "VOLLSTAENDIG",
          "bezeichnung": "Tagesgeldkonto",
          "kategorie": "TAGESGELDKONTO",
          "saldo": 27365.56,
          "aktualisierungszeitpunkt": "2021-10-15 09:13:44",
          "saldoDatum": "2021-10-15 00:00:00",
          "waehrung": "EUR",
          "kontonummer": "9012345679",
          "iban": "DE89370400440532013000",
          "bic": "XXX12345678",
          "blz": "12345678",
          "kreditinstitut": "Demo Provider",
          "inhaber": "Fritz Testmüller"
        }
      ]
    }
    
    

    CreateBankAccessBuilder

    Properties

    Name Type Required Restrictions Description
    id string(uuid) true none The ID of the access to create
    providerId string(uuid) true none The ID of the access provider (bank or service provider) according to the provider list
    bankprodukte [SimpleProduct] true none The banking products available in the access.

    CreateBankAccessData

    {
      "815251d6-c062-4f61-bec0-182bc14a48fb": {
        "providerId": "00000000-0000-0000-0000-000000000000",
        "credentials": {
          "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
          "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
        },
        "sync": true,
        "selectedBankProducts": [
          "DE00123456789012345679"
        ]
      }
    }
    
    

    Create Bank Access Data

    Properties

    Name Type Required Restrictions Description
    providerId string(uuid) false none The ID of the access provider (bank or service provider) according to the provider list
    credentials Credentials false 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. The Credentials object is not required for REG/Protect tenants only.
    sync boolean false none Whether an automatic regular background update is to be performed or not
    selectedBankProducts [string] false none The set of selected bank products that should be fetched.
    ebics boolean false none Whether this credentials are for EBICS or not.
    hostId string false none Host-ID for EBICS as provided by the bank
    hostUrl string false none Host-URL for EBICS as provided by the bank

    CreateBulkTransferLegacy

    {
      "payments": [
        {
          "empfaenger": "UNICEF",
          "verwendungszweck": "Spende UNICEF",
          "iban": "DE57370205000000300000",
          "bic": "BFSWDE33XXX",
          "waehrung": "EUR",
          "betrag": 150
        },
        {
          "empfaenger": "netzpolitik.org e. V.",
          "verwendungszweck": "Spende netzpolitik.de",
          "iban": "DE62430609671149278400",
          "bic": "GENODEM1GLS",
          "waehrung": "EUR",
          "betrag": 75
        }
      ],
      "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/customer/v2/ueberweisung/3e97fa51-ce7b-42a0-9101-50fd67dbc3e7/consent"
        }
      ]
    }
    
    

    Properties

    Name Type Required Restrictions Description
    credentials Credentials false 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. The Credentials object is not required for REG/Protect tenants only.
    sicherheitsverfahrenKodierung integer(int32) false none Coding of the security procedure to use , see Bank product
    ausfuehrungsdatum DateTime false none This object represents a timestamp. Format: YYYY-MM-DD hh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.
    tanMediumName string false none The TAN medium to be used
    payments [UeberweisungDetails] true none none

    CreateTextTan

    {
      "tan": "4103582"
    }
    
    

    CreateTextTan

    Properties

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

    CreateToken

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

    CreateToken

    Properties

    Name Type Required Restrictions Description
    grant_type string true none Must be one of the following:
    • password: Get a user token, which is needed when creating or querying banking accounts.
    • client_credentials: Get a client token, which is needed for administrative use cases such as creating users.
    username string false none Username of user. REQUIRED if 'grant_type' is 'password'!
    password string false none Password of user. REQUIRED if 'grant_type' is 'password'!
    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.
    Enumerated Values
    Property Value
    grant_type password
    grant_type client_credentials

    CreateTransfer

    {
      "allOf": [
        {
          "allOf": [
            {
              "title": "UeberweisungDetails",
              "required": [
                "empfaenger",
                "verwendungszweck",
                "iban",
                "betrag",
                "waehrung"
              ],
              "type": "object",
              "properties": {
                "empfaenger": {
                  "type": "string",
                  "description": "Receiver of the transfer"
                },
                "verwendungszweck": {
                  "type": "string",
                  "description": "Purpose of the transfer."
                },
                "iban": {
                  "type": "string",
                  "description": "IBAN of the recipient account"
                },
                "bic": {
                  "type": "string",
                  "description": "BIC of the recipient account"
                },
                "waehrung": {
                  "type": "string",
                  "description": "Currency of the transfer (Alphabetic Code ISO 4217)"
                },
                "betrag": {
                  "type": "number",
                  "description": "Transfer amount"
                }
              },
              "description": "UeberweisungDetails are used in CreateTransfer and CreateBulkTransfer"
            }
          ]
        },
        {
          "title": "CreateTransfer",
          "required": [
            "empfaenger",
            "verwendungszweck",
            "iban",
            "betrag",
            "bic",
            "waehrung"
          ],
          "type": "object",
          "properties": {
            "credentials": {
              "title": "Credentials",
              "description": "The Credentials object is a map of encrypted and Base64-encoded access data, corresponding\nto the provider's authentication fields. The Base64 encoding must not use line wrapping.\n\nThe encryption method used is described in the chapter Encryption.\n\nThe Credentials object is not required for REG/Protect tenants only.",
              "required": [
                "userid",
                "pin"
              ],
              "type": "object",
              "properties": {
                "userid": {
                  "type": "string",
                  "example": "cust0815",
                  "description": "Encrypted and Base64-encoded username of the user at the bank, e.g. used in his online banking.<br/>EBICS: The User-ID (Teilnehmer-ID) as provided by the bank must be transmitted."
                },
                "pin": {
                  "type": "string",
                  "example": "verySecret",
                  "description": "Encrypted and Base64-encoded pin / password of the user at the bank, e.g. used in his online banking.<br/>EBICS: A pin must not be transmitted."
                },
                "partnerid": {
                  "type": "string",
                  "example": "PID0001",
                  "description": "Encrypted and Base64-encoded partner id (Kunden-ID) only required for EBICS."
                },
                "corporateid": {
                  "type": "string",
                  "example": 123456,
                  "description": "Encrypted and Base64-encoded corporate id required by some banks for business accounts."
                }
              },
              "example": {
                "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
                "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
              }
            },
            "sicherheitsverfahrenKodierung": {
              "type": "integer",
              "description": "Coding of the security procedure to use , see Bank product",
              "format": "int32"
            },
            "ausfuehrungsdatum": {
              "title": "DateTime",
              "description": "This object represents a timestamp. Format: `YYYY-MM-DD hh:mm:ss`. Data will be interpreted according to the time zone Europe/Berlin.",
              "type": "string",
              "example": "2019-12-04 13:37:00"
            },
            "tanMediumName": {
              "type": "string",
              "description": "The TAN medium to be used"
            }
          },
          "description": "Request data to start a transfer",
          "example": {
            "credentials": {
              "userid": "mXlkGe+ukA ... MOfGsd8HY=",
              "pin": "XO2jg ... 5GfhKpZmw="
            },
            "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"
          }
        }
      ]
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous UeberweisungDetails false none none

    and

    Name Type Required Restrictions Description
    anonymous object false none Request data to start a transfer
    » credentials Credentials false 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. The Credentials object is not required for REG/Protect tenants only.
    » sicherheitsverfahrenKodierung integer(int32) false none Coding of the security procedure to use , see Bank product
    » ausfuehrungsdatum DateTime false none This object represents a timestamp. Format: YYYY-MM-DD hh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.
    » tanMediumName string false none The TAN medium to be used

    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 of the user. The password policy is as follows:
  • at least 10 characters
  • at least 2 letters
  • at least 2 special characters (numbers or any other characters like ,.-;:_&%$ etc.)
  • firstname string false none The first name
    lastname string false none Last name

    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.
    EBICS: The User-ID (Teilnehmer-ID) as provided by the bank must be transmitted.
    pin string true none Encrypted and Base64-encoded pin / password of the user at the bank, e.g. used in his online banking.
    EBICS: A pin must not be transmitted.
    partnerid string false none Encrypted and Base64-encoded partner id (Kunden-ID) only required for EBICS.
    corporateid string false none Encrypted and Base64-encoded corporate id required by some banks for business accounts.

    Customer

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

    Properties

    Name Type Required Restrictions Description
    messages [Message] false none [Messages transport both errors and analysis events.]
    bankzugaenge object false none none
    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.]

    DateTime

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

    DateTime

    Properties

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

    DebitBaseInfo

    {
      "required": [
        "creditorSchemeIdentification",
        "requestedCollectionDate"
      ],
      "type": "object",
      "properties": {
        "business": {
          "type": "boolean",
          "description": "Indicates whether the debit should be submitted for business or private customers.<br/><br/> It is recommended to assign this field together with `sequenceType` on the top layer (here) and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time."
        },
        "sequenceType": {
          "title": "DebitSequenceType",
          "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
          "enum": [
            "FRST",
            "RCUR",
            "FNAL",
            "OOFF"
          ],
          "type": "string"
        },
        "creditorSchemeIdentification": {
          "type": "string",
          "description": "The scheme identification of the creditor."
        },
        "requestedCollectionDate": {
          "type": "string",
          "format": "YYYY-MM-DD",
          "description": "The requested collection date of the debit."
        }
      }
    }
    
    

    Properties

    Name Type Required Restrictions Description
    business boolean false none Indicates whether the debit should be submitted for business or private customers.

    It is recommended to assign this field together with sequenceType on the top layer (here) and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.
    sequenceType DebitSequenceType false none Sequence type of the debit.

    It is recommended to assign this field together with business on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.

    Sequence types:
  • FRST - first debit
  • RCUR - recurrent debit
  • FNAL - final debit
  • OOFF - one-off debit
  • creditorSchemeIdentification string true none The scheme identification of the creditor.
    requestedCollectionDate string(YYYY-MM-DD) true none The requested collection date of the debit.

    DebitDetails

    {
      "allOf": [
        {
          "title": "DebitDetails",
          "required": [
            "amount",
            "currency",
            "purpose",
            "endToEndId",
            "debtorName",
            "debtorIban",
            "mandateIdentification",
            "mandateDateOfSignature"
          ],
          "type": "object",
          "properties": {
            "amount": {
              "type": "number",
              "format": "double",
              "description": "Debit amount"
            },
            "currency": {
              "type": "string",
              "description": "Currency of the debit"
            },
            "purpose": {
              "type": "string",
              "description": "Purpose of the debit."
            },
            "endToEndId": {
              "type": "string",
              "description": "End to End Identification of the debit."
            },
            "debtorName": {
              "type": "string",
              "description": "Name of the debtor."
            },
            "debtorIban": {
              "type": "string",
              "description": "IBAN of the debtor."
            },
            "debtorAccountNumber": {
              "type": "string",
              "description": "Account number of the debtor."
            },
            "debtorBankCode": {
              "type": "string",
              "description": "Bank code of the debtor."
            },
            "debtorBic": {
              "type": "string",
              "description": "BIC of the debtor."
            },
            "mandateIdentification": {
              "type": "string",
              "description": "Identification of the mandate."
            },
            "mandateDateOfSignature": {
              "type": "string",
              "format": "YYYY-MM-DD",
              "description": "The signature date of the mandate."
            },
            "business": {
              "type": "boolean",
              "description": "Indicates whether the debit should be submitted for business or private customers.<br/><br/> The mixing of true / false is not allowed in the same request.<br/><br/> It is recommended to assign this field together with `sequenceType` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time."
            },
            "sequenceType": {
              "title": "DebitSequenceType",
              "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
              "enum": [
                "FRST",
                "RCUR",
                "FNAL",
                "OOFF"
              ],
              "type": "string"
            }
          },
          "description": "DebitDetails are used in InitiateSingleDebit and InitiateBulkDebit"
        }
      ]
    }
    
    

    Properties

    Name Type Required Restrictions Description
    amount number(double) true none Debit amount
    currency string true none Currency of the debit
    purpose string true none Purpose of the debit.
    endToEndId string true none End to End Identification of the debit.
    debtorName string true none Name of the debtor.
    debtorIban string true none IBAN of the debtor.
    debtorAccountNumber string false none Account number of the debtor.
    debtorBankCode string false none Bank code of the debtor.
    debtorBic string false none BIC of the debtor.
    mandateIdentification string true none Identification of the mandate.
    mandateDateOfSignature string(YYYY-MM-DD) true none The signature date of the mandate.
    business boolean false none Indicates whether the debit should be submitted for business or private customers.

    The mixing of true / false is not allowed in the same request.

    It is recommended to assign this field together with sequenceType on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.
    sequenceType DebitSequenceType false none Sequence type of the debit.

    It is recommended to assign this field together with business on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.

    Sequence types:
  • FRST - first debit
  • RCUR - recurrent debit
  • FNAL - final debit
  • OOFF - one-off debit
  • DebitSequenceType

    {
      "title": "DebitSequenceType",
      "description": "Sequence type of the debit.<br/><br/> It is recommended to assign this field together with `business` on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.<br/><br/> Sequence types: <li>`FRST` - first debit</li> <li>`RCUR` - recurrent debit</li> <li>`FNAL` - final debit</li> <li>`OOFF` - one-off debit</li>",
      "enum": [
        "FRST",
        "RCUR",
        "FNAL",
        "OOFF"
      ],
      "type": "string"
    }
    
    

    DebitSequenceType

    Properties

    Name Type Required Restrictions Description
    DebitSequenceType string false none Sequence type of the debit.

    It is recommended to assign this field together with business on the top layer and not in debitDetails. Moreover, it is not allowed to assign these fields on both levels at the same time.

    Sequence types:
  • FRST - first debit
  • RCUR - recurrent debit
  • FNAL - final debit
  • OOFF - one-off debit
  • Enumerated Values
    Property Value
    DebitSequenceType FRST
    DebitSequenceType RCUR
    DebitSequenceType FNAL
    DebitSequenceType OOFF

    EntitySchema

    {
      "properties": {
        "displayName": {
          "description": "Display name of the entity",
          "example": "TRANSACTION",
          "type": "string"
        },
        "entityClass": {
          "description": "Class of the entity, such as TRANSACTION or USER",
          "example": "TRANSACTION",
          "type": "string"
        },
        "id": {
          "description": "Transaction UUID or USER UUID.",
          "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
          "type": "string"
        },
        "userId": {
          "description": "UUID of the USER. Same as id field for USER entities.",
          "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
          "type": "string"
        }
      },
      "required": [
        "displayName",
        "entityClass",
        "id"
      ],
      "type": "object"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    displayName string true none Display name of the entity
    entityClass string true none Class of the entity, such as TRANSACTION or USER
    id string true none Transaction UUID or USER UUID.
    userId string false none UUID of the USER. Same as id field for USER entities.

    Field

    {
      "fieldkey": "pin",
      "label": "Demo-Passwort",
      "secret": true,
      "hint": "demo1, demo2 oder demo3",
      "format": "^.{1,50}$"
    }
    
    

    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 regular expression (regex) pattern specifying the format for the input field

    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"
        },
        "decoupled": false,
        "redirect": false
      }
    }
    
    

    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

    Investment

    {
      "name": "GENERAL ELECTRIC CO",
      "menge": 167,
      "handelseinheit": "STUECK",
      "isin": "US3696041033",
      "wkn": "851144",
      "kurs": 24.32,
      "kursDatum": "2021-10-15 15:31:20",
      "waehrung": "USD",
      "waehrungskurs": 1.18,
      "handelsplatz": "Xetra",
      "gesamtwert": 3441.9
    }
    
    

    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 Amount 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 string(YYYY-MM-DD hh:mm:ss) false none The quote date
    waehrung string false none Trading currency (Alphabetic Code ISO 4217)
    waehrungskurs number false none Conversion rate from EUR to the trading currency
    handelsplatz string false none Trading place of the price determination
    gesamtwert number false none Total value of the stock in the currency given in 'waehrung' as at the end of the financial statements
    Enumerated Values
    Property Value
    handelseinheit STUECK
    handelseinheit NOMINAL

    IsoDateTime

    "2019-12-04T13:37:00"
    
    

    IsoDateTime

    Properties

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

    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

    ListOfBankAccesses

    {
      "0b7f4783-4c93-4820-8e73-354a0f1c469e": {
        "id": "0b7f4783-4c93-4820-8e73-354a0f1c469e",
        "providerId": "00000000-0000-0000-0000-000000000000",
        "aktualisierungszeitpunkt": "2021-10-15 09:13:44",
        "tanMedien": [
          {
            "name": "Mobil",
            "medienklasse": "MOBIL",
            "gueltigVon": "2021-10-15 09:13:44",
            "gueltigBis": "2021-10-15 09:13:44"
          }
        ],
        "sicherheitsverfahren": [
          {
            "kodierung": 1,
            "name": "mockTAN",
            "hinweis": "Gib eine durch 2 teilbare Zahl ein"
          },
          {
            "kodierung": 999,
            "name": "iTAN",
            "hinweis": "Gib die TAN \"12\" an."
          }
        ],
        "aktivesSicherheitsverfahren": {
          "kodierung": 999,
          "name": "iTAN",
          "hinweis": "Gib die TAN \"12\" an."
        },
        "relations": [
          {
            "rel": "self",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/0b7f4783-4c93-4820-8e73-354a0f1c469e"
          },
          {
            "rel": "delete_bankzugang",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/0b7f4783-4c93-4820-8e73-354a0f1c469e"
          }
        ],
        "status": "VOLLSTAENDIG",
        "bankprodukte": [
          {
            "id": "DE00123456789012345679",
            "status": "VOLLSTAENDIG",
            "bezeichnung": "Tagesgeldkonto",
            "kategorie": "TAGESGELDKONTO",
            "saldo": 27365.56,
            "aktualisierungszeitpunkt": "2021-10-15 09:13:44",
            "saldoDatum": "2021-10-15 00:00:00",
            "waehrung": "EUR",
            "kontonummer": "9012345679",
            "iban": "DE00123456789012345679",
            "bic": "XXX12345678",
            "blz": "12345678",
            "kreditinstitut": "Demo Provider",
            "inhaber": "Fritz Testmüller",
            "transferSupport": true,
            "relations": [
              {
                "rel": "get_kontoumsaetze",
                "href": "https://banksapi.io/customer/v2/bankzugaenge/0b7f4783-4c93-4820-8e73-354a0f1c469e/DE00123456789012345679/kontoumsaetze"
              },
              {
                "rel": "initiate_single_transfer",
                "href": "https://banksapi.io/customer/v2/payment/single-transfer"
              },
              {
                "rel": "initiate_bulk_transfer",
                "href": "https://banksapi.io/customer/v2/payment/bulk-transfer"
              }
            ],
            "messages": [],
            "verfuegungsrahmen": 27365.56,
            "verfuegterBetrag": 0
          }
        ],
        "sync": true
      },
      "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
    additionalProperties BankAccess false none none

    MaxTransactions

    {
      "title": "MaxTransactions",
      "description": "Indicator if transactions older than 90 days should be fetched<br/><br/> MaxTransactions: <li>`none` - default value</li> <li>`all` - all accounts</li> <li>`paymentAccounts` - only payment accounts</li>",
      "enum": [
        "none",
        "all",
        "paymentAccounts"
      ],
      "type": "string"
    }
    
    

    MaxTransactions

    Properties

    Name Type Required Restrictions Description
    MaxTransactions string false none Indicator if transactions older than 90 days should be fetched

    MaxTransactions:
  • none - default value
  • all - all accounts
  • paymentAccounts - only payment accounts
  • Enumerated Values
    Property Value
    MaxTransactions none
    MaxTransactions all
    MaxTransactions paymentAccounts

    MediaClass

    "MOBILE"
    
    

    MediaClass

    Properties

    Name Type Required Restrictions Description
    MediaClass string false none Media Classes:
  • LISTE - Paper-TAN list
  • GENERATOR - TAN generator
  • MOBILE - mobile phone
  • SECODER - TAN matrix generator
  • PUSHTAN - Push message
  • ALL - All classes
  • PROPRIETARY - Proprietary media
  • Enumerated Values
    Property Value
    MediaClass LISTE
    MediaClass GENERATOR
    MediaClass MOBILE
    MediaClass SECODER
    MediaClass PUSHTAN
    MediaClass ALL
    MediaClass PROPRIETARY

    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 string true none Level of the message, INFO or ERROR
    code MessageCode true none Code of the message

    Message Codes:
  • BA999 - Internal error (ERROR)
  • BA1000 - Maintenance work provider (ERROR)
  • BA1001 - Provider no longer active (ERROR)
  • BA1010 - Access blocked (ERROR)
  • BA1011 - Access data incorrect (ERROR)
  • BA1012 - Access data incomplete (ERROR)
  • BA1013 - Account not activated (ERROR)
  • BA1014 - Too many unsuccessful logins (ERROR)
  • BA1020 - Account has improper permissions (ERROR)
  • BA1051 - Bank access unavailable (ERROR)
  • BA1052 - Bank access not fully available (ERROR)
  • BA1053 - Access exceeded (ERROR)
  • BA1060 - Product could not be updated (ERROR)
  • BA1062 - Transactions could not be updated (ERROR)
  • BA1063 - Depot positions could not be updated (ERROR)
  • BA1064 - Message from bank (ERROR)
  • BA1100 - Transfer data invalid (ERROR)
  • BA1101 - Invalid TAN procedure (ERROR)
  • BA1102 - Invalid TAN medium (ERROR)
  • BA1103 - TAN invalid (ERROR)
  • BA1104 - Bank transfer not possible (ERROR)
  • BA1110 - TAN input required (INFO)
  • BA1111 - The transfer has been completed successfully (INFO)
  • BA1112 - The transfer has been submitted successfully (INFO)
  • BA1200 - Debit data invalid (ERROR)
  • BA1204 - Debit not supported (ERROR)
  • BA1212 - The debit has been submitted successfully (INFO)
  • BA2002 - There are notifications from your bank (INFO)
  • BA2003 - Product type not supported (INFO)
  • BA2004 - Bank access not activated yet (INFO)
  • BA2021 - Missing permission (INFO)
  • BA2062 - Transactions not available (INFO)
  • BA3000 - SCA required (INFO)
  • BA3005 - SCA redirect required (INFO)
  • BA3010 - Select SCA method (INFO)
  • BA3020 - Select SCA medium (INFO)
  • BA3030 - SCA Challenge (INFO)
  • BA3040 - SCA failed (ERROR)
  • BA3060 - No supported SCA method found (ERROR)
  • 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.
    Enumerated Values
    Property Value
    level INFO
    level ERROR

    MessageCode

    "BA999"
    
    

    MessageCode

    Properties

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

    Message Codes:
  • BA999 - Internal error (ERROR)
  • BA1000 - Maintenance work provider (ERROR)
  • BA1001 - Provider no longer active (ERROR)
  • BA1010 - Access blocked (ERROR)
  • BA1011 - Access data incorrect (ERROR)
  • BA1012 - Access data incomplete (ERROR)
  • BA1013 - Account not activated (ERROR)
  • BA1014 - Too many unsuccessful logins (ERROR)
  • BA1020 - Account has improper permissions (ERROR)
  • BA1051 - Bank access unavailable (ERROR)
  • BA1052 - Bank access not fully available (ERROR)
  • BA1053 - Access exceeded (ERROR)
  • BA1060 - Product could not be updated (ERROR)
  • BA1062 - Transactions could not be updated (ERROR)
  • BA1063 - Depot positions could not be updated (ERROR)
  • BA1064 - Message from bank (ERROR)
  • BA1100 - Transfer data invalid (ERROR)
  • BA1101 - Invalid TAN procedure (ERROR)
  • BA1102 - Invalid TAN medium (ERROR)
  • BA1103 - TAN invalid (ERROR)
  • BA1104 - Bank transfer not possible (ERROR)
  • BA1110 - TAN input required (INFO)
  • BA1111 - The transfer has been completed successfully (INFO)
  • BA1112 - The transfer has been submitted successfully (INFO)
  • BA1200 - Debit data invalid (ERROR)
  • BA1204 - Debit not supported (ERROR)
  • BA1212 - The debit has been submitted successfully (INFO)
  • BA2002 - There are notifications from your bank (INFO)
  • BA2003 - Product type not supported (INFO)
  • BA2004 - Bank access not activated yet (INFO)
  • BA2021 - Missing permission (INFO)
  • BA2062 - Transactions not available (INFO)
  • BA3000 - SCA required (INFO)
  • BA3005 - SCA redirect required (INFO)
  • BA3010 - Select SCA method (INFO)
  • BA3020 - Select SCA medium (INFO)
  • BA3030 - SCA Challenge (INFO)
  • BA3040 - SCA failed (ERROR)
  • BA3060 - No supported SCA method found (ERROR)
  • Enumerated Values
    Property Value
    MessageCode BA999
    MessageCode BA1000
    MessageCode BA1001
    MessageCode BA1010
    MessageCode BA1011
    MessageCode BA1012
    MessageCode BA1013
    MessageCode BA1014
    MessageCode BA1020
    MessageCode BA1051
    MessageCode BA1052
    MessageCode BA1053
    MessageCode BA1060
    MessageCode BA1062
    MessageCode BA1063
    MessageCode BA1064
    MessageCode BA1100
    MessageCode BA1101
    MessageCode BA1102
    MessageCode BA1103
    MessageCode BA1104
    MessageCode BA1110
    MessageCode BA1111
    MessageCode BA1112
    MessageCode BA1200
    MessageCode BA1204
    MessageCode BA1212
    MessageCode BA2002
    MessageCode BA2003
    MessageCode BA2004
    MessageCode BA2021
    MessageCode BA2062
    MessageCode BA3000
    MessageCode BA3005
    MessageCode BA3010
    MessageCode BA3020
    MessageCode BA3030
    MessageCode BA3040
    MessageCode BA3060

    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

    PaymentInitializationDetails

    {
      "required": [
        "provider",
        "product"
      ],
      "type": "object",
      "properties": {
        "provider": {
          "type": "string",
          "description": "Provider to initiate the payment from",
          "format": "uuid"
        },
        "credentials": {
          "title": "Credentials",
          "description": "The Credentials object is a map of encrypted and Base64-encoded access data, corresponding\nto the provider's authentication fields. The Base64 encoding must not use line wrapping.\n\nThe encryption method used is described in the chapter Encryption.\n\nThe Credentials object is not required for REG/Protect tenants only.",
          "required": [
            "userid",
            "pin"
          ],
          "type": "object",
          "properties": {
            "userid": {
              "type": "string",
              "example": "cust0815",
              "description": "Encrypted and Base64-encoded username of the user at the bank, e.g. used in his online banking.<br/>EBICS: The User-ID (Teilnehmer-ID) as provided by the bank must be transmitted."
            },
            "pin": {
              "type": "string",
              "example": "verySecret",
              "description": "Encrypted and Base64-encoded pin / password of the user at the bank, e.g. used in his online banking.<br/>EBICS: A pin must not be transmitted."
            },
            "partnerid": {
              "type": "string",
              "example": "PID0001",
              "description": "Encrypted and Base64-encoded partner id (Kunden-ID) only required for EBICS."
            },
            "corporateid": {
              "type": "string",
              "example": 123456,
              "description": "Encrypted and Base64-encoded corporate id required by some banks for business accounts."
            }
          },
          "example": {
            "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
            "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
          }
        },
        "product": {
          "type": "string",
          "description": "Product to initiate the payment from"
        }
      }
    }
    
    

    Properties

    Name Type Required Restrictions Description
    provider string(uuid) true none Provider to initiate the payment from
    credentials Credentials false 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. The Credentials object is not required for REG/Protect tenants only.
    product string true none Product to initiate the payment from

    Consent

    {
      "type": "object",
      "properties": {
        "messages": {
          "type": "array",
          "items": {
            "title": "Message",
            "required": [
              "level",
              "code",
              "message"
            ],
            "type": "object",
            "properties": {
              "level": {
                "type": "string",
                "description": "Level of the message, INFO or ERROR",
                "enum": [
                  "INFO",
                  "ERROR"
                ]
              },
              "code": {
                "title": "MessageCode",
                "type": "string",
                "description": "Code of the message<br/><br/>Message Codes: <li>`BA999` - Internal error (ERROR)</li> <li>`BA1000` - Maintenance work provider (ERROR)</li> <li>`BA1001` - Provider no longer active (ERROR)</li> <li>`BA1010` - Access blocked (ERROR)</li> <li>`BA1011` - Access data incorrect (ERROR)</li> <li>`BA1012` - Access data incomplete (ERROR)</li> <li>`BA1013` - Account not activated (ERROR)</li> <li>`BA1014` - Too many unsuccessful logins (ERROR)</li> <li>`BA1020` - Account has improper permissions (ERROR)</li> <li>`BA1051` - Bank access unavailable (ERROR)</li> <li>`BA1052` - Bank access not fully available (ERROR)</li> <li>`BA1053` - Access exceeded (ERROR)</li> <li>`BA1060` - Product could not be updated (ERROR)</li> <li>`BA1062` - Transactions could not be updated (ERROR)</li> <li>`BA1063` - Depot positions could not be updated (ERROR)</li> <li>`BA1064` - Message from bank (ERROR)</li> <li>`BA1100` - Transfer data invalid (ERROR)</li> <li>`BA1101` - Invalid TAN procedure (ERROR)</li> <li>`BA1102` - Invalid TAN medium (ERROR)</li> <li>`BA1103` - TAN invalid (ERROR)</li> <li>`BA1104` - Bank transfer not possible (ERROR)</li> <li>`BA1110` - TAN input required (INFO)</li> <li>`BA1111` - The transfer has been completed successfully (INFO)</li> <li>`BA1112` - The transfer has been submitted successfully (INFO)</li> <li>`BA1200` - Debit data invalid (ERROR)</li> <li>`BA1204` - Debit not supported (ERROR)</li> <li>`BA1212` - The debit has been submitted successfully (INFO)</li> <li>`BA2002` - There are notifications from your bank (INFO)</li> <li>`BA2003` - Product type not supported (INFO)</li> <li>`BA2004` - Bank access not activated yet (INFO)</li> <li>`BA2021` - Missing permission (INFO)</li> <li>`BA2062` - Transactions not available (INFO)</li> <li>`BA3000` - SCA required (INFO)</li> <li>`BA3005` - SCA redirect required (INFO)</li> <li>`BA3010` - Select SCA method (INFO)</li> <li>`BA3020` - Select SCA medium (INFO)</li> <li>`BA3030` - SCA Challenge (INFO)</li> <li>`BA3040` - SCA failed (ERROR)</li> <li>`BA3060` - No supported SCA method found (ERROR)</li>",
                "enum": [
                  "BA999",
                  "BA1000",
                  "BA1001",
                  "BA1010",
                  "BA1011",
                  "BA1012",
                  "BA1013",
                  "BA1014",
                  "BA1020",
                  "BA1051",
                  "BA1052",
                  "BA1053",
                  "BA1060",
                  "BA1062",
                  "BA1063",
                  "BA1064",
                  "BA1100",
                  "BA1101",
                  "BA1102",
                  "BA1103",
                  "BA1104",
                  "BA1110",
                  "BA1111",
                  "BA1112",
                  "BA1200",
                  "BA1204",
                  "BA1212",
                  "BA2002",
                  "BA2003",
                  "BA2004",
                  "BA2021",
                  "BA2062",
                  "BA3000",
                  "BA3005",
                  "BA3010",
                  "BA3020",
                  "BA3030",
                  "BA3040",
                  "BA3060"
                ],
                "example": "BA999"
              },
              "message": {
                "type": "string",
                "description": "**Error** text for display by the end customer according to **errors and messages**"
              },
              "details": {
                "type": "string",
                "description": "Further information on the display at the end customer, which can change from message to message."
              }
            },
            "example": [
              {
                "level": "INFO",
                "code": "BA3010",
                "message": "SCA benötigt",
                "details": "Bitte wählen Sie eine SCA-Methode aus"
              }
            ],
            "description": "Messages transport both errors and analysis events."
          },
          "description": "Messages transport both errors and analysis events."
        },
        "scaMethods": {
          "type": "array",
          "items": {
            "title": "SecurityProcedureEn",
            "description": "The security procedure determines how end users authenticate their transaction(s).",
            "type": "object",
            "properties": {
              "code": {
                "type": "integer",
                "description": "Key to the security procedure"
              },
              "name": {
                "type": "string",
                "description": "Human readable name for the security procedure"
              },
              "hint": {
                "type": "string",
                "description": "Human readable reference to the security procedure"
              }
            },
            "example": {
              "code": 4711,
              "name": "mTAN",
              "hint": "Ihre mTAN"
            }
          },
          "description": "List of possible sca methods for this account."
        },
        "scaMediums": {
          "type": "array",
          "items": {
            "title": "TanMediumEn",
            "description": "This object describes a TAN medium.",
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of the TAN medium such as \"Mobile\""
              },
              "mediaClass": {
                "description": "Media classes: <li>`LIST` - Paper-TAN list</li> <li>`GENERATOR` - TAN generator</li> <li>`MOBILE` - mobile phone</li> <li>`SECODER` - TAN matrix generator</li> <li>`PUSHTAN` - Push message</li> <li>`ALL` - All classes</li> <li>`PROPRIETARY` - Proprietary media class</li>",
                "type": "string",
                "enum": [
                  "LIST",
                  "GENERATOR",
                  "MOBILE",
                  "SECODER",
                  "PUSHTAN",
                  "ALL",
                  "PROPRIETARY"
                ]
              },
              "validFrom": {
                "type": "string",
                "format": "YYYY-MM-DD hh:mm:ss",
                "description": "Date and time from which the TAN medium is valid."
              },
              "validTo": {
                "type": "string",
                "format": "YYYY-MM-DD hh:mm:ss",
                "description": "Date and time until which the TAN medium is valid."
              }
            },
            "example": {
              "validFrom": "2016-01-01 00:00:00",
              "validTo": "2016-12-31 23:59:59",
              "name": "+49-1111-11111",
              "mediaClass": "MOBILE"
            }
          },
          "description": "List of possible sca mediums for this account."
        },
        "challenge": {
          "title": "Challenge",
          "required": [
            "name",
            "content"
          ],
          "description": "Contains information about TAN generation",
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the TAN procedure"
            },
            "content": {
              "title": "ChallengeContent",
              "type": "object",
              "properties": {
                "instructions": {
                  "type": "string",
                  "description": "Textual description on how to perform authentication",
                  "example": "Nutzen sie Ihren TAN-Generator und geben sie anschließend Ihre TAN ein."
                },
                "HHD": {
                  "type": "string",
                  "description": "Textual representation of flicker code when using optical ChipTAN",
                  "example": "11048714955205123456789F14302C303107"
                },
                "HHDUC": {
                  "type": "string",
                  "description": "Textual representation of code when using FlickerTAN",
                  "example": "1234567891234567891234567890,01"
                },
                "photo": {
                  "type": "string",
                  "description": "Base64-encoded png of the mosaic photo to be displayed to the user when using PhotoTAN",
                  "example": "data:image/png;base64,iVBORw0KGgoAAA..."
                },
                "PDF": {
                  "type": "string",
                  "description": "Base64-encoded PDF needed for the challenge",
                  "example": "data:application/pdf;base64,JVBERi0xLjQNCj..."
                }
              },
              "description": "Challenge data needed to perform the authentication with the chosen authentication method",
              "example": {
                "instructions": "Nutzen sie Ihren TAN-Generator und geben sie anschließend Ihre TAN ein.",
                "HHD": "11048714955205123456789F14302C303107",
                "HHDUC": "1234567891234567891234567890,01"
              }
            },
            "decoupled": {
              "type": "boolean",
              "description": "Indicates whether the SCA approach is decoupled, thus not expecting `scaAuthenticationData` within [Submit SCA Data](#/components/schemas/SubmitScaData), but just an empty object to confirm the user indicated that he meanwhile confirmed the activity, e.g. through the bank app, independently."
            },
            "redirect": {
              "type": "boolean",
              "description": "Indicates whether the SCA approach is redirect."
            }
          },
          "example": {
            "challenge": {
              "name": "chipTAN optisch",
              "content": {
                "instructions": "Nutzen sie Ihren TAN-Generator und geben sie anschließend Ihre TAN ein.",
                "HHD": "11048714955205123456789F14302C303107",
                "HHDUC": "1234567891234567891234567890,01"
              },
              "decoupled": false,
              "redirect": false
            }
          }
        },
        "relations": {
          "type": "array",
          "items": {
            "title": "Relation",
            "description": "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.",
            "required": [
              "rel",
              "href"
            ],
            "type": "object",
            "properties": {
              "rel": {
                "type": "string",
                "description": "Machine readable string to differentiate the relations",
                "example": "self"
              },
              "href": {
                "type": "string",
                "description": "URL where the relation links to",
                "example": "https://banksapi.io:443/providers/v2/00000000-0000-0000-0000-000000000000"
              }
            },
            "example": {
              "rel": "self",
              "href": "https://banksapi.io:443/providers/v2/00000000-0000-0000-0000-000000000000"
            }
          },
          "description": "The relations available for the payment"
        }
      }
    }
    
    

    Properties

    Name Type Required Restrictions Description
    messages [Message] false none Messages transport both errors and analysis events.
    scaMethods [SecurityProcedureEn] false none List of possible sca methods for this account.
    scaMediums [TanMediumEn] false none List of possible sca mediums for this account.
    challenge Challenge false none Contains information about TAN generation
    relations [Relation] false none The relations available for the payment

    Product

    {
      "id": "DE00123456789012345679",
      "status": "VOLLSTAENDIG",
      "bezeichnung": "Tagesgeldkonto",
      "kategorie": "TAGESGELDKONTO",
      "saldo": 27365.56,
      "aktualisierungszeitpunkt": "2021-10-15 09:13:44",
      "saldoDatum": "2021-10-15 00:00:00",
      "waehrung": "EUR",
      "kontonummer": "9012345679",
      "iban": "DE00123456789012345679",
      "bic": "XXX12345678",
      "blz": "12345678",
      "kreditinstitut": "Demo Provider",
      "inhaber": "Fritz Testmüller",
      "transferSupport": true,
      "relations": [
        {
          "rel": "get_kontoumsaetze",
          "href": "https://banksapi.io/customer/v2/bankzugaenge/0b7f4783-4c93-4820-8e73-354a0f1c469e/DE00123456789012345679/kontoumsaetze"
        },
        {
          "rel": "initiate_single_transfer",
          "href": "https://banksapi.io/customer/v2/payment/single-transfer"
        },
        {
          "rel": "initiate_bulk_transfer",
          "href": "https://banksapi.io/customer/v2/payment/bulk-transfer"
        }
      ],
      "messages": [],
      "verfuegungsrahmen": 27365.56,
      "verfuegterBetrag": 0
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous SimpleProduct false none Banking product (e.g. account) with only a subset available product data

    and

    Name Type Required Restrictions Description
    anonymous object false none Banking product with all available fields. A simpler version of this object is
    » status string false none Retrieval status for product data
    » aktualisierungszeitpunkt string(YYYY-MM-DD hh:mm:ss) true none Time of the last product update at the bank/service provider
    » transferSupport boolean false none Indicates if transfers are supported for this bank product or not.
    » bulkTransferSupport boolean false none Indicates if bulk transfers are supported for this bank product or not.
    » relations [Relation] true none List of relations that are available as next steps.
    » messages [Message] false none List of messages that show which steps are required to continue further.
    » saldoDatenquelle string false none The source of the data for this depots balance. Only for products of type depot.
    » ueberziehungslimit number false none The overdraft limit for a bank account. Only for products that have an overdraft limit.
    » verfuegungsrahmen number false none Contains the available balance (usually overdraft limit + balance)
    » verfuegterBetrag number false none Contains the available balance (usually overdraft limit + balance)
    » vertragsnummer string false none The contract number for home savings contracts.
    » rating number false none none
    » vertragssumme number false none The contract amount for home savings contracts.
    » vertragstyp string false none The type of home savings contract.
    » sparzustand boolean false none Shows if the home savings contract is currently in saving state (true) or not (false)
    » vertragsstatus string false none The current state of a home savings contract.
    » sparzinssatz number false none The savings rate of a home savings contract.
    » schuldzinssatz number false none The debt interest rate of a home savings contract.
    » vertragsDatum string(YYYY-MM-DD hh:mm:ss) false none The date of a home savings contract.
    Enumerated Values
    Property Value
    saldoDatenquelle SWIFTMSG
    saldoDatenquelle SONSTIGE

    ProductCategories

    [
      "GIROKONTO",
      "TAGESGELDKONTO"
    ]
    
    

    ProductCategories

    Properties

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

    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
  • KREDITKARTENKONTO - Credit card acount:
  • 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 KREDITKARTENKONTO
    ProductCategory SONSTIGEKARTE
    ProductCategory DEPOT
    ProductCategory SONSTIGESPRODUKT

    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": "^.{1,50}$"
          },
          {
            "fieldkey": "pin",
            "label": "Demo-Passwort",
            "secret": true,
            "hint": "demo1, demo2 oder demo3",
            "format": "^.{1,50}$"
          }
        ]
      }
    }
    
    

    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
    consumerRelevant boolean true none Whether this provider should be displayed to the customer for the provider selection or not
    group string false none Grouping term for providers. If several providers have the same group the same logo could be displayed, e.g.
    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 180 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.

    ProviderCoreData

    [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Demo Provider",
        "group": "demo",
        "blz": "12345678",
        "bic": "DEMO1234",
        "logo": "https://banksapi.io/providers/v2/demo.svg"
      }
    ]
    
    

    ProviderCoreData

    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 the same logo could be displayed, e.g.
    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
    logo string false none Returns the path to the provider logo in SVG-format

    ProviderJobStatistics

    [
      {
        "logo": "demo",
        "latestSuccessDate": "2023-09-20 11:21:02",
        "averageDuration": 29962,
        "successRate": 1
      },
      {
        "logo": "sparkasse",
        "latestSuccessDate": "2023-09-20 11:28:57",
        "averageDuration": 54186,
        "successRate": 0.99
      }
    ]
    
    

    ProviderJobStatistics

    Properties

    Name Type Required Restrictions Description
    logo string true none Logo of the provider.
    latestSuccessDate string(YYYY-MM-DD hh:mm:ss) true none Date of the latest successful data job for providers with the corresponding logo.
    averageDuration number true none The average duration of data jobs in ms for providers with the corresponding logo.
    successRate number true none The success rate of data jobs for providers with the corresponding logo.

    ProviderEbicsInfo

    {
      "hostId": "HOSTIDXY",
      "hostUrl": "https://ebics.bank.com/ebics"
    }
    
    

    ProviderEbicsInfo

    Properties

    Name Type Required Restrictions Description
    hostId string false none The EBICS host ID of the bank
    hostUrl string false none The EBICS host URL of the bank

    CheckInstantPaymentSupport

    {
      "type": "object",
      "properties": {
        "recipientIbans": {
          "type": "array",
          "description": "The recipient's IBANs. If not provided, it will only be determined if the provider supports sending instant payments.",
          "items": {
            "type": "string"
          },
          "example": [
            "DE92123456789876543210"
          ]
        },
        "transferType": {
          "type": "string",
          "description": "The type of transfer. This type is required if `recipientIbans` is not provided.",
          "enum": [
            "SINGLE",
            "BULK"
          ],
          "example": "SINGLE"
        }
      }
    }
    
    

    Properties

    Name Type Required Restrictions Description
    recipientIbans [string] false none The recipient's IBANs. If not provided, it will only be determined if the provider supports sending instant payments.
    transferType string false none The type of transfer. This type is required if recipientIbans is not provided.
    Enumerated Values
    Property Value
    transferType SINGLE
    transferType BULK

    InstantPaymentSupportResult

    {
      "type": "object",
      "required": [
        "senderProviderId",
        "transferType",
        "instantPaymentSupported"
      ],
      "properties": {
        "senderProviderId": {
          "type": "string",
          "description": "The ID of the provider sending the instant payment.",
          "example": "00000000-0000-0000-0000-000000000000"
        },
        "recipientIbans": {
          "type": "array",
          "description": "The IBANs of the recipients.",
          "items": {
            "type": "string"
          },
          "example": [
            "DE92123456789876543210"
          ]
        },
        "transferType": {
          "type": "string",
          "description": "The type of transfer.",
          "enum": [
            "SINGLE",
            "BULK"
          ],
          "example": "SINGLE"
        },
        "instantPaymentSupported": {
          "type": "boolean",
          "description": "Indicates if instant payment is supported.",
          "example": true
        }
      }
    }
    
    

    Properties

    Name Type Required Restrictions Description
    senderProviderId string true none The ID of the provider sending the instant payment.
    recipientIbans [string] false none The IBANs of the recipients.
    transferType string true none The type of transfer.
    instantPaymentSupported boolean true none Indicates if instant payment is supported.
    Enumerated Values
    Property Value
    transferType SINGLE
    transferType BULK

    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

    RelationSchema

    {
      "properties": {
        "href": {
          "description": "Link of the relation",
          "example": "https://banksapi.io/.../tags/tag-trees/1/",
          "type": "string"
        },
        "rel": {
          "description": "Name of the relation",
          "example": "tag_trees",
          "type": "string"
        }
      },
      "required": [
        "href",
        "rel"
      ],
      "type": "object"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    href string true none Link of the relation
    rel string true none Name of the relation

    ScaInteraction

    {
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "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.
    relations [Relation] true none The relations available for bank access
    tanMedien [TanMedium] false none List of available TAN media in the access

    SecurityProcedure

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

    SecurityProcedure

    Properties

    Name Type Required Restrictions Description
    kodierung integer 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

    SecurityProcedureEn

    {
      "code": 4711,
      "name": "mTAN",
      "hint": "Ihre mTAN"
    }
    
    

    SecurityProcedureEn

    Properties

    Name Type Required Restrictions Description
    code integer false none Key to the security procedure
    name string false none Human readable name for the security procedure
    hint string false none Human readable reference to the security procedure

    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

    SimpleProduct

    {
      "id": "DE89370400440532013000",
      "status": "VOLLSTAENDIG",
      "bezeichnung": "Tagesgeldkonto",
      "kategorie": "TAGESGELDKONTO",
      "saldo": 27365.56,
      "aktualisierungszeitpunkt": "2021-10-15 09:13:44",
      "saldoDatum": "2021-10-15 00:00:00",
      "waehrung": "EUR",
      "kontonummer": "9012345679",
      "iban": "DE89370400440532013000",
      "bic": "XXX12345678",
      "blz": "12345678",
      "kreditinstitut": "Demo Provider",
      "inhaber": "Fritz Testmüller"
    }
    
    

    Simple Product

    Properties

    Name Type Required Restrictions Description
    id string true none Identifier for the bank product
    bezeichnung string false none Name of bank product according to bank/service provider
    kategorie 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
  • saldo number false none Balance/value of bank product (with two decimal places)
    saldoDatum string(YYYY-MM-DD hh:mm:ss) false none Balance/value date as reported by the bank/service provider
    waehrung string false none Currency in which the bank product is valued/managed (Alphabetic Code ISO 4217)
    salden object false none A map where the key is the currency and the value is a Balance object. This field is only returned for multicurrency accounts.
    » additionalProperties Balance false none none
    kontonummer string true none The account or credit card number. The credit card number may not be issued completely, but with a star e.g. "3223 ****** 4554"
    iban string false none The IBAN (International Bank Account Number)
    bic string false none The BIC (Business Identifier Code)
    blz string false none The (state local) bank code
    kreditinstitut string false none Name of financial institution
    inhaber string false none Full name of account holder
    Enumerated Values
    Property Value
    kategorie GIROKONTO
    kategorie SPARKONTO
    kategorie FESTGELDKONTO
    kategorie KREDITKONTO
    kategorie TAGESGELDKONTO
    kategorie BAUSPARVERTRAG
    kategorie VERSICHERUNG
    kategorie SONSTIGESKONTO
    kategorie AMERICANEXPRESS
    kategorie MASTERCARD
    kategorie VISA
    kategorie DINERSCLUB
    kategorie SONSTIGEKARTE
    kategorie DEPOT
    kategorie KREDITKARTENKONTO

    SingleDebitData

    {
      "provider": "ca650b48-3edc-45f4-938d-d21df8cba761",
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iH ... D/MOfGsd8HY=",
        "pin": "XO2jgZ ... 5GfhKpZmw="
      },
      "product": "DE89370400440532013000",
      "business": false,
      "sequenceType": "OOFF",
      "creditorSchemeIdentification": "GlauebigerId",
      "requestedCollectionDate": "2022-02-22",
      "debitDetails": {
        "amount": 1337.42,
        "currency": "EUR",
        "purpose": "Verwendungszweck",
        "endToEndId": "123",
        "debtorName": "Max Mustermann",
        "debtorIban": "DE62430609671149278400",
        "debtorAccountNumber": "1149278400",
        "debtorBankCode": "43060967",
        "debtorBic": "GENODEM1GLS",
        "mandateIdentification": "MandatsId",
        "mandateDateOfSignature": "2022-02-02"
      }
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous PaymentInitializationDetails false none none

    and

    Name Type Required Restrictions Description
    anonymous DebitBaseInfo false none none

    and

    Name Type Required R