feat: implement missing FinTS 3 features (HKPAE, HKCSE, full mock server & integration tests)#42
feat: implement missing FinTS 3 features (HKPAE, HKCSE, full mock server & integration tests)#42
Conversation
Agent-Logs-Url: https://github.com/larsdecker/fints/sessions/8f5a1b48-c3fb-432e-b19f-0737c87474e4 Co-authored-by: larsdecker <1968186+larsdecker@users.noreply.github.com>
… server and integration tests) Agent-Logs-Url: https://github.com/larsdecker/fints/sessions/8f5a1b48-c3fb-432e-b19f-0737c87474e4 Co-authored-by: larsdecker <1968186+larsdecker@users.noreply.github.com>
…tion finding Agent-Logs-Url: https://github.com/larsdecker/fints/sessions/8f5a1b48-c3fb-432e-b19f-0737c87474e4 Co-authored-by: larsdecker <1968186+larsdecker@users.noreply.github.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 27d9cb84c1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| await dialog.send(this.createRequest(dialog, segments)); | ||
| if (shouldInitializeDialog) { | ||
| await dialog.end(); | ||
| } |
There was a problem hiding this comment.
After HKPAE succeeds, the method immediately closes the dialog without updating the client/dialog PIN to newPin, so HKEND (and all later requests) are still signed with the old PIN. On banks that apply the PIN change immediately, this causes the close request or the very next API call to fail authentication even though the PIN change itself succeeded.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Implements missing FinTS 3.0 business transactions (PIN change + scheduled SEPA credit transfer), expands the mock FinTS 3 test server to cover additional operations, and adds extensive integration/unit test coverage.
Changes:
- Add new FinTS 3.0 segments for PIN change (HKPAE) and scheduled SEPA credit transfer (HKCSE/HICSE/HICSES), plus capability flag wiring.
- Extend mock bank server sync + business transaction handling (credit transfer, direct debit, scheduled transfer, standing orders, holdings).
- Add/expand integration and unit tests to exercise the full dialog lifecycle and new features.
Reviewed changes
Copilot reviewed 14 out of 15 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| yarn.lock | Lockfile updated; now includes workspace file: entries (currently with absolute paths). |
| packages/fints/src/v4/dialog.ts | Add supportsScheduledCreditTransfer (v4 still reports false). |
| packages/fints/src/types.ts | Add scheduled credit transfer request/submission types + capability flag. |
| packages/fints/src/test-server/test-data.ts | Add task ID constant and test MT535 / PAIN.001 builders for mock responses. |
| packages/fints/src/test-server/mock-bank-server.ts | Expand mock server to handle additional FinTS 3 transactions + new sync advertisement. |
| packages/fints/src/test-server/tests/test-mock-bank-v3-integration.ts | Add many integration tests covering the new mock server behaviors and client APIs. |
| packages/fints/src/segments/index.ts | Export newly added segments. |
| packages/fints/src/segments/hkpae.ts | New HKPAE segment (PIN change request) serialization. |
| packages/fints/src/segments/hkcse.ts | New HKCSE segment (scheduled credit transfer request) serialization. |
| packages/fints/src/segments/hicse.ts | New HICSE acknowledgement segment parsing. |
| packages/fints/src/segments/hicses.ts | New HICSES parameter segment parsing. |
| packages/fints/src/segments/tests/test-hkpae.ts | Unit tests for HKPAE serialization. |
| packages/fints/src/segments/tests/test-hkcse.ts | Unit tests for HKCSE serialization and HICSE/HICSES parsing. |
| packages/fints/src/dialog.ts | Add scheduled credit transfer capability detection and expose via capabilities. |
| packages/fints/src/client.ts | Add changePin, scheduledCreditTransfer, and completeScheduledCreditTransfer APIs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.001.003.03`, | ||
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.002.003.03`, | ||
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.008.003.02`, |
There was a problem hiding this comment.
The HISPAS sync response encodes each PAIN format as a separate + data group. However, HISPAS.deserialize() only reads the 4th data group for formats, so formats after the first one are silently dropped (e.g. pain.008 won’t be advertised to the client). Pack the supported formats into the expected single DEG (e.g. join formats with : in the 4th field) so response.painFormats contains all advertised PAIN versions.
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.001.003.03`, | |
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.002.003.03`, | |
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.008.003.02`, | |
| [ | |
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.001.003.03`, | |
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.002.003.03`, | |
| `urn?:iso?:std?:iso?:20022?:tech?:xsd?:pain.008.003.02`, | |
| ].join(":"), |
| `5000,00:EUR`, // Credit limit | ||
| `C:13095,67:EUR:${dateStr}`, // Pre-booked balance | ||
| `5000,00:EUR`, // Credit limit (Dispositionskredit) | ||
| `C:13095,67:EUR`, // Available balance (Verfügbarer Betrag) |
There was a problem hiding this comment.
HISAL.deserialize() expects the available-balance data group to contain the numeric amount as its first element. The mock response currently sends C:13095,67:EUR, which parses to ['C','13095,67','EUR'] and results in availableBalance becoming NaN. Send the available balance as an amount element (e.g. 13095,67 or 13095,67:EUR) so parsing yields a valid number.
| `C:13095,67:EUR`, // Available balance (Verfügbarer Betrag) | |
| `13095,67:EUR`, // Available balance (Verfügbarer Betrag) |
| * Submit a scheduled (future-dated) SEPA credit transfer (Terminüberweisung). | ||
| * | ||
| * The execution date is encoded inside the pain.001 XML message as | ||
| * ReqdExctnDt. The bank must advertise HICSES support during synchronisation; | ||
| * otherwise an error is thrown. | ||
| * |
There was a problem hiding this comment.
The JSDoc says an error is thrown if the bank does not advertise HICSES support, but scheduledCreditTransfer() does not check dialog.supportsScheduledCreditTransfer (or hicseVersion) before submitting the request. Either add an explicit capability check and throw a clear error, or update the documentation to match the current behavior (letting the server response drive failures).
| /** | ||
| * Negotiated version for HKCSE (scheduled credit transfer). | ||
| */ | ||
| public hicseVersion = 1; |
There was a problem hiding this comment.
Dialog uses hkccsVersion / hkdseVersion naming for the negotiated request-segment versions, but the new scheduled-transfer version is named hicseVersion even though it’s used as the HKCSE request version (derived from HICSES). For consistency and to avoid confusion with the response segment HICSE, consider renaming this to hkcseVersion (and updating call sites) or otherwise aligning the name with the existing pattern.
| public hicseVersion = 1; | |
| public hkcseVersion = 1; |
|
@copilot apply changes based on the comments in this thread Please let also a eslint and prettier run before you commit your changes. |
…e, hkcseVersion rename, capability check, eslint/prettier Agent-Logs-Url: https://github.com/larsdecker/fints/sessions/3836d525-d5c2-475f-9fd5-afc9ab8ffdfb Co-authored-by: larsdecker <1968186+larsdecker@users.noreply.github.com>
All four review points have been addressed in commit
ESLint (0 errors) and Prettier were run on all changed files before committing. |
Summary
Implements the previously missing FinTS 3.0 business transactions, extends the mock bank server to cover all operations, and adds comprehensive integration tests.
Changes
New FinTS 3 Segments
hkpae.ts) – PIN change request (Persönliche Kennung ändern, FinTS 3.0 §C.4.1). Sends new PIN twice for confirmation; old PIN is authenticated via the standard HNSHA mechanism.hkcse.ts) – Scheduled SEPA credit transfer (Terminüberweisung). Same pain.001 structure as HKCCS but withReqdExctnDtset to a future date inside the XML.hicse.ts) – Bank acknowledgement for HKCSE, carrying the assigned task ID.hicses.ts) – Parameter segment advertised by the bank during sync to indicate scheduled credit transfer support.Client Methods
changePin(newPin)– Sends HKPAE and handles the dialog lifecycle.scheduledCreditTransfer(account, request)– Sends HKCSE with a future execution date embedded in the pain.001 XML.completeScheduledCreditTransfer(...)– Completes a TAN-challenged scheduled transfer.Capability Detection
supportsScheduledCreditTransferadded toBankCapabilities,Dialog, andFinTS4Client.Mock Bank Server (
mock-bank-server.ts)Now handles all major FinTS 3 business transactions:
Sync response now advertises: HICCSS, HIDSES, HICSES, HICDBS, HIWPDS.
Also fixed the HISAL response format: correct account DEG order and added the 7th available-balance field required by the spec.
Tests
test-mock-bank-v3-integration.ts) covering the full dialog lifecycle, all business transactions, and the high-level PinTanClient API.Total: 584 tests passing (541 originally + 43 new).