---
language: "de"
---
# konfipay help center
## konfipay help center
*
### [konfipay](https://wiki.konfipay.de/konfipay/konfipay.md)
konfipay ist eine Dienstleistung der cisbox GmbH, mit der Sie einfach und sicher nationale und internationale Zahlungsaufträge an Ihre Kreditinstitute und Zahl...
*
#### [konfipay (EN)](https://wiki.konfipay.de/konfipay/konfipay-en.md)
konfipay is a service of cisbox GmbH, with which you can easily and securely transfer national and international payment orders to your credit institutions and...
---
language: "de"
---
# Abschaltung der Umsatzformate MT940 und MT942 für den Kontoumsatzabruf in windata professional 9 SQL
Im November 2025 wird ein Großteil aller Kreditinstitute eine Formatänderung vornehmen. Die bisher üblichen Format MT940 und MT942 werden durch die neuen Umsatzformate „camt" (Cash Management) ersetzt. Hier stehen 3 Varianten zur Verfügung. Detaillierte Informationen erhalten Sie von Ihrem Kreditinstitut.
**Nutzen Sie windata professional 9 SQL in der aktuellen Version, übernimmt windata professional 9 SQL in vielen Bereichen die Umstellung für Sie.**
## Wie ändern sich die Formate
|-----------------------------------------|----------------------|--------------------------|
| *Art des Umsatzes* | *Altes Umsatzformat* | ***Neues Umsatzformat*** |
| *Gebuchte Umsätze* | MT940 | **camt.053** |
| *Vormerkposten (untertägige Buchungen)* | MT942 | **camt.052** |
| *Sammelbuchungsdateien* | | **camt.054** |
## Was ist noch wichtig zu wissen
* Alle windata Schnittstellen wie z.B. Addison, DATEV etc. gelten selbstverständlich weiterhin auch für camt.053.
* Änderungen des Umsatzformats im Programm werden in die Einstellungen des AutoAuszugs automatisch übernommen. Es ist kein weiteres To Do notwendig.
* Werden vom Kreditinstitut die neuen camt.053 Umsätze beim ersten Abruf rückwirkende Umsätze übergeben, sorgt windata dafür, dass Sie keine doppelten Umsätze sehen.
## Wie ändern Sie das Format in windata professional?
### HBCI / FINTS
Stellt Ihr Bankinstitut die Umsätze von MT940 auf camt.053 um und übergibt Ihnen von einem Tag auf den anderen keine MT940 Umsätze mehr, **brauchen Sie nichts zu tun**, windata professional erkennt beim Abruf das neue Format und stellt im Programm das Abrufformat automatisch auf camt.
Stellt Ihr Bankinstitut über einen Zeitraum hinweg beide Formate zur Verfügung, nehmen Sie die Änderung selbst vor oder warten, bis die Bank MT940 endgültig abschaltet und windata professional 9 SQL die Änderung automatisch vornimmt.
So ändern Sie schon beim Abruf selbst das Format von MT940 auf camt.053:
* Menü *Ausführen \> HBCI / FINTS \> Kontoumsätze abrufen \> Abrufformat* für markierte Kontenauswahl
Die Einstellung bleibt gespeichert.
**Bitte beachten Sie** : Ändern Sie das Abrufformat**nicht** mehr zurück und informieren Sie weitere windata Benutzer, dass eine Änderung auf MT940 doppelte Umsatzanzeigen verursachen kann.
### EBICS
Stellt Ihr Bankinstitut die Umsätze von MT940 auf camt.053 um und übergibt Ihnen von einem Tag auf den anderen keine MT940 Umsätze mehr, **brauchen Sie nichts zu tun**, windata professional erkennt beim Abruf das neue Format und stellt im Programm das Abrufformat automatisch auf camt.
Stellt Ihr Bankinstitut die Umsätze über einen Zeitraum hinweg beide Formate zur Verfügung, nehmen Sie die Änderung selbst vor oder warten, bis die Bank MT940 endgültig abschaltet und windata professional 9 SQL die Änderung automatisch vornimmt.
So ändern Sie schon beim Abruf selbst das Format von MT940 auf camt.053:
* Menü *Ausführen \> HBCI / FINTS \> Kontoumsätze abrufen \> Abrufformat für markierte Kontenauswahl*
Die Einstellung bleibt gespeichert.
**Bitte beachten Sie** : Ändern Sie das Abrufformat**nicht** mehr zurück und informieren Sie weitere windata Benutzer, dass eine Änderung auf MT940 doppelte Umsatzanzeigen verursachen kann.
## Wie konvertieren Sie camt.053 zurück nach MT940
Ihre Finanzbuchhaltung kann noch keine camt-Formate einlesen? Kein Problem.
Konvertieren Sie das abgerufene Format camt einfach zurück in MT940 und exportieren Sie die Umsätze wie gewohnt in das dafür vorgesehene Exportverzeichnis.
So exportieren Sie die Kontoumsätze direkt mit dem Umsatzabruf im gewünschten Exportformat. Starten Sie mit dem Menüpunkt *Ausführen \> Kontoumsätze abrufen:*
### HBCI / FINTS
Achten Sie zunächst darauf, dass das Abrufformat korrekt eingestellt ist, oder nutzen Sie die o.a. Anleitung zur manuellen Umstellung.
Setzen Sie die Markierung für *Originaldateien exportieren* und wählen Sie über die *3 Punkte* Ihre gewünschte **Konvertierung** und das für Sie passende **Exportverzeichnis** aus. Bestätigen Sie Ihre Angaben mit*OK.*
### EBICS
Achten Sie zunächst darauf, dass das Abrufformat korrekt eingestellt ist, oder nutzen Sie die o.a. Anleitung zur manuellen Umstellung.
Setzen Sie die Markierung für *Originaldateien exportieren* und wählen Sie über die *3 Punkte* Ihre gewünschte **Auswahl** , **Konvertierung** und das passende **Exportverzeichnis** aus. Beim EBICS-Umsatzabruf können Sie wählen, ob Sie die camt-Umsatzdatei zusätzlich im Original gezipt oder entpackt exportieren möchten. Bestätigen Sie mit *OK*.
## Wie konvertieren Sie camt.053 von Version 08 zurück nach Version 02 (und umgekehrt)
Ihre Finanzbuchhaltung kann noch keine camt-Formate in **Version 08** einlesen? Kein Problem.
Konvertieren Sie das abgerufene Format camt.053 Version 08 einfach zurück in camt.053 Version 02 und exportieren Sie die konvertierten Umsätze in das dafür vorgesehene Exportverzeichnis. Sie können ebenso Version 02 in Version 08 konvertieren.
Diese Konvertierung steht Ihnen für **alle Übertragungsstandards** manuell über den Menüpunkt *Import/Export \> Exportieren* zur Verfügung.
Nutzen Sie folgende Auswahl und bestätigen Sie mit *Weiter*
Treffen Sie die Auswahl der Konten, deren Kontoumsätze Sie konvertieren möchten und legen Sie anschließend über die Einstellung *Format* die gewählte Version fest. Über *Export* wählen Sie den zu exportierenden Zeitraum und bestätigen Sie mit*Weiter*. Im Folgefenster legen Sie das passende Exportverzeichnis fest.
Bitte beachten Sie, windata professional 9 SQL hat keinen Einfluss auf die camt.053 Version im Umsatzabruf. Ein Abruf beider Versionen ist bankseitig nicht möglich. Kontaktieren Sie für Detailinformationen Ihren Bankberater.
Die Version Ihrer camt.053 sehen Sie im Header (Titel) Ihrer Datei. Öffnen Sie eine exportierte Datei (rechte Maustaste) mit dem Editor, oder Ihrem Browser (z.B. Micosoft Edge)
## Mögliche Fehlerursachen
* Sie sehen nach dem Abruf mit geänderten Formaten doppelte Umsätze in den Kontoinformationen:
* Führen Sie in dem neuen Format camt.053 einen historischen Abruf durch, in dem Sie beim Umsatzabruf das Anfangsdatum passend zu den doppelten Umsätzen wählen.
* Ihre Finanzbuchhaltung nimmt die konvertierte MT940 Umsatzdatei nach dem Export nicht an.
* Bitte beachten Sie, dass die von windata konvertierte Datei dem MT940 Standard entspricht, die bisher bankseitige MT940 Umsatzdatei kann daher in kleinen Details abweichen. Melden Sie sich in einem solchen Falle bitte im windata Kundenservice unter [windata-support@cisbox.com](mailto:windata-support@cisbox.comde)
* Sie sehen die in der o.a. Anleitung dargestellten Funktionen nicht?
* Führen Sie bitte ein Update auf die aktuellste windata professional Version durch (mind. 9.3.0.6 vom 25.11.2025)
Bitte nutzen Sie bei technischen Support-Anfragen die E-Mail [windata-support@cisbox.com](mailto:windata-support@cisbox.comde) und in dringenden Fällen unseren telefonischen Kundenservice.
Möchten Sie die Antwortzeiten verkürzen, nennen Sie in Ihrer Mail direkt Lizenznummer und Lizenzversion (Reiter „*Info*") und machen Sie screenshots vom ganzen Bildschirm.
Beratungen zum Thema VoP und MT940 erhalten Sie bei uns auf Termin. Achten Sie auf die kostenlosen webinare zu wichtigen Themen rund um Ihr windata professional -- direkt im Programm.
---
language: "de"
---
# Account information
Under "Account information", you can find information about your bank accounts. Check account transactions or the current account balances:
* [Fetch transactions](https://wiki.konfipay.de/konfipay/fetch-transactions.md)
* [Account transactions](https://wiki.konfipay.de/konfipay/account-transactions.md)
* [Balances](https://wiki.konfipay.de/konfipay/balances.md)
* [Financial planning](https://wiki.konfipay.de/konfipay/financial-planning.md)
---
language: "de"
---
# Account transactions
Here you will find the account transactions for all your client's bank accounts. You may have to [fetch account transactions](https://wiki.konfipay.de/konfipay/fetch-transactions) so that current data can be seen here.
In general, you can always select the account in the upper table for which you want to see the transactions or transaction files in the lower table.
## Configure view
In the upper table, you can configure which account balances are to be displayed -- either booked account balances or booked and earmarked account balances can be displayed. Depending on your selection, the existing earmarked items will be included in the calculation of the account balances or not.
To specify how transactions should be displayed, click on the gray drop-down field in the lower table. There you can specify whether you want to see individual transactions (transaction view) or files in the form in which they are delivered by the bank (file view). You can further configure the two views according to the following sections.
## Transaction view
You can further configure the transaction view by selecting whether the data shown should be already booked transactions or earmarked items in the next gray drop-down field. You can also specify the period to be displayed. Use the lock icon to specify whether the date selection should also apply to other bank accounts. If the lock is closed, the date you selected will also be applied to the next account. If the lock is open, you can select a different date for each account.
Finally, you can specify whether batch booking files should be grouped (i.e., one booking per batch) or broken down (i.e., each individual booking from a batch separately). A grouped batch booking can also be expanded to display the individual bookings.
By clicking on `Details` in the toolbar or double-clicking on a transaction, you can view the transaction details and, for example, add a free text note that is visible to your colleagues.
By clicking `Seen` or `Unseen` in the toolbar, you can mark a transaction accordingly to indicate to yourself and your colleagues that you have already taken note of it.
By clicking on `Show payment`, you can jump directly from a transaction to the corresponding payment in konfipay, as this data is dynamically linked.
### FX/currency information
With [version 4.13.0](https://wiki.konfipay.de/konfipay/version-4-13-0-en), information on foreign currencies is also read from account statements (camt). If a transaction was executed in a foreign currency, you can use these fields to see the exchange rate used and the amounts corresponding to the transaction in the source and target currencies.
For example: If a third party transfers EUR 19.12 to your USD account, your bank will specify the source and target currencies in the transaction file, as well as the initial amount transferred of EUR 19.12 and the final amount booked of USD 20.78. You will also be informed of the exchange rate applied from EUR to USD, which is 1.0868200837. The screenshot shows how this information is displayed in konfipay in the transaction view:
Alternatively, you can open a single transaction by double-clicking or clicking on `Details` and view the same information in the transaction details:
The currency conversion information is only provided automatically for future incoming account transactions. For existing account transactions, the evaluation must be performed manually again. To do this, switch to the file view, select the corresponding account transaction file, and then select `File` \> `Process` from the menu bar.
### Create payment from transaction view
You can create payments directly from the transaction view. For example, you can transfer the balance from one account to another by selecting the account in the list, then clicking `Create payment` in the lower toolbar and then clicking `Balance transfer`. A pre-filled transfer form will then open automatically, in which you only need to specify the recipient account to transfer the balance of an account.
You can also create a transfer directly from a transaction by selecting the transaction and then clicking `Create Payment` in the lower toolbar and then `Transfer`. If the original transaction is an outgoing payment, a pre-filled transfer form with the original payment will open automatically. This allows you to easily execute a booked payment again.
If the original transaction is an incoming payment, a pre-filled transfer form will automatically open, allowing you to transfer the amount back to the original sender. This makes it easy to refund a booked incoming payment.
## File view
In the file view, the transactions are displayed in the table as they were provided by the bank, sorted in files:
Above the window, you can set the display period as in the transaction view. In the file view, you can also specify which file types should be displayed by clicking on the file type at the top right of the window (e.g., camt.053):
You can then select which file types should be displayed in the lower list. Please also note the following application example:
### PDF account statements in the file view
If your bank also provides PDF account statements via EBICS, you have the option of displaying these in the file view of the account transactions (as an alternative to fetching them as miscellaneous files -- [this article](https://wiki.konfipay.de/konfipay/fetching-account-statements-as-pdf) describes the setup steps in detail). To display the PDF statements after successful setup, click on the file type at the top right of the window and select `Electronic account statements (PDF)`:
If you have also selected other file types, all selected file types will be displayed together in the file view.
Under certain circumstances, explicit configuration of your EBICS contact may be necessary. If you are sure that your bank provides PDF account statements via EBICS, but you are not receiving any PDF account statements in konfipay, you may need to adjust the business transactions for retrieval from this EBICS contact. You can find more information for [EBICS 2.5 contacts](https://wiki.konfipay.de/konfipay/ebics-order-types#EBICSordertypes(EBICS2.5)-Download) and [EBICS 3.0 contacts](https://wiki.konfipay.de/konfipay/btf-parameters-ebics-3-0) at the following links.
### API acknowledgement status of files
You can change the API acknowledgement status of files in the file view. The toolbar functions `Mark as 'New'` or `Mark as 'Retrieved'` affect the general, client-wide acknowledgement status. The file is then marked accordingly for all API keys that do not use the [acknowledgement per API key](https://wiki.konfipay.de/konfipay/api-keys#APIkeys-AcknowledgementperAPIkey). For the corresponding API keys, transactions that are marked as *New* are delivered during the API call. Transactions that have already been manually marked as *Retrieved*are not delivered when retrieved via the API.
You can use `Key acknowledgements` in the toolbar to view and change the acknowledgement status of a file individually for each API key that does use the [acknowledgement per API key](https://wiki.konfipay.de/konfipay/api-keys#APIkeys-AcknowledgementperAPIkey). To do this, select the file for which the acknowledgement status is to be changed from the list below and click on `Key acknowledgements` in the toolbar. Then select the key for which you want to change the individual acknowledgement status and click on `Mark as 'New'` or `Mark as 'Retrieved'`.
### Transaction file download and detail view
Using the toolbar, you can display the original file with `File` and, if necessary `Download` the file.
In order to see individual bookings within a file, click on `Postings` in the toolbar. Then you can use `Details` in the toolbar or by double-clicking on a transaction to view the transaction details and, for example, add a free text note visible to your colleagues. Using `Seen` or `Unseen` In the toolbar, you can mark a transaction accordingly to indicate to you and your colleagues that you have already taken note of it:
### Conversion to MT940
Using our conversion function, you can convert camt.053 transaction files to MT940 transaction files. To do this, select the relevant camt.053 file(s) in the table below and click on `File` in the toolbar, then on `Generate`. This clones the files, so that both the original camt.053 file and the MT940 clone are retained. The generated file is automatically added to your database and you can download it via the API or from the toolbar if required (if the file is not displayed, make sure that you have activated the view of MT940 files in the upper toolbar).
You can also automate this conversion for each bank account so that all incoming camt.053 files are automatically converted to MT940 files.
The converted MT940 file does not officially come from your bank. We generate the files based on the MT940 standard, but do not guarantee that the file format is fully compatible with your system landscape.
## Export transaction data
You can export transaction data from both tables by clicking on the export icon in the top right corner of the desired table. Click on the drop-down arrow to select the export format---PDF, Excel, and CSV files are available.
The export takes into account exactly the content displayed, i.e., the groupings, filters, and sorting are taken into account and reflected in the exported file.
---
language: "de"
---
# Accounts (subordinate clients)
Within your account, you can manually create additional accounts whose database is separate from your own account. These accounts are then displayed on this page.
The function for creating a client is not available by default and must first be activated by the konfipay administrators. Please contact [vertrieb@windata.de](mailto:vertrieb@windata.de) for this purpose.
## Create account
To create a new account, click on `Add` in the toolbar. Enter a customer number and a name for the account. On the right-hand side, enter information about the administrator of the new account. A tick next to `Third party login` allows the administrator to [log in via third-party providers](https://wiki.konfipay.de/konfipay/creating-a-new-user#Creatinganewuser-Authenticationviathird-partyproviders(Microsoft)) such as Microsoft.
At the bottom, you can specify which [konfipay modules](https://wiki.konfipay.de/konfipay/modules) the users of the new account should have access to. Any account can only pass on those modules that it has licenced himself.
## Edit account
To edit an account, select it in the list of account and click on `Edit` in the toolbar. You then have the option of changing the name, customer number and module scope.
## Delete account
You can delete an account by selecting it in the list and clicking `Delete` at the top of the toolbar. After a further confirmation, the client is marked for deletion. Please note that the account will be permanently deleted after a period of 30 days. Before this period expires, the account will still be visible in the list of accounts (with a tick next to "Deletion") and you can still revoke the deletion. An account marked for deletion can not be used by its users.
---
language: "de"
---
# Activity log
The activity log documents all changes and operations within your client's database. This allows you to see at any time which user made a change and when. To call up the activity log, open the administration area. Then click on `Users` in the navigation bar on the left and then click on `Activity log` at the top of the toolbar.
You can also display details for each operation by selecting the desired activity in the list and then clicking on `Details`.
Read-only accesses are not recorded in the activity log. Changes made via the API are not recorded here, but tracked under [API communication](https://wiki.konfipay.de/konfipay/api-communication) instead.
---
language: "de"
---
# Add a FinTS/XS2A bank connection
A FinTS/XS2A bank connection is connected via the secure web form of the bank (finAPI Web Form 2.0). Unlike with EBICS, no EBICS keys and no bank letter are needed -- the login and the strong customer authentication (SCA) take place directly with the bank.
The prerequisite is that the FinTS/XS2A module is activated and the one-off finAPI setup has been carried out (see [*Setting up FinTS/XS2A*](https://wiki.konfipay.de/konfipay/setting-up-fints-xs2a)).
## Creating a bank connection
**Master data \> finTS/XS2A** is opened on the left in the navigation bar and `Add` is clicked at the top of the toolbar. The **Add bank connection** dialog opens. The following is entered there:
* **Designation** -- a freely chosen name for the bank connection, under which it can later be found again in konfipay.
* **Account types** -- the choice of which kinds of accounts are to be imported. The available options are *current account* , *savings account* , *credit card* , *loan* , *membership* , *building-society savings* and *securities*. By default, all account types are selected.
* **User assignment**-- If you assign one or more konfipay users to a bank connection, only those users will be able to use that bank connection. If you do not assign any users, all users in your client will have access to that bank connection.
Then `Continue` is clicked.
## Login in the bank's web form
konfipay now opens the finAPI web form of the bank (*login with the bank*). Depending on the configuration, it is displayed embedded directly in konfipay or called up in a separate step. The login takes place there with the online-banking credentials and the confirmation of the required strong customer authentication (e.g. by a TAN procedure).
## Automatic import of the bank accounts
After a successful login, konfipay determines the bank accounts belonging to the bank connection and -- in accordance with the selected account types -- automatically creates them in the master data. The bank connection then appears in the list with the status *Active* . The connected accounts can be viewed via the toolbar function `Bank accounts` of the bank connection.
If a fresh login is required later for the bank connection, this is shown via the status *Action required* or *Re-authentication required* and the link**Execute action** (see the section page [*FinTS/XS2A (finAPI)*](https://wiki.konfipay.de/konfipay/fints-xs2a-finapi)).
---
language: "de"
---
# Adding an EBICS contact
Setting up an [EBICS contact](https://wiki.konfipay.de/konfipay/ebics-en) is simple and easy. The EBICS wizard guides you step by step through the setup process. Start the setup process by clicking on `Add` at the toolbar.
## Enter EBICS data
In the first step of the creation process, you enter the data for the EBICS contact. The individual components are explained in the next sections.
### Connection information
In the first set-up step, you must enter the data for your EBICS contact. Assign a unique name for the EBICS contact. You must know the customer ID and participant ID of your EBICS contact and enter these as well. If you do not have this information, please contact your bank.
If you do not have the host ID and the EBICS server address, you can enter the BIC or the sort code in the corresponding field and click on the search symbol to the right of it. The connection information will then be filled in automatically and a connection test will be carried out (you may still have to enter the connection information manually if your bank's EBICS server is not listed in the konfipay database).
### Assign EBICS key
Then select which [EBICS key](https://wiki.konfipay.de/konfipay/ebics-keys) you want to use for authentication. You can create a new key by clicking on the small blue "plus" symbol. Each EBICS contact is linked to an EBICS key, which is used to authenticate authorized signatories for a client. Each EBICS key is in turn protected by a key password, which you must enter in order to carry out communication via EBICS if the password for the key is not stored in the database.
Please note that you cannot easily change the assigned EBICS key once the EBICS contact has been initialized. To be able to use a different key, the contact must be reset and reinitialized by the bank.
### Automation settings
In the lower section of the editing window, you can specify whether the [automation](https://wiki.konfipay.de/konfipay/automation) should be activated for the EBICS contact, and if so, for which actions. This is necessary if, for example, konfipay is to automatically retrieve account transactions at regular intervals. This setting can be changed at any time.
If you want to activate the automation, the EBICS password for the EBICS key must be saved. If this is not yet the case, you will be prompted to enter the EBICS password for the key before saving so that it can be saved.
On the right-hand side under `Manual operation`, you can specify whether the saved EBICS key password should still be required to be entered for manual actions such as retrieval and transfer.
The options "Password entry for manual transfer" and "Password entry for manual retrieval" determine whether the users in your client should be required to enter the EBICS password when manually transmitting or retrieving files: If the checkboxes for "Password entry for manual transfer" or "Password entry for manual retrieval" are checked, the users in your client must authenticate themselves with the password for manual actions. If the checkboxes for "Password entry for manual transfer" or "Password entry for manual retrieval" are not ticked and the password for the EBICS key is saved, the users in your client can perform manual actions without having to enter the EBICS password.
For security reasons, it is recommended to check the box for additional password entry when the password is saved.
## Initialize contact
In the next step, you must initialize the EBICS contact. In this step, konfipay makes contact with the bank's EBICS server for the first time. konfipay transmits the previously selected EBICS key, which it will later use to identify itself to the bank for each EBICS communication. The EBICS key is transmitted to the bank system. To do this, click on `Initialize contact`. If necessary, you will need to enter your EBICS key password here.
## Download Ini letters
Once initialization has been completed, you must download the so-called Ini letters (or initialization letters). The ini letters are required by your bank in order to verify the authenticity of your previously transferred key.
Print out the letters and sign them. Send the manually signed Ini letters to your bank (e.g. by fax). Once your bank has processed the letters, the bank will then activate your EBICS access.
## Retrieve bank key
Once your bank has received the Ini letters and activated your EBICS contact, you can retrieve the bank keys here. Simply click on `Retrieve bank key`. Please note that this is only possible after your bank has received the signed Ini letters and has activated your EBICS contact. Depending on the bank, this process may take some time.
## Conclusion
If all the previous steps have been successfully completed, your EBICS contact has now been successfully set up and can be used to its full extent.
## Reset initialization
You can reset the initialization of an EBICS contact by selecting the relevant EBICS contact in the list of EBICS contacts, then clicking on `Setup` in the toolbar at the top and selecting `Reset` in the top left corner. To be able to use the contact again afterwards, you must repeat the initialization process.
---
language: "de"
---
# Additional resources
Here you can access further supporting documentation for konfipay. Read articles on frequently used processes, refer to the FAQ or other information.
* [Frequent processes](https://wiki.konfipay.de/konfipay/frequently-used-processes.md)
* [FAQ (EN)](https://wiki.konfipay.de/konfipay/faq-en.md)
* [Navigation in konfipay (EN)](https://wiki.konfipay.de/konfipay/navigation-in-konfipay-en.md)
* [Tables in konfipay](https://wiki.konfipay.de/konfipay/tables-in-konfipay.md)
* [Search functionality](https://wiki.konfipay.de/konfipay/search-functionality.md)
* [Help page](https://wiki.konfipay.de/konfipay/help-page.md)
* [konfipay customer advisor](https://wiki.konfipay.de/konfipay/konfipay-customer-advisor.md)
* [Order for data change](https://wiki.konfipay.de/konfipay/order-for-data-change.md)
* [Supported banks](https://wiki.konfipay.de/konfipay/supported-banks.md)
* [Modules](https://wiki.konfipay.de/konfipay/modules.md)
* [Verification of Payee (VoP) - konfipay (EN)](https://wiki.konfipay.de/konfipay/verification-of-payee-vop-konfipay-en.md)
* [SEPA formats from November 2026 - konfipay](https://wiki.konfipay.de/konfipay/sepa-formats-from-november-2026-konfipay.md)
---
language: "de"
---
# Administration (EN)
[Landing page (administration)](https://wiki.konfipay.de/konfipay/landing-page-administration.md)
* [Accounts (subordinate clients)](https://wiki.konfipay.de/konfipay/accounts.md)
[User management](https://wiki.konfipay.de/konfipay/user-management.md)
* [Automation](https://wiki.konfipay.de/konfipay/automation.md)
* [Push Services (EN)](https://wiki.konfipay.de/konfipay/push-services-en.md)
* [Tags](https://wiki.konfipay.de/konfipay/tags.md)
[API (EN)](https://wiki.konfipay.de/konfipay/api-en.md)
* [Settings](https://wiki.konfipay.de/konfipay/api-settings.md)
[Auto delete](https://wiki.konfipay.de/konfipay/auto-delete.md)
* [Report](https://wiki.konfipay.de/konfipay/report-1.md)
---
language: "de"
---
# Administration
[Startseite (Administration)](https://wiki.konfipay.de/konfipay/startseite-administration.md)
* [Untergeordnete Mandanten](https://wiki.konfipay.de/konfipay/mandanten.md)
[Benutzerverwaltung](https://wiki.konfipay.de/konfipay/benutzerverwaltung.md)
* [Automatisierung](https://wiki.konfipay.de/konfipay/automatisierung.md)
* [Push Services](https://wiki.konfipay.de/konfipay/push-services.md)
* [Kennungen](https://wiki.konfipay.de/konfipay/kennungen.md)
[API](https://wiki.konfipay.de/konfipay/api.md)
* [Einstellungen](https://wiki.konfipay.de/konfipay/api-einstellungen.md)
[Löschfristen](https://wiki.konfipay.de/konfipay/loschfristen.md)
* [Auswertung](https://wiki.konfipay.de/konfipay/report.md)
---
language: "de"
---
# Aktivitätsprotokoll
Das Aktivitätsprotokoll dokumentiert alle Änderungen und Operationen im Datenbestand Ihres Mandanten. So können Sie jederzeit sehen, welcher Benutzer wann eine Änderung vorgenommen hat. Um das Aktivitätsprotokoll aufzurufen, öffnen Sie den Administrationsbereich. Klicken Sie dann links in der Navigations-Leiste auf `Benutzer` und dann oben in der Toolbar auf `Aktivitätsprotokoll`.
Sie können sich zu jedem Zugriff auch Details anzeigen lassen, indem Sie die gewünschte Aktivität in der Liste auswählen und dann oben in der Toolbar auf `Details` klicken.
Lesende Zugriffe werden nicht im Aktivitätsprotokoll mitgeschrieben. Änderungen, die über die API vorgenommen werden, werden nicht hier, sondern unter [API-Kommunikation](https://wiki.konfipay.de/konfipay/api-kommunikation) protokolliert.
---
language: "de"
---
# Anwendungsbeispiele für Rechteverwaltung
Nachfolgend finden Sie einige Beispiele von Anwendungsfällen, in denen das Berechtigungskonzept von konfipay genutzt wird, um spezielle Zugriffsrechte bzw. Beschränkungen umzusetzen. Durch das additive Kombinieren von Funktionsberechtigungen und Inhaltsbeschränkungen lässt sich praktisch jeder Sonderfall abbilden.
| **Beispiel** | **Berechtigungen in der Berechtigungsmatrix** |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| *Benutzer soll volle Funktionsberechtigungen erhalten, aber keine Gehaltszahlungen sehen können.* Umsetzung: * Benutzergruppe `Vollzugriff` * eigene Benutzergruppe `Kein SALA` erstellen, die keine Funktionsberechtigungen hat und Zahlungsart "SALA" einschränkt → Funktionsberechtigungen und Inhaltsbeschränkungen sind additiv, d.h. der Nutzer erhält die Berechtigungen aus der Gruppe `Vollzugriff` und die Beschränkungen aus der Gruppe `Kein SALA` |   |
| *Benutzer soll im Mandanten arbeiten können, aber alle Daten zum Bankkonto "SRZ Test Coba" nicht einsehen können.* Umsetzung: * Benutzergruppe Anwender * eigene Benutzergruppe `Kein DE89` erstellen, die keine Funktionsberechtigungen hat und Zugriff auf das Konto einschränkt → Funktionsberechtigungen und Inhaltsbeschränkungen sind additiv, d.h. der Nutzer erhält die Berechtigungen aus der Gruppe `Anwender` und die Beschränkungen aus der Gruppe `Kein DE89` |   |
| *Benutzer soll volle Funktionsberechtigungen erhalten, aber nur Daten zum Bankkonto "SRZ Test Coba" sehen können.* Umsetzung: * Benutzergruppe `Vollzugriff` * eigene Benutzergruppe `Nur DE89` erstellen, die keine Funktionsberechtigungen hat und nur Zugriff auf das Konto erlaubt → Funktionsberechtigungen und Inhaltsbeschränkungen sind additiv, d.h. der Nutzer erhält die Berechtigungen aus der Gruppe `Vollzugriff` und die Beschränkungen aus der Gruppe `Nur DE89` |   |
| *Benutzer soll keine Bankkonten mit der Kennung "Geheim" sehen können* Umsetzung: * Kennung "Geheim" erstellen und den Konten zuweisen * eigene Benutzergruppe `Kein Geheim` erstellen, die keinen Zugriff auf die Kennung "Geheim" hat → Der Benutzer kann gemäß seiner normalen Benutzergruppe arbeiten, aber sieht keine Konten/Daten, die die Kennung "Geheim" haben |    |
---
language: "de"
---
# API
Die konfipay-API (kurz für *Application Programming Interface*) ermöglicht es, auch außerhalb der konfipay-Weboberfläche mit konfipay zu kommunizieren. Dies geschieht über HTTP-Anfragen. Sie können Drittanbieter-Software wie z.B. Ihr ERP-System nutzen und damit direkt Dateien mit konfipay austauschen. Dies erlaubt eine ideale Integration der konfipay-Funktionalitäten in eine bestehende Systemlandschaft.
Die Nutzung der konfipay-API setzt technische Vorkenntnisse voraus. Die Funktionen der API sind in der [API-Dokumentation](https://portal.konfipay.de/api-docs/index.html) detailliert festgehalten. Auf der Seite [REST API](https://wiki.konfipay.de/konfipay/rest-api) und Unterseiten finden Sie eine detaillierte Erklärung des API-Konzepts für konfipay.
Unter [https://www.konfipay.de](https://www.konfipay.de/) finden Sie unter "Integrationen" eine Auflistung von Systemen, für die es u.a. schon eine Integration mit der konfipay-API gibt.
## Weiterführende Links
* [API-Schlüssel](https://wiki.konfipay.de/konfipay/api-schlussel.md)
* [API-Kommunikation](https://wiki.konfipay.de/konfipay/api-kommunikation.md)
* [konfipay sync](https://wiki.konfipay.de/konfipay/konfipay-sync.md)
* [API-Dokumentation](https://wiki.konfipay.de/konfipay/api-dokumentation.md)
---
language: "de"
---
# API communication
Here you will find a detailed log of your client's API communication. All access via the API is recorded here, so you can see when which interaction between external applications and the API took place and whether this interaction was successful.
You can completely deactivate the logging of API communication here by clicking on `Deactivate protocol`.
API communication with details of a request
## Communication details
You can select an entry in the list to see details of the corresponding API access and the full text of the request and response.
The following information is available:
| **Detail** | **Contents** |
|------------------|------------------------------------------------------|
| Timestamp | The exact time at which the communication took place |
| Method | The HTTP request method sent to the konfipay server |
| URL | The API URL used for the request |
| Request Header | The HTTP request headers set by the client |
| Request Content | The HTTP request content transmitted by the client |
| Response status | The status reported back by the server |
| Response header | The HTTP response headers set by the server |
| Response Content | The HTTP response content transmitted by the server |
---
language: "de"
---
# API documentation
The API documentation is primarily aimed at developers who want to integrate the API into an external ERP system. The API documentation is only available in English.
The functions and endpoints of the konfipay API are documented [here](https://portal.konfipay.de/api-docs/index.html) in detail for developers.
On the page [REST API (EN)](https://wiki.konfipay.de/konfipay/rest-api-en) and subpages you will find a detailed explanation of the API concept for konfipay.
---
language: "de"
---
# API-Dokumentation
Die API-Dokumentation richtet sich hauptsächlich an Entwickler, die die API in ein externes ERP-System integrieren wollen. Die API-Dokumentation ist nur auf Englisch verfügbar.
Die Funktionen und Endpunkte der konfipay-API sind für Entwickler [hier](https://portal.konfipay.de/api-docs/index.html) ausführlich dokumentiert.
Auf der Seite [REST API](https://wiki.konfipay.de/konfipay/rest-api) und Unterseiten finden Sie eine detaillierte Erklärung des API-Konzepts für konfipay.
---
language: "de"
---
# Einstellungen
Hier finden Sie Einstellungsmöglichkeiten für die Nutzung von konfipay. Die Einstellungen sind in Prüfungen und Aktionen unterteilt. Hierbei sind Prüfungen dazu da, eingereichte Daten überprüfen und ggf. Fehler melden. Aktionen verändern Daten automatisch und können dazu dienen, Fehler in eingereichten Daten zu korrigieren.
## Prüfungen
Die Prüfungen dienen dazu, syntaktische und/oder logische Fehler möglichst frühzeitig in der Zahlungsverarbeitung zu erkennen. Da verschiedene Banken unterschiedlich tolerant gegenüber Fehlern sind, können Sie jede Prüfung einzeln aktivieren oder deaktivieren, um sie an die Prüfkriterien Ihrer Bank anzupassen.
Die folgende Tabelle beschreibt die einzelnen Prüfungen im Detail:
| **Prüfung** | **Beschreibung** |
|--------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| SEPA Teilnehmerland | Prüfung, ob die IBAN der gegenüberstehenden Partei der Überweisung oder Lastschrift zu einem SEPA-Teilnehmerland gehört. Gilt nur für Zahlungsformate, welche der SEPA-Länderbeschränkung unterliegen. |
| IBAN Validierung | Validierung der IBAN durch Berechnung und Abgleich der Prüfziffer. |
| IBAN/BIC Zusammengehörigkeit | Prüfung der Zusammengehörigkeit von IBAN und BIC. |
| XML-Schema Validierung | Validierung der eingereichten Dateien gegen das referenzierte XML Schema. |
| DFÜ-Zeichensatzprüfung | Prüfung der Dateien gegen den im DFÜ-Abkommen erlaubten Zeichensatz. Bei dieser Prüfung kann zwischen dem "Standard-Zeichensatz" und dem "Erweiterten Zeichensatz" gewählt werden. Gilt nur für Dateien, welche der DFÜ-Zeichensatzbeschränkung unterliegen. |
| EPC-/DK Regeln | Prüfung von Einschränkungen und Regeln des European Payment Council und der Deutschen Kreditwirtschaft. |
| Prüfung der Kontrollwerte | Überprüfung der in der Datei angegebenen Anzahl an Zahlungen und der Kontrollsumme gegenüber den tatsächlichen Werten. |
| AZV-Dateiprüfung | Überprüfung von Struktur und Inhalt bei Auslandsüberweisungen im DTAZV-Format. |
| Doppeleinreichung | Prüfung, ob die gleiche Datei innerhalb eines definierten Zeitraums bereits eingereicht wurde. Der Zeitraum kann individuell festgelegt werden (1 bis 48 Stunden). |
| Adressprüfung für Lastschriften außerhalb der EU | Überprüfung, ob die Adresse des Zahlungspflichtigen in der Lastschrift enthalten ist. Befindet sich das kontoführende Kreditinstitut des Zahlungspflichtigen außerhalb der EU, so ist die Angabe der Adresse zwingend notwendig. |
| Prüfung der EBICS-Auftragsart | Überprüfung, ob der zur Ausführung einer Zahlung verwendete EBICS-Kontakt über die notwendige Auftragsart verfügt. |
| Ausführungsdatum | Überprüfung des Ausführungsdatums für eingereichte Zahlungsaufträge. Das Ausführungsdatum darf nicht in der Vergangenheit liegen. |
| Gläubiger-Identifikationsnummer | Überprüfung der Gläubiger-Identifikationsnummer für eingereichte Zahlungsaufträge. |
| Eindeutige Message-ID | Prüfung auf Eindeutigkeit der Message-ID. |
| Erstellung von Offline-Konten | Ist die Einstellung aktiv, wird die Erstellung von Offline-Konten über die API zugelassen. Ist die Einstellung deaktiviert, wird die Erstellung von Offline-Konten über die API abgelehnt. Offline-Konten sind weder mit einem EBICS-Zugang verknüpft noch an ein Service-Rechenzentrum angebunden, sodass keinerlei Online-Aktion möglich ist. |
| Empfängerprüfung (VOP) | Wenn [VOP (Verification of Payee)](https://wiki.konfipay.de/konfipay/verification-of-payee-vop-konfipay) aktiv ist, werden Namen von Zahlungsempfängern mit den tatsächlich bei der Empfängerbank hinterlegten Namen abgeglichen. Das Deaktivieren dieser Funktion erhöht das Risiko von Betrug erheblich. |
| Empfängerprüfung (VOP) bei Einzelzahlungen | Aktiviert oder deaktiviert VOP für Einzelzahlungen. Standardmäßig ist VOP für Einzelzahlungen obligatorisch. Diese Einstellung sollte nur nach Rücksprache mit Ihrer Bank deaktiviert werden. Wenn VOP allgemein aktiv ist (siehe Einstellung oberhalb), dann ist VOP bei Einzelzahlungen auch immer aktiviert. |
Wenn Sie die Überprüfung des Zahlungsempfängers (VOP) deaktivieren, werden Sie aufgefordert, diese Aktion explizit zu bestätigen. Dies liegt daran, dass VOP einen Schutz vor Betrug darstellt und die Deaktivierung dokumentiert werden muss. Protokolle zur Aktivierung bzw. Deaktivierung von VOP finden Sie im [Aktivitätsprotokoll](https://wiki.konfipay.de/konfipay/aktivitatsprotokoll).
## Aktionen
Die Aktionen greifen automatisch in die übertragenen Daten oder in den Datenbestand von konfipay ein, sofern bestimmte Bedingungen erfüllt sind. Die Aktionen können helfen, Workflows zu optimieren oder Fehler in den übertragenen Daten automatisch zu korrigieren.
Die Aktionen sind standardmäßig deaktiviert und müssen vom Nutzer aktiv ausgewählt werden. Die folgende Tabelle beschreibt die einzelnen Aktionen im Detail:
| **Aktion** | **Beschreibung** |
|------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Konvertierung nicht erlaubter Zeichen | Automatische Konvertierung von nicht erlaubten Zeichen (gemäß DFÜ-Abkommen) für SEPA-Zahlungen. Die Konvertierung erfolgt gemäß des [EPC SEPA Conversion Table](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best), und funktioniert in konfipay entsprechend der Konvertierungstabelle, die Sie am [unteren Ende dieser Seite](https://wiki.konfipay.de/konfipay/api-einstellungen#API-Einstellungen-KonvertierungstabellenichterlaubterZeichen) finden. |
| Bankkonten automatisch anlegen | Automatische Anlage von Bankkonten aus Zahlungsverkehrsdateien. |
| Konvertierung von COR1 in CORE | COR1 wird als Lastschrifttyp nicht mehr unterstützt. Bei Aktivierung wird der Lastschrifttyp automatisch von COR1 in CORE geändert. |
| Bankfachliche XML-Dateien formatieren | Bankfachliche XML-Dateien werden formatiert ausgegeben (Zeilenumbrüche und Einrückungen). |
| XML-Deklaration in bankfachlichen XML-Dateien | Die XML-Deklaration \ wird bankfachlichen XML-Dateien vorangestellt. |
| Konvertierung veralteter Zahlungsauftragsdateien | Zahlungsauftragsdateien im SEPA pain-Format werden automatisch auf eine akuelle Version angehoben. Die Konvertierung erfolgt ausschließlich für Versionen, welche laut DFÜ-Abkommen nicht mehr gültig sind, nach folgendem Schema: `pain.001.002.03` ➡ `pain.001.001.03` `pain.001.003.03` ➡ `pain.001.001.03` `pain.008.002.02` ➡ `pain.008.001.02` `pain.008.003.02` ➡ `pain.008.001.02` |
| Asynchrone Dateiverarbeitung | Zahlungsverkehrsdateien werden nach der Einreichung asynchron verarbeitet. Empfohlen für große Dateien (\>2 MB). |
| Konvertierung von Zahlungsauftragsdateien in länderspezifische Formate | Automatische Konvertierung von eingereichten SEPA-Zahlungen in das länderspezifische Zielformat. Das Zielformat richtet sich nach dem ISO-Ländercode des jeweiligen EBICS-Kontakts. *Hinweis:*Aufgrund inhaltlicher Einschränkungen ist die Konvertierung nicht in allen Fällen möglich. Mögliche Konvertierungen sind nachfolgenden Tabellen zu entnehmen: **Legende** 💛 Eine Konvertierung ist nicht vorgesehen. Das Original-Dokument wird zurückgegeben. ❌ Eine Konvertierung ist nicht möglich (unbekannte pain-Formate oder gravierende Unterschiede in Quelle- und Ziel-XSD-Schema). ✅ Eine Konvertierung ist möglich: u. U. je nach Belegung der Felder können Fehler auftreten. **Überweisungen**  **Lastschriften**  |
| Konvertierung von Eilüberweisungen in Echtzeitüberweisungen | Eingereichte Eilüberweisungen werden für eine noch schnellere Übertragung automatisch in Echtzeitüberweisungen konvertiert. Stellen Sie bei der Aktivierung dieser Aktion sicher, dass Ihre Bank Echtzeitüberweisungen anbietet. Das Betragslimit legt fest, bis zu welchem Überweisungsbetrag Eilüberweisungen in Echtzeitüberweisungen umwandelt. Falls das Betragslimit mit einer Zahlung überschritten wird, wird die Zahlung bei Einreichung mit einer entsprechenden Fehlermeldung abgelehnt. |
### Konvertierungstabelle nicht erlaubter Zeichen
| **Nicht erlaubtes Zeichen** | **Konvertierung zu** |
|-----------------------------|----------------------|
| `ä` | `a` |
| `ö` | `o` |
| `ü` | `u` |
| `Ä` | `A` |
| `Ö` | `O` |
| `Ü` | `U` |
| `ß (scharfes s)` | `s` |
| `& (kaufmännisches "und")` | `+ (Plus)` |
| `* (Asterisk)` | `. (Punkt)` |
| `$ (Dollarzeichen)` | `. (Punkt)` |
| `% (Prozent)` | `. (Punkt)` |
| `@ (At)` | `. (Punkt)` |
---
language: "de"
---
# API (EN)
The konfipay API (short for *Application Programming Interface*) makes it possible to communicate with konfipay outside of the konfipay website. This is done via HTTP requests. You can use third-party software, such as your ERP system to exchange files directly with konfipay. This allows ideal integration of the konfipay functionalities into an existing system landscape.
The use of the konfipay API requires prior technical knowledge. The functions of the API are described in the [API documentation](https://portal.konfipay.de/api-docs/index.html) in detail. On the page [REST API (EN)](https://wiki.konfipay.de/konfipay/rest-api-en) and subpages you will find a detailed explanation of the API concept for konfipay.
Under [https://www.konfipay.de](https://www.konfipay.de/) under "Integrations", you will find a list of systems for which there is already an integration with the konfipay API.
## Further links
* [API keys](https://wiki.konfipay.de/konfipay/api-keys.md)
* [API communication](https://wiki.konfipay.de/konfipay/api-communicaton.md)
* [konfipay sync (EN)](https://wiki.konfipay.de/konfipay/konfipay-sync-en.md)
* [API documentation](https://wiki.konfipay.de/konfipay/api-documentation.md)
---
language: "de"
---
# API Errorcodes
The API uses a structured error code system that allows for the clear identification of the error that has occurred. Each error code follows a standardized format that indicates both the category and the specific identifier of the error. This structure enables quick error assignment and efficient troubleshooting.
## Structure of Error Codes
The error codes follow the following schema:
`ERR-{Category}-{Number}`
* `ERR` -- A fixed prefix currently used for all error codes. This prefix was introduced to potentially support other message types, such as warnings, in the future (currently not available). It serves to clearly identify error messages and makes it easier to distinguish them from other codes or status messages.
* `{Category}` -- The category of the error, which describes the affected functional area or type of error. Examples of categories include `AUTH` for authentication errors, `VALIDATION` for validation errors, or `SERVER` for internal server errors.
* `{Number}` -- A unique number within the respective category. Each number is specific to a particular error and does not repeat within the same category.
This structured list of error codes allows for quick identification and efficient resolution of errors that may occur when using the API.
### List of All Error Codes and Error Messages with Explanations
#### **ERR-01-XXXX -- Category: Invalid String Parameter**
* **ERR-01-0001 - RIdNotFound:** No resource was found for the given RId.
* **ERR-01-0002 - MsgIdNotFound:** No resource was found for the given message identification.
* **ERR-01-0003 - AmbiguousMsgId:** The given message identification is not unique.
* **ERR-01-0004 - InvalidMinDate:** The specified minimum date is not a valid date.
* **ERR-01-0005 - InvalidMaxDate:** The specified maximum date is not a valid date.
* **ERR-01-0006 - InvalidPeriod:** The specified period is invalid (start date and end date must be chronological).
* **ERR-01-0007 - InvalidDate:** The specified date is not a valid date.
* **ERR-01-0008 - TransactionIdNotFound:** No resource was found for the given transaction ID.
* **ERR-01-0009 - InvalidTransactionId:** The specified transaction ID is invalid (empty or longer than 19 characters).
* **ERR-01-0010 - AmbiguousTransactionId:** The specified transaction ID is not unique.
* **ERR-01-0011 - EMailAddressOrMerchantIdNotFound:** No resource was found for the given email address or merchant ID.
* **ERR-01-0012 - MissingParameter:** A required parameter was not specified.
* **ERR-01-0013 - BankNotFound:** The specified bank was not found.
* **ERR-01-0014 - InvalidGateway:** The specified gateway is not supported. Only "SRZ," "EBICS," or a valid rId are allowed.
* **ERR-01-0015 - UnsupportedApiVersion:** The specified API version is not supported for the requested resource.
* **ERR-01-0016 - InvalidQueryStringValue:** The query string parameter contains an invalid value.
*** ** * ** ***
#### **ERR-02-XXXX -- Category: Content Validation Failed**
* **ERR-02-0000 - ContentValidationFailed:** Content validation failed. More information about the exact cause can be found in the error details.
* **ERR-02-0001 - InvalidRId:** The specified RId is invalid (empty or not 36 characters long).
* **ERR-02-0002 - InvalidXmlCharacter:** The file contains invalid characters according to the DFÜ agreement.
* **ERR-02-0003 - MissingXmlNamespace:** The XML document does not contain a valid XML namespace.
* **ERR-02-0004 - InvalidXmlNamespacePrefix:** The XML namespace prefix is invalid.
* **ERR-02-0005 - PainVersionNotSupported:** The specified PAIN version is not supported by konfipay.
* **ERR-02-0006 - PainVersionReleaseDateNotReached:** The PAIN version specified in the XML document is not (yet) valid.
* **ERR-02-0007 - SchemaValidationError:** Validation of the XML document against the XML schema failed.
* **ERR-02-0008 - InitPartyIbanChecksumValidationFailed:** The IBAN checksum of the ordering party account is invalid.
* **ERR-02-0009 - OtherPartyIbanChecksumValidationFailed:** The IBAN checksum of the beneficiary account is invalid.
* **ERR-02-0010 - InvalidIbanIsoCountryCode:** The ISO country code contained in the IBAN is invalid or not supported.
* **ERR-02-0011 - TransactionLimitExceeded:** The maximum number of transactions allowed per payment order was exceeded.
* **ERR-02-0012 - LocalInstrumentMashup:** The document contains more than one payment method.
* **ERR-02-0013 - InvalidServiceLevel:** The specified service level is invalid (urgent payments are not allowed).
* **ERR-02-0014 - InvalidExecutionDate:** The execution date is too far in the future or past.
* **ERR-02-0015 - InvalidInitiatingPartyIban:** The bank account is not assigned to the user account or is inactive.
* **ERR-02-0016 - IbanBicMismatch:** The bank code of the IBAN does not match the BIC of the financial institution.
* **ERR-02-0017 - ControlSumMismatch:** The checksum specified in the header or a payment does not match the content.
* **ERR-02-0018 - NumberOfTransactionsMismatch:** The number of transactions specified in the header or a payment does not match the content.
* **ERR-02-0019 - InvalidOtherPartyCountry:** The beneficiary account is not located in a SEPA-participating country.
* **ERR-02-0020 - InvalidBankAccountIban:** The IBAN checksum of the bank account is invalid.
* **ERR-02-0021 - InvalidBankAccountAdditionalInformation:** The content exceeds the maximum length of 500 characters.
* **ERR-02-0022 - InvalidCreditorId:** The structure of the creditor ID is invalid.
* **ERR-02-0023 - MissingRefundIdentifier:** No identifier was specified for the refund (transaction ID or RId).
* **ERR-02-0024 - InvalidRefundMemo:** The note specified for the refund is invalid (max. 255 characters).
* **ERR-02-0025 - InvalidRefundType:** The specified refund type is invalid. Possible types: "Full" or "Partial."
* **ERR-02-0026 - MissingRefundAmount:** The refund amount was not specified. The amount is required if the refund type is "Partial."
* **ERR-02-0027 - InvalidRefundAmountValue:** The specified refund amount is invalid.
* **ERR-02-0028 - InvalidRefundAmountCurrency:** The currency of the refund amount is invalid.
* **ERR-02-0029 - DtazvValidationFailed:** Validation of the DTAZV file failed.
* **ERR-02-0030 - IbanValidationFailed:** Validation of the IBAN failed.
* **ERR-02-0031 - InvalidBlz:** The specified bank code is invalid.
* **ERR-02-0032 - ContainerVersionNotSupported:** The container version specified in the XML document is not supported.
* **ERR-02-0033 - CamtVersionNotSupported:** The CAMT version specified in the XML document is not supported.
* **ERR-02-0034 - InvalidValue:** A field in the transmitted JSON or XML document contains an invalid value.
* **ERR-02-0035 - OtherPartyAddressRequired:** For payment orders outside the EU with an amount \> €1,000, the address must be provided.
* **ERR-02-0036 - DeprecatedLocalInstrument:** The file contains the unsupported direct debit type "COR1." Only "CORE" and "B2B" are supported. Automatic conversion from "COR1" to "CORE" can be enabled in the API settings.
* **ERR-02-0037 - InvalidLocalInstrument:** The file contains an invalid value in the "LocalInstrument" field for this payment type.
* **ERR-02-0038 - PaymentMessageIsNotUnique:** The Message ID of the payment file must be unique. This optional check can be disabled in the API settings.
*** ** * ** ***
#### **ERR-03-XXXX -- Category: Content Not Readable**
* **ERR-03-0001 - NoContentReceived:** No content was transferred.
* **ERR-03-0002 - InvalidContentType:** The specified content type of the transferred content is invalid.
* **ERR-03-0003 - InvalidFileStructure:** The structure of the transferred file is syntactically invalid.
* **ERR-03-0004 - InvalidXmlDocument:** The transferred content does not correspond to a well-formed XML document.
* **ERR-03-0005 - InvalidLoginCredentials:** The syntactic structure of the login information is invalid.
* **ERR-03-0006 - InvalidBankAccount:** The syntactic structure of the bank account information is invalid.
* **ERR-03-0007 - InvalidRefund:** The syntactic structure of the refund information is invalid.
* **ERR-03-0008 - ContentNotReadable:** The transferred text, JSON, or XML file does not have the expected structure.
*** ** * ** ***
#### **ERR-04-XXXX -- Category: Prerequisites Not Met**
* **ERR-04-0001 - MissingScope:** The API key used for authentication does not have the necessary permissions to access the requested resource.
* **ERR-04-0002 - SrzMappingFailed:** Determining the service data center for submitting the payment file failed.
* **ERR-04-0003 - EbicsContactMappingFailed:** No fully initialized EBICS contact was found for transmitting the payment file.
* **ERR-04-0004 - MissingEbicsOrderType:** The EBICS contact does not have the order type required for the payment type.
* **ERR-04-0005 - InvalidEbicsContact:** The EBICS contact for transmitting the payment file is not fully initialized or not configured to send payments.
* **ERR-04-0006 - InvalidPaymentStatus:** The payment status is already set to "executed." A new execution is only possible if the `force` parameter is set to "true."
* **ERR-04-0007 - BankAccountIbanAlreadyExists:** A bank account with the specified IBAN and currency already exists.
* **ERR-04-0008 - InactiveBankAccount:** The bank account is deactivated in konfipay.
* **ERR-04-0009 - UnknownBankAccount:** No bank account was found for the given IBAN.
* **ERR-04-0010 - AmbiguousRefundIdentifier:** The identifier for the refund transaction is not unique.
* **ERR-04-0011 - DuplicateFound:** The file was identified as a duplicate.
* **ERR-04-0012 - IndividualRestriction:** The payment file cannot be accepted due to an individual restriction of the financial institution.
* **ERR-04-0013 - ClientBlocked:** The client application was blocked by konfipay. More information about the exact cause can be found in the error details.
* **ERR-04-0014 - InsufficientPermissions:** The client is not authorized to perform the requested action. More information about the exact cause can be found in the error details.
*** ** * ** ***
#### **ERR-05-XXXX -- Category: Processing Error**
* **ERR-05-0000 - ProcessingError:** An error occurred while processing the request. More information about the exact cause can be found in the error details.
* **ERR-05-0001 - EbicsError:** An error occurred while performing the EBICS action.
* **ERR-05-0002 - PayPalError:** An error occurred while performing the PayPal action.
* **ERR-05-0003 - PayPalUnspecifiedError:** An unspecified error occurred during the execution of the PayPal action.
---
language: "de"
---
# API-Fehlercodes
Die API verwendet ein strukturiertes Fehlercodesystem, das eine eindeutige Identifikation des aufgetretenen Fehlers ermöglicht. Jeder Fehlercode folgt einem standardisierten Aufbau, der sowohl die Kategorie als auch die spezifische Kennung des Fehlers angibt. Dadurch lassen sich Fehler schnell zuordnen und effizient beheben.
## **Aufbau der Fehlercodes**
Die Fehlercodes folgen dem folgenden Schema:
`ERR-{Category}-{Number}`
* `ERR` -- Ein fester Präfix, der aktuell für alle Fehlercodes verwendet wird. Dieses Präfix wurde eingeführt, um künftig auch andere Meldungstypen wie Warnungen zu unterstützen (derzeit nicht der Fall). Es dient zur eindeutigen Kennzeichnung von Fehlermeldungen und erleichtert die Unterscheidung von anderen Codes oder Statusmeldungen.
* `{Category}` -- Die Kategorie des Fehlers, die den betroffenen Funktionsbereich oder die Art des Fehlers beschreibt.
* `{Number}` -- Eine eindeutige Nummer innerhalb der jeweiligen Kategorie. Jede Nummer ist spezifisch für einen bestimmten Fehler und wiederholt sich nicht innerhalb derselben Kategorie.
Diese strukturierte Liste der Fehlercodes ermöglicht eine schnelle Identifikation und effiziente Behebung von Fehlern, die während der Nutzung der API auftreten können.
### Liste aller Fehlercodes und Fehlermeldungen mit Erläuterung
#### **ERR-01-XXXX -- Kategorie: Ungültiger Zeichenketten-Parameter**
* **ERR-01-0001 - RIdNotFound:** Es wurde keine Ressource für die angegebene RId gefunden.
* **ERR-01-0002 - MsgIdNotFound:** Es wurde keine Ressource für die angegebene Nachrichtenkennung gefunden.
* **ERR-01-0003 - AmbiguousMsgId:** Die angegebene Nachrichtenkennung ist nicht eindeutig.
* **ERR-01-0004 - InvalidMinDate:** Das angegebene Mindestdatum ist kein gültiges Datum.
* **ERR-01-0005 - InvalidMaxDate:** Das angegebene Höchstdatum ist kein gültiges Datum.
* **ERR-01-0006 - InvalidPeriod:** Der angegebene Zeitraum ist ungültig (Startdatum und Enddatum müssen chronologisch sein).
* **ERR-01-0007 - InvalidDate:** Das angegebene Datum ist kein gültiges Datum.
* **ERR-01-0008 - TransactionIdNotFound:** Es wurde keine Ressource für die angegebene Transaktions-ID gefunden.
* **ERR-01-0009 - InvalidTransactionId:** Die angegebene Transaktions-ID ist ungültig (leer oder länger als 19 Zeichen).
* **ERR-01-0010 - AmbiguousTransactionId:** Die angegebene Transaktions-ID ist nicht eindeutig.
* **ERR-01-0011 - EMailAddressOrMerchantIdNotFound:** Es wurde keine Ressource für die angegebene E-Mail-Adresse oder Händler-ID gefunden.
* **ERR-01-0012 - MissingParameter:** Ein erforderlicher Parameter wurde nicht angegeben.
* **ERR-01-0013 - BankNotFound:** Die angegebene Bank wurde nicht gefunden.
* **ERR-01-0014 - InvalidGateway:** Das angegebene Gateway wird nicht unterstützt. Erlaubt sind nur „SRZ", „EBICS" oder eine gültige rId.
* **ERR-01-0015 - UnsupportedApiVersion:** Die angegebene API-Version wird für die angeforderte Ressource nicht unterstützt.
* **ERR-01-0016 - InvalidQueryStringValue:** Der Query-String-Parameter enthält einen ungültigen Wert.
*** ** * ** ***
#### **ERR-02-XXXX -- Kategorie: Inhaltsvalidierung fehlgeschlagen**
* **ERR-02-0000 - ContentValidationFailed:** Die Validierung des Inhalts ist fehlgeschlagen. Weitere Informationen zur genauen Ursache finden sich in den Fehlerdetails.
* **ERR-02-0001 - InvalidRId:** Die angegebene RId ist ungültig (leer oder nicht 36 Zeichen lang).
* **ERR-02-0002 - InvalidXmlCharacter:** Die Datei enthält gemäß DFÜ-Abkommen ungültige Zeichen.
* **ERR-02-0003 - MissingXmlNamespace:** Das XML-Dokument enthält keinen gültigen XML-Namespace.
* **ERR-02-0004 - InvalidXmlNamespacePrefix:** Das Präfix des XML-Namespaces ist ungültig.
* **ERR-02-0005 - PainVersionNotSupported:** Die angegebene PAIN-Version wird von konfipay nicht unterstützt.
* **ERR-02-0006 - PainVersionReleaseDateNotReached:** Die im XML-Dokument angegebene PAIN-Version ist (noch) nicht gültig.
* **ERR-02-0007 - SchemaValidationError:** Die Validierung des XML-Dokuments gegen das XML-Schema ist fehlgeschlagen.
* **ERR-02-0008 - InitPartyIbanChecksumValidationFailed:** Die IBAN-Prüfziffer des Auftraggeberkontos ist ungültig.
* **ERR-02-0009 - OtherPartyIbanChecksumValidationFailed:** Die IBAN-Prüfziffer des Empfängerkontos ist ungültig.
* **ERR-02-0010 - InvalidIbanIsoCountryCode:** Der im IBAN enthaltene ISO-Ländercode ist ungültig oder wird nicht unterstützt.
* **ERR-02-0011 - TransactionLimitExceeded:** Die maximal zulässige Anzahl an Transaktionen pro Zahlungsauftrag wurde überschritten.
* **ERR-02-0012 - LocalInstrumentMashup:** Das Dokument enthält mehr als eine Zahlungsart.
* **ERR-02-0013 - InvalidServiceLevel:** Das angegebene Servicelevel ist ungültig (Eilzahlungen sind nicht erlaubt).
* **ERR-02-0014 - InvalidExecutionDate:** Das Ausführungsdatum liegt zu weit in der Zukunft oder Vergangenheit.
* **ERR-02-0015 - InvalidInitiatingPartyIban:** Das Bankkonto ist dem Benutzerkonto nicht zugeordnet oder inaktiv.
* **ERR-02-0016 - IbanBicMismatch:** Der Bankcode der IBAN stimmt nicht mit dem BIC des Finanzinstituts überein.
* **ERR-02-0017 - ControlSumMismatch:** Die im Header oder einer Zahlung angegebene Prüfsumme stimmt nicht mit dem Inhalt überein.
* **ERR-02-0018 - NumberOfTransactionsMismatch:** Die im Header oder einer Zahlung angegebene Anzahl der Transaktionen stimmt nicht mit dem Inhalt überein.
* **ERR-02-0019 - InvalidOtherPartyCountry:** Das Empfängerkonto befindet sich nicht in einem SEPA-Teilnehmerland.
* **ERR-02-0020 - InvalidBankAccountIban:** Die IBAN-Prüfziffer des Bankkontos ist ungültig.
* **ERR-02-0021 - InvalidBankAccountAdditionalInformation:** Der Inhalt überschreitet die maximale Länge von 500 Zeichen.
* **ERR-02-0022 - InvalidCreditorId:** Die Struktur der Gläubiger-ID ist ungültig.
* **ERR-02-0023 - MissingRefundIdentifier:** Es wurde keine Kennung für die Rückerstattung angegeben (Transaktions-ID oder RId).
* **ERR-02-0024 - InvalidRefundMemo:** Die für die Rückerstattung angegebene Notiz ist ungültig (max. 255 Zeichen).
* **ERR-02-0025 - InvalidRefundType:** Der angegebene Rückerstattungstyp ist ungültig. Mögliche Typen: „Full" oder „Partial".
* **ERR-02-0026 - MissingRefundAmount:** Der Rückerstattungsbetrag wurde nicht angegeben. Der Betrag ist erforderlich, wenn der Rückerstattungstyp „Partial" ist.
* **ERR-02-0027 - InvalidRefundAmountValue:** Der angegebene Rückerstattungsbetrag ist ungültig.
* **ERR-02-0028 - InvalidRefundAmountCurrency:** Die Währung des Rückerstattungsbetrags ist ungültig.
* **ERR-02-0029 - DtazvValidationFailed:** Die Validierung der DTAZV-Datei ist fehlgeschlagen.
* **ERR-02-0030 - IbanValidationFailed:** Die Validierung der IBAN ist fehlgeschlagen.
* **ERR-02-0031 - InvalidBlz:** Die angegebene Bankleitzahl ist ungültig.
* **ERR-02-0032 - ContainerVersionNotSupported:** Die im XML-Dokument angegebene Containerversion wird nicht unterstützt.
* **ERR-02-0033 - CamtVersionNotSupported:** Die im XML-Dokument angegebene CAMT-Version wird nicht unterstützt.
* **ERR-02-0034 - InvalidValue:** Ein Feld im übertragenen JSON- oder XML-Dokument enthält einen ungültigen Wert.
* **ERR-02-0035 - OtherPartyAddressRequired:** Für Zahlungsvorgänge außerhalb der EU mit einem Betrag \> 1.000 € muss die Adresse angegeben werden.
* **ERR-02-0036 - DeprecatedLocalInstrument:** Die Datei enthält den nicht unterstützten Lastschrifttyp „COR1". Erlaubt sind nur „CORE" und „B2B". Die automatische Umwandlung von „COR1" in „CORE" kann in den API-Einstellungen aktiviert werden.
* **ERR-02-0037 - InvalidLocalInstrument:** Die Datei enthält einen ungültigen Wert im Feld „LocalInstrument" für diese Zahlungsart.
* **ERR-02-0038 - PaymentMessageIsNotUnique:** Die Message-ID der Zahlungsdatei muss eindeutig sein. Diese optionale Prüfung kann in den API-Einstellungen deaktiviert werden.
*** ** * ** ***
#### **ERR-03-XXXX -- Kategorie: Inhalt nicht lesbar**
* **ERR-03-0001 - NoContentReceived:** Es wurde kein Inhalt übertragen.
* **ERR-03-0002 - InvalidContentType:** Der angegebene Content-Type des Inhalts ist ungültig.
* **ERR-03-0003 - InvalidFileStructure:** Die Struktur der übertragenen Datei ist syntaktisch ungültig.
* **ERR-03-0004 - InvalidXmlDocument:** Der übertragene Inhalt entspricht keinem wohlgeformten XML-Dokument.
* **ERR-03-0005 - InvalidLoginCredentials:** Die syntaktische Struktur der Anmeldeinformationen ist ungültig.
* **ERR-03-0006 - InvalidBankAccount:** Die syntaktische Struktur der Bankkontoinformationen ist ungültig.
* **ERR-03-0007 - InvalidRefund:** Die syntaktische Struktur der Rückerstattungsinformationen ist ungültig.
* **ERR-03-0008 - ContentNotReadable:** Die übertragene Text-, JSON- oder XML-Datei entspricht nicht der erwarteten Struktur.
*** ** * ** ***
#### **ERR-04-XXXX -- Kategorie: Voraussetzungen nicht erfüllt**
* **ERR-04-0001 - MissingScope:** Der für die Authentifizierung verwendete API-Schlüssel verfügt nicht über die erforderlichen Berechtigungen, um auf die angeforderte Ressource zuzugreifen.
* **ERR-04-0002 - SrzMappingFailed:** Die Bestimmung des Service-Rechenzentrums für die Übermittlung der Zahlungsdatei ist fehlgeschlagen.
* **ERR-04-0003 - EbicsContactMappingFailed:** Es wurde kein vollständig initialisierter EBICS-Kontakt für die Übertragung der Zahlungsdatei gefunden.
* **ERR-04-0004 - MissingEbicsOrderType:** Der EBICS-Kontakt verfügt nicht über den für den Zahlungstyp erforderlichen Ordertyp.
* **ERR-04-0005 - InvalidEbicsContact:** Der EBICS-Kontakt für die Übertragung der Zahlungsdatei ist nicht vollständig initialisiert oder nicht zur Übertragung von Zahlungen konfiguriert.
* **ERR-04-0006 - InvalidPaymentStatus:** Der Status der Zahlung ist bereits auf „executed" gesetzt. Eine erneute Ausführung ist nur möglich, wenn der Parameter `force` auf „true" gesetzt ist.
* **ERR-04-0007 - BankAccountIbanAlreadyExists:** Ein Bankkonto mit der angegebenen IBAN und Währung existiert bereits.
* **ERR-04-0008 - InactiveBankAccount:** Das Bankkonto ist in konfipay deaktiviert.
* **ERR-04-0009 - UnknownBankAccount:** Es wurde kein Bankkonto für die angegebene IBAN gefunden.
* **ERR-04-0010 - AmbiguousRefundIdentifier:** Die Kennung für die Rückerstattungstransaktion ist nicht eindeutig.
* **ERR-04-0011 - DuplicateFound:** Die Datei wurde als Duplikat erkannt.
* **ERR-04-0012 - IndividualRestriction:** Die Zahlungsdatei kann aufgrund einer individuellen Einschränkung der Bank nicht akzeptiert werden.
* **ERR-04-0013 - ClientBlocked:** Die Client-Anwendung wurde von konfipay gesperrt. Weitere Informationen zur genauen Ursache finden sich in den Fehlerdetails.
* **ERR-04-0014 - InsufficientPermissions:** Der Client ist nicht berechtigt, die angeforderte Aktion auszuführen. Weitere Informationen zur genauen Ursache finden sich in den Fehlerdetails.
*** ** * ** ***
#### **ERR-05-XXXX -- Kategorie: Verarbeitungsfehler**
* **ERR-05-0000 - ProcessingError:** Während der Verarbeitung der Anfrage ist ein Fehler aufgetreten. Weitere Informationen zur genauen Ursache finden sich in den Fehlerdetails.
* **ERR-05-0001 - EbicsError:** Beim Ausführen der EBICS-Aktion ist ein Fehler aufgetreten.
* **ERR-05-0002 - PayPalError:** Beim Ausführen der PayPal-Aktion ist ein Fehler aufgetreten.
* **ERR-05-0003 - PayPalUnspecifiedError:** Während der Ausführung der PayPal-Aktion ist ein Fehler aufgetreten, der von PayPal nicht näher spezifiziert wurde.
---
language: "de"
---
# API keys
Do not store your API keys in publicly accessible places and do not pass them on. Anyone who has access to your API keys can access your accounts via the API and possibly send unauthorized payments!
Here you will find an overview of all API keys for your client. An API key is required to gain access to the konfipay API with a software application, as the API endpoints are not public.
In the overview, you can see at a glance the name of a key, whether it is active, when it was created (column: *"Timestamp"* ) and when it was last used for authentication at the API (column: *"Last used"*).
## Add or edit keys
To create a new API key, click in the toolbar on `Add` at the top left. Assign a name for the key and define the so-called scope by selecting which API endpoints the key may access. Also decide whether the acknowledgement for this API key should be carried out individually or generally (more information in the following section).
To change the name or scope for an existing key, select the API key in the list and click on `Edit` in the toolbar at the top.
Important: An API key is displayed in full only once after generation. Be sure to save it yourself in a secure location, as konfipay cannot display it again afterwards.
## Acknowledgement per API key
When creating or editing an API key, you have the option of activating the acknowledgement for the corresponding API key individually. Please note that the **activation of the individual acknowledgement can not be reversed.**
To take advantage of the acknowledgement per API key, it is required that you use a separate API key for each application connected via the API.
### Background info
Acknowledgement per API key means that an independent dataset with the status of acknowledgements is kept for the respective key when it is activated. For example, when an account transaction is retrieved via the API, the account transaction is only marked as retrieved for this individual API key. This is useful if you access your client's data via the API using different applications and the data should be complete in each application separately.
You can also activate the acknowledgement per API key for some API keys only if required. In this case, the API keys with general acknowledgement continue to access the general, client-wide acknowledgement status.
**Example:**You use two API keys to retrieve account transactions via konfipay sync and via your ERP system. If you do not use the acknowledgement per API key, the account transaction is retrieved in konfipay sync, for example, and then acknowledged. In this case, the acknowledgement applies to all applications that retrieve data via the konfipay API. If the ERP system then wants to retrieve all unacknowledged transactions, it will no longer receive any data, as the acknowledgements have already been set by konfipay sync.
To avoid such a scenario, a separate API key can be used in konfipay sync and in the ERP application, for which the acknowledgement per API key has been activated. If konfipay sync now acknowledges a retrieval, this is linked to the API key and only counts for this API key. The ERP system is therefore not affected and can acknowledge the retrieved data independently.
### File types with their own acknowledgement status
The acknowledgement status is logged in konfipay for the following file types:
| **File type** | **API end point with API documentation link** |
|---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| Account transactions | [api/v6/transaction-files](https://portal.konfipay.de/api-docs/index.html#tag/Transaction-files/operation/GetTransactionFiles) |
| PayPal transactions | [api/v6/paypal/transactions/{rid}](https://portal.konfipay.de/api-docs/index.html#tag/PayPal/operation/GetTransaction) |
| Miscellaneous files (e.g. PDF account statements) | [api/v6/documents](https://portal.konfipay.de/api-docs/index.html#tag/Documents/operation/GetDocuments) |
| PaymentProvider data | [api/v6/payment-providers/payloads/{rid}](https://portal.konfipay.de/api-docs/index.html#tag/Payment-providers/operation/GetPaymentProviderPayload) |
### Activating the acknowledgement per API key
If you activate the acknowledgement per API key for an API key, you must select the status of the acknowledgements with which you want to activate the option for the key. This status only serves as a starting point. After activation, the status of the acknowledgements for this key is decoupled from the general status. You have the following options:
* **Current status →**the status of the client-wide acknowledgement status is adopted and the retrieval is acknowledged individually for all future data records
* **All new →**all existing data records are marked as "Not retrieved"/"New" for the corresponding API key
* **All retrieved →**all available data records are marked as "Retrieved" for the corresponding API key
* **All retrieved until →**the available data records are marked as "Retrieved" up to the corresponding date for the corresponding API key, and all later available data records are marked as "Not retrieved"/"New"
When the acknowledgement is activated for each API key, the API key is briefly deactivated so that the selected status of the acknowledgements can be applied in the background. You cannot use the API key during this time. The duration varies between a few seconds and several minutes, depending on the size of the database.
### Mass change of the acknowledgement status for individual API keys
Within the konfipay user interface, you can only make mass changes to the general, client-wide acknowledgement status for files, but not for individual API keys. For individual API keys, you can only [change the acknowledgement status for each file individually](https://wiki.konfipay.de/konfipay/account-transactions#Accounttransactions-APIacknowledgementstatusoffiles). If you need to make a mass change to the acknowledgement status for individual API keys, please contact our support team at [support@konfipay.de](mailto:support@konfipay.de)
## Deactivate or delete key
If you no longer need an API key and want to ensure that it can no longer be used for access, you can deactivate or delete the key. Deletion is permanent; a deactivated key can be reactivated and used again at a later time.
To delete or deactivate an API key, select the key in the list and click on `Delete` or `Deactivate`.
## Regenerate key
You can regenerate an existing API key by selecting the key in the list and clicking on `Generate new`. As a result, the key must be re-entered in all applications that use it, as the old key then loses its validity.
Regenerating an API key is comparable to changing a password - the new password must then be re-entered on all devices.
Important: Even when a key is regenerated, an API key is displayed in full only once. Be sure to save it yourself in a secure location, as konfipay cannot display it again afterwards.
---
language: "de"
---
# API-Kommunikation
Hier finden Sie ein detailliertes Protokoll der API-Kommunikation Ihres Mandanten. Alle Zugriffe auf die API werden hier mitgeschrieben, Sie können also nachvollziehen, wann welche Interaktion von externen Applikationen mit der API stattgefunden hat und ob diese Interaktion erfolgreich war.
Sie können die Protokollierung der API-Kommunikation hier vollständig deaktivieren, indem Sie in der Toolbar oben auf `Protokoll deaktivieren` klicken.
API-Kommunikation mit Details zu einem Request
## Kommunikationsdetails
Sie können einen Eintrag in der Liste auswählen, um Details zu dem entsprechenden API-Zugriff und den Text von Request und Response vollständig zu sehen.
Die folgenden Informationen stehen dabei zur Verfügung:
| **Detail** | **Inhalt** |
|------------------|--------------------------------------------------------------------|
| Zeitstempel | Die genaue Zeit, zu der die Kommunikation stattgefunden hat |
| Methode | Die HTTP-Anfragemethode, die an den konfipay-Server gesendet wurde |
| URL | Die verwendete API-URL für die Anfrage |
| Request Header | Die vom Klienten gesetzten HTTP Request Header |
| Request Content | Der vom Klienten übertragene HTTP Request Content |
| Response Status | Der vom Server zurückgemeldete Status |
| Response Header | Die vom Server gesetzten HTTP Response Header |
| Response Content | Der vom Server übertagene HTTP Response Content |
---
language: "de"
---
# API-Schlüssel
Speichern Sie Ihre API-Schlüssel nicht an öffentlich zugänglichen Stellen und geben Sie diese nicht weiter. Wer Ihre API-Schlüssel kennt, kann Ihre Konten über die API ansteuern und ggf. nicht autorisierte Zahlungen senden!
Hier finden Sie eine Übersicht über alle API-Schlüssel Ihres Mandanten. Ein API-Schlüssel wird benötigt, um mit einer Software-Anwendung Zugang zur konfipay-API zu erhalten, da die API-Endpunkte nicht öffentlich sind.
In der Übersicht sehen Sie auf einen Blick die Bezeichnung eines Schlüssels, ob dieser aktiv ist, wann er erstellt wurde (Spalte: *"Zeitstempel"* ) und wann er zum letzten Mal zur Authentifizierung an der API verwendet wurde (Spalte: *"Letzte Verwendung"*).
## Schlüssel hinzufügen oder bearbeiten
Um einen neuen API-Schlüssel zu erstellen, klicken Sie in der Toolbar oben links auf `Hinzufügen`. Vergeben Sie eine Bezeichnung für den Schlüssel und legen Sie den sogenannten Scope fest, indem Sie auswählen, auf welche API-Endpunkte der Schlüssel zugreifen darf. Entscheiden Sie auch, ob die Quittierung für diesen API-Schlüssel einzeln oder allgemein durchgeführt werden soll (mehr Infos im folgenden Abschnitt).
Um die Bezeichnung oder den Scope für einen existierenden Schlüssel zu ändern, wählen Sie den API-Schlüssel in der Liste aus und klicken Sie oben in der Toolbar auf `Bearbeiten`.
**Wichtig:** Ein API-Schlüssel wird nach der Generierung nur ein einziges Mal vollständig angezeigt. Speichern Sie ihn unbedingt eigenständig an einem sicheren Ort, da konfipay ihn anschließend nicht erneut anzeigen kann.
## Quittierung je API-Schlüssel
Bei der Erstellung bzw. Bearbeitung eines API-Schlüssels haben Sie die Möglichkeit, die Quittierung für den entsprechenden API-Schlüssel einzeln zu aktivieren. Bitte beachten Sie, dass die Aktivierung der einzelnen Quittierung nicht mehr rückgängig gemacht werden kann.
Um die Vorteile der Quittierung je API-Schlüssel zu nutzen, ist es eine Voraussetzung, dass Sie für jede über die API verbundene Anwendung auch einen separaten API-Schlüssel verwenden.
### Hintergrund
Die Quittierung je API-Schlüssel bedeutet, dass bei Aktivierung für den jeweiligen Schlüssel ein eigenständiger Datenbestand mit dem Status von Quittierungen erzeugt wird. In diesem Fall wird z.B. bei Abruf eines Kontoumsatzes über die API der Kontoumsatz nur für diesen einzelnen API-Schlüssel als abgerufen markiert. Das ist sinnvoll, wenn Sie über verschiedene Applikationen über die API auf den Datenbestand Ihres Mandanten zugreifen, und die Daten in jeder Applikation separat vollständig sein sollen.
Sie können die Quittierung je API-Schlüssel bei Bedarf auch nur für manche API-Schlüssel aktivieren. Dann greifen die API-Schlüssel mit allgemeiner Quittierung weiterhin auf den allgemeinen, mandantenweiten Quittierungsstatus zu.
**Beispiel:**Sie nutzen zwei API-Schlüssel, um über konfipay sync und über Ihr ERP-System Kontoumsätze abzurufen. Wenn Sie die die Quittierung je API-Schlüssel nicht nutzen, wird der Kontoumsatz z.B. in konfipay sync abgerufen und danach quittiert. In diesem Fall gilt die Quittierung für alle Anwendungen welche Daten über die konfipay API beziehen. Wenn das ERP-System im Anschluss alle nicht quittierten Umsätze abrufen möchte, erhält es keine Daten mehr, da die Quittierungen von konfipay Sync im Vorfeld bereits gesetzt wurden.
Um ein solches Szenario zu vermeiden, kann in konfipay sync und in der ERP-Anwendung jeweils ein anderer API-Schlüssel verwendet werden, bei welchen die Quittierung je API-Schlüssel aktiviert wurde. Führt konfipay sync nun eine Quittierung durch, so ist diese an den API-Schlüssel gekoppelt und zählt auch nur für diesen. Das ERP-System wird somit nicht beeinflusst und kann die abgerufenen Datensätze selbstständig quittieren.
### Dateitypen mit eigenem Quittierungsstatus
Für die nachfolgenden Dateitypen wird der Quittierungsstatus in konfipay protokolliert:
| **Dateityp** | **API-Endpunkt mit Link zur API-Doku** |
|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| Kontoumsätze | [api/v6/transaction-files](https://portal.konfipay.de/api-docs/index.html#tag/Transaction-files/operation/GetTransactionFiles) |
| PayPal-Transaktionen | [api/v6/paypal/transactions/{rid}](https://portal.konfipay.de/api-docs/index.html#tag/PayPal/operation/GetTransaction) |
| Diverse Dateien (z. B. Elektronische Kontoauszüge) | [api/v6/documents](https://portal.konfipay.de/api-docs/index.html#tag/Documents/operation/GetDocuments) |
| PaymentProvider-Daten | [api/v6/payment-providers/payloads/{rid}](https://portal.konfipay.de/api-docs/index.html#tag/Payment-providers/operation/GetPaymentProviderPayload) |
### Aktivieren der Quittierung je API-Schlüssel
Wenn Sie die Quittierung je API-Schlüssel für einen API-Schlüssel aktivieren, müssen Sie auswählen, mit welchem Stand der Quittierungen sie die Option für den Schlüssel aktivieren möchten. Dieser Stand dient lediglich als Ausgangslage. Nach der Aktivierung ist der Stand der Quittierungen für diesen Schlüssel vom allgemeinen Stand entkoppelt. Sie haben folgende Optionen:
* **Aktueller Stand →**der Stand des mandantenweiten Quittierungsstatus wird übernommen, und für alle zukünftigen Datensätze wird der Abruf einzeln quittiert.
* **Alle neu →**alle vorliegenden Datensätze werden für den entsprechenden API-Schlüssel als "Nicht abgerufen"/"Neu" markiert.
* **Alle abgerufen →**alle vorliegenden Datensätze werden für den entsprechenden API-Schlüssel als "Abgerufen" markiert.
* **Alle abgerufen bis →**die vorliegenden Datensätze werden bis zu dem entsprechenden Datum für den entsprechenden API-Schlüssel als "Abgerufen" markiert, und alle späteren vorliegenden Datensätze werden als "Nicht abgerufen"/"Neu" markiert.
Bei der Aktivierung der Quittierung je API-Schlüssel wird der API-Schlüssel kurz deaktiviert, damit im Hintergrund der gewählte Stand der Quittierungen übernommen werden kann. Während dieser Zeit können Sie den API-Schlüssel nicht verwenden. Die Dauer schwankt je nach Größe des Datenbestands zwischen wenigen Sekunden und einigen Minuten.
### Massenänderung des Quittierungsstatus für einzelne API-Schlüssel
Innerhalb der konfipay-Benutzeroberfläche können Sie nur für den allgemeinen, mandantenweiten Quittierungsstatus von Dateien Massenänderungen durchführen, aber nicht den für einzelne API-Schlüssel. Für einzelne API-Schlüssel können Sie den [Quittierungsstatus nur für jede Datei einzeln verändern](https://wiki.konfipay.de/konfipay/kontoumsatze-anzeigen#Kontoums%C3%A4tzeanzeigen-API-QuittierungsstatusvonKontoumsatzdateien). Wenn eine Massenänderung des Quittierungsstatus für einzelne API-Schlüssel nötig sein sollte, kontaktieren Sie bitte unseren Support unter [support@konfipay.de](mailto:support@konfipay.de)
## Schlüssel deaktivieren oder löschen
Wenn Sie einen API-Schlüssel nicht mehr benötigen und sicherstellen wollen, dass er nicht mehr für Zugriffe genutzt werden können, können Sie den Schlüssel deaktivieren oder löschen. Eine Löschung ist permanent; ein deaktivierter Schlüssel kann zu einem späteren Zeitpunkt wieder aktiviert und wieder genutzt werden.
Um einen API-Schlüssel zu löschen bzw. zu deaktivieren, wählen Sie den Schlüssel in der Liste aus und klicken oben in der Toolbar auf `Löschen` bzw. `Deaktivieren`.
## Schlüssel neu generieren
Sie können einen existierenden API-Schlüssel erneut generieren, indem Sie den Schlüssel in der Liste auswählen und oben in der Toolbar auf `Neu generieren` klicken. Dies hat zur Folge, dass der Schlüssel in allen Anwendungen, die ihn nutzen, neu hinterlegt werden muss, da der alte Schlüssel dann seine Gültigkeit verliert.
Einen API-Schlüssel neu zu generieren, ist vergleichbar mit einer Passwortänderung - das neue Passwort muss an allen Geräten dann neu eingegeben werden.
**Wichtig:** Auch bei der Neu-Generierung wird ein API-Schlüssel nur ein einziges Mal vollständig angezeigt. Speichern Sie ihn unbedingt eigenständig an einem sicheren Ort, da konfipay ihn anschließend nicht erneut anzeigen kann.
---
language: "de"
---
# Settings
Here you will find options for using konfipay. The settings are divided into verifications and actions. Verifications are used to check submitted files and report any errors. Actions change data automatically and can be used to correct errors in submitted files.
## Verifications
The verifications are used to detect syntactical and/or logical errors as early as possible in payment processing. As different banks have different levels of tolerance towards errors, you can activate or deactivate each check individually in order to adapt it to your bank's verification criteria.
The following table describes the individual tests in detail:
| **Verification** | **Description** |
|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| SEPA participating country | Check whether the IBAN of the other party to the credit transfer or direct debit belongs to a SEPA participant country. Only applies to payment formats that are subject to the SEPA country restriction. |
| IBAN validation | Validation of the IBAN by calculating and comparing the check digit. |
| IBAN/BIC affiliation | Check that IBAN and BIC belong together. |
| XML schema validation | Validation of the submitted files against the referenced XML schema. |
| RDT character set check | Checking the files against the character set permitted in the DFÜ agreement. During this check, you can choose between the "Standard character set" and the "Extended character set". Only applies to files that are subject to the DFÜ character set restriction. |
| EPC/DK rules | Examination according to restrictions and rules of the European Payment Council (EPC) and the German Banking Industry (Deutsche Kreditwirtschaft, DK). |
| Checking the control values | Verification of the number of payments specified in the file and the checksum total against the actual values. |
| AZV file check | Checking the structure and content of international transfers in DTAZV format. |
| Double submission | Check whether the same file has already been submitted within a defined period of time. The time period can be set individually (1 to 48 hours). |
| Address verification for direct debits outside the EU | Check whether the debitor's address is included in the direct debit. If the debtor's account-holding bank is located outside the EU, the address must be provided. |
| Checking the EBICS order type | Check whether the EBICS contact used to execute a payment has the necessary order type. |
| Execution date | Checking the execution date for submitted payment orders. The execution date must not be in the past. |
| Creditor identification number | Verification of the creditor identification number for submitted payment orders. |
| Unique message ID | Check for uniqueness of the message ID. |
| Creation of offline accounts | If the setting is active, the creation of offline accounts via the API is permitted. If the setting is deactivated, the creation of offline accounts via the API is rejected. Offline accounts are neither linked to an EBICS access nor connected to a service data center, so that no online action is possible. |
| Verification of Payee (VOP) | When [VOP (Verification of Payee)](https://wiki.konfipay.de/konfipay/verification-of-payee-vop-konfipay) is active, the names of payees are compared with the names actually stored at the recipient bank. Deactivating this function significantly increases the risk of fraud. |
| Verification of Payee (VOP) for single payments | Enables or disables VOP for single payments. By default, VOP is mandatory for single payments. This setting should only be disabled after consulting your bank. If VOP is enabled in general (see setting above), then VOP is always enabled for single payments. |
If you disable Verification of Payee (VOP), you will be asked to explicitly confirm this action. This is because VOP provides protection against fraud and its deactivation must be documented. Logs for activating or deactivating VOP can be found in the [activity log](https://wiki.konfipay.de/konfipay/activity-log).
## Actions
The actions automatically intervene in the transferred files or in the database of konfipay if certain conditions are met. The actions can help to optimize workflows or automatically correct errors in the transferred data.
The actions are deactivated by default and must be actively selected by the user. The following table describes the individual actions in detail:
| **Action** | **Description** |
|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Conversion of non-permitted characters | Automatic conversion of non-permitted characters (in accordance with the DFÜ agreement) for SEPA payments. The conversion is done according to the [EPC SEPA Conversion Table](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best), and works in konfipay according to the conversion table that you can [find at the bottom of this page](https://wiki.konfipay.de/konfipay/api-settings#APIsettings-Conversiontableofnon-permittedcharacters). |
| Create bank accounts automatically | Automatic creation of bank accounts from payment transaction files submitted via API. |
| Conversion from COR1 to CORE | COR1 is no longer supported as a direct debit type. When activated, the direct debit type is automatically changed from COR1 to CORE. |
| Formatting bank-specific XML files | Bank-specific XML files are output in formatted form (line breaks and indentations). |
| XML declaration in banking XML files | The XML declaration \ is placed in front of bank-specific XML files. |
| Conversion of outdated payment order files | Payment order files in SEPA pain format are automatically upgraded to a current version. The conversion only takes place for versions that are no longer valid according to the RDT agreement, according to the following scheme: `pain.001.002.03` ➡ `pain.001.001.03` `pain.001.003.03` ➡ `pain.001.001.03` `pain.008.002.02` ➡ `pain.008.001.02` `pain.008.003.02` ➡ `pain.008.001.02` |
| Asynchronous file processing | Payment transaction files are processed asynchronously after submission. Recommended for large files (\>2 MB). |
| Conversion of payment order files into country-specific formats | Automatic conversion of submitted SEPA payments into the country-specific target format. The target format depends on the ISO country code of the respective EBICS contact. *Note:*Due to content restrictions, conversion is not possible in all cases. Possible conversions can be found in the following tables: **Legend** 💛 Conversion is not intended. The original document is returned. ❌ Conversion is not possible (unknown pain formats or serious differences in source and target XSD scheme). ✅ Conversion is possible: errors may occur depending on the assignment of the fields. **Transfers**  **Direct debits**  |
| Conversion of urgent payments to instant payments | Submitted urgent payments are automatically converted to instant payments for even faster transfers. When activating this, make sure that your bank offers instant payments. The amount limit defines the transfer amount up to which urgent payments are converted to instant payments. If the amount limit is exceeded, the payment will be rejected upon submission with a corresponding error message. |
### Conversion table of non-permitted characters
| **Non-permitted character** | **Converts to** |
|-----------------------------|-----------------|
| `ä` | `a` |
| `ö` | `o` |
| `ü` | `u` |
| `Ä` | `A` |
| `Ö` | `O` |
| `Ü` | `U` |
| `ß (sharp s)` | `s` |
| `& ("and" sign)` | `+ (plus)` |
| `* (asterisk)` | `. (dot)` |
| `$ (dollar sign)` | `. (dot)` |
| `% (percent)` | `. (dot)` |
| `@ (at)` | `. (dot)` |
---
language: "de"
---
# API-Version 4
Veröffentlicht: 24.07.2021
Dieser Artikel beschreibt die Neuerungen und Änderungen der API-Version 4 im Vergleich zur API-Version 3.1. Die technische API-Dokumentation finden Sie [hier](https://portal.konfipay.de/api-docs/index.html).
Eine Einführung einer neuen Version erfolgt, wenn durch eine Änderung die Abwärtskompatibilität der API **nicht mehr sichergestellt** werden kann. Bitte prüfen Sie vor dem Wechsel auf diese API-Version ob die Änderungen Auswirkungen auf Ihr System haben und **führen Sie die notwendigen Anpassungen** durch.
## Angabe des UTC offset in Datum/Uhrzeit
Die Angabe von der konfipay API ausgegebenen Datums- und Uhrzeitwerten erfolgt in **CEWT** (**C** entral **E** uropean **W** inter **T** ime) bzw. **CEST** (**C** entral **E** uropean **S** ummer **T** ime). Um eine automatische Umrechnung zu ermöglichen, enthalten Datums- und Uhrzeitangaben ab API-Version 4 den UTC offset. Dieser repräsentiert die Abweichung zur UTC-Zeit. Im nachfolgenden Beispiel ist zu sehen, dass die Datumsangabe im Feld **timestamp** mit der API-Version 4 den Zusatz +02:00 erhält. Dies bedeutet, dass der angegebene Datumswert 2 Stunden vor der UTC Zeit liegt. In UTC-Zeit umgerechnet wäre das Datum somit *2021-07-15T15:54:27*.
| **API-Version 3.1** | **API-Version 4** |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-15T17:54:27", "type": "pain", "paymentStatusItem": { "status": "KON_ACCEPTED_AND_QUEUED" } } | JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-15T17:54:27+02:00", "type": "pain", "paymentStatusItem": { "status": "KON_ACCEPTED_AND_QUEUED" } } |
Datums- und Uhrzeitangaben von PayPal-Transaktionen enthalten ebenfalls den UTC offset. Die Zeitzone richtet sich in diesem Fall aber nach den **in PayPal hinterlegten Ländereinstellungen** für das jeweilige PayPal-Konto und weicht somit gegebenenfalls von den von konfipay verwendeten Zeitzonen (CEWT/CEST) ab.
## Korrektur falscher Namespaces für PayPal-Transaktionen
In API-Version 3.1 wurden PayPal-Transaktionen im XML-Format mit dem falschen Namespace erzeugt. Dies wurde mit API-Version 4 behoben.
| **API-Version 3.1** | **API-Version 4** |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| XML 5d12c087-be1e-456c-a33f-4f8750fa7814 2021-07-15T18:02:28.341 TDZRPUF6Q6VL8 transaction_id T0000 General: received payment of a type not belonging to the other T00nn categories 2020-05-05T14:02:05+0000 EUR 55 -13.79 EUR ... | XML 5d12c087-be1e-456c-a33f-4f8750fa7814 2021-07-15T17:54:28+02:00 TDZRPUF6Q6VL8 transaction_id Reference Id ODR T0000 General: received payment of a type not belonging to the other T00nn categories 2020-05-05T14:02:05+0000 2014-07-11T04:03:52+0000 55 EUR -13.79 EUR ... |
## Dateinamen für Dokumente
Das **DocumentItem** -Objekt wird um das Feld **fileName**erweitert. Dieses enthält den original Dateinamen. Dieser variiert je nach Quelle der Datei:
* **Abruf über EBICS/Servicerechenzentrum**: Der Dateiname wird vom Bankrechenzentrum vergeben.
* **Import über das Portal**: Bezeichnung der Datei zum Zeitpunkt des Uploads.
Betroffene API-Endpunkte:
* Document - Camt
* /api/v4/Document/Camt
* /api/v4/Document/Camt/History
* /api/v4/Document/Camt/{rId}/Acknowledge
* /api/v4/Document/Camt/{rId}/Item
* Document - Misc
* /api/v4/Document/Misc
* /api/v4/Document/Misc/History
* /api/v4/Document/Misc/{rId}/Acknowledge
* /api/v4/Document/Misc/{rId}/Item
* Document - SWIFT MT
* /api/v4/Document/MT
* /api/v4/Document/MT/History
* /api/v4/Document/MT/{rId}/Acknowledge
* /api/v4/Document/MT/{rId}/Item
**Beispiel:**
| **API-Version 3.1** | **API-Version 4** |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "href": "api/v3.1/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-19T20:04:29.451", "iban": "DE12345678901234567890", "isNew": true, "format": "camt.053" } | JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "href": "api/v4/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-19T20:00:48+02:00", "iban": "DE12345678901234567890", "isNew": true, "format": "camt.053", "fileName": "2021-07-18_C53_DE12345678901234567890_EUR_21-00001.xml" } |
## Neuer Status: FIN_CONFIRMED
Mit [Version 3.4.0](https://windata.atlassian.net/wiki/spaces/DOCS/pages/2004910103)erfolgt die Einführung des neuen Status **FIN_CONFIRMED** für Zahlungsauftragsdateien.
Durch den mit dieser Version eingeführten Abruf und die Auswertung bankfachlicher Protokolle für den Zahlungsstatus im pain.002-Format stehen detailliertere Informationen zum bankseitigen Status einer Zahlungsauftragsdatei zur Verfügung. Der Abruf der Protokolle erfolgt über die EBICS-Auftragsarten **Z01, CRZ, CDZ, CIZ** und **XMF** . Im bisherigen Prozess der Verarbeitung von Zahlungsaufträgen war der Status **FIN_ACCEPTED** der letztmögliche, positive Status einer Zahlungsauftragsdatei. Dieser basiert auf der Rückmeldung aus dem EBICS-Kundenprotokoll (Auftragsart: HAC). Dem Status FIN_ACCEPTED kann entnommen werden, dass alle, das EBICS-Verfahren betreffenden Schritte erfolgreich abgeschlossen wurden, was aber noch kein Garant für die Ausführung der Zahlung ist.
Der neue Status FIN_CONFIRMED repräsentiert eine eindeutige, bankseitige Bestätigung zur Ausführung der angewiesenen Zahlungsaufträge. FIN_CONFIRMED löst somit FIN_ACCEPTED als finaler, positiven Status einer Zahlungsauftragsdatei ab. Aus Gründen der Abwärtskompatibilität wird der Status FIN_CONFIRMED in den API-Versionen \< 4.0 als Status FIN_ACCEPTED zurückgegeben.
Die Auftragsarten Z01, CRZ, CDZ und XML sind optional und werden nicht von jedem EBICS-Server unterstützt. Die müssen zudem für den jeweiligen EBICS-Zugang bankseitig konfiguriert und freigegeben werden. Sind diese Voraussetzungen nicht gegeben, verbleibt FIN_ACCEPTED als letztmöglicher positiver Status einer Zahlungsauftragsdatei.
| **API-Version 3.1** | **API-Version 4** |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-21T15:35:20.662", "type": "pain", "paymentStatusItem": { "status": "FIN_ACCEPTED", "uploadTimestamp": "2021-07-21T16:47:33.662", "orderID": "A1BC", "reasonCode": "TS01", "reason": "The transfer of the file was successful", "additionalInformation": "Additional information 1" } } | JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-21T15:35:20.662", "type": "pain", "paymentStatusItem": { "status": "FIN_CONFIRMED", "uploadTimestamp": "2021-07-21T16:47:33.662", "orderID": "A1BC", "reasonCode": "TS01", "reason": "The transfer of the file was successful", "additionalInformation": "Additional information 1" } } |
---
language: "de"
---
# API Version 4 (EN)
Published: 24.07.2021
This article describes the new features and changes in API version 4 compared to API version 3.1. The technical API documentation can be found [here](https://portal.konfipay.de/api-docs/index.html).
A new major version is introduced when a change means that the backward compatibility of the API can **no longer be ensured** . Before switching to this API version, please check whether the changes have an impact on your system and **make the necessary adjustments**.
## Specification of the UTC offset in date/time
The date and time values output by the konfipay API are in **CEWT** (**C** entral **E** uropean **W** inter **T** ime) or **CEST** (**C** entral **E** uropean **S** ummer **T** ime). To enable an automatic conversion, date and time values from API version 4 contain the UTC offset. This represents the deviation from UTC time. In the following example, you can see that the date specification in the **timestamp**field receives the addition +02:00 with API version 4. This means that the specified date value is 2 hours ahead of UTC time. Converted to UTC time, the date would thus be 2021-07-15T15:54:27.
| **API-Version 3.1** | **API-Version 4** |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-15T17:54:27", "type": "pain", "paymentStatusItem": { "status": "KON_ACCEPTED_AND_QUEUED" } } | JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-15T17:54:27+02:00", "type": "pain", "paymentStatusItem": { "status": "KON_ACCEPTED_AND_QUEUED" } } |
Date and time information of PayPal transactions also contain the UTC offset. In this case, however, the time zone depends on the **country settings stored in PayPal** for the respective PayPal account and thus may differ from the time zones used by konfipay (CEWT/CEST).
## Correction of wrong namespaces for PayPal transactions
In API version 3.1, PayPal transactions were generated in XML format with the wrong namespace. This has been fixed with API version 4.
| **API-Version 3.1** | **API-Version 4** |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| XML 5d12c087-be1e-456c-a33f-4f8750fa7814 2021-07-15T18:02:28.341 TDZRPUF6Q6VL8 transaction_id T0000 General: received payment of a type not belonging to the other T00nn categories 2020-05-05T14:02:05+0000 EUR 55 -13.79 EUR ... | XML 5d12c087-be1e-456c-a33f-4f8750fa7814 2021-07-15T17:54:28+02:00 TDZRPUF6Q6VL8 transaction_id Reference Id ODR T0000 General: received payment of a type not belonging to the other T00nn categories 2020-05-05T14:02:05+0000 2014-07-11T04:03:52+0000 55 EUR -13.79 EUR ... |
## File names for documents
The **DocumentItem** object is extended by the **fileName**field. The field contains the original file name. This varies with the source of the file:
* **Retrieval via EBICS/service data center**: The file name is assigned by the bank data center.
* **Import via the portal**: Name of the file at the time of upload.
Affected API endpoints:
* Document - Camt
* /api/v4/Document/Camt
* /api/v4/Document/Camt/History
* /api/v4/Document/Camt/{rId}/Acknowledge
* /api/v4/Document/Camt/{rId}/Item
* Document - Misc
* /api/v4/Document/Misc
* /api/v4/Document/Misc/History
* /api/v4/Document/Misc/{rId}/Acknowledge
* /api/v4/Document/Misc/{rId}/Item
* Document - SWIFT MT
* /api/v4/Document/MT
* /api/v4/Document/MT/History
* /api/v4/Document/MT/{rId}/Acknowledge
* /api/v4/Document/MT/{rId}/Item
**Example**:
| **API-Version 3.1** | **API-Version 4** |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "href": "api/v3.1/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-19T20:04:29.451", "iban": "DE12345678901234567890", "isNew": true, "format": "camt.053" } | JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "href": "api/v4/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-19T20:00:48+02:00", "iban": "DE12345678901234567890", "isNew": true, "format": "camt.053", "fileName": "2021-07-18_C53_DE12345678901234567890_EUR_21-00001.xml" } |
## New status: FIN_CONFIRMED
[Version 3.4.0](https://cisbox.atlassian.net/wiki/pages/createpage.action?spaceKey=DOCS&title=Version%203.4.0%20%28EN%29) introduces the new **FIN_CONFIRMED**status for payment order files.
The retrieval and processing of bank-specific logs for the payment status in pain.002 format introduced with this version provides more detailed information on the status of a payment order file on the bank side. The logs are retrieved via the EBICS order types **Z01, CRZ, CDZ, CIZ** and **XMF** . In the previous process of processing payment orders, the **FIN_ACCEPTED**status was the last possible positive status of a payment order file. This is based on the feedback from the EBICS customer log (order type: HAC). The FIN_ACCEPTED status indicates that all steps relating to the EBICS procedure have been successfully completed, but this does not guarantee that the payment will be executed.
The new FIN_CONFIRMED status represents a clear, bank-side confirmation of the execution of the instructed payment orders. FIN_CONFIRMED thus replaces FIN_ACCEPTED as the final, positive status of a payment order file. For backward compatibility, the FIN_CONFIRMED status is returned as FIN_ACCEPTED status in API versions \< 4.0.
The order types Z01, CRZ, CDZ and XML are optional and are not supported by every EBICS server. They must also be configured and released for the respective EBICS access by the bank. If these requirements are not met, FIN_ACCEPTED remains as the last possible positive status of a payment order file.
| **API-Version 3.1** | **API-Version 4** |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-21T15:35:20.662", "type": "pain", "paymentStatusItem": { "status": "FIN_ACCEPTED", "uploadTimestamp": "2021-07-21T16:47:33.662", "orderID": "A1BC", "reasonCode": "TS01", "reason": "The transfer of the file was successful", "additionalInformation": "Additional information 1" } } | JSON { "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814", "timestamp": "2021-07-21T15:35:20.662", "type": "pain", "paymentStatusItem": { "status": "FIN_CONFIRMED", "uploadTimestamp": "2021-07-21T16:47:33.662", "orderID": "A1BC", "reasonCode": "TS01", "reason": "The transfer of the file was successful", "additionalInformation": "Additional information 1" } } |
---
language: "de"
---
# API-Version 5
Veröffentlicht: 14.05.2022
Dieser Artikel beschreibt die Neuerungen und Änderungen der API-Version 5 im Vergleich zur API-Version 4. Die technische API-Dokumentation finden Sie [hier](https://portal.konfipay.de/api-docs/index.html).
Eine Einführung einer neuen Version erfolgt, wenn durch eine Änderung die Abwärtskompatibilität der API **nicht mehr sichergestellt** werden kann. Bitte prüfen Sie vor dem Wechsel auf diese API-Version ob die Änderungen Auswirkungen auf Ihr System haben und **führen Sie die notwendigen Anpassungen** durch.
## Neue API-Endpunkte
Mit der API-Version 5.0 erfolgt die Einführung neuer API-Endpunkte. Folgende Endpunkte wurden hinzugefügt oder um neue Funktionalitäten erweitert:
| **Neue/erweiterte API-Endpunkte** | **Kurzbeschreibung** | **API-Dokumentation** |
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `Account` | Dieser Endpunkt erlaubt nun auch die Verwaltung von anderen Mandanten, d.h. unter anderem die Anlage, Bearbeitung oder Löschung von Mandanten. Die Nutzung der neuen API-Endpunkte zur Erstellung und Verwaltung anderer Mandanten ist Integrationspartnern der windata GmbH voraus. Zur nutzung ist eine vorherige Freischaltung Ihres Mandanten erforderlich. Für weitere Informationen hierzu, wenden Sie sich bitte an den windata Kundenservice. | [konfipay api dokumentation - Account](https://portal.konfipay.de/api-docs/index.html) |
| `User` | Dieser neue Endpunkt macht die Nutzerverwaltung innerhalb eines Mandanten per API möglich. Von Anlage über Datenänderung bis zur Einladung von Nutzern stehen nun die meisten Funktionen zur Verfügung, die auch in der konfipay-Weboberfläche verfügbar sind. | [konfipay api dokumentation - User](https://portal.konfipay.de/api-docs/index.html) |
| `UserGroup` | Dieser neue Endpunkt erlaubt den Abruf der vorhandenen Benutzergruppen und deren Mitglieder. Die Berechtigungen der Benutzergruppen werden im aktuellen Umfang der API nicht abgedeckt (weder lesend noch schreibend). | [konfipay api dokumentation - UserGroup](https://portal.konfipay.de/api-docs/index.html) |
Vorhandene API-Schlüssel verfügen **nicht über die Berechtigungen** für die neuen API-Endpunkte. Diese müssen für jeden [Schlüssel erst aktiviert](https://cisbox.atlassian.net/wiki/pages/createpage.action?spaceKey=DOCS&title=API-Schl%C3%BCssel) werden.
## Anpassungen im Bereich der Bankkonten
Die Informationen zum Kontoinhaber eines Bankkontos werden ab dieser Version im neuen Unterelement `accountHolder` dargestellt. Dazu gehören der Name (Element: `name`) des Kontoinhabers, die Gläubiger-ID (Element: `creditorId`) und die Adresse (Element: `postalAddress`). Im Rahmen der Angleichung an den ISO 20022-Standard wurde die Adresse zudem in deren Bestandteile untergliedert:
* Straße (Element: `street`)
* Hausnummer (Element: `buildingNumber`)
* Postfach (Element: `postBox`)
* Postleitzahl (Element: `postCode`)
* Ort (Element: `town`)
* Land (Element: `country`)
Das Bankkonto selbst wurde ebenfalls um weitere Felder ergänzt:
* Kontonummer (Element: `accountNumber`)
* Bankleitzahl (Element: `bankCodeNational`)
* BIC (`bankCodeInternational`) ergänzt.
**Beispiel:**
| **API-Version 4** | **API-Version 5** |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JSON { "iban": "DE12345678901234567890", "description": "Description1", "creditorId": "DE98ZZZ09999999999", "accountHolderName": "Alice Mayer", "postalAddress": "Example street 1, 12345 Somewhere", "additionalInformation": "Additional information 1" } | JSON { "iban": "DE12345678901234567890", "accountNumber": "12345678", "bankCodeNational": "11223344", "bankCodeInternational": "ABCDEFG1CBA", "description": "Description1", "additionalInformation": "Additional information 1", "accountHolder": { "name": "Alice Mayer", "creditorId": "DE98ZZZ09999999999", "postalAddress": { "street": "Examplestreet1", "postBox": "12 45 68", "buildingNumber": "12", "postCode": "12345", "town": "ExampleTown1", "country": "DE" } } } |
Alle aktuell in konfipay hinterlegten Adressen für Kontoinhaber werden über die API **nicht mehr abgebildet**. Diese Änderung gilt auch rückwirkend für die API-Versionen 2.0 bis 4.0.
Das für die API-Versionen 2.0 und 4.0 verwendete Element`postalAddress` wird bei \[POST\] und \[PUT\]-Requests ignoriert und somit nicht gespeichert. In den Antwortnachrichten wird das Feld ebenfalls nicht mehr zurückgegeben.
---
language: "de"
---
# API Version 5 (EN)
Published: 14.05.2022
This article describes the new features and changes in API version 5 compared to API version 4. The technical API documentation can be found [here](https://portal.konfipay.de/api-docs/index.html).
A new version is introduced when a change means that the backward compatibility of the API **can no longer be ensured** . Before switching to this API version, please check whether the changes have an impact on your system and **make the necessary adjustments**.
## New API endpoints
API version 5.0 introduces new API endpoints. The following endpoints have been added or extended with new functionalities:
| **New/extended API endpoints** | **Brief description** | **API documentation** |
|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `Account` | This endpoint now also allows the management of other clients, i.e. among other things the creation, editing or deletion of clients. The use of the new API endpoints for the creation and administration of other clients is only possible for integration partners of windata GmbH in advance. For the use, a prior activation of your client is required. For further information, please contact the windata customer service. | [konfipay api documentation - Account](https://portal.konfipay.de/api-docs/index.html) |
| `User` | This new endpoint makes user management within a client possible via API. From creation to data modification to the invitation of users, most of the functions are now available that are also available in the konfipay web interface. | [konfipay api documentation - User](https://portal.konfipay.de/api-docs/index.html) |
| `UserGroup` | This new endpoint allows retrieving the existing user groups and their members. The permissions of the user groups are not covered in the current scope of the API (neither read nor write). | [konfipay api documentation - UserGroup](https://portal.konfipay.de/api-docs/index.html) |
Existing API keys **do not have the permissions** for the new API endpoints. The necessary permissions must first be activated for each key.
## Adjustments for account holder and address of bank accounts
From this version on, the information about the account holder of a bank account is stored in a new sub-element `accountHolder` displayed. This includes the name (Element: `name`)of the account holder, the creditor ID (element: `creditorId`) and the address (element: `postalAddress`). As part of the alignment with the ISO 20022 standard, the address was also divided into its components:
* Street (Element: `street`)
* House number (element: `buildingNumber`)
* Postal code (element: `postCode`)
* Place (Element: `town`)
* Country (Element: `country`)
**Example:**
| **API version 4** | **API version 5** |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JSON { "iban": "DE12345678901234567890", "description": "Description1", "creditorId": "DE98ZZZ09999999999", "accountHolderName": "Alice Mayer", "postalAddress": "Example street 1, 12345 Somewhere", "additionalInformation": "Additional information 1" } | JSON { "iban": "DE12345678901234567890", "accountNumber": "12345678", "bankCodeNational": "11223344", "bankCodeInternational": "ABCDEFG1CBA", "description": "Description1", "additionalInformation": "Additional information 1", "accountHolder": { "name": "Alice Mayer", "creditorId": "DE98ZZZ09999999999", "postalAddress": { "street": "Examplestreet1", "buildingNumber": "12", "postCode": "12345", "town": "ExampleTown1", "country": "DE" } } } |
All addresses currently stored in konfipay for account holders will be transferred via API **no longer shown**. This change also applies retroactively to API versions 2.0 to 4.0.
The element used for API versions 2.0 and 4.0.`postalAddress` is ignored in \[POST\] and \[PUT\] requests, the specified address is not stored. In the response messages the field is also no longer returned.
---
language: "de"
---
# API-Version 6
Veröffentlicht: 05.03.2025
Dieser Artikel beschreibt die Neuerungen und Änderungen der API-Version 6 im Vergleich zur API-Version 5. Die technische API-Dokumentation finden Sie [hier](https://portal.konfipay.de/api-docs/index.html).
Eine Einführung einer neuen Version erfolgt, wenn durch eine Änderung die Abwärtskompatibilität der API **nicht mehr sichergestellt** werden kann. Bitte prüfen Sie vor dem Wechsel auf diese API-Version ob die Änderungen Auswirkungen auf Ihr System haben und **führen Sie die notwendigen Anpassungen** durch.
## Ziele
Mit der Veröffentlichung von **API-Version 6** haben wir uns bewusst dazu entschieden, tiefgreifende strukturelle Änderungen vorzunehmen. Diese Version enthält deutlich mehr Anpassungen als ein üblicher API-Versionswechsel. Statt inkrementelle Änderungen über viele kleinere Updates hinweg zu verteilen, haben wir die Gelegenheit genutzt, so viele Neuerungen wie möglich in einem einzigen großen Schritt zusammenzuführen.
Unser Ziel war es, die API **skalierbarer** , **effizienter** und **zukunftssicherer**zu gestalten. Während unsere Plattform weiter wächst, steigen auch die Anforderungen an unsere Infrastruktur und die Erwartungen unserer Nutzer. Um diesen Herausforderungen gerecht zu werden, haben wir zentrale Funktionen implementiert, die Leistung, Zuverlässigkeit und Flexibilität verbessern.
Wir veröffentlichen neue API-Versionen nur, wenn wir es als absolut notwendig erachten. Dabei verfolgen wir das Ziel, in einem solchen Schritt möglichst viele Änderungen zu bündeln. So stellen wir sicher, dass unsere Kunden nicht durch häufige Migrationsaufwände belastet werden und eine API-Version über einen langen Zeitraum genutzt werden kann, ohne an Aktualität zu verlieren.
## Wichtige Neuerungen
1. **Paging** : Um die Antwortzeiten zu verkürzen und den Datentransfer zu optimieren, führen wir Paging in unserer API ein. Anstatt alle Daten auf einmal zurückzugeben, liefert API Version 6 die Informationen in kleineren, handlichen Paketen von 100 Einträgen pro Seite. Dies ermöglicht eine effizientere Datenverarbeitung sowohl auf der Server- als auch auf der Client-Seite, was zu schnelleren Ladezeiten und einer verbesserten Gesamtleistung führt. Weitere Informationen hierzu finden Sie im Abschnitt [Paging](https://wiki.konfipay.de/konfipay/api-version-6#API-Version6-Paging).
2. **Rate Limiting** : Um eine faire und zuverlässige Nutzung für alle Nutzer sicherzustellen, führen wir ein Ratenbegrenzungssystem (Rate Limiting) ein. Dieses System schützt unsere Infrastruktur vor Überlastung und sorgt gleichzeitig dafür, dass alle Nutzer von gleichbleibender Leistung profitieren können. Weitere Informationen hierzu finden Sie im Abschnitt [Rate Limiting](https://wiki.konfipay.de/konfipay/api-version-6#API-Version6-RateLimiting).
3. **Fokus auf JSON:** Ab API-Version 6 entfällt die Unterstützung für XML (`application/xml`, `text/xml`). Unsere API verarbeitet und liefert Daten künftig ausschließlich im JSON-Format (`application/json`). Diese Entscheidung wurde getroffen, da sich JSON als Standard für REST-APIs etabliert hat und die Fokussierung auf ein einheitliches Format eine effizientere Wartung sowie schnellere Weiterentwicklungen ermöglicht. Weitere Informationen hierzu finden Sie im Abschnitt [Datenformate](https://wiki.konfipay.de/konfipay/api-version-6#API-Version6-Datenformate).
## Warum diese Änderungen wichtig sind
Unser Ziel mit Version 6 ist es, eine API zu entwickeln, die sich **nahtlos skalieren** lässt, während sowohl das Datenvolumen als auch der Nutzerdurchsatz steigt. Diese Verbesserungen sorgen dafür, dass die API auch bei wachsendem Datenbestand und steigender Nutzeraktivität eine zuverlässige, schnelle und effiziente Dienstleistung erbringt. Durch die Ausrichtung unserer API an **Branchengrundsätzen** bieten wir Entwicklern eine konsistente und stabile Grundlage für zukünftige Entwicklungen.
Zusammengefasst ist **API Version 6** ein Schritt in Richtung einer robusteren Plattform, die den sich wandelnden Anforderungen unserer Nutzer gerecht wird und größere Datenmengen sowie erhöhten Traffic bewältigen kann, ohne die Leistung zu beeinträchtigen. Wir sind überzeugt, dass diese Änderungen nicht nur die aktuelle Nutzererfahrung verbessern, sondern auch die Weichen für weiteres Wachstum und Erfolg in der Zukunft stellen.
## Alle Änderungen im Überblick
### Generelle Änderungen
#### Paging
Mit der neuen Version unserer API wurde Paging für **alle** API-Endpunkte eingeführt, die eine Liste von Elementen zurückgeben, um die Abfrage großer Datenmengen effizienter zu gestalten. Standardmäßig werden bei einer Anfrage **100** Einträge pro Seite zurückgegeben, wobei diese Zahl über den Parameter `pageSize` auf bis zu 1000 Einträge erhöht werden kann. Über den Parameter `pageNumber` kann festgelegt werden, welche Seite der Ergebnisse abgerufen wird. Der zurückgegebene Inhalt wird nun in einem Wrapper-Element bereitgestellt, wobei die eigentlichen Daten im Element `results` enthalten sind. Das Wrapper-Element selbst liefert zusätzliche Informationen wie die Anzahl der Einträge pro Seite, die aktuelle Seite, die Gesamtanzahl der Seiten und die Gesamtzahl aller Elemente über alle Seiten hinweg. Im folgenden Beispiel sehen Sie die Struktur der neuen Paging-Antwort:
JSON
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalItems": 2,
"links": [
{
"href": "https://portal.konfipay.de/api/v6/Example?pageNumber=1&pageSize=100",
"rel": "self",
"method": "GET"
}
],
"results": [
. . .
]
Bisher wurden Listen in einer verschachtelten Struktur zurückgegeben und waren in einem übergeordneten Element beinhaltet.
Beispiel (übergeordnetes Element: `documentItems`)
JSON
{
"documentItems": [
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"href": "api/v5.0/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-27T09:33:43+01:00",
"iban": "DE12345678901234567890",
"isNew": true,
"format": "camt.053",
"fileName": "2025-02-26_C53_DE12345678901234567890_EUR_21-00001.xml"
},
{
"rId": "fa727310-3072-4abc-a982-b511b8b81108",
"href": "api/v5.0/Document/Camt/fa727310-3072-4abc-a982-b511b8b81108",
"timestamp": "2025-02-27T10:45:56+01:00",
"iban": "DE12345678901234567890",
"isNew": true,
"format": "camt.053",
"fileName": "2025-02-27_C53_DE12345678901234567890_EUR_21-00002.xml"
}
]
}
Mit der Einführung von Paging wird auf diese zusätzliche Ebene verzichtet. Listen werden in diesem Fall direkt im `results` Element zurückgegeben. Diese Änderung erstreckt sich auf alle Stellen der API.
#### Rate Limiting
Um eine ausgewogene Verteilung der Ressourcen sicherzustellen, haben wir in unserer API standardmäßige Rate-Limiting-Werte implementiert:
* **Öffentliche Endpunkte (z.B. Authentifizierung)**: 100 Anfragen pro Minute
* **Authentifizierte Endpunkte**: 1000 Anfragen pro Minute
Diese Limits verhindern eine Überlastung der Ressourcen und gewährleisten eine stabile Leistung der API. Sollten Ihre Anforderungen über diese Standardlimits hinausgehen, bieten wir Ihnen die Möglichkeit, die Rate-Limits auf Anfrage individuell zu erhöhen. Senden Sie hierzu bitte eine entsprechende Anfrage an [support@konfipay.de](mailto:support@konfipay.de).
Basierend auf der aktuellen API-Nutzung werden wir bereits einige Kunden zur Veröffentlichung auf höhere Limits angeheben, um eine unterbrechungsfreie Nutzung sicherzustellen.
**Wichtig**: Diese Anpassung gilt API-weit und betrifft nicht nur die API-Version 6, sondern alle Versionen der API. Die Einführung des Rate Limiting erfolgt zeitgleich mit der Veröffentlichung der API-Version 6, ist jedoch von dieser unabhängig.
Wird ein Limit überschritten, antwortet der Server mit dem HTTP-Statuscode `429 - Too Many Requests`, was bedeutet, dass die maximale Anzahl an Anfragen pro Minute erreicht wurde. Der Client kann spätestens nach einer Minute wieder Anfragen stellen, da die Messung der API-Requests pro Minute erfolgt.
#### Datenformate
Ab API-Version 6 unterstützt unsere API ausschließlich JSON (`application/json`). Die bisherigen XML-Formate (`application/xml`, `text/xml`) werden ab dieser Version nicht länger unterstützt -- weder für Anfragen noch für Antworten.
Die Entscheidung, XML nicht länger zu unterstützen, basiert auf einer Abwägung zwischen Entwicklungsaufwand und tatsächlicher Nutzung. JSON hat sich als Standardformat für REST-APIs etabliert und wird von den meisten modernen Anwendungen bevorzugt. Durch diese Fokussierung können wir unsere Ressourcen gezielt für die Weiterentwicklung und Optimierung der API einsetzen.
Falls Ihre Anwendung bisher XML verwendet hat, ist eine Umstellung auf JSON notwendig. Dies betrifft sowohl die gesendeten Anfragen als auch die Verarbeitung der API-Antworten.
#### Umbenennung von Feldnamen und Elementen
In dieser API-Version wurden einige Feldnamen angepasst, um die Lesbarkeit und Verständlichkeit zu verbessern. Das Wort **„Item"** wurde beispielsweise aus allen Feldnamen und Elementen entfernt, da es redundant ist und keine zusätzlichen Bedeutungen hinzufügt. Die Änderungen beziehen sich ausschließlich auf die Bezeichnungen der Felder oder Elemente, ohne die zugrunde liegende Struktur oder die Datenformate zu verändern.
Beispiel für Änderungen von Elementen:
* `relatedPaymentItems` ➡️`relatedPayments`
* `errorItems` ➡️ `errors`
* `paymentInfoItems` ➡️ `paymentInfos`
Außerdem wurden alle Vorkommen von `paymentStatusItem` und `documentStatusItem` durch das einheitliche Element `status` ersetzt. Um Namenskonflikte zu vermeiden, wurde das ursprüngliche `status `Feld in `statusValue`umbenannt.
Beispiel API-Version 5:
JSON
{
"status": "KON_REJECTED",
"uploadTimestamp": "2025-01-08T13:55:50+01:00",
"orderID": "A1BC",
"reasonCode": "TD02",
"reason": "The file cannot be read (unknown format)",
"additionalInformation": "Additional information 1",
"errorItem": {
"errorCode": "ERR-00-0000",
"errorMessage": "ErrorMessage1",
"errorDetails": "ErrorDetails1",
"timestamp": "2025-01-08T13:55:50+01:00"
}
Beispiel API-Version 6:
JSON
{
"statusValue": "KON_REJECTED",
"uploadTimestamp": "2025-01-08T13:55:50+01:00",
"orderID": "A1BC",
"reasonCode": "TD02",
"reason": "The file cannot be read (unknown format)",
"additionalInformation": "Additional information 1",
"error": {
"errorCode": "ERR-00-0000",
"errorMessage": "ErrorMessage1",
"errorDetails": "ErrorDetails1",
"timestamp": "2025-01-08T13:55:50+01:00"
}
#### API-Endpunkte: Vereinheitlichung \& Umstrukturierung
Mit der Einführung von API-Version 6 haben wir verschiedene Anpassungen an den Endpunkten vorgenommen, um die Struktur und Lesbarkeit der API zu verbessern. Die Änderungen orientieren sich an allgemeinen REST-API-Standards und verbessern die Einheitlichkeit sowie die Konsistenz der API.
##### 1. Entfernen des Zusatzes „item"
In vorherigen API-Versionen wurde für einzelne Ressourcen der Zusatz **„item"** verwendet (z. B. `paymentItem`). Um die API klarer und einheitlicher zu gestalten, haben wir diesen Zusatz **entfernt**. Einzelne Ressourcen sind nun durch ihren Namen eindeutig erkennbar.
**Beispiel:**
* Vorher: `api/v5/Document/Camt/{rid}/item`
* Jetzt: `api/v6/transaction-files/{rid}`
Diese Änderung sorgt für eine **schlankere und intuitivere API**, ohne überflüssige Begriffe in den URLs.
##### 2. Pluralisierung von Ressourcen
Um den allgemeinen REST-Standards besser zu entsprechen, wurden alle Ressourcen **pluralisiert**. Eine Ressource stellt eine Sammlung von Objekten dar, daher verwenden wir nun durchgehend Pluralformen für Ressourcennamen.
**Beispiel:**
* Vorher: `api/v5/payment`
* Jetzt: `api/v6/payments`
Diese Änderung verbessert die **Konsistenz** und sorgt für eine einheitliche Benennung innerhalb der API.
##### 3. Einheitliche Kleinbuchstaben \& Bindestriche in URLs
Wir haben alle Endpunkte in **Kleinbuchstaben** umgestellt und **Bindestriche (** `-`**)** als Trennzeichen eingeführt, um die Lesbarkeit zu verbessern.
**Beispiel:**
* Vorher: `api/v5/ExchangeRates`
* Jetzt: `api/v6/exchange-rates`
Diese Änderungen entsprechen modernen REST-API-Best Practices und sorgen für eine **leichtere Handhabung**, insbesondere für Entwickler, die mit verschiedenen APIs arbeiten.
##### Vereinheitlichung von Query-Parameter
Im Zuge der Vereinheitlichung der URLs wurden auch die Query-Parameter entsprechend angepasst. Diese Anpassungen umfassen die konsequente Verwendung von Kleinbuchstaben sowie die Nutzung von Bindestrichen in den Query-Parametern.
Beispiel:
* Vorher: `api/v5/PayPal/Transaction/{rId}?forceUpdate=true`
* Jetzt: `api/v6/paypal/transactions/{rid}?force-update=true`
Die konsequente Anwendung dieser Regeln verbessert die Lesbarkeit von API-Requests und fördert eine saubere, gut verständliche API-Struktur.
Darüber hinaus wurden häufig genutzte Query-Parameter über unterschiedliche Endpunkte hinweg vereinheitlicht. Diese Änderung betrifft hauptsächlich den Abruf von historischen Daten. Anstelle der bisherigen Parameter `start` und `end` müssen nun `min-date` und `max-date` angegeben werden. Die konsistente Nutzung einheitlicher Begriffe in der gesamten API vereinfacht die Arbeit mit verschiedenen Endpunkten. Zudem sind die Begriffe `min-date` und `max-date` präziser und definieren eindeutig die Grenzen eines Datumsbereichs.
#### Änderung der Quittierungslogik ab API-Version 6
Bis zur API-Version 5 wurde bei jedem Abruf von Daten (z. B. PayPal-Transaktionen, Kontoumsätze) automatisch ein Status gesetzt, der den jeweiligen Datensatz als **"abgerufen"** markierte. Zusätzlich wurden API-Endpunkte bereitgestellt, die ausschließlich Datensätze zurücklieferten, die noch nicht als abgerufen markiert waren. Dadurch mussten Clients nicht selbst nachverfolgen, welche Datensätze bereits verarbeitet wurden -- diese Information wurde direkt in **konfipay** hinterlegt.
Ergänzend gab es die Möglichkeit, die automatische Quittierung durch Setzen des optionalen Parameters `ack=false` zu unterdrücken. In diesem Fall konnte die Quittierung über einen separaten API-Endpunkt erfolgen. Das Problem hierbei war, dass im Standardfall die Quittierung **automatisch mit dem Abruf erfolgte** . Trat während der Verarbeitung auf der Client-Seite ein Fehler auf, war der Datensatz in **konfipay** trotzdem bereits als **abgerufen** markiert -- unabhängig davon, ob er erfolgreich verarbeitet wurde oder nicht.
Ab **API-Version 6** wird die Quittierung nicht mehr automatisch beim Abruf gesetzt. Die neue Standardvorgehensweise erfordert eine **zweistufige Verarbeitung**:
1. **Abruf des Datensatzes:** Der Datensatz bleibt weiterhin als **nicht abgerufen** markiert.
2. **Explizite Quittierung:** Erst nach erfolgreicher Verarbeitung muss eine separate API-Anfrage zur Quittierung erfolgen.
Diese Änderung stellt eine **fundamentale Anpassung des bisherigen Workflows** dar. Wird dies beim Wechsel auf **API-Version 6** nicht berücksichtigt, bleiben alle Datensätze als **nicht abgerufen** markiert und werden bei jeder Abfrage erneut zurückgeliefert.
Clients müssen daher sicherstellen, dass sie nach der erfolgreichen Verarbeitung eines Datensatzes die Quittierung explizit durchführen, um eine korrekte Statusverwaltung in **konfipay** zu gewährleisten.
#### **Filtern und Suchen**
Bis zur **API-Version 5** war die API so aufgebaut, dass es für den Abruf von Daten (z. B. PayPal-Transaktionen oder Kontoumsatzdateien) immer zwei separate Endpunkte gab:
* **Abruf neuer Daten:** Liefert nur Datensätze zurück, die noch nicht als **abgerufen** markiert sind.
* **Abruf historischer Daten:** Ermöglicht den Abruf aller Datensätze innerhalb eines angegebenen Zeitraums (z. B. **01.01.2023 -- 01.01.2024**), unabhängig vom Quittierungsstatus.
Mit **API-Version 6** wurde diese Trennung aufgehoben. Stattdessen gibt es nun **einen einzigen API-Endpunkt** für den Abruf von Daten in Listenform, der über flexible **Filter-Parameter**gesteuert wird.
Die bisherigen Filter für **"neue" Datensätze** oder für den **historischen Abruf nach Zeitraum** müssen (bzw. können, da sie optional sind) jetzt explizit als **Filter-Parameter** angegeben werden. Dadurch sind auch neue Kombinationen möglich, wie z. B.:
* **Abruf aller neuen Transaktionen innerhalb eines bestimmten Zeitraums**
* **Abruf aller bereits quittierten Transaktionen in einem definierten Zeitraum**
Diese Änderung bietet **mehr Flexibilität** und ermöglicht es Clients, weiterhin das bisherige Verhalten der API nachzubilden, indem sie die **Filter-Parameter entsprechend setzen**.
In diesem Rahmen wurde generell eine Reihe neuer Möglichkeiten zum Filtern und Suchen hinzugefügt. Zu diesen Parametern zählen (unter anderem):
* Beträge (minimaler Betrag / maximaler Betrag)
* Kontodaten (Bezeichnung, Iban, Kontoinhaber)
* Bankfachliche Informationen (Verwendungszweck, Kundenreferenz, Zahlungsart)
Eine vollständige Liste der jeweiligen Parameter kann der API Dokumentation entnommen werden.
Es ist insbesondere möglich, mehrere Parameter miteinander zu kombinieren. Bei der Kombination von Parametern sollte jedoch beachtet werden, dass sie sich unter Umständen gegenseitig ausschließen können. In diesem Fall führt die Abfrage zu keinem Ergebnis (`204 - No Content`).
### Änderungen an bestehenden API-Endpunkten
#### Authentifizierung
##### Verpflichtende Angabe des Clients
In der neuen API-Version ist das Element `client`, welches Informationen über den Namen und die Version der Client-Software enthält, die den Authentifizierungs-Request sendet, nun verpflichtend.
Bisher war dieses Element optional. Die verpflichtende Angabe dieser Informationen ermöglicht es, eine bessere **Unterstützung bei Problemen oder API-Integrationen** zu leisten. Neben der schnelleren Identifikation von versionsspezifischen Fehlern können wir durch diese Angaben auch allgemeine Trends, Nutzungsmuster oder Probleme der verschiedenen Client-Versionen analysieren. Dies hilft uns, neue Features gezielt für die am häufigsten genutzten Versionen zu optimieren. Zudem erlaubt es eine bessere Dokumentation von Versionen und Kompatibilitäten, was zukünftige Migrationsprozesse für Kunden deutlich vereinfachen kann.
Beispiel eines Authentifizierungs-Requests:
JSON
{
"apiKey": "JGtjzzFfDoU5UWFl14yalcpj2pwtd0kXHGfBDDBELMPbwcqLyRKBeuiYZ7BxTHi5",
"client": {
"name": "ClientApplicationName",
"version": "1.0.0.0"
}
}
##### Ende der Unterstützung für Cookie-Authentifizierung
Im Rahmen der Modernisierung unserer API haben wir uns dazu entschieden, die Unterstützung für die Cookie-Authentifizierung zu entfernen. Diese Entscheidung basiert auf gestiegenen Sicherheitsanforderungen, da Cookies anfällig für Angriffe wie Cross-Site Scripting (XSS) und Cross-Site Request Forgery (CSRF) sind. Stattdessen setzen wir auf die sicherere und flexiblere Bearer-Token-Authentifizierung, die sich in der Praxis als moderner Standard etabliert hat. Bearer Tokens bieten nicht nur einen besseren Schutz, sondern sind auch unabhängig von der Browser-Umgebung und ermöglichen so eine breitere Anwendbarkeit in modernen Anwendungen, wie mobilen Apps oder serverseitigen Diensten.
##### Restrukturierung der API-Endpunkte
Aufgrund der nicht länger unterstützten Cookie-Authentifizierung ab API-Version 6 (`Auth/Login`) wurden die API-Endpunkte für die Authentifizierung restrukturiert. Die bisherigen Endpunkte unter `Auth/*` wurden durch eine neue, klarere und konsistentere Namenskonvention ersetzt, die sich stärker an RESTful-Prinzipien orientiert.
| **URL Alt** | **URL Neu** | **Beschreibung** |
|--------------------|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| Auth/Login | **Entfernt** | Die Cookie-Authentifizierung wird ab API-Version 6 nicht mehr unterstützt. Stattdessen muss nun ein Token über `authentication/token` genutzt werden. |
| `Auth/Login/Token` | `authentication/token` | Fordert ein neues Zugriffstoken an. |
| `Auth/Logout` | `authentication/token/revoke` | Widerruft ein aktives Zugriffstoken. |
| `Auth/Scope` | `authentication/scopes` | Ruft die Berechtigungen des aktuellen API-Schlüssels ab. |
| `Auth/Scope/All` | `authentication/scopes/all` | Listet alle verfügbaren API-Berechtigungen auf. |
##### Anpassung der Scopes
Aufgrund der Anpassung der API-Endpunkte, der Einführung neuer Endpunkte und der Entfernung nicht mehr benötigter Endpunkte wurden die **API-Scopes aktualisiert**.
| Alter Scope (bis API-Version 5) | Neuer Scope (ab API-Version 6) |
|---------------------------------|-------------------------------------------------|
| `Account` | `Accounts` |
| `Bank` | `Banks` |
| `BankAccount` | `BankAccounts` |
| `Payment` | `Payments` |
| `PaymentStatus` | entfernt (integriert in "`Payments`") |
| `Document` | aufgeteilt in "`Documents`" \& "`Transactions`" |
| `ExchangeRate` | `ExchangeRates` |
| `PaymentProvider` | `PaymentProviders` |
| `PayPal` | `PayPal` |
| `User` | `Users` |
| `UserGroup` | `UserGroups` |
Besonderheiten:
* Bei der Erstellung eines neuen API-Schlüssels über API-Version 5 oder älter:
* Der Scope "PaymentStatus" wird verworfen und in "Payments" übersetzt.
* Der Scope "Document" wird automatisch in "Documents" und "Transactions" aufgeteilt.
* Beim Abrufen von Scopes für bestehende API-Schlüssel:
* Für API-Versionen ≤ 5 gibt die API weiterhin die alten Scope-Namen zurück.
* Ab Version 6 werden ausschließlich die neuen Scopes verwendet.
#### Bankkonten
##### Neues Feld: Währung
In der API-Version 6 wird die Funktionalität zur Erstellung und Aktualisierung von Bankkonten erweitert, sodass künftig die Währung als zusätzlicher Parameter angegeben werden kann. Diese Erweiterung erleichtert die Implementierung von „Multi-Währungs-Funktionalitäten" und sorgt für eine eindeutige Definition und Zuordnung während der Kontoerstellung oder -Aktualisierung.
##### Asynchrone Löschung von Bankkonten
In früheren API-Versionen konnten Bankkonten synchron gelöscht werden. Aufgrund der zunehmenden Abhängigkeiten im System, der wachsenden Datenmengen sowie der daraus resultierenden längeren Wartezeiten und höheren Systembelastung wurde der Prozess so optimiert, dass das Löschen von Bankkonten nun asynchron erfolgt. Diese Änderung erhöht die Skalierbarkeit, reduziert Timeouts und sorgt für eine bessere Systemstabilität sowie eine optimierte Benutzererfahrung. Nach erfolgreicher Initiierung des Löschprozesses gibt der API-Endpunkt eine Tracking-Kennung des Vorgangs zusammen mit dem initialen Status zurück.
Beispiel Antwort:
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"statusCode": 1,
"statusName": "Scheduled",
"details": "Additional information 1",
"operationStatusUrl": "https://portal.konfipay.de/api/v6.0/delete/status/5d12c087-be1e-456c-a33f-4f8750fa7814",
"operationStatusMethod": "GET"
}
##### Statusabfrage des Löschvorgangs
Aufgrund der Einführung des asynchronen Löschvorgangs wird zusätzlich ein neuer API-Endpunkt bereitgestellt, welcher es ermöglicht, den aktuellen Status einer ausstehenden Löschung eines Bankkontos zu überprüfen. Dieser Endpunkt liefert Statusinformationen darüber, ob die Löschung in Bearbeitung, abgeschlossen oder ob ein Fehler aufgetreten ist.
Beispiel Antwort:
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"statusCode": 3,
"statusName": "Finished",
"details": "Additional information 1"
}
Weitere Informationen zu dieser neuen API-Schnittstelle können der API-Dokumentation entnommen werden.
##### Aktivieren/Deaktivieren von Bankkonten
In dieser API-Version besteht die Möglichkeit, Bankkonten beim Erstellen oder Aktualisieren zu aktivieren oder zu deaktivieren. Falls ein Bankkonto aktiviert werden soll, so muss das Feld `isActive` auf `true` gesetzt werden. Falls das Feld auf `false` gesetzt wird, so wird das Bankkonto deaktiviert.
| **Endpunkte (bis Version 5)** | **Endpunkte (ab Version 6)** |
|-----------------------------------|-------------------------------------|
| POST `/api/{version}/BankAccount` | POST `/api/{version}/bank-accounts` |
| PUT `/api/{version}/BankAccount` | PUt `/api/{version}/bank-accounts` |
Inaktive Bankkonten werden in allen automatischen Prozessen (z. B. beim Abruf von Kontoumsätzen) nicht berücksichtigt. Für inaktive Konten können keine Zahlungsaufträge erstellt oder eingereicht werden.
#### Dokumente und Transaktionen
##### Neue Endpunkte
Mit API-Version 6 wurden zwei neue API-Endpunkte eingeführt, um eine klare Trennung zwischen **bankfachlichen Dateien** und den daraus extrahierten **Transaktionsdaten** (= Buchungen) zu schaffen:
* **Transactions API** : Ermöglicht den direkten Abruf von Buchungen in strukturierter Form als **JSON**. Damit entfällt die Notwendigkeit, Kontoumsatzdateien selbst auszuwerten.
* **Transaction Files API**: Bietet weiterhin den Zugriff auf die originalen Kontoumsatzdateien (z. B. camt.053) und Vormerkposten, falls diese benötigt werden.
Bisher war es bei Nutzung der **Documents API** notwendig, Kontoumsatzdateien abzurufen und manuell auszuwerten. Die neue **Transactions API** übernimmt diesen Schritt, indem **konfipay** die enthaltenen Buchungen extrahiert und direkt als **JSON** bereitstellt. Dadurch ist keine eigene Verarbeitung bankfachlicher Dateien mehr erforderlich.
Die **Transaction Files API** übernimmt in diesem Zusammenhang die Funktion der **Documents API** für Kontoumsatzdateien und Vormerkposten und ersetzt diese in diesem Bereich. Andere bankfachliche Dokumente bleiben weiterhin über die **Documents API** verfügbar.
Zusätzlich wurde die bisherige Trennung der Endpunkte für **MT94X** und **camt** aufgehoben. Beide Formate sind nun über die **Transaction Files API** verfügbar. Falls erforderlich, kann die Formatunterscheidung über die **Filter-Parameter** der **Transaction Files API** erfolgen.
| **Endpunkte (bis Version 5)** | **Endpunkte (ab Version 6)** |
|-------------------------------------------------------------|------------------------------------|
| `/api/{version}/Document/Camt` `/api/{version}/Document/MT` | `/api/{version}/transaction-files` |
##### Quittierung von Kontoumsatzdaten
Um die potenziell große Menge an Kontoumsatzdaten und die damit verbundene hohe Anzahl an API-Requests zu minimieren, wird in dieser API-Version vorerst auf eine separate Quittierung pro Transaktion verzichtet.
Stattdessen wird in dieser Version die Möglichkeit geschaffen, vollständige Listen der abgerufenen Ergebnisse mit einer Quittierung zu versehen.
Dafür wird beim Abruf von Kontoumsatzdaten der Liste von Kontoumsätzen (`transactions`) eine **temporäre ID** (`acknowledgementID`) zugewiesen. Diese ID bleibt für **eine Stunde** gültig oder wird nach der Quittierung gelöscht. Die ID fasst die Kontoumsätze zusammen, welche auf einer Seite der Abfrage gruppiert wurden und kann genutzt werden, um die Umsätze auf dieser Seite zu quittieren. In diesem Fall ändert sich der Status der Transaktionen von `isNew=true` zu `isNew=false`.
**Beispiel:**
JSON
{
"pageNumber": 1,
"pageSize": 1000,
"totalPages": 1,
"totalItems": 2,
"links": [
{
"href": "https://portal.konfipay.de/api/v6/Example?pageNumber=1&pageSize=1000",
"rel": "self",
"method": "GET"
}
],
"results": {
"acknowledgementId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
"transactions": [
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-18T08:53:51+01:00",
"amount": 10.99,
"currency": "EUR",
"creditDebitIndicator": "CRDT",
"electronicSequenceNumber": "74",
"name": "Alice Mayer",
"iban": "DE12345678901234567890",
"bic": "ABCDEFG1CBA",
"bookingText": "SAMMELÜBERWEISUNG",
"bookingDate": "2025-02-18T10:06:04+01:00",
"valueDate": "2025-02-18T10:06:04+01:00",
"isNew": false,
"bankReference": "bankRefernceNumber",
"paymentIdentificationId": "konfipay-1-11111",
"primaNota": "9301",
"document": {
"rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
"timestamp": "2025-02-18",
"isNew": true,
"format": "camt.052"
},
"bankAccount": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"iban": "DE09876543210987654321",
"currency": "EUR"
}
},
{
"rId": "fa727310-3072-4abc-a982-b511b8b81108",
"timestamp": "2025-02-18T08:53:51+01:00",
"amount": 500,
"currency": "EUR",
"creditDebitIndicator": "DBIT",
"electronicSequenceNumber": "82",
"name": "Alice Mayer",
"iban": "DE12345678901234567890",
"bic": "ABCDEFG1CBA",
"bookingText": "GUTSCHRIFT ÜBERWEISUNG",
"bookingDate": "2025-02-18T10:06:04+01:00",
"valueDate": "2025-02-18T10:06:04+01:00",
"isNew": true,
"bankReference": "bankRefernceNumber",
"paymentIdentificationId": "konfipay-1-11112",
"primaNota": "9301",
"document": {
"rId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
"timestamp": "2025-02-18",
"isNew": true,
"format": "camt.053"
},
"bankAccount": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"iban": "DE09876543210987654321",
"currency": "EUR"
}
}
]
}
}
##### Neue Felder: Auszugsnummer und elektronische Auszugsnummer bei Camt und MT940
Beim Abruf bankfachlicher Kontoumsatzdokumente (camt und MT94X) wurde die Antwort um zwei neue Felder erweitert: die **Auszugsnummer** (`legalSequenceNumber`) und die **elektronische Auszugsnummer** (`electronicSequenceNumber`). Beide Felder sind optional und spiegeln die Angaben wider, die in den von der jeweiligen Bank bereitgestellten Dokumenten enthalten sind.
##### Neues Element: Informationen über den Kontoinhaber bei Camt und MT940
In den älteren API-Versionen konnte die IBAN zur Abfrage von Kontoumsatzdokumenten verwendet werden. Da die IBAN jedoch mittlerweile nicht mehr eindeutig ist, können beim Abruf ggf. die Umsätze von zwei verschiedenen Konten ausgeliefert werden. Aus diesem Grund wird in dieser API-Version die Antwort von bankfachlichen Kontoumsatzdokumenten (camt und MT940) um ein neues Element erweitert: die **Informationen über das zugrundeliegende Bankkonto** (`bankAccount`). Dieses neue Element umfasst wichtige Informationen wie RID, IBAN und Währung (`currency`) des Bankkontos. Es sorgt für eine transparentere und genauere Zuordnung zu einem bestehenden Bankkonto, selbst bei der Verwendung verschiedener Währungen.
Beispiel:
JSON
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"href": "api/v6.0/transaction-files/5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-26T11:14:25+01:00",
"isNew": false,
"format": "camt.053",
"fileName": "2025-02-25_C53_DE12345678901234567890_EUR_21-00001.xml",
"electronicSequenceNumber": 1,
"legalSequenceNumber": 1,
"bankAccount": {
"rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
"iban": "DE12345678901234567890",
"currency": "EUR"
}
}
#### Zahlungen und Zahlungsdateien
##### Abruf der Zahlungsübersicht
Mit der API-Version 6 wird eine Erweiterung im Zahlungsbereich eingeführt, welche eine Auflistung der vorhandenen Zahlungsdateien ermöglicht. Bei der Abfrage können diverse Parameter genutzt werden, um die Ergebnisliste nach verschiedenen Kriterien zu filtern. So lassen sich Zahlungen gezielt nach Zahlungsart (`purpose`), Zahlungstyp (`payment-type`) (z. B. Überweisungen, Lastschriften usw.), Zahlungsstatus (`status`), Erstellungsdatum (`min-date/max-date`) oder Ausführungsdatum (`min-execution-date/max-execution-date`) filtern. Weitere Informationen zu dieser neuen API-Schnittstelle können der API-Dokumentation entnommen werden.
##### Zusammenfassen der API-Endpunkte von Zahlungen
Die Neustrukturierung der Endpunkte für Zahlungen umfasst das Zusammenfassen verschiedener API-Schnittstellen zur Übermittlung und zum Abruf von Zahlungsdateien. Folgende Endpunkte wurden zusammengefasst:
| **Bis API-Version 5** | **Ab API-Version 6** |
|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
| POST `api/v5/Payment/Sepa/Container` POST `api/v5/Payment/Sepa/Pain` POST `api/v5/Payment/ISO20022/Pain` POST `api/v5/Payment/Sepa/DTAZV` | Post `api/v6/payment-files` |
Im Standard erkennt konfipay automatisch das Format von eingereichten Zahlungsaufträgen. Die automatische Erkennung kann über den `scope`parameter überschrieben werden.
##### Einreichung ohne Übertragung
Mit dieser API-Version wurde die Möglichkeit hinzugefügt, Zahlungsdateien beim Import in konfipay nicht sofort an die Bank zu übertragen, sondern zunächst nur im System zu speichern. Um diese flexible Verarbeitung zu ermöglichen, wurde ein neuer API-Endpunkt eingeführt: POST `/api/v6/payment-files/{rid}/submit`.
Dieser Endpunkt ermöglicht die manuelle Übertragung einer zuvor erstellten Zahlungsdatei an das Rechenzentrum der Bank. Falls eine Datei bereits übermittelt wurde, erfolgt keine erneute Übertragung. Eine erneute Übermittlung kann jedoch erzwungen werden, indem der Query-Parameter force=true gesetzt wird.
Eine erneute Übermittlung bereits gesendeter Zahlungsdateien wird nur empfohlen, wenn diese von der Bank abgelehnt wurden. In solchen Fällen ermöglicht der `force`-Parameter einen erneuten Versuch, ohne eine neue Zahlungsdatei erstellen zu müssen.
Weitere Informationen zu dieser neuen API-Schnittstelle können der API-Dokumentation entnommen werden.
##### Extrahieren von Einzelzahlungen aus Zahlungsdateien in die offenen Aufträge
Die API-Version 6 bietet die Möglichkeit Zahlungsaufträge aus einer Zahlungsdatei direkt in die offenen Aufträge zu übernehmen, ohne dass eine Dateiübertragung an die Bank oder eine Speicherung der Zahlungsdatei erfolgt ( Post `/api/v6/payment-files/extract`). Sobald die Zahlungen aus der Zahlungsdatei extrahiert wurden, können diese bearbeitet werden und zu neuen Zahlungsdateien kombiniert werden. Darüber hinaus werden die gemeinsam importierten Aufträge mit einer eindeutigen Batch-RID versehen, um auch nachträglich eine Zuordnung zur ursprünglichen Zahlungsdatei sicherzustellen.
Beispiel Antwort:
JSON
[
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-18T08:53:48+01:00",
"batch": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"numberOfElements": 2
},
...
},
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-18T08:53:48+01:00",
"batch": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"numberOfElements": 2
},
...
}
]
##### Einreichung von Zahlungsaufträgen als (ehemals "ccft")
In API-Version 6 wurde der bisherige Endpunkt `/api/v5/Payment/Custom/Windata/Ccft` durch `/api/v6/payments` ersetzt. Gleichzeitig wurde der Workflow für die Übertragung von Zahlungen zur Bank überarbeitet.
Bisher wurden eingereichte Zahlungen direkt in SEPA-Dateien umgewandelt und unmittelbar an die Bank übermittelt. Ab API-Version 6 erfolgt dies nun in zwei separaten Schritten:
1. Zahlungen einreichen:
* Zahlungen werden über post `/api/v6/payments` erstellt und zunächst im System gespeichert.
* Vor der Übertragung können die Zahlungen über die API oder das Webportal noch bearbeitet werden.
2. Manuelle Übertragung zur Bank:
* Über den neuen API-Endpunkt POST `/api/v6/payments/submit` können gezielt ausgewählte Zahlungen anhand ihrer RID an die Bank übermittelt werden.
* konfipay erstellt automatisch die erforderlichen SEPA-Pain-Dateien und überträgt diese.
Diese Änderung ermöglicht mehr Flexibilität und verhindert, dass Zahlungen direkt nach dem Einreichen übertragen werden, bevor sie final geprüft oder bearbeitet wurden.
Falls die Erstellung der Zahlungsdatei im Rahmen der Übertragung nicht erfolgreich ist, wird der Prozess abgebrochen und die Zahlungen verbleiben als `Pending` in den Zahlungsaufträgen. Gelingt die Erstellung der Zahlungsdatei, werden die Zahlungen dieser Datei zugewiesen und können weder bearbeitet noch gelöscht werden -- unabhängig davon, ob die Dateiübertragung erfolgreich ist oder nicht[.](http://nicht.in/) In diesem Fall ändert sich der Status der Zahlungen von `Open` zu `Pending.`
Weitere Informationen zu dieser neuen API-Schnittstelle können der API-Dokumentation entnommen werden.
Beispiel Request:
{
"batchBooking": true,
"paymentRids": [
"5d12c087-be1e-456c-a33f-4f8750fa7814",
"fa727310-3072-4abc-a982-b511b8b81108"
],
"failOnSubmittedPayments": false
}
##### Abruf von Zahlungsaufträgen
In dieser API-Version wird die Funktionalität eingeführt, Zahlungsaufträge anhand der optionalen Batch-RID (`batch-``rid`) oder ihrem Status (`status`) abzurufen. Bei der Abfrage der Zahlungsaufträge wird eine Liste an Aufträgen zurückgegeben, die entweder in einem Batch importiert wurden oder einem gewissen Status (`Processed`/`Pending`) zugeordnet sind. Wenn kein Filterparameter angegeben ist, wird die vollständige Liste aller Zahlungsaufträge zurückgegeben. Ein Zahlungsauftrag wird als offen betrachtet, wenn weder eine Zahlungsdatei erstellt noch eine Dateiübertragung an die Bank durchgeführt wurde.
##### Abruf von Zahlungen
Die neue API-Schnittstelle Get `/api/v6/payments/{rid}` ermöglicht den Abruf von Zahlungsinformationen. Dieser Endpunkt liefert sowohl Daten zum Batch (`batch`) als auch detaillierte Informationen zur Zahlung (`transaction`). Zusätzlich können die Kontodaten des Auftraggebers (`initPartyBankAccount`) und des Empfängers (`otherPartyBankAccount`) eingesehen werden. Falls eine Zahlungsdatei vorhanden ist, steht auch diese zur Verfügung (`paymentFile`).
Eine umfassende Beschreibung der enthaltenen Elemente und Felder ist in der zugehörigen API-Dokumentation verfügbar.
Beispiel:
JSON
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-18T08:53:48+01:00",
"batch": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"numberOfElements": 5
},
"transaction": {
"type": "TRF",
"amount": 10055,
"currency": "EUR",
"country": "DE",
"executionDate": "2025-02-17",
"endToEndId": "NOTPROVIDED",
"purposeCode": "SALA",
"chargeBearer": "SLEV",
"instrId": "ABC123456789",
"rmtInfoUStrd": "Reference from the payer to the bank"
},
"initPartyBankAccount": {
"rId": "fa727310-3072-4abc-a982-b511b8b81108",
"iban": "DE12345678901234567890",
"description": "Alice Mayer"
},
"otherPartyBankAccount": {
"rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
"iban": "DE09876543210987654321",
"description": "Bob Mayer"
},
"paymentFile": {
"rId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
"timestamp": "2025-02-18T08:53:48+01:00",
"format": "pain.001",
"executionDate": "2025-02-18",
"paymentType": "CBTRF",
"status": {
"statusValue": "FIN_CONFIRMED",
"uploadTimestamp": "2025-02-18T10:06:01+01:00",
"orderID": "A1BC",
"reasonCode": "TS01",
"reason": "The transfer of the file was successful",
"additionalInformation": "Additional information 1"
}
}
}
##### Löschen von Zahlungen
Der neue API-Endpunkt DELETE `/api/v6/payments/{rid}` ermöglicht es Zahlungen zu löschen. Nur nicht verarbeitete Zahlungen können gelöscht werden. Sobald eine Zahlung verarbeitet und in eine SEPA konvertiert wurde, ist eine Löschung nicht mehr möglich.
##### Genaue Spezifikation der Formate
In den vorherigen API-Versionen wurden bei den Zahlungsdateien nur das allgemeine Format wie beispielsweise „pain" oder „container" zurückgegeben. Ab API-Version 6 wird das spezifische Format, wie z. B. „pain.001" oder „pain.008", in der Antwort übermittelt.
**Antwort bis API-Version 5**:
JSON
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2024-10-18T13:30:48+02:00",
"type": "pain",
"paymentStatusItem": {
"status": "FIN_CONFIRMED",
"uploadTimestamp": "2024-10-18T14:43:01+02:00",
"orderID": "A1BC",
"reasonCode": "TS01",
"reason": "The transfer of the file was successful",
"additionalInformation": "Additional information 1"
}
}
**Antwort ab API-Version 6**:
JSON
{
"paymentInfo": {
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-01-09T14:36:50+01:00",
"format": "pain.001",
"executionDate": "2025-01-09",
"paymentType": "TRF",
"status": {
"statusValue": "FIN_CONFIRMED",
"uploadTimestamp": "2025-01-09T15:49:03+01:00",
"orderID": "A1BC",
"reasonCode": "TS01",
"reason": "The transfer of the file was successful",
"additionalInformation": "Additional information 1"
}
}
}
##### Ablehnung von Dateien mit mehreren SEPA-Sammelaufträgen
Ab API-Version 6 ist die Einreichung von Dateien, welche mehr als einen SEPA-Sammelauftrag (Element: ``) enthalten nicht länger zulässig. Diese Anpassung dient dazu, eine konsistente und verlässliche Verarbeitung über alle Prüf-, Anzeige- und Verarbeitungsschritte hinweg sicherzustellen.
#### PayPal
##### Unterstützung von Sandbox Konten
In dieser API-Version ist die Nutzung von PayPal-Sandbox-Konten möglich. Über das Feld `isSandbox` kann bei der Erstellung oder Aktualisierung festgelegt werden, ob das PayPal-Konto in der Sandbox-Umgebung betrieben wird. Standardmäßig ist dieser Wert auf `false` gesetzt. Wenn der Wert auf `true` gesetzt ist, kann das Konto flexibel für Test- und Entwicklungszwecke genutzt werden.
Beispiel Anfrage:
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"description": "Description1",
"clientId": "Adsf-sdffgghghjhklkj_xOFZDwIjP-qeryuioplkjhgfdcvbnu2SfHM0_mnbvcx",
"clientSecret": "akcvkfriooi$^&dfd=dsfdsf=-dsfsdljllerejjlgl;r",
"isActive": true,
"startFetchDate": "2025-01-18T08:53:51+01:00",
"isSandbox": false
}
Beispiel Antwort:
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"description": "Description1",
"clientId": "Ysnf-tQW8usdfsdfsdf_xOFZDwIjP-qsfsdfdfreerkuyiu2SfHM0_ghjghjghD",
"isActive": true,
"timestamp": "2025-02-18T08:53:51+01:00",
"startFetchDate": "2025-01-18T08:53:51+01:00",
"payPalBalances": [
...
],
"isSandbox": false
}
### Entfallene API-Endpunkte
Bis API-Version 5 wurden alle Zahlungsformate über einen eigenständigen API-Endpunkt abgebildet. Damit der Status einer Zahlung über alle Formate hinweg zentral abgerufen werden konnte, wurde bis API-Version 5 die PaymentStatus API bereitgestellt ( GET `/api/{version}/PaymentStatus/{rid}`). Mit der Zusammenfassung der API Endpunkte für Zahlungen zu einem gemeinsamen Endpunkt (`/api/{version}/payment-files`) entfällt die Notwendigkeit der Bereitstellung eines eigenständigen API Endpunktes. Der Status einer Zahlung kann ab API Version 6 über den Endpunkt GET `/api/v6/payment-files/{rid}`abgerufen werden.
---
language: "de"
---
# API Version 6 (EN)
Published: 05.03.2025
This article describes the new features and changes in API version 6 compared to API version 5. The technical API documentation can be found [here](https://portal.konfipay.de/api-docs/index.html).
A new version is introduced when a change means that the **backward** compatibility of the API **can no longer be ensured** . Before switching to this API version, please check whether the changes have an impact on your system and **make the necessary adjustments.**
## Goals
With the publication of **API version 6** we have deliberately decided to make far-reaching structural changes. This version contains significantly more adjustments than a standard API version change. Instead of spreading incremental changes over many smaller updates, we have taken the opportunity to bring together as many innovations as possible in a single major step.
Our aim was to make the API **more scalable** , **more efficient** and **more future-proof.** As our platform continues to grow, the demands on our infrastructure and the expectations of our users are also increasing. To meet these challenges, we have implemented central functions that improve performance, reliability and flexibility.
We only publish new API versions when we consider it absolutely necessary. In doing so, we aim to bundle as many changes as possible in one such step. This way, we ensure that our customers are not burdened by frequent migration efforts and that an API version can be used over a long period of time without becoming outdated.
## Important innovations
1. **Paging:** To shorten response times and optimize data transfer, we are introducing paging in our API. Instead of returning all data at once, API version 6 delivers the information in smaller, manageable packets of 100 entries per page. This allows for more efficient data processing on both the server and client side, resulting in faster load times and improved overall performance. Further information on this can be found in the section on [Paging](https://wiki.konfipay.de/konfipay/api-version-6-en#APIVersion6(EN)-Paging).
2. **Rate Limiting:** To ensure fair and reliable use for all users, we are introducing a rate limiting system. This system protects our infrastructure from overload and at the same time ensures that all users can benefit from consistent performance. You can find more information on this in the section on [Rate limiting](https://wiki.konfipay.de/konfipay/api-version-6-en#APIVersion6(EN)-Ratelimiting).
3. **Focus on JSON:** As of API version 6, we no longer support XML (`application/xml`, `text/xml`). In the future, our API will process and deliver data exclusively in JSON format (`application/json`). This decision was made because JSON has established itself as the standard for REST APIs and the focus on a standardized format enables more efficient maintenance and faster further developments. Further information on this can be found in the section on [Data formats](https://wiki.konfipay.de/konfipay/api-version-6-en#APIVersion6(EN)-Dataformats).
## Why these changes are important
Our aim with version 6 is to develop an API that can be **scaled seamlessly** while both data volume and user throughput increase. These improvements ensure that the API provides a reliable, fast and efficient service even as data volumes and user activity increase. By aligning our API with **industry principles** we offer developers a consistent and stable basis for future developments.
In summary, **API version 6** is a step towards a more robust platform that meets the changing needs of our users and can handle larger data volumes and increased traffic without compromising performance. We are convinced that these changes will not only improve the current user experience, but also set the course for further growth and success in the future.
## All changes at a glance
### General changes
#### Paging
With the new version of our API, paging for **all** API endpoints has been introduced. We now return a list of elements to make querying large amounts of data more efficient. By default, when a request is made, **100** entries per page are returned, whereby this number is determined by the parameter `pageSize` and can be increased to up to 1000 entries. The parameter `pageNumber` can be used to specify which page of the results is to be retrieved. The returned content is now provided in a wrapper element, whereby the actual data is stored in the `results`. The wrapper element itself provides additional information such as the number of entries per page, the current page, the total number of pages and the total number of all elements across all pages. The following example shows the structure of the new paging response:
JSON
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalItems": 2,
"links": [
{
"href": "https://portal.konfipay.de/api/v6/Example?pageNumber=1&pageSize=100",
"rel": "self",
"method": "GET"
}
],
"results": [
. . .
]
Previously, lists were returned in a nested structure and were contained in a parent element.
Example (superordinate element: `documentItems`)
JSON
{
"documentItems": [
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"href": "api/v5.0/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-27T09:33:43+01:00",
"iban": "DE12345678901234567890",
"isNew": true,
"format": "camt.053",
"fileName": "2025-02-26_C53_DE12345678901234567890_EUR_21-00001.xml"
},
{
"rId": "fa727310-3072-4abc-a982-b511b8b81108",
"href": "api/v5.0/Document/Camt/fa727310-3072-4abc-a982-b511b8b81108",
"timestamp": "2025-02-27T10:45:56+01:00",
"iban": "DE12345678901234567890",
"isNew": true,
"format": "camt.053",
"fileName": "2025-02-27_C53_DE12345678901234567890_EUR_21-00002.xml"
}
]
}
With the introduction of paging, this additional level is removed. In this case, lists are created directly in the `results` element. This change applies to all places in the API.
#### Rate limiting
To ensure a balanced distribution of resources, we have implemented standard rate limiting values in our API:
* **Public endpoints (unauthenticated):** 1000 requests per minute, per client IP
* **Authenticated endpoints:**10000 requests per minute per tenant; can be raised on request
These limits prevent resource overload and ensure stable API performance. If your requirements exceed these standard limits, we offer you the option of increasing the rate limits individually on request. Please send a corresponding request to [support@konfipay.de](mailto:support@konfipay.de).
Based on current API usage, we are already raising some customers to higher limits at the time of the update to ensure uninterrupted use.
**Important:**This adjustment applies API-wide and affects not only API version 6, but all versions of the API. The introduction of rate limiting coincides with the release of API version 6, but is independent of the API version used.
If a limit is exceeded, the server responds with the HTTP status code `429 - Too Many Requests`which means that the maximum number of requests per minute has been reached. The client can make requests again after one minute at the latest, as the API requests are measured per minute.
#### Data formats
As of API version 6, our API only supports JSON (`application/json`). The previous XML formats (`application/xml`, `text/xml`) are no longer supported from this version onwards - neither for requests nor for responses.
The decision to no longer support XML is based on a trade-off between development effort and actual usage. JSON has established itself as the standard format for REST APIs and is preferred by most modern applications. This focus allows us to use our resources specifically for the further development and optimization of the API.
If your application previously used XML, you will need to switch to JSON. This affects both the requests sent and the processing of API responses.
#### Renaming field names and elements
In this API version, some field names have been adapted to improve readability and comprehensibility. The word **"Item"** for example, has been removed from all field names and elements as it is redundant and does not add any additional meaning. The changes relate exclusively to the names of the fields or elements, without changing the underlying structure or data formats.
Example of changes to elements:
* `relatedPaymentItems` ➡️`relatedPayments`
* `errorItems` ➡️ `errors`
* `paymentInfoItems` ➡️ `paymentInfos`
In addition, all occurrences of `paymentStatusItem` and `documentStatusItem` through the uniform element `status` has been replaced. To avoid naming conflicts, the original `status `Field in `statusValue`renamed.
Example API version 5:
JSON
{
"status": "KON_REJECTED",
"uploadTimestamp": "2025-01-08T13:55:50+01:00",
"orderID": "A1BC",
"reasonCode": "TD02",
"reason": "The file cannot be read (unknown format)",
"additionalInformation": "Additional information 1",
"errorItem": {
"errorCode": "ERR-00-0000",
"errorMessage": "ErrorMessage1",
"errorDetails": "ErrorDetails1",
"timestamp": "2025-01-08T13:55:50+01:00"
}
Example API version 6:
JSON
{
"statusValue": "KON_REJECTED",
"uploadTimestamp": "2025-01-08T13:55:50+01:00",
"orderID": "A1BC",
"reasonCode": "TD02",
"reason": "The file cannot be read (unknown format)",
"additionalInformation": "Additional information 1",
"error": {
"errorCode": "ERR-00-0000",
"errorMessage": "ErrorMessage1",
"errorDetails": "ErrorDetails1",
"timestamp": "2025-01-08T13:55:50+01:00"
}
#### API endpoints: Standardization \& restructuring
With the introduction of API version 6, we have made various adjustments to the endpoints to improve the structure and readability of the API. The changes are based on general REST API standards and improve the uniformity and consistency of the API.
##### 1. Removal of the "item" suffix
In previous API versions, the addition **"item"** is used (e.g. `paymentItem`). To make the API clearer and more uniform, we have **removed**this addition. Individual resources are now clearly recognizable by their name.
**Example:**
* Before: `api/v5/Document/Camt/{rid}/item`
* Now: `api/v6/transaction-files/{rid}`
This change ensures a **leaner and more intuitive API**without superfluous terms in the URLs.
##### 2. Pluralization of resources
In order to better comply with the general REST standards, all resources have been **pluralized.** A resource represents a collection of objects, which is why we now use plural forms for resource names throughout.
**Example:**
* Before: `api/v5/payment`
* Now: `api/v6/payments`
This change improves the **consistency** and ensures uniform naming within the API.
##### 3. Uniform lowercase letters \& hyphens in URLs
We have all end points in **lower case** and **hyphens (** `-`**)** have been introduced as a separator to improve readability.
**Example:**
* Before: `api/v5/ExchangeRates`
* Now: `api/v6/exchange-rates`
These changes are in line with modern REST API best practices and ensure a **easier handling**especially for developers who work with different APIs.
##### Standardization of query parameters
In the course of standardizing the URLs, the query parameters were also adapted accordingly. These adjustments include the consistent use of lowercase letters and the use of hyphens in the query parameters.
Example:
* Before: `api/v5/PayPal/Transaction/{rId}?forceUpdate=true`
* Now: `api/v6/paypal/transactions/{rid}?force-update=true`
The consistent application of these rules improves the readability of API requests and promotes a clean, easy-to-understand API structure.
In addition, frequently used query parameters have been standardized across different endpoints. This change mainly affects the retrieval of historical data. Instead of the previous parameters `start` and `end` must now `min-date` and `max-date` can be specified. The consistent use of standardized terms throughout the API simplifies working with different endpoints. In addition, the terms `min-date` and `max-date` are more precise and clearly define the limits of a date range.
#### Change to the acknowledgement logic from API version 6
Up to API version 5, a status was automatically set each time data was retrieved (e.g. PayPal transactions, account transactions), which marked the respective data record as **"retrieved".** In addition, API endpoints existed that only returned data records that had not yet been marked as retrieved. This meant that clients did not have to keep track of which records had already been processed - this information was stored directly in **konfipay.**
In addition, it was possible to deactivate automatic acknowledgement by setting the optional parameter `ack=false`. In this case, acknowledgement could take place via a separate API endpoint. The problem here was that in the standard case, the acknowledgement happened **automatically with the API call.** If an error occurred on the client side during processing, the data record in **konfipay** was nevertheless marked as **retrieved** - regardless of whether it has been successfully processed or not.
From **API version 6** the acknowledgement is no longer set automatically with an API call. The new standard procedure requires **two-stage processing**:
1. **Retrieval of the data record:** The data record remains marked as **not retrieved.**
2. **Explicit acknowledgement:** A separate API request for acknowledgement must be made after successful processing.
This change represents a **fundamental adjustment of the existing workflow.** If this is not taken into account during the change to API version 6, all data records remain marked as **not retrieved** and are returned with every query.
Clients must therefore ensure that they explicitly perform the acknowledgement after successful processing of a data record in order to ensure correct status management in **konfipay.**
#### **Filter and search**
Until the **API version 5** the API was structured in such a way that there were always two separate endpoints for retrieving data (e.g. PayPal transactions or account transaction files):
* **Retrieval of new data:** Only returns data records that have not yet been marked as **retrieved.**
* **Retrieval of historical data:** Enables the retrieval of all data records within a specified time period (e.g. **01.01.2023 - 01.01.2024**), regardless of the acknowledgement status.
With **API version 6** this separation has been abolished. Instead, there is now **a single API endpoint** for retrieving data in list form, which can be controlled via flexible **Filter parameters.**
The previous filters for **"new" data records** or for the **historical retrieval by period** must (or can, as they are optional) now be explicitly marked as **filter parameters.** This also makes new combinations possible, e.g:
* **Retrieval of all new transactions within a certain period of time**
* **Retrieval of all transactions already acknowledged in a defined time period**
This change offers **more flexibility** and allows clients to continue to emulate the previous behavior of the API by using the **filter parameters accordingly.**
In this context, a number of new options for filtering and searching have generally been added. These parameters include (among others):
* Amounts (minimum amount / maximum amount)
* Account details (name, Iban, account holder)
* Banking information (purpose of use, customer reference, payment type)
A complete list of the respective parameters can be found in the API documentation.
In particular, it is possible to combine several parameters with each other. When combining parameters, however, it should be noted that they may be mutually exclusive. In this case, the query will not produce a result (`204 - No Content`).
### Changes to existing API endpoints
#### Authentication
##### Mandatory specification of the client
In the new API version, the element `client`which contains information about the name and version of the client software sending the authentication request, is now mandatory.
This element was previously optional. The mandatory specification of this information makes it possible to provide better **support with problems or API integrations.**In addition to identifying version-specific errors more quickly, we can also use this information to analyze general trends, usage patterns or problems with the various client versions. This helps us to optimize new features specifically for the most frequently used versions. It also allows better documentation of versions and compatibilities, which can significantly simplify future migration processes for customers.
Example of an authentication request:
JSON
{
"apiKey": "JGtjzzFfDoU5UWFl14yalcpj2pwtd0kXHGfBDDBELMPbwcqLyRKBeuiYZ7BxTHi5",
"client": {
"name": "ClientApplicationName",
"version": "1.0.0.0"
}
}
##### End of support for cookie authentication
As part of the modernization of our API, we have decided to remove support for cookie authentication. This decision is based on increased security requirements, as cookies are vulnerable to attacks such as cross-site scripting (XSS) and cross-site request forgery (CSRF). Instead, we rely on the more secure and flexible bearer token authentication, which has established itself as a modern standard in practice. Bearer tokens not only offer better protection, but are also independent of the browser environment and thus enable broader applicability in modern applications such as mobile apps or server-side services.
##### Restructuring of the API endpoints
Due to the no longer supported cookie authentication from API version 6 (`Auth/Login`), the API endpoints for authentication have been restructured. The previous endpoints under `Auth/*` have been replaced by a new, clearer and more consistent naming convention that is more closely aligned with RESTful principles.
| **URL old** | **URL new** | **Description** |
|--------------------|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| Auth/Login | **Removed** | Cookie authentication is no longer supported from API version 6. Instead, a token must now be authenticated via `authentication/token` be used. |
| `Auth/Login/Token` | `authentication/token` | Requests a new access token. |
| `Auth/Logout` | `authentication/token/revoke` | Revokes an active access token. |
| `Auth/Scope` | `authentication/scopes` | Retrieves the authorizations of the current API key. |
| `Auth/Scope/All` | `authentication/scopes/all` | Lists all available API authorizations. |
##### Adaptation of the scopes
Due to the adjustment of the API endpoints, the introduction of new endpoints and the removal of endpoints that are no longer required, the **API scopes were updated.**
| Old scope (up to API version 5) | New scope (from API version 6) |
|---------------------------------|------------------------------------------------|
| `Account` | `Accounts` |
| `Bank` | `Banks` |
| `BankAccount` | `BankAccounts` |
| `Payment` | `Payments` |
| `PaymentStatus` | removed (integrated in "`Payments`") |
| `Document` | divided into "`Documents`" \& "`Transactions`" |
| `ExchangeRate` | `ExchangeRates` |
| `PaymentProvider` | `PaymentProviders` |
| `PayPal` | `PayPal` |
| `User` | `Users` |
| `UserGroup` | `UserGroups` |
Special features:
* When creating a new API key via API version 5 or older:
* The scope "PaymentStatus" is discarded and translated into "Payments".
* The "Document" scope is automatically divided into "Documents" and "Transactions".
* When retrieving scopes for existing API keys:
* For API versions ≤ 5, the API continues to return the old scope names.
* From version 6, only the new scopes are used.
#### Bank accounts
##### New field: Currency
In API version 6, the functionality for creating and updating bank accounts will be extended so that the currency can be specified as an additional parameter in the future. This extension facilitates the implementation of "multi-currency functionalities" and ensures a clear definition and assignment during account creation or updating.
##### Asynchronous deletion of bank accounts
In previous API versions, bank accounts could be deleted synchronously. Due to the increasing dependencies in the system, the growing data volumes and the resulting longer waiting times and higher system load, the process has been optimized so that bank accounts are now deleted asynchronously. This change increases scalability, reduces timeouts and ensures better system stability and an optimized user experience. After successful initiation of the deletion process, the API endpoint returns a tracking identifier of the process along with the initial status.
Example answer:
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"statusCode": 1,
"statusName": "Scheduled",
"details": "Additional information 1",
"operationStatusUrl": "https://portal.konfipay.de/api/v6.0/delete/status/5d12c087-be1e-456c-a33f-4f8750fa7814",
"operationStatusMethod": "GET"
}
##### Status query of the deletion process
Due to the introduction of the asynchronous deletion process, a new API endpoint is also provided, which makes it possible to check the current status of a pending deletion of a bank account. This endpoint provides status information on whether the deletion is being processed, completed or whether an error has occurred.
Example answer:
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"statusCode": 3,
"statusName": "Finished",
"details": "Additional information 1"
}
Further information on this new API interface can be found in the API documentation.
##### Activating/deactivating bank accounts
In this API version, it is possible to activate or deactivate bank accounts when creating or updating them. If a bank account is to be activated, the field `isActive` must be set to `true`. If the field is set to `false`, the bank account is deactivated.
| **Endpoints (up to version 5)** | **Endpoints (from version 6)** |
|------------------------------------|-------------------------------------|
| POST ` /api/{version}/BankAccount` | POST `/api/{version}/bank-accounts` |
| PUT ` /api/{version}/BankAccount` | PUt `/api/{version}/bank-accounts` |
Inactive bank accounts are not taken into account in any automatic processes (e.g. when retrieving account transactions). No payment orders can be created or submitted for inactive accounts.
#### Documents and transactions
##### New endpoints
With API version 6, two new API endpoints were introduced to ensure a clear separation between **banking files** and the extracted **transaction data** (= bookings):
* **Transactions API** : Enables the direct retrieval of bookings in structured form as **JSON**. This eliminates the need to evaluate account transaction files yourself.
* **Transaction Files API**: Provides access to the original account transaction files (e.g. camt.053) and earmarked items if required.
Previously, when using the **Documents API,** it was necessary to retrieve and manually evaluate account transaction files. The new **Transactions API** takes over this step by **konfipay** extracting the contained transactions and saving them directly as well as providing them as **JSON.**This means that you no longer need to process your own banking files.
The **Transaction Files API** assumes the function of the **Documents API** for account transaction files and memo items and replaces them in this area. Other banking documents remain available via the **Documents API** available.
In addition, the previous separation of the end points for **MT94X** and **camt** has been discontinued. Both formats are now available via the **Transaction Files API.** If necessary, the format distinction can be made using the **Filter parameters** in the **Transaction Files API.**
| **Endpoints (up to version 5)** | **Endpoints (from version 6)** |
|-------------------------------------------------------------|------------------------------------|
| `/api/{version}/Document/Camt` `/api/{version}/Document/MT` | `/api/{version}/transaction-files` |
##### Acknowledgenebt of account transaction data
In order to minimize the potentially large amount of account transaction data and the associated high number of API requests, this API version does not require a separate acknowledgement per transaction for the time being.
Instead, this version provides the option of adding an acknowledgement to complete lists of retrieved results.
To do this, when retrieving account transaction data from the list of account transactions (`transactions`) one **temporary ID** (`acknowledgementID`) is assigned. This ID remains valid for **one hour** or is deleted after confirmation. The ID summarizes the account transactions that were grouped on one page of the query and can be used to confirm the transactions on this page. In this case, the status of the transactions changes from `isNew=true` to `isNew=false`.
**Example:**
JSON
{
"pageNumber": 1,
"pageSize": 1000,
"totalPages": 1,
"totalItems": 2,
"links": [
{
"href": "https://portal.konfipay.de/api/v6/Example?pageNumber=1&pageSize=1000",
"rel": "self",
"method": "GET"
}
],
"results": {
"acknowledgementId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
"transactions": [
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-18T08:53:51+01:00",
"amount": 10.99,
"currency": "EUR",
"creditDebitIndicator": "CRDT",
"electronicSequenceNumber": "74",
"name": "Alice Mayer",
"iban": "DE12345678901234567890",
"bic": "ABCDEFG1CBA",
"bookingText": "SAMMELÜBERWEISUNG",
"bookingDate": "2025-02-18T10:06:04+01:00",
"valueDate": "2025-02-18T10:06:04+01:00",
"isNew": false,
"bankReference": "bankRefernceNumber",
"paymentIdentificationId": "konfipay-1-11111",
"primaNota": "9301",
"document": {
"rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
"timestamp": "2025-02-18",
"isNew": true,
"format": "camt.052"
},
"bankAccount": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"iban": "DE09876543210987654321",
"currency": "EUR"
}
},
{
"rId": "fa727310-3072-4abc-a982-b511b8b81108",
"timestamp": "2025-02-18T08:53:51+01:00",
"amount": 500,
"currency": "EUR",
"creditDebitIndicator": "DBIT",
"electronicSequenceNumber": "82",
"name": "Alice Mayer",
"iban": "DE12345678901234567890",
"bic": "ABCDEFG1CBA",
"bookingText": "GUTSCHRIFT ÜBERWEISUNG",
"bookingDate": "2025-02-18T10:06:04+01:00",
"valueDate": "2025-02-18T10:06:04+01:00",
"isNew": true,
"bankReference": "bankRefernceNumber",
"paymentIdentificationId": "konfipay-1-11112",
"primaNota": "9301",
"document": {
"rId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
"timestamp": "2025-02-18",
"isNew": true,
"format": "camt.053"
},
"bankAccount": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"iban": "DE09876543210987654321",
"currency": "EUR"
}
}
]
}
}
##### New fields: Statement number and electronic statement number for Camt and MT940
Two new fields have been added to the response when retrieving banking account transaction documents (camt and MT94X): the **Statement number** (`legalSequenceNumber`) and the **Electronic statement number** (`electronicSequenceNumber`). Both fields are optional and reflect the information contained in the documents provided by the respective bank.
##### New element: Information about the account holder for Camt and MT940
In the older API versions, the IBAN could be used to retrieve account transaction documents. However, as the IBAN is no longer unique, the transactions from two different accounts may be delivered when retrieved. For this reason, this API version adds a new element to the response from banking account transaction documents (camt and MT940): the **information about the underlying bank account** (`bankAccount`). This new element includes important information such as RID, IBAN and currency (`currency`) of the bank account. It ensures a more transparent and accurate allocation to an existing bank account, even when using different currencies.
Example:
JSON
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"href": "api/v6.0/transaction-files/5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-26T11:14:25+01:00",
"isNew": false,
"format": "camt.053",
"fileName": "2025-02-25_C53_DE12345678901234567890_EUR_21-00001.xml",
"electronicSequenceNumber": 1,
"legalSequenceNumber": 1,
"bankAccount": {
"rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
"iban": "DE12345678901234567890",
"currency": "EUR"
}
}
#### Payments and payment files
##### Retrieval of the payment overview
API version 6 introduces an extension in the payment area that enables a list of existing payment files. Various parameters can be used in the query to filter the results list according to different criteria. For example, payments can be filtered by payment type (`purpose`), payment type (`payment-type`) (e.g. transfers, direct debits, etc.), payment status (`status`), creation date (`min-date/max-date`) or execution date (`min-execution-date/max-execution-date`) filter. Further information on this new API interface can be found in the API documentation.
##### Summarizing the API endpoints of payments
The restructuring of the endpoints for payments includes the consolidation of various API interfaces for the transmission and retrieval of payment files. The following endpoints have been combined:
| **Up to API version 5** | **From API version 6** |
|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
| POST `api/v5/Payment/Sepa/Container` POST `api/v5/Payment/Sepa/Pain` POST `api/v5/Payment/ISO20022/Pain` POST `api/v5/Payment/Sepa/DTAZV` | Post `api/v6/payment-files` |
By default, konfipay automatically recognizes the format of submitted payment orders. Automatic recognition can be deactivated via the `scope` parameter.
##### Submission without transfer
With this API version, the option has been added to not immediately transfer payment files to the bank when importing them into konfipay, but to initially only save them in the system. A new API endpoint has been introduced to enable this flexible processing: POST `/api/v6/payment-files/{rid}/submit`.
This endpoint enables the manual transfer of a previously created payment file to the bank server. If a file has already been transmitted, it will not be transmitted again. However, a retransmission can be forced by setting the query parameter `force=true`.
Resending payment files that have already been sent is only recommended if they have been rejected by the bank. In such cases, the `force` parameter allows to try again without having to create a new payment file.
Further information on this new API interface can be found in the API documentation.
##### Extract individual payments from payment files into the open orders
API version 6 offers the option of transferring payment orders from a payment file directly to the open orders without transferring a file to the bank or saving the payment file ( Post `/api/v6/payment-files/extract`). Once the payments have been extracted from the payment file, they can be processed and combined into new payment files. In addition, the jointly imported orders are provided with a unique batch RID to ensure that they can also be subsequently assigned to the original payment file.
Example answer:
JSON
[
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-18T08:53:48+01:00",
"batch": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"numberOfElements": 2
},
...
},
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-18T08:53:48+01:00",
"batch": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"numberOfElements": 2
},
...
}
]
##### Submission of payment orders as (formerly "ccft")
In API version 6, the previous endpoint `/api/v5/Payment/Custom/Windata/Ccft` has been replaced by `/api/v6/payments`. At the same time, the workflow for transferring payments to the bank has been revised.
Previously, submitted payments were converted directly into SEPA files and sent directly to the bank. From API version 6, this now takes place in two separate steps:
1. Submit payments:
* Payments are made via post `/api/v6/payments` and initially saved in the system.
* Payments can still be processed via the API or the web portal before they are transferred.
2. Manual transfer to the bank:
* Using the new API endpoint POST `/api/v6/payments/submit` selected payments can be transmitted to the bank based on their RID.
* konfipay automatically creates the required SEPA pain files and transfers them.
This change allows more flexibility and prevents payments from being transferred immediately after submission before they have been finally checked or processed.
If the creation of the payment file is not successful during the transfer, the process is canceled and the payments remain as `Pending`in the payment orders. If the payment file is created successfully, the payments are assigned to this file and cannot be edited or deleted - regardless of whether the file transfer is successful or not[.](http://nicht.in/) In this case, the status of the payments changes from `Open` to `Pending`.
Further information on this new API interface can be found in the API documentation.
Request example:
{
"batchBooking": true,
"paymentRids": [
"5d12c087-be1e-456c-a33f-4f8750fa7814",
"fa727310-3072-4abc-a982-b511b8b81108"
],
"failOnSubmittedPayments": false
}
##### Retrieval of payment orders
This API version introduces the functionality to process payment orders using the optional batch RID (`batch-rid`) or their status (`status`). When querying the payment orders, a list of orders is returned that were either imported in a batch or have a certain status (`Processed`/`Pending`). If no filter parameter is specified, the complete list of all payment orders is returned. A payment order is considered open if neither a payment file has been created nor a file transfer to the bank has been carried out.
##### Retrieving payments
The new API interface Get `/api/v6/payments/{rid}` enables the retrieval of payment information. This endpoint provides both batch data (`batch`) as well as detailed information on payment (`transaction`). In addition, the account details of the client (`initPartyBankAccount`) and the recipient (`otherPartyBankAccount`) can be viewed. If a payment file exists, this is also available (`paymentFile`).
A comprehensive description of the elements and fields included is available in the associated API documentation.
Example:
JSON
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-02-18T08:53:48+01:00",
"batch": {
"rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
"numberOfElements": 5
},
"transaction": {
"type": "TRF",
"amount": 10055,
"currency": "EUR",
"country": "DE",
"executionDate": "2025-02-17",
"endToEndId": "NOTPROVIDED",
"purposeCode": "SALA",
"chargeBearer": "SLEV",
"instrId": "ABC123456789",
"rmtInfoUStrd": "Reference from the payer to the bank"
},
"initPartyBankAccount": {
"rId": "fa727310-3072-4abc-a982-b511b8b81108",
"iban": "DE12345678901234567890",
"description": "Alice Mayer"
},
"otherPartyBankAccount": {
"rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
"iban": "DE09876543210987654321",
"description": "Bob Mayer"
},
"paymentFile": {
"rId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
"timestamp": "2025-02-18T08:53:48+01:00",
"format": "pain.001",
"executionDate": "2025-02-18",
"paymentType": "CBTRF",
"status": {
"statusValue": "FIN_CONFIRMED",
"uploadTimestamp": "2025-02-18T10:06:01+01:00",
"orderID": "A1BC",
"reasonCode": "TS01",
"reason": "The transfer of the file was successful",
"additionalInformation": "Additional information 1"
}
}
}
##### Deleting payments
The new API endpoint DELETE `/api/v6/payments/{rid}` allows you to delete payments. Only payments that have not been processed can be deleted. Once a payment has been processed and converted into a SEPA file, deletion is no longer possible.
##### Exact specification of the formats
In the previous API versions, only the general format such as "pain" or "container" was returned for the payment files. From API version 6, the specific format, such as "pain.001" or "pain.008", is transmitted in the response.
**Response up to API version 5**:
JSON
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2024-10-18T13:30:48+02:00",
"type": "pain",
"paymentStatusItem": {
"status": "FIN_CONFIRMED",
"uploadTimestamp": "2024-10-18T14:43:01+02:00",
"orderID": "A1BC",
"reasonCode": "TS01",
"reason": "The transfer of the file was successful",
"additionalInformation": "Additional information 1"
}
}
**Response from API version 6**:
JSON
{
"paymentInfo": {
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"timestamp": "2025-01-09T14:36:50+01:00",
"format": "pain.001",
"executionDate": "2025-01-09",
"paymentType": "TRF",
"status": {
"statusValue": "FIN_CONFIRMED",
"uploadTimestamp": "2025-01-09T15:49:03+01:00",
"orderID": "A1BC",
"reasonCode": "TS01",
"reason": "The transfer of the file was successful",
"additionalInformation": "Additional information 1"
}
}
}
##### Rejection of files with multiple SEPA batch bookings
As of API version 6, the submission of files containing more than one SEPA batch booking (Element: ``) is no longer permitted. This adjustment serves to ensure consistent and reliable processing across all testing, display and processing steps.
#### PayPal
##### Support for sandbox accounts
In this API version, the use of PayPal sandbox accounts is possible. Via the field `isSandbox` you can specify whether the PayPal account is operated in the sandbox environment when creating or updating it. By default, this value is set to `false`. If the value is set to `true`, the account can be used flexibly for testing and development purposes.
Example request:
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"description": "Description1",
"clientId": "Adsf-sdffgghghjhklkj_xOFZDwIjP-qeryuioplkjhgfdcvbnu2SfHM0_mnbvcx",
"clientSecret": "akcvkfriooi$^&dfd=dsfdsf=-dsfsdljllerejjlgl;r",
"isActive": true,
"startFetchDate": "2025-01-18T08:53:51+01:00",
"isSandbox": false
}
Example answer:
{
"rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
"description": "Description1",
"clientId": "Ysnf-tQW8usdfsdfsdf_xOFZDwIjP-qsfsdfdfreerkuyiu2SfHM0_ghjghjghD",
"isActive": true,
"timestamp": "2025-02-18T08:53:51+01:00",
"startFetchDate": "2025-01-18T08:53:51+01:00",
"payPalBalances": [
...
],
"isSandbox": false
}
### Dropped API endpoints
Up to API version 5, all payment formats were mapped via a separate API endpoint, so that the status of a payment could be called up centrally across all formats. The PaymentStatus API was provided up to API version 5 ( GET `/api/{version}/PaymentStatus/{rid}`). Combining the API endpoints for payments into a common endpoint (`/api/{version}/payment-files`) eliminates the need to provide a separate API endpoint. From API version 6, the status of a payment can be checked via the endpoint GET `/api/v6/payment-files/{rid}`.
---
language: "de"
---
# API-Versionen
Dieser Artikel beschreibt die Versionierung der konfipay-REST-API. Die technische API-Dokumentation finden Sie [hier](https://portal.konfipay.de/api-docs/index.html).
## Versionierung der REST-API
Die REST-API von konfipay wird über Versionsnummern stabilisiert, um die langfristige Kompatibilität von Integrationen sicherzustellen. Änderungen an einer API können bestehende Implementierungen beeinträchtigen, wenn sogenannte **Breaking Changes** auftreten. Um solche Fälle sauber handhabbar zu machen, erfolgt die Versionierung ausschließlich über ganze Hauptversionen.
Die Version ist Teil der URL und wird in der Form
`api/{version}/endpoint`
angegeben, beispielsweise:
`api/v2/bank-accounts`
Damit obliegt es dem Aufrufer der API, zu entscheiden, welche Version genutzt wird und wann ein Wechsel auf eine neuere Version erfolgt. Ältere Versionen bleiben für einen definierten Zeitraum bestehen, sodass eine Migration planbar durchgeführt werden kann. Abkündigungen von Versionen erfolgen frühzeitig, in der Regel mehr als ein Jahr vor endgültiger Abschaltung.
### Kriterien für eine neue Version
Eine neue Hauptversion (z. B. `v1` → `v2`) wird ausschließlich veröffentlicht, wenn Breaking Changes auftreten. Als Breaking Changes gelten insbesondere:
* Entfernen oder Umbenennen von Feldern in Nachrichten (JSON/XML)
* Änderungen an Enumerationen oder anderen festen Wertebereichen
* Änderung oder Entfernung von URLs
* Entfernen oder Umbenennen von URL-Parametern
* Änderung des Datentyps eines Feldes (z. B. `int` → `string`)
* Einführung neuer Pflichtfelder oder Änderung von Standardwerten
* Änderungen an der fachlichen Semantik oder Logik bestehender Felder (z. B. wenn ein Feld `amount` bisher den Bruttobetrag enthielt und künftig den Nettobetrag ausweist)
* Anpassungen bei HTTP-Statuscodes (z. B. bisher 200, künftig 204)
### Änderungen ohne neue Version
Folgende Anpassungen gelten nicht als Breaking Changes und können innerhalb einer bestehenden Version eingeführt werden:
* Hinzufügen neuer URLs (z. B. zusätzliche Endpunkte)
* Hinzufügen neuer **optionaler** URL-Parameter
* Erweiterung von Requests um **optionale** Felder
* Erweiterung von Responses (z. B. zusätzliche Felder, die Clients ignorieren dürfen)
### Hinweis zur Client-Implementierung
Bei der Implementierung von Clients sollte berücksichtigt werden, dass Änderungen ohne neue Versionsnummer keine Inkompatibilität verursachen dürfen. Insbesondere die Erweiterung von Responses ist unproblematisch, solange Clients tolerant gegenüber unbekannten Feldern sind und diese ignorieren, anstatt sie als Fehler zu interpretieren.
### Versionshistorie
* [API-Version 6](https://wiki.konfipay.de/konfipay/api-version-6.md)
* [API-Version 5](https://wiki.konfipay.de/konfipay/api-version-5.md)
* [API-Version 4](https://wiki.konfipay.de/konfipay/api-version-4.md)
---
language: "de"
---
# API Versions
This article describes the versioning of the konfipay REST API. The technical API documentation can be found [here](https://portal.konfipay.de/api-docs/index.html).
## Versioning of the REST API
The konfipay REST API is stabilized through version numbers to ensure long-term compatibility of integrations. Changes to an API can affect existing implementations when so-called breaking changes occur. To handle such cases in a structured way, versioning is applied exclusively through whole major versions.
The version is part of the URL and is specified in the form
`api/{version}/endpoint`
For example:
`api/v2/bank-accounts`
It is the responsibility of the API consumer to decide which version to use and when to switch to a newer version. Older versions remain available for a defined period of time, allowing migrations to be planned accordingly. Deprecations of versions are announced early, typically more than one year before final shutdown.
### Criteria for a new version
A new major version (e.g., `v1` → `v2`) is released only when breaking changes occur. Breaking changes in particular include:
* Removal or renaming of fields in messages (JSON/XML)
* Changes to enumerations or other fixed value ranges
* Modification or removal of URLs
* Removal or renaming of URL parameters
* Change of a field's data type (e.g., `int` → `string`)
* Introduction of new mandatory fields or modification of default values
* Changes to the semantics or business logic of existing fields (e.g., if a field `amount` previously contained the gross amount and now contains the net amount)
* Adjustments to HTTP status codes (e.g., previously 200, now 204)
### Changes without a new version
The following adjustments are not considered breaking changes and can be introduced within an existing version:
* Adding new URLs (e.g., additional endpoints)
* Adding new optional URL parameters
* Extending requests with optional fields
* Extending responses (e.g., additional fields that clients may ignore)
### Note on client implementation
When implementing clients, it should be ensured that changes without a new version number do not cause incompatibility. In particular, extensions of responses are unproblematic as long as clients are tolerant towards unknown fields and ignore them rather than treating them as errors.
Version history
* [API Version 6 (EN)](https://wiki.konfipay.de/konfipay/api-version-6-en.md)
* [API Version 5 (EN)](https://wiki.konfipay.de/konfipay/api-version-5-en.md)
* [API Version 4 (EN)](https://wiki.konfipay.de/konfipay/api-version-4-en.md)
---
language: "de"
---
# Aufgaben
Unter diesem Reiter können Sie Aufgaben für konfipay sync definieren, also das Senden von Zahlungen und das Abholen von Umsätzen über die API.
## Zahlungen
Um einen neuen Sendeauftrag für Zahlungen anzulegen, wählen Sie den Reiter `Aufgaben`, dann `Zahlungen`,und anschließend `Neu`.
In diesem Fenster kann der Auftrag dann genau mit Typ, Auftragsnamen und Quellordner der Zahlungsdateien definiert werden. Die Option `Unterordner einbeziehen` sorgt dafür, dass auch alle Dateien aus Unterordnern übertragen werden.
Außerdem kann spezifiziert werden, in welchen Ordner fehlerhafte Dateien ausgesteuert werden, und wie konfipay sync mit eingereichten Zahlungen verfährt.
Bitte verwenden Sie bei allen Pfadangaben keine gemappten Laufwerke, sondern den UNC-Pfad.
## Umsätze
Parallel zu den Zahlungen können auch Abholaufträge für Umsätze definiert werden, indem Sie den Reiter `Aufgaben`wählen, dann `Umsätze`und `Neu`.
Im folgenden Fenster wird der Auftrag dann mit Typ, Auftragsnamen und Zielordner für die Umsatzdateien definiert. Die Option `Umsätze historisch abrufen` legt fest, ob auch vergangene Umsätze mit abgerufen werden und wenn ja, in welchem zeitlichen Rahmen.
Die Option "Umsätze bei Abruf quittieren" legt fest, ob die Umsätze nach dem Abruf als abgerufen an die API zurückgemeldet werden. Wenn Sie eine bestimmte Namenskonvention für die Umsatzdateien wünschen, haben Sie mit der Option `Individueller Dateiname`einige Möglichkeiten zur Verfügung. Standardmäßig sind die Dateien nach ihrer konfipay RID benannt.
Bitte verwenden Sie bei allen Pfadangaben keine gemappten Laufwerke, sondern den UNC-Pfad.
## Aufgaben manuell ausführen
Um eine erstellte Aufgabe manuell auszuführen, muss diese Aufgabe in konfipay sync markiert und über `Ausführen` angestoßen werden.
Es kann nur eine Aufgabe auf einmal manuell ausgeführt werden.
---
language: "de"
---
# Authorising payments with konfipaySign
This function is only available if the konfipaySign [module](https://wiki.konfipay.de/konfipay/modules) is activated in your client.
Before you can authorise payments or see results from the [Verification of Payee (VoP)](https://wiki.konfipay.de/konfipay/verification-of-payee-vop-konfipay), you must first retrieve the open [VEU orders from the bank server](https://wiki.konfipay.de/konfipay/fetch-veu-orders). To do this, you can click on `Update` in the toolbar. If the retrieval was successful and new VEU orders are available, they are displayed here in the list.
To view the details of a VEU order, double-click on the order or select it in the list and click on `Details`. To view or download the original file, click on `File view` in the toolbar. You can see an overview of the VoP results if you hover your mouse over the colored bar in the "Payee verification" column".
In the file view of VEU orders, the [user group permission management](https://wiki.konfipay.de/konfipay/permission-management) applies as usual - for example, wage and salary payments (PurposeCode: SALA) cannot be viewed here either if this has been defined accordingly in the user groups.
## Authorise or cancel VEU order
You can authorise one or more orders by selecting them in the list and clicking on `Sign`. First, the results of the recipient check will be presented to you, provided that this function is active. If there is no complete match for the recipient information for one or more orders, you must actively confirm that you have taken note of these results by checking the box and clicking on `Sign orders`.
If there is a partial match for an order, you can automatically transfer the reported recipient information to the corresponding payment partner after the payment has been transferred. How this works is documented here.
If you want to reject a payment order based on the result of the recipient check, you must cancel the entire order and resubmit and sign it with the corrected recipient data.
If the password for the EBICS key of the corresponding EBICS contact [is not saved](https://wiki.konfipay.de/konfipay/ebics-keys#EBICSkeys-ManagestorageoftheEBICSkeypassword) or [must be entered manually,](https://wiki.konfipay.de/konfipay/ebics-en#EBICS(EN)-Automationsettings) you must enter this password to carry out the release.
A window then opens in which the orders to be authorised are listed. By clicking on `Details`, you can make sure once again that the correct payment has been selected for authorisation/cancellation. You confirm the authorisation by clicking on `Signing` in the bottom right-hand corner. Once the payment has been approved, konfipaySign reports the corresponding status for the payment in this window:
Authorising the order
Positive feedback from authorisation
The procedure for canceling payments is identical to the approval process - select the relevant payments in the list and click on `Cancel`.
You can also automate the approval of VEU orders - you can find more information on this [here](https://wiki.konfipay.de/konfipay/automatic-signature-in-konfipaysign).
## Which VEU orders are displayed?
Please note that the same VEU order can also be displayed several times in the list if you can provide a signature with several different EBICS contacts. Pay attention to the entry in the column `Caller Subscriber ID`. If you want to authorise a VEU order that is displayed multiple times with a specific EBICS contact, select the order in the list for which the correct EBICS contact is entered in the `Caller Subscriber ID` column.
By default, only VEU orders for which you can provide a signature are displayed here in the list. In the drop-down menu at the top left below the menu bar, you can instead choose to display all VEU orders, including those that cannot be signed by the contact making the retrieval. You can also restrict the orders to be displayed to certain clients.
## Which VEU orders are not displayed?
Orders are hidden if the user does not have access to the retrieving EBICS contact. This is the case if the [key of the EBICS contact is assigned to another user](https://wiki.konfipay.de/konfipay/ebics-keys#EBICSkeys-Userassignment). As a result, all EBICS contacts that use this key are not displayed for the current user. Consequently, all corresponding VEU orders are also hidden. In addition, all VEU orders are hidden if the ordering party account is not displayed due to a user's rights restrictions.
---
language: "de"
---
# Auto delete
If necessary, konfipay can automatically delete data in accordance with the relevant deletion periods. This may be relevant, for example, in order to comply with internal deletion deadlines or data protection regulations such as the EU GDPR. Under [deletion settings](https://wiki.konfipay.de/konfipay/deletion-settings) you can set whether and which files should be deleted automatically and at what frequency.
konfipay checks every 24 hours whether the defined deadlines have been reached. If this is the case, the corresponding data is deleted. Under [deletion reports](https://wiki.konfipay.de/konfipay/deletion-reports) you can also call up deletion reports for better traceability.
* [Deletion settings](https://wiki.konfipay.de/konfipay/deletion-settings.md)
* [Deletion reports](https://wiki.konfipay.de/konfipay/deletion-reports.md)
---
language: "de"
---
# Automatic signature in konfipaySign
This function is only available if the konfipaySign [module](https://wiki.konfipay.de/konfipay/modules) is activated in your client.
The signature of VEU orders can be automated within konfipaySign. The prerequisite for this is that the EBICS contact that is to be used for the automated signature is also [set up for automation](https://wiki.konfipay.de/konfipay/ebics-en#EBICS(EN)-Automationsettings).
The automatic signature applies to the following payments:
* Payments that were transferred without [Verification of Payee (VoP)](https://wiki.konfipay.de/konfipay/verification-of-payee-vop-konfipay)
* Payments that were transferred with Verification of Payee and for which the verification resulted in a complete match
The following payments are not automatically approved, even if the automatic signature is set up:
* Payments that were transferred with Verification of Payee and where the verification resulted in a partial match or no match at all.
In the latter case, you must take manual action. Either approve the payment manually after reviewing it or transfer it again with an adjusted payee.
## Manage automation rules
Open the settings for automated tasks by editing an EBICS contact under [EBICS](https://wiki.konfipay.de/konfipay/ebics-en) and clicking on `Automatic signature` in the toolbar. You can then set up a rule for automatic signatures for the selected EBICS contact.
After you click on `Automatic Signatures` you will see a list of all active rules for this contact. This list is empty the first time you open it, as no rules have been set up yet. Click at the top on `Add` to create a new rule for this EBICS contact.
In the area [Push Services](https://wiki.konfipay.de/konfipay/push-services-en) within the administration of your client, you can personalize the notification settings for VEU-related events.
### Criteria-based automation
When creating a rule, you can specify the criteria for which this rule should apply. You can choose from the following:
* Payment method (credit transfer or direct debit)
* Maximum amount up to which automatic authorisation should take place
* Currency for which the rule is to apply (this specification is optional --- if no currency is specified, all payments below the amount limit will be signed, regardless of the currency)
If you would like to be informed about the automatic releases, you can confirm this at the bottom of the window by ticking the box. Save the rule by clicking on `Save`.
In the example shown, all open VEU orders for transfers up to a maximum of EUR 100 would be authorised automatically. The automatic retrieval of open VEU orders takes place every 8 hours by default. The automated authorisation of open VEU orders takes place every hour by default. In the [automation](https://wiki.konfipay.de/konfipay/automation) area (management of program-wide jobs), these rhythms can be adjusted.
### Automation for all orders
You also have the option of setting up automation for all orders, regardless of criteria such as amount or currency. To do this, click on `Sign all automatically` in the "Automatic signature" area of an EBICS contact in the toolbar. You can then check the `Sign all automatically` box and select whether you want to be automatically informed about automatic approvals.
Please note that if you activate this option, all VEU orders for this EBICS contact will be released automatically, without exception. The order is then no longer checked manually. The use of this function is at your own risk.
## Application example for automated release
To illustrate how the automated release works, let's look at an example payment - a transfer to the fictitious Hamburger Eisenwerke for EUR 87.33.
Once this payment has been transferred to the bank via EBICS, it is transferred to the VEU (provided the VEU is configured by the bank and the transfer is made with a properly configured contact). This means that the payment must first be authorised via VEU, e.g. via konfipaySign, before it is executed.
konfipay regularly carries out an automatic retrieval of all open VEU orders. This open VEU order is retrieved and displayed in konfipaySign. For all open VEU orders, a regular automatic check is carried out to see whether the order falls under an automation rule - if so, the order is automatically authorised. In the example, the rule set up looks as follows:
In this case, the VEU order is a transfer of less than EUR 100, so the release is automatically issued by the retrieving EBICS contact. After the release, you will receive a notification about the event, provided that the check mark to `Automatically notify` is set.
The rhythms of the automatic actions, i.e. the automatic retrieval of open VEU orders and the automated release of open VEU orders, can be set in the [automation](https://wiki.konfipay.de/konfipay/automation) (management of program-wide jobs).
---
language: "de"
---
# Automating tasks
konfipay sync also executes certain tasks automatically if desired. To set up this automation, select the tab `Automation` in konfipay sync. Via the button `New` you can set up the automation of a task.
## Automation of tasks
Under `Task` first select the task to be automated from the list and name the automation process. If this list is empty, the [task](https://wiki.konfipay.de/konfipay/tasks) must be defined under the previous tab `Tasks`.
## Automated login
Under `Login`, select the corresponding user account of your operating system under which the task is to be automated. If this is a domain account, check the appropriate box and enter the domain name.
The button `Current user`automatically fills in the user name of the currently logged in user.
Make sure that the selected user has sufficient read and write permissions in the corresponding directories.
## Automation interval
In the following, under`Interval` you can specify the interval at which the task should be repeated. Depending on the interval, you will be asked to specify an exact start time and repetition time. The last point `Finish` summarizes the selected properties once again.
Once the tasks have been set up and automated, konfipay sync no longer needs to be started separately - the automation works in the background.
---
language: "de"
---
# Automation
You can automate some parts of your client's bank communication in konfipay. This means that konfipay then carries out certain tasks automatically on a regular basis.
## Configure automation
To configure the automation, click on `Automation` in the navigation bar on the left-hand side of the administration area.
In the overview, you can see all tasks that can be automated. You can activate or deactivate automation for each task and set the interval at which the task is to be repeated. To change the automation interval of a task, select this task in the list and click on `Edit`.
You can execute a task manually at any time outside of the automation cycle by selecting the task in the list and clicking on `Perform task`.
## Configure EBICS contacts for automation
Please note that the automation in konfipay via EBICS can only work if the EBICS contacts of your client are configured accordingly. The EBICS password for the EBICS key used must be saved in the database and the automation must be activated for the EBICS contact that you want to use. You can make these settings under [automation settings for each EBICS contact](https://wiki.konfipay.de/konfipay/ebics-en#Automation-settings).
---
language: "de"
---
# Automatische Unterschrift in konfipaySign
Diese Funktion ist nur verfügbar, wenn das [Modul](https://wiki.konfipay.de/konfipay/module) *konfipaySign* in Ihrem Mandanten aktiviert ist.
Die Freigabe von VEU-Aufträgen kann innerhalb von konfipaySign automatisiert werden. Voraussetzung hierfür ist, dass der EBICS-Kontakt, der für die automatische Unterschrift genutzt werden soll, auch [für die Automatisierung eingerichtet](https://wiki.konfipay.de/konfipay/ebics#EBICS-Automatisierungseinstellungen) ist.
Die automatische Unterschrift greift für folgende Zahlungen:
* Zahlungen, die ohne [Empfängerprüfung (Verification of Payee, VoP)](https://wiki.konfipay.de/konfipay/verification-of-payee-vop-konfipay) übertragen wurden
* Zahlungen, die mit Empfängerprüfung übertragen wurden und bei denen die Empfängerprüfung eine vollständige Übereinstimmung für alle Zahlungsempfänger ergeben hat
Folgende Zahlungen werden nicht automatisch freigegeben, auch wenn die automatische Unterschrift eingerichtet ist:
* Zahlungen, die mit Empfängerprüfung übertragen wurden und bei denen die Empfängerprüfung eine teilweise oder gar keine Übereinstimmung ergeben hat.
Im letzten Fall müssen Sie manuell tätig werden. Entweder geben Sie die Zahlung manuell nach Sichtung frei oder übertragen sie mit angepasstem Zahlungsempfänger erneut.
## Automatisierungs-Regeln verwalten
Öffnen Sie die Einstellungen für die automatischen Unterschriften, indem Sie unter [EBICS](https://wiki.konfipay.de/konfipay/ebics) einen EBICS-Kontakt bearbeiten und in der Menüleiste auf `Automatische Unterschift` klicken. Dann können Sie für den ausgewählten EBICS-Kontakt eine Regel für automatische Unterschriften einrichten.
Nachdem Sie auf `Automatische Unterschrift` geklickt haben, sehen Sie eine Auflistung aller aktiven Freigabe-Regeln für diesen Kontakt. Beim ersten Aufruf ist diese Liste leer, da noch keine Regeln eingerichtet sind. Klicken Sie oben auf `Hinzufügen`, um für diesen EBICS-Kontakt eine neue Regel zu erstellen.
Im Bereich [Push Services](https://wiki.konfipay.de/konfipay/push-services) innerhalb der Administration Ihres Mandanten können Sie die Benachrichtigungseinstellungen für Ereignisse rund um die VEU personalisieren.
### Kriterienbasierte Automatisierung
Bei der Erstellung einer Regel können Sie angeben, für welche Kriterien diese Regel greifen soll. Zur Auswahl stehen:
* Zahlungsart (Überweisung oder Lastschriften)
* Maximalbetrag, bis zu dem die automatische Freigabe erfolgen soll
* Währung, für die die Regel gelten soll (diese Angabe ist optional - wenn keine Währung angegeben wird, werden werden alle Zahlungen unterhalb der Betragsgrenze unterschrieben, unabhängig von der jeweiligen Währung.)
Wenn Sie über die automatischen Freigaben informiert werden möchten, können Sie das am unteren Rand des Fensters mit dem Häkchen bestätigen. Speichern Sie die Regel mit einem Klick auf `Speichern`.
In dem abgebildeten Beispiel würden alle offenen VEU-Aufträge für Überweisungen bis maximal 100 EUR automatisch freigegeben. Der automatische Abruf der offenen VEU-Aufträge erfolgt standardmäßig alle 8 Stunden. Die automatisierte Freigabe der offenen VEU-Aufträge erfolgt standardmäßig im stündlichen Rhythmus. Im Bereich [Automatisierung](https://wiki.konfipay.de/konfipay/automatisierung) (Verwaltung der programmweiten Jobs) können diese Rhythmen angepasst werden.
### Automatisierung für alle Aufträge
Sie haben auch die Möglichkeit, eine Automatisierung für alle Aufträge einzurichten, unabhängig von Kriterien wie Betrag oder Währung. Klicken Sie dazu im Bereich "Automatische Unterschrift" eines EBICS-Kontaktes in der Toolbar auf `Alles automatisch unterschreiben`. Dann können Sie einen Haken bei `Alles automatisch unterschreiben` setzen und auswählen, ob Sie automatisch über die automatischen Freigaben informiert werden wollen.
Bitte beachten sie, dass bei Aktivierung dieser Option ausnahmslos alle VEU-Aufträge für diesen EBICS-Kontakt automatisch freigegeben werden. Es erfolgt dann keine manuelle Prüfung des Auftrags mehr. Die Nutzung dieser Funktion erfolgt auf eigenes Risiko.
## Anwendungsbeispiel für die automatisierte Freigabe
Um die Funktionsweise der automatisierten Freigabe zu verdeutlichen, betrachten wir eine Beispiel-Zahlung - eine Überweisung an die fiktiven Hamburger Eisenwerke über 87,33 EUR.
Nachdem diese Zahlung über EBICS an die Bank übertragen wurde, läuft sie dort in die VEU (sofern die VEU bankseitig konfiguriert ist und die Übertragung mit einem entsprechenden Kontakt erfolgt). Das heißt, dass die Zahlung erst mittels VEU, z.B. über konfipaySign, freigegeben werden muss, bevor sie ausgeführt wird.
konfipay führt regelmäßig einen automatischen Abruf aller offenen VEU-Aufträge durch. Dabei wird dieser offene VEU-Auftrag abgerufen und in konfipaySign angezeigt. Für alle offenen VEU-Aufträge wird regelmäßig automatisch geprüft, ob der Auftrag unter eine Automatisierungsregel fällt - wenn ja, wird der Auftrag automatisch freigegeben. Im Beispiel sieht die eingerichtete Regel wie folgt aus:
In diesem Fall handelt es sich bei dem VEU-Auftrag um eine Überweisung unter 100 EUR, sodass die Freigabe automatisch durch den abrufenden EBICS-Kontakt erteilt wird. Nach der Freigabe erhalten Sie eine Benachrichtigung über das Ereignis, sofern der Haken bei `Automatisch informieren` gesetzt ist.
Die Rhythmen der automatischen Aktionen, also des automatischen Abrufs offener VEU-Aufträge und der automatisierten Freigabe offener VEU-Aufträge, können im Bereich [Automatisierung](https://wiki.konfipay.de/konfipay/automatisierung) (Verwaltung der programmweiten Jobs) angepasst werden.
---
language: "de"
---
# Automatisierung
Sie können einige Teile der Bankenkommunikation Ihres Mandanten in konfipay automatisieren. Das heißt, dass konfipay bestimmte Aufgaben dann regelmäßig selbstständig durchführt.
## Automatisierung konfigurieren
Um die Automatisierung zu konfigurieren, klicken Sie innerhalb des Administrationsbereichs links in der Navigationsleiste auf `Automatisierung`.
In der Übersicht sehen Sie alle Aufgaben, die automatisiert werden können. Sie können die Automatisierung für jede Aufgabe aktivieren oder deaktivieren, und das Intervall festlegen, in dem die Aufgabe wiederholt werden soll. Um das Automatisierungs-Intervall einer Aufgabe zu ändern, wählen Sie diese Aufgabe in der Liste aus und klicken oben in der Toolbar auf `Bearbeiten`.
Sie können eine Aufgabe jederzeit außerhalb des Automatisierungszyklus manuell ausführen, indem Sie die Aufgabe in der Liste auswählen und oben in der Toolbar auf `Aufgabe ausführen` klicken.
## EBICS-Kontakte für die Automatisierung konfigurieren
Beachten Sie, dass die Automatisierung für Aufgaben über EBICS in konfipay nur funktionieren kann, wenn die EBICS-Kontakte Ihres Mandanten entsprechend konfiguriert sind. Das EBICS-Passwort für den verwendeten EBICS-Schlüssel muss in der Datenbank gespeichert sein, und die Automatisierung muss für den verwendeten EBICS-Kontakt aktiviert sein. Diese Einstellungen können Sie unter [Automatisierungseinstellungen](https://wiki.konfipay.de/konfipay/ebics#Automatisierungseinstellungen) für jeden EBICS-Kontakt vornehmen.
---
language: "de"
---
# Automatisierung von Aufgaben
konfipay sync führt bestimmte Aufgaben auf Wunsch auch automatisch aus. Um diese Automatisierung einzurichten, wählen Sie den Reiter `Automatisierung` in konfipay sync. Über den Button `Neu` können Sie die Automatisierung einer Aufgabe durchführen.
## Automatisierung von Aufgaben
Unter `Aufgabe` wählen Sie zunächst in der Liste die Aufgabe aus, die automatisiert werden soll, und benennen Sie den Automatisierungsvorgang. Wenn diese Liste leer ist, muss die [Aufgabe](https://wiki.konfipay.de/konfipay/aufgaben) zuvor unter dem Reiter `Aufgaben`definiert werden.
## Automatisierte Anmeldung
Danach wählen Sie bei `Anmeldung` das entsprechende Benutzerkonto Ihres Betriebssystems, unter dem die Aufgabe automatisiert werden soll. Falls es sich um ein Domänenkonto handelt, setzen Sie den Haken an der entsprechenden Stelle und geben den Domänennamen ein.
Der Button `Aktueller Benutzer`füllt automatisch den Nutzernamen des aktuell angemeldeten Nutzers ein.
Stellen Sie sicher, dass der gewählte Benutzer ausreichend Lese- und Schreibberechtigungen in den entsprechenden Verzeichnissen besitzt.
## Automatisierungsintervall
Im Folgenden legen Sie unter`Intervall` fest, in welchem Rhythmus die Aufgabe wiederholt werden soll. Je nach Intervall werden Sie aufgefordert, einen exakten Startzeitpunkt und Wiederholungszeitpunkt festzulegen. Der letzte Punkt `Fertigstellen` fasst noch einmal die gewählten Eigenschaften zusammen.
Wenn die Aufgaben einmal eingerichtet und automatisiert sind, muss konfipay sync nicht mehr separat gestartet werden -- die Automatisierung funktioniert im Hintergrund.
---
language: "de"
---
# Balances
Here you can view the current account balances for your client's bank accounts. Select an account from the top list to view the account balances over time.
You can display the account balances over time either as a table or as a chart. To do this, select the desired account in the list and click on the corresponding option at the top of the toolbar.
If you are missing some accounts in the list, this may be because accounts without a balance are hidden by default. To change this, uncheck the box next to `Hide bank accounts without account balance` out.
---
language: "de"
---
# Bank accounts
Here you can manage all bank accounts that belong to your client - these are all the bank accounts for which you can create payments and retrieve transactions. You can also manage how individual accounts communicate with the bank here.
## Add bank account
If you want to create payments for a bank account in konfipay, you must first create this account. There are the following options for creating a bank account:
### Manual creation
At the top of the toolbar, click on `Add`. `IBAN` and `Designation` are mandatory fields. If only an account number and no IBAN is available, enter the account number in the IBAN field instead. When saving, konfipay will display a corresponding message, but the information will be saved nonetheless. To make international payments, it is recommended that you also enter name and address.
If you use multiple EBICS contacts, you can select in the "Settings" tab under `EBICS contact` at the bottom to define which EBICS contact should be used for communicating with the bank regarding the account. If you have only one EBICS account or intend to use the account [via SRZ](https://wiki.konfipay.de/konfipay/ebics-or-srz) or another means, you can leave this field blank.
Additional settings you can configure when manually creating bank accounts are [documented below](https://wiki.konfipay.de/konfipay/bank-accounts#Further-settings-for-bank-accounts).
Tab "Bank account"
Tab "Settings"
### Creation via EBICS account list
Some banks transfer account data when an [EBICS contact](https://wiki.konfipay.de/konfipay/ebics-en) is set up automatically, They transfer a list of associated bank accounts, which konfipay is able to read and to use in order to create the corresponding bank accounts automatically. This means that you may not have to create your bank accounts manually when setting up konfipay.
The account list is also retrieved automatically at set intervals so that bank accounts that are added after the EBICS contact has been set up, are also created in konfipay without the need for manual entry.
### Creation via FinTS/XS2A bank connection
When you [add a FinTS/XS2A bank connection](https://wiki.konfipay.de/konfipay/add-a-fints-xs2a-bank-connection.md), konfipay automatically imports the associated bank accounts into the master data. This means you do not need to create these accounts manually.
### Creation via API
Bank accounts can also be managed by external applications via the konfipay API. Further information on creating bank accounts via the API can be found in the [API documentation](https://portal.konfipay.de/api-docs).
### Creation on payment submission
In the [API settings](https://wiki.konfipay.de/konfipay/api-settings) under the tab *Actions,* the setting `Automatic setup of bank accounts` can be activated. This means that when a payment is submitted, the associated bank account is automatically created in konfipay if it does not already exist.
### Further settings for bank accounts
#### Country default for file creation
Depending on the country in which the account-holding bank is located, different guidelines apply for payment transaction files. The country default for file creation setting can be used to specify which country default is to be used to create the payment transaction file for this account. It is not usually necessary to change this value manually. When setting up a bank account, konfipay automatically determines the country setting based on the two-digit ISO country code of the IBAN.
#### Format default for file creation
This setting controls which format version konfipay uses when generating payment transaction files (fully prepared files submitted via import or the API are not affected by this). `Common formats` stands for the proven format version that is accepted by practically all banks. `Latest formats` stands for the respective latest format version -- this has to be supported by your bank.
**Format changeover 2026:** On **20 October 2026** , konfipay centrally switches the setting to `Latest formats` for all bank accounts, as the previously common formats (pain.001.001.03, pain.008.001.02) are considered outdated as of the deadline on **15 November 2026** . From the deadline onwards, both options -- `Common formats` and `Latest formats` -- produce the same formats (pain.001.001.09, pain.008.001.08); the setting then temporarily has no effect. As some banks only accept the new formats via EBICS 3.0, we strongly recommend switching your EBICS contacts to [EBICS 3.0](https://wiki.konfipay.de/konfipay/switch-to-ebics-3-0.md) beforehand where possible.
**Future format versions:** With the update that introduces a new format version (e.g. pain.001.001.10), that version is made available under `Latest formats` and all bank accounts are set to `Common formats` at the same time. File creation therefore remains unchanged; the new version can be selected per bank account as soon as the bank supports it.
Further information: Version 5.2.0 (English release notes in preparation), [SEPA formats from November 2026](https://wiki.konfipay.de/konfipay/sepa-formats-from-november-2026-konfipay.md)
If your bank regularly rejects payments due to incorrect format, you may need to adjust the "Format default for file creation".
The setting applies per bank account and to all payment types. Which format version is actually generated additionally depends on the `Country default for file creation` and on the payment type. For some payment types only one format is permitted - there the setting has no effect, and no message is displayed. The following subsections show, by country and payment type, which format is used depending on the setting (status before version 5.2.0).
##### Germany (country default DE)
The country default DE is the standard for all accounts except those in Austria, Switzerland and Liechtenstein.
| Payment type | Common formats | Latest formats | Note |
|----------------------------------------------------------|-----------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Credit transfer (SEPA, incl. urgent and instant payment) | pain.001.001.03 | pain.001.001.09 | |
| Direct debit (CORE / B2B) | pain.008.001.02 | pain.008.001.08 | |
| International payment (AZV) | pain.001.001.09 | pain.001.001.09 | **No effect** with a German IBAN - pain.001.001.03 is not permitted for international payments under the DFÜ agreement. Only with a non-German IBAN does `Common formats` produce pain.001.001.03. |
##### Austria (country default AT)
| Payment type | Common formats | Latest formats | Note |
|----------------------------------------------|-----------------|-----------------|--------------------------------------------------------------------------------------|
| Credit transfer (SEPA, incl. urgent payment) | pain.001.001.03 | pain.001.001.09 | |
| Instant payment | pain.001.001.09 | pain.001.001.09 | **No effect** - in Austria, instant payments are only supported in the newer format. |
| Direct debit (CORE / B2B) | pain.008.001.02 | pain.008.001.08 | |
| International payment (AZV) | pain.001.001.03 | pain.001.001.09 | |
| Tax office payment | pain.001.001.03 | pain.001.001.03 | **No effect** - as an instant payment, pain.001.001.09 is generated. |
##### Switzerland and Liechtenstein (country default CH)
| Payment type | Common formats | Latest formats | Note |
|-----------------------|-----------------|-----------------|---------------|
| Credit transfer | pain.001.001.03 | pain.001.001.09 | |
| Direct debit (CH-DD) | pain.008.001.02 | pain.008.001.02 | **No effect** |
| International payment | pain.001.001.09 | pain.001.001.09 | **No effect** |
#### Generate account statement files - MT940 from camt.053
Activate this setting to automatically create MT940 files based on the camt.053 files provided by the bank. The MT940 files created are automatically assigned to your database and can be viewed, downloaded, or accessed via the konfipay API as transaction files.
The generated MT940 file does not officially come from your bank. We generate the files based on the MT940 standard, but do not guarantee that the file format is fully compatible with your system landscape.
#### SRZ statement processing
By participating in the SRZ procedure, account transactions are provided, depending on the agreement. If this is no longer desired (e.g. because the account transactions are retrieved via another access such as EBICS), the processing of transactions provided via SRZ can be deactivated via this option. This option takes effect immediately after saving, but has no effect on existing account transactions - these are retained. Deactivating the processing in konfipay is therefore generally much quicker and easier than revoking the provision at the service data center. Nevertheless, it is recommended to revoke the provision if this is no longer desired. If the revocation is not made, konfipay will no longer process the files, but they will still be provided by the service data center.
## Settings for Verification of Payee (VOP)
[Verification of Payee (VOP)](https://wiki.konfipay.de/konfipay/verification-of-payee-vop-konfipay) can be controlled individually for each bank account. VOP can be enabled or disabled for bulk payments and single payments for each account. By default, the preferences for VOP stored under [Settings](https://wiki.konfipay.de/konfipay/api-settings) apply to all bank accounts.
To change the VOP settings for a single bank account (or a group of bank accounts), select the relevant accounts from the list. Then click `Verification of Payee` at the top of the toolbar.
You can then enable or disable VOP in general on the left. On the right, you can enable or disable VOP for single payments. If VOP is enabled in general, then VOP is always automatically enabled for single payments.
In the bank account overview, you can see for each account individually whether VOP is currently enabled in general and for single payments. If the setting has been made individually at account level, this is indicated here with the gear icon.
In the [activity log](https://wiki.konfipay.de/konfipay/activity-log), you will find comprehensive documentation of which user changed this setting for which bank account, when, and how.
## Deactivate bank account
You have the option of completely deactivating bank accounts for your client. No more account transactions will then be processed for deactivated bank accounts and no payment files can be submitted. Deactivated bank accounts are hidden in all views - however, existing data linked to deactivated accounts (i.e. account transactions or payment orders) is retained in full.
Deactivating bank accounts can be useful if you have several accounts with a bank but only want to use one of these accounts in konfipay. These accounts would always be created automatically as your client's bank accounts due to the automated retrieval of the account list - by deactivating them, you can prevent this and only work with the accounts you want to work with in konfipay.
To deactivate a bank account, simply select the account in the list and click on `Deactivate` in the toolbar at the top. You will then find deactivated accounts under the item `Deactivated accounts` in the toolbar - you can also reactivate the accounts there if required.
## Manage bank communication
After you create a bank account, konfipay automatically determines the method and, if applicable, the EBICS contact used to connect the account to the bank for automatic payment transfers (when using [automation](http://wiki.konfipay.de/konfipay/automation) or the API). If necessary, you can manually specify which bank connection should be used to access the bank account for automatic payment transfers or payment transfers via the API. To do this, click on `Bank accesses` at the top of the toolbar.
Here you will find a list of all bank accounts in your client. For each account, you can define the upload channel and the download channel here. When selecting a channel, first use the dropdown menu to specify whether the upload or download should take place via EBICS or SRZ. A detailed explanation of the differences between SRZ and EBICS can be found in [this article](https://wiki.konfipay.de/konfipay/ebics-or-srz). You can find instructions on how to set up a bank account with bank access via SRZ [here](https://wiki.konfipay.de/konfipay/setting-up-a-bank-account-for-srz).
If you choose EBICS, select the desired EBICS contact from the dropdown menu. If you choose SRZ, you can manually change the SRZ channel by clicking the pencil icon next to the SRZ channel name. You can then choose a different SRZ channel from all available options (by clicking the circular arrow icon, you can reset the SRZ channel to the default).
When using SRZ for upload, you can also specify an EBICS contact for upload. The reason for this is that certain payment types (such as SEPA Instant Payments or international payments) cannot be transmitted via SRZ. These payment types are then transmitted via the specified EBICS contact.
If you have configured an EBICS contact for upload, you can also specify which method (EBICS or SRZ) should be used for download. If you select EBICS here, the same contact that is configured for the upload will be used.
You can filter the displayed accounts by selecting in the top-left corner which EBICS contact's associated bank accounts should be displayed. Additionally, you can use the corresponding checkboxes in the top-left corner to select that only bank accounts with incorrect or incomplete configurations should be displayed.
Please note that these settings apply only to automatic payment transfers and payment transfers via the API. For manual transactions, you can select the transfer channel individually. To change the available EBICS contacts for manual payment submission, please use the [bank account setting](https://wiki.konfipay.de/konfipay/ebics-en#EBICS(EN)-Bankaccounts) in the EBICS contact administration section.
## Account identifiers
To automatically assign account transactions to an account, konfipay generally uses the IBAN in the transaction files. However, if this is not specified in the transactions or is incomplete, konfipay falls back on the identifiers defined here.
Identifiers consist, for example, of a combination of account number, bank code, BIC and currency of the account. If such an identifier is then found in a transaction file, the file can be assigned to the correct account.
Identifiers are automatically generated for some accounts when the account lists are retrieved via EBICS.
Examples of identifiers for a fictitious account
## Tags
You can use [tags](http://wiki.konfipay.de/konfipay/tags) to mark data in konfipay (e.g., bank accounts). This can be helpful for implementing efficient [content restrictions](https://wiki.konfipay.de/konfipay/permissions#Permissions-Permissionsforcontent(contentrestrictions)), for example. To do this, select the bank account in the list for which you want to manage the tags and click on `Tags` at the top of the toolbar. You will then see the tags already assigned to this account.
Click in the `Tags` field to see all available tags. By clicking on the relevant tags, you can select which tags you want to assign to the account. You can also remove a tag from an account by clicking on the x icon next to the tag.
You can also create a new tag by clicking on the + icon. This opens the creation dialog, and you can assign the newly created tag directly to the account.
## Manage konfipay test accounts
Several test accounts are provided in konfipay for testing purposes. These accounts generate daily test sales and can also be used to test payment submission. The submitted payments are not executed.
You can activate or deactivate these accounts by clicking on `Test accounts`, then selecting the desired account and clicking again in the top bar on `Activate` or `Deactivate` respectively.
For activated test accounts, for example, account transactions are then displayed and the activated accounts can be selected for payment transfers on a test basis.
## FinTS/XS2A as bank access
In addition to EBICS and SRZ, FinTS/XS2A is also available as an upload and download channel since version 5.0.0. If you select FinTS/XS2A when choosing a channel, a `Bank Connection` selection field appears in place of an EBICS contact, allowing you to specify the desired [FinTS/XS2A bank connection](https://wiki.konfipay.de/konfipay/fints-xs2a-finapi.md).
You specify which bank interface is used for uploads (transfers or direct debits) and which is used for downloads for each bank account under `Business Transactions`.
## Account merge
If your bank merges with another bank, your bank account may continue to exist with a new IBAN or BIC. By automatically retrieving the account list, konfipay automatically creates the new account with the new connection information (new IBAN/BIC). In this case, the account is then kept in konfipay twice - once with the old information from before the bank merger, and once with the new information after the merger. When importing account transactions manually, it is also possible that konfipay will create a new bank account for the transactions instead of adding them to the existing account.
You can merge the two accounts to ensure that the data, e.g. account transactions, is retained without any break. This involves transferring the data (payment history, transactions, balances, etc.) from the old account to the new account.
To do this, click on `Account merge` at the top of the toolbar. On the left-hand side, select the `Source account` - i.e. the old account whose data is to be transferred to the new account. On the right, under `Target account`, select the new account to which the data is to be transferred. In the next line, specify what should happen to the old account (source account) after the merge - the source account can be deactivated or completely deleted.
An account merge cannot be undone. Please check your details carefully before you start the merger.
---
language: "de"
---
# Bank transfers
Under **Payment entry** , you will find a range of different bank transfer types in konfipay. The form and its functions are identical for all transfer types. A special case is the cross-border payment, which is described in more detail [further down](https://wiki.konfipay.de/konfipay/bank-transfers#Banktransfers-Cross-borderpayment) on this page.
## List of transfer types
Select the desired type and payment method using the tabs at the top of the page. The numbers on the tabs indicate how many transfers of that type have already been saved.
The various transfer types differ as follows:
| **Designation** | **Description** |
|----------------------|-------------------------------------------------------------------------------------------------|
| Payment | Standard SEPA transfer |
| Instant payment | SEPA Instant Payment |
| Urgent payment | SEPA express credit transfer (CCU) |
| Cross-border payment | [See below](https://wiki.konfipay.de/konfipay/bank-transfers#Banktransfers-Cross-borderpayment) |
Furthermore, you can select the following payment purposes for all transfer types (except cross-border payments):
| **Designation** | **Description** |
|--------------------------|------------------------------------------------------------------------------|
| None | Executes the previously selected transfer type without any further additions |
| Salary payment | SEPA credit transfer with SEPA Purpose Code "SALA" |
| Capital building payment | SEPA credit transfer with SEPA Purpose Code "CBFF" |
| Charity payment | SEPA credit transfer with SEPA Purpose Code "CHAR" |
## Filling out a transfer
Start by selecting the ordering party of the transfer from the drop-down list. The ordering party is the [bank account](https://wiki.konfipay.de/konfipay/bank-accounts) from which the payment is to be sent. If one of your bank accounts is not displayed in this list, this means that the account does not support the respective transfer type.
Select the creditor from the drop-down list of existing payment partners. The recipient's account details (IBAN and BIC) are then displayed to the right of the selection -- as with the ordering party -- and are read-only in the form. This prevents a payment partner's bank details from being accidentally overwritten during selection.
If the recipient has not yet been created as a payment partner, click on the "Plus" symbol next to Creditor to create a new payment partner. If you would like to change the IBAN or BIC of an existing payment partner, select it from the drop-down list and then click on the pencil icon to edit it.
If you would like to make a simple one-time payment, select the `One-time payment` option in the drop-down menu under "Save as". You can find more information on templates and recurring payments further down in the article.
### Balance forecast
Once you have selected the ordering party account and entered the amount, you will automatically see an estimate of the account balance that includes the payment you just entered.
The forecast takes four factors into account: the current balance of the selected bank account, other transactions already in the system, the current transaction itself, and its execution date. Based on these values, konfipay calculates the projected balance as of the execution date and breaks it down in a transparent manner (current balance, future deposits, future debits, current payment, and projected balance). If payments or account balances are in different currencies, konfipay automatically converts them where possible. Please note that this is an estimate based on visible data -- the actual account balance may differ.
## Create payment from QR code
You can create a bank transfer or direct debit from a QR code and generate a payment file directly to save time and avoid typing errors during data entry. To do this, you can either use your device's camera or import an image from your computer. konfipay supports both the EPC QR code (GiroCode) and the Swiss QR code.
To do this, click on the round icon with the QR code in the upper right corner of the transfer/direct debit form, and then click on the QR code icon again.
Launch your camera by clicking `Start camera` or select the `Upload file` tab if you want to upload an image file or PDF of the invoice. Then click `Select files` to choose the appropriate PDF file from your computer, or drag and drop the file into the window.
Once the scan is complete, a screen will open for you to edit the payment partner with whom the transaction is to be carried out. After you save the information displayed, you will see the transfer form and can then save the payment.
## Attach PDF receipt to payment
For each transfer or direct debit, you can attach a related receipt, invoice, or similar documents in PDF format. This document is then directly linked to the transfer or direct debit in konfipay, so you can easily find and view it later. Only one document can be linked per payment.
To do this, click on the round icon with the QR code in the upper right corner of the transfer/direct debit form, and then click on the document icon.
In the window that opens, click `Add` in the toolbar to upload a new document. Then click `Select files` to choose the appropriate PDF file from your computer, or drag and drop the file into the window. You can also view and manage existing documents here.
The attached receipts are not processed here; no data is extracted from them, and no payments are created automatically.
## Create payment template
You can save a payment as a template by filling out the transfer form as usual, but selecting `Template` at the bottom in the "Save as" drop-down menu.
Then give the template a name and specify whether it should be saved as a personal template - then, only you personally can see the template. Otherwise, all members of your client with the corresponding rights will see it.
Also select whether the template should also be added to the payment list. In this case, a payment is created directly alongside the template, which appears in the payment list and can be transferred to the bank.
You can manage saved templates by clicking on the pencil icon at the top of the payment form under "Payment templates". You can then rename and delete templates:
To change templates, open them in the payment form and change the corresponding data. Then click on the small arrow next to "Save" at the bottom right and select `Overwrite payment template`.
## Recurring payments
If you regularly make a certain payment, you can also save it as a recurring payment. The payment is then created repeatedly in a set cycle.
Recurring payments are not executed automatically, but only created automatically. These payments must then be executed manually from the payment list.
To do this, fill out the transfer form in the same way as when creating a template. At the bottom under "Save as", select the `Recurring payment` option in the drop-down menu. After clicking on `Save`, you can further configure the recurring payment.
Enter a description for the recurring payment and specify the interval at which the payment is to be created. The first execution is the date on which the payment is created for the first time. The lead time is the period of time before the due date in which the payment is created. If, as in the screenshot, the first execution is on 07/01 and the lead time is 7 days, the payment will therefore be created automatically on 06/24.
If you specify a runtime, you can define the date up to which the recurring payment should be created. When the runtime ends, the recurring payment is deactivated and can only be reactivated manually once the runtime has been extended.
To manage your recurring payments, click on Recurring payments in the toolbar of the transfer screen. You can then edit the details of the payment, activate or deactivate the payment and delete it. With `Restore payment`, you can also immediately create a single payment that corresponds to the recurring payment.
## Save payment as a draft
If you want to save a payment as a draft, you can leave the amount at 0.00 euros. When you click on `Save` the payment file is created and added to the payment list, but not yet transferred to the bank.
## Payment list and file transfer to the bank
The payment list is located on the right-hand side of the view. All saved, but not yet transferred payments of the selected transfer type are displayed there. If required, you can also select the saved payments again and change or delete them.
You also have the option of making bulk changes, which allows you to edit a group of saved but not yet transferred payments at the same time. To do this, select the relevant payments and click on `Bulk Edit` in the right-hand toolbar. Then select the fields you want to edit by checking the corresponding boxes and enter the desired changes. These will then be applied to all selected payments.
To transfer manually created payments to the bank, visit [Execute \> Submit payments](https://wiki.konfipay.de/konfipay/submit-payments).
## Cross-border payment
The form for cross-border payments differs from other credit transfers because different requirements apply to the information in a payment for cross border payment transactions (outside the SEPA area).
Please note that you can use two different formats for international transfers - the ISO 20022 format and the DTAZV format are available. To switch between the formats, click on `File format` in the menu bar at the top and select the desired format.
According to the German Banking Industry (DK), the DTAZV format will no longer be the DK standard from November 2026 and will be replaced by the ISO 20022 format. Please make sure to switch your processes to the ISO 20022 format by then to avoid complications during the transition.
## Cash discount calculator
If you are granted a cash discount by the creditor of a bank transfer, you can easily calculate the amount with the discount calculator. First, click on `Discount calculator` in the top left of the toolbar. Enter the original amount at the top and the discount as a percentage below. The discount calculator then automatically calculates the discount amount and offsets it against the original amount. Click on `Apply`to transfer the calculated discounted amount to the amount field of the transfer.
If you check the `Enter cash discount in purpose of payment` checkbox, information on the cash discount will also be transferred to the reference line of the transfer.
## Configure view of transfer page
Depending on your requirements, you can also hide or enlarge the transfer form on the left-hand side or the payment list on the right-hand side.
To hide the payment list, click on `Payment list` in the top left-hand corner of the toolbar or on `Hide` in the top right corner of the toolbar. To display the payment list again, simply click again on `Payment list`.
To hide the transfer form, click on `Enlarge` in the top right-hand corner of the toolbar. To display the transfer form again, click on `Reduce`.
## SEPA real-time payments via FinTS/XS2A
When transferring funds via [FinTS/XS2A](https://wiki.konfipay.de/konfipay/fints-xs2a-finapi.md), urgent transfers up to a certain amount can be automatically converted into real-time payments (SEPA Instant Payments)---in accordance with the Instant Payment Regulation. Additional fees and restrictions may apply to SEPA Instant Payments.
---
language: "de"
---
# Bankkonten
Hier können Sie alle Bankkonten verwalten, die zu Ihrem Mandanten gehören - das sind alle Bankkonten, für die Sie Zahlungen erstellen und Umsätze abrufen können. Außerdem können Sie hier die Bankzugänge für einzelne Konten verwalten.
## Bankkonto hinzufügen
Wenn Sie in konfipay für ein Bankkonto Zahlungen erstellen möchten, müssen Sie dieses Konto zuerst anlegen. Folgende Möglichkeiten gibt es, ein Bankkonto anzulegen:
### Manuelle Anlage
Klicken Sie oben in der Toolbar auf `Hinzufügen`. Bei der Anlage sind `IBAN` und `Kontobezeichnung` Pflichtfelder. Falls nur eine Kontonummer und keine IBAN verfügbar ist, tragen Sie stattdessen die Kontonummer in das Feld IBAN ein. Beim Speichern wird konfipay eine entsprechende Mitteilung anzeigen, der Speichervorgang wird jedoch durchgeführt. Um Auslandszahlungen zu tätigen, empfiehlt es sich, Name und Anschrift zusätzlich zu erfassen.
Falls Sie verschiedene EBICS-Kontakte nutzen, können Sie im Reiter "Einstellungen" bei `EBICS-Kontakt` festlegen, über welchen das Bankkonto angesteuert werden soll. Falls Sie nur einen EBICS-Kontakt haben oder [das Konto über SRZ](https://wiki.konfipay.de/konfipay/ebics-oder-srz#EBICSoderSRZ?-Verbindung%C3%BCberSRZ) oder einen anderen Weg nutzen möchten, können Sie das Feld freilassen.
Weitere Einstellungen, die Sie bei der manuellen Erstellung von Bankkonten treffen können, sind [weiter unten](https://wiki.konfipay.de/konfipay/bankkonten#Weitere-Einstellungen-f%C3%BCr-Bankkonten) dokumentiert.
Reiter "Kontodaten"
Reiter "Einstellungen"
### Anlage über EBICS-Kontenliste
Manche Banken übertragen beim Einrichten des [EBICS-Kontakts](https://wiki.konfipay.de/konfipay/ebics) automatisch eine Kontenliste, die konfipay ausliest und die entsprechenden Bankkonten selbstständig anlegt. Unter Umständen müssen Sie Ihre zugehörigen Bankkonten bei der Einrichtung von konfipay also nicht händisch anlegen.
Der Abruf der Kontenliste erfolgt zudem automatisch in festgelegten Intervallen, sodass Bankkonten, welche nach der Einrichtung des EBICS-Kontakts hinzukommen, ebenfalls in konfipay angelegt werden, ohne dass eine manuelle Erfassung erforderlich ist.
### Anlage über FinTS/XS2A-Bankverbindung
Wenn Sie eine [FinTS/XS2A-Bankverbindung hinzufügen](https://wiki.konfipay.de/konfipay/fints-xs2a-bankverbindung-hinzufugen.md), übernimmt konfipay die zugehörigen Bankkonten automatisch in die Stammdaten. Sie müssen diese Konten also nicht manuell anlegen.
### Anlage über die API
Über die API von konfipay können Bankkonten auch durch externe Anwendungen verwaltet werden. Weitere Informationen zur Anlage von Bankkonten über die API können der [API-Dokumentation](https://portal.konfipay.de/api-docs) entnommen werden.
### Anlage über Zahlungseinreichung
In den [API-Einstellungen](https://wiki.konfipay.de/konfipay/api-einstellungen#API-Einstellungen-Aktionen) kann unter dem Reiter *Aktionen* die Einstellung `Bankkonten automatisch anlegen` aktiviert werden. Dadurch wird beim Einreichen einer Zahlung über die API das zugehörige Bankkonto automatisch in konfipay angelegt, sofern es nicht bereits vorhanden ist.
### Weitere Einstellungen für Bankkonten
#### Ländervorgabe für Dateierstellung
Je nach Land, in welchem sich das kontoführende Kreditinstitut befindet, gelten unterschiedliche Richtlinien für Zahlungsverkehrsdateien. Über die Einstellung `Ländervorgabe für Dateierstellung` kann festgelegt werden, nach welcher Ländervorgabe die Zahlungsverkehrsdatei für dieses Konto erstellt werden soll. Eine manuelle Änderung dieses Wertes ist in der Regel nicht notwendig. Bei der Einrichtung eines Bankkontos legt konfipay die Ländereinstellung automatisch anhand des zweistelligen ISO-Ländercodes der IBAN fest.
#### Formatvorgabe für Dateierstellung
Diese Einstellung regelt, in welcher Formatversion konfipay Zahlungsverkehrsdateien erzeugt (fertig eingereichte Dateien via Import oder API sind davon nicht betroffen). `Gängige Formate` steht für die bewährte Formatversion, die von praktisch allen Banken akzeptiert wird. `Neueste Formate` steht für die jeweils neueste Formatversion -- diese muss von Ihrer Bank unterstützt werden.
**Formatumstellung 2026:** Am **20.10.2026** stellt konfipay die Einstellung zentral bei allen Bankkonten auf `Neueste Formate` um, da die bisher gängigen Formate (pain.001.001.03, pain.008.001.02) mit dem Stichtag am **15.11.2026** als veraltet gelten. Ab dem Stichtag erzeugen beide Optionen -- `Gängige Formate` und `Neueste Formate` -- dieselben Formate (pain.001.001.09, pain.008.001.08); die Einstellung ist dann vorübergehend ohne Wirkung. Da vereinzelt Banken die neuen Formate nur über EBICS 3.0 annehmen, empfehlen wir dringend, die EBICS-Kontakte nach Möglichkeit vorher auf [EBICS 3.0](https://wiki.konfipay.de/konfipay/umstellung-auf-ebics-3-0.md) umzustellen.
**Künftige Formatversionen:** Mit dem Update, das eine neue Formatversion (z. B. pain.001.001.10) einführt, wird diese unter `Neueste Formate` bereitgestellt und alle Bankkonten werden gleichzeitig auf `Gängige Formate` gesetzt. Die Dateierstellung bleibt damit unverändert; die neue Version kann je Bankkonto gewählt werden, sobald die Bank sie unterstützt.
Weitere Informationen: [Version 5.2.0](https://wiki.konfipay.de/konfipay/version-5-2-0.md), [SEPA-Formate ab November 2026](https://wiki.konfipay.de/konfipay/sepa-formate-ab-november-2026-konfipay)
Falls Ihre Bank regelmäßig Zahlungen aufgrund von fehlerhaftem Format ablehnt, könnte unter Umständen eine Anpassung der Einstellung "Formatvorgabe für Dateierstellung" nötig sein.
Die Einstellung gilt je Bankkonto für alle Zahlungsarten. Welche Formatversion konkret erzeugt wird, hängt zusätzlich von der `Ländervorgabe für Dateierstellung` und von der Zahlungsart ab. Für einige Zahlungsarten ist jeweils nur ein Format zulässig - dort bleibt die Einstellung ohne Wirkung, ohne dass eine Meldung erscheint. Die folgenden Teilabschnitte stellen pro Land und Zahlungsart dar, welches Format bei welcher Einstellung erzeugt wird (Stand vor Version 5.2.0).
##### Deutschland (Ländervorgabe DE)
Die Ländervorgabe DE ist der Standard für alle Konten außer Österreich, Schweiz und Liechtenstein.
| Zahlungsart | Gängige Formate | Neueste Formate | Hinweis |
|--------------------------------------------------------|-----------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Überweisung (SEPA, inkl. Eil- und Echtzeitüberweisung) | pain.001.001.03 | pain.001.001.09 | |
| Lastschrift (CORE / B2B) | pain.008.001.02 | pain.008.001.08 | |
| Auslandszahlung (AZV) | pain.001.001.09 | pain.001.001.09 | **Keine Auswirkung** bei deutscher IBAN - pain.001.001.03 ist für den Auslandszahlungsverkehr nach dem DFÜ-Abkommen nicht zulässig. Nur bei nicht-deutscher IBAN wird mit `Gängige Formate` pain.001.001.03 erzeugt. |
##### Österreich (Ländervorgabe AT)
| Zahlungsart | Gängige Formate | Neueste Formate | Hinweis |
|------------------------------------------|-----------------|-----------------|------------------------------------------------------------------------------------------------------|
| Überweisung (SEPA, inkl. Eilüberweisung) | pain.001.001.03 | pain.001.001.09 | |
| Echtzeitüberweisung (Instant Payment) | pain.001.001.09 | pain.001.001.09 | **Keine Auswirkung** - Echtzeitüberweisungen werden in Österreich nur im neueren Format unterstützt. |
| Lastschrift (CORE / B2B) | pain.008.001.02 | pain.008.001.08 | |
| Auslandszahlung (AZV) | pain.001.001.03 | pain.001.001.09 | |
| Finanzamtszahlung | pain.001.001.03 | pain.001.001.03 | **Keine Auswirkung** - als Echtzeitüberweisung wird pain.001.001.09 erzeugt. |
##### Schweiz und Liechtenstein (Ländervorgabe CH)
| Zahlungsart | Gängige Formate | Neueste Formate | Hinweis |
|---------------------|-----------------|-----------------|----------------------|
| Überweisung | pain.001.001.03 | pain.001.001.09 | |
| Lastschrift (CH-DD) | pain.008.001.02 | pain.008.001.02 | **Keine Auswirkung** |
| Auslandszahlung | pain.001.001.09 | pain.001.001.09 | **Keine Auswirkung** |
#### Umsatzdateien erstellen - MT940 aus camt.053
Aktivieren Sie diese Einstellung, um automatisch MT940-Dateien auf Basis der vom Bankrechner bereitgestellten camt.053-Dateien zu erstellen. Die erstellten MT940-Dateien werden automatisch Ihrem Datenbestand zugeordnet und können als Umsatzdateien eingesehen, heruntergeladen oder über die API von konfipay abgerufen werden.
Die konvertierte MT940-Datei kommt nicht offiziell von Ihrer Bank. Wir generieren die Dateien auf Basis des MT940-Standards, aber übernehmen keine Gewährleistung für die vollständige Kompatibilität des Dateiformats mit Ihrer Systemlandschaft.
#### SRZ-Umsatzverarbeitung
Mit der Teilnahme am SRZ-Verfahren werden, je nach Vereinbarung, Kontoumsätze bereitgestellt. Sollte dies nicht länger gewünscht sein (z. B. weil die Kontoumsätze über einen anderen Zugang wie EBICS abgerufen werden) dann kann die Verarbeitung von Umsätzen, welche über SRZ bereitgestelt werden über diese Option deaktiviert werden. Diese Option greift unmittelbar nach dem Speichern, hat jedoch keine Auswirkungen auf bereits vorhandene Kontoumsätze - diese bleiben erhalten. Die Deaktivierung der Verarbeitung in konfipay ist damit in der Regel deutlich schneller und einfacher als der Widerruf der Bereitstellung beim Servicerechenzentrum. Es wird dennoch empfohlen, die Bereitstellung zu widerrufen, wenn dies nicht länger gewünscht ist. Sollte der widerruf nicht erfolgen, verarbeitet konfipay die Dateien zwar nicht mehr, aber sie werden dennoch vom Servicerechenzentrum bereitgestellt.
## Einstellungen zur Empfängerprüfung
Die Empfängerprüfung [(Verification of Payee, kurz VOP)](https://wiki.konfipay.de/konfipay/verification-of-payee-vop-konfipay) kann für jedes Bankkonto individuell gesteuert werden. Pro Konto kann VOP für Sammelzahlungen und Einzelzahlungen aktiviert bzw. deaktiviert werden. Standardmäßig gelten für jedes Bankkonto die unter [Einstellungen](https://wiki.konfipay.de/konfipay/api-einstellungen) gespeicherten Präferenzen zu VOP-Prüfungen.
Um die Einstellungen zur Empfängerprüfung für ein einzelnes Bankkonto (oder eine Gruppe von Bankkonten) zu ändern, wählen Sie die betreffenden Konten in der Liste aus. Klicken Sie dann oben in der Toolbar auf `Empfängerprüfung`.
Dann können Sie links die Empfängerprüfung (VOP) allgemein aktivieren bzw. deaktivieren. Rechts können Sie die die Empfängerprüfung (VOP) für Einzelzahlungen aktivieren bzw. deaktivieren. Wenn VOP allgemein, dann ist VOP bei Einzelzahlungen automatisch immer aktiviert.
In der Übersicht der Bankkonten können Sie für jedes Konto individuell einsehen, ob VOP allgemein und für Einzelzahlungen aktuell aktiv ist. Falls die Einstellung auf Kontenebene individuell getroffen wurde, ist dies hier mit dem Zahnrad-Symbol vermerkt.
Im [Aktivitätsprotokoll](https://wiki.konfipay.de/konfipay/aktivitatsprotokoll) finden Sie eine umfassende Dokumentation, welcher Benutzer diese Einstellung für welches Bankkonto wann und wie geändert hat.
## Bankkonto deaktivieren
Sie haben die Möglichkeit, Bankkonten für Ihren Mandanten komplett zu deaktivieren. Für deaktivierte Bankkonten werden dann keine Kontoumsätze mehr verarbeitet und es können keine Zahlungsdateien eingereicht werden. Deaktivierte Bankkonten werden in allen Ansichten ausgeblendet - bereits bestehende Daten, die mit deaktivierten Konten verknüpft sind (also Kontoumsätze oder Zahlungsaufträge), bleiben aber vollständig erhalten.
Die Deaktivierung von Bankkonten kann sinnvoll sein, wenn Sie bei einer Bank mehrere Konten führen, in konfipay aber nur eines dieser Konten nutzen möchten. Über den automatisierten Abruf der Kontenliste würden diese Konten immer wieder als Bankkonten Ihres Mandanten angelegt werden - durch die Deaktivierung können Sie das unterbinden und in konfipay ausschließlich mit den Konten arbeiten, mit denen Sie arbeiten möchten.
Um ein Bankkonto zu deaktivieren, wählen Sie das Konto einfach in der Liste aus und klicken Sie oben in der Toolbar auf `Deaktivieren`. Deaktivierte Konten finden Sie dann unter dem Punkt `Deaktivierte Konten` in der Toolbar - dort können Sie die Konten bei Bedarf auch wieder reaktivieren.
## Bankzugänge steuern
Nach Anlage eines Kontos ermittelt konfipay selbstständig, über welchen Weg und ggf. welchen EBICS-Kontakt das Konto für die automatische Zahlungsübertragung (bei Nutzung der [Automatisierung](https://wiki.konfipay.de/konfipay/automatisierung) und über die API) mit der Bank verbunden wird. Sie können bei Bedarf händisch einstellen, über welchen Bankzugang das Bankkonto bei der automatischen Zahlungsübertragung bzw. Zahlungsübertragung über die API angesteuert werden soll. Klicken Sie dafür oben in der Toolbar auf `Bankzugänge`.
Hier sehen Sie eine Liste aller Bankkonten, die in Ihrem Mandanten angelegt sind. Für jedes Konto können Sie hier den Upload-Kanal und den Download-Kanal definieren. Bei der Kanalauswahl legen Sie zunächst über das Dropdown-Menü fest, ob die Übertragung bzw. der Abruf über EBICS oder SRZ stattfinden soll. Eine genaue Erklärung der Unterschiede zwischen SRZ und EBICS finden Sie in [diesem Artikel](https://wiki.konfipay.de/konfipay/ebics-oder-srz). Eine Anleitung, wie Sie ein Bankkonto mit Bankzugang über SRZ einrichten, finden Sie [hier](https://wiki.konfipay.de/konfipay/bankkonto-uber-srz-einrichten).
Wenn Sie sich für EBICS entscheiden, wählen Sie im nächsten Schritt über das Dropdown-Menü noch den gewünschten EBICS-Kontakt aus. Wenn Sie sich für SRZ entscheiden, können Sie den SRZ-Kanal manuell ändern, indem Sie auf das Stift-Symbol neben dem Namen des SRZ-Kanals klicken. Dann können Sie einen anderen SRZ-Kanal aus allen verfügbaren wählen (durch einen Klick auf das Symbol mit dem runden Pfeil können Sie den SRZ-Kanal wieder auf den Standard zurücksetzen).
Bei Nutzung von SRZ zur Dateiübertragung können Sie außerdem für die Dateiübertragung zusätzlich einen EBICS-Kontakt festlegen. Dies hat den Hintergrund, dass bestimmte Zahlungsarten (wie SEPA Instant Payments oder Auslandszahlungsverkehr) nicht über SRZ übertragen werden kann. Diese Zahlungsarten werden dann über den festgelegten EBICS-Kontakt übertragen.
Falls Sie für ein Konto bei der Übertragung einen EBICS-Kontakt konfiguriert haben, können Sie auch festlegen, über welchen Weg (EBICS oder SRZ) der Dateiabruf erfolgen soll. Wenn Sie hier EBICS auswählen, wird derselbe Kontakt verwendet, der auch für die Übertragung konfiguriert ist.
Sie können die angezeigten Konten filtern, indem Sie links oben auswählen, für welchen EBICS-Kontakt die zugehörigen Bankkonten angezeigt werden sollen. Zusätzlich können Sie links oben über die entsprechenden Checkboxen auswählen, dass nur Bankkonten mit fehlerhafter oder unvollständiger Konfiguration angezeigt werden sollen.
Bitte beachten Sie, dass diese Einstellungen nur die automatische Zahlungsübertragung und die Zahlungsübertragung über die API betreffen. Bei manuellen Aktionen können Sie den Übertragungskanal individuell wählen. Um die zur Verfügung stehenden EBICS-Kontakte für die manuelle Zahlungsübertragung zu verändern, nutzen Sie die Funktion [Bankkonten](https://wiki.konfipay.de/konfipay/ebics#EBICS-Bankkonten) in der Verwaltung der betreffenden EBICS-Kontakte.
## FinTS/XS2A als Bankzugang
Neben EBICS und SRZ steht seit Version 5.0.0 auch FinTS/XS2A als Upload- und Download-Kanal zur Verfügung. Wählen Sie bei der Kanalauswahl FinTS/XS2A aus, erscheint anstelle eines EBICS-Kontakts ein Auswahlfeld `Bankverbindung`, über das Sie die gewünschte [FinTS/XS2A-Bankverbindung](https://wiki.konfipay.de/konfipay/fints-xs2a.md) festlegen.
Welche Bankschnittstelle für den Upload (Überweisungen bzw. Lastschriften) und welche für den Download verwendet wird, legen Sie je Bankverbindung unter `Geschäftsvorfälle` fest.
## Konten-Identifikatoren
Um Kontoumsätze automatisch einem Konto zuzuordnen, nutzt konfipay generell die IBAN in den Umatzdateien. Ist diese in den Umsätzen aber nicht angegeben oder unvollständig, greift konfipay auf die hier festgelegten Identifikatoren zurück.
Identifikatoren bestehen z.B. aus einer Kombination von Kontonummer, Bankleitzahl, BIC und Währung des Kontos. Wenn ein solcher Identifikator dann in einer Umsatzdatei gefunden wird, kann die Datei dem richtigen Konto zugeordnet werden.
Für manche Konten werden beim Abruf der Kontenlisten über EBICS automatisch Identifikatoren generiert.
Beispiele für Identifikatoren für ein fiktives Konto
## Kennungen
Mithilfe von [Kennungen](http://wiki.konfipay.de/konfipay/kennungen) können Sie Daten in konfipay (z.B. Bankkonten) markieren. Das kann z.B. für die Umsetzung von effizienten [Inhaltsbeschränkungen](https://wiki.konfipay.de/konfipay/berechtigungen#Berechtigungen-Berechtigungenf%C3%BCrInhalte(Inhaltsbeschr%C3%A4nkungen)) hilfreich sein. Wählen Sie dazu das Bankkonto in der Liste aus, für das Sie die Kennungen verwalten möchten, und klicken Sie oben in der Toolbar auf `Kennungen`. Dann sehen Sie die bereits zugewiesenen Kennungen für dieses Konto.
Klicken Sie in das Feld `Kennungen`, um alle verfügbaren Kennungen zu sehen. Indem Sie die infrage kommenden Kennungen anklicken, wählen Sie aus, welche Kennungen Sie dem Konto zuweisen möchten. Ebenso können Sie eine Kennung von einem Konto entfernen, indem Sie neben der Kennung auf das x Symbol klicken.
Sie können auch eine neue Kennung erstellen, indem Sie auf das + Symbol klicken. Dann öffnet sich der Dialog zur Erstellung und Sie können die neu erstellte Kennung direkt dem Konto zuweisen.
## konfipay-Testkonten verwalten
In konfipay werden zu Testzwecken einige Testkonten bereitgestellt. Diese Konten generieren täglich Test-Umsätze und können auch zum Testen der Zahlungseinreichung genutzt werden. Die eingereichten Zahlungen werden nicht ausgeführt.
Sie können diese Konten aktivieren oder deaktivieren, indem Sie oben in der Toolbar auf `Testkonten` klicken, dann das gewünschte Konto markieren und wiederum in der oberen Leiste auf `Aktivieren` bzw. `Deaktivieren` klicken.
Für aktivierte Testkonten werden dann z.B. Kontoumsätze angezeigt und die aktivierten Konten können testweise zur Zahlungsübertragung ausgewählt werden.
## Kontenzusammenführung
Wenn Ihre Bank mit einer anderen Bank fusioniert, besteht Ihr Bankkonto ggf. mit einer neuen IBAN oder BIC fort. Durch den automatisierten Abruf der Kontenliste erstellt konfipay das neue Konto automatisch mit den neuen Verbindungsinformationen (neue IBAN/BIC). In diesem Fall wird das Konto in konfipay dann doppelt geführt - einmal mit den alten Informationen von vor der Fusion, und einmal mit den neuen Informationen nach der Fusion. Auch beim manuellen Import von Kontoumsätzen kann es sein, dass konfipay für die Umsätze ein neues Bankkonto anlegt, anstatt sie in den Datenbestand des bestehenden Kontos einzupflegen.
Sie können die beiden Konten zusammenführen, um einen Fortbestand der Daten wie z.B. Kontoumsätze ohne zeitlichen Bruch sicherzustellen. Dabei wird der Datenbestand (Zahlungshistorie, Umsätze, Salden...) des alten Kontos zum neuen Konto transferiert.
Klicken Sie dafür oben in der Toolbar auf `Kontenzusammenführung`. Wählen Sie auf der linken Seite das `Quellkonto` aus - also das alte Konto, dessen Datenbestand auf das neue Konto übertragen werden soll. Rechts wählen Sie unter `Zielkonto` das neue Konto aus, zu dem der Datenbestand übertragen werden soll. In der nächsten Zeile legen Sie fest, was mit dem alten Konto (Quellkonto) nach der Zusammenführung passieren soll - das Quellkonto kann [deaktiviert](https://wiki.konfipay.de/konfipay/bankkonten#Bankkonten-Bankkontodeaktivieren) oder komplett gelöscht werden.
Eine Kontozusammenführung kann nicht rückgängig gemacht werden. Bitte überprüfen Sie ihre Angaben sorgfältig, bevor Sie die Zusammenführung starten.
---
language: "de"
---
# Bankkonto über SRZ einrichten
Um ein [Bankkonto](https://wiki.konfipay.de/konfipay/bankkonten) in konfipay über SRZ mit der Bank zu verbinden, legen Sie das Bankkonto zunächst an. Klicken Sie links in der Navigationsleiste auf `Stammdaten` und dann `Bankkonten`. Dann klicken Sie oben in der Toolbar auf `Hinzufügen` und geben die entsprechenden Daten des Bankkontos ein.
## Automatische Steuerung des Bankzugangs
In der Regel erkennt konfipay automatisch, ob das neu angelegte Konto über einen eigenen [EBICS-Kontakt](https://wiki.konfipay.de/konfipay/ebics) Ihres Mandanten angesteuert werden kann. Wenn das nicht der Fall ist, wählt konfipay automatisch SRZ als Bankzugang aus. (Zur Funktionsweise der Bankkommunikation über SRZ können Sie [hier](https://wiki.konfipay.de/konfipay/ebics-oder-srz) mehr Informationen finden.)
Wenn konfipay für das Bankkonto automatisch SRZ als Bankzugang festgelegt hat, können Sie den nächsten Schritt überspringen und bei der [SRZ-Teilnahmevereinbarung](https://wiki.konfipay.de/konfipay/bankkonto-uber-srz-einrichten#Bankkonto%C3%BCberSRZeinrichten-SRZ-Teilnahmevereinbarung) weitermachen.
## Bankzugang über SRZ manuell konfigurieren
Falls konfipay das angelegte Bankkonto einem EBICS-Kontakt zugeordnet hat, Sie das Konto aber explizit über SRZ ansteuern möchten, können Sie den Bankzugang manuell festlegen. Markieren Sie dazu das Konto in der Liste der Bankkonten und klicken Sie oben in der Toolbar auf `Bankzugänge`.
Legen Sie die Steuerung als `Manuell` fest und wählen Sie beim SRZ-Kontakt die entsprechende Bank aus der Dropdown-Liste aus. Setzen Sie den SRZ-Kontakt außerdem als `Bevorzugt` fest. Dann wird die Bankenkommunikation für das Konto bevorzugt über den entsprechenden SRZ-Kontakt abgewickelt.
## SRZ-Teilnahmevereinbarung
Damit konfipay die hauseigene SRZ-Verbindung zur Bank für dieses Konto nutzen darf, bedarf es einer ausdrücklichen Freigabe durch den Kontoinhaber, also durch Sie bzw. Ihre Firma.
Für diese Freigabe gibt es ein Formular, die sog. SRZ-Teilnahmevereinbarung. Dieses Formular können Sie unkompliziert in konfipay herunterladen, indem Sie das Bankkonto in der Liste auswählen, für das Sie die Freigabe erteilen möchten, und oben in der Toolbar auf `Teilnahmevereinbarung` klicken. Dann öffnet sich die Teilnahmevereinbarung als PDF.
Laden Sie das Formular herunter und füllen es entsprechend aus. Schicken Sie das Formular dann unterschrieben an Ihre Bank (nicht an konfipay!), damit Ihre Bank den SRZ-Zugang für konfipay freischalten kann. Bitte beachten Sie: Erst, wenn Ihre Bank das Dokument erhalten hat und die Freigabe bearbeitet hat, kann das Bankkonto in konfipay über SRZ genutzt werden.
Über die Bearbeitungsdauer der SRZ-Teilnahmevereinbarung kann konfipay keine Aussagen treffen, da dies von Bank zu Bank unterschiedlich ist. Bei Anfragen ist das Kreditinstitut direkt zu kontaktieren.
---
language: "de"
---
# Beauftragung zur Datenänderung
Im konfipay-Portal verwalten Sie Ihren unternehmensinternen Zahlungsverkehr und administrieren alle dazu berechtigten Benutzer. Begleitende Unterstützung erhalten Sie über die [integrierte Online-Hilfe](https://wiki.konfipay.de/konfipay) oder unseren konfipay-Kundenservice kostenlos.
Möchten Sie mehr als eine begleitende Unterstützung, können Sie uns für folgende Vorgänge direkt beauftragen:
* Übertragen von Administrator-Berechtigungen zwischen Benutzern
* Anlegen oder Löschen von Benutzern
* Hinzufügen von Benutzern zu Benutzergruppen
* Einrichten eines EBICS-Bankzugangs
Zu Ihrer und unserer Sicherheit kann eine Beauftragung nur mit dem [Dokument "Beauftragung zur Datenänderung"](https://download.windata.de/konfipay/Beauftragung_zur_Datenaenderung.pdf) erfolgen. Senden Sie uns dieses bitte vollständig ausgefüllt per E-Mail an support@konfipay.de. Unser konfipay-Kundenservice bestätigt den Erhalt und die erfolgreiche Ausführung Ihres Auftrags.
Für die Bearbeitung erheben wir pro Auftrag eine einmalige Gebühr in Höhe von 119,00€ zzgl. MwSt.
Aufträge, die von den oben genannten Tätigkeiten abweichen, können wir entweder nach Rücksprache oder entsprechender Aufwandsschätzung bearbeiten. Hierzu nutzen Sie im Dokument die Kategorie „Anderer Auftrag" und warten auf die Bestätigung durch den konfipay-Kundenservice.
---
language: "de"
---
# Benutzer
Hier haben Sie die Möglichkeit, Benutzer zu verwalten, die in Ihrem Mandanten registriert sind. Sie können neue Benutzer hinzufügen oder bereits angelegte Benutzer ändern, indem Sie den gewünschten Benutzer in der Liste auswählen und dann die entsprechende Option oben in der Toolbar wählen.
Über der Liste fassen drei Kennzahlen den Mandanten zusammen: Benutzer gesamt, Administratoren und offene Einladungen, jeweils mit dem Anteil der Gastbenutzer. Ein Filter in der Toolbar grenzt die Liste nach Rolle, Einladung, Authentifizierung und Status ein.
## Benutzer hinzufügen
[Hier](https://wiki.konfipay.de/konfipay/neuen-benutzer-anlegen) finden Sie eine separate Anleitung zur Anlage eines neuen Benutzers in Ihrem Mandanten.
## Benutzer bearbeiten
Um einen bereits existierenden Benutzer zu bearbeiten, wählen Sie diesen in der Liste aus und klicken dann oben in der Toolbar auf `Benutzer` \> `Bearbeiten`. Dann öffnet sich ein Fenster mit denselben Einstellungsmöglichkeiten wie unter [Mein Konto](https://wiki.konfipay.de/konfipay/mein-konto). Sie können dort dieselben Änderungen vornehmen (mit Ausnahme von E-Mail- oder Passwort-Änderungen - das kann nur der betroffene Benutzer selbst ändern).
## Benutzer löschen
Um einen existierenden Benutzer zu löschen, wählen Sie den Benutzer in der Liste aus und klicken Sie dann oben in der Toolbar auf `Benutzer` \> `Löschen`.
Ein Administrator kann gelöscht werden, solange mindestens ein weiterer Administrator im Mandanten verbleibt. Näheres dazu finden Sie im Abschnitt [Administrator-Rolle](https://wiki.konfipay.de/konfipay/benutzer#Administrator-Rolle).
## Benutzergruppen eines Benutzers verwalten
Um die Benutzergruppen eines Benutzers zu verwalten, wählen Sie den entsprechenden Benutzer in der Liste aus und klicken Sie in der Toolbar auf `Berechtigungen` \> `Benutzergruppen`. Dann sehen Sie direkt, welchen Benutzergruppen der Benutzer aktuell angehört.
Wählen Sie eine Benutzergruppe in der Liste aus und klicken Sie in der Toolbar auf `Hinzufügen`, um den Benutzer zu der Gruppe hinzuzufügen. Mit `Entfernen` können Sie den Benutzer aus der Gruppe entfernen, und mit `Berechtigungen anzeigen` können Sie das [Berechtigungsschema](https://wiki.konfipay.de/konfipay/berechtigungen) der ausgewählten Benutzergruppe einsehen.
Mit dem Knopf `Alle entfernen` können Sie einem Benutzer alle Benutzergruppen entziehen und mit `Zurücksetzen` können Sie alle ungespeicherten Änderungen an den Benutzergruppen zurücksetzen.
## Berechtigungen eines Benutzers anzeigen
Um die Berechtigungen eines Benutzers anzuzeigen, wählen Sie den Benutzer in der Liste aus und klicken Sie dann oben in der Toolbar auf `Berechtigungen` \> `Berechtigungen anzeigen`. Dann sehen Sie links, zu welchen Benutzergruppen dieser Benutzer gehört und rechts, welche Berechtigungen er dadurch erhält. Sie können sich neben der Berechtigungsmatrix der Funktionsbeschränkungen unter dem Reiter `Inhalte` auch die Inhaltsbeschränkungen des Nutzers anzeigen lassen.
Wie das Berechtigungssystem in konfipay funktioniert und wie Sie die Berechtigungen optimal für Ihre Zwecke nutzen können, lesen Sie [hier](https://wiki.konfipay.de/konfipay/benutzergruppen).
## Protokolle zu Benutzeraktivität
Unter `Protokolle` in der Toolbar können Sie zwei verschiedene Protokolle zur Aktivität der Benutzer im Mandanten einsehen. Unter `Protokolle` \> `Aktivitätsprotokoll` finden Sie das Aktivitätsprotokoll, welches [hier](https://wiki.konfipay.de/konfipay/aktivitatsprotokoll) genauer beschrieben wird.
Unter `Protokolle` \> `Benutzeranmeldungen` finden Sie eine detaillierte Auflistung aller Anmeldeaktivitäten im Mandanten, d.h. alle erfolgreichen und fehlgeschlagenen Anmeldeaktivitäten der Benutzer mit IP-Adresse.
## Benutzer deaktivieren und aktivieren
Ein Administrator eines Mandanten hat die Möglichkeit, Benutzer zu deaktivieren. Dafür wählt der Administrator den entsprechenden Benutzer aus der Liste aus und klickt oben in der Toolbar auf `Benutzer` \>`Deaktivieren`. Ein deaktivierter Benutzer kann sich nicht mehr in konfipay anmelden und damit nicht mehr auf die Daten und Funktionalitäten eines Mandanten zugreifen, jedoch gehen seine Benutzerdaten nicht verloren und der Benutzer kann zu einem späteren Zeitpunkt wieder aktiviert werden.
Um einen Benutzer wieder zu aktivieren, klickt der Administrator oben in der Toolbar auf `Inaktive Benutzer`, wählt den zu reaktivierenden Benutzer in der Liste aus und klickt auf `Reaktivieren`.
## Administrator-Rolle
Administratoren nehmen eine besondere Rolle innerhalb der Benutzer ein. Sie gehören keiner Benutzergruppe an und können somit in ihren Berechtigungen nicht eingeschränkt werden. Zudem besitzen Administratoren Zugriff auf Funktionen, die für keinen anderen Benutzer zur Verfügung stehen. Hierzu zählen:
* Verwaltung von Hardware-Token
* Deaktivieren/Reaktivieren von Benutzern
* Festlegung eines individuellen Designs (Logo und Farben) für den Mandanten
Ein Mandant kann mehrere Administratoren haben, sodass die Administration nicht an einer einzelnen Person hängt. Administratoren stehen als reguläre Zeilen in der Benutzerliste und sind dort als `Admin` gekennzeichnet.
### Administrationsrecht vergeben
Wählen Sie den gewünschten Benutzer in der Liste aus und klicken Sie in der Toolbar auf `Berechtigungen` \> `Als Administrator hinzufügen`. Der Benutzer muss die Einladung in den Mandanten zuvor angenommen haben.
Der Dialog weist vorab auf die Auswirkungen hin: Der Benutzer wird aus allen Benutzergruppen entfernt, seine Berechtigungen können anschließend nicht mehr eingeschränkt werden, und er kann erst wieder gelöscht werden, wenn ihm das Administrationsrecht zuvor entzogen wurde.
### Administrationsrecht entziehen
Wählen Sie den betreffenden Administrator in der Liste aus und klicken Sie in der Toolbar auf `Berechtigungen` \> `Administratorrechte entziehen`. Der Benutzer bleibt erhalten und kann anschließend wie jeder andere Benutzer über [Benutzergruppen](https://wiki.konfipay.de/konfipay/benutzergruppen) berechtigt werden.
### Schutz des letzten Administrators
Der jeweils letzte verbleibende Administrator ist geschützt: Ihm kann das Administrationsrecht nicht entzogen werden, und er kann weder deaktiviert noch gelöscht werden. So kann ein Mandant nicht versehentlich ohne Administrator zurückbleiben. Ebenso kann sich ein Administrator das eigene Recht nicht selbst entziehen. Solange mindestens ein weiterer Administrator vorhanden ist, lassen sich Administratoren wie andere Benutzer deaktivieren oder löschen.
Jede Vergabe und jeder Entzug des Administrationsrechts wird im [Aktivitätsprotokoll](https://wiki.konfipay.de/konfipay/aktivitatsprotokoll) dokumentiert; die betroffenen Benutzer werden per E-Mail informiert.
Ist kein Administrator des Mandanten mehr erreichbar (z. B. weil die Person die Organisation bereits verlassen hat), ist die Beauftragung einer Änderung durch den konfipay-Kundenservice möglich. Nutzen Sie hierzu bitte die [Beauftragung zur Datenänderung](https://wiki.konfipay.de/konfipay/beauftragung-zur-datenanderung).
---
language: "de"
---
# Benutzerspezifische Einstellungen
* [Mein Konto](https://wiki.konfipay.de/konfipay/mein-konto.md)
* [Persönliche Einstellungen](https://wiki.konfipay.de/konfipay/personliche-einstellungen.md)
[Next Page](https://wiki.konfipay.de/llms-full.txt/1)