BANKS/Connect Customer API

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

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

To get started, see our Quick Start Guide.

INFO

The entry point to BANKS/Connect Customers API is https://banksapi.io/customer/v2.

Example Response

json

{
  "1cb1126d-360d-412d-a74f-985414f57ea3": {
    "status": "VOLLSTAENDIG",
    "aktivesSicherheitsverfahren": {
      "kodierung": 1,
      "name": "Mock-TAN",
      "hinweis": "Mock-TAN"
    },
    "aktualisierungszeitpunkt": "2025-06-10 17:17:40",
    "timeout": "2025-12-24 13:37:42",
    "bankprodukte": [],
    "sync": false,
    "tanMedien": [{
      "gueltigVon": "2025-06-03 17:17:41",
      "gueltigBis": "2025-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"
    }]
  }
}

API Reference

Concepts

REG/Protect (redirect solution)

The BANKSapi REG/Protect 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.

For enhanced security, tenants can configure allowed callback URL patterns to restrict which URLs can be used when returning from REG/Protect processes. This provides additional protection for end users by preventing unauthorized redirects. Patterns support wildcards (e.g., https://*.banking.com/*, intent://banksapi.finished/). If you wish to implement such restrictions, please contact BANKSapi to configure these security settings.

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.

Strong customer authentication

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

Knowledge
Possession
Inherence

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

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

TAN-less procedures include apps provided by the banks to the end customers that can be used to just approve of activities. In this case the phone itself is the possession factor. For Update Bank Access Consent, 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

INFO

The exact characteristics of the media class and the name are not necessarily identical for each security procedure, as they depend on the respective provider.

Customer IP Address

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

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

add_bankzugang
start_ueberweisung
delete_bankzugang
delete_bankzugaenge
start_sca

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

Customer-IP-Address: 123.234.123.234

REG/Protect

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

Context info when returning to your app

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

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

Adding and authenticating a bank access

bash

$ 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.

INFO

For regulatory reasons, the REG/Protect may only be accessed (e.g. in a separate window) in such a way that the URL and SSL certificate of BANKSapi GmbH are visible to the end user. Accordingly, a solution using iframe is not permitted.

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.

TIP

It makes sense, for example, to append your own reference IDs to the callbackUrl as query parameters in order to recognize the user after a redirect and to continue the process correctly.

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

bash

curl https://banksapi.io/customer/v2/ueberweisung/e1f30693-bab3-4c8b-9b3c-bc2/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 a 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 (URL-encoded), 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 Update Bank Access Consent 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 Update Bank Access Consent 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 Update Bank Access Consent. authentication_decoupled: This relation is for TAN-less i.e. decoupled methods, send a `GET` request to the `authentication_decoupled`-relation to poll for the status of the SCA. This relation appears together with the `authentication`-relation, but should always be preferred. redirect_url: When this relation is available the authentication will be performed on the bank interface. The user therefore needs to be redirected to the URL in this relation and will reenter your application at the given `callbackUrl`, that was provided as a query parameter in the POST request. If the redirected authentication ends prematurely and the user cannot finish the authentication, we offer a `cancel`-relation There can be multiple SCAs for a single bank access, so your application needs to be able to handle any of the above mentioned relations at any point of the creation/update. If any of the SCAs fail, there will be `start_sca` relation when the bank access reaches the status `VOLLSTAENDIG`
No	Background update of a bank access	The consent of the customer might expire at some point and new data can't be fetched from the bank. In this case, the BankAccess object will contain a relation `start_sca`. `POST` an empty object to this relation in order to indicate that the user is ready to start an SCA process and renew the consent.

Encryption

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

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

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

INFO

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

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). Please be aware that this functionality is best effort and while more than 90 days is possible for the majority of accounts, there are banks that still only return 90 days.

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 more than 90 days, you can use the optional parameter maxTransactions as a query parameter when adding or refreshing a bank access. If indicating paymentAccounts, more than 90 days 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 application.

TIP

Best Practice: Use the maxTransactions parameter when first creating a bank access to fetch the complete transaction history, if necessary. Avoid using it during refresh operations, as this would cause unnecessary SCAs since the transaction history will already be available from the initial creation and as well as the ongoing background synchronization.

INFO

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

Transaction tags (categorization)

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

BANKS/Connect Customer API ​

Example Response ​

API Reference ​

Concepts ​

REG/Protect (redirect solution) ​

Background update ​

Strong customer authentication ​

TAN medium ​

Customer IP Address ​

REG/Protect ​

Context info when returning to your app ​

Adding and authenticating a bank access ​

Triggering a payment ​

Operations with SCA ​

Encryption ​

Transactions older than 90 days ​

Transaction tags (categorization) ​

BANKS/Connect Customer API

Example Response

API Reference

Concepts

REG/Protect (redirect solution)

Background update

Strong customer authentication

TAN medium

Customer IP Address

REG/Protect

Context info when returning to your app

Adding and authenticating a bank access

Triggering a payment

Operations with SCA

Encryption

Transactions older than 90 days

Transaction tags (categorization)