odoo_account_ebics/account_ebics/static/description/index.html

<!-- Generated from README.rst: edit the README, not this file. -->
<div class="section" id="ebics-banking-protocol">
<h1>EBICS Banking Protocol</h1>
<p><strong>Exchange files directly with your banks from Odoo, with no portal and nobody logging in.</strong></p>
<p>EBICS, the Electronic Banking Internet Communication Standard, is the channel European
banks open to companies that want their software to talk to the bank. Bank statements are
downloaded on a schedule and payment files are uploaded from Odoo, authenticated by your
own cryptographic keys instead of a login page.</p>
<p>This module implements that protocol in Odoo. It is developed and maintained by
Noviat, and follows each new version of Odoo, which matters when a bank connection has to
survive your next migration.</p>
<p>If you are still working out whether EBICS is the right channel for you, we explain it
without the jargon, with screen recordings of the flow in Odoo, on
<a class="reference external" href="https://www.noviat.com/ebics">noviat.com/ebics</a>.</p>
<img alt="Statements come down as camt.053 or camt.052 files, payment files go up as pain.001 or pain.008, and your keys stay on your own server" src="ebics_flow.png" style="width: 100%;" />
<div class="section" id="what-you-get">
<h2>What you get</h2>
<ul class="simple">
<li><strong>Statements that arrive on their own.</strong> A scheduled task collects the files your bank
publishes, for every account, and processes them into bank statements.</li>
<li><strong>Payments that leave the same way.</strong> A payment batch or a payment order is uploaded to
the bank in the format the bank expects, without exporting a file and re-uploading it
somewhere else.</li>
<li><strong>Several companies, one connection.</strong> Keys are held per bank rather than per company:
when fifteen entities bank with the same institution, the bank sends a single daily file
carrying fifteen statements and the module puts each statement in the right company.</li>
<li><strong>No bank credentials in Odoo.</strong> The connection uses your own company keys, generated on
your side and kept on your server. Access to the EBICS configuration is a permission of
its own ('EBICS Manager'), separate from ordinary accounting rights.</li>
<li><strong>A test mode, where your bank offers one.</strong> French banks accept a test flag, so a file
can be submitted and validated before anything is switched to production. German and
Swiss banks generally do not: there the first payment is a real one, kept small and sent
to an account you control.</li>
<li><strong>A trace of every exchange.</strong> Each download and each upload is a record, with the file
it carried, the moment it happened and the user behind it.</li>
</ul>
<p><strong>EBICS 2.4</strong>, <strong>EBICS 2.5</strong> and <strong>EBICS 3.0</strong> are supported. EBICS 3.0, the current
specification since December 2022, names what is exchanged with BTF instead of the
country-specific order type codes of EBICS 2.x. Many banks still run 2.4 or 2.5 in parallel.</p>
</div>
<div class="section" id="what-travels-over-the-link">
<h2>What travels over the link</h2>
<ul class="simple">
<li><strong>Coming in:</strong> camt.053 for the end of day statement, camt.052 for intraday movements
where the bank offers them, and national formats such as the French CFONB.</li>
<li><strong>Going out:</strong> pain.001 for credit transfers and pain.008 for direct debits, generated by
Odoo from your payment batches.</li>
</ul>
<p>We do not process MT940 statements: the format carries bank and country specific variations,
and the Odoo community stopped maintaining a general parser for it after Odoo 10. Where a
bank publishes camt.053 alongside it, which is now the usual case, that is the format to use.</p>
</div>
<div class="section" id="which-banks">
<h2>Which banks</h2>
<p>Any bank that publishes an EBICS access point can be connected. The standard is maintained by
EBICS SC, a company held by the German, French, Swiss and Austrian banking bodies
(DK, CFONB, SIX and PSA), and it is the standard corporate channel in those countries.</p>
<p>To check a specific bank before you start, joonis publishes a public directory at
<a class="reference external" href="https://www.joonis.de/en/fintech/banks/">joonis.de/en/fintech/banks</a>. Enter a BIC and it
returns the SEPA services the bank offers, the EBICS versions it supports and its Host-ID.</p>
<p>A bank missing from that directory is not a no: it is joonis' own list, not an official
register. Ask your bank whether it publishes an EBICS access point.</p>
</div>
<div class="section" id="what-it-costs">
<h2>What it costs</h2>
<p><strong>This module is free software</strong>, published under LGPL-3. There is no licence fee, no
subscription and no per-connection charge from Noviat.</p>
<p>It does however rely on the <a class="reference external" href="https://pypi.python.org/pypi/fintech">fintech</a> library from
joonis, and that library requires a <strong>commercial licence for production use</strong>: as soon as
you upload SEPA files with more than five transactions, retrieve statements older than the
last three days, or use the distributed signature. The licence is contracted directly with
joonis, not with Noviat.</p>
<p>joonis charges a one-off setup fee plus a monthly fee per EBICS user id. Current pricing is
published on
<a class="reference external" href="https://www.joonis.de/en/fintech/prices/">joonis.de</a>.</p>
<p>Your bank may also charge a subscription for the EBICS channel itself. It varies from one
bank to another and is billed by the bank, separately from anything on the Odoo side.</p>
</div>
<div class="section" id="requirements">
<h2>Requirements</h2>
<p>The module depends on two Python libraries:</p>
<ul class="simple">
<li><a class="reference external" href="https://pypi.python.org/pypi/fintech">fintech</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/cryptography">cryptography</a></li>
</ul>
<p>Because the connection needs a Python library and your key files on the server, it runs on
<strong>Odoo.sh</strong> or on an <strong>on-premise</strong> installation.</p>
<p>The EBICS test mode for uploads requires fintech 4.3.4 or higher for EBICS 2.x and fintech
7.2.7 or higher for EBICS 3.0. SWIFT 3SKey support requires fintech 6.4 or higher, and the signature passphrase
fintech 7.3.1 or higher.</p>
<div class="section" id="fintech-licence">
<h3>Fintech licence</h3>
<p>With a fintech licence, add its parameters to the <tt class="docutils literal">[options]</tt> section of the Odoo server
configuration file:</p>
<ul class="simple">
<li><tt class="docutils literal">fintech_register_name</tt>: the name of the licensee;</li>
<li><tt class="docutils literal">fintech_register_keycode</tt>: the keycode of the licensed version.</li>
</ul>
<p>Example:</p>
<pre class="literal-block">
; fintech
fintech_register_name = MyCompany
fintech_register_keycode = AB1CD-E2FG-3H-IJ4K-5L
</pre>
</div>
</div>
<div class="section" id="companion-modules">
<h2>Companion modules</h2>
<p>From this repository:</p>
<ul class="simple">
<li><strong>EBICS - Odoo Enterprise Integration</strong> (<tt class="docutils literal">account_ebics_oe</tt>): required on Odoo
Enterprise; installed automatically.</li>
<li><strong>EBICS - Bank Statement Import (OCA)</strong> (<tt class="docutils literal">account_ebics_oca_statement_import</tt>):
matches the statements processed with the OCA statement import to the right bank
journal; installed automatically with <tt class="docutils literal">account_statement_import_file</tt>.</li>
<li><strong>EBICS - Scheduled File Import</strong> (<tt class="docutils literal">account_ebics_batch</tt>): downloads and processes the
files of every connection on a schedule.</li>
<li><strong>EBICS - Batch Payments (Odoo Enterprise)</strong> (<tt class="docutils literal">account_ebics_batch_payment</tt>): uploads
the batch payments of the Odoo Enterprise <tt class="docutils literal">account_batch_payment</tt> module.</li>
<li><strong>EBICS - Payment Orders (OCA)</strong> (<tt class="docutils literal">account_ebics_payment_order</tt>): uploads the payment
orders of the OCA <tt class="docutils literal">account_payment_order</tt> module
(<a class="reference external" href="https://github.com/OCA/bank-payment">OCA/bank-payment</a>).</li>
</ul>
<p>To process the downloaded statements, install the module of each format you receive:</p>
<ul class="simple">
<li><strong>camt.053, camt.052 and camt.054</strong>: <tt class="docutils literal">account_statement_import_camt</tt>
(<a class="reference external" href="https://github.com/OCA/bank-statement-import">OCA/bank-statement-import</a>). For
camt.053, the Odoo Enterprise <tt class="docutils literal">account_bank_statement_import_camt</tt> works too.</li>
<li><strong>French CFONB</strong>: <tt class="docutils literal">account_statement_import_fr_cfonb</tt>
(<a class="reference external" href="https://github.com/OCA/l10n-france">OCA/l10n-france</a>).</li>
</ul>
<p>Recommended with several financial journals: <tt class="docutils literal">account_usability</tt>
(<a class="reference external" href="https://github.com/OCA/account-financial-tools">OCA/account-financial-tools</a>), which adds
accounting menus such as a list of all bank statements, including those downloaded by the
scheduled import.</p>
</div>
<div class="section" id="getting-your-bank-online">
<h2>Getting your bank online</h2>
<p>The configuration on the Odoo side takes fifteen to thirty minutes. What sets the pace of a
project is the bank, and it is almost never for a technical reason:</p>
<ul class="simple">
<li><strong>The bank opens the access.</strong> You receive the host ID, the address of the access point,
your partner and user identifiers, and a letter carrying the hash values of the bank's keys.</li>
<li><strong>INI and HIA.</strong> Odoo generates your key pairs for signature, authentication and encryption,
sends the public keys to the bank and produces the initialisation letters, which you print,
sign and send. The bank compares them by hand with the keys it received online.</li>
<li><strong>HPB.</strong> Once the bank has activated your access, you retrieve its public keys and compare
their hash values with the letter it sent you. That comparison is what makes the channel
trustworthy.</li>
<li><strong>The first exchange.</strong> Statements come down first. Payments follow, as a test file where
the bank supports the test flag, otherwise as a real transfer of a small amount.</li>
</ul>
<p>Count in weeks per bank rather than days, and start the contract and the paperwork early.</p>
</div>
<div class="section" id="configuration">
<h2>Configuration</h2>
<p>The menus are those of Odoo Enterprise; on Odoo Community, the application is called
<em>Invoicing</em> instead of <em>Accounting</em>.</p>
<p><strong>Who may configure.</strong> In <em>Settings &gt; Users</em>, with the developer mode active, tick
<strong>EBICS Manager</strong> in the <em>Technical</em> section of the users who maintain the EBICS
configuration.</p>
<p><strong>File formats.</strong> In <em>Accounting &gt; Configuration &gt; EBICS &gt; EBICS File Formats</em>, check that the
formats you exchange with your banks are defined; the common ones are created at
installation. A missing format can be reported on
<a class="reference external" href="https://github.com/Noviat/account_ebics/issues">GitHub</a>.</p>
<p>A download format can carry a <strong>Download Process Method</strong>, run by the <em>Process</em> button of a
downloaded file: <tt class="docutils literal">camt.053</tt>, <tt class="docutils literal">camt.052</tt>, <tt class="docutils literal">camt.054</tt> and <tt class="docutils literal">cfonb120</tt>. Each needs the
module of its format (see Companion modules); Odoo tells you which one when it is missing.</p>
<p><strong>Bank connections.</strong> In <em>Accounting &gt; Configuration &gt; EBICS &gt; EBICS Configuration</em>, create one
connection per bank contract, with the identifiers your bank sent you.</p>
<img alt="A downloaded camt.053 statement file in Odoo, before processing" src="ebics_download.png" style="width: 100%;" />
</div>
<div class="section" id="usage">
<h2>Usage</h2>
<p>The <strong>EBICS Processing</strong> menu, in the top bar of the Accounting application, lists the
downloaded and uploaded files and offers manual downloads and uploads.</p>
<p>Downloaded files are processed into bank statements. Uploads are launched from the payment
batch or the payment order. For a payment order, the format comes from its payment mode;
for a batch payment, Odoo proposes the connection's upload format and you confirm it in
the upload window.</p>
<img alt="Uploading a pain.001 SEPA credit transfer file over EBICS 3.0, with the test mode option" src="ebics_upload.png" style="width: 100%;" />
</div>
<div class="section" id="diagnostics">
<h2>Diagnostics</h2>
<p>To diagnose the connection with your bank, add this line to the Odoo server configuration
file:</p>
<pre class="literal-block">
log_handler = fintech.ebics:DEBUG
</pre>
<div class="section" id="ebics-return-codes">
<h3>EBICS return codes</h3>
<p>During an upload or a download, your bank may return an error code, for example:</p>
<pre class="literal-block">
EBICS Functional Error:
EBICS_NO_DOWNLOAD_DATA_AVAILABLE (code: 90005)
</pre>
<p>The codes are explained on <a class="reference external" href="https://www.ebics.org">ebics.org</a> and in the <tt class="docutils literal">doc</tt> folder of
this module (<tt class="docutils literal">EBICS_Annex1_ReturnCodes</tt>).</p>
</div>
<div class="section" id="electronic-distributed-signature-eds">
<h3>Electronic Distributed Signature (EDS)</h3>
<p>Where your bank supports EBICS T, Odoo prepares the file and holds no signing credentials
at all: the payment is approved in your own signing application, which is what a segregation
of duties policy usually demands. Where it does not, which happens with German and Swiss
banks, the signing key sits on your Odoo server, and you can protect it with a separate
signature passphrase that is never stored and is asked for every signed transaction.</p>
<p>External signing apps include BankingVEU
(<a class="reference external" href="https://play.google.com/store/apps/details?id=subsembly.bankingveu">Android</a>,
<a class="reference external" href="https://apps.apple.com/de/app/bankingveu/id1578694190">iOS</a>).</p>
</div>
</div>
<div class="section" id="roadmap">
<h2>Roadmap</h2>
<ul class="simple">
<li>Import externally generated keys and certificates (today only the 3SKey signature
certificate).</li>
<li>Support the SWIFT 3SKey signing JavaScript library
(<a class="reference external" href="https://www2.swift.com/3skey/help/sconnect.html">SConnect</a>).</li>
</ul>
<p>Issues and pull requests are welcome on
<a class="reference external" href="https://github.com/Noviat/account_ebics">GitHub</a>.</p>
</div>
<div class="section" id="credits">
<h2>Credits</h2>
<p>This module is developed and maintained by <a class="reference external" href="https://www.noviat.com">Noviat</a>, Odoo
integrator in Belgium, specialised in accounting and finance since 2009.</p>
<p>We implement it, we configure the connection with your banks and we support you through the
first cycles. If you want help getting a bank online, tell us which banks you use:
<a class="reference external" href="https://www.noviat.com/ebics">https://www.noviat.com/ebics</a></p>
</div>
</div>