Web Form 2.0 Java SDK usage

Installation

Please first download a Web Form 2.0 Java SDK by following the instructions as described in Using a generated SDK and choosing “java” as the target language.

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

The code examples in this chapter assume that you used the “Download SDK” button to generate the SDK and chose the V2 API version. By doing so, the generator runs with the default options, using OkHttp as the HTTP client library and GSON as the serialization library.
If you used the finAPI SDK Generator instead to customize SDK generation, you may end up with a different SDK structure and divergent Java code, especially if you change the library parameter. The code examples should still be helpful for you, even though you may need to adjust them.

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 check the API usage, as they contain example calls for 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.:

CODE

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

In this case, the API class uses the default 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’ll 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 all model classes.

Usage Examples

The following examples are reduced to the necessary minimum to help you get easily started with the SDK. However, for a production application, more topics need to be considered. Please refer to the Web Form 2.0 Java SDK usage | Advanced-topics section for this.

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 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:

CODE

// 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 Import a new Bank Connection - with Web Form 2.0 (Recommended option) can be executed via the 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.

CODE

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:

CODE

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 a parameter:

CODE

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 completed successfully, the bank connection may still be in the process of categorizing transactions in the background (please check Post Processing of Bank Account Import/Update for details). This means that if you try to access transactions of the imported bank connection, they will likely have no category assigned. Based on your use case, you can either ignore that fact or wait until the categorization is finished. Use the getBankConnection service for this and provide the bankConnectionId returned in step 3 as the parameter:

CODE

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 Access Java SDK usage | Get-Accounts-and-Transactions for SDK usage examples.

Advanced topics

Please also refer to Access Java SDK usage | Advanced-topics for further topics that also partially 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:

CODE

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:

CODE

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 always having a unique request ID is to use the UUID:

CODE

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