Midaz for Children's Accounts

Context

Midaz allows the concept of "child-accounts," enabling parents to create accounts for their children, as shown in Figure 1. In this figure, entity 123 has portfolio 1 which contains accounts 1 (BRL), 2 (USD), and 3 (BTC). Entity 626 is a child of entity 123 and has account 98 (BTC) as a child-account of account 3 (BTC).

Thus, for regulatory purposes and similar considerations, portfolio 1 of entity 123 owns 4 accounts (3 of its own + 1 from entity 626), however, in the client's application flows, entity 626 (the child) will only be able to access their own account (98), as shown on Figure 1.

Figure 1: example of accounts and child-accounts.

Implementation

To create the portfolio for the entityId 123, the Create a Portfolio endpoint should be called.

POST /v1/organizations/{{id}}/ledgers/{{id}}/portfolios

Body:

{
  "entityId": "123",
  "name": "My portfolio"
}

201:

{
  "id": "298c1e79-00b8-4f4b-a045-dd7300213b7a",
  "entityId": "123",
  "ledgetId": "d2d17868-cab3-49f3-9b25-55d139e1ff6e",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "name": "My portfolio",
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "metadata": null,
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null
}

With the portfolio created, accounts can be created using the Create an Account endpoint as shown below.

POST /v1/organizations/{{id}}/ledgers/{{id}}/portfolios/{{id}}/accounts

Body:

{
  "instrumentCode": "BTC",
  "alias": "jhondoe",
  "name": "My BTC account",
  "type": "deposit"
}

201:

{
  "id": "776c4fcd-62dc-4aaa-842c-6bbcbe35ed76",
  "entityId": "123",
  "ledgetId": "d2d17868-cab3-49f3-9b25-55d139e1ff6e",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "parentAccountId": null,
  "productId": null,
  "name": "My BTC account",
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "allowSending": true,
  "allowReceiving": true,
  "alias": "jhondoe_brl",
  "instrumentCode": "BTC",
  "type": "deposit",
  "balance": {
    "available": 0,
    "onHold": 0,
    "scale": 0
  },
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null
}

Given that in this example the entityId 123 has BRL, USD, and BTC accounts, the POST /accounts endpoint would be called three times.

Once this is done, the account for the child (entityId 626) could be created by calling the same POST /accounts, but with the parentAccountId being the id of the BTC account of the entityId 123 as shown below.

POST /v1/organizations/{{id}}/ledgers/{{id}}/portfolios/{{id}}/accounts

Body:

{
  "instrumentCode": "BTC",
  "alias": "janedoe",
  "name": "Jane's BTC account",
  "type": "deposit",
  "entityId": "626",
  "parentAccountId": "776c4fcd-62dc-4aaa-842c-6bbcbe35ed76"
}

201:

{
  "id": "358d0eca-2070-42a9-8f19-7cab1263ffa2",
  "entityId": "626",
  "ledgetId": "d2d17868-cab3-49f3-9b25-55d139e1ff6e",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "parentAccountId": "776c4fcd-62dc-4aaa-842c-6bbcbe35ed76",
  "productId": null,
  "name": "Jane's BTC account",
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "allowSending": true,
  "allowReceiving": true,
  "alias": "janedoe",
  "instrumentCode": "BTC",
  "type": "deposit",
  "balance": {
    "available": 0,
    "onHold": 0,
    "scale": 0
  },
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null
}

After that, you can retrieve the child-account in your app by calling the Retrieve all Accounts endpoint.

GET /v1/organizations/{{id}}/ledgers/{{id}}/portfolios/{{id}}/accounts?entityId=626

200:

[
  {
    "id": "358d0eca-2070-42a9-8f19-7cab1263ffa2",
    "entityId": "626",
    "ledgetId": "d2d17868-cab3-49f3-9b25-55d139e1ff6e",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "parentAccountId": "776c4fcd-62dc-4aaa-842c-6bbcbe35ed76",
    "productId": null,
    "name": "Jane's BTC account",
    "status": {
      "code": "ACTIVE",
      "description": null
    },
    "allowSending": true,
    "allowReceiving": true,
    "alias": "janedoe",
    "instrumentCode": "BTC",
    "type": "deposit",
    "balance": {
      "available": 0,
      "onHold": 0,
      "scale": 0
    },
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
  }
]