RFC: Onboarding

Context

The Onboarding domain is responsible for setting up a new company that wants to use Midaz. It is up to the client to handle service authentication, as they will most likely be hosting the application exclusively for their own company's use.

Entities

The entities in the Onboarding domain are:

• Organization: the company that serves as the interface for using Midaz. For example: Itaú Bank;
• Ledger: the book that records all transactions (and operations) of this organization. Each organization can have multiple ledgers;
• Asset (this belongs to the Portfolio domain but is part of the onboarding flow): a permitted asset of the ledger that will have operations and accounts using this asset as a balance. It can be: BRL, EUR, BTC, soybeans, refrigerators, and similar items.

Each of the companies wishing to use Midaz can have multiple ledgers, as shown below. This ensures better internal organization for the company in some use cases, such as if they want to separate a ledger by country and similar considerations.
Additionally, we have the concept of parentOrganizationId, allowing an organization to be linked to another parent organization, providing more flexibility for different use cases, as outlined below.

Diagrams

Onboarding - Create Organization, Ledger and Assets

API modeling

Organizations

The user will register on the platform using the endpoint below.

Create an Organization

POST - v1/organizations

{
  "legalName": "Lerian Studio",
  "parentOrganizationId": null,
  "doingBusinessAs": "Lerian", //optional
  "legalDocument": "123456789",
  "status": { //optional
    "code": "ACTIVE", // optional - default "ACTIVE"
    "description": null //optional - default null
  },
  "address": {
    "line1": "Avenida Paulista, 10000",
    "line2": "Centro",
    "zipCode": "04023060",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR" //use ISO 3166-1 alpha2
  },  
  "metadata": { //optional
    "key": "value",
    "boolean": true,
    "double": 10.5,
    "int": 1
  }
}

Retrieve all Organizations

GET - v1/organizations

Retrieve Organization by id

GET - v1/organizations/{organization_id}

Update an Organization

PATCH - v1/organizations/{organization_id}

Updatable fields:

• legalName
• parentOrganizationId
• doingBusinessAs
• address
• metadata

{
   "legalName":"Lerian Studio",
   "parentOrganizationId": null,
   "doingBusinessAs": "Lerian",
   "address": {
     "line1": "Avenida Paulista, 10000",
     "line2": "Centro",
     "zipCode": "04023060",
     "city": "São Paulo",
     "state": "SP",
     "country": "BR" //use ISO 3166-1 alpha2
  },
   "status":{
      "code":"MY_CODE",
      "description":"MY_DESCRIPTION"
   }
}

Delete an Organization

DELETE - v1/organizations/{organization_id}

Ledgers

Create a Ledger

To create ledgers, the endpoint below needs to be called.

POST - v1/organizations/{organization_id}/ledgers

{
  "name": "The Neobank Brazil",
  "status": { //optional
    "code": "ACTIVE", //optional - default "ACTIVE"
    "description": "Ready to use" //optional - dafault null
  },
  "metadata": { //optional
    "key": "value",
    "boolean": true,
    "double": 10.5,
    "int": 1
  }
}

Retrieve all Ledgers

GET - v1/organizations/{organization_id}/ledgers

Retrieve Ledger by id

GET - v1/organizations/{organization_id}/ledgers/{ledger_id}

Update a Ledger

PATCH - v1/organizations/{organization_id}/ledgers/{ledger_id}

Updatable fields:

• name
• status
• metadata

{
   "name":"The Neobank Brazil",
   "status":{
      "code":"New code",
      "description":"New description"
   },
   "metadata":{
      "costCenter":"BR_123"
   }
}

Delete a Ledger

DELETE - v1/organizations/{organization_id}/ledgers/{ledger_id}

Assets

Create an Asset

To create assets, the endpoint below needs to be called.

POST - v1/organization/{organization_id}/ledgers/{ledger_id}/assets

{
  "name": "Bitcoin",
  "type": "crypto", //crypto, currency (ISO 4217), commodity, others
  "code": "BTC", //always UPPERCASE
  "status": { //optional
    "code": "ACTIVE", //optional - default "ACTIVE" 
    "description": null //optional - default null
  },
  "metadata": { //optional
    "key": "value",
    "boolean": true,
    "double": 10.5,
    "int": 1
  } 
}

Important

The combination {asset} + {ledgerId} + {organizationId} must be unique in the database.

Data

Database modeling