Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 2 Next »

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.

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 this, the generator runs with 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, however, may need to be adapted.

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

The following examples are reduced to the necessary minimum, to help you get easily started with the SDK. However, for a productive application more topics are to be considered, please refer to the Advanced topics !!!!!!!!!!!!!!! link 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 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.

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());

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

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 status of the bank connection can be checked, which is done with the Access API. Use 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()
}

Please beware that it takes some time to download the accounts and transactions from the bank. For more details, please check /wiki/spaces/AAPD/pages/2766405656.

Step 5 - Get Accounts and Transactions

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

public String requestId() {
    return UUID.ToString();
}

  • No labels