NAV
JSON HTTP

Welcome to AHOI!

Here you will find details and documentation about the multi-bank API of the German Savings Banks Finance Group (Sparkassen Finanzgruppe).

The basis for this services is AHOI*, our managed and flexible banking API designed to offer easy access to a user’s bank accounts. Actions like retrieving user transactions, analyzing and aggregating transactions, generating balance forecasts, and notifying a user about account activity are simplified. This is achieved by hiding complex banking APIs, supporting most German banks and implementing high security and regulatory standards.

If you want to access and use the API applications will have to register with us beforehand. We will then provide support and consulting in return for a usage fee.

We are planning to constantly develop and enhance AHOI with functionalities that are required by our partners.

At the moment, the whole extent of changes that will be caused by the revised Directive on Payment Services (PSD2) is unclear. However we will adopt our API to PSD2.

Talk to us about your ideas and we will do our best to support you! ahoi-api@starfinanz.de

This documentation provides an overview of what you can do with our API and how you can use it. For more detailed information, please refer to our AHOI API Documentation.

Conventions and Paradigms

We are aiming for consistent behavior of the AHOI API so you can expect AHOI to act the same way when accessing different resources — starting, naturally, with the use of HTTP methods for CRUD (create, retrieve, update and delete) and extending to the kinds of responses that are received. This will foster usability and help you to get acquainted with the API quickly.

Encoding

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

Encryption

This far we have three means to secure your data when transferring them to our domain: * AppSecret * SessionKey * PublicKey

They will be detailled in the specific sub-chapters.

AppSecret

The AppSecret credentials consists of Application Secret Initializiation Vector (AppSecretIv) and Application Secret Key (AppSecretKey). This is used to transfer your installation ID to the authorization server (see Retrieving an Enhanced Token). The expected encryption algorithm is AES-CBC.

SessionKey

The SessionKey is an encryption measure to allow secure data transfer between you and AHOI. You generate a random SessionKey and provide it when retrieving or submitting sensitive information to AHOI (see Registration Process and Accessing the bank through AHOI). The IV when using the SessionKey is 16 byte initialized with 0x00 values the expected algorithm is AES-CBC. You can use the session key as long as your OAuth2 Token is valid then please generate a new one.

(!) SessionKeys we regard as unsafe will be dismissed by AHOI and you will be requested to generate a new, safe one. (!)

PublicKey

The PublicKey is used to encrypt the SessionKey (see Step 4: Call the registration endpoint). The expected encryption algorithm is RSA_2048_SHA1.

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",
  "code": "VALIDATION_FAILED",
  "message": "No account found with id 9999."
}

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

The message part is aimed 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.

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 responses and what kinds of errors may occur.

Retrieving resources with GET

To retrieve resources, GET requests are used. Non qualified GET requests – for example GET <HOST>/ahoi/api/v2/accesses/1/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 (like in GET <HOST>/ahoi/api/v2/accesses/1/accounts/123) retrieves a single resource with the given ID 123. 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, usually the ID of the resource has to be provided as a path parameter in the URL. Also, the ID may be set in the JSON document in the request body. Since IDs cannot be changed, the ID provided in the URL has precedence over the one in the request body.

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/1/accounts/123/transactionpatterns/8787/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/1/accounts/999). 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, deletes cascade: If you remove an access, for example, its entire existence along with all connected accounts, transactions and so forth is deleted.

Authentication via OAuth2

For authentication and authorization OAuth2 with client credentials grant type is used. The AHOI authorization server is capable of providing two different kinds of JSON web tokens (JWT):

Without a token, AHOI will return an error message. A standard token enables a client to register a user. Further endpoints cannot be accessed. With an enhanced token, all (enabled) enpoints can be used.

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

Retrieving a Standard Token

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

Retrieving a standard token follows the client credentials flow. The token is requested using a HTTP POST request to the URL https://<HOST>/auth/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 client secret, separated by colon: HTTP 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 the application.

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

Once the token runs out, the client needs to request another token.

Retrieving an Enhanced Token

{
  "installationId":"247ac36e97cb45b ... e97cb45276c",
  "nonce":"e5028e4b- ... -9fde986dff9c",
  "timestamp":"2017-06-07T10:32:05.123Z"
}
X-Authorization-Ahoi: Base64URL{ AES_AppSecret{ jsonDocument }}

