Skip to main content
Skip table of contents

Access V2 migration guide

Overview

The Access V2 API is an evolved version of the Access V1 API. This document covers the differences between both versions and how to upgrade your client to the Access V2 API.

Major changes summary

  • All services, request/response parameters, and headers that are marked as deprecated in V1 have been removed from V2.

  • The old internal Web Form (V1) is no longer supported in Access V2.So if you’re using finAPI’s internal Web Form, you have to migrate to the Web Form 2.0 product before you can use Access V2. For Access V1, the internal Web Form is still available.

  • General improvements and cleanup have been done on the service parameters and responses.

  • The technical and/or semantic details of some fields have changed. The changes are described in detail below.

OpenAPI definition changes

For Access V2, a new OpenAPI definition (“openapi-access-v2.yaml”) is available by selecting “V2 (latest)” in the “API VERSION” combo box of the API Documentation page.

With the Access V2 rollout, the “openapi-access-latest.yaml” file (the one you got previously when “finAPI Access” was selected in the “SELECT PRODUCT” combo box) is no longer available. This was a cleaned-up Access V1 view without deprecated fields and services, which will no longer be available, as the Access V1 API has now been deprecated as a whole.

The full Access V1 API is still available as “openapi-access.yaml”. Previously it was referred to as “finAPI Access (with deprecation)”, now you find it by selecting “V1 deprecated” in the “API VERSION” combo box.

The “openapi-payment.yaml” file is no longer supported. It was shown before when “finAPI Payment” was selected in the “SELECT PRODUCT” combo box, but in fact, it was a payment-filtered view on the Access API. If you have generated a client based on this yaml file, please now use the full “openapi-access.yaml” yaml file instead.

Activate Access V2

As described in Upgrading to a new API version | Switching-between-API-versions, your client configuration is bound to one API version at a time, which is V1 initially.

To update your client configuration to Access V2, please execute the switchApiVersion service and set the apiVersion parameter to V2. After that, you will be able to go back to V1 for 7 days. Now you are ready to use the new API.

API changes summary

To make migration easy for you, the following chapter groups most API changes by feature, so that you can go through the sub-chapters one by one and adjust your client code.

In the following, services are referred to by their “operationId” in the OpenAPI file, not by the service name that is shown in the API documentation. However, both names match closely, e.g. the “Get and search all banks” service has the operationId “getAndSearchAllBanks“.

For changes in service requests and responses, the name of the OpenAPI schema type is used in the text as the reference. You can find these schema-type definitions in the “components/schemas” section of the OpenAPI file.

If you use an OpenAPI-generated API client: Please generate a new client based on “openapi-access-v2.yaml” and update your project with the newly generated sources. Some of the changes described below will not even affect you as they are abstracted by the generated code.
The mentioned operationId’s are usually identical to the service’s method name in the generated client, so should help you to easily find the service calls in your code. Also the mentioned schema type names usually match with the model class names in the generated code.

If you use a self-implemented API client: Please refer to the openapi-access-v2.yaml file to determine the respective service definition by searching for the mentioned operationId resp. schema type name.

For detailed information on the changes to a specific service, you may want to refer to the full API diff in the appendix.

OpenAPI operationId changes

The OpenAPI operationId for the "Delete a consent" service has been changed from deleteAccessData to deleteConsent to better reflect the service name.

Url changes

All services available below /api/v1 for Access V1 are now located below the /api/v2 base path for Access V2.

Additionally, OAuth2 token services have been moved below the base path:

  • getToken: /oauth/token → /api/v2/oauth/token

  • revokeToken: /oauth/revoke → /api/v2/oauth/revoke

If you use an OpenAPI-generated API client: No changes are required to your code.

Null response properties are skipped in the response

Response properties having a null value are no longer returned in the response.

Example
Access V1: getTransaction

JSON 
{
  "id": 6134,
  "parentId": null,
  "accountId": 3,
  "valueDate": "2022-09-05 00:00:00.000",
  "importDate": "2022-09-05 11:12:22.000",
...
  "endToEndReference": null,
  "compensationAmount": null,
  "originalAmount": null,
  "originalCurrency": null,
  "differentDebitor": null,
  "differentCreditor": null
}

Access V2: getTransaction

JSON 
{
  "id": 6134,
  "accountId": 3,
  "valueDate": "2022-09-05",
  "importDate": "2022-09-05T11:12:22.000+02:00"
...
}

