Subsembly EBICS API

Copyright © 2009-2024 Subsembly GmbH

The Subsembly EBICS API provides businesses with access to EBICS bank accounts in Germany, Austria and Switzerland.

Release Notes

The release notes can be found here.

Assemblies

The Subsembly EBICS API consists of several core assemblies compiled for .NET Standard 2.0 and some optional Windows 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.

All Runtime files are stored in the folder bin in the Subsembly.EBICS.zip. For an easy deployment, simply copy all files from this bin folder to your installation directory.

The following core assemblies were compiled for .NET Standard 2.0 and must be installed with your applications. These 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.EBICS.Core.dll
  • Subsembly.Interweb.dll
  • Subsembly.Json.dll
  • Subsembly.Printing.dll
  • Subsembly.Sepa.dll
  • Subsembly.SubFS.dll

For internationalization the following text resource files are included.

  • de-CH/Subsembly.EBICS.Core.resources.dll
  • en/Subsembly.EBICS.Core.resources.dll
  • en/Subsembly.Sepa.resources.dll
  • fr/Subsembly.EBICS.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 assemblies are only supported on Windows and have been compiled for .NET Framework 4.8:

  • Subsembly.EBICS.Win32.dll
  • en/Subsembly.EBICS.Win32.resources.dll
  • fr/Subsembly.EBICS.Win32.resources.dll
  • Subsembly.Win32.dll
  • en/Subsembly.Win32.resources.dll
  • fr/Subsembly.Win32.resources.dll

If smart cards shall be supported, the following Windows DLLs must be included, too:

  • Subsembly.EBICS.SmartCard.dll
  • en/Subsembly.EBICS.SmartCard.resources.dll
  • fr/Subsembly.EBICS.SmartCard.resources.dll
  • Subsembly.SmartCard.dll

For managing Windows Scheduled Taks with the EbicsSpoolerTask the following runtime assembly or the NuGet package TaskScheduler by David Hall must be installed, too.

  • Microsoft.Win32.TaskScheduler.dll
  • fr/Microsoft.Win32.TaskScheduler.resources.dll

The following essential tools are included with the Subsembly EBICS API for redistribution and should be installed, when neeed. The command line tools EbicsSpooler.exe and EbicsSpoolerConfig.exe currently require .NET 8.0 for execution.

  • EbicsAdmin.exe
  • EbicsAdmin.exe.config
  • EbicsSpooler.dll
  • EbicsSpooler.exe
  • EbicsSpooler.runtimeconfig.json
  • EbicsSpoolerUsage.txt
  • EbicsSpoolerConfig.dll
  • EbicsSpoolerConfig.exe
  • EbicsSpoolerConfig.runtimeconfig.json
  • EbicsSpoolerConfigUsage.txt

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

  • Subsembly.EBICS.Core.xml
  • Subsembly.EBICS.SmartCard.xml
  • Subsembly.EBICS.Win32.xml
  • Subsembly.Json.xml
  • Subsembly.Sepa.xml

All of these assemblies and files are contained in the bin folder of the ZIP file of the Subsembly EBICS API software development kit.

API Documentation

The Subsembly EBICS API is divided into three separate assemblies.

  • The Subsembly.EBICS.Core.dll contains the platform neutral base classes. These can be used on any platform. All classes in this assembly are part of namespace Subsembly.EBICS.

  • The Subsembly.EBICS.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 namespace Subsembly.EBICS.

  • The Subsembly.EBICS.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.EBICS.

Environment Variables

The following system environment variables may be set to configure the Subsembly EBICS API and the EBICS Spooler. These are also accessible through the static EbicsConfig class.

SUBSEMBLY_EBICS_CONTACTFOLDERPATH

A complete, rooted path to the directory where the EbicsContact objects are stored by default. See EbicsContactFolder.Default. If this is not set, then either a folder in the SUBSEMBLY_EBICS_SPOOLERFOLDERPATH or a folder Subsembly/EBICS below the Environment.SpecialFolder.ApplicationData folder will be used. Usually there is no need to set this variable.

SUBSEMBLY_EBICS_SPOOLERFOLDERPATH

A complete, rooted path to the directory that acts as the root for the EBICS Spooler storage. See EbicsFileSpooler. This variable must be set if an EBICS Spooler Folder shall be used.

SUBSEMBLY_EBICS_SPOOLERBINARYPATH

A complete, rooted path to the directory where the binary executables of the Subsembly EBICS API have been installed. This must be set explicitly for the EBICS Spooler Task.

EBICS Spooler

The Subsembly EBICS API includes an EBICS file spooler facility to automate downloads of account statements and reports and uploads of SEPA payment files. The EBICS file spooler is made available through the Subsembly.EBICS.EbicsFileSpooler and associated classes. In addition a EbicsSpooler command line application is included which can be started manually, or automatically through some operating system timer facility, e.g. the Windows Task Scheduler or a Cron job.

On Windows the Subsembly.EBICS.Win32.dll provides a default EbicsSpoolerTask that integrates with the Windows Task Scheduler. The default EBICS Spooler Task can also be managed through the EbicsAdmin application for Windows.

