models/tech.yaxi.routex.models

Package-level declarations

YAXI Open Banking wire DTOs (services, tickets, credentials, dialogs, responses, errors).

Types

Account access exceeded the user's consent. Only the non-interactive transactions refresh path raises this error; the interactive transactions flow does not.

Account

@Serializable

data class Account

Payment account exposed by a service connection.

AccountBalances

@Serializable

data class AccountBalances

Per-account container holding zero or more typed balances.

AccountField

@Serializable(with = AccountFieldSerializer::class)

sealed class AccountField<ValueType>

Field of an Account that can be referenced in filters or requested from the service.

AccountFilter

@Serializable(with = AccountFilterSerializer::class)

sealed class AccountFilter

Predicate applied to accounts when invoking the accounts service.

AccountIdentifier

@Serializable(with = AccountIdentifierSerializer::class)

sealed class AccountIdentifier

Identifier of an account, used when referencing creditor or debtor accounts in payment-related requests.

AccountReference

@Serializable(with = AccountReferenceSerializer::class)

data class AccountReference(val iban: String, val currency: String? = null) : DebtorAccountReference

Reference to an account by IBAN, with an optional ISO 4217 currency code for multi-currency accounts.

AccountsResult

@Serializable

data class AccountsResult : RoutexResult<List<Account>>

Authenticated result of a successful accounts service call.

AccountsServiceRequest

@Serializable

data class AccountsServiceRequest(val credentials: Credentials, val session: Session? = null, val recurringConsents: Boolean = false, val fields: List<AccountField<*>>, val filter: AccountFilter? = null)

Request body for the interactive accounts service.

AccountStatus

@Serializable

enum AccountStatus : Enum<AccountStatus>

Status of an Account.

AccountType

@Serializable

enum AccountType : Enum<AccountType>

Type of an Account (mostly aligned with ISO 20022 ExternalCashAccountType1Code).

Amount

@Serializable

data class Amount(val amount: BigDecimal, val currency: String)

Monetary amount paired with an ISO 4217 currency code.

Authenticated

class Authenticated<T>

Wrapper around an authenticated YAXI service response carried as a JWT.

AuthenticatedDecodeError

class AuthenticatedDecodeError(message: String, cause: Throwable? = null) : RuntimeException

Thrown when a JWT-bearing response cannot be decoded, the JWT is structurally malformed, its body is not valid JSON, the data claim is missing, or the claim's value does not match the expected typed payload shape.

Balance

@Serializable

data class Balance

Single account balance reported by the balances service.

Balances

@Serializable

data class Balances

Top-level payload returned by the balances service.

BalancesResult

@Serializable

data class BalancesResult : RoutexResult<Balances>

Authenticated result of a successful balances service call.

BalancesServiceRequest

@Serializable

data class BalancesServiceRequest(val credentials: Credentials, val session: Session? = null, val recurringConsents: Boolean = false, val accounts: List<AccountReference>)

Request body for the interactive balances service.

BalanceType

@Serializable

enum BalanceType : Enum<BalanceType>

Kind of balance reported for an account.

BankTransactionCode

@Serializable(with = BankTransactionCodeSerializer::class)

sealed class BankTransactionCode

Bank transaction code attached to a Transaction.

BatchData

@Serializable

data class BatchData

Per-transaction batch metadata: count of grouped transactions plus their individual details where the provider supplied them.

BatchTransactionDetails

@Serializable

data class BatchTransactionDetails

Per-entry details for a transaction inside a batch. Same fields as Transaction minus the booking dates and status (those are carried by the parent transaction).

Canceled

@Serializable

data object Canceled : RoutexError

The user canceled the flow (rejecting an SCA prompt or letting it time out). Ask whether the user wants to start again.

ChargeBearer

@Serializable

enum ChargeBearer : Enum<ChargeBearer>

Who bears the charges for a transfer.

CollectPaymentResult

@Serializable

data class CollectPaymentResult : RoutexResult<PaymentInitiation>

Authenticated result of a successful collect-payment service call.

CollectPaymentServiceRequest

@Serializable

data class CollectPaymentServiceRequest(val credentials: Credentials, val session: Session? = null, val recurringConsents: Boolean = false, val account: DebtorAccountReference? = null)

Request body for the interactive collect-payment service.

ConfirmationContext

@Serializable(with = ConfirmationContextSerializer::class)

