Skip to content

Latest commit

 

History

History
137 lines (100 loc) · 5.79 KB

usage.md

File metadata and controls

137 lines (100 loc) · 5.79 KB

Using the client

var moneta = new MonetaClient();                  // one per application
var me = moneta.with(new AccessToken(myToken));   // cheap, keep it or make one per request

var november = me.transactions().between(LocalDate.of(2026, 11, 1), LocalDate.of(2026, 11, 30));

november.list();                        // everything
november.incoming().booked().list();    // money that came in, booked
november.transfers().outgoing().list(); // transfers that went out
november.cards().list();                // paid by the account's card

me.balance();                           // booked and available, with the instant MONETA computed it
me.tokenExpiry();                       // when the token stops working: ask the merchant for a new one before it does
Kotlin
val moneta = MonetaClient()                 // one per application
val me = moneta.with(AccessToken(myToken))  // cheap, keep it or make one per request

val november = me.transactions().between(LocalDate.of(2026, 11, 1), LocalDate.of(2026, 11, 30))

november.list()                        // everything
november.incoming().booked().list()    // money that came in, booked
november.transfers().outgoing().list() // transfers that went out
november.cards().list()                // paid by the account's card

me.balance()                           // booked and available, with the instant MONETA computed it
me.tokenExpiry()                       // when the token stops working: ask the merchant for a new one before it does

With the Spring Boot starter, moneta.token gives you the AccessToken bean.

Filtering

Step Keeps
between(from, to) days, both inclusive; required
transfers(), cards(), method(…) how the money moved
incoming(), outgoing() money in, money out
booked(), pending() booked, pending
  • Steps are optional and combine; a later one of the same kind wins.
  • A query is immutable, so one base query can branch, as november above.
  • Nothing is read until list(). MONETA filters by date only, so a shorter range is what makes it cheaper.

More than one account

transactions() and balance() read the only account the token opens, and throw IllegalStateException when there are more. Name the account then. To read the one you stored, find it by its IBAN, which is what the merchant gave you; MONETA's own account id is known to nobody outside it:

var account = me.accountByIban(storedIban);   // only letters and digits count, in either case
if (account == null) {
    return refuse();                          // the token no longer sees it: revoked, or another token pasted
}
me.transactions(account.id()).between(from, to).list();

for (var other : me.accounts()) {             // or every account the token opens
    me.transactions(other.id()).between(from, to).cards().list();
}
Kotlin
val account = me.accountByIban(storedIban) ?: return refuse()
me.transactions(account.id).between(from, to).list()

for (other in me.accounts()) {
    me.transactions(other.id).between(from, to).cards().list()
}

accountByIban reads the accounts on every call, so an account revoked for the token shows on the next one. A blank IBAN, or one failing its check digits, is an IllegalArgumentException: a typo, not a revoked account. Two accounts with one IBAN, one per currency, are an IllegalStateException naming both ids.

Several account holders, each with their own token, share one client:

holders.forEach(holder -> moneta.with(holder.token()).transactions().between(from, to).list());
Kotlin
holders.forEach { moneta.with(it.token).transactions().between(from, to).list() }

What to know

  • entryReference changes when a movement is booked: deduplicate by it and a payment counts twice. Act on booked movements, or match by symbols, amount and counterparty account, as examples/cafe does.
  • Dates only, no time of day. The payment's date is enteredDate() while pending, valueDate() once booked. Need "paid a minute ago"? Store when you first saw it.
  • amount() is signed: negative is money out, so amounts add up. Money is a BigDecimal with a currency.
  • method() is TRANSFER, CARD or OTHER, and gains constants as they are seen live (#66): keep a default in a switch.
  • symbols() reads VS, KS and SS, leading zeros kept.
  • reversed() is a reversal, not a payment.
  • raw() has the whole movement as JSON. It, message() and the counterparty stay out of toString(), not out of a JSON serialiser: map to your own type before returning one from a controller.
  • A read is all or nothing, every page or a failure. Read long ranges month by month.
  • Records may gain components before 1.0: use accessors, not record patterns.

How MONETA API behaves has the details behind each.

Failures

A sealed MonetaException, so a switch over it is exhaustive:

Subtype When Do
InvalidToken 401, 403 get a new token
RateLimited 429 wait retryAfter()
HttpError any other status body() has MONETA's answer
NoAnswer timeout, refused connection retry
InvalidResponse an unexpected body report it

An interrupted thread throws CancellationException instead, interrupt flag kept.

Settings

MonetaClient.builder(): baseUri(…), requestTimeout(…), partner(…) (headers MONETA does not ask for yet), configureHttpClient(…) for a proxy or mTLS, decorateHttpClient(…) for tracing or metrics (examples). close() releases the HTTP client it made.