Accordingly in the OpenAPI definition, all nullable response properties are no longer marked as mandatory, and the “| null” addition has been removed from the type definition:

Example

Access V1:

Access V2:

If you use an OpenAPI-generated API client: No changes should be required, as the generated code should still return null values as before.

Date fields use real date types instead of strings

In Access V1, date properties in service requests and responses were defined as OpenAPI “string” type with an additional format description “YYYY-MM-DD” in the API docs. Starting with Access V2, all such properties now refer to the regular OpenAPI "date" type by additionally specifying the format: date qualifier.
The JSON payload is unchanged as the OpenAPI “date” type uses an identical date format. But if you generate a client from the OpenAPI definition, you will now get a proper date type generated in your target language, making date-to-string or string-to-date conversion unnecessary.

The following properties are affected:

  • BankConnectionOwner type: dateOfBirth

  • CreateDirectDebitParams type: executionDate

  • CreateMoneyTransferParams type: executionDate

  • CreateStandingOrderParams type: startDate, endDate

  • DirectDebitOrderParams type: mandateDate

  • EditTppCredentialParams type: validFromDate, validUntilDate

  • NewTransaction type: bookingDate, valueDate

  • Payment type: instructedExecutionDate

  • StandingOrder type: startDate, endDate

  • TppCertificate type: validFrom, validUntil

  • TppCertificateParams type: validFromDate, validUntilDate

  • TppCredentials type: validFrom, validUntil

  • TppCredentialsParams type: validFromDate, validUntilDate

  • UserInfo type: registrationDate, deletionDate, lastActiveDate, latestBankConnectionImportDate, latestBankConnectionDeletionDate

Additionally, the following response properties, which were previously defined as type “string” containing a date-time value, but in fact always returned a date with “00:00:00.000” as the time part, have been migrated to the OpenAPI “date” type. This affects the following response types and properties:

  • Transaction type: valueDate, bankBookingDate, finapiBookingDate

  • DailyBalance type: date

Timezone information included for date-time response properties

In Access V1, date-time properties in service responses were defined as OpenAPI “string” type with an additional format description “'YYYY-MM-DD HH:MM:SS.SSS' (german time)” in the API docs. Starting with Access V2, such properties now use the regular OpenAPI “date-time” format which includes timezone information according to RFC 3339, section 5.6.
The JSON response format is changed in the following way (Example: Excerpt from getAccount response):

Access V1:

CODE 
"lastSuccessfulUpdate": "2022-09-05 13:14:58.000"

Access V2:

CODE 
"lastSuccessfulUpdate": "2022-09-05T13:14:58.000+02:00"

The following response properties are affected:

  • Account type: lastSuccessfulUpdate, lastUpdateAttempt

  • AccountInterface type: lastSuccessfulUpdate, lastUpdateAttempt

  • Bank type: lastCommunicationAttempt, lastSuccessfulCommunication

  • BankConsent type: expiresAt

  • BankInterface type: lastCommunicationAttempt, lastSuccessfulCommunication

  • DailyBalanceList type: latestCommonBalanceTimestamp

  • ErrorMessage type: date

  • IbanRule type: creationDate

  • KeywordRule type: creationDate

  • Payment type: requestDate, executionDate

  • Security type: quoteDate

  • StandingOrder type: requestDate, requestCompletionDate

  • Transaction type: importDate

  • UpdateResult type: timestamp

If you generate a client from the OpenAPI definition, you will now get a proper date-time type generated in your target language, making date-time-to-string or string-to-date-time conversion unnecessary.
The returned timezone is defined by the finAPI Access server environment, but can easily be converted into your desired client timezone.

Web Form related changes

Support for the deprecated internal Web Form has been removed.

Removed services

  • getWebForm

Changed services

The HTTP status code 451 to signal that a Web Form must be opened has been removed from the following services:

  • importBankConnection, updateBankConnection, editBankConnection, connectInterface, submitPayment

The enumeration properties aisWebFormMode, pisWebFormMode and pisStandaloneWebFormMode returned by the services

  • getClientConfiguration, editClientConfiguration

