Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .docs/moneta.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# How MONETA's e-mail behaves

**Not seen as a real e-mail yet (2026-11-10).** The parser follows the sanitised samples in
[radekhulan/myinvoice](https://github.com/radekhulan/myinvoice/blob/master/api/tests/Unit/Bank/MonetaBankEmailNoticeParserTest.php)
(MIT), whose MONETA parser real users run. No key is pinned, so `withDns()` refuses every MONETA e-mail as `Unverified`,
with the fingerprint of the key DNS gave in the message. The first real e-mail confirms the template and that key;
see [#18](https://github.com/landsman/bank-java/issues/18).

## What it carries, and what it does not

Subject `Přišly peníze` or `Odešly peníze`, from `infoservis@moneta.cz`, the label on one line and its value on the next:

```
Přišly peníze

Účet:
238***891

Datum:
01.07.2026

Částka:
35 000,00 Kč

Popis:
OKAMŽITÁ ÚHRADA, DOM-AVIZO:202600009 FIRMA DEMO S.R.O., VS: 202600009

Od:
264555317/0300

Disponibilní zůstatek:
64 831,42 Kč

Účetní zůstatek:
64 831,42 Kč
```

- **The receiving account is masked** (`238***891`): `account()` is `null`. Which merchant it belongs to has to come from
the address it was sent to.
- **No transaction id**: `transactionId()` is `null`. A second delivery of the same e-mail is told apart only by a
signed `messageId()`, if MONETA signs it, which a real e-mail will show.
- **The variable symbol is inside `Popis`**, as `VS: 202600009`, and `Popis` may hold the payer's own text. Two `VS:`
there are refused; one is taken, so **match on the amount as well**.
- **The balance has a date but no time**, so `balance()` is `null`.
- **`type()` is `GENERAL`**: the description says `OKAMŽITÁ ÚHRADA` and the like, but no mapping is built without samples.
- Only `Kč` amounts are read; another currency is refused.

## Setting it up

[Fakturoid's guide](https://www.fakturoid.cz/podpora/parovani/moneta): Nastavení → Upozornění - Info Servis →
Přidat upozornění → Účty; E-mail for Příchozí and Odchozí platba. **MONETA notifies only from 100 Kč**, so smaller
payments send nothing. MONETA also has a free API with a token the account holder issues, without that floor:
[moneta-api-java](https://github.com/landsman/moneta-api-java).
5 changes: 5 additions & 0 deletions .docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,11 @@ English); its fields, as both interfaces showed them on 2026-11-10:

Check that `read` returns a `Transaction` for a small payment.

## MONETA

See [moneta.md](moneta.md#setting-it-up): Upozornění - Info Servis, e-mail for incoming and outgoing payments, only
from 100 Kč. Not verified yet: no real MONETA e-mail has been read.

## Another bank

Not supported yet; see [what it covers](../README.md#what-it-covers). Adding one starts from one of its real e-mails,
Expand Down
5 changes: 3 additions & 2 deletions .docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ with the message `no parser for sender domain <domain>`, until that bank is adde
| Bank | Recognised by | Reads | Details |
|---|---|---|---|
| Air Bank | `From: info@airbank.cz`, signed by `airbank.cz` | incoming and outgoing transfers | [how its e-mail behaves](air-bank.md) |
| MONETA | `From: infoservis@moneta.cz`, signed by `moneta.cz` | incoming and outgoing, from public samples; no key pinned, so `Unverified` until a real e-mail | [how its e-mail behaves](moneta.md) |
| Fio banka CZ | `From: automat@fio.cz`, signed by `fio.cz` | transfers in and out, card payments, direct debits | [how its e-mail behaves](fio-cz.md) |

```java
Expand Down Expand Up @@ -67,14 +68,14 @@ from a fake.
| `signedBy()` | the bank's domain whose signature verified: `airbank.cz`, `fio.cz` |
| `direction()`, `incoming()` | `INCOMING` or `OUTGOING` |
| `type()` | `TRANSFER`, `CARD`, `DIRECT_DEBIT`, or `GENERAL` when the e-mail does not say |
| `account()` | the account the e-mail is about, a `BankAccount` |
| `account()` | the account the e-mail is about, a `BankAccount`; `null` where the bank masks it (MONETA) |
| `counterAccount()` | the payer of an incoming payment, the recipient of an outgoing one; `null` for a card payment |
| `counterName()` | the other side's name, when the bank prints it; `null` otherwise |
| `amount()` | a `Money`: `BigDecimal` and `Currency`, signed, positive in and negative out |
| `symbols()` | `PaymentSymbols`: `variable()`, `constant()`, `specific()`, each `null` when absent |
| `message()` | the payment's message, when the bank prints it; `null` otherwise |
| `bookedOn()` | the booking date the bank states |
| `transactionId()` | the bank's own id of the transaction |
| `transactionId()` | the bank's own id of the transaction; `null` where the bank prints none (MONETA) |
| `messageId()` | the e-mail's `Message-ID`, only when the bank's DKIM signature covers it; `null` otherwise (Air Bank and Fio do not sign it) |
| `balance()` | a `Balance`: the `available()` money right after the payment and `asOf()`, the bank's time to the minute; `null` when the bank does not state it in a form the library reads |

Expand Down
33 changes: 17 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,22 +24,22 @@ For Java 21+ and Kotlin, one jar, no framework required.

## What it covers

✅ read, ⬜ not yet, ❔ no real e-mail has shown it yet. Details per bank: [Air Bank](.docs/air-bank.md),
[Fio CZ](.docs/fio-cz.md).

| Feature | Air Bank | Fio banka CZ |
|---|:---:|:---:|
| Incoming payment | ✅ | ✅ |
| Outgoing payment | ✅ | ✅ |
| Card payment | ❔ | ✅ |
| Direct debit | ❔ | ✅ |
| Amount | ✅ below 1 000 so far | ✅ |
| Who paid: name and account | ✅ | ✅ |
| Variable symbol | ✅ | ✅ |
| Message for the recipient | ✅ | ✅ |
| Date and transaction id | ✅ | ✅ |
| Balance after the payment | ✅ below 1 000 so far | ✅ |
| Proven to come from the bank | ✅ | ✅ |
✅ read, ⬜ not yet, ❔ no real e-mail has shown it yet. MONETA is read from public samples only. Details per bank:
[Air Bank](.docs/air-bank.md), [Fio CZ](.docs/fio-cz.md), [MONETA](.docs/moneta.md).

| Feature | Air Bank | Fio banka CZ | MONETA |
|---|:---:|:---:|:---:|
| Incoming payment | ✅ | ✅ | ❔ |
| Outgoing payment | ✅ | ✅ | ❔ |
| Card payment | ❔ | ✅ | ❔ |
| Direct debit | ❔ | ✅ | ❔ |
| Amount | ✅ below 1 000 so far | ✅ | ❔ |
| Who paid: name and account | ✅ | ✅ | ❔ account only |
| Variable symbol | ✅ | ✅ | ❔ from Popis |
| Message for the recipient | ✅ | ✅ | ❔ |
| Date and transaction id | ✅ | ✅ | ❔ date only |
| Balance after the payment | ✅ below 1 000 so far | ✅ | ⬜ |
| Proven to come from the bank | ✅ | ✅ | ⬜ no key yet |

Other banks: not yet.

Expand All @@ -53,6 +53,7 @@ Other banks: not yet.
| [How verification works](.docs/verification.md) | why a forged e-mail cannot pass |
| [How Air Bank's e-mail behaves](.docs/air-bank.md) | what the bank sends and what has not been seen yet |
| [How Fio CZ's e-mail behaves](.docs/fio-cz.md) | the same for Fio banka in Czechia |
| [How MONETA's e-mail behaves](.docs/moneta.md) | the same for MONETA, from public samples |
| [Roadmap](.docs/plan/roadmap.md) | what is next |
| [Development](.docs/development.md) | building it, adding a bank |
| [llms.txt](llms.txt) | for a coding assistant adding the library to a project |
Expand Down
3 changes: 2 additions & 1 deletion llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ Mistakes to avoid:
- Deduplicate on `transactionId()`, per bank: the same e-mail can arrive twice. `messageId()` is set only when the
bank signs it; never deduplicate on a `Message-ID` header read elsewhere, which a copy of the e-mail can change.
- `balance()` is the balance right after the payment and may be `null`; never take it for the account's current balance.
- `counterAccount()` is `null` for a card payment.
- `counterAccount()` is `null` for a card payment; `account()` and `transactionId()` are `null` for MONETA, which
masks the account and prints no id: tell the merchant by the inbound address, deduplicate on a signed `messageId()`.
- `amount()` is signed: negative is money out. `Transaction.Type` may gain constants: keep a `default` branch.
- Messages over 64 KiB are `Unparsed`; a notification is around 5 KiB.
- Do not use `trustingKeysFrom` in production: it skips DNSSEC and pinning. It is for tests.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
Date: Wed, 01 Jul 2026 12:49:00 +0200
From: MONETA Money Bank <infoservis@moneta.cz>
To: bruce.wayne@gothba.org
Message-ID: <0000@moneta.cz>
Subject: =?utf-8?b?UMWZacWhbHkgcGVuw616ZQ==?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit

Dobrý den,
zasíláme Vám nové upozornění. Na tento e-mail prosím neodpovídejte, jedná se o automaticky generovaný e-mail.
Přišly peníze

Účet:
238***891

Datum:
01.07.2026

Částka:
35 000,00 Kč

Popis:
OKAMŽITÁ ÚHRADA, DOM-AVIZO:202600009 WAYNE ENTERPRISES S.R.O., VS: 202600009

Od:
9876543211/0300

Disponibilní zůstatek:
64 831,42 Kč

Účetní zůstatek:
64 831,42 Kč
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
Date: Wed, 01 Jul 2026 12:49:00 +0200
From: MONETA Money Bank <infoservis@moneta.cz>
To: bruce.wayne@gothba.org
Message-ID: <0000@moneta.cz>
Subject: =?utf-8?b?T2RlxaFseSBwZW7DrXpl?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit

Odešly peníze

Účet:
238***891

Datum:
15.07.2026

Částka:
1 250,50 Kč

Popis:
Platba faktury VS: 2607001

Od:
1234567899/0100

Disponibilní zůstatek:
10 000,00 Kč
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
package cz.insuit.bank.notification;

import cz.insuit.bank.notification.BankNotificationException.Unparsed;
import cz.insuit.bank.notification.Transaction.Direction;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.Currency;
import java.util.Map;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.jspecify.annotations.Nullable;

/**
* MONETA Money Bank's Info Servis e-mail, "Přišly peníze" / "Odešly peníze", from {@code infoservis@moneta.cz}.
*
* <p><b>Read from public samples, not from a real e-mail yet</b>: the template follows the sanitised bodies in
* <a href="https://github.com/radekhulan/myinvoice">radekhulan/myinvoice</a> (MIT), its MONETA parser's test. No
* key is pinned, so {@link BankNotifications#withDns()} refuses every MONETA e-mail as unverified, naming the key DNS
* gave, until a real one confirms the template and the key.
*
* <p>What the e-mail does not carry, and the transaction leaves out: the receiving account, which MONETA masks
* ({@code 238***891}), so {@link Transaction#account()} is {@code null}; a transaction id, so
* {@link Transaction#transactionId()} is {@code null}; and the balance's time, so there is no balance. The variable
* symbol is taken from {@code Popis}, which may hold the payer's own text, so a match must check the amount too.
*/
final class Moneta implements Bank {

static final String DOMAIN = "moneta.cz";

/** None yet: no real e-mail has shown MONETA's selector. See {@link AirBank#KEY_FINGERPRINTS} for how they are kept. */
static final Set<String> KEY_FINGERPRINTS = Set.of();

@Override
public String domain() {
return DOMAIN;
}

@Override
public Set<String> keyFingerprints() {
return KEY_FINGERPRINTS;
}

@Override
public Transaction parse(@Nullable String subject, String body) {
Direction stated = subject == null ? null : HEADINGS.get(subject);
if (stated == null) throw new Unparsed("not a template this library knows, subject: " + subject);

NotificationLines lines = new NotificationLines(body);
Matcher heading = lines.single(HEADING, "heading");
if (heading == null || HEADINGS.get(heading.group()) != stated) {
throw new Unparsed("subject and heading disagree on the direction");
}
// Past the description only the counter-account and the balances follow.
Map<String, String> fields =
lines.stacked(LABELS, Set.of(DESCRIPTION), Set.of(COUNTER_ACCOUNT, AVAILABLE, BOOKED));
if (!fields.containsKey(ACCOUNT)) throw new Unparsed("no Účet");

String amountText = fields.get(AMOUNT);
Matcher amount = amountText == null ? null : MONEY.matcher(amountText);
if (amount == null || !amount.matches()) throw new Unparsed("amount missing or not in the known format");
String date = fields.get(DATE);
if (date == null) throw new Unparsed("no Datum");
LocalDate bookedOn;
try {
bookedOn = LocalDate.parse(date, DATE_FORMAT);
} catch (DateTimeParseException e) {
throw new Unparsed("Datum not dd.MM.yyyy: " + date);
}

String description = fields.get(DESCRIPTION);
String variableSymbol = null;
if (description != null) {
Matcher symbol = VARIABLE_SYMBOL.matcher(description);
if (symbol.find()) {
variableSymbol = symbol.group(1);
// A second one can only be the payer's text; neither is then the bank's.
if (symbol.find()) throw new Unparsed("two variable symbols in Popis");
}
}
try {
String counter = fields.get(COUNTER_ACCOUNT);
Money value = new Money(
new BigDecimal(amount.group(1).replace(" ", "") + "." + amount.group(2)),
Currency.getInstance("CZK"));
return new Transaction(
DOMAIN,
stated,
Transaction.Type.GENERAL,
null,
counter == null ? null : BankAccount.parse(counter),
null,
stated == Direction.INCOMING ? value : value.negate(),
new PaymentSymbols(variableSymbol, null, null),
description,
bookedOn,
null,
null,
null);
} catch (IllegalArgumentException e) {
throw new Unparsed(e.getMessage() == null ? "invalid value" : e.getMessage(), e);
}
}

private static final Map<String, Direction> HEADINGS =
Map.of("Přišly peníze", Direction.INCOMING, "Odešly peníze", Direction.OUTGOING);
private static final Pattern HEADING = Pattern.compile("Přišly peníze|Odešly peníze");
// Only Kč seen; another currency is refused rather than guessed.
private static final Pattern MONEY = Pattern.compile("(\\d{1,3}(?: \\d{3})*),(\\d{2}) Kč");
private static final Pattern VARIABLE_SYMBOL = Pattern.compile("\\bVS: ?(\\d{1,10})\\b");
private static final DateTimeFormatter DATE_FORMAT = DateTimeFormatter.ofPattern("dd.MM.uuuu");

private static final String ACCOUNT = "Účet";
private static final String DATE = "Datum";
private static final String AMOUNT = "Částka";
private static final String DESCRIPTION = "Popis";
private static final String COUNTER_ACCOUNT = "Od";
private static final String AVAILABLE = "Disponibilní zůstatek";
private static final String BOOKED = "Účetní zůstatek";
private static final Set<String> LABELS =
Set.of(ACCOUNT, DATE, AMOUNT, DESCRIPTION, COUNTER_ACCOUNT, AVAILABLE, BOOKED);
}
Loading
Loading