Wallet Accounting Structure
This section describes the CoreWallet accounting concepts and structure.
Accounting concept
The figure above shows the general wallet/accounting concept.
Subsidiary
Represents a main legal entity to which wallets belong. All accounting transfers are inside a single subsidiary, thus each subsidiary is considered an isolated accounting scope. As such, each subsidiary has its own set of system-accounts, VAT definitions, etc.
Wallet
Represents the main wallet entity, which can have zero or more WalletAccounts. One or more users may have access to the wallet. Since it's only a container for WalletAccounts, it has no balance or currency, other than the aggregated balances of all owned WalletAccounts.
Must belong to exactly one Subsidiary.
WalletAccount
Represents the main account entity visible to the user, in a single currency. Has zero or more Transactions that modify the account-balance. Has zero or more WalletAccountItems, that represent activity on the WalletAccount, that may or may not influence the balance.
Is the owner of one or more AccountingAccounts that actually represent the financial state of the WalletAccount.
WalletAccountItem
Represents a visible activity on the WalletAccount for the user. Can be considered a line on the account-statement, is always in the WalletAccount-currency. However, a WalletAccountItem does not need to have financial effect, e.g. it can represent in 'pending' Payment, which has not yet been processed. Usually belongs to a Transaction. Contains currency-exchange information in case of a multi-currency Transaction.
Transaction
Represents a wallet-process, such as an Invoice, Purchase, P2P-transfer, Payment, Trade. Belongs to a WalletAccount, has zero or more WalletAccountItems depending on the process. May be in a different currency than the WalletAccount-currency, in that case currency-exchange is applied.
Is the owner of zero or more Transfers.
AccountingAccount
Represents a simple financial account in a single currency. Contains AccountItems which make up the account balance. Can be source or target for Transfers.
AccountItem
Represents a credit or debit amount of money on an AccountingAccount. Contains account-balance and turn-over at the time of the account-item for historical purposes, which is set by an asynchronous job (thus has some delay).
Transfer
Represents a transfer between two AccountingAccounts, with a debit and credit AccountItem. The TransferType determines, among other things, how the transfer affects the TurnOver of the debit and credit account, e.g. None, Increase, Decrease.
Account Balance
The account-balance is the amount of money currently 'in' the account, which can be negative or positive. It is the sum of all account-items that belong to the account.
For performance-reasons, we cache the aggregated account-balance (otherwise the account-balance-calculation would get less efficient with increasing numbers of account-items).
The account-balance at a given point in time is determined by examining the latest account-item before that time.
Account TurnOver
The account-turnover is a value calculated based on business rules and account-items. In general it is an ever-increasing number, but some transfers may also decrease the turn-over of an account, for example a purchase-cancellation.
The transfer-type determines how an account-item affects the turn-over of an account, e.g. not at all (None), increasing it (Increase) or decreasing it (Decrease).
Which transfer-types are used in what situation is purely a product definition.
Typically the turn-over is used to limit account-activity for a customer, e.g. by limiting the amount of money that can be loaded into the wallet using payments/merchant-credits/…
The turn-over in a given period is calculated by subtracting the turn-over at t0 from the turn-over at t1.
Technical overview
The diagram above shows the general technical concept. There are various management services for the Wallet, WalletAccount and Transactions (e.g. Invoice, Purchase, Payment), which implement the workflows and actions for the respective items (e.g. create wallet, create invoice, confirm invoice, cancel invoice, get account balance). These services have no idea about the accounting-representation or consequences of their actions.
Every significant action is reported to the respective AccountingHandler, which provides the logic towards the accounting-component. Each AccountingHandler uses the WalletTransferService to perform accounting actions, such as get/create an account, or transfer an amount between accounts. The WalletTransferService uses a WalletAccountingConfiguration to determine which account/transfer types apply at what event. E.g. it determines which AccountingAccounts are created when a WalletAccount is created, and it determines which of those accounts are used to calculate the WalletAccount balance.
In addition, the AccountingHandler is responsible for creating and updating WalletAccountItems for specific events.
Account types
The system contains multiple account types for AccountingAccounts:
- System accounts (per subsidiary)
- Expense / Income accounts
- VAT accounts
- Currency exchange accounts
- Inter-subsidiary accounts (aggregation accounts for transfers between subsidiaries)
- Payment method accounts (e.g. for a specific payment contract)
- Wallet accounts (per WalletAccount)
- Main accounts (unrestricted available balance)
- Restricted accounts (e.g. bound to specific MCC codes)
- Reserve accounts (e.g. for escrow, reservations, ...)
- Deposit accounts (for Deposit wallet-accounts)
- Loyalty accounts (for LoyaltyProgram/Member wallet-accounts)
- Payment instrument accounts (e.g. for a specific bank account or card)
- Main account