also known as
Single European Payment Area, is a system of tools/technologies/regulations,
facilitating simplifacation of bank transfers denominated in EUR.
There are quite a few steps involved in processing
SEPA transactions from start to end. These include:
- management of EBICS users
- generation of XML documents with different formats; depending on your needs
- communicating XML files to financial institutions
- reading and parsing bank statements to perform updates in your system (if needed)
Building all of the above from scratch would take a considerable
amount of time. I have encountered a few awesome tools in ruby, that
may help us with just that, and save some of your precious time.
We will go through tools that we can use for each step, also
noting some gotchas along the way.
Management of EBICS users
First of all, to submit transactions and fetch bank statements,
we would need to have the EBICS users contracted, configured and confirmed.
This post assumes that you have done a contractual part
with your bank/financial institution and have details
at hand for the user. If not, please contact your
financial institution to provide you with an EBICS user.
EBICS users can be an SRZ type or not. The difference is that the prior
may process transactions on behalf of other customers of
the bank, given the authorization. Normal users (NON-SRZ) may only
process transactions for bank account it is associated with.
So, before asking for an EBICS user, it's good to know what your
needs are for its utilization.
Configuring and confirming an EBICS user involves 3 steps.
- Create an EBICS user with data given by your financial institution; saving keys, and other user-related data.
- Print INI file received after creation, and physically sign/send to bank
- Confirm the user when you receive
okfrom your bank
Folks at Rails Love built an awesome
gem Epics, to do just that.
Let's get started.
Setting up the user initially...
# initialize user user = Epics::Client.setup( "some-secure-password", "https://ebics.sandbox", "EBICS_HOST_ID", "EBICS_USER_ID", "EBICS_PARTNER_ID" ) # save keys (important!) user.save_keys('path/to/my.key') # submit keys to the bank # sends the signature key user.INI # sends the encryption and authentication keys user.HIA # save ini file (you will need to print, sign and send this to the bank) user.save_ini_letter( 'Bank Name', "/path/to/ini.html" )
Once your financial institution confirms that you may proceed
with the user, you will have to confirm the user again(
HBP order type)
and download public keys of the bank.
Epics gem becomes handy in this part as well.
# initialize the client you have set up above user = Epics::Client.new( File.open('/path/to/my.key'), 'some-secure-password', 'https://ebics.sandbox', 'EBICS_HOST_ID', 'EBICS_USER_ID', 'EBICS_PARTNER_ID' ) # confirm and fetch the bank's public keys user.HBP # save new keys # (you will use these keys from now on to initialize client) user.save_keys('path/to/my.key') # Try something to see if user works. # this will return available order # types for the user. However, from experience # this list is not always correct :) user.HAA
Now, we have got the EBICS user creation out of the
way, let's go through how we can build an XML from
list of transactions with correct format.
Generating XML documents consisting your transactions
Folks at SalesKing, wrote
an awesome gem Sepa King
to build XML files for direct debit and credit transactions
with legacy and latest schema format.
Note that, Sepa King will suit your needs only if you are
It is due to differences between container and non-container
XML schema, which Sepa King currently does not support.
Explaining container/non-container format is not part of this
blog post, thus we skip to usage of Sepa King.
Identify if you would like to create a debit or credit
transaction, and create an XML out of it by providing data
to Sepa King.
Have a look at their Readme,
as it is pretty straight forward.
Once you have generated the XML, we need to communicate this to
Communicating XML to financial institutions
Now we have the XML file from Sepa King, we can use the
Epics gem again to initialize our EBICS user, and communicate
this XML to the bank.
# Generate the XML file xml_file = 'your_xml_output_received_from_sepa_king...' # initialize EBICS user user = Epics::Client.new( File.open('/path/to/my.key'), 'some-secure-password', 'https://ebics.sandbox', 'EBICS_HOST_ID', 'EBICS_USER_ID', 'EBICS_PARTNER_ID' ) # Submit to bank puts user.CDD(xml_file) # for direct debit puts user.CCT(xml_file) # for direct transfer
order_id of the order.
Mind that the order type(CDD|CCT) is important to distinguish
as they are used for seperate things( direct debit vs direct transfers).
It may happen that some order types are not available for
your user, and you may get errors due to not being authorized
to perform such orders. In that case, contact your financial
institution to enable the required order types.
Fetching and parsing bank statements to perform updates
It may be that, you need to follow up with the transactions
you have submitted previously by reading bank statements, parsing
it to perform updates in your system or to send out notifications.
Parsing XML documents and digging for data using
Xpath is always
painful. To ease their pain for common good, folks at Barzahlen
wrote another awesome gem Camt Parser,
which parses bank statements and supports several formats(C52, 53, 54).
Let's get to use it.
# Initialize EBICS user user = Epics::Client.new( File.open('/path/to/my.key'), 'some-secure-password', 'https://ebics.sandbox', 'EBICS_HOST_ID', 'EBICS_USER_ID', 'EBICS_PARTNER_ID' ) # Request C53 bank statement collection_of_statements = user.C53(from_date = "2020-04-14", to_date = "2020-04-15") # Pass it to camt_parser parsed_document = CamtParser::String.parse(collection_of_statements) # You may also parse files parsed_document = CamtParser::File.parse '/path/to/your_statement.xml' # Now, you can iterate over statements parsed_document.statements.each do |statement| puts statement.account.iban statement.entries.each do |entry| # Access individual entries/bank transfers puts entry.amount puts entry.debitor.iban end end
See other accessors and how an example C53 statement looks
That's all for now.
We have gone through:
- creation and management of EBICS users
- creation of Direct Debit and Transfer XML files
- communication with banks
- parsing and using bank statements
There are lots of small stuff that we did not cover in this
post such as batch booking, differences in statements, container
and non-container XML formats. However, this should get you started.
Wish you chargeback-free statements :), and let me
know if you have any suggestions for the post or questions about SEPA.
This post has also been published @ramblingcode.
Top comments (0)