class ConfirmationContext

Opaque context returned alongside a Confirmation dialog, a Redirect, or a RedirectHandle. Pass it back to one of the confirm* methods on RoutexClient to continue the flow.

ConnectionData

@Serializable(with = ConnectionDataSerializer::class)

class ConnectionData

Opaque connection data returned by a successful interactive service call.

ConnectionDetails

@Serializable

enum ConnectionDetails : Enum<ConnectionDetails>

Optional extra fields a search may request the server to populate on each returned ConnectionInfo.

ConnectionId

@Serializable(with = ConnectionIdSerializer::class)

data class ConnectionId(val uuid: Uuid)

Identifier of a specific service connection (bank or other provider integration).

ConnectionInfo

@Serializable

data class ConnectionInfo

Metadata describing a single service connection (bank or other provider integration).

ConnectionType

@Serializable

enum ConnectionType : Enum<ConnectionType>

Type of connections to consider when searching.

ConsentExpired

@Serializable

data class ConsentExpired : RoutexError

The recurring consent attached to the call's ConnectionData has expired. The YAXI service emits this only when the call carried Credentials.connectionData (or, for RoutexRefreshClient, a stored ConnectionData). Restart the flow without ConnectionData so the user can renew consent.

CountryCode

typealias CountryCode = String

ISO 3166-1 ALPHA-2 country code.

Credentials

@Serializable

data class Credentials @JvmOverloads constructor(val connectionId: ConnectionId, val userId: String? = null, val password: String? = null, val connectionData: ConnectionData? = null)

User credentials for a given service connection.

CredentialsModel

@Serializable

data class CredentialsModel

Requirements for user identifier and password a connection accepts.

CreditorAddress

@Serializable

data class CreditorAddress(val townName: String, val country: CountryCode)

Postal address of a creditor.

DebtorAccountReference

@Serializable(with = DebtorAccountReferenceSerializer::class)

sealed interface DebtorAccountReference

Reference to a debtor account for the collect-payment service.

DecimalSerializer

object DecimalSerializer : KSerializer<BigDecimal>

Serializes a BigDecimal as a plain JSON string ("-12.34", "1200.00"; never scientific notation), preserving the original number of fractional digits.

Dialog

@Serializable

data class Dialog

User dialog returned by an interactive service call.

DialogContext

@Serializable

enum DialogContext : Enum<DialogContext>

Context of a user dialog, distinguishing what the dialog is asking the user about.

DialogInput

@Serializable(with = DialogInputSerializer::class)

sealed class DialogInput

Data defining the interactive part of a Dialog.

DialogOption

@Serializable

data class DialogOption

Single option inside a DialogInput.Selection.

EncryptedIbanReference

class EncryptedIbanReference(val bytes: ByteArray, val currency: String? = null) : DebtorAccountReference

Reference to a debtor account by encrypted-IBAN ciphertext, for the collect-payment service. Opaque on the client; the ciphertext is produced by the caller's backend with its API secret following the Opaque Data protocol so the frontend never sees the underlying IBAN.

ExchangeRate

@Serializable

data class ExchangeRate

Currency conversion attached to a Transaction.

Fee

@Serializable

data class Fee

Fee attached to a transaction, transfer detail, or batch entry.

HttpResponse

data class HttpResponse : RoutexError

Fallback error carrying the raw HTTP status and response body. Returned by RoutexErrorDispatcher.dispatch when no typed error variant matches; typically when the YAXI service introduces a new error variant ahead of an updated SDK. Display a generic technical-error message; report internally if it recurs.

Image

@Serializable

class Image

Image data for a dialog.

InputContext

@Serializable(with = InputContextSerializer::class)

class InputContext

Opaque context returned alongside a Selection or Field dialog input. Pass it back to one of the respond* methods on RoutexClient together with the user-supplied response to continue the flow.

InputType

@Serializable

enum InputType : Enum<InputType>

Type of an input field. May be used for showing hints or dedicated keyboard layouts and for applying input restrictions or validation.

InternalRoutexApi

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.TYPEALIAS])

@RequiresOptIn(level = RequiresOptIn.Level.ERROR, message = "This is an internal Routex API. External use is unsupported.")

annotation class InternalRoutexApi

Marks declarations that are internal in the Routex client API. Their signatures and semantics may change between releases without warnings and without providing migration aids; external use is unsupported.

