Context
Introduction¶
The Accounts subdomain is a fundamental component of the Payment Gateway, and is used to create and manage financial structures. It is built around two primary concepts: Accounts and Account Holders.
-
Accounts: These are the financial entities within the system, acting as virtual representations of banking or financial accounts. They are capable of holding funds, processing transactions, and recording financial activities. A key feature of the component is the ability to issue Payment Cards directly linked to an account. Every Account belongs to an Account Holder.
-
Account Holders: These entities, which can be individuals or businesses, own or control Accounts. An Account Holder may manage multiple Accounts.
An Account Holder can have multiple Accounts, creating a 1-n relationship between Account Holders and Accounts.
graph LR;
AccountHolder[Account Holder] -->|1..n| Account[Account]Relation to Adyen's Concepts¶
In our Payment Gateway, Accounts and Account Holders closely align with Adyen's terminologies:
-
Accounts correspond to Adyen Balance Accounts, serving as the financial backbone for transaction processing and fund management. Every Balance Account belongs to an Account Holder.
-
Account Holders equate to Adyen Account Holders and are closely tied to a Legal Entity, reflecting their significant role in managing and owning Accounts within the system. This association emphasizes the importance of Account Holders in the financial structure, underscoring their legal and operational significance.
An Account Holder can have multiple Balance Accounts, creating a 1-n relationship between Account Holders and Balance Accounts. This mimicks the relationship between our own entities.
graph LR;
AccountHolder[Account Holder] -->|1..n| BalanceAccount[Balance Account]Our entities use the external_id field as a unique identifier, storing the corresponding Adyen ID for each entity within our system, thus ensuring a seamless mapping process between the two data models.
Source of Truth and Lifecycle Management¶
Account Holders¶
Info
The class AccountHolderLogic is responsible for the whole scope of Account Holder management.
The component does not manage the lifecycle of Account Holders but focuses on the declaration of existing Adyen Account Holders into our platform. This is because Account Holder management is intricately tied to legal entities, which is beyond the component's scope. Legal entities and Account Holders are typically created together during company onboarding. Therefore, the component supports only declaration and termination operations. Termination operations are confined to our side and do not impact the Adyen side.
Adyen remains the source of truth for Account Holder information. There is no automatic synchronization with Adyen. Changes to an Adyen Account Holder must be manually replicated in our Payment Gateway. This manual process is typically reserved for rare occurrences, such as a company name change, due to the close tie of Account Holder management with legal entities, which is beyond our component's scope.
Accounts¶
Info
The class AccountLogic is responsible for the whole scope of Account management.
Unlike Account Holders, Accounts lifecycles are fully managed within the component, encompassing creation, modification, and termination. Each Account on our platform is directly mirrored by a corresponding Adyen Balance Account.
Our component is the primary source of truth and takes full ownership of their lifecycle management, with each Account on our side having a corresponding Adyen Balance Account. This setup ensures a one-way synchronization from our component to Adyen, reflecting our component's proactive role in managing these financial entities. Changes in Adyen need manual replication in our system; however, given our component's control over the full Account liefecycle, such situations are exceptional.