API

The CoreWallet provides a stateless, RESTful API, and uses HTTP headers for authentication, thus mitigating session-based and CSRF-attacks, and simplifying horizontal scaling and system upgrades without downtime.

A Swagger UI based API test client is automatically generated for easy testing during development (can be disabled per deployment), and provides a special AdminAPI for internal processes (can be disabled per deployment).

The transaction API-calls follow a 'create/confirm' pattern, ensuring idempotency of the API calls for transactions, and mitigating CSRF-attacks.

AdminUI

The AdminUI is a user-interface where the Client can manage the Product. The AdminUI uses the AdminAPI, and provides functionality to view, modify and review user data (KYC-process), view wallets/accounts/transactions, lock/unlock wallets/accounts, configure payment business contracts and routings, manage unmatched payments, etc.

The AdminUI has to be extended and customized for features built specifically in the Product.

Wallet

The Wallet is the main component, and supports both Full and Guest wallets. A Wallet can have one or more WalletAccounts, each in a given currency for a given purpose (e.g. regular emoney, loyalty points, shop, safeguard-deposits, …). A WalletAccount can contain multiple emoney-types based on category-code (e.g. unrestricted, restricted-gambling, …) and emoney-usability must be defined per transaction-type.

Invoices can be used to credit or debit a certain WalletAccount from/to a system-account.

Purchase is used in typical merchant-with-shop setup, which also provides a billing/settlement feature for the purchase transactions.

Funding/withdrawal is used to top-up or withdraw from a WalletAccount, resulting from or in a payment-transaction at a PSP through the Payment-module. A Funding/Withdrawal typically references PaymentInstrument (e.g. a bank account or credit-card) that the payment was/will be made with. A payment-approval-process can be configured to require admin-approval for payments with certain preconditions (typically for larger withdrawals).

P2P transactions are voucher-based transactions between WalletAccounts.

Unmatched-payments result when incoming/outgoing payments in the payment-module cannot be automatically matched to a specific Wallet. These have to be resolved manually via the AdminUI.

The payment-matching process matches incoming payment events from the payment-module to a specific Wallet. If no match could be made, it results in an UnmatchedPayment which has to be resolved manually in the AdminUI. The matching logic must be provided in the Product as it strongly depends on the integrated PSPs.

The CoreWallet allows to define fine-granular limits for different business processes, such as failed-logins or funding/withdrawal. The limits apply in a specific context (business process, user KYC level, country, currency, …) and may block a certain business process.

The CoreWallet allows to define fees for certain business processes, which apply in a specific context (business process, user KYC level, country, currency, …).

The CoreWallet supports Merchant Wallets with Shop WalletAccounts to provide the basis for a traditional Merchant/Consumer purchase process.

The CoreWallet requires authentication for each individual API call. There are typical login-based authentications which require a password, and API-based authentications which require no password (typically for API-based integrations for Shops). Each authentication belongs to a User (or Shop), which defines the roles. Each API call ensures that the current caller has access to the requested entity based on its role and ownership. This prevents users accessing data from other users.

The authentication-module may need to be extended for LDAP-integration, and already supports a product-specific role model, which has to be implemented in the Product.

The authentication-module supports 2-factor-authentication mechanisms, but the actual 2-factor implementation (e.g. Google Authenticator) must be implemented in the Product. The 2-factor can be configured as required for certain API calls (e.g. login, or confirming a withdrawal).

Each Wallet can be annotated with admin-comments, which can be seen in the AdminUI. These annotations are also created for significant events, e.g. failed logins, lock/unlock actions, etc.

The CoreWallet supports multiple Subsidiaries, which have their own set of accounts, configurations, etc. Some configurations are global (such as the currency-configuration, account-type configuration), and it can be configured which transactions are allowed between which subsidiaries (which are booked via inter-subsidiary-accounts). In the registration process there is a default mapping between user-country and subsidiary, which can be customized in the Product to be based on additional input or context data.

The CoreWallet supports management for generated files in a Wallet context, e.g. account-statements or transaction exports, which can be downloaded via the API. Actual file generation is product-specific and must be implemented in the Product.