InterruptError

@Serializable

data object InterruptError : RoutexError

The service call requires user interaction to complete.

InvalidCredentials

@Serializable

data class InvalidCredentials : RoutexError

The bank rejected the supplied user identifier, password, or TAN input. Show userMessage if present and let the user re-enter their credentials.

InvalidTicketError

class InvalidTicketError(message: String, cause: Throwable? = null) : RuntimeException

Thrown when a raw JWT string is not a valid Routex ticket (bad structure, missing claims, or a service claim that does not match the typed Ticket subclass).

IsoDateTimeOrDate

@Serializable(with = IsoDateTimeOrDateSerializer::class)

sealed class IsoDateTimeOrDate

Date-or-date-time value as used by the transfer service's requestedExecutionDate.

NonInteractiveAccountsRequest

@Serializable

data class NonInteractiveAccountsRequest(val connectionData: ConnectionData, val session: Session? = null, val fields: List<AccountField<*>>, val filter: AccountFilter? = null)

Request body for the non-interactive accounts endpoint.

NonInteractiveBalancesRequest

@Serializable

data class NonInteractiveBalancesRequest(val connectionData: ConnectionData, val session: Session? = null, val accounts: List<AccountReference>)

Request body for the non-interactive balances endpoint.

NonInteractiveResponse

@Serializable

data class NonInteractiveResponse<T>(val result: T, val session: Session? = null, val connectionData: ConnectionData? = null)

Envelope for non-interactive service responses returned by RoutexRefreshClient.

NonInteractiveTransactionsRequest

@Serializable

data class NonInteractiveTransactionsRequest(val connectionData: ConnectionData, val session: Session? = null)

Request body for the non-interactive transactions endpoint.

NotFound

data object NotFound : RoutexError

The requested resource was not found. On transactions this typically means the supplied AccountReference is unknown to the bank: verify the reference. info and trace also raise this.

Party

@Serializable

data class Party

Counterparty (creditor or debtor) referenced by a Transaction.

PaymentErrorCode

@Serializable

enum PaymentErrorCode : Enum<PaymentErrorCode>

Reason why a payment failed.

PaymentFailed

@Serializable

data class PaymentFailed : RoutexError

The bank rejected the payment (for example, an exceeded transfer limit). Show userMessage if present; code carries a machine-readable reason. Specific to collectPayment.

PaymentInitiation

@Serializable

class PaymentInitiation

Payload returned by the collect-payment service.

PaymentProduct

@Serializable

enum PaymentProduct : Enum<PaymentProduct>

Payment product used when initiating a transfer.

PaymentStatus

@Serializable

enum PaymentStatus : Enum<PaymentStatus>

Progress status of a payment initiated via a service.

PeriodOutOfBounds

@Serializable

data class PeriodOutOfBounds : RoutexError

Requested time period falls outside what the bank supports. Show userMessage if present. The transactions flow raises this.

ProviderError

@Serializable

data class ProviderError : RoutexError

The bank reported a technical failure (often maintenance). For payment-style services this does not guarantee the operation failed: the transaction may still have executed. Tell the user a technical error occurred and to retry later.

ProviderErrorCode

@Serializable

enum ProviderErrorCode : Enum<ProviderErrorCode>

Transient condition on the provider side.

Redirect

@Serializable

data class Redirect

User redirect.

RedirectHandle

@Serializable

data class RedirectHandle

Incomplete user redirect.

Response

sealed class Response<T>

Response from a YAXI Open Banking service.

RoutexError

sealed class RoutexError : RuntimeException

Base class for all typed errors returned by the YAXI Open Banking services.

RoutexErrorDispatcher

object RoutexErrorDispatcher

Decodes wire-form error responses from the YAXI service into typed RoutexError subclasses. Falls back to NotFound for HTTP 404 and to HttpResponse for any status whose body the dispatcher cannot recognize as a known variant.

RoutexResult

interface RoutexResult<out T>

Authenticated result wrapper carried in the JWT body's data claim of every service response.

SearchFilter

@Serializable(with = SearchFilterSerializer::class)

sealed class SearchFilter

Predicate applied when searching for service connections.

SecrecyLevel

@Serializable

enum SecrecyLevel : Enum<SecrecyLevel>

Level of secrecy for an input field.

ServiceBlocked

@Serializable