Retrieving an enhanced token follows the scheme for getting a standard 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, AES encrypted JSON document of the installationId, a nonce and a timestamp.

For encryption, the client uses AES in cipher block chaining (CBC) mode, with PKCS5 padding with the App Secret key and initialization vector as provided during your registration.

The result looks similar to the request of a standard token.

Forwarding the Token to AHOI

Authorization: Bearer eyJhbGciOi ... JRt2ywq40

Once a JSON document, as shown by the example Retrieving a Standard Token has been retrieved, the token can be extracted from the field access_token (when retrieving an enhanced token, the same JSON document structure is shown). This string is a JSON web token (JWT), which means, it is a base64 encoded JSON document itself. You can explore it, if you copy the string into the formular at https://jwt.io.

In order 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.

Registration Process

In order to be able to use AHOI, a registration process for each user needs to be carried out. During this process, a user specific installation ID is created. This installation ID is mapped to AHOIs internal user context.

The following chapter describes, how the registration process needs to be completed.

Step 1: Getting a Standard Token

Retrieving a Standard Token is easy, it is described in the Retrieving a Standard Token.

Obviously, the retrieved token needs to be sent to AHOI in each of the following requests, as described here: Forwarding the Token to AHOI

Step 2: Retrieving a temporary public key

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

Calling 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 spec.

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

The public key is identified by a key ID. During the registration process and later on (when protecting confidential information) the public key is used to encrypt a temporary, client generated, symmetric session key. AHOI uses the key ID to select the matching private key and decrypt the session key.

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 which refer to the expired public key.

Step 3: Create a Session Key

To protect information in transit, the client generates a session key. At the moment, AHOI allows the following symmetric ciphers for session keys:

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

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

Please note: Each session key may be used once. AHOI will reject any request, which uses a previously used session key.

Step 4: Call the registration endpoint

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

Now, the client encrypts the generated Session Key from step 3 with the public key retrieved in step 2.

The client then creates a JSON document, as shown below. The publicKeyId refers to the keyId of the response of step 2. sessionKey contains the generated, encrypted and Base64URL encoded, session key (Base64URL{ pubKey{ sessionKey } }). The keySpecification needs to be set to the value of the cipher selected in step 3.

This JSON document is then Base64URL encoded and sent as header field X-Ahoi-Session-Security when making a GET <HOST>/ahoi/api/v2/registration.

AHOI will return a JSON document containing the installation ID. The installation ID is encrypted using your provided session key and needs to be decoded before passing on to the authorization server.

Step 5: Securly store the installation ID

The installation ID is private information and needs protection.

It identifies a user context, thus, it must be stored safely and securely in your application. Also, it must never be passed unprotected.

When Retrieving an Enhanced Token it is encrypted using the App Secret. This is the only case, in which you need to transmit the installation ID to AHOI.

Tutorial

This tutorial helps you through the AHOI API by following an example user experience. It describes how to look for supported bank providers, set up an access to a bank account, retrieve transactions for the bank account and register notifications for changes to that account.

While this tutorial is not meant to be complete in the sense that all resources are shown in their entirety and all operations are invoked, it does provide an understanding of what steps are important and required to get going.

From this point on, the AHOI API Documentation will help you dig into the details.

The diagram below provides an overview of how the different resources are interconnected. It shows the relations between the different resources. Use it as a guideline, if you want to find out, how to find a resource. diagram and relation of DTOs

AHOI is a managed API, consequently, all of its REST endpoints are access restricted and protected via OAuth2 JWT. In Authentication via OAuth2, it is described how to retrieve tokens from AHOIs authorization server and use them with the AHOI API.

Checking whether a bank is supported

