Subsembly FinTS API

Copyright © 2004-2023 Subsembly GmbH

The Subsembly FinTS API is a comprehensive class library for FinTS/HBCI online banking clients.

Release Notes

The release notes (in German only) can be found here.

Assemblies

The Subsembly FinTS API consists of several core assemblies compiled for .NET Standard 2.0 and some optional assemblies compiled for .NET Framework 4.8. See https://docs.microsoft.com/de-de/dotnet/standard/net-standard for a table of .NET Standard 2.0 compatible platforms.

The following core assemblies were compiled for .NET Standard 2.0 and can be added to any project that targets a .NET Standard 2.0 compatible environment:

Subsembly.AppBase.dll
Subsembly.Crypto.dll
Subsembly.Csv.dll
Subsembly.FinTS.Core.dll
Subsembly.Json.dll
Subsembly.Printing.dll
Subsembly.Sepa.dll
FinBanks.dat (set Build Action to Content)

For internationalization the following text resource files are included.

en/Subsembly.FinTS.Core.resources.dll
en/Subsembly.Sepa.resources.dll

Also, you must add a NuGet reference to System.Text.Encoding.CodePages by Microsoft (see https://www.nuget.org/packages/System.Text.Encoding.CodePages/4.7.1), or add the following files to your installation:

System.Runtime.CompilerServices.Unsafe.dll
System.Text.Encoding.CodePages.dll

The following assemblies are only supported on Windows and have been compiled for .NET Framework 4.8:

Subsembly.FinTS.SmartCard.dll (only if smart cards are used)
en/Subsembly.FinTS.SmartCard.resources.dll (for english texts)
Subsembly.FinTS.Win32.dll
Subsembly.SmartCard.dll (only if smart cards are used)

In addition the following files should be added to your development environment in order to support the Visual Studio Intellisense:

Subsembly.FinTS.Core.xml
Subsembly.FinTS.SmartCard.xml
Subsembly.FinTS.Win32.xml
Subsembly.Json.xml
Subsembly.Sepa.xml

The FinAdmin tool is included with the Subsembly FinTS API for redistribution and should be installed, when neeed.

FinAdmin.exe
FinAdmin.exe.config

All of these assemblies and files are contained in the Subsembly FinTS API software development kit.

API Documentation

The Subsembly FinTS API itself is divided into three separate assemblies. It uses several supporting assemblies that are also included in the package.

The Subsembly.FinTS.Core.dll contains the platform neutral base classes. This assembly targets .NET Standard 2.0. All classes in this assembly are part of the following namespaces:
The Subsembly.FinTS.SmartCard.dll contains additional classes for supporting HBCI smart cards. These classes are only supported on Windows and macOS platforms. All classes in this assemblys are also part of these namespaces:
- Namespace Subsembly.FinTS
- Namespace Subsembly.FinTS.HHD
The Subsembly.FinTS.Win32.dll contains UI classes for Windows only. These classes require a true Windows platform with .NET Framework 4.8. The classes of this assembly use
- Namespace Subsembly.FinTS.Forms

The supporting assemblies are

The Subsembly SEPA API contained in the Subsembly.Sepa3.dll assembly. Documentation of these classes can be found with the Subsembly SEPA API.
The private smart card access classes contained in the Subsembly.SmartCard.dll. These are only needed when HBCI smart cards shall be supported.
The cryptographic algorithms implemented in the Subsembly.Crypto.dll.
Simple CSV utility classes implemented in the Subsembly.Csv.dll.
Simple JSON utility classes implemented in the Subsembly.Json.dll.
A PDF generator for generating Ini-Letters in PDF Format is implemented in the Subsembly.Printing.dll.

Download

Please contact Subsembly for your private download link and credentials.

IMPORTANT: License Token

In order to use the Subsembly FinTS API you will need a valid license token. The license token may be installed alongside the assemblies using the file name FinLicense.jwt, or the token may be passed to the static method Subsembly.FinTS.FinLicense.SetLicenseToken(System.String).

You can get a time limited token for evaluation upon request from Subsembly GmbH. With a valid license, you will get an unlimited license token.

IMPORTANT: Client Registration for PSD 2 compliance

Because of the new PSD 2 regulations, the Deutsche Kreditwirtschaft (DK) decided that all FinTS clients have to registered with it. For details please read:

https://www.hbci-zka.de/register/register_faq.htm

Starting on 2018-12-01 you should supply your registration code as the product name in every FinTS dialog initialisation. Starting at 2019-08-01 you must supply your registration code.

With the latest version of the Subsembly FinTS API you can supply the registration code by setting the static property FinDialog.ProductRegisterNo.

Also note, that the PSD 2 migration period ends on 2019-09-14. Starting with this day, it is no longer permitted to use FinTS bank interfaces from third party services. All third party services must then use the new PSD 2 interfaces that will be provided by the banks. Yet, it is still possible to directly connect to FinTS interfaces from traditional client software, such as Windows applications or mobile apps.

If you have any questions concerning FinTS and the new PSD 2 regulations, please feel free to contact us at any time.

FinTS Test Server

We are proud to announce that we now operate a fully functional FinTS 3.0 server, designed as a testing environment. This server already implements all PSD 2 extensions to FinTS and can be used to test various PSD 2 migration and cutover scenarios.

Please contact us for information on how to get access to the Subsembly FinTS Server.

Getting Started

The central classes of the Subsembly FinTS API are FinContact and FinBanking. These are supported by an instance of the class FinCredentialManager, which provides any (or no) user interface.

The FinContact holds all the data and information for one particular online banking user at a bank. For using PIN/TAN based security at a minimum the following properties of the FinContact must be initialized:

Based on a FinContact a new FinBanking instance can be created. A FinBanking holds the session context for one or more FinTS dialogs of the online banking user identified by the given FinContact. A very simple code sequence to send a single order without any error handling would look something like this:

    using Subsembly.FinTS;
    using Subsembly.FinTS.Online;
    using Subsembly.Sepa;

    FinDialog.ProductRegisterNo = "YOURFINTSREGISTRATIONNUMBER";

    FinContact aContact = new FinContact("https://fintsurl", "00000000", "UserID");
    FinCredentialManager aCredentialManager = new FinCredentialManager("YOURPIN");

    using (FinBanking aBanking = new FinBanking(aContact, aCredentialManager))
    {
        FinDialogResult aResult = aBanking.BeginDialog();

        FinAcctBalBuilder aBalanceOrderBuilder = new FinAcctBalBuilder(aContact);
        FinAcct aOrderAcct = aContact.ProduceOrderAcct(FinAcctTypeClass.Giro,
            new SepaIBAN("DE00123456781234567890"), "EUR");
        FinAcctBal aBalanceOrder = aBalanceOrderBuilder.Build(aOrderAcct, false);

        aResult = aBanking.SendOrder(aBalanceOrder);

        aBanking.TermDialog();
    }

Of course, real code would have to handle the result of every step. Through the result the method may request additional information, such as in the case of the result codes SelectTanProc, SelectTanMedia, NeedTan, and NeedDecoupled.

By processing these results your code has full control of the UI. As an alternative solution a derived or special instance of the class FinCredentialManager can be created in order to provide the UI. The Subsembly FinTS API includes a complete default UI that can be instantiated as follows:

    using Subsembly.FinTS;
    using Subsembly.FinTS.Online;
    using Subsembly.FinTS.Forms;


    FinBankingPinStore aPinStore = new FinBankingPinStore();
    FinCredentialForm aCredentialForm = new FinCredentialForm();
    FinTanProcForm aTanProcForm = new FinTanProcForm();

    FinCredentialManager aCredentialManager = new FinCredentialManager(
        aPinStore, aCredentialForm, aTanProcForm, aTanProcForm);

This FinCredentialManager can then be provided to the new FinBanking instance in order to handle all user interface requests.

Sample Code

The Subsembly FinTS API development kit includes four sample projects with source code.

FinAdmin A very simple application that launches the FinTS Administrator contained in the Subsembly FinTS API. You may include this executable with your product. However, it must be configured through command line parameters in order to include your FinTS product registration number.
FinPad A simple banking client application that uses the user interface integrated into the Subsembly FinTS API.
FinCmd A command line utility that demonstrates how to use the Subsembly FinTS API with a custom unser interface.
FinPing A small tool that demonstrates anonymous FinTS dialogs.