Download

Please contact Subsembly for your private download link and credentials.

IMPORTANT: License Token

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

Getting Started

1. Obtain an EBICS bank access

Before you can start developing you need an EBICS bank access set up at your bank. If you do not have the possibility to get an EBICS bank access, you can alternatively contact Subsembly in order to get access to the Subsembly EBICS Dummy test system.

You need the following information from your bank in order to set up an EBICS bank access:

  • Host-ID
  • Host-URL
  • User-ID
  • Partner-ID
  • Supported EBICS versions
  • Bank key hash value

2. Use EbicsAdmin to set up bank access

Once you have all the information required to set up an EBICS bank connection, you should start the EbicsAdmin application included with the Subsembly EBICS API development kit. Klick on New EBICS Bank Connection and select the Key File option for setting up an EBICS bank connection protected by private keys stored in a file.

Create a New Key File protected by a password of your choice. The required Host-ID, Host-URL, User-ID, and Partner-ID should have been provided by your bank. We recommend choosing EBICS version 2.5 for setting up a new EBICS bank connection. It is possible to easily switch to EBICS version 3.0 later, if needed at all.

Important: Be aware that there is only a single attempt to set up a new EBICS user at a bank. If there is some failure, or you loose your key file, or forget your key file password, then you will have to contact your bank and ask to fully reset your EBICS user ID, so that you can start over again.

After you printed, signed and sent your INI letter to the bank you will have to wait for the bank to process the INI letter and finally activate your EBICS bank connection. When using the Subsembly EBICS Dummy, this is not needed, as all submitted user keys are immediately processed and activated without any further action needed.

If the EBICS bank connection was activated, you still have to download the bank keys (HPB) using the context menu in order to complete the set up. This is only possible, after the bank has activated the keys that you previously submitted to the bank. After you acknowledge the bank keys, by comparing the bank key hash value, the bank connection is ready to be used.

All the steps needed to set up a new EBICS bank connection could also be done in code. However, at least for the first development steps, we highly recommend to use the EbicsAdmin instead.

3. Obtain EbicsContact instance

Every EBICS bank connection listed in the EbicsAdmin application corresponds to an instance of the EbicsContact class. When working with the Subsembly EBICS API you always start with obtaining an EbicsContact instance that represents the EBICS bank connection to you want to access.

All the EBICS bank connections shown in the EbicsAdmin are directly available through the global Default EbicsContactFolder. By enumerating the folder content, you will find all the EbicsContact instances corresponding to the EBICS bank connections of the EbicsAdmin.

Alternatively the EBICS bank connections can be exported in individual XML files that store the complete data of the EBICS bank connection, but without the key file. The XML file still contains just the file name of the actual key file that is used by that EBICS bank connection. The exported XML file can be used to create an EbicsContact instance by calling the static LoadContact method.

4. Controlling the persistence of the EbicsContact

If an EbicsContact is naively loaded from a file, the application has to be careful to manually save back any direct or indirect changes of the EbicsContact to the XML file.

This is different to an EbicsContact that was obtained from an EbicsContactFolder, where all changes are automatically saved back to the folder where it was loaded from. For this reason it makes sense to always use some sort of IEbicsContactFolder implementation in order to take over persistence of the EbicsContact.

For simple file based storage the default EbicsContactFolder implementation can be used on any file system folder. If the EBICS bank connections shall be stored somewhere else, e.g. a database, then a suitable implementation of IEbicsContactFolder should be provided.

For first development steps it is probably easiest to just use the EbicsContact instances obatined through the global Default EbicsContactFolder.

5. Authenticate the EbicsContact

The key file used by an EbicsContact is encrypted with the password that was chosen during setup of the EBICS bank connection. Hence, whenever the EbicsContact shall be used, this password must be presented. As the Subsembly EBICS API also supports other means to store the private keys of an EbicsContact, the key storage is abstractly used through the IEbicsSecurityMedium interface. Thus, in order to use an EbicsContact, you need to authenticate the attached security medium by presenting the password to it. To do so, call the method Authenticate with the key file password. If successful, this will provide an authenticated IEbicsSecurityMedium instance.

If authentication fails, then an exception will be thrown. Hence it is important to protect the call to Authenticate with a try/catch construct.

6. Create an EbicsOrder

There are only two kinds of EBICS orders: Uploads and downloads. Both just transfer some opaque order data blob that has no meaning to the EBICS protocol itself. Hence the generic EbicsOrder class can be used to perform any conceivable EBICS order type.

Up to EBICS version 2.5 the content of the EBICS data transfer was described by a three letter EBICS order type that was sent together with the order data. EBICS version 3.0 introduced a much more complex meta data scheme to describe the EBICS order data.

For common EBICS order types, such as downloading account statements, or uploading payments, the Subsembly EBICS API already provides convenient wrapper classes that derive from EbicsOrder. These wrapper classes also handle the differences between EBICS 2.5 (or earlier) and EBICS 3.0 (or later). Hence it makes sense to uses these EbicsOrderXXX classes whenever possible.

