NAV Navbar


Ahoy from AHOI!

You are reading the Cookbook for the AHOI API.

Are you looking for the AHOI API documentation?

What is AHOI?

AHOI is a managed and flexible banking API that provides easy access to users' bank accounts. Actions such as retrieving account balances, submitting transfers, analyzing transactions, forecasting balances, and notifications of account activity are simplified by hiding complex bank interfaces. Most German banks are supported, and a high level of security and regulatory standards are maintained.

Why does the world need AHOI?

Developing a service that provides banking functionality to users is challenging. The German banking sector is incredibly varied, with different interfaces and processes, so simple requirements like the retrieval of account balances or transactions require complex protocols.

That's where AHOI comes in. AHOI unifies all bank interfaces into a single multi-bank API. This is achieved by:

AHOI relies on well-established standards such as REST, JSON and OAuth2.0.

What does AHOI offer?

AHOI offers standard banking functionality such as retrieving account information or submitting new transfers. In addition, more intelligent features such as recognizing contracts, categorization, push notifications for new incoming transactions or account balance forecasts are also available. You can find the complete scope of AHOI functions in the Features chapter.

Furthermore, AHOI provides you with a variety of tools that make it easier for you to familiarize yourself and develop with AHOI:

In short, AHOI has something for everyone!

How does AHOI work?

Every attempt to access account-related data from a banking institution requires the corresponding access credentials of the bank customer. These usually consist of a username/account number and a PIN. However, since AHOI performs background analytic operations on the bank data, it isn't convenient to request user access credentials every time AHOI retrieves data from the bank. In addition, frequent input and transmission of sensitive data introduces an increased security risk.

For various reasons AHOI asks only once for user bank access credentials and saves them in an encrypted format in high-security data storage. Next, AHOI retrieves the accounts and transactions from the associated bank, converts them to the standard AHOI format and maintains them internally. After this setup process, the standardized account data is ready for retrieval via the AHOI-REST interface. AHOI also constantly synchronizes the data with the bank in the background to ensure that it is always up-to-date. This enables AHOI to provide features such as notifications for new incoming transactions.

If desired, AHOI can also perform further special operations on the data, such as identifying regular transactions or orders (see Features).

How can AHOI work for you?

Want to develop a product or service that provides banking functionality to your users? Then you've come to the right place.

Just register for free at our Sandbox and try AHOI right away. If you'd like to use AHOI in your product, contact us.


AHOI supports all standard banking functionality. This includes

Furthermore, AHOI offers additional features such as

In addition, AHOI enables you to test and evaluate all of its functionality on a non-production system. With our AHOI Sandbox, you can emulate your own miniature demo with the AHOI Sandbank and use it to generate transactions. This allows you to create customized scenarios and test all AHOI features extensively without the need for production data.


To give you a better understanding of how AHOI works, we would like to introduce you to some of its basic concepts.

big picture


AHOI is most exciting when you use it to develop your own service in order to provide banking functionality to your users.

What that service looks like is completely up to you. As long as it communicates with AHOI via REST, there are no limits.

As a prerequisite to using AHOI, you must uniquely register your service. This is done simply by registering for Sandbox access. Doing so will provide you with service-specific credentials that you will later integrate securely into your service application to uniquely identify your HTTP requests to AHOI. For more details on how to construct your requests, see the In-Depth Tutorial.

Endpoints and Data Types

The AHOI endpoints and data types are described in detail in the API documentation. To make it easier for you to get started, here's an overview of the most important data types:

A bank is represented in AHOI through a Provider. Customer-specific access to that bank, which is simply called Access, is always assigned to such a Provider. For this Access, bank customers typically have credentials like username and pin that are used to authenticate with their online banking service.

One or more bank accounts, called Accounts, are attached to an Access. These Accounts have a balance as well as other related information.

An Account itself contains Transactions, which represent account activity.

Here's a brief overview of all AHOI data types.

HTTP Requests

We aim for consistent behavior in the AHOI API, so you can expect AHOI to behave in the same way when accessing different endpoints — naturally using HTTP methods in line with REST for CRUD (create, read, update, delete) commands. This improves usability and helps you to familiarize yourself quickly with the API. For more information on HTTP requests, see the detailed chapter on HTTP requests.

User Registration

When you send requests from your service to AHOI, it must be able to identify not only your service as such but also the users of your service. To associate your users with AHOI, you must explicitly register each individual user for whom you want to perform banking via AHOI. Only then you can execute user- and account-specific actions on their behalf. To learn how this user registration operates, see the In-Depth Tutorial. The goal of this registration is to obtain a secret for each user. This user secret, which we call installationId, gives you the authority to set up bank accounts for them and to leverage all of AHOI's banking features.

This results in two steps for each user:

  1. A one-time registration step that aims to create a user context with which bank data can later be transmitted. The goal of this step is to obtain a user secret (installationId).

  2. The subsequent and ongoing banking step, which allows you to set up a user's bank access as well as access to any banking-specific endpoints for that user.


To understand how authentication works in AHOI, it's necessary to differentiate between two distinct authentication processes: the authentication of a bank customer with that customer's bank and the authentication of an AHOI user with the AHOI API.

Authentication with the bank

Authentication of a bank customer at the corresponding bank is always done using username and pin. Those access credentials are required every time account-specific data (e.g., requesting new transactions) are retrieved. However, since this sensitive data should not be requested each and every time the bank is contacted, AHOI collects it once and then stores it server-side in an encrypted format.

Authentication with AHOI

To create a secure user context in which the access credentials can be stored and with which user-specific bank data can later be transmitted, a user must first be registered with AHOI, as noted above.

After registration, the user secret (installationId), which functions like an ID and a secret at the same time, can be used to obtain an authorization token from the AHOI authentication server. This token authorizes the user to access all banking-specific AHOI endpoints.

As a rule, AHOI uses the OAuth 2.0 open protocol. The basic idea here is that a user does not authenticate at the banking endpoints with the sensitive user secret (in this case the installationId) but rather only with a token. This token is issued to the user by the AHOI authentication server after the installationId is presented. A token expires after a few minutes and therefore carries less risk than the more critical installationId in the event of loss.

