Bank integration

Omoplata integrates directly with your bank through the FinTS protocol, which is supported by most German banks. This lets you fetch bank transactions, match incoming payments to open invoices automatically, and reconcile your books -- all without leaving the application.

What is FinTS

FinTS is a secure banking standard used primarily by German banks. It allows Omoplata to communicate with your bank to fetch account statements, view balances, and match payments. Most major German banks support FinTS.

Your bank credentials are stored securely in Omoplata, encrypted with a PIN that you choose during setup.

Connecting your bank account

To set up the bank connection, go to your FinTS settings and follow these steps:

Step 1: Enter credentials

Fill in the following fields:

• Bank URL -- the FinTS endpoint URL for your bank (your bank provides this).
• Bank code -- your bank's routing number (Bankleitzahl).
• Username -- your online banking username.
• Password -- your online banking password.

Click Save. A modal will prompt you to create a PIN. This PIN encrypts your credentials and will be required each time you perform a bank operation.

After saving, Omoplata connects to your bank and fetches the available TAN modes and bank accounts. If the connection fails, no data is stored and you will see an error notification.

Step 2: Configure TAN and account

Once the connection is established, a second form appears where you can select:

• TAN mode -- the authentication method your bank uses (for example, pushTAN, chipTAN, or SMS-TAN).
• TAN medium -- the specific device or phone number used for TAN delivery.
• Default account -- which bank account to use for transactions.

These options can be saved and changed independently of the credentials.

Importing bank transactions

Once connected, you can fetch bank transactions directly from the FinTS page. The import process works as follows:

1. Navigate to Finance > Bank integration (the FinTS page).
2. Enter your PIN to decrypt the stored credentials.
3. Trigger a bank statement fetch. If TAN authentication is required, follow the prompts.
4. Omoplata downloads your recent bank transactions and stores them locally.

Statement format

Omoplata supports two bank statement formats:

• CAMT (default) -- the modern format supported by most banks. Provides richer data including payment references and detailed party information.
• MT940 (legacy) -- an older format. Available as a fallback if your bank does not support CAMT.

The default is CAMT. You can change the format in the FinTS settings if your bank requires it.

Automatic transaction matching

After bank transactions are imported, Omoplata automatically tries to match incoming payments (credits) with open invoices. The system uses a pipeline of matchers, each with a different strategy and confidence level.

How matching works

Matching runs automatically after each import. Omoplata processes incoming payments and compares them against open invoices (pending, pending retry, sent to bank, overdue, or on hold).

Matching strategies

Omoplata uses three matching strategies, applied in order of reliability:

1. End-to-end ID matching (highest confidence)

When a SEPA payment is made with an end-to-end ID that references an invoice (for example, INV-1000042), this matcher finds the exact invoice. Confidence: 90-100%.

2. IBAN matching (high confidence)

Compares the sender's IBAN against the bank details stored in your members' payment methods. If the IBAN matches and the amount is correct, the invoice is identified. Confidence: 85-95%.

3. Name and amount matching (fallback)

For payments without a recognizable IBAN or end-to-end ID, the system looks for invoices with a matching amount and then scores name similarity between the sender and your members. This supports variations like "LastName FirstName" ordering, which is common in German bank transfers. Confidence: 50-80%.

Confidence thresholds

The confidence score determines what happens with each match:

Manual matching and reconciliation

For matches that are not auto-confirmed, or for transactions that the system could not match at all, you can reconcile manually.

Reviewing pending matches

The bank transactions page shows imported transactions alongside their match status. For each pending match, you can:

• Confirm -- accept the match. The invoice is marked as paid and any other pending matches for the same transaction are rejected.
• Reject -- dismiss the match. The transaction remains unmatched and can be paired with a different invoice.

Match statuses

Bank transaction statistics

The bank transactions page shows summary statistics to help you understand the state of your reconciliation:

• How many transactions have been imported in the current fetch.
• How many have been matched (automatically or manually).
• How many are still pending review.

FinTS authentication flow

FinTS operations authenticate in stages. Here is what happens when you trigger any bank action:

1. A modal prompts for the PIN you created during setup. This decrypts the stored bank credentials.
2. The action runs using the decrypted credentials.
3. If the bank requires two-factor authentication (TAN), the system pauses the operation and stores the pending action.
4. Depending on your TAN mode:
   • Decoupled TAN (pushTAN): a modal asks you to confirm in your banking app. Omoplata can poll the bank automatically or wait for you to click a check button.
   • Classic TAN (chipTAN, SMS-TAN): a challenge image or code is displayed and you enter the TAN manually.
5. After TAN verification, the stored action resumes and completes.
6. The result is returned and the interface updates accordingly.