Skip to content

Latest commit

 

History

History
126 lines (87 loc) · 6.4 KB

README.md

File metadata and controls

126 lines (87 loc) · 6.4 KB
Raw

HOWTO

Overview

This project connects with your bank account using Ebics standard. The project wraps a java-based command-line tool into a REST service and add features like cron and webhooks.

Setting it up successfully means, that you can

  • Read daily statements including account balance and transactions of multiple accounts
  • Trigger payments from your bank account(s)

The picture below shows the bigger picture:

Architecture

Start the service & take a look at the API

    docker run -p 8093:8093 e36io/ebics-service

Open Swagger in your browser and test the simulate service. For other APIs you need to set up and connect to your banks Ebics API.

Start the service in development and production mode

Development mode is default. Ebics-java-client does not connect to your bank but ebics documents and commands get logged.

    docker run -v $HOME/ebics./root/ebics -p 8093:8093 e36io/ebics-service

Production mode (Spring prod profile) requires Ebics to be set up. :warning: This may trigger real payments from your bank account!

    docker run -v $HOME/ebics:/root/ebics --env spring.profiles.active=prod -p 8093:8093 e36io/ebics-service

Again, open Open Swagger to test the API. All Ebics documents which are exchanged with the bank are stored in HOME/ebics/client.

Setup Ebics Configuration

Ebics (Electronic Banking Internet Communication Standard) defines the protocol and a series of document to access and exchange banking data. You need to talk to your bank first and request to provide access to the Ebics interface. Alternatively you can ask about ISO20022 or an interface to transfer Camt.053 and Pain.001 or Pain.002 files, which should be well known among banks. Most banks offer the service for free.

A crucial part to understand of Ebics is the key-exchange- roughly it works like this:

  • Generate keypair and send public to bank with the ebics client
  • You send client specific keys via a physically printed letter to the bank
  • All configurations for the setup are done in one specific file: $HOME/ebics/client/ebics.txt see ebics-template.txt

Check HOWTO for technical instructions how to set up the Ebics interface with your bank.

Supported banks and national flavours

Ebics standard was initiated by banks German/French partnership later adopted by Austria and Switzerland and by Banks across Europe. You will find many bank supporting Ebics, a general list of all banks supporting Ebics was not found.

There are national flavours regarding the data on bank transfers and bank statements, which are represented by national changes of the original Ebics XML documents. For example Switzerland:

  • In addition to a reference field (e.g. invoice 1234) you may use a dedicated "reference number" on payment slips which you don't find on the payment slips of other countries
  • Account statements, status reports are ZIP files available through separate Ebics commands. Generally it is easy to add new commands to the ebics-java-client library.

Switzerland

A national overview and selection of test interfaces for Ebics and test environments in Switzerland:

Bank URL for testing/validating more info
SIX Group validation Url
Credit Suisse test-API help
PostFinance register
Raiffeisen test-API
UBS register info
ZKB test-platform help

Other countries

Non-exhaustive examples of European banks providing Ebics information:

Adapt to national flavours

The setup process does not need to be adapted. Anyway you might need to adapt to local flavour of your country or your bank if they support different Ebics commands or have national modifications of their Ebics XML documents. This can be done in the io.element36.cash36.ebics.strategy.* package. Examples:

  • Adapt conversion between Ebics-XML documents: E.g. io.element36.cash36.ebics.strategy.implStatementCamt53_001 for mapping of daily statements to Json Response.
  • Add new commands to ebics-java-cli: look for org.kopi.ebics.interfaces.OrderType which hold commands available at the command line but which are also directly transferred to the Ebics server as commands. Look for national mapping tables if you face this issue. E.g. Switzerland and Austria
  • Genereate new ebics documents based on XSD specifications in build.gradle and generateSourcesForXsd.

You may check out www.ebics.ch, www.ebics.de. www.ebics.at, www.ebics.org.

Use the sandbox

You can use a fake banking backend by starting the sandbox as a backend, see SANDBOX.md.

Run tests

Coverage

Run & check tests TEST.md.