All of the EbicsOrder derived classes can be instantiated directly. Some of these classes have additional, mostly optional, order parameters. These are described with the constructors of the individual classes.

7. Send the EbicsOrder

Once you have an EbicsOrder, you can send it using the EbicsContact and the authenticated IEbicsSecurityMedium obtained above. This can be easily done through the Send method of the EbicsContact.

There are various overloads of the Send method. Those that expect an IEbicsTransport implementation can simply be provided with a new EbicsTransport instance, unless you want to take control over the actual transport of the raw data.

8. Complete Download Order sample

The following code is a complete sample that shows how to download the CAMT account statement documents for the last 14 days. It uses a previously configured EBICS bank connection that was named "My Contact Name" in the EbicsAdmin application. The password of the key file is assumed to be "mypassword".

    // using Subsembly.EBICS;
    // using Subsembly.Sepa;

    EbicsContact aContact = EbicsContactFolder.Default.Find("My Contact Name");
    IEbicsSecurityMedium aSecurity = aContact.Authenticate("mypassword");
    EbicsOrderCamt aOrder = EbicsOrderCamt.CreateOrderC53("C53", DateTime.Today.AddDays(-14));
    IEbicsTransport aTransport = new EbicsTransport();

    EbicsErrorClass nErrorClass = aContact.Send(aOrder, aSecurity, aTransport);

    foreach (EbicsOrderCamtDocument aCamtDocument in aOrder.CamtDocuments)
    {
        // The CAMT C53 message that was contained in the downloaded ZIP-file
        // can be conveniently accessed through the CamtMessage property.

        SepaBankToCustomerMessage aCamtMessage = aCamtDocument.CamtMessage;
    }

If your bank only supports account statements in SWIFT MT-940 format, then you just have to replace "C53" with "STA". The instantiated EbicsOrderCamt implementation automatically converts SWIFT MT-940 to CAMT 053 on the fly, thus the code sample actually works with CAMT 053 and SWIFT MT-940 formats without changes.

Using some convenient overloads the sample can be shortened to:

    // using Subsembly.EBICS;
    // using Subsembly.Sepa;

    EbicsContact aContact = EbicsContactFolder.Default.Find("My Contact Name");
    EbicsOrderCamt aOrder = EbicsOrderCamt.CreateOrderC53("C53", DateTime.Today.AddDays(-14));

    EbicsErrorClass nErrorClass = aContact.Send(aOrder, "mypassword");

    foreach (EbicsOrderCamtDocument aCamtDocument in aOrder.CamtDocuments)
    {
        // The CAMT C53 message that was contained in the downloaded ZIP-file
        // can be conveniently accessed through the CamtMessage property.

        SepaBankToCustomerMessage aCamtMessage = aCamtDocument.CamtMessage;
    }

If you use the Windows UI classes of the Subsembly EBICS API, then the following code may be used inside a Windows Forms event handler. This code automatically obtains the password from the user.

    // using Subsembly.EBICS;
    // using Subsembly.Sepa;

    EbicsContact aContact = EbicsContactFolder.Default.Find("My Contact Name");
    EbicsOrderCamt aOrder = EbicsOrderCamt.CreateOrderC53("C53", DateTime.Today.AddDays(-14));

    EbicsErrorClass nErrorClass = aContact.Send(this, aOrder);

    foreach (EbicsOrderCamtDocument aCamtDocument in aOrder.CamtDocuments)
    {
        // The CAMT C53 message that was contained in the downloaded ZIP-file
        // can be conveniently accessed through the CamtMessage property.

        SepaBankToCustomerMessage aCamtMessage = aCamtDocument.CamtMessage;
    }

9. Uploading a SEPA payment file

Payment orders are usually uploaded to the EBICS server using SEPA PAIN XML documents. Hence, the first step to upload one or more payments is to create appropriate SEPA PAIN 001 or PAIN 008 documents. This can be accomplished using the Subsembly SEPA API classes, that are included with the Subsembly EBICS API development kit.

However the SEPA payments are created, the following sample code assumes that the SEPA payment document is provided as an instance of the SepaDocument class. If you have an externally created SEPA payment file, you can easily just load it into a new SepaDocument instance.

    // using Subsembly.EBICS;
    // using Subsembly.Sepa;

    SepaDocument aSepaDocument = SepaDocument.New("painfile.xml");

    EbicsContact aContact = EbicsContactFolder.Default.Find("My Contact Name");
    EbicsOrderSepa aOrder = new EbicsOrderSepa(aSepaDocument);

    EbicsErrorClass nErrorClass = aContact.Send(this, aOrder);

The result EbicsErrorClass indicates whether the upload was successful, or not.

Important

A successful upload does not imply that the order was correct or will be executed. An EBICS server asynchronously processes uploaded files. Hence, any errors in the payment file will only be found after the upload was already acknowledged successfully.

10. Further Topics

Due to the nature of the asynchronous processing of uploads, a client application can check the asynchronous result by downloading the processing protocol using the EbicsOrderProtocol class.

The EbicsOrderHTD can be used to download information about the bank accounts accessible to the user, and his order permissions. A client can use this information to automatically set up bank accounts in the application.