Portfolio
The Portfolio service is responsible for creating and managing the entities that interact within the Ledger system. These entities include accounts, sub-accounts, and portfolios.
Key Entities
Entities (or Persons)
An entity is the owner of an account. In the case of an individual account, the entity is a Natural Person. For a corporate account, the entity is a Legal Person.
Entities are part of the Entities satellite but are directly related to the Portfolio service.
Parent Entity
A parent entity is a person linked to an account but not the primary holder. For example, Person 123 owns Portfolio 1 and decides to create a new portfolio (ID 2) for their child (Person 626). The parent entity needs access to account movements, balances, and other relevant information.
Assets
Assets represent the allowed currencies or commodities within the Ledger that accounts can hold and operate with. Examples include BRL (Brazilian Real), EUR (Euro), BTC (Bitcoin), or even physical commodities like soybeans or refrigerators.
Although the Assets are part of the Portfolio domain, they are created during Onboarding.
Account Type
The account type defines the primary function of the account within the Ledger system. Each account created must have an Account Type, which will be one of the following types:
Deposit: A basic account model used for checking or payment purposes. It is the most common type of transactional account.
Savings: An investment account model that may or may not offer daily earnings (such as an interest-bearing account), depending on whether the Interests satellite service is activated.
Loans: A sub-account used for loans received by the client. It also supports automatic calculation of loan values when integrated with the Interests satellite service.
Marketplace: This account type is used for settlements over time, particularly for acquirers. For example, a sale made in installments over five months would show future balances in this Marketplace child-account. It can also integrate with products like receivables advances.
Credit Card: An account for managing credit utilized via a credit card. It tracks balances and payments specific to card usage.
External Accounts: These accounts signal money entering or leaving the ledger. This is the only account type that can have a negative balance, indicating that money has entered the ledger but is still in transit. It is commonly used for temporary amounts in the ledger, such as funds that need to be transferred to another institution or payments to credit card networks.
The table below indicates which account types can be deactivated based on customer requirements, which types can have multiple sub-accounts, and which types allow user editing.
Type | Deactivated | Edited | Negative |
---|---|---|---|
Deposit | ✅ | ✅ | ❌ |
Savings | ✅ | ✅ | ❌ |
Loans | ✅ | ✅ | ❌ |
Market Place | ✅ | ✅ | ❌ |
Credit Card | ✅ | ✅ | ❌ |
External Account | ❌ | ❌ | ✅ |
This flexibility allows users to customize the system to their specific financial structure and needs.
Product ID
The product ID is a customer clustering concept that can be created according to specific user policies. It allows for segmentation and customized management of account groups.
Portfolio
A portfolio is a grouping of accounts. Just like a physical wallet can hold various currencies (e.g., Real, Euro, Dollar), the portfolio groups together accounts that deal with different assets.
Accounts
Accounts are the fundamental entities within the Ledger that perform transactions. Each account is linked to a specific asset and may contain multiple sub-accounts, each with its own specific purpose.
Child Accounts (Sub-accounts)
Child accounts are accounts linked to another primary account. They are subordinate and can serve specialized roles or purposes.
Example Structure
Figure 1 illustrates the relationship topology between these entities.
Entity 123 owns Portfolio 1, which includes Accounts 1, 2, and 3 (all three accounts are linked to Entity 123).
Portfolio 1 also has a sub-account, Account 98, which is linked to Entity 626
This concept is especially helpful for situations like managing sub-accounts for children. In this scenario, the parent is connected to the main account (since both are under the same portfolio), but the child, with their own entity ID, is the one who actively uses the child account.
This setup enables flexible management of relationships and access controls between primary and secondary account holders.
Creating the Portfolio structure
The main flow of the Portfolio domain will be the creation of Portfolios, and Accounts (main or sub-accounts), for one or more resources configured for the Ledger in question.
The Portfolio structure must be created in the following order:
Step 1 - Create the Portfolio
The first entity you must create is the Portfolio.
To create a Portfolio, use the Create a Portfolio endpoint.
Retrieving Portfolio information
After creating a Portfolio, you can retrieve the information as follows:
To retrieve the information of all Portfolios that are part of your Ledger, use the Retrieve all Portfolios endpoint.
To retrieve the information of a specific Portfolio, use the Retrieve Portfolio by id endpoint.
Updating a Portfolio
If you need to update the information of a Portfolio, use the Update a Portfolio endpoint.
Deleting a Portfolio
To deactivate a Portfolio, use the Delete a Portfolio endpoint.
Step 2 - Create the Accounts
Once you've created a Portfolio, you can create Accounts, according to the Assets you have in your Ledger.
To create an account, use the Create an Account endpoint.
When creating the Account, you can set the productId
field to indicate that the account is part of a client clusterization. You will receive the value of the roductId
field when you create the product.
To create the product, use the Create a Product endpoint.
If you have already created a product, you can use the following endpoints to retrieve the
productId
:Use the Retrieve all Products to retrieve information about all Products a user has created.
Use the Retrieve Product by id to retrieve information about a specific Product.
Refer to the Product API page for more information about managing a Product.
Retrieving Account information
After creating the Account, you can retrieve the information as follows:
To retrieve the information of all Accounts you have created, use the Retrieve all Accounts endpoint.
To retrieve the information of a specific Account, use the Retrieve Account by id endpoint.
Updating an Account
If you need to update the information of an Account, use the Update an Account endpoint.
The following account types can be updated: deposit, savings, loans, overdrafts, market place, and credit card.
In the Open Source contracting model, all accounts can be edited
Deleting an Account
To disconnect an Account, use the Delete an Account endpoint.
The following account types can be disconnected: deposit, savings, loans, overdrafts, market place, and credit card.
Last updated