Subsembly XS2A API

Copyright © 2017-2023 Subsembly GmbH

The Subsembly XS2A API provides unified access to various bank accounts and credit cards. Depending on the account type FinTS or screen scraping is applied to retrieve the data. The complete reference documentation can be found in the respective namespaces below.

Release Notes

The release notes can be found here.

Namespaces

• Namespace Subsembly.Scraper
• Namespace Subsembly.Scraper.FinTS
• Namespace Subsembly.Json

Assemblies

The Subsembly XS2A API consists of several core assemblies compiled for .NET Standard 2.0. 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.Crypto.dll
• Subsembly.Csv.dll
• Subsembly.FinBanks.dll
• Subsembly.FinTS.Core.dll
• Subsembly.Interweb.dll
• Subsembly.Json.dll
• Subsembly.Scraper.dll
• Subsembly.Scraper.FinTS.dll
• Subsembly.Sepa.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), or add the following files to your installation:

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

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

• Subsembly.Csv.xml
• Subsembly.Json.xml
• Subsembly.Scraper.xml
• Subsembly.Scraper.FinTS.xml
• Subsembly.Sepa.xml

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

API Documentation

The primary namespace is Subsembly.Scraper with some support from the namespace Subsembly.Json. Also the Subsembly SEPA API is used extensively. The special FinTS protocol scraper is found in the namespace Subsembly.Scraper.FinTS in its own assembly.

Download

Please contact Subsembly for your private download link and credentials.

IMPORTANT: License Token

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

Quick Start

The following sample code shows the minimum amount of code that is needed in order to download the transaction data for the last 90 days from a given credit card account.

    JsonObject jsCred = new JsonObject();
    jsCred["UserID"] = "UserID or Credit Card Number";
    jsCred["Password"] = "My Secret Password";

    JsonObject jsAcct = new JsonObject();
    jsAcct["AcctTpCd"] = "CRDC";
    jsAcct["AcctNo"] = "Credit Card Number";
    jsAcct["AcctCcy"] = "EUR";

    SepaDocument camt;

    ScraperResult res = ScraperService.DownloadStatement(
        out camt, jsCred, jsAcct, DateTime.Today.AddDays(-90));

    if (res.IsSuccess && (camt != null))
    {
        camt.WriteDocument("camt.xml");
    }

The ScraperService class automatically finds an appropriate screen scraper or API scraper for the given credit card, based on the first six digits of the credit card number. It then instantiates a IScraperSession for it and uses it to download the statement data.

Important: If you want to use FinTS, then you must manually register the available scrapers as follows, before invoking any other ScraperService methods.

    ScraperService.RegisterBuiltInScrapers();
    ScraperService.RegisterFinTSScraper();

Classes and Interfaces

ScraperService

The static ScraperService class is at the root of the Subsembly XS2A architecture. At the root of every account access module is an implementation of the IScraper interface that is statically registered with the ScraperService, such that the ScraperService can find an implementation suitable for a given account.

