FinTex

An Elixir-based client library for HBCI 2.2 and FinTS 3.0.

In 1995 German banks announced a common online banking standard called Homebanking Computer Interface (HBCI). In 2003 they published the next generation and named it Financial Transaction Services (FinTS). Today more than 2,000 German banks support HBCI/FinTS.

This client library supports both APIs, HBCI 2.2 and FinTS 3.0. It can be used to read the balance of a bank account, receive an account statement, and make a SEPA payment using PIN/TAN.

Installation

Include a dependency in your mix.exs:

deps: [
  {:fintex, "~> 0.3.0"}
]

To use FinTex modules, add use FinTex to the top of each module you plan on referencing FinTex from.

Usage

First and foremost you need bank-specific connection data of the bank you try to connect to (payment industry jargon: FinBanks). A full list of connection data can be obtained from the official DK website. Please keep in mind that these connection details are subject to change.

use FinTex
bank = %{
  blz: "12345678",            # 8 digits bank code
  url: "https://example.org", # URL of the bank server
  version: "300"              # API version
}

Ping

Some, but not all, banks support the “anonymous login” feature, so you can send a ping request:

FinTex.ping(bank)

Initialize the dialog

In order to authenticate , you need credentials to a real-life bank account (usually login and PIN). Note that repeated failed attempts to log in might cause the bank to block the bank account.

credentials = %{
  login: "username",
  pin: "secret"
}
f = FinTex.new(bank, credentials)
# %FinTex{bank: %FinTex.User.FinBank{blz: "12345678", url: "https://example.org", version: "300"}, client_system_id: "321", tan_scheme_sec_func: "999"}

Retrieve all bank accounts

Retrieve account-specific data, such as an account’s balance:

FinTex.accounts!(f, credentials) |> Enum.to_list # retrieve a list of bank accounts

Retrieve all transactions of a bank account

Request all transactions of one of the bank accounts:

FinTex.transactions!(f, credentials, account) |> Enum.to_list # retrieve a list of transactions

Make a SEPA credit transfer

A bank account contains a list of supported TAN schemes each of which can be used to make a SEPA credit transfer. Pick a sender bank account (see above), add the recipient’s bank account (IBAN/BIC) and define the details:

payment = %{
  sender_account: %{
    iban:  "DE89370400440532013000",
    bic:   "COBADEFFXXX",
    owner: "John Doe"
  },
  recipient_account: %{
    iban:  "FR1420041010050500013M02606",
    bic:   "ABNAFRPPXXX",
    owner: "Jane Doe"
  },
  amount: "1.00",
  currency: "EUR",
  purpose: "A new test payment",
  tan_scheme: %{
    sec_func: "921"
  }
}

FinTex.initiate_sepa_credit_transfer(f, credentials, payment)

Error handling

Most of the functions in this module return {:ok, result} in case of success, {:error, reason} otherwise. Those functions are also followed by a variant that ends with ! which takes the same arguments but which returns the result (without the {:ok, result} tuple) in case of success or raises an exception in case it fails.

SSL hostname verification & path validation

In order to prevent man-in-the-middle attacks it is recommended to enable hostname verification of the bank server’s SSL certificate. This security feature verifies that the server’s hostname matches the common name (CN) of the server’s SSL certificate. In addition the path validation feature checks the bank server’s SSL certificate against a list of trusted Certificate Authorities (CAs). Where this list is located depends on the local operating system, e.g. on Ubuntu a concatenated single-file list of certificates is available at /etc/ssl/certs/ca-certificates.crt. An example of how to set up both security features is included in config/config.exs.

Proxy Settings

Find sample configurations in config/config.exs that show how to set up proxy authentication and SOCKS5.

Documentation

API documentation is available at http://hexdocs.pm/fintex.

Specification

For exact information please refer to the German version of the specification. There is also an unauthorized English translation.

Copyright & License

Copyright (c) 2015-2017 Florian J. Breunig

Licensed under MIT, see LICENSE file.