have been removed and replaced by the new boolean properties aisViaWebForm, pisViaWebForm, and pisStandaloneViaWebForm. The mapping is as follows:

  • aisWebFormMode.INTERNAL, -> no longer available as the internal Web Form has been removed.

  • aisWebFormMode.EXTERNAL → aisViaWebForm is set to true

  • aisWebFormMode.DISABLED -> aisViaWebForm is set to false

  • pisWebFormMode.INTERNAL, -> no longer available as the internal Web Form has been removed.

  • pisWebFormMode.EXTERNAL → pisViaWebForm is set to true

  • pisWebFormMode.DISABLED -> pisViaWebForm is set to false

  • pisStandaloneWebFormMode.INTERNAL, -> no longer available as the internal Web Form has been removed.

  • pisStandaloneWebFormMode.EXTERNAL → pisStandaloneViaWebFormis set to true

  • pisStandaloneWebFormMode.DISABLED -> pisStandaloneViaWebFormis set to false

Removed properties (related to the Web Form) are mentioned in the “Removed deprecated request and response properties” section below.

Authorization changes

For security reasons, it’s no longer possible to provide security-relevant data as query parameters. This affects the following services:

  • getToken service: credentials can no longer be passed as query parameters. Please provide credentials in the request body as described in the service documentation.

  • revokeToken service: the query parameters - token and token_type_hint - have been replaced by the new RevokeTokenParams OpenAPI schema type which must now be provided in the request body.

  • all other services: the access token can no longer be passed with the “access_token” query parameter. Please provide it in the “Authorization” request header instead.

The maximum length of the “access_token” returned by the getToken service has been increased from 128 to 8192. The token format hasn’t changed yet with Access V2, and existing access tokens created with the Access V1 API are still valid, but the token format may change in the future. So please make sure you are able to handle and store tokens up to the new maximum length.

Property interface renamed to bankingInterface

To avoid problems with generated API clients, the property interface has been renamed to bankingInterface for parameters and responses, as "interface" is a reserved word in some programming languages.

This affects the following schema types:

  • request types: ImportBankConnectionParams, UpdateBankConnectionParams, EditBankConnectionParams, ConnectInterfaceParams, RemoveInterfaceParams, SubmitPaymentParams, SubmitStandingOrderParams, MockBankConnectionUpdate

  • response types: BankInterface, BankConnectionInterface, AccountInterface

For consistency, the property “sourceInterface” has also been renamed to "sourceBankingInterface" in:

  • ConnectInterfaceParams type

Also, the supportedInterfaces query parameter has been renamed to supportedBankingInterfaces in the following service:

  • getAndSearchAllBanks

Property bankingInterface made mandatory

The bankingInterface property (renamed from "interface") has been made mandatory in the following request types:

  • importBankConnectionParams, UpdateBankConnectionParams, MockBankConnectionUpdate

Property Bank.interfaces changed in its semantics

In V1, the interfaces property of the Bank resource contained only those interfaces that were supported (i.e. that can be used for bank connection import and/or payments).

In V2, the interfaces property contains all interfaces that exist in the finAPI bank repository, even when they are currently not supported. This change was done to ensure data consistency in the case when we have to (temporarily) disable an interface, for example, due to bank-side issues. In V1, this situation could lead to existing bank connections that are linked to an interface that no longer exists in the API. In V2, disabled interfaces would still be returned in the API.

To determine whether an interface is supported in V2, you need to regard the BankInterface properties isAisSupported / isPisSupported.

Property UpdateBankConnectionParams.importNewAccounts changed in its semantics

In V1, if the flag importNewAccounts was set to true on a bank connection update and the bank connection had an existing consent with supportsImportNewAccounts=false (which is the case for Sparkasse banks and the finAPI demo bank DEMO0001 with XS2A), the update succeeded, but without importing new accounts (as the bank can’t handle new accounts with the existing consent), so the flag had no effect.

In V2, this case now results in an HTTP 422 error with type=BUSINESS and code=ILLEGAL_ENTITY_STATE. So if you want to perform an update with importNewAccounts=true, please make sure that the consent (if available) supports it. If it doesn’t, then you must first delete the existing consent with the deleteConsent service before you can try to import new accounts. Note that in any case, when a new consent is requested during an update, user involvement is required due to strong customer authentication.

Added properties

The following new response properties have been added (please refer to the Access V2 docs for further details):

  • BankInterface type: isPisSupported

Removed deprecated services

All services have been removed that were marked as deprecated for a long time (please refer to their Access V1 docs on how to migrate them):

