CoreExchange Structure / Wallet Entities
Represents the system´s legal entity that is the legal contract partner for every user. It has its own (closed) set of accounting accounts, and is the basis for most configurations.
Represents a customer legal entity that is the legal contract partner for a subsidiary. A user can have properties (such as name/address), may have identifiers (such as email address or telephone number used for login/identification) and authentication data (e.g. password or API credentials, and security roles). A user is the owner of a wallet. The user has a verification level corresponding to the KYC process he/she has undergone.
Represents the link between a subsidiary and a user, and is a container for wallet accounts and payment instruments.
Represents a single account in a wallet with a single currency and a defined purpose, depending on the wallet account type. Typically at least one wallet account exists in a wallet, or multiple in case the wallet should support multiple currencies. A wallet account can store emoney, and its functions depend on the accounting and transaction configuration in the system.
Wallet Account Item
Represents an activity on a wallet account, that may or may not influence the wallet account balance. The wallet account items form the account statement. Typically each transaction has one or more wallet account items. The wallet account item aggregates all accounting transfers that may be required for a transaction event.
Represents a bank account, credit card or crypto wallet that is used to deposit funds at or to withdraw them from a wallet account.
Is the generic type for any entity/process that influences the wallet account balance, such as a trade, a payment or an invoice.
A transaction always references one or more wallet accounts, and may have any number of wallet account items.
Is the account in the accounting component, that stores emoney of a given type for a wallet account. A wallet account can have multiple emoney accounts, e.g. for different emoney types (unrestricted, or MCC code restricted, reserved, frozen).
Stateless RESTful API
CoreExchange 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.
The transaction API calls follow a “create/confirm” pattern, ensuring idempotency of the API calls for transactions, and mitigating CSRF attacks.
Generated Swagger API Test Client
An API test client is automatically generated for easy testing and provides a special AdminAPI for internal processes (both can be disabled per deployment).
Public API for High-Frequency Traders
The CoreExchange public API allows trading bots and high-frequency traders to process high volumes of trades. Usage requires secure authentication. More on authentication methods can be found in chapter: 4.7.2
Trading Engine & Management
CoreExchange comes with a state-of-the-art, high-performance trading engine that is also highly customizable to meet your business needs.
The trading process in CoreExchange is event-based to ensure high performance of the trading engine. The events are processed based on their timestamp. This applies for both creating and cancelling orders.
Order Book Processes
The CoreExchange order book supports multiple algorithms to determine the correct market price.
- Highest or lowest price
- Average price
- Oldest order item
The algorithm is set whenever a new trading pair (market) is created and is one of the market properties. Orders are always processed in a fair (timestamp) and deterministic (sequential) manner.
CoreExchange comes with a highly flexible configuration of markets (trading pairs), allowing you to configure the following parameters:
- Price calculation algorithm
- Dynamic price adjustment
- Price granularity
- Price range amount
- Price range ratio
- Split orders
- Minimum deal amount
CoreExchange supports the following order types for traders.
A market order is a buy or sell order that is executed immediately at the best currently available market price.
A limit order is a buy or sell order that is executed at a pre-set price or higher. A buy limit order can only be executed at the limit price or lower, and a sell limit order can only be executed at the limit price or higher. Limit orders are not guaranteed to be executed.
CoreExchange supports configurable market maker and taker fees. Each party (user) involved in a trade is charged a predefined fee. This amount can also vary, depending on the customer´s KYC level, country, currency and other parameters.
We provide a thorough documentation of the CoreExchange trading engine and markets incl. detailed description for each individual parameter to help you configure it.
The CoreExchange Admin UI is the back office tool for your customer support, IT and finance departments. It provides tools for a wide array of business operations, all based on a “read only” and a “read/write” role access model.
In the customer management section you can access all user accounts registered with your CoreExchange product. A search mask helps you to quickly filter those by name, email, nation code etc.
Here you can also:
- See all customer data provided upon registration
- Review (accept/reject) documents uploaded by customer
- Update customer verification (KYC) level
- Upload internal corresponding documents
- Access wallet audit trail (wallet notifications)
- See all addresses linked to the account
- See all payment instruments linked to the account
- See all wallet accounts linked to the account
- See full transaction history for each wallet account
- See the actual balance for each wallet account
- Lock wallets individually
- Lock wallet accounts individually
- Lock payment instruments individually
- Set users on a suspicious activity watchlist
KYC Process (document upload)
KYC processes usually require to review official documents that the customer has to provide. Admin UI allows you to review these documents on a per account basis and verify the customer data individually. Documents can also be rejected if they do not meet the necessary criteria.
A rejection will trigger an email notification to the customer giving an explanation as to why the document was rejected (if provided by the reviewer).
The exact KYC levels and transitions between those must be defined and configured in CoreExchange to meet national regulatory and AML requirements.
The payment management section is where you will find an overview of all incoming and outgoing funds of your CoreExchange product including a set of tools for efficient administration of payments.
Every time a chargeback happens the corresponding payment will appear here for you to be retriggered or challenged with the customer.
For outgoing payments, we allow you to manually approve/decline the transfer as a security measure. This feature is configurable based on the amount to be withdrawn and can be disabled completely if not required.
Whenever the CoreExchange payments engine can not match an incoming transfer to a corresponding user wallet account (due to missing or mistyped subject ID), that payment is queued in a pool of unmatched payments, waiting to be assigned manually to the correct user wallet account, or booked out of the system.
Business contracts serve as the logical and technical configuration layer for all transfers to and from CoreExchange.
For FIAT currencies business contracts contain the configuration of your payment services provider or bank, as well as alternative payment method contracts to allow fundings and withdrawals in FIAT currencies.
For cryptocurrencies they serve as a mechanism to easily disable a certain currency and stop all withdrawals if needed (in that particular currency).
Example: If your second-choice Acquirer/PSP is cheaper in a specific country or for a specific transaction type than your usual PSP, you can configure CoreExchange to route all concerned transactions through that specific PSP and save costs.
BIN ranges allow you to group and route certain BIN ranges (credit card) through a specific business contract.
All FIAT currencies are supported but require business contract configurations and integration of corresponding payment methods for deposits and withdrawals. CoreExchange provides a SEPA/MT940 gateway as the default, built-in bank transfer payment method for fundings and withdrawals.
On the cryptocurrency side, CoreExchange supports by default:
- Bitcoin (XBT)
- Ethereum (ETH)
- ERC20 Tokens
- Litecoin (LTC)
- Dogecoin (DOGE)
Supported ERC20 Tokens are configurable through the Admin UI. We provide comprehensive documentation, covering all steps involved to enable you to introduce new tokens easily.
CoreExchange allows you to define fine-grained limits for different business processes, such as trading, funding or withdrawal. The limits also become effective in regard to specific contexts, such as business process, user KYC level, country, currency and many more. Limit violations may also block certain business processes.
Fees can be configured for certain business processes, and can apply in a specific context e.g. business process, user´s KYC level, country, currency and so on.
VAT definitions can be applied on a per country basis.
Orders & Deals
This section of the Admin UI gives you a full overview of all orders created and deals closed (executed orders), along with all necessary information, e.g.:
- Order type
- Order status
- Total amount sold and bought (also for partially cleared orders)
Each listed deal is linked to the corresponding buyer and seller wallet and wallet account for easy access. You can also filter the list by orders or deals of a specific user.
The Wallet is the main component of the CoreExchange accounting backend. A Wallet can have one or more wallet accounts, each in a given currency (FIAT or Crypto).
Upon registration, a wallet is created for each customer, along with corresponding wallet accounts for each supported FIAT currency.
For cryptocurrencies wallet accounts are created on demand and require customer interaction on the deposit page.
Wallet Account Management
Support of Multiple Emoney Types
A Wallet can have one or more wallet accounts, each in a given currency for a given purpose (e.g. regular FIAT/crypto emoney,
loyalty points, safeguard deposits).
A Wallet Account can contain multiple emoney types based on a category code (e.g. unrestricted, restricted trading, etc.)
The emoney utility must be defined per transaction type.
CoreExchange supports the following transaction types:
Invoices can be used to credit or debit a certain wallet account to/from a system wallet. This is mainly done to correct bookings.
Funding / Withdrawal
Funding/withdrawal is used to top up a wallet account or withdraw funds from it, resulting in a payment transaction at a PSP through the payment module.
A funding/withdrawal process typically references the payment instrument (e.g. a bank account or cryptocurrency wallet) that the payment was/will be completed with. A payment approval process can be configured to require admin approval for outgoing payments with certain preconditions (typically for larger withdrawals).
P2P transactions are voucher-based transactions between wallet accounts of different users. At the withdrawal stage, a user can generate a voucher code with any given amount, provided it does not violate his current limits. The corresponding funds are then reserved until the voucher is redeemed by another user (which leads to a funding on his account) or cancelled by its issuer. Vouchers are available for both, crypto and FIAT currencies.
Vouchers can also be generated from a System Account and distributed to customers in the means of a marketing campaign or good will gesture.
Whenever the CoreExchange payments engine can not match an incoming transfer to a corresponding user wallet account (e.g. due to missing or mistyped subject ID), this payment is queued in a pool of unmatched payments, waiting to be assigned manually to the correct user wallet account.
CoreExchange generates an audit trail for all significant events, e.g. failed logins, changes to KYC levels or other user core data, creation and verification of payment instruments, locking/unlocking account actions and so on.
In addition, each wallet can be annotated with admin comments that can only be seen by the staff via the Admin UI and are for internal purposes only.
Both lead to an auditable history of events that helps you or one of your employees to reconstruct what happened to the wallet in question and ultimately also the user in the past.
Authentication & Security
In order to secure user funds from being illicitly withdrawn and to prevent unauthorized account access in general, CoreExchange allows to set two-factor authentication at the login and withdrawal level. If set, the customer will be asked to provide a randomly generated 6-digit code (e.g. via the Google Authenticator or Authy app on a user’s mobile device) before the request is authorized.
A number of recovery codes will be displayed to the customer upon setup and can be used to disable two-factor-authentication in case the device is broken, lost or stolen.
CoreExchange validates the authentication on each API request. Two types of authentication processes are possible.
UI authentication: typically used by the CoreExchange consumer and Admin UIs, meaning the user has to login with his/her credentials to authenticate himself. A logout invalidates the UI authentication.
API authentication: This authentication is represented by a token which has to be passed in a HTTP header on each API request. Only a logged-in user is able to create one or multiple API authentication tokens. The API authentication can only access a subset of public APIs and is typically used by trading bots. The API authentication token belongs to its creator, meaning all trading operations relate to the wallet of the user who created the API authentication token in the first place. An API authentication token stays valid until it is invalidated manually.
Obviously, the authorization is checked for each business object access operation, so authenticated users can only access their own objects.
Hierarchical Deterministic Wallets (Multi Signature)
Classic cryptocurrency wallets, like Bitcoin and Litecoin are implemented in a hierarchical, deterministic manner (HD wallets / Multisignature) as defined in BIP 0032, whereby a set of three private keys is derived for each public key.
In CoreExchange, two out of three private keys are required to be present to sign a transaction. Standalone signing services sign the transactions, preventing private keys from being exposed to the coin daemons.
The third key is currently not in use.
The 2-of-3 HD key multi-signature approach allows you to implement more advanced schemes for crypto withdrawals in the future, for example handing out one of the (derived) keys directly to the user, another one to a trusted third party, so that crypto withdrawals can be implemented with enhanced security where neither party (CoreExchange, user, trusted third party) can create a valid withdrawal without the consent of at least one of the other parties.
Ethereum Smart Contracts
For Ethereum one smart contract is deployed per customer, which serves the purpose of a deposit address (so called proxy contracts).
Incoming Ethereum deposits are transferred to a multi-signature smart contract for enhanced security, if they exceed a configurable threshold. Withdrawals below that threshold are done from a proxy contract with a matching balance; withdrawals above that threshold are done from the multi-signature smart contract.
Granular Role Support
Out of the box, the Admin UI comes with two predefined user roles:
- Read-only admin user
- Read-write admin user
The role model can easily be extended and customized to meet your business needs.
CoreExchange supports multiple subsidiaries, each having its own set of accounts, configurations, etc. though some configurations remain global (such as the currency configuration, account type configuration).
If configured, CoreExchange may allow defined transaction types between certain subsidiaries (these are then booked via inter subsidiary accounts).
In the registration process, a default mapping between user country and subsidiary is done. This can be customized and extended to be based on additional input or context data.
Generated File Management
CoreExchange also supports management for generated files in a wallet context, e.g. account statements or transaction exports. These can be downloaded via the API.
The user module contains the user core data, such as name, email, phone numbers, addresses, user identifiers (typically email address), and performs verification processes for that data in the shape of configurable KYC processes.
3rd party user data normalization and validation services can be easily integrated with CoreExchange.
User Document Management
The user can upload personal documents to CoreExchange in order to get his/her account verified and upgraded to the next higher KYC tier which usually involves higher spending limits.
All uploaded documents will appear in the customer's account in the Admin UI and there also in a queue on the home tab for easy access. Customer Care staff can review the uploaded documents and mark verified data in the Admin UI. Documents that do not meet the required criteria can be rejected and the staff will be asked to provide a reason for the rejection. The reasoning will be included in the email notification to the customer, so he/she can take the necessary actions.
In addition, CoreExchange also allows the staff to upload internal documents via the Admin UI to the customer’s account. These are for informational purposes only.
CoreExchange comes with a pre-configured set of email notifications for certain business processes. These include notifications such as:
- Sign-up welcome
- Email verified
- Login successful
- Password forgotten
- Deposit successful
- Withdrawal requested SEPA, Remittance & Crypto
- 2FA enabled & disabled
- Trade order completed
- Voucher code created
- KYC: Document rejected
All templates can of course be customized in text and layout to match your company's branding. Multi-language support is also given.
For email sending purposes, the user module comes with a standard integration of Mailgun (https://www.mailgun.com) that can be used right out of the box. Other email providers will require additional integration efforts.
SMS notifications serve as a way to verify the customer's phone number as a guaranteed communication channel. In addition it is also possible to enable SMS for two-factor authentication.
CoreExchange comes with a standard Twilio (https://www.twilio.com/) integration that can be used right away. Other SMS providers will require additional integration efforts.
SMS templates for the two aforementioned use cases are provided by default. Customization of the existing SMS templates or other means of sending can be done upon request but require additional implementation work.
KYC Level-Based Action Permissions
CoreExchange is highly flexible in the configuration of allowed business processes per KYC level.
This granular configuration can be applied on a per country level, e.g.:
At KYC level 1, customers from country A may be blocked from certain business processes that are allowed for the same KYC level customer in country B.
This helps you to tailor CoreExchange to different regulatory frameworks worldwide.
A user account can be locked at wallet level to prevent him from conducting specific types of financial transfers. The user may however still access his/her account, in order to provide information that may lead to the account being unlocked again by the staff.
If required, accounts may also be terminated by the staff resulting in the customer no longer being able to login. This is done in the user account overview window.
Payment Instrument Verification
You may ask your customers to verify their bank account(s) to ascertain they are the actual owner. CoreExchange does this by sending a small amount of funds along with a PIN code to the customer's bank account.
The customer can then verify the payment instrument by entering the received PIN in the settings area of his/her CoreExchange account.
CoreExchange comes with a dedicated payment module for easy integration of local payment service providers, acquirers, banks or alternative payment methods. CoreExchange only provides the extension point for these integrations, not the actual implementations, apart from SEPA/MT940 processing, which is integrated per default.
For each new payments integration a corresponding business contract needs to be configured.
CoreExchange allows to process SEPA MT940/MT942 account statements, whereby the incoming transfers are automatically identified and credited to the corresponding user wallet accounts.
For outgoing payments, CoreExchange generates a CSV / XML file that can be processed by the bank.
Incoming funds that exceed the user’s KYC limits are put in a so called “frozen state” and can not be accessed by the user until the KYC level is increased accordingly and thereby his/her spending limit. Frozen funds are also released if the account balance is reduced through a withdrawal and the total remaining amount stays below the allowed spending limit.
Business Contract Management
A business contract, once created, can be easily managed through the Admin UI. There its parameters can be edited or the contract can be deactivated if a payment method should no longer be available to the customers.
For more information about business contracts, see chapter 4.4.4
Context-Based Contract Routing
Business contracts can be configured to process transactions context based. This is done via business contract routings, which are part of a business contract configuration. Routings allow you to define the following parameters:
- MCC range
- User verification level
- Payment context
- Payment instrument status
- BIN group
Example Use Case:
Your acquirer has sanctioned certain countries due to regulatory requirements and does not allow credit card transactions from/to customers with this origin. Routing tables allow you to exclude one or multiple countries on a per contract basis.
Payment instruments are stored at wallet level for each individual customer. These can be:
- bank accounts
- credit cards
- external accounts
- crypto wallets
CoreExchange supports integration of an external storage service for securely storing credit card / bank account data if needed.
To keep the PCI DSS audit scope (handling of the sensitive credit card data) as limited as possible, the payment module is built to support indirections of sensitive payment instrument details. For example, it can handle tokenized credit cards. In this case, a dedicated PCI-scoped deployment can be setup for those PSP integrations that need clear text card details. This dramatically reduces the system parts in PCI scope.
Payment Session Management
A payment session is used in preparation of a single payment transaction, typically in a funding or withdrawal business process. The payment session contains all available and usable payment options from which the user can select one to be used for the transaction.
The accounting module provides the abstraction for managing accounts with credits/debits and an account balance, without knowing about wallets, wallet accounts, etc.
The balance calculation is always efficient and accurate (but performance 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.
Account Item Binding Process
The account item binding process is used 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 like SAP or Navision must be implemented separately.
CoreExchange provides a configuration service that allows certain system behaviors to be configured and updated at runtime. Currently, this is used mainly to finetune batch sizes and delays for jobs. But it can also be used to toggle features/behavior.
System Notification Publisher
The system notification publisher collects events generated in the CoreExchange 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.
Internal Service Monitoring / Statistics
The internal service monitoring collects statistics about CoreExchange 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.
Timestamp Synchronisation per API Call
The CoreExchange 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.
Public / Display IDs for Entities
CoreExchange provides public IDs and display IDs in public API entities, to obfuscate internal database IDs, so that we prevent exposing information regarding the number of entities in the system. Each public ID contains a checksum to prevent guessing IDs.