Accounting Model
Basic Entities
Account
Also can be named as Wallet or in-system account – is a container that stores value, in more common words – an account or a wallet (for digital wallet systems). In SDK.finance we have different types of accounts which can be of different levels (system, gate, client etc) and of different types. In the code this entity is named as “coin”.
Account Levels
System – accounts that are used for general system purposes
Gate – accounts that participate in gate transactions (like top-up/withdraw via Provider)
Issuer – a level of accounts used to issue electronic money and balance its circulation
Client – accounts of individuals and merchants, involved in circulation.
Account Usage
There are two categories of accounts depending on their usage. Some are used for CIRCULATION and some for ACCOUNTING purposes.
This is the attribute common for all the accounts. Its main purpose is to provide understanding about the balances of what accounts are INSIDE the Circulation (e.g. are accounted for by calculation of circulation), and which are OUTSIDE the Circulation (not accounted for by calculation).
Circulation is the total amount of money inside the system e.g. on all the clients’ accounts (wallets). The amount of money in circulation should be equal to the money on the company’s bank account, which represents issued electronic money, to guarantee that the funds of clients inside the system are safe and covered with real money.
Account Types
Each type of account can be technical and not technical (technical: TRUE/FALSE). Technical accounts are temporary containers for technical operations, which have a limited life cycle according to the Business Process flow.
| Type | Description | Level | Usage | Collector |
| issuer | Money which was issued in the system (circulation). | issuer | circulation | n/a |
| technical_transit | Technical transit account. After completion of the business process the balance of this account must be 0 | system | circulation* | n/a |
| technical_transit | Technical transit account. After completion of the business process the balance of this account must be 0 | system | accounting* | n/a |
| regular_system_ commission | System commission from regular users such as individuals for the internal operation (e.g. transfer, top up via bank etc.), which are included in the circulation | system | circulation | system |
| business_system_ commission | System commission from business users such as merchants for the internal operation (e.g. transfer, top up via bank, etc.), which are included in the circulation | system | circulation | system |
| regular_system_commission | System commission from regular users such as individuals for the internal operation (e.g. transfer, top up via bank etc.), which are not included in the circulation | system | accounting | system |
| business_system_ commission | System commission from business users such as merchants for the internal operation (e.g. transfer, top up via bank, etc.), which are not included in the circulation | system | accounting | system |
| issuing_balance | Ledger account, is used to calculate the in-system circulation volume. Issuing balance (GLOBAL) is one general account for accounting all the balances in the same currencies of different Issuers. | system | accounting | n/a |
| regular_gate_commission | Calculated commission for specified provider accounts and specific commission collectors for Individuals for the external operation (e.g. Top up via provider, Withdrawal via provider). External operation means that any 3rd party takes part in the operation processing and commission should be paid to the 3rd party. | gate | accounting | Provider, system |
| business_gate_commission | Is used for calculations of commission for specified provider accounts and specific commission collector for Merchant. For the external operation (e.g. Top up via provider, Withdrawal via provider) | gate | accounting | Provider, system |
| client | A general type of accounts owned by end users (Individual, Merchant) | client | circulation | n/a |
| gate | Gate balance account. | gate | accounting | n/a |
| reserve | Money which is being transferred from one cash desk to another | system | circulation | n/a |
| cash | Cash desk account | cash desk | accounting | n/a |
| prepaid | Prepaid account can be accessed by serial and pin (voucher coin) | client | circulation | n/a |
| cashback_payer (is not used) | the merchant obligation before the payers to pay cashback, the funds from this coin are sent to payer client coin at the end of the month | client | circulation | n/a |
| cashback_merchant (is not used) | the obligation to pay cashback for merchant who accept payment, the funds on this account are sent to payer client coin (also to the commission coin) at the end of the month | client | circulation | n/a |
*balance of the technical account must be 0 after completion of business process
Business Process
Business process is an end-to-end operation from the business perspective, like Account top-up, Payment from account or Transfer between accounts. Each business process can contain a set of atomic transactions to represent accounting. For example, Account top-up can have up to 8 Transactions: several funds holds, accounting transfers, hold captures etc. Business processes are shown in the transaction history for end users.
There are a number of basic Business Processes in the system. They meet the basic functions such as performing operations via providers (gates), bank, and system operations (e.g. Top up, Withdraw, Transfer).
But of course, they cannot cover all the needs of a particular business. If the pre-installed business processes don’t meet your business goals, you may want to add a new business process and the business logic to work with it.
Having access to the source code your developers can add a custom business process based on an existing one or add any additional transactions for accounting to the existing business processes.
Business Request
BusinessRequest is a part of the business process allowing BusinessProcess to become more flexible in case of status transition flow. Business request is used when we have several business process flows depending on external decisions, like compliance approval or interaction with 3rd parties. For example, BusinessProcess can be in pending status, while its BusinessRequest can have either pending, requires_confirmation, approved_by_accountant etc. This allows us to create more complex business processes that depend on some event or a trigger.
Flow
Determines the rules for a Business Process. Includes information about the business process type and in case of complex business processes – related processes, contract type, accounts involved etc.
Contract
Determines the rules of collecting the fees and commissions from and specifying limits for each type of operation available for a Client. More about contracts here.
Transaction
Transaction in SDK.finance is an atomic operation with 1 or 2 accounts of the same Issuer. It has no status or flow, because it is persisted within a single database transaction.
The main idea is that all of the transactions (including technical) are stored in the transaction history in the database and then they can be extracted in the form of reports or represented on the dashboards, to create special reports for regulators etc.
On the atomic level of the system there are the following transaction types:
Transaction types
| Type | Description |
| issue | means that the system creates a technical account and adds the value on this certain account. These funds are just being recorded on the technical account first with their further transfer (merge) to another account (destination account). |
| merge | transfer all funds from the technical source account to destination account and delete source account; |
| transfer | simple funds transfer from source account to destination account; |
| split | is a transaction of issuing the destination account and further transfer from the source account; |
| redeem | Withdrawal of funds from the source account; |
| commission | funds transfer from the source account to the destination account, where destination account is a commission one; |
| authorization | hold funds for transfer from source account to destination account, where destination account may be absent; |
| commission_authorization | hold funds for transfer from source account to destination account , where destination account is a commission one; |
| capture | capture (remove hold and perform transfer) funds held by authorization transaction; |
| commission_capture | capture funds held by commission_authorization transaction; |
| reversal | remove hold created by authorization transaction; |
| commission_reversal | remove hold created by commission_authorization transaction; |
EXAMPLE 1: Transfer
To understand how the accounting works let’s use an example of a basic simple Business Process such as Transfer where Client 1 transfers funds from his in-system account to the in-system account of Client 2.
Assume, that Client 1 belongs to an organisation type “Standard” with a predefined set of Contract rules:
| Contract settings: | Direction | ||
| Operation “Transfer” | active | ||
| System commission | 3% | OUT | Initial operation amount does not include commission amount, commission is added to the initial amount |
| Calculations | |||
| Transfer amount | 1000 | ||
| Funds withdrawn from Client 1 Wallet | 1030 | ||
| System commission amount | 30 | ||
| Funds to be added to Client 2 Wallet | 1000 |
In this case, we have a very simple Business Process between three coins: Client 1 (organisation type: individual), Client 2 (organisation type.individual), regular_commission (organisation type: system). This operation does not affect the Circulation amount because money is already in the client’s in-system account and they were issued in circulation earlier (via one of the possible operations of funding the client’s account from an external source). Money remains inside the system.
EXAMPLE 2: Top-up via Bank
A more complex example of a Business Process that increases the Circulation amount is a Wallet top-up. A Top-up via Bank operation is not considered to be a gate operation because money comes to the bank Account of the company and the accountant can simply check the bank statements to see which wallet should be topped-up. This process can be automated by integration with your Bank when, for example, the SDK.finance system will call the Bank’s APIs and check for new transactions from clients.
Contract settings for this operation are:
| Contract settings: | Direction | ||
| Operation | Top-up via Bank | ||
| System commission | 4% | OUT | Commission is added to the initial amount |
| Calculations | |||
| Top-up amount | 1000 | ||
| Amount to debit from Bank account | 1040 | ||
| Amount of Client`s Wallet top-up | 1000 | ||
| System commission | 40 | ||
| Issued amount | 1000 | Amount of the money issued into the system circulation |
- Systems Issues digital money on a temporary technical account.
- Funds were merged on the general (non technical) transit account and technical account was deleted.
- System Transfers the commission to the dedicated regular_commission account.
- System Transfers 1000 to the Issuer account – increasing the circulation volume.
- At the same time Systems performs Issue operation on the temporary issuing_balance account.
- Funds are merged on the general (Global) issuing_balance account for accounting purposes (outside the circulation).
- Funds, added to the circulation, are transferred from the Issuer account to the Account of Client.
In this case, after execution of the top-up operation, the volume of funds in Circulation has been increased by 1000.
EXAMPLE 3: Top-up via Provider
A more complex Business process of Wallet top-up is Top-up via provider, where provider has its own commission for the operation.
| Contract settings: | Direction/Rule | ||
| Operation | Top-up via Provider | ||
| Provider commission | 1% | OUT | |
| Total commission | 5% | OUT | |
| Calculations | |||
| Top-up amount | 1000 | ||
| Amount to debit from Card | 1050 | Amount sent to provider to process card debit transaction | |
| Amount to top-up wallet (net amount) | 1000 | ||
| Commission taken from customer | 50 | ||
| Provider commission | 10.5 | Provider commission is calculated from the amount sent to provider | |
| System commission | 39.5 | ||
| Settlement amount received from provider | 1039.5 | Provider commission is deducted from the settlement amount and system receives Amount sent to provider minus Provider commission | |
| Issued amount | 1000 | Amount of the money issued into the system circulation |
- System issues digital money on a temporary technical gate account.
- Funds are merged on the general gate account (not technical)
- From the gate account system transfers system commission to the system commission account (regular_gate_commission), where the collector is System.
- At the same time, the system issued the amount of provider’s commission on temporary technical regular_gate_commission.
- Funds are merged on the general regular_gate_commission account where the collector is Provider.
- Systems performs Issue operation on the temporary issuing_balance account.
- Funds were merged on the general (Global) issuing_balance account for accounting purposes (outside the circulation).
- System Transfers 1000 to the Issuer account increasing the circulation volume.
- Funds added to the circulation are transferred from the Issuer account to the Account of Client. .