A client uses the ScraperService to find a registered IScraper implementation, either by providing account details (FindScraper(jsAcct) or by providing a well known implementation name (FindScraper(sClassName). The returned IScraper interface can then be used the create a IScraperContact.

As a convenient shortcut, a client may also use CreateContact, in order to get an appropriately initialized IScraperContact for accessing a particular account product.

IScraperContact

Through the IScraperContact interface a client application can query various properties that describe the scraper implementation. A client application uses these properties in order to construct an user interface that is tailored for that particular account service and account product. For example, through this interface the client application learns which kind of user credentials are needed for log-on and which kind of services are actually supported by the scraper implementation.

Finally, the IScraperContact interface provide a method CreateSession which is used to prepare an online access to account session. CreateSession returns an IScraperSession interface.

The IScraperContact interface is based on the IScraperPersist interface through which the contact data with all its details can be persistently stored and recreated. More about scraper persistence is found below.

IScraperSession

Through the IScraperSession interface the client application conducts the online banking session with the account service provider. It uses the interface for logging on, getting balances and statements, and finally logging off again.

The IScraperSession interface is based on the IScraperPersist interface, through which the session can be persisted and resumed later. Provided that the session did not expire at the account service provider. More about scraper persistence is found below.

IScraperPersist

The architecture of the Subsembly XS2A API was designed to support storing and retrieving the state of the scraper contact and session objects. Thus, even an active session can be completely stored and suspended to be loaded and resumed lateron. By keeping the state on the client, this allows for a completely stateless server implementation. This is achieved through The IScraperPersist interface that is at the base of the IScraperContact and IScraperSession interfaces.

In addition to this base interface, every implementation of IScraperContact and IScraperSession is required to provide a parameterless default constructor.

Any IScraperContact or IScraperSession can easily by stored in a JSON object through the Save method. In order to recreate the saved object, a default constructed implementation can be initialized from this JSON object through the Load method.

In order to be able to recreate the correct implementation, you have to store information about the object type along with the JSON object that contains the instance state. The ScraperService class provides two convenience methods SaveObject and LoadObject that accomplish this for you.

ScraperResult

Whenever a method can return successfully, or with error, the Subsembly XS2A API uses the ScraperResult class to provide the result to the caller. Methods that return an instance of this class will never return null. Thus the caller never needs to check whether the returned value was null.

Through the ScraperResult the Subsembly XS2A API also indicates if additional information or a strong customer authentication (SCA) is required.

The static utility class ScraperJson provides methods for converting a ScraperResult to JSON.

Subsembly SEPA API

The Subsembly XS2A API references several classes from the Subsembly SEPA API.

• SepaBalance - Representation of a balance amount with sign, date, currency and more. An array of SepaBalances is returned by the DownloadBalances method.

• SepaStatement - Representation of a single CAMT account statement with optional balances.

• SepaDocument - A complete CAMT document that may contain multiple CAMT account statements. Currently, however, there is always at most a single CAMT account statement inside a CAMT document. A SepaDocument is returned by the DownloadStatement method.

All of these can be conveniently converted to JSON using the ScraperJson class.

Please refer to the Subsembly SEPA API reference documentation for a detailed descriptions of the SEPA classes.

JSON Objects

For maximum flexibility and easier serialization of parameters, the Subsembly XS2A API uses JSON objects to represent user credentials, accounts, and document file metadata. For easy handling of these JSON objects, the Subsembly XS2A API includes various JSON helper classes in the Subsembly.Json namespace, such as the JsonObject. These are similar in nature than the .NET System.Json classes, but with the advantage of being available on all .NET platforms.

The name of these JSON object data elements are based on ISO 20022 and are documented in the SUPA - Subsembly Payments File Format specification. Please refer to this specification for a detailed description of the individual data elements.

There is a static utility class ScraperJson that provides various methods for converting between Subsembly SEPA API objects and corresponding JSON objects.

JSON Account

Various methods and the IScraperSession.Accounts property use a JSON object to pass account details. The ScraperJson class provides static methods For easier conversion between SepaAccount objects and JSON account objects.

Depending on whether an account specifies a bank account or a credit card, different JSON fields must be set up.

Credit Cards

For credit cards all of the fields shown in the following example must be properly set up.

    {
        "AcctTpCd" = "CRDC"
        "AcctCcy" = "EUR"
        "AcctNo" = "1234567812345678",
    }

The AcctNo data element must be initialized with the complete credit card number (also known as primary account number or PAN). The AcctCcy data element must be initialized with the credit cards settlement currency, which is usually EUR for all currently supported credit cards.

Current Bank Accounts

For simple bank accounts all of the fields shown in the following example can be provided by the client.

    {
        "AcctTpCd" = "CACC",
        "AcctCcy" = "EUR",
        "AcctIBAN" = "DE000000000000000",
        "AcctBIC" = "AAAADEBBB",
        "AcctCtry" = "DE",
        "AcctNo" = "1234567890",
        "AcctBankCode" = "10010010"
    }

The account type AcctTpCd and account currency AcctCcy must always be provided.

If an account does have an IBAN number, then it must be provided in the AcctIBAN field. The AcctBIC is always optional, but may be provided for better performance.

If there is no AcctIBAN for an account, then the fields AcctCtry, AcctNo, and AcctBankCode must be provided. Otherwise they are optional.

Minimum required for an account with IBAN:

    {
        "AcctTpCd" = "CACC",
        "AcctCcy" = "EUR",
        "AcctIBAN" = "DE000000000000000",
    }

Minimum required for an account without IBAN:

    {
        "AcctTpCd" = "CACC",
        "AcctCcy" = "EUR",
        "AcctCtry" = "DE",
        "AcctNo" = "1234567890",
        "AcctBankCode" = "10010010"
    }

JSON Balance

The ScraperJson.ConvertBalance method pair can be used to convert a SepaBalance to JSON and vice versa. A converted JSON balance is according to the SUPA specification and may contain the fields shown in the following example.

    {
        "TpCd" = "XPCD",
        "Amt" = 1234.56,
        "CdtDbtInd" = "CRDT",
        "Ccy" = "EUR",
        "CdtLineIncl" = false,
        "CdtLineAmt" = 2000,
        "Dt" = "2017-11-28"
    }

The CdtLineIncl indicates whether the CdtLineAmt was already added to the Amt, or not. If the CdtLineIncl value is true, then the CdtLineAmt must be subtracted from the Amt in order to get the real balance value.

Please refer to the SUPA - Subsembly Payments File Format specification. for a detailed description of the other data elements.

JSON Statement Entry

An individual SepaStatementEntry can be converted to JSON using the method ScraperJson.ConvertStatementEntry. Again, the statement entry JSON conforms to the SUPA specification. The following example shows which fields may currently be contained.

    {
        "BookgDt" = "2017-11-28",
        "ValDt" = "2017-11-27",
        "TxDt" = "2017-11-27",
        "Amt" = 1234.56,
        "AmtCcy" = "EUR",
        "CdtDbtInd" = "DBIT",
        "PmtInfId" = "P12345678",
        "EndToEndId" = "Invoice 101",
        "MndtId" = "MANDATE1000",
        "CdtrId" = "DE99ZZZ0000000000",
        "RmtInf" = "Dish cleaner M4711",
        "PurpCd" = "EPAY",
        "BookgTxt" = "POS PAYMENT",
        "BankRef" = "89768723465",
        "RmtdNm" = "MALLWART INC"
        "RmtdUltmtNm" = "MALLWART LONDON",
        "RmtdAcctIBAN" = "GB29NWBK60161331926819",
        "RmtdAcctNo" = "31926819",
        "RmtdAcctBIC" = "NWBKGBAAA",
        "RmtdAcctBankCode" = "601613",
        "BookgSts" = "BOOK"
    }

Of course, usually much less fields are present. Also, additional fields may be added in the future.

JSON Credentials

A JSON object with user credentials is passed to IScraperSession.Login. Which credentials are required depends on the account service provider. See the IScraperSession.Login reference documentation for details.

JSON Contact Profile

The IScraperContact.Profile property uses a JSON object to convey profile information about the contact. Please refer to the IScraperContact.Profile reference documentation for further details.

JSON Document Metadata

Document metadata is also passed as JSON objects.

CSV Converters

Internally the screen scraper implementations of the Subsembly XS2A API try to download CSV files from the webpage and then convert these to CAMT format. Only if the account service provider does not provide CSV files, or other downloadable data files, then the screen scrapers extract the transaction data straight from the HTML page.

For additional benefit to the application developer, the internally used CSV converter classes are also made available in the public API of namespace Subsembly.Scraper.

All CSV converters implement the interface IScraperCsvConverter which converts a binary CSV data blob to a new SepaStatement that contains the parsed statement balances (if any) and statement entries.

At this time the following CSV converter classes are available:

• ScraperCsvBankOfScotland
• ScraperCsvBarclays
• ScraperCsvBunq
• ScraperCsvCommerzbank
• ScraperCsvDkbVisa
• ScraperCsvMilesMore
• ScraperCsvPostbank
• ScraperCsvVW

The CSV converters are not multi-thread safe. Hence, it is not possible to have statically registered instances of these classes. Instead for each conversion a new instance must be created.

Sample Project

The Subsembly XS2A API software development kit includes the C# source code a small sample project named ScraperCmd. This sample project is by itself already useful and can be used to get familiar with the Subsembly XS2A API.

Implementing Scrapers

At this time there is no development kit for implementing your own IScraper. In any way, currently scrapers can only be implemented in C# and must be compiled into the Subsembly.Scraper.dll. Please contact us if you are interested in developing scrapers.