Deprecated Payment Services:

  • requestSepaMoneyTransfer, executeSepaMoneyTransfer, requestSepaDirectDebit, executeSepaDirectDebit

Deprecated “getMultiple” services (please migrate to the respective “getAll” services):

  • getMultipleBanks, getMultipleBankConnections, getMultipleAccounts, getMultipleTransactions, getMultipleSecurities, getMultipleCategories, getMultipleLabels

Deprecated “editMultiple” services (please migrate to the “editMultipleTransactions” service):

  • editMultipleTransactionsDeprecated

Removed deprecated query parameters

The following query parameters have been removed:

  • getAndSearchAllBanks service: isSupported, pinsAreVolatile, supportedDataSources

  • getAndSearchAllAccounts service: accountTypeIds

Removed deprecated request and response properties

The following properties have been removed from request and response schema types. All properties are marked as deprecated in the Access V1 API. Please refer to the Access V1 docs on how to migrate them.

Client configuration related:

  • ClientConfigurationParams request type: isPinStorageAvailableInWebForm, storeSecretsAvailableInWebForm, applicationName, supportSubjectDefault, supportEmail

  • ClientConfiguration response type: isXs2aEnabled, pinStorageAvailableInWebForm, applicationName, storeSecretsAvailableInWebForm, supportSubjectDefault, supportEmail, autoDismountWebForm

Account related:

  • AcountParams request type: accountTypeId

  • Account response type: accountTypeId, accountTypeName, lastSuccessfulUpdate, lastUpdateAttempt, status, supportedOrders, clearingAccounts

Bank related:

  • Bank response type: loginHint, blzs, isSupported, health, loginFieldUserId, loginFieldCustomerId, loginFieldPin, pinsAreVolatile, isCustomerIdPassword, supportedDataSources, lastCommunicationAttempt, lastSuccessfulCommunication

  • BankInterface response type: isMoneyTransferSupported

Bank connection related:

  • importBankConnectionParams request type: bankingUserId, bankingCustomerId, bankingPin, storePin, accountTypeIds, challengeResponse

  • updateBankConnectionParams request type: bankingPin, storePin, challengeResponse, forceWebForm

  • editBankConnectionParams request type: bankingUserId, bankingCustomerId, bankingPin

  • BankConnection response type: bankId, bankingUserId, bankingCustomerId, bankingPin, type, lastManualUpdate, lastAutoUpdate, ibanOnlyMoneyTransferSupported, ibanOnlyDirectDebitSupported, collectiveMoneyTransferSupported, defaultTwoStepProcedureId, twoStepProcedures, furtherLoginNotRecommended

Payment related:

  • SubmitPaymentParams request type: hideTransactionDetailsInWebForm, forceWebForm

  • CreateStandingOrderParams request type: dayOfExecution

  • StandingOrder response type: dayOfExecution

Proposed migration approach

We propose the following approach for the migration to Access V2:

  • If you are still using the deprecated internal Access Web Form :
    Then please migrate to Web Form V2 first. We suggest doing this on Access V1 already as a separate step before the Access V2 migration.

  • If you are still using deprecated services or properties from Access V1 (see “Removed Services” section”):
    Then we suggest migrating them to non-deprecated services on Access V1 first, as a separate step before starting the Access V2 migration, as the Access V1 API documentation describes the necessary changes in detail.
    If your API client has been generated from the V1 “openapi-access-latest.yaml” file, in which all deprecations have been removed already, you are already done.

  • Activate the Access V2 API for your client on our sandbox environment using the switchApiVersion service.

  • Adjust your client to the Access V2 API by implementing the changes described in the “API changes summary” section and test that your application works correctly against the new API. If you cannot finish your tests within the 7 days rollback period, remember to switch back to V1 in time. This allows you to restart the testing period when you switch to V2 again, to have 7 more days for testing.

  • Activate the Access V2 API for your client on your production environment and roll out your adjusted application. Also on the production environment, you can switch back to V1 if necessary as described for the sandbox environment.

Appendix

For a detailed comparison of service changes, you may refer to the generated API diff between Access V1 and Access V2:

Changelog-2022.42.1-V1-V2.pdf


Please note that the document reflects the changes at the time when Access V2 was rolled out on October 20th, 2022. Later adjustments or extensions to the Access API won’t be covered here.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close