Description
n8n-nodes-fints
This is an n8n community node that integrates with the Financial Transaction Services (FinTS) interface used by German banks, allowing you to retrieve real-time account balances within your n8n workflows.
n8n is a fair-code licensed workflow automation platform.
Installation
Follow the installation guide in the n8n community nodes documentation, or install directly via npm:
npm install n8n-nodes-fints
Operations
- Get Account Balance: Retrieves the current balance and currency information for a specified bank account.
- User ID / Login: Your customer identification number.
- PIN: Your Personal Identification Number.
- Tested with n8n versions >= 0.150.0.
- Compatible with FinTS versions 1.1, 2.2, and 3.0.
- Supports optional FinTS 4.1 mode (experimental) and automatic protocol Auto-Detect via
fints-lib.
Credentials
To authenticate with your bank’s FinTS server, you need:
The Bank Code (BLZ) and FinTS server URL are set via the node parameters or by choosing your bank during credential setup.
The available banks are defined in nodes/FintsNode/banks.json. To support additional institutions, add an entry with value, displayName, blz, and fintsUrl to this file and rebuild the project.
Once you have these details, create new credentials in n8n under Settings → API Credentials, select FinTS, and enter the above information.
FinTS Product Registration ID
Some banks require an official FinTS Product Registration ID, also called productId, to access their FinTS interface.
This project does not provide a shared Product ID by default.
If your bank requires one, you are responsible for obtaining and using your own valid ID.
Using a shared or public ID may fail depending on the bank and can lead to rate limiting or blocking.
You can request an official Product ID via the FinTS registration form:
In this node, the Product ID can be provided through the FinTS Registration Number parameter, which maps to the fintsProductId field.
If you are unsure whether your bank requires it, try the node with an empty value first.
If the request fails with an error such as 9050, configure your registered Product ID and try again.
Compatibility
Usage
1. Add the FinTS node to your workflow.
2. Select the FinTS credentials you created.
3. Choose the operation: Get Account Balance.
4. Select the FinTS Protocol:
– FinTS 3.0 (Stable) for the established MT940-based flow (default, recommended).
– FinTS 4.1 (Experimental) to use the newer XML-based flow.
– Auto-Detect (Prefers 4.1, Falls Back to 3.0) — the node probes whether your bank supports FinTS 4.1 and automatically uses it if available, otherwise falls back to FinTS 3.0. If your PIN is incorrect the node reports it immediately without attempting the 3.0 fallback.
5. Configure the remaining parameters. The node automatically retrieves all accounts linked to your login.
6. Optionally, set Start Date and End Date to limit the booking range. If left empty, the node fetches statements from the last 14 days up to today.
7. Optionally, enable Include Firefly III Fields to add a nested firefly object with fields compatible with Firefly III personal finance software.
8. Optionally, use Exclude IBANs/Account Numbers to filter out specific accounts from the results by providing a comma-separated list of IBANs or account numbers to exclude.
9. Execute the workflow to receive a response object containing balance,currency, bank, account, and an array of transactions.
[
{
"account": "DEXXXXXXXXXX",
"bank": "23445561",
"balance": 10001,
"currency": "EUR",
"transactions": [
{
"amount": 20,
"text": "Some payment",
"valueDate": "2025-06-03",
"currency": "EUR",
"reference": "XYZ",
"isCredit": true,
"isExpense": false
}
]
}
]
Firefly III Integration
When you enable the Include Firefly III Fields option, each transaction will include an additional nested firefly object with fields specifically mapped for Firefly III compatibility:
{
"amount": 20,
"text": "Some payment",
"valueDate": "2025-06-03",
"currency": "EUR",
"reference": "XYZ",
"isCredit": true,
"isExpense": false,
"firefly": {
"transactionId": "20250603-001",
"transactionType": "deposit",
"description": "Some payment",
"date": "2025-06-03",
"sendingAccount": "DE98370400440532013000",
"targetAccount": "DEXXXXXXXXXX",
"notes": "Customer Ref: ABC123",
"endToEndRef": "NOTPROVIDED"
}
}
Firefly III Field Descriptions:
deposit for incoming payments, withdrawal for outgoing paymentssepactid in Firefly IIIFiltering Accounts
The Exclude IBANs/Account Numbers parameter allows you to filter out specific accounts from the results. This is useful when you have multiple accounts linked to your FinTS login but only want to process a subset of them.
How to use:
DE89370400440532013000) and account numbers (e.g., 12345678) are supportedExample:
DE89370400440532013000, 87654321
This will exclude the account with IBAN DE89370400440532013000 and the account with account number 87654321 from the results.
Resources
Automated releases
Publishing from CI requires an npm automation token stored as the NPM_TOKEN repository secret. Generate the token in the npm account settings, ensure it has automation scope, and add it under Settings → Secrets and variables → Actions before pushing release commits or tags. The GitHub Actions workflow validates that the secret is present and aborts with a descriptive error if it is missing.
Version history
Auto-Detect option via a single fintsProtocol parameter (3.0 / 4.1 / auto); auto-detect probes 4.1 first and falls back to 3.0, with immediate PIN error propagation (no silent fallback on wrong PIN); add distinct PinError/AuthenticationError handling in the catch block for clearer user-facing error messages; bump fints-lib to 0.11.0; add tests for protocol options and auth error types.Exclude IBANs/Account Numbers filter to exclude specific accounts from results; add optional Firefly III field mapping nested under a firefly object; introduce debug mode with server-side logging and improved error handling; update tests and documentation; bump dependencies and fix CI/build issues.
