Subsembly FinTS API

Copyright © 2004-2025 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
  • fr/Subsembly.FinTS.Core.resources.dll
  • fr/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 core assemblies were compiled for .NET Standard 2.0 but do only work in a Windows environment:

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

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

  • Subsembly.FinTS.Win32.dll

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

  • Subsembly.FinTS.Win32.Net.dll

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

You must supply your application 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.

IMPORTANT: SWIFT MT-940 transaction data is end-of-life

At last, the tone old SWIFT MT-940 format for account transaction data is retired. Many banks already started to support download of transaction data in the new CAMT format via segment type HKCAZ. This is already supported by the class FinCamtStatementBuilder and is the preferred method for downloading transaction data, if supported by the bank.

Starting November 2025 several banks discontinue the support for downloading transaction data in SWIFT MT-940 format via segment type HKKAZ. Hence, your code must be able to handle both scenarios.

Here an example of the recommended way to determine which way to download account transaction data shall be used.

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

// FinContact aContact
// FinAcctInfo aAcctInfo // from UPD
// SwiftDate tStartDate
// SwiftDate tEndDate
// IWin32Window aParentWindow

FinCamtStatementBuilder aCamtBuilder = new FinCamtStatementBuilder(aContact);

if (aCamtBuilder.IsSupported && aAcctInfo.IsAllowed(aCamtBuilder.OrderSegmentType))
{
    FinCamtStatement aOrder = aCamtBuilder.Build(aAcctInfo.Acct, tStartDate, tEndDate);
    FinScriptSendOrder.Execute(aParentWindow, aContact, aOrder, null);
    // aOrder.BookedCamts -> Booked transactions
    // aOrder.NonbookedCamts -> Pending transactions
}
else
{
    FinAcctMvmtsSpecifiedPeriodBuilder aSwiftBuilder = new FinAcctMvmtsSpecifiedPeriodBuilder(aContact);

    if (aSwiftBuilder.IsSupported && aAcctInfo.IsAllowed(aSwiftBuilder.OrderSegmentType))
    {
        FinAcctMvmtsSpecifiedPeriod aOrder = aSwiftBuilder.Build(aAcctInfo.Acct, false, tStartDate, tEndDate, 0, null);
        FinScriptSendOrder.Execute(aParentWindow, aContact, aOrder, null);
        // aOrder.GetBooked() -> Booked transactions
        // aOrder.GetNonbooked() -> Pending transactions
    }
}
else
{
    // Download of transactions is not supported by the bank or account.
}

IMPORTANT: Verfication of Payee

Starting on October, 5th 2025 all remittances are subject to a Verfication of Payee procedure. This means that before a remittance is executed by the bank, it verifies whether the given payee IBAN matches the given payee name, as known be the recipient bank. If there is a mis-match, then the user must explicitly confirm this mis-match, in order to execute the remittance anyway.

For this confirmation step a new interface Subsembly.FinTS.Forms.IFinVerificationOfPayeeForm was added to the UI components. By providing an implementation of this interface to Subsembly.FinTS.Forms.FinScriptSendOrder, your code can take over control of the Verification of Payee confirmation. If you do not provide an implementation, then the Subsembly.FinTS.Forms.FinVerificationOfPayeeForm will be used.

If you are not using FinScriptSendOrder, but are working with Subsembly.FinTS.Online.FinBanking, then you have to handle the additional new FinDialogResultCodes Subsembly.FinTS.FinDialogResultCode.NeedContinue and Subsembly.FinTS.FinDialogResultCode.NeedConfirmationOfPayee.

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 also the complete Verfication of Payee procedure.

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

Getting Started

The easiest way to use the Subsembly FinTS API is through the various FinScript derived classes. These, however, are only available on the Windows platform and facilitate their own Windows UI.

The central class of the Subsembly FinTS API is the FinContact. 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:

A fully initialized FinContact can be used to send any FinOrder to the bank. Orders are created through FinOrderBuilder derived classes. Here an example of how to create an order that submits a SEPA payment to the bank.

    using Subsembly.FinTS;
    using Subsembly.Sepa;

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

    // SepaDocument aSepaDoc

    FinAcct aOrderAcct = aContact.ProduceOrderAcct(FinAcctTypeClass.Giro,
        new SepaIBAN("DE00123456781234567890"), "EUR");

    FinSepaOrderBuilder aBuilder = new FinSepaSingRemittBuilder(aContact);
    FinOrder aOrder = aBuilder.Build(aOrderAcct, aSepaDoc);

The class FinScriptSendOrder can now be used to send this order to the bank. Note that this will begin a new FinTS dialog, send the order and finally orderly close the FinTS dialog again.

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

    FinDialog.ProductRegisterNo = "YOURFINTSREGISTRATIONNUMBER";

    // FinContact aContact
    // FinOrder aOrder
    // IWin32Window aParentWindow

    FinScriptSendOrder aScript = FinScriptSendOrder.Execute(aParentWindow, aContact, aOrder, null);
    // aScript.Trace
    // aScript.Result

If you do not want (or can) to use the default UI, then you have to use the class FinBanking for conducting FinTS dialogs and send orders. This is supported by an instance of the class FinCredentialManager, which provides any (or no) user interface for gathering credentials from the user.

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
    // FinOrder aOrder

    FinCredentialManager aCredentialManager = new FinCredentialManager("YOURPIN");

    using (FinBanking aBanking = new FinBanking(aContact, aCredentialManager))
    {
        FinDialogResult aResult = aBanking.BeginDialog();
        aResult = aBanking.SendOrder(aOrder);
        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, NeedDecoupled, NeedContinue, and NeedConfirmationOfPayee.

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 credential interface requests.

An application still must handle the Verfication of Payee responses NeedContinue and NeedConfirmationOfPayee. However, it can do use by leveraging the default Windows implementation FinVerificationOfPayeeForm.

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.