Two points are important for you to bear in mind. On the one hand, a user must be registered before the user-specific bank access credentials can be transferred. And on the other hand, every request to AHOI must be authenticated with a user-specific OAuth token.

Similarly to the two steps above (i.e., registration and banking), there are two different types of tokens:

  1. An anonymous registration token, which is only required for the registration process of a user who is new to AHOI. To obtain this token, your service only needs the service-specific credentials (clientId etc.). You can find these in your Sandbox Manager.

  2. A user-specific banking token that can be obtained by sending a user's installationId. This token is required to access all banking-specific endpoints.

You can learn how to obtain the tokens and what you can do with them in the Authentication via OAuth2 chapter.



AHOI offers developers who want to test or evaluate AHOI a development environment designed for test operations. In keeping with the idea of a safe playground space, we call this system the Sandbox.

In this Sandbox, every registered developer has his or her own corner to experiment. It includes:

Also, the more complex security mechanisms (such as encryption of sensitive data) are deactivated in the Sandbox by default so you can get started more easily. If you want to, however, you can re-enable encryption.

The following chapter on Tools explains the Sandbox-Manager in more detail.


AHOI provides you with a range of tools to simplify your experience when developing with AHOI.


The Sandbox-Manager is the best starting point for developing your own (test) banking service.

This is where you can get a preliminary overview of your registered service. You can see your service-specific credentials, such as your clientId, clientSecret, appSecretKey and your appSecretIV. What exactly you need to do with all these components is described in the Getting Started section.

You can also simulate your very own miniature AHOI Sandbank here. Currently you have the ability to manage one bank access with three accounts. Additionally, you can find the bank access credentials (like username and pin) that you can use to set up bank accounts with AHOI for your (demo) users. You can generate new transactions of any kind in your demo account. We have already generated a variety of transactions for you. These are from a real (albeit anonymous) bank account and have been personally tailored to make your test scenarios as authentic as possible.

To try AHOI, please register with the Sandbox-Manager. It's free!

API Explorer

The API Explorer allows you to access all AHOI endpoints directly from your browser without writing a single line of code.

It's your perpetual companion — from your very first introduction all the way to extensive debugging during the development phase (in case your code doesn't work as it should, which, of course, will never happen!).

The API Explorer is directly integrated into the API documentation. Detailed instructions on how to use the API Explorer can be found below.


Many developers want to see sample code first. No problem! You can find our introduction to the AHOI SDKs below. They'll save you a lot of time and effort.

Getting Started

We want you to be able to get started quickly with AHOI. Regardless of whether you just want to give AHOI a try or you already have big plans in mind, this is the right place for you.

In any event, you'll need your own access to the Sandbox first. Here's where you can register for the Sandbox.

Once you've registered, there are several ways to try out AHOI:

API Explorer Tutorial

The API Explorer is integrated directly into the AHOI documentation. Follow the steps below to experience your first success with the API Explorer:

  1. Open your Sandbox Manager so you can see your service-specific credentials.

  2. Open the API Explorer in a second browser tab.

  3. Copy your credentials (clientId, clientSecret, appSecretIV and appSecretKey) from the Sandbox Manager into the respective fields in the API Explorer in the sidebar located on the left.

  4. Click on Get Registration Token. This obtains a registration token that appears in the Token field.

  5. Select Registration in the menu on the left, then User Registration, and finally select TRY for this endpoint. The previously anonymous user will now be registered and that user's installationId will be displayed. But you don't have to remember the installationId — just close the pop-up. The API Explorer will automatically put the variable into the corresponding field in the sidebar on the left. The Explorer has also automatically fetched a banking token for you, so you can now access all banking-specific AHOI endpoints. Congratulations!

  6. Set up your AHOI Sandbank access in AHOI. To do this, first take note of your AHOI Sandbank credentials (blz, username, pin) in the Sandbox Manager. Then switch to Provider in the menu and select List bank providers. Insert the bank code of the AHOI Sandbank (99994000) into the bankCode field and execute the request with TRY.

  7. As a result, you've now received an id for the provider. Next, select Access in the menu and then select the Create a new access endpoint. By clicking on the JSON body sample on the right, you can add an accessDto to your request. Replace the values in the providerId, USERNAME and PIN fields with your own values, delete the entry for CUSTOMERNUMBER and then execute the request. In response, you should get an HTTP status code 201 with a validationState: OK.

Your bank account is now successfully set up and AHOI has retrieved the account data for the AHOI Sandbank. And you also have all the other banking endpoints such as Get Account or List Transactions at your fingertips. Just give it a try!

SDKs Tutorial

Our SDKs are currently in closed beta state and thus not yet publicly available. If you are interested, please don't hesitate to Contact Us directly.

In-Depth Tutorial

A prerequisite for this tutorial is that you have studied the Basics of AHOI extensively and already have a Sandbox account.

1. Note Your Sandbox Credentials

For various operations you will need your service-specific credentials. Log into the Sandbox Manager and note the values for clientId and clientSecret.

2. Become Familiar with OAuth Flow

You must always send authentication tokens to AHOI as part of your requests. Before continuing, be sure to familiarize yourself with the two different types of AHOI tokens by reading the chapter on Authentication via OAuth2.

In that chapter, you'll find information on how to obtain the two tokens (registration and banking tokens) and integrate them into your HTTP requests to AHOI. Once you're done with that, you can proceed to the next step.

3. Register a User

Now we want to register a sample user with AHOI and obtain an installationId, which we can then use to obtain a banking token.

First, get a registration token as described in the OAuth chapter and integrate it into your request. Also consult the chapter on HTTP requests.

Next, invoke the endpoint POST <HOST>/ahoi/api/v2/registration. You'll receive an installationId for your user.

  "installation": "UW/QJ5ow1N ... L62OTyzDE="