data class ServiceBlocked : RoutexError

The bank blocked the service for this user. Common causes: the user must accept new terms, change their password, or the account itself is blocked. Show userMessage if present; otherwise pick a generic message based on code.

ServiceBlockedCode

@Serializable

enum ServiceBlockedCode : Enum<ServiceBlockedCode>

Reason why a service is blocked for the user.

Session

@Serializable(with = SessionSerializer::class)

class Session

Opaque session token returned by a YAXI Open Banking service call.

SupportedService

@Serializable

enum SupportedService : Enum<SupportedService>

Services an account can be filtered by for potential support.

Ticket

sealed class Ticket

A Routex service ticket. The raw string is a JWT whose data.service claim names the specific service it authenticates; the subclasses pin that service at the type level so the Kotlin compiler rejects passing an Accounts ticket to balances() and vice versa.

TicketError

@Serializable

data class TicketError : RoutexError

The routex service rejected the Ticket. When code is TicketErrorCode.EXPIRED, the user took too long to finish the flow: issue a fresh ticket and start over. Any other code indicates a configuration error in the calling application (wrong key, environment mismatch, ticket / service mismatch).

TicketErrorCode

@Serializable

enum TicketErrorCode : Enum<TicketErrorCode>

Reason why a ticket was rejected.

TraceId

class TraceId

Trace identifier returned by the YAXI Open Banking service for the most recent request, used by support to correlate a client-side failure with server-side traces.

Transaction

@Serializable

data class Transaction

Single transaction returned by the transactions service. Most fields are optional; provider coverage varies and a typical Transaction populates a small subset. The required fields are status and amount.

TransactionsResult

@Serializable

data class TransactionsResult : RoutexResult<List<Transaction>?>

Authenticated result of a successful transactions service call.

TransactionsServiceRequest

@Serializable

data class TransactionsServiceRequest(val credentials: Credentials, val session: Session? = null, val recurringConsents: Boolean = false)

Request body for the interactive transactions service.

TransactionStatus

@Serializable

enum TransactionStatus : Enum<TransactionStatus>

Status of a single Transaction.

Transfer

@Serializable

data class Transfer

Payload returned by the transfer service.

TransferDetails

@Serializable

data class TransferDetails @JvmOverloads constructor(val amount: Amount, val creditorAccount: AccountIdentifier, val creditorName: String, val endToEndIdentification: String? = null, val creditorAgentBic: String? = null, val creditorAddress: CreditorAddress? = null, val remittance: String? = null, val chargeBearer: ChargeBearer? = null)

Details of a single credit transfer inside a TransferServiceRequest.

TransferResult

@Serializable

data class TransferResult : RoutexResult<Transfer>

Authenticated result of a successful transfer service call.

TransferServiceRequest

@Serializable

data class TransferServiceRequest(val credentials: Credentials, val session: Session? = null, val recurringConsents: Boolean = false, val product: PaymentProduct, val debtorAccount: AccountReference? = null, val debtorName: String? = null, val requestedExecutionDate: IsoDateTimeOrDate? = null, val details: List<TransferDetails>)

Request body for the interactive transfer service.

Unauthorized

@Serializable

data class Unauthorized : RoutexError

The bank refused the recurring consent attached to the call's ConnectionData. The YAXI service raises this only when the call carries Credentials.connectionData. Restart the flow without Credentials.connectionData so the user can grant a fresh consent.

UnexpectedError

@Serializable

data class UnexpectedError : RoutexError

The bank or another upstream returned a response YAXI could not process. For payment-style services this does not guarantee the operation failed: the transaction may still have executed. Show userMessage if present, then consider prompting the user to share a diagnostics archive with YAXI.

UnexpectedValue

@Serializable

data class UnexpectedValue : RoutexError

A value passed to the call was malformed (for example, an invalid IBAN). The error field explains what was wrong. This error targets the application developer: validate inputs before submitting them, especially when they came from the user.

UnsupportedProduct

@Serializable

data class UnsupportedProduct : RoutexError

The bank cannot perform the requested operation for this combination of inputs. Examples: an instant payment was requested but the bank only supports the standard variant, or the connection does not support the chosen service. See Instant by default. Show userMessage if present.

UnsupportedProductReason

@Serializable

enum UnsupportedProductReason : Enum<UnsupportedProductReason>

Reason why a payment product is not supported for a given request.