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.
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.
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
}
Some, but not all, banks support the “anonymous login” feature, so you can send a ping request:
FinTex.ping(bank)
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 account-specific data, such as an account's balance:
FinTex.accounts!(f, credentials) |> Enum.to_list # retrieve a list of bank accounts
Request all transactions of one of the bank accounts:
FinTex.transactions!(f, credentials, account) |> Enum.to_list # retrieve a list of transactions
A bank account contains a list of supported TAN schemes each of which can be used to make a SEPA payment. Pick a sender bank account (see above), add the receiver bank account (IBAN/BIC) and define the details:
payment = %{
sender_account: %{
iban: "DE89370400440532013000",
bic: "COBADEFFXXX",
owner: "John Doe"
},
receiver_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_payment(f, credentials, payment)
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.
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.
Find sample configurations in config/config.exs that show how to set up proxy authentication and SOCKS5.
API documentation is available at http://hexdocs.pm/fintex.
For exact information please refer to the German version of the specification. There is also an unauthorized English translation.
Copyright (c) 2015-2016 Florian J. Breunig
Licensed under MIT, see LICENSE file.