The installationId is private and must be protected. It identifies the user context and must therefore be stored securely within your service.

If you have enabled encryption (disabled by default), you will have to decrypt the installationId before continuing.

4. Obtain a Banking Token

With the installationId you can now obtain a banking token. This procedure is also described in the chapter on Authentication via OAuth2.

From now on, you have to include this banking token in each of your requests for this user.

5. Check If a Provider Is Supported

  "type": "BankProvider",
  "id": "f8735c31-fbc9-4461-96e5-22b4b1ae9c92",
  "name": "Sandbox",
  "location": "Hamburg",
  "accessDescription": {
    "infoText": "Geben Sie bitte unter Benutzerkennung Ihre Kontonummer ein.",
    "fieldDescriptions": [
        "id": "USERNAME",
        "label": "Benutzerkennung",
        "masked": false,
        "lengthMin": 0,
        "lengthMax": 0
        "id": "PIN",
        "label": "PIN",
        "masked": true,
        "format": "UNSPECIFIED",
        "lengthMin": 5,
        "lengthMax": 5
  "supported": true,
  "bankCode": "99994000",
  "bic": "TESTBIC"

To have AHOI connect to your AHOI Sandbank account, you first need to check whether the bank is supported and how AHOI needs to access it. AHOI's provider REST endpoint provides this information.

To obtain a list of all providers, a GET request to GET <HOST>/ahoi/api/v2/providers is sufficient. However, finding something is much quicker if you know what you’re looking for. With this in mind, you can narrow the search by providing a bank code (BLZ or routing number) with GET <HOST>/ahoi/api/v2/providers?bankCode=99994000.

In response, AHOI returns an expanded JSON representation of the provider.

The supported field in the provider's JSON representation denotes whether or not AHOI is able to access the provider. The document contains other important fields, such as the accessDescription, which contains the fieldDescriptions. Those are required to set up access to a bank in AHOI.

As the JSON response shows, the provider "Sandbox" requires two credential fields to create an access in AHOI:

Along with the IDs for these fields, labels are also returned. These labels contain names that are significant to the provider's customers. For example, if the USERNAME field is set up to be used with the customer's e-mail address, the label would be “e-mail address”. Or if the bank account number of the account is used, it would say “bank account no.”. Additionally, information is provided about which fields must be masked when displayed in the user interface, how long the values for the fields have to be and what kinds of input are required. This is useful information for validation.

6. Create Bank Access

POST /ahoi/api/v2/accesses HTTP/1.1
Authorization: Bearer eyJhbGciOi ... JRt2ywq40
X-Ahoi-Session-Security: QJ5ow1N ... L62OTyzDE

Content-Type: application/json
Cache-Control: no-cache

  "type": "BankAccess",
  "providerId": "f8735c31-fbc9-4461-96e5-22b4b1ae9c92",
  "accessFields": {
    "PIN": "PIN",

  "type": "BankAccess",
  "id": "6743c69b-d9d7-4b49-a476-562cc5f8c72c",
  "providerId": "f8735c31-fbc9-4461-96e5-22b4b1ae9c92",
  "validationStatus": "OK"

With the information gathered so far, AHOI can set up an Access to the bank Provider.

For the two fields

the respective values now have to be provided. In this case, these are the bank access credentials from your Sandbox Manager. If you have encryption for access credentials turned on, please have a look at the Encryption chapter on how to encrypt your data.

Now is the time to execute your access credentials using POST <HOST>/ahoi/api/v2/accesses.

AHOI connects to your bank and checks for bank Accounts and Transactions associated with the Access. If everything has gone smoothly, an HTTP 201 - Created response with the created bank access JSON document is returned in the response body. The response header fields contain a reference to the created resource (e.g., Location: <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c) as well as its ID (e.g., X-Id: 6743c69b-d9d7-4b49-a476-562cc5f8c72c).

Your bank data is now ready to be fetched, so let's try it out.

7. Get the Account

The Accounts REST endpoint allows you to interact with accounts in a more general manner. For example, GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts returns all Accounts for all Accesses with the id 6743c69b-d9d7-4b49-a476-562cc5f8c72c. GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf returns the Account with the ID a01e7861-03ff-4511-b8ef-dbd7bf7581bf.

AHOI automatically synchronizes accounts with the bank. By default, AHOI refreshes transactions on a daily basis. Transactions will be refreshed hourly if notifications (BalanceNotification, BudgetNotification or TransactionNotification) have been set up. After a certain time (default 90 days) of inactivity the data will be automatically deleted.

8. Get Transactions

    "type": "GiroTransaction",
    "transactionPatternId": 222,
    "id": "b0ec5b85-2251-42a9-b342-7d4fcc467065",
    "amount": {
      "value": 6522,
      "currency": "EUR"
    "bookingDate": "2016-11-13T12:00:00Z",
    "valueDate": "2016-11-13T12:00:00Z",
    "creditor": "Stadtreinigung Musterstadt",
    "creditorBankCode": "DEUTDEFFXXX",
    "creditorAccountNumber": "DE21330500000405205000",
    "debtor": "Symbioticon-Team15",
    "debtorBankCode": "TESTBIC",
    "debtorAccountNumber": "DE00999940000894952507",
    "purpose": "Kd 1181843 AN 100204621 sie he Gebue hrenbescheid",
    "cleanPurpose": "Kd 1181843 AN 100204621 sie he Gebue hrenbescheid",
    "prebooked": false

Transactions belong to one account. Therefore the accounts resource endpoint is responsible for providing a list of its transactions. In most cases, a GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf/transactions is sufficient. A useful parameter for this GET request is max-age, which specifies the maximum acceptable interval since the last refresh of the given account. The granularity for this parameter is in seconds. Therefore, if you set max-age to 1, you force the account to be refreshed immediately.

9. Transaction Patterns and Forecast

    "id": "044e53d2-95f5-480c-8912-c3746f3e0d9b",
    "state": "ACTIVE",
    "cycle": "MONTHLY",
    "origin": "FINDER",
    "day": 13,
    "relatedAccountOwner": "Symbioticon-Team15",
    "amount": {
      "value": 3797,
      "currency": "EUR"
    "accountNumber": "DE00999940000894952507",
    "bankCode": "TESTBIC",

Transaction patterns represent recurring transactions. AHOI tries to detect those on its own, but the user is also able to create transaction patterns and have AHOI use them to estimate a monthly budget.

First, determine which patterns AHOI has discovered on its own via GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf/transactionpatterns. If these transaction patterns were not detected correctly or are not relevant to the forecast, they can be disabled easily: PUT <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf/transactionpatterns/7574f9ef-29d3-45b3-8721-18d08751a2e5/active/false, where 7574f9ef-29d3-45b3-8721-18d08751a2e5 in this case is the ID of the transaction pattern.

Once the transaction patterns are adjusted, the request GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf/forecast returns the estimated balance forecast for the end of the current month based on the transaction patterns. The request GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf/forecast/transactions returns the same balance forecast including the expected transactions up to the end of the month.

10. Making Money Transfers

TAN Schemes

    "schemeId": "901",
    "name": "SMSTAN",
    "tanMediaList": [
        "tanMediaId": "6b46ee21f322a77e7062d4cc13f6a832",
        "name": "smsTAN",
        "description": "Privattelefon ******3020"
        "tanMediaId": "6b46ee21f322a77e7062d4cc13f6a832",
        "name": "smsTAN",
        "description": "Privattelefon ******1456"

Transfer Order

POST /ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf/transfers HTTP/1.1
Authorization: Bearer eyJhbGciOi ... JRt2ywq40
Content-Type: application/json
Cache-Control: no-cache

    "iban": "DE00999940000894952507",
    "bic": "XXXTESTBIC",
    "name": "Max Mustermann",
    "amount": {
      "value": 100,
      "currency": "EUR"
    "purpose": "Thanks a lot.",
    "tanScheme": "901",
    "tanMediaId": "6b46ee21f322a77e7062d4cc13f6a832"

  "transferTaskId": "d7261880-e7f8-4bc0-b831-9ec4278192f3",
  "fieldDescriptions": [
      "id": "TAN",
      "label": "TAN",
      "masked": true,
      "format": "DEFINITELYNUMERIC",
      "lengthMin": 6,
      "lengthMax": 6
  "challenge": "Bitte geben Sie die TAN ein!",
  "responseObjects": {
    "TAN": ""


POST /ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf/transfers/d7261880-e7f8-4bc0-b831-9ec4278192f3/authorize HTTP/1.1
Authorization: Bearer eyJhbGciOi ... JRt2ywq40
Content-Type: application/json
Cache-Control: no-cache

    "responseObjects": {
        "TAN": "111111"
 "state": "FINISHED",
 "transferTaskId": "d7261880-e7f8-4bc0-b831-9ec4278192f3"

Transferring money is a three-step process:

  1. GET supported TAN schemes
  2. POST an order to transfer money and receive a response to a challenge
  3. authorize the order

To place a transfer order, you need to know which TAN schemes are supported for the account you want to transfer from. To retrieve the supported TAN schemes, use GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/tanschemes, where 6743c69b-d9d7-4b49-a476-562cc5f8c72c is the ID of the access. You need to provide the name of the TAN scheme and the id of the TAN media (901 and 6b46ee21f322a77e7062d4cc13f6a832 in this example).

In the second step, the order to transfer money is created. It contains the information to whom and how much money will be transferred. Posting the request returns a transfer task, including field definitions for the challenge response and UI representation, the challenge itself and a representation of the response scheme. Also, it contains the transferTaskId field, which will be required to authorize the transfer later.

To answer the challenge/response scheme and authorize the transfer, the transferTaskId from the previous response and the TAN are required and sent in a JSON document in the request body of a POST request.

11. Get Notifications

Set up notification target

POST /ahoi/api/v2/notificationtargets HTTP/1.1
Authorization: Bearer eyJhbGciOi ... JRt2ywq40
Accept: application/json
Content-Type: application/json
Cache-Control: no-cache
  [JSON body]
  "appToken": "***appToken***",
  "productId": "***productId***",
  "operatingSystem": "ANDROID",
  "locale": "de_DE"

Set up balance change notification

POST /ahoi/api/v2/notificationtargets/d41b0a03-aeb3-415d-9e4c-78bb44d4cfab/notifications/balancechangenotification HTTP/1.1
Authorization: Bearer eyJhbGciOi ... JRt2ywq40
Accept: application/json
Content-Type: application/json
Cache-Control: no-cache
  [JSON body]
  "type": "BalanceChangeNotification",
  "accountId": "a01e7861-03ff-4511-b8ef-dbd7bf7581bf",
  "lowerThreshold": {
    "value": 10000,
    "currency": "EUR"

AHOI is capable of sending different kinds of push notifications to iOS and Android devices. The underlying services for notifications are the Apple Push Notification service (APNs) and Google Cloud Messaging (GCM). If you'd like to implement either of those services in your application, please refer to the documentation and provide us with the necessary credentials to connect you with our push service.

To do so, a notification target, which represents the device, needs to be set up. It includes a productId that identifies an app. Use "sandbox app" for testing purposes, or to receive notifications on actual devices, please contact us and include the credentials and application ID for the service of your choice. The topmost POST request represents an example request.

Next, the notification needs to be set up. AHOI currently supports four kinds of configurable notifications:

The second POST request shows how a balance change notification is set up.

The notifications themselves consist of a title and message, for example, the title "AHOI" and the message body:

Apple Push Notification service

Apple: DailySummaryNotification

    "msgType" : "DailySummaryNotification",
    "account" : "a01e7861-03ff-4511-b8ef-dbd7bf7581bf",
    "aps" : {
        "alert" : {
            "body" : "169 neue Umsätze seit letztem Status. Aktueller Kontostand: 11,29 \u20ac Offene Ausgaben: 0,00 \u20ac",
            "title" : "Das Girokonto"

Apple: AccessLockedNotification

    "msgType" : "AccessLockedNotification",
    "access" : "6743c69b-d9d7-4b49-a476-562cc5f8c72c",
    "aps" : {
        "alert" : {
            "body" : "Ihre Zugangsdaten zu {0} sind möglicherweise gesperrt. ...",
            "title" : "Gesperrte Zugangsdaten"

Notifications for IOS notification targets will be sent directly to the registered device and be displayed to the user as a notification.

The following notification definitions exist for APNs:

Notification Configurable Type Description
DailySummaryNotification yes user notification Information about the current account status, individual per account
BudgetChangeNotification yes user notification Notification that the calculated budget has crossed the configured threshold
BalanceChangeNotification yes user notification Notification that the account balance has crossed the configured threshold
NewTurnoverNotification (aka NewTransactionNotification) yes user notification Notification that a new transaction was received
NewTurnoverNotification (aka NewTransactionNotification) no silent notification Information that a new transaction was received
AccessWrongNotification no user notification Notification that the access credentials have changed and it is necessary to update them in AHOI
AccessLockedNotification no user notification Notification that the access has been locked after too many failed authentication attempts
NewTurnoverPatternNotification no user notification Notification that a new pattern has been discovered by AHOI

Google Cloud Messaging

GCM: DailySummaryNotification

    "msgType" : "DailySummaryNotification",
    "title" : "Das Girokonto",
    "body" : "0 neue Umsätze. Aktueller Kontostand: -47.794,76 € Offene Ausgaben: 0,00 €",
    "account" : "a01e7861-03ff-4511-b8ef-dbd7bf7581bf"

GCM: AccessLockedNotification

    "msgType" : "AccessLockedNotification",
    "title" : "Gesperrte Zugangsdaten",
    "body" : "Ihre Zugangsdaten zu {0} sind möglicherweise gesperrt. ...",
    "access" : "6743c69b-d9d7-4b49-a476-562cc5f8c72c"

Notifications for ANDROID notification targets are sent as silent messages that you need to process and display to the user. This is necessary because standard notification handling would only show partial messages owing to length constraints.

The delivered format is defined as shown below:

Please refer to the GCM documentation on how to implement a client.

The following notification definitions exist for GCM:

Notification Configurable Type Description
DailySummaryNotification yes user notification Information about the current account status, individual per account
BudgetChangeNotification yes user notification Notification that the calculated budget has crossed the configured threshold
BalanceChangeNotification yes user notification Notification that the account balance has crossed the configured threshold
NewTurnoverNotification (aka NewTransactionNotification) yes user notification Notification that a new transaction was received
NewTurnoverNotification (aka NewTransactionNotification) no silent notification Information that a new transaction was received
AccessWrongNotification no user notification Notification that the access credentials have changed and it is necessary to update them in AHOI
AccessLockedNotification no user notification Notification that the access has been locked after too many failed authentication attempts
NewTurnoverPatternNotification no user notification Notification that a new pattern has been discovered by AHOI

12. Delete an Access from AHOI

To have data removed from AHOI, the Access simply needs to be deleted. To do so, an HTTP delete request to the accesses resource with the access ID is sufficient: DELETE <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c.

All AHOI data related to the access is removed in the process.

13. Delete a User Registration from AHOI

To delete a user registration send your banking token with a DELETE <HOST>/ahoi/api/v2/registration request. This also deletes all data stored with this registration. This means if you try further requests you will receive a http status 403 Permission denied. You will also no longer be able to retrieve a banking token with our authorization service.

You can however still request a new registration to continue your work.

HTTP Requests

Here are some basic guidelines for using HTTP requests with AHOI.


Within our domain we use Base64URL encoding, which differs from Base64 encoding in omitting the = padding and replacing the characters + with - and / with _.

Media Types

Requests that carry a JSON document in the request body need to set the Content-Type: application/json header field. AHOI will also set this header field if it returns a JSON document in the response body.

At the moment, all resources will be returned in JSON format. XML format is currently not supported.

Error Messages

  "qualifier": "ERROR",
  "message": "No account found with id edc4c059-e9e6-4788-8334-fa1eef29e85d."

Error messages all have a similar structure. They provide three kinds of information:

The message part is supposed to be presented to the end user.

HTTP Methods

In general, AHOI uses the four most common HTTP methods—POST, GET, PUT and DELETE—for creating, retrieving, updating and deleting resources.

In addition, the available methods for an endpoint can be displayed with OPTIONS.

Accessing resources is structured hierarchically

The AHOI API Documentation provides detailed information on what the various REST endpoints for the different resources expect as request parameters, what is returned in response and what kinds of errors might occur.

Retrieving resources with GET

To retrieve resources, GET requests are used. Non-qualified GET requests—for example, GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts—return a JSON document that contains a list of resources in the HTTP response body. If there are no resources to return, an empty list is returned. The HTTP response code in both cases is 200 - OK if the request is processed successfully.

Providing a qualifier (as in GET <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf) retrieves a single resource with the given ID a01e7861-03ff-4511-b8ef-dbd7bf7581bf. The HTTP response code is 200 and the response body contains the JSON representation of the resource.

Creating resources with POST

To create a resource, a POST request is sent. The request body contains the JSON representation of the resource to be created. If the resource is created successfully, an HTTP response code 201 - Created is returned, and the response body contains a JSON representation of the newly created resource. Also, two header fields are set in the response: X-Id contains the ID of the newly created resource and Location points to an endpoint where the resource can be retrieved.

IDs for resources are created by AHOI. If you provide an ID for a resource when trying to create it, the process is aborted and AHOI will return an error.

Updating resources with PUT

To modify resources, PUT requests are used. The request body contains the JSON representation of the resource to modify. If the resource is modified successfully, an HTTP response code 200 - OK is returned, and the response body contains the JSON representation of the updated resource.

When updating a resource, the ID of the resource has to be provided as a path parameter in the URL. Also, the ID must be set in the JSON document in the request body and must match the URL parameter.

There is no mass update in AHOI.

For some common modifications there are shortcuts or convenience methods. In these cases, the part of the resource to be modified is provided as a path parameter and no JSON document in the request body is required. For example, PUT <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf/transactionpatterns/06afadc5-5732-4e5f-af37-cc940126c062/active/true modifies the active field of a specified transaction pattern and account. In return, AHOI answers by sending a JSON document of the modified resource in the response body — just like the above example.

Removing resources with DELETE

Resources are removed by issuing DELETE requests. The resource type and ID are identified using the request path (e.g., DELETE <HOST>/ahoi/api/v2/accesses/6743c69b-d9d7-4b49-a476-562cc5f8c72c/accounts/a01e7861-03ff-4511-b8ef-dbd7bf7581bf). In the event that the resource has been successfully deleted, an HTTP response code 204 - No Content is returned. The response body is empty.

There is no mass delete in AHOI. However, if you remove an access, for example, its entire existence along with all connected accounts, transactions and so forth are deleted.

HTTP Return Codes

Code Meaning
200 OK – Returned if a GET request was issued. The response body contains the data.
201 Created – Returned if a resource has been created with a POST request. The response body contains a representation of the resource. The header fields X-Id and Location will be set.
204 No Content – The request was carried out, but there is no content to display — for example, if a resource has been removed via a DELETE request.
400 Bad Request – There is something wrong with the request (e.g., parameters are missing or formatted incorrectly).
403 Forbidden – If you try to access a resource you are not entitled to. As a basic troubleshooting step, check your credentials. Maybe you haven't been authorized (yet)?
404 Not Found – Returned if the requested resource was not found.
405 Method Not Allowed – Returned if an endpoint is accessed with an HTTP method that is not permitted.
409 Conflict – This code is returned if there is some sort of resource conflict.
500 Internal Server Error – Something went wrong with the server.
503 Service Unavailable – Maintenance mode active. We need to feed our hamster.

Authentication via OAuth2

As described above, AHOI uses the open OAuth2.0 protocol for any authentication with the API. The grant type client credentials is used.

The AHOI authorization server is capable of providing two different kinds of JSON web tokens (JWT):

Without sending a token, AHOI will return an error message. A registration token enables a client to register a user. Further endpoints are inaccessible. With a banking token, all endpoints can be used except for registration.

In the following, the procedure for retrieving a token from the authorization server and forwarding the token to AHOI are described.

Obtain a Registration Token

    "access_token": "eyJhbGciOi ... JRt2ywq40",
    "expires_in": 359,
    "jti": "78164f88-6d97-4825-b626-2e235471397b",
    "scope": "ANON",
    "token_type": "bearer"

Retrieving a registration token follows the client credentials flow. The token is requested using a HTTP POST request to the URL https://<HOST>/auth/v1/oauth/token?grant_type=client_credentials.

Additionally, a basic authentication is employed: A header field called Authorization needs to be set. The header value consists of the constant Basic followed by a space character and the Base64-encoded clientId and clientSecret separated by a colon.

Authorization: Basic Base64{clientId:clientSecret}

The clientId and the clientSecret will be provided to you when you register for an AHOI Sandbox account. They have to be treated confidentially by you and your application.

The server returns a JSON document, which contains the JWT (access_token) and the time for how long the token will be valid in seconds (expires_in).

If the registration token expires before the registration is completed, the client needs to request another token.

Obtain a Banking Token

  "installationId":"247ac36e97cb45b ... e97cb45276c",
  "nonce":"e5028e4b- ... -9fde986dff9c",
X-Authorization-Ahoi: Base64URL{ jsonDocument }

To obtain a banking token, be sure to have all your service-specific credentials available. You can find them in the Sandbox Manager.

Retrieving the token follows the scheme for obtaining a registration token. However, another header field needs to be set.

The name of the header field is X-Authorization-Ahoi. The value consists of an Base64URL-encoded JSON document of the installationId, a nonce and a timestamp.

The result looks similar to a registration token request.

Extract the Token and Integrate It in the Request

Authorization: Bearer eyJhbGciOi ... JRt2ywq40

Once the JSON document has been retrieved, the token can be extracted from the access_token field. This string is a JWT, which means that it's a base64-encoded JSON document. You can explore it by copying the string into the form at

To use the token, you need to send it with each request to AHOI in an Authorization header field. Its value consists of the keyword Bearer followed by a space character and the access_token.

AHOI Data Types

This section provides a brief overview of the various key components of AHOI. If you're uncertain about what a resource actually represents, please begin by consulting this section.


An access represents a login to an assigned provider (e.g., login credentials for online banking). It includes data such as the username and PIN. Which fields are required will be described in the provider's input field descriptions.

Each access has a validation state that describes the validity of the credentials. This state might change over time if the credentials are no longer valid.


An account is a grouping of financial records (e.g., a bank account). It contains information about the account name, the account holder, the account type as well as related information such as the account number, IBAN or account balance. It is associated with one or more accesses.

An automatic background refresh of transactions can be activated for every account.


A provider represents financial institutions AHOI can connect to (e.g., banks).


A resource in the context of this documentation is used as an abstract designator for access, account, provider and the like.


A transaction represents a financial operation associated with an account. A bank account transaction contains information about the payee and the creditor, the amount, the date on which it was booked, the availability of funds and its purpose. A transaction might also be related to a recurring transaction pattern.


Transaction patterns are the result of analyzing regularly recurring transactions. These patterns can be automatically recognized by AHOI. The recognition process starts after every account refresh and updates the patterns that have already been detected. As this process is not 100% accurate, transaction patterns can be deactivated or created manually by the user. Transaction patterns are used to identify upcoming transactions and to calculate a balance forecast.

Transaction patterns can be configured as monthly, quarterly, semi-annually or annually recurring. To automatically create a transaction pattern there have to be at least three transactions related to that pattern.


The budget represents a balance forecast for the end of the current month, based on the transaction patterns.


Notification targets are a requirement to send notifications. A notification target represents a notification recipient (e.g., a push token for sending push notifications to a mobile app).


A notification alerts the user to certain status updates and changes to the account. Configuring a notification defines rules for an account to trigger an event. If that event is triggered, a notification is sent to the associated notification target (e.g., a push notification is sent).

New Transaction Notification

This notification signals a new transaction for the related account. It can be configured with upper and lower thresholds (e.g., all transactions above 100 euros).

Daily Summary Notification

This notification consists of a summary of all new transactions and the current account balance. The daily summary notification can be configured to be sent on specific days and at specific times.

Budget Notification

This notification refers to changes concerning the lower or upper threshold for a configured budget for the related account.

Balance Change Notification

This notification refers to changes concerning the lower threshold for a configured balance for the related account (e.g., balance below 50 euros).

Enabling Encryption

AHOI may be used without encryption in the Sandbox test environment and in server-to-server communication with a valid client certificate. If AHOI is used in production without a client certificate, sensitive information like the installationId and the bank access credentials must be transmitted in an encrypted format. This is where you can learn how to use this feature.

How to Turn It On

To enable the encryption of sensitive data, you must first activate this option for your service in the Sandbox Manager.

Affected Requests

If encryption is enabled, three communication processes with AHOI are affected:

  1. Retrieving an installationId during user registration
  2. Obtaining a banking token with an installationId
  3. Creating and updating a bank access, which involves transmitting access credentials

There are two different encryption approaches in AHOI depending on the server you are talking to: the AHOI Resource Server (REST API) and the AHOI Authorization Server.

Items 1 and 3 are requests to the Resource Server. For this, a symmetrical one-time key called a sessionKey is generated for each transmission.

When communicating with the Authorization Server (item 2), a hardwired secret is used: the appSecret.

Both procedures are explained below.

Encryption with sessionKey

To exchange encrypted information with the AHOI Resource Server, your service generates a sessionKey and transmits the encrypted key to AHOI. This sessionKey is used as a symmetric key to encrypt and decrypt information.

As this sessionKey is also very sensitive, it is encrypted asymmetrically by a public/privateKey procedure (RSA) and transmitted to AHOI in the HTTP header.

The procedure is as follows:

  1. Generate a sessionKey.

  2. Retrieve a publicKey from AHOI.

  3. Encrypt information with the sessionKey.

  4. Encrypt the sessionKey with the publicKey.

  5. Transmit the encrypted information and encrypted sessionKey to AHOI.

  6. AHOI decrypts the encrypted sessionKey with the privateKey.

  7. AHOI decrypts information with the sessionKey (or encrypts some information for response with the sessionKey).

1. Generate sessionKey

The initialization vector (IV) when using the sessionKey is 16-byte initialized with 0x00 values; the expected algorithm is AES-CBC.

(!) Session keys that we consider insecure will be dismissed by AHOI and you will be requested to generate a new, secure one. (!)

Currently, AHOI allows the following symmetric ciphers for session keys:

Identifier Description
AES AES with 128-bit key length, with a zero IV and no salt.

Zero IV refers to a byte array of size 16 with all bytes set to 0x00.

Please note: Each sessionKey may be used only once. AHOI will reject any request that uses a previously used sessionKey.

2. Retrieve publicKey

    "keyId": "be51b2ab-...-5b2a3564be3e",
    "validUntil": "2017-06-16T07:29:59Z",
    "publicKey": {
        "value": "MIIBIjANBgkqhkiG9w...Cw5L3rdxsXT6cEm",
        "specification": "RSA_2048_SHA1"
    "publicKeySignature": {
        "value": "TBM7FX9oRzRsLr...bWmh+C706NYcpbOwA==",
        "specification": "SHA1_WITH_RSA"

Invoking the GET <HOST>/ahoi/api/v2/registration/keys REST endpoint returns a JSON document with a temporary AHOI public key.

The JSON document returned by the endpoint consists of a keyId, a validUntil time and a publicKey and publicKeySignature, both with corresponding specs.

Identifier Description
RSA_2048_SHA1 RSA private / public key with 2048-bit key length and OAEP padding. (RSA/ECB/OAEPWithSHA-1AndMGF1Padding)
SHA1_WITH_RSA SHA1 signature with RSA private / public key with 2048-bit key length and PKCS1 padding. (SHA1withRSA)

The public key is identified by a keyID. Currently, AHOI generates RSA private / public key pairs with 2048-bit key length and OAEP padding. The cryptographic signature for the generated key enables the client to verify the origin of the public key. The validUntil field specifies the time until the key may be used. After that, AHOI will reject requests that refer to the expired public key.

3. Encrypt sessionKey and integrate it into the request

  "publicKeyId":"ffa91778- ... -d8931ff3ad04",
  "sessionKey":"1748aafa509c ... e47ac2f9473b2eb3d06",
  "keySpecification": "AES"
  "installation": "UW/QJ5ow1N ... L62OTyzDE="

At this point, the client encrypts the generated sessionKey with the public key.

The client then creates a JSON document, as shown on the right. The "publicKeyId" field refers to the keyId. The "sessionKey" field contains the generated, encrypted and Base64URL-encoded sessionKey: (Base64URL{ pubKey{ sessionKey } }). The "keySpecification" needs to be set to the value of the selected cipher in step 2.

This JSON document is then Base64URL-encoded and sent as header field X-Ahoi-Session-Security when making a request with encrypted data.

4. En- or decrypt information with sessionKey

In the case of a user registration, no encrypted information is sent to AHOI along with the sessionKey. Instead, only the key itself is sent to AHOI so that AHOI can encrypt the installationId in the response. Therefore the endpoint GET <HOST>/ahoi/api/v2/registration is invoked as usual, only with the extension of the X-Ahoi-Session-Security field in the header and the encrypted and encoded sessionKey as the value.

The response installationId must then be decoded with Base64URL and decrypted with the sessionKey. The encryption method used depends on the chosen type of the sessionKey (e.g., AES).

When setting up an Access, you have to encrypt the AccessFields (USERNAME and PIN) and encode them in Base64URL as well.

Encryption with appSecret

When a banking token is obtained from the AHOI Authorization Server, your service has to provide the installationId. As described in Obtain a Banking Token, a JSON document is created with the trio of installationId, nonce and timestamp.

This JSON document must now be AES encrypted. For encryption, use AES in cipher block chaining (CBC) mode with PKCS5 padding with the appSecretKey and appSecretIV as the initialization vector.



Which banks are currently supported on the sandbox system?

Right now, you can only use the AHOI Sandbank.

Why can I only use "AHOI Sandbank" on the sandbox system?

In order to give access to real bank accounts a registration with the BaFin is necessary. Our registration is not yet complete, but we expect it in 2018.

Which banks does AHOI basically support?

Currently AHOI supports all banks that offer FinTS with PIN and TAN. These are essentially: Sparkassen, Volksbanks and Raiffeisenbanks as well as most private banks, with the exception of Commerzbank, for example.

Which banks will AHOI connect to in the future?

How do I set up a bank access?


My accounts are gone, why?

Why do I always have to re-register with AHOI to see my account?

Oh, you don't have to! When you register, you receive an InstallationID, which you have to save. Next time you come back, you use this InstallionID without re-registration and can access your data again. To manage data for multiple users/installations, you have to create your own mapping of the users/installation to the corresponding InstallationID.

What account types does AHOI support?

AHOI basically supports giro-like and security accounts, both account types are also offered by AHOI Sandbank.

What account types are still planned in AHOI?

Here, too, we are guided by our customers and will implement new types of accounts, given there is a relevant demand for them.


How do I get new transactions from my bank?

You get new transactions from your bank (also from AHOI Sandbank) when you

a) use the max-age_parameter accordingly, i.e. you tell AHOI to refresh transactions of an account if the last refresh was at least max-age seconds ago (see also the tutorial for transactions.

b) have not made any further configuration, AHOI will update the accounts once a day, as long as you have sent any requests during the last 30 days using the InstallationID for which your accounts are stored.

c) have configured Apple or Google Notifications/Push messages for accounts. AHOI can then update your accounts hourly - this depends on the bank used.

Why am I not receiving new transactions on my AHOI Sandbank accounts?

The AHOI Sandbank accounts currently only creates transactions when you register with the sandbox manager. There are no new transactions generated continuously. But you can generate your own transactions:

  1. By creating transfers to these accounts via the AHOI API. For example, if you transfer money from one demo account to another demo account, corresponding transactions are created.

  2. You have the possibility to create transactions directly in the sandbox manager for a demo account.

Payment transactions / bank transfers / direct debits

What kind of payment transactions does AHOI currently support?

AHOI currently does not offer any payment transactions for real accounts. Currently you can only do a bank transfer with our demo accounts for testing and integration purposes. We are working on support for real accounts.

Managing my sandbox manager access

I forgot my password for the sandbox manager, what do I do?

No problem - you can use our "Forgot password" function to reassign a new password in a secure way. You will then receive an e-mail with detailed instructions.

I want to delete / log out / deregister my sandbox access, how can I do this?

We think that's a pity, but it's still very simple. You log in to the sandbox manager and under "Settings" you will find the section "Delete your sandbox access" below.

I want to delete data in my sandbox account without deleting the sandbox account itself - how do I do that?

Just log into the sandbox manager.

a) You can delete a single InstallationID from the overview page at the bottom of the "Delete Installation Data" section.

b) You can delete all InstallationIDs and their associated data for a client ID at once, in the "Delete all Installation data" area on the overview page

Productive use of AHOI

I want to use AHOI in one of my applications, what do I have to do?

You can contact us via, maybe you can already describe your application and the AHOI-features you want to use and also name the initial quantity structure (e.g. number of users, estimated number of updates per day, estimated number of new transactions, etc.), because this will determine the costs.

Can I also use AHOI if I am not/do not have a company regulated by ZAG?

If you only process your own companies account data (e.g. incoming payment check or statistics), we can offer you a solution. Simply contact us at, ideally with your contact details and a short description of what you would like to do, how many bank accounts are affected and how many transactions per day can occur.

Can I as a private person use AHOI for my own application?

In principle you can also use AHOI as a private person, unfortunately currently only with the demo accounts. We are working on making it work with real accounts on the sandbox system again soon.

Engineering / Software Development

Is there a client SDK for AHOI?

We can currently offer SDKs for Java, JavaScript and PHP. However, we give no guarantee for these clients. The clients should help you to build your applications in a simple way. Just contact us at

Do I have a way to generate an AHOI client?

Yes, you can generate a client via our swagger file, but you will have to do it yourself.

Will you also offer Server-to-Server Notifications / Web-Hooks?

Yes we plan a server to server / webhook notification. Unfortunately we can't name an availability date yet.


Why does AHOI store my bank access credentials?

AHOI frequently attempts to refresh your accounts, for one to provide you with up to date information and also to inform you via notifications about new events such as transactions. If we would have to request your credentials every time this unattended approach would not be possible.

Why has the AHOI client to encrypt certain data? Why is transport encryption via TLS not sufficient?

Mobile devices in particular are often on the move in insecure networks, where communication can be spied on. To avoid this, certain data has to be encrypted.

Are there any security requirements for clients that I want to provide to my customers?

Yes, we have security requirements for clients using the AHOI-API. However, these requirements only apply once the application goes live with your customers. On request, we pass on the "Security Standard for AHOI Clients" prior to the conclusion of the contract.

How is the encrypted JSON data encoded?

The encrypted JSON data must be serialized via Base64URL encoding (without padding) (see also the chapter on encryption)

How can I tell AHOI to work with or without application-side encryption?

In the context of the sandbox you can turn this on or off in the sandbox manager via "Advanced Encryption". In the productive context this is configured by us for you (see also the first two questions in security).

Contact Us

Do you need help? Is anything unclear? We're more than happy to help. Just send us an e-mail:

We also welcome your feedback on our documentation.