Background: this documente guides you through the first steps from user creation to a successful bank connection import.

We strive to provide you with an optimal development experience. As such, we are happy about comments or feedback that help us improving this guide.

Topics:

• User registration

• User login

• Importing your first bank

• Accessing the data you just imported

• Managing bank connections

User registration

To register a new user, use the /v1/signup endpoint. Note that the “email” field may contain an arbitrary hash instead of a valid email as well. This is actually recommended as a best practice for security.

We provide a guide on user management here.

User login

Our API uses the Bearer token standard. To this end, your requests needs the
Authentication Bearer {token} header to perform authenticated requests.

User authentication is done either via username and password or via refresh token. Use the /oauth/access_token endpoint with the respective scope to either login-in or exchange a refresh token for an access token.

Note that both, login and token exchange will require your mandator credentials as a second authentication factor, as specified by the oauth standard - see our API documentation for details. As mandator credentials you have received a clientId (a UUIS) and a client secret (also a UUID).

Note: your mandator also has a publicId for certain use cases in which the ID might be exposed, e.g. during user signup in the frontend. This public ID is not equal to the clientId.

Importing your first bank

Once your user is set up, you may proceed to import your first bank. Once imported, a bank becomes a “bank connection”. A bank connection essentially identifies a certain user / customer a the bank. Each bank connection may hold an arbitrary number of accounts and portfolios.

Find your bank

Use the /v1/banks endpoint to find your bank. Each bank in the returned list of banks contains the attributes

• multibankingApiProvider (currently supported are FIN_API or WEALTH_API)

• bankSlug the unique identifier for the bank

When creating a web-form, these two parameters must be provided.

Creating a web form

Web-forms are created using POST /v2/tppWebForms. Typically you do not want to specify the attribute bankConnectionInterfaceType unless you are certain that you want to import only one selected bank connection interface. If not provided, the web-form will handle the correct choice for you. You will find more information on bank connection interfaces here.

Importing a bank connection using the web-form

The response of your web-form creation request will look somewhat like:

The most important attribute to get started is the startWebFormFlowUrl. Point your browser (or web-view) to the start URL to start the import process. Once the import is completed (or cancelled) the user will be redirected to the redirectUrl.

Note that you may also overwrite the redirectUrl in the fronted by adding the URL as parameter redirectUrl to the start web form flow URL. Note that the URL composed in the parameter must be URL encoded.

So, a web form start URL like that would allow the fronted to dynamically set the redirect URL; e.g. to react to the place from which the web-form was created.

https://wealthapi.eu/.../{token}?redirectUrl={yourUrlEncodedString}

Updating a bank connection using the web-form

We recommend to update bank connections using the web-form flow as well. When updating, you web-form request must contain the bankConnectionId of the bank connection you would like to update.

Accessing the data you just imported

Once the import finished and the user was redirected, you will find the imported portfolios and cash accounts. Use the endpoints

• GET /v1/accounts

• GET /v1/investments

to see what you just got. You may also retrieve the bank connections using

• GET /v1/bankConnections/{id} (FIN_API typed connections)

• GET /api/v3/wealth_api/bank_connections/{id} (WEALTH_API typed connections)

to retrieve the bank connection. The bank connection will contain the import status and eventual import error should they have occurred.

Managing bank connections

There are two main management operations that you probably want to perform on a bank connection. These are to delete stored credentials and to delete the entire bank connection.

Managing bank connection slightly differs for wealthAPI and finAPI connections.

… for wealthAPI connections (Trade Republic, Scalable, …)

Use the endpoints

• DELETE /api/v3/wealth_api/bank_connections/{id}/credentials to delete stored credentials

• DELETE /api/v3/wealth_api/bank_connections/{id} to deletes the entire bank connection

… for finAPI connections (comdirect, ING, …)

Use the endpoints

• DELETE /v1/bankConnections/secrets/{id} to delete stored credentials

• DELETE /v1/bankConnections/{id} to delete the entire bank connection

Getting a bank connection status

A bank connection entity will always contain the connections status. If the last connection attempt failed with an error, then the bank connection will contain error information as well.

Overview of frequently used banks

We provide an overview of frequently used banks and list their respective capabilities and data quality on a dedicated page.