{"id":35165985,"url":"https://github.com/robocode13/lib-fints","last_synced_at":"2026-01-12T14:35:46.161Z","repository":{"id":246039870,"uuid":"819934681","full_name":"robocode13/lib-fints","owner":"robocode13","description":"A Typescript/Javascript client library for Online-Banking via the FinTS 3.0 protocol with PIN/TAN.","archived":false,"fork":false,"pushed_at":"2026-01-10T11:01:46.000Z","size":18964,"stargazers_count":12,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-11T03:30:22.967Z","etag":null,"topics":["banking","fints","hbci","homebanking","onlinebanking","pin-tan"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/lib-fints","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robocode13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-06-25T13:20:18.000Z","updated_at":"2026-01-10T11:01:50.000Z","dependencies_parsed_at":"2025-04-24T08:24:29.000Z","dependency_job_id":"297efccf-8cc8-4bf5-ba55-484b50adbe6a","html_url":"https://github.com/robocode13/lib-fints","commit_stats":null,"previous_names":["robocode13/lib-fints"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/robocode13/lib-fints","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocode13%2Flib-fints","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocode13%2Flib-fints/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocode13%2Flib-fints/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocode13%2Flib-fints/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robocode13","download_url":"https://codeload.github.com/robocode13/lib-fints/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocode13%2Flib-fints/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28340402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["banking","fints","hbci","homebanking","onlinebanking","pin-tan"],"created_at":"2025-12-28T19:32:45.935Z","updated_at":"2026-01-12T14:35:46.149Z","avatar_url":"https://github.com/robocode13.png","language":"TypeScript","readme":"[![Node.js CI with pnpm](https://github.com/robocode13/lib-fints/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/robocode13/lib-fints/actions/workflows/ci.yml)\n\n# Lib-FinTS\n\nA Typescript/Javascript client library for Online-Banking via the FinTS 3.0 protocol with PIN/TAN, supporting PSD2 and decoupled TAN methods. The library has no dependencies on other libraries\n\n## Getting Started\n\nThese instructions will show you how to install the library on your local machine and give a quick sample of how to use the library\n\n### Prerequisites\n\n#### Product Registration\n\nIn order to communicate with banks via the FinTS protocol you have to register a product ID with the german banking industry (Deutsche Kreditwirtschaft) which you need to pass as part of the configuration to the client:\n\n\u003e In order to fulfill the PSD2 requirements regarding transparency about the software used by customers, the German Banking Industry has established a process for registering FinTS products in order to be able to provide customers with information regarding FinTS usage.\n\u003e FinTS product registration is currently offered free of charge by the German Banking Industry.\n\n[ZKA Registration Website](https://www.fints.org/de/hersteller/produktregistrierung)\n\n### Runtime Environment\n\nThe library is written in Typescript and compiled to the ES2022 Javascript language standard which means a minimum Node version of 18 is required.\n\n**A note about Browsers:**\nIn theory the library is compatible with a browser environment, but communicating directly from the front-end with a bank server will, apart from security considerations, most likely fail because of the imposed CORS restrictions from web browsers and the lack of corresponding CORS headers in bank server responses.\n\n### Installing\n\nInstallation is straight forward by simply adding the npm package.\n\n```\nnpm i lib-fints\n```\n\n**Dependencies**: The library includes the `fast-xml-parser` package for robust CAMT statement parsing but has no other runtime dependencies.\n\n### Sample Usage\n\nThe main public API of this library is the `FinTSClient` class and `FinTSConfig` class. In order to instantiate the client you need to provide a configuration instance. There are basically two ways to initialize a configuration object, one is when you communicate with a bank for the first time and the other when you already have banking information from a prevous session available (more on that later).\n\nIf you don't have any previous banking information available you can use the static `forFirstTimeUse()` factory method like this:\n\n```typescript\nconst config = FinTSConfig.forFirstTimeUse(productId, productVersion, bankUrl, bankId, userId, pin);\n\nconst client = new FinTSClient(config);\n```\n\nThen you should first make a synchronization call to get banking and account information:\n\n```typescript\nlet syncResponse = await client.synchronize();\n```\n\nyou should always check the `success` and `requiresTan` properties of any response object because other data might only be available when `success=true` and `requiresTan=false`.\nin any case you can also check the `bankAnswers` array for return messages from the bank which may contain the reasons for a failed request.\n\nIf the call is successfull the response will contain a `bankingInformation` object filled with all the relevant information provided by the bank from synchronization:\n\n```typescript\nexport type BankingInformation = {\n  systemId: string;\n  bpd?: BPD;\n  upd?: UPD;\n  bankMessages: BankMessage[];\n};\n```\n\nThe BPD object (_BankParameterDaten_) contains general information (e.g. available TAN methods and allowed transactions) and the UPD object (_UserParameterDaten_) user-specific information which is mainly the list of the user's bank accounts.\n\nUnfortunately with this first synchronization call most banks will likely only return the BPA information but no UPD (accounts) information, which is needed to fetch balances or statements. The reason for this is that you need to specify a TAN method before making the synchronization call, but you can only know which TAN methods are available from the BPA? This is why you need to make a second synchronization call with a TAN method selected from the `availableTanMethodIds`in the BPA, returned from the first synchronization call:\n\n```typescript\n// for simplicity, we just select the first available TAN method\nclient.selectTanMethod(syncResponse.bankingInformation.BPD.availableTanMethodIds[0]);\n```\n\nnow you can repeat the syncronization call from above and it will return additional data including the UPD with the account information.\n\nFinally you can start fetching balances or statements:\n\n```typescript\n// for simplicity, use the first account\nconst account = syncResponse.bankingInformation.upd.bankAccounts[0];\n\n// fetch the current balance\nconst balanceResponse = await client.getAccountBalance(account.accountNumber);\n\n// fetch all available statements\nconst statementResponse = await client.getAccountStatements(account.accountNumber);\n\n// or fetch portfolio from a securities account\nclient.getPortfolio(account.accountNumber);\n```\n\nThese are only the most basic steps needed to retrieve information from the bank. There are still some unanswered questions like \"how to handle TANs\" or \"how to avoid synchronizations every time you start a new session\". These are explained in the corresponding sections below.\n\n## More detailed API Description\n\n### Handle TAN challenges from the bank\n\nMost transactions may require authorization with a two step TAN process. As mentioned above in the sample, every response may set the `requiresTan`property to `true` which means that the response does not include the expected transaction data, but some additional TAN related properties. You first need to handle this TAN challenge by asking the user for the TAN and sending it back to the bank to continue the process and retrieve the actual transaction result:\n\n```typescript\n// we use the node readline interface later to ask the user for a TAN\nconst rl = readline.createInterface({\n  input: process.stdin,\n  output: process.stdout,\n});\n\nlet response = await client.getAccountStatements(account.accountNumber);\n\nif (!response.success) {\n  return;\n}\n\n// need to check if a TAN is required to continue the transaction\nif (response.requiresTan) {\n  // asking the user for the TAN, using the tanChallenge property\n  const tan = await rl.question(response.tanChallenge + ': ');\n  // continue the transaction by providing the tanReference from the response and the entered TAN\n  response = await client.getAccountStatementsWithTan(response.tanReference!, tan);\n}\n```\n\nThe `FinTSClient`contains for every transaction method like `synchronize()` or `getAccountStatements()` a corresponding `...WithTan()` method which needs to be called to continue the transaction with the given `tanReference` returned in the first response. The response object of this second call should now contain all transaction related data, assuming `success=true`.\n\n**Decoupled TAN methods**\n\nThe library now also supports decoupled TAN methods where you don't actually have to provide a TAN entered by a user, but the approval is done \"decoupled\" on another device (e.g. mobile phone via banking app). The procedure explained above is still very similar, `requiresTan` will signal a required approval and you can continue with one of the `...WithTan()` methods where you can ommit the last `tan` parameter.\n\nYou could ask the user to confirm that the approval was given and then continue with the call or periodically call the method until it returns the transaction result (`requiresTan=false` and `success=true`). The continuation methods will keep returning `requiresTan=true` as long as the user hasn't approved the transaction.\n\nsee also the `decoupled` property on the `TanMethod` object for related parameters given by the bank.\n\n### Starting a session from saved banking information\n\nAs mentioned earlier there is a second way to initialize the `FinTSClient` with a `FinTSConfig` when you already performed a synchronization in a previous session and this is by providing the `bankingInformation` object received from previous uses. This `bankingInformation` object, which contains the general bank (BPD) and accounts information (UPD), should be persisted after a session and reloaded in the next session.\nThis not only saves you from making the same synchronization requests every time before making a transaction, but the sychronization will also assign a `systemId` (a property in `bankingInformation`) to your client which should stay the same once assigned.\n\n```typescript\nconst config = FinTSConfig.fromBankingInformation(\n  productId,\n  productVersion,\n  bankingInformation,\n  userId,\n  pin,\n  tanMethodId,\n  tanMediaName // when also needed (see below)\n);\nconst client = new FinTSClient(config);\n```\n\nYou should also set the TAN method to use, by using the optional `tanMethodId` and `tanMediaName` parameters or calling `client.selectTanMethod()` before making the first transaction.\n\n#### Tan Media\n\nIt might be the case that you have more than one active TAN media available (like multiple mobile phones) and the bank requires you to also specify which TAN media to use.\nYou can find out if this is the case by inspecting the `TanMethod` object in the BPD.\nYou can get a list of all available TAN methods from the `config.availableTanMethods` property or if you already selected a TAN method with `config.selectedTanMethod`.\n\n```typescript\nexport type TanMethod = {\n  id: number;\n  name: string;\n  version: number;\n  activeTanMediaCount: number;\n  activeTanMedia: string[];\n  tanMediaRequirement: TanMediaRequirement;\n};\n```\n\nThe `TanMethod` object contains a property `tanMediaRequirement` and if this is set to `TanMediaRequirement.Required`, you also need to select a TAN media, either by providing the name in the configuration factory method `FinTSConfig.fromBankingInformation()` or by using `client.selectTanMedia()`.\n\nThe property `activeTanMedia` contains a list of the TAN media names you can use for selection.\n\n#### Banking Information may be updated any time\n\nThe `bankingInformation` is primarily obtained through the `synchronize()` calls as demonstrated above. However, it is possible that the banking information may have changed since the last synchronization call. To address this, the BPD and UPD are versioned, and with every transaction made, not just synchronizations, the currently used versions are provided to the bank. If any changes have occurred, the bank will send back new versions of the BPD and UPD respectively. This process is managed by the client, but it is essential to check the `bankingInformationUpdated` property, which is available in every response. This property indicates if there have been any changes, and it is important to persist the new version for future sessions. The most up-to-date version of the `bankingInformation` object can always be retrieved using `config.bankingInformation`.\n\n### Debugging\n\nIf you need to debug issues and the `response.bankAnswers` don't provide enough information, you can enable debugging of messages with:\n\n```typescript\nconfig.debugEnabled = true;\n```\n\nThis will print out all sent messages and received responses to the console in a structured format.\n\n## Supported Transactions\n\nThe following table shows all transactions supported by the FinTSClient interface:\n\n| Transaction                | Method                                                               | Description                                                                     | FinTS Segment(s)           | TAN Support | Account-Specific |\n| -------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------- | ----------- | ---------------- |\n| **Synchronization**        | `synchronize()`                                                      | Synchronizes bank and account information, updating config.bankingInformation   | HKIDN, HKVVB, HKSYN, HKTAB | ✓           | ❌               |\n| **Account Balance**        | `getAccountBalance(accountNumber)`                                   | Fetches the current balance for a specific account                              | HKSAL                      | ✓           | ✓                |\n| **Account Statements**     | `getAccountStatements(accountNumber, from?, to?)`                    | Fetches account transactions/statements for a date range (MT940 or CAMT format) | HKKAZ, HKCAZ               | ✓           | ✓                |\n| **Portfolio**              | `getPortfolio(accountNumber, currency?, priceQuality?, maxEntries?)` | Fetches securities portfolio information for depot accounts                     | HKWPD                      | ✓           | ✓                |\n| **Credit Card Statements** | `getCreditCardStatements(accountNumber, from?)`                      | Fetches credit card statements for credit card accounts                         | DKKKU                      | ✓           | ✓                |\n| **TAN Method Selection**   | `selectTanMethod(tanMethodId)`                                       | Selects a TAN method by ID from available methods                               | -                          | ❌          | ❌               |\n| **TAN Media Selection**    | `selectTanMedia(tanMediaName)`                                       | Selects a specific TAN media device by name                                     | -                          | ❌          | ❌               |\n\n### Transaction Support Checking\n\nFor each account-specific transaction, the client provides corresponding `can*` methods to check if the bank or specific account supports the transaction:\n\n| Support Check Method                         | Purpose                                                         |\n| -------------------------------------------- | --------------------------------------------------------------- |\n| `canGetAccountBalance(accountNumber?)`       | Checks if account balance fetching is supported                 |\n| `canGetAccountStatements(accountNumber?)`    | Checks if account statements fetching is supported (MT940/CAMT) |\n| `canGetPortfolio(accountNumber?)`            | Checks if portfolio information fetching is supported           |\n| `canGetCreditCardStatements(accountNumber?)` | Checks if credit card statements fetching is supported          |\n\n### TAN Continuation Methods\n\nEvery transaction that supports TAN authentication has a corresponding `*WithTan` method for continuing the transaction after TAN entry:\n\n- `synchronizeWithTan(tanReference, tan?)`\n- `getAccountBalanceWithTan(tanReference, tan?)`\n- `getAccountStatementsWithTan(tanReference, tan?)`\n- `getPortfolioWithTan(tanReference, tan?)`\n- `getCreditCardStatementsWithTan(tanReference, tan?)`\n\nThe `tan` parameter can be omitted when using decoupled TAN methods.\n\n## Limitations\n\n- Only FinTS 3.0 is supported (older versions may not work)\n- Only PIN/TAN security is supported (including decoupled TAN methods)\n- No support for payment transactions or transfers yet\n\nImplementing further transactions should be straight forward and contributions are highly appreciated\n\n### Successfully tested with the following banks\n\n- DKB\n- ING-DiBa\n- Renault Bank Direkt\n\n## Built With\n\n- [Typescript](https://www.typescriptlang.org/) - Programming Language\n- [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) - XML parsing for CAMT statements\n- [Vitest](https://vitest.dev/) - Testing Framework\n- [pnpm](https://pnpm.io/) - Package manager\n\n## Contributing\n\nFeel free to create an issue if you want to report a bug.\n\nIf you tested this library with some other bank it would be great to hear from you and update the information on this page\n\nAs this is a free-time project, a lot of things are still remaining which could be added to this library, especially other kinds of transactions. If you want to contribute with pull-requests this would be highly appreciated\n\n## License\n\nThis project is licensed under the LGPL 3.0 License - see the [LICENSE](LICENSE) file for details\n\n## References\n\n- [Product Registration](https://www.hbci-zka.de/register/prod_register.htm)\n- [FinTS 3.0 Specification](https://www.hbci-zka.de/spec/3_0.htm)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobocode13%2Flib-fints","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobocode13%2Flib-fints","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobocode13%2Flib-fints/lists"}