Accounts

Accounts are the resources against which financial transactions are recorded.

An account belongs to a ledger, has an associated currency, and maintains balances representing its financial position.

Understanding accounts

An account provides a structured representation of financial value.

Depending on the application, accounts may represent customer balances, operational funds, clearing positions, fees, or other accounting categories.

Ledger
├── Customer Account
│   └── EUR
├── Treasury Account
│   └── EUR
├── Clearing Account
│   └── EUR
└── Fee Account
    └── EUR

These are illustrative account roles rather than mandatory account types.

Account properties

The core accounting model includes the following account fields.

Property	Description
`id`	Unique account identifier
`ledger_id`	Associated ledger identifier
`currency`	Account currency
`currency_exponent`	Decimal exponent for interpreting amounts
`status`	Account status
`available_balance`	Available balance in minor units
`pending_balance`	Pending balance in minor units
`metadata`	Additional account information
`created_at`	Account creation timestamp

Some deployments include provider-related identifiers and additional metadata.

Account currency

Each account has an associated currency.

Examples include:

EUR — Euro
GBP — British pound
USD — United States dollar

The currency exponent determines how integer monetary values are interpreted.

For example, an EUR account with an exponent of 2 interprets 12500 minor units as EUR 125.00.

Account status

The core account model uses ACTIVE for active accounts.

Other lifecycle values should only be relied upon where they are explicitly supported by the relevant API contract.

Account metadata

Metadata allows applications to associate additional information with an account.

Depending on the integration, metadata may contain internal references, account classifications, provider mappings, or business-specific information.

Applications should not store passwords, API secrets, or other sensitive credentials in general-purpose metadata.

Accounts and transactions

Accounts participate in transactions through accounting entries.

For example, a transfer of EUR 50.00 from Account A to Account B produces corresponding debit and credit effects.

Transaction: Transfer EUR 50.00

Account A
  Debit:  5000 minor units

Account B
  Credit: 5000 minor units

The ledger maintains the transaction and its entries as related financial records.

Account balances

Accounts maintain two core balance fields:

Available balance

Represents the amount available according to the core ledger's balance rules.

Pending balance

Represents the pending balance tracked by the core ledger.

Applications must interpret these fields according to transaction status and posting rules rather than assuming that all pending transactions affect balances identically.

Provider-linked accounts

Infrarails can associate internal financial accounts with external provider identifiers.

Provider-related metadata may include:

Provider name.
Provider account identifier.
Provider balance identifier.
Provider user identifier.
External account information.

These associations support integration and reconciliation workflows.

An internal ledger account and an externally maintained provider account are distinct resources, even when linked.

Best practices

Use the correct ledger identifier when referencing an account.
Validate account currency before creating transactions.
Interpret balances using the account's currency exponent.
Avoid using floating-point arithmetic for monetary calculations.
Keep provider identifiers separate from core account identifiers.
Use the ledger transaction system for financial movements rather than directly modifying balance values.
Preserve sufficient account and transaction history for reconciliation.

Next steps

Continue with Balances to understand monetary representation and balance management.