Content Comparison

...

Please first download a Web Form 2.0 Java SDK by following the description instructions as described 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 can 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 check the API usage, as they contain example calls of 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.:

...

In this case, the API class uses a pre-configured 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 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 the all model classes.

Usage Examples

...

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:

...

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

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

...

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 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 ID of the finAPI demo bank:

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

...

As a result of step 1, a web form is generated. Use webForm.getUrl() returned in the first step 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 for 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:

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 completed successfully, the status of the bank connection can be checked, which is done with the Access API. Use the bank connection may still be in the process of categorizing transactions in the background (please check /wiki/spaces/AAPD/pages/2766405656 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:

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

Retrieving accounts Accounts and transactions is done with 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.

...

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

...

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

...

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

publicprivate String requestId() {
    return UUID.randomUUID().ToStringtoString();
}