RoutexClient

Kotlin client for the YAXI Open Banking interactive services: accounts, balances, collectPayment, transactions, transfer, plus the discovery endpoints info and search.

Every service call returns a typed Response. A Response.Result holds an Authenticated JWT carrying the typed payload; the other variants (Response.Dialog, Response.Redirect, Response.RedirectHandle) are interrupts the caller resolves before the flow can complete (see Handling interrupts). Each call is authorized by a typed Ticket (for example Ticket.Accounts) minted by the caller's backend (see Getting started); the bank-side identification uses a Credentials envelope (see Providing Credentials).

Resolving interrupts

• Response.Dialog: present dialog.input to the user, then call the matching respond* (when the user enters or selects an answer) or confirm* (when the user just confirms) with the context carried by the input.

• Response.Redirect: send the user to redirect.url, then call the matching confirm* with redirect.context.

• Response.RedirectHandle: call registerRedirectUri with redirectHandle.handle to obtain the URL to open, then confirm with redirectHandle.context. Setting a default redirect via setRedirectUri turns later interrupts into Response.Redirect directly.

Loop until a Response.Result is returned.

Handling the result

• Forward result.authenticated.jwt to your backend, verify the signature with your YAXI API secret (the same key your backend uses to mint tickets), and act on the verified payload. See Verify results for backend snippets. result.authenticated.decodeUnverified() is available for client-only display; its output must never reach a backend or drive a security-sensitive decision.

• Persist result.connectionData. Pass it back via Credentials.connectionData on a future RoutexClient call to skip prompts the original consent already covers, or hand it to your backend to drive non-interactive refreshes via RoutexRefreshClient.

• Pass result.session to subsequent calls in the same flow.

Shared parameters

Service methods share these optional inputs (omitted from each method's KDoc; see Handling sessions for the broader picture):

• session: opaque Session returned by a previous call in the same flow.

• recurringConsents: when true, request a long-lived consent with the maximum permissions the bank grants for this ticket's service so the returned ConnectionData carries it. Subsequent RoutexClient calls that reuse that ConnectionData (via Credentials.connectionData) and non-interactive refreshes on RoutexRefreshClient skip the interrupt loop until the consent expires or is revoked. Persist the resulting ConnectionData alongside the user's credentials, since it gates downstream refreshes. Default false requests a one-shot consent scoped to this call.

Errors

Service methods are suspend and throw on failure. Expected exceptions:

• RoutexError subclasses (mapped from the server's typed error response; see Errors).

• RoutexClientError.MalformedResponse when the server returned a payload this client could not decode (incident-grade; report it with the traceId).

• AuthenticatedDecodeError when the JWT body did not match the expected typed shape (raised lazily by result.authenticated.decodeUnverified()).

• I/O exceptions from the underlying HttpTransport (timeouts, connection failures, and similar).

Lifecycle

Instances are safe to share across coroutines; create one per backing HttpTransport and reuse it. Java callers should use RoutexAsyncClient.

Samples

client.accounts(
    accountsTicket,
    credentials,
    fields = listOf(
        AccountField.Iban,
        AccountField.Bic,
        AccountField.Name,
        AccountField.DisplayName,
        AccountField.OwnerName,
        AccountField.Currency,
    ),
    filter = AccountField.Iban.notEq(null)
        .and(AccountField.Type.eq(AccountType.CURRENT)
            .or(AccountField.Type.eq(null)))
        .and(Account.supports(SupportedService.COLLECT_PAYMENT)),
)