[
{
  "type": "BankProvider",
  "id": 4158,
  "name": "Sandbox",
  "location": "Hamburg",
  "accessDescription": {
    "infoText": "Geben Sie bitte unter Benutzerkennung Ihre Kontonummer ein.",
    "fieldDescriptions": [
      {
        "id": "USERNAME",
        "label": "Benutzerkennung",
        "masked": false,
        "format": "DEFINITELYALPHANUMERIC",
        "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 a (bank) account, you first need to check whether the provider (i.e., the bank) is supported and how AHOI needs to access it. AHOI’s provider REST endpoint provides precisely 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. Or, if you know the provider ID, query the provider resource directly: GET <HOST>/ahoi/api/v2/providers/4158.

In the two latter GET requests, 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 in order 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, it would be called “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.

Apart from those two fields, the type and id are required, for setup and access.

Accessing the bank through AHOI

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

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

{
  "type": "BankAccess",
  "providerId": "4158",
  "accessFields": {
    "PIN": "Base64URL{ sessionKey{ PIN } }",
    "USERNAME": "Base64URL{ sessionKey{ USERNAME } }"
  }
}

{
  "type": "BankAccess",
  "id": 69,
  "providerId": 4158,
  "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. Obviously, these two fields carry sensitive information and deserve special protection. For protection, the same measures as during the registration process are used. As in Retrieving a temporary public key the client needs to get the current public key and Create a Session Key. Similarly, as in Call the registration endpoint, the client then encrypts the session-key and embeds it in a JSON document, which is then sent in the X-Ahoi-Session-Security header field. The session key is used to encrypt the PIN and USERNAME. After encryption, both fields have to be Base64URL encoded. Finally, a POST /ahoi/api/v2/accesses request is sent.

If everything worked fine, 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/69) as well as its ID (e.g. X-Id: 69).

Please note: For obvious reasons, masked fields are not returned by AHOI.

In the background, AHOI checks for bank accounts and transactions associated with the access. Sending a GET <HOST>/ahoi/api/v2/accesses/69/accounts request returns all accounts for the access with ID 69.

The accounts REST endpoint allows to interact with accounts in a more general manner, e.g. GET <HOST>/ahoi/api/v2/accesses/1/accounts returns all accounts (for all accesses). GET <HOST>/ahoi/api/v2/accesses/1/accounts/69 returns the account with the ID 69. Getting all transactions for an account is done issuing GET <HOST>/ahoi/api/v2/accesses/1/accounts/69/transactions.

AHOI automatically refreshes transactions for an account. By default, AHOI refreshes transactions on a daily basis. Transactions will be refreshed hourly if notifications (BalanceNotification, BudgetNotification or TransactionNotification) are being setup. After a certain time (default 90 days) of inactivity the data will be automatically deleted.

Retrieving transactions

[
  {
    "type": "GiroTransaction",
    "transactionPatternId": 222,
    "id": 69,
    "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 the most cases a GET <HOST>/ahoi/api/v2/accesses/1/accounts/99999/transactions is sufficient. A useful parameter for this GET request is max-age, which specifies the maximum acceptable timeframe since the last refresh of the given account. The granularity for this parameter is seconds. So, if you set max-age to 1, you force the account to be refreshed immediately.

Transaction patterns and forecast

[
  {
    "id": 223,
    "state": "ACTIVE",
    "cycle": "MONTHLY",
    "origin": "FINDER",
    "day": 13,
    "relatedAccountOwner": "Symbioticon-Team15",
    "amount": {
      "value": 3797,
      "currency": "EUR"
    },
    "accountNumber": "DE00999940000894952507",
    "bankCode": "TESTBIC",
    "kind": "SEPA-DAUERAUFTRAG"
  }
]

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 for the estimation of a monthly budget.

First, check which patterns AHOI discovered on its own via GET <HOST>/ahoi/api/v2/accesses/1/accounts/999/transactionpatterns. If these transaction patterns were not detected correctly or shall be irrelevant for the forecast, they can be disabled easily: PUT <HOST>/ahoi/api/v2/accesses/1/accounts/999/transactionpatterns/9999/active/false, where 9999 in this case is the ID of the transaction pattern.

Once the transaction patterns are adjusted, the request GET <HOST>/ahoi/api/v2/accesses/1/accounts/999/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/1/accounts/999/forecast/transactions returns the same balance forecast including the expected transactions up to the end of the month.

Making money transfers

Tan-Schemes

[
  {
    "name": "SMSTAN",
    "tanMediaList": [
      {
        "id": 1,
        "name": "smsTAN",
        "description": "Privattelefon ******3020"
      },
      {
        "id": 2,
        "name": "smsTAN",
        "description": "Privattelefon ******1456"
      }
    ]
  }
]

Transfer Order

POST /ahoi/api/v2/accesses/1/accounts/47/transfer HTTP/1.1
Host: banking-sandbox.starfinanz.de
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": "SMSTAN",
    "tanMediaId": 2
}

{
  "transferTaskId": 4,
  "fieldDescriptions": [
    {
      "id": "TAN",
      "label": "TAN",
      "masked": true,
      "format": "DEFINITELYNUMERIC",
      "lengthMin": 6,
      "lengthMax": 6
    }
  ],
  "challenge": "Bitte geben Sie die TAN ein!",
  "responseObjects": {
    "TAN": ""
  }
}

Authorization

POST /ahoi/api/v2/accesses/1/accounts/59/transfers/4/authorize HTTP/1.1
Host: banking-sandbox.starfinanz.de
Authorization: Bearer eyJhbGciOi ... JRt2ywq40
Content-Type: application/json
Cache-Control: no-cache

{
    "responseObjects": {
        "TAN": "111111"
    }
}
{
 "state": "FINISHED",
 "transferTaskId": 4
}

Transferring money is a three-step process:

  1. get supported tan-schemes
  2. post an order to transfer money
  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/18/tanschemes, where 18 is the ID of the access. You need to provide the name of the tan-scheme and the id of the tan-media (SMSTAN and 2 in this example).

In the second step, the order to transfer money is created. It contains the information to whom and how much money shall 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 holds the transferTaskId field, which is 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.

Getting notified of changes

POST /ahoi/api/v2/notificationtargets HTTP/1.1
Host: banking-sandbox.starfinanz.de
Authorization: Bearer eyJhbGciOi ... JRt2ywq40
Accept: application/json
Content-Type: application/json
Cache-Control: no-cache

{
  "appToken" : "***appToken***",
  "operatingSystem" : "IOS",
  "productId" : "***productId***"
}
POST /ahoi/api/v2/notificationtargets/59/notifications/balancechangenotification HTTP/1.1
Host: banking-sandbox.starfinanz.de
Authorization: Bearer eyJhbGciOi ... JRt2ywq40
Accept: application/json
Content-Type: application/json
Cache-Control: no-cache

{
  "type" : "BalanceChangeNotification",
  "accountId" : "9999"
}

AHOI is capable of sending different kinds of push notifications to iOS and Android devices. The underlying services for notifications are Apple Push Notification service (APNs) and Google Cloud Messaging (GCM). If you want 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.

2 new transactions since last status.
Current values for this month
balance: 210,23€
outstanding payments: -42,23€

To do so, a notification target, that represents the device, needs to be set up. It includes a productId which identifies an app. Use “sandbox-app” for testing purposes, to receive real on devices please contact us and include the credentials and application id for the service of your choice. The upper 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 sent consist of a title and message e.g. the title “AHOI” and the message body:

Apple Push Notification service

Apple: DailySummaryNotification

{
    "msgType" : "DailySummaryNotification",
    "account" : 12010,
    "aps" : {
        "alert" : {
            "body" : "169 neue Umsätze seit letztem Status. Aktueller Kontostand: 11,29 \u20ac Offene Ausgaben: 0,00 \u20ac",
            "title" : "Das Girokonto"
        }
    }
}

Apple: BudgetChangeNotification

{
    "msgType" : "BudgetChangeNotification",
    "aps" : {
        "alert" : {
            "body" : "Kontostand unter {0}.",
            "title" : "Das Girokonto"
        }
    }
}

Apple: BalanceChangeNotification

{
    "msgType" : "BalanceChangeNotification",
    "aps" : {
        "alert" : {
            "body" : "Budget unter {0}.",
            "title" : "Das Girokonto"
        }
    }
}

Apple: NewTurnoverNotification (NewTransactionNotification)

{
    "msgType" : "NewTurnoverNotification",
    "aps" : {
        "alert" : {
            "body" : "Aldi 12,34",
            "title" : "Das Girokonto"
        }
    }
}

Apple: NewTurnoverNotification (silent, NewTransactionNotification)

{
    "msgType" : "NewTurnoverNotification",
    "account" : 12007,
    "aps" : {
        "content-available" : 1
    }
}

Apple: AccessWrongNotification

{
    "msgType" : "AccessWrongNotification",
    "access" : 1007,
    "aps" : {
        "alert" : {
            "body" : "Ihre Zugangsdaten zu {0} sind nicht korrekt. ...",
            "title" : "Zugangsdaten fehlerhaft"
        }
    }
}

Apple: AccessLockedNotification

{
    "msgType" : "AccessLockedNotification",
    "access" : 1007,
    "aps" : {
        "alert" : {
            "body" : "Ihre Zugangsdaten zu {0} sind möglicherweise gesperrt. ...",
            "title" : "Gesperrte Zugangsdaten"
        }
    }
}

Apple: NewTurnoverPatternNotification (NewTransactionPatternNotification)

{
    "msgType" : "NewTurnoverPatternNotification",
    "aps" : {
        "alert" : {
            "body" : "Neuer regelmäßiger Umsatz zu {0} erkannt.",
            "title" : "Das Girokonto"
        }
    }
}

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

The following notification definition 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" : 12010
}

GCM: BudgetChangeNotification

{
    "msgType" : "BudgetChangeNotification",
    "title" : "Das Girokonto",
    "body" : "Kontostand unter {0}."
}

GCM: BalanceChangeNotification

{
    "msgType" : "BalanceChangeNotification",
    "title" : "Das Girokonto",
    "body" : "Budget unter {0}"
}

GCM: NewTurnoverNotification (NewTransactionNotification)

{
    "msgType" : "NewTurnoverNotification",
    "title" : "Das Girokonto",
    "body" : "Aldi 12,34"
}

GCM: NewTurnoverNotification (silent, NewTransactionNotification)

{
    "msgType" : "NewTurnoverNotification",
    "account" : 12007
}

GCM: AccessWrongNotification

{
    "msgType" : "AccessWrongNotification",
    "title" : "Zugangsdaten fehlerhaft",
    "body" : "Ihre Zugangsdaten zu {0} sind nicht korrekt. ...",
    "access" : 1007
}

GCM: AccessLockedNotification

{
    "msgType" : "AccessLockedNotification",
    "title" : "Gesperrte Zugangsdaten",
    "body" : "Ihre Zugangsdaten zu {0} sind möglicherweise gesperrt. ...",
    "access" : 1007
}

GCM: NewTurnoverPatternNotification (NewTransactionPatternNotification)

{
    "msgType" : "NewTurnoverPatternNotification",
    "title" : "Das Girokonto",
    "body" : "Neuer regelmäßiger Umsatz zu {0} erkannt."
}

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 due to length constraints.

The delivered format is defined as displayed below:

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

The following notification definition 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

Cleaning up

To have data removed from AHOI, the access simply needs to be deleted. To do so, a HTTP delete request to the accesses resource with the ID of the access is sufficient: DELETE <HOST>/ahoi/api/v2/accesses/999.

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

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.

Glossary

This section provides a short overview of the various key aspects of AHOI. If you are uncertain about what a resource actually represents, please begin by consulting this section.

Access

An access represents a login to an assigned provider (e.g. login credentials to online banking). This includes for example data like username and pin. Which fields are necessary is described in the inputfield descriptions of the provider.

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

Account

An account groups financial records (e.g. a bank account). It holds information about the accountname, the owner, the account type but also type related information, for example account-number, IBAN or balance for bank accounts. It is related to one or more accesses.

For every account the automatic background refresh of transactions can be activated.

Provider

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

Resource

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

Transaction

A transaction represents a financial operation related to an account. A bank account transaction holds information about the debtor and the creditor, the amount, date information about booking and availability and the purpose of it. Additionally a transaction may be related to a recurring transaction pattern.

TransactionPattern

Transaction patterns are the results of regularly recurring transactions. These patterns can be automatically recognized by AHOI. The recognition process starts after every account refresh and updates the already found patterns. Since the process is not 100% accurate, transaction patterns can be deactivated or can be 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 this pattern.

Budget

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

NotificationTarget

Notification targets are an requirement to send notifications. A notification target represents a receiver of notifications to (e.g. a pushtoken for sending push notifications to a mobile app).

Notification

A notification expresses the users interest in certain status updates and changes to the account. It defines rules for an account to trigger an event. If that event fires, 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 bounds (e.g. get notified about all transactions with amounts greater than 100 Euro).

Daily Summary Notification

This notification consists of a summary of all new transactions and the current account balance. The daily summary notification is configured to be send at specific weekdays and time.

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.