Web Form 2.0 Java SDK usage

Installation

Please first download a Web Form 2.0 Java SDK by following the description in /wiki/spaces/AAPD/pages/3224272928 and choosing “java” as the target language.

A standalone Java project is generated that can be built with either Gradle or Maven. You may either build the project and include the created jar file as a dependency in your application, or directly copy out the generated code into your application.

Overview

The src/main/java folder contains the SDK classes. The app subpackage contains API classes to call API service methods. For each section of the Web Form 2.0 API (see the left sidebar of the Web Form 2.0 API documentation), a distinct API class is available. The model package contains the API request and response model classes.

The src/test/java folder is not required to run the SDK, but the pre-generated tests are helpful to checkout API usage, as they contain example calls of all API services.

The easiest way to run a service is to just instantiate the API class and execute the desired service method, e.g.:

new AccountInformationServicesApi().createForBankConnectionImport(<parameters>);

In this case, the API class uses a pre-configured global configuration. You can change the configuration settings globally by calling the setter methods of Configuration.getDefaultApiClient(). This configuration will by default use https://webform-sandbox.finapi.io as the API base path, so you need your sandbox client credentials to run the following examples.

To find out which parameters you have to provide for a service call, just navigate to the method implementation in your IDE, e.g. to AccountInformationServicesApi.createForBankConnectionImport. Each method contains an extensive Javadoc comment with the same information as on our API documentation page. The same applies to the model classes.

Usage Examples

Authorization and Creation of a User Identity

The Web Form 2.0 API services require a user access token to be provided. Authorization and user creation are not part of the Web Form 2.0 API but require the Access API. So you need to download the Access SDK as described in Using a generated Access SDK and additionally integrate it into your application.

The https://finapi.jira.com/wiki/spaces/AAPD/pages/3226828807/Access+Java+SDK+usage#Authorization-and-Creation-of-a-User-Identity section described the necessary Java calls to create a user and retrieve a user token.

Note: The following usage examples assume that you retrieved a user token via the Access API first and registered it globally within the Web Form 2.0 SDK:

// Call Access API to retrieve user token
AccessToken userToken = authorizationApi.getToken(...);

Configuration.getDefaultApiClient().setAccessToken(userToken.getAccessToken());

Import a new Bank Connection

This section shows how the API calls described in /wiki/spaces/AAPD/pages/2755395613 can be executed via Java SDK.

Step 1 - Request to generate a web form to import a bank connection

In the easiest case, the service can be called without any arguments. The created web form will then ask the user to first select the bank to be imported. The service returns a web form resource containing the web form URL to be opened.

AccountInformationServicesApi accountInformationServicesApi = new AccountInformationServicesApi();
WebForm webForm = accountInformationServicesApi.createForBankConnectionImport(new BankConnectionImportDetails());

The BankConnectionImportDetails class supports many parameters to control the web form flow behavior.
E.g. If the bank to be imported is already known, you can provide it as a service parameter, either the bank id or a search string, so the created web form won’t ask the user to select a bank.
The following example provides the id of the finAPI demo bank:

AccountInformationServicesApi accountInformationServicesApi = new AccountInformationServicesApi();
BankConnectionImportDetails bankConnectionImportDetails =
    new BankConnectionImportDetails().bank(new ImportBankDetails().id(280001L));
WebForm webForm = accountInformationServicesApi.createForBankConnectionImport(bankConnectionImportDetails);

Step 2 - Ask the user to log in at the bank and authorize access

As a result of step 1, a web form is generated. Use webForm.getUrl() to present the web form to the user to authorize access (login at the bank and complete the second-factor authentication procedure).

No Web Form 2.0 API call is required in this step.

Step 3 - Check the status of the Web Form

As no callback was registered during step 1 (which would have directly informed you about web form completion, including the status), you need to poll the “Get a web form” service unless it returns a final status. The id of the web form created in step 1 must be given as the parameter:

AccountInformationServicesApi accountInformationServicesApi = new AccountInformationServicesApi();
WebForm updatedWebForm = new WebFormsApi().getWebForm(webForm.getId());

// TODO react on updatedWebForm.getStatus()

Step 4 - Check the status of the bank connection

If the web form is finished successfully, the bank connection may still be in the process of downloading accounts and transactions in the background (please check /wiki/spaces/AAPD/pages/2766405656 for details). So before you can access accounts and transactions, you need to wait until the update status is READY. Use the getBankConnection service for this and provide the bankConnectionId returned in step 3 as the parameter:

if (updatedWebForm.getStatus() == COMPLETED) {
    BankConnectionsApi bankConnectionsApi = new BankConnectionsApi();
    BankConnection bankConnection = bankConnectionsApi.getBankConnection(
        updatedWebForm.getPayload().getBankConnectionId(), null);

    // TODO check bankConnection.getUpdateStatus() until 'READY'
}

Step 5 - Get Accounts and Transactions

Accounts and transactions are available through the Access API. Please refer to https://finapi.jira.com/wiki/spaces/AAPD/pages/3226828807/Access+Java+SDK+usage#Get-Accounts-and-Transactions for SDK usage examples.

Advanced topics

Please also refer to https://finapi.jira.com/wiki/spaces/AAPD/pages/3226828807/Access+Java+SDK+usage#Advanced-topics for further topics that partially also apply to the Web Form 2.0 API.

Configure the API basepath

If you instantiate an API class with the default constructor as shown in the examples, the call will be executed against the finAPI Web Form 2.0 sandbox (https://webform-sandbox.finapi.io). This is correct when you start adopting the API, but to switch to our production environment, you need to override the URL to https://webform-live.finapi.io.

The simplest option is to override the URL in the default API client:

Configuration.getDefaultApiClient().setBasePath("https://webform-live.finapi.io");

Provide a request id

For each Web Form 2.0 API request, you should provide a unique X-Request-Id header on each request as described in the General information section of the API documentation.

As the request id cannot be provided as a parameter to the SDK methods, it must be added at a central place. One approach could be to intercept request handling on the OkHttpClient level:

OkHttpClient httpClient = new OkHttpClient.Builder().addInterceptor(chain ->
    chain.proceed(chain.request().newBuilder()
        .addHeader("X-Request-Id", requestId())
        .build())).build();
Configuration.getDefaultApiClient().setHttpClient(httpClient);

A simple approach to generate the request id is to use a UUID:

private String requestId() {
    return UUID.randomUUID().toString();
}