User

The User module provides the user core-data-management, such as name, email addresses, phone numbers, addresses, user-identifiers (typically email-address), and verification processes for that data, to allow for a configurable KYC process. Product-specific user data normalization and validation services can be easily integrated within the user module.

The KYC process is configurable in the Product, for which the KYC-levels and transitions between the KYC-levels must be defined and configured. A User can upload files for the KYC-process, which can then be verified or rejected in the AdminUI, and may verify certain user data such as name, address, date-of-birth. Based on the KYC-level it can be configured which actions are allowed.

The User-module provides the email-infrastructure to send emails which are triggered in the various business processes in the Wallet. CoreWallet comes with standard Twilio (https://www.twilio.com/) and SureSMS (https://www.suresms.com/en/) integrations that both can be used out-of-the-box. SMS templating or other means of sending is product-specific and must be implemented in the Product.

The User-module provides the SMS-infrastructure to send SMS-es which are triggered in the various business processes in the Wallet. CoreWallet comes with a standard Twilio (https://www.twilio.com/) integration that can be used out-of-the-box. SMS templating or other means of sending is product-specific and must be implemented in the Product.

Payment

The payment module provides the abstraction for PSP-integrations without knowing about Wallets, WalletAccounts, etc. For each PSP-integration a BusinessContract can be configured, and the preconditions when it can be used (Routings), such as business process, country, currency, user KYC level, etc.

A PaymentSession is used in preparation of a single PaymentTransaction, typically in a Purchase, Funding or Withdrawal business process. The PaymentSession contains all available and usable payment-options, from which the user can select one to be used with the transaction.

PaymentTransactions represent outgoing payments that are sent to a PSP, or incoming payments received from a PSP.

The BusinessContracts and Routings can be managed via the AdminUI, allowing for flexible and immediate configuration of usable payment options.

Actual PSP integrations are product-specific, and must be implemented in the Product, so that the payment-module can use them. These integrations can be anything from actual PSPs, to SEPA-file-processors or crypto-coin-daemons. The CoreWallet only provides the extension point for these integrations, not the actual implementations.

Accounting

The accounting module provides the abstraction for managing accounts with credits/debits and an account-balance, without knowing about Wallets, WalletAccounts, etc. The balance calculation is always efficient and accurate (but may depend on database transaction isolation and locking), transfers are always atomic, and business processes can define a 'minimum-remaining-balance' as precondition for a transfer.

The accounts form a closed set per subsidiary: the sum of all account balances is always 0.

The account item binding process is used to be able to efficiently query which debits were paid with which credits in a single accounting-account.

Any integration with or export to an external accounting system must be implemented in the Product.

4-eyes principle

The CoreWallet supports a configurable generic 4-eyes-principle feature for AdminAPIs. This ensures that all non-read-only AdminAPI calls require approval by another Admin-user before they are executed.

For more details, please see the detail page for the generic 4-eyes-principle.

General

The CoreWallet provides a Configuration-service that allows certain system-behaviors to be configured and updated at runtime, currently used mainly to fine-tune batch-sizes and delays for jobs. Can be used to toggle features/behavior as well.

The SystemNotification-publisher collects events generated in CoreWallet, and publishes them into a channel (currently, a dedicated log-file). These events can then be consumed by e.g. an ELK-setup (ElasticSearch, LogStash, Kibana) to allow for detailed system monitoring and insight. The events can be of a technical or business nature.

The internal service monitoring collects statistics about CoreWallet API calls and service-methods regarding count and duration and automatically emits log-entries when thresholds are exceeded. This allows for detailed system monitoring and optimization.

The CoreWallet provides a timestamp-synchronization mechanism to ensure the timestamps in a single API call are all identical, to prevent issues where multiple entities are created in the database at different timestamps, especially at day/month/year boundaries.

The CoreWallet provides PublicIDs and DisplayIDs in public API entities, to obfuscate internal database IDs, so that we prevent exposing information regarding the number of entities in the system. Each PublicID contains a checksum to prevent guessing IDs.