> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Estruturando operações bancárias com o Midaz

> Desenhe Organizações, Ledgers, Portfólios e Segmentos para banking de varejo e corporativo, com boas práticas para hierarquias escaláveis.

O Midaz aceita banking de varejo e corporativo por meio de uma hierarquia de entidades clara. Esta página traz boas práticas para estruturar organizações, ledgers, contas, portfólios e segmentos. Uma boa estrutura mantém as operações simples conforme você escala.

## Hierarquia de Organizações e Ledgers

***

### Organização única vs. múltiplas Organizações

Um banco que opera como uma única entidade legal precisa de uma Organização no Midaz. Para um grupo bancário com subsidiárias, use uma organização pai sobre várias organizações filhas. Essa estrutura corresponde à sua governança corporativa. Ela também isola os dados por entidade.

> [!NOTE]
>
> A estrutura de organização deve refletir sua estrutura corporativa.

### Usando múltiplos Ledgers

Dentro de uma organização, escolha o número de ledgers a partir das suas necessidades operacionais. Mantenha um **ledger primário** para transações de clientes. Adicione ledgers para propósitos especiais, como operações de tesouraria ou segmentação regulatória.

> [!NOTE]
>
> Use múltiplos ledgers apenas quando necessário para manter a complexidade baixa. Uma transação pode mover fundos entre ledgers apenas quando cada ledger habilita `crossLedger.enabled`. Veja [Ledgers](https://docs.lerian.studio/pt/products/midaz/ledgers.md).

## Estruturação de contas para banking de varejo e corporativo

***

### Clientes de varejo – Portfólio por cliente

Para banking de varejo, crie um Portfólio para cada cliente. Cada portfólio contém as contas do cliente, como conta corrente, poupança ou cartão de crédito. Essa estrutura deixa os saldos fáceis de ler por cliente.

> [!TIP]
>
> Use o [CRM](https://docs.lerian.studio/pt/products/midaz/crm/crm-data-security.md) para gerenciar dados pessoais como identificadores fiscais, endereços e aliases bancários, tudo em um só lugar.

### Clientes corporativos – contas hierárquicas

Para banking corporativo, use **contas filhas** dentro dos portfólios para refletir a estrutura interna. Uma empresa pode manter uma conta pai para seus fundos principais. Ela pode adicionar contas filhas para subdivisões, como folha de pagamento ou rastreamento de despesas.

### Contas internas

Crie contas internas para receita, despesas e fluxos de liquidação. Contas nomeadas como "Fee Income – USD" ou "Interest Expense – USD" mantêm os relatórios financeiros claros.

## Exemplo prático: um banco digital típico

***

Este exemplo mostra como um banco digital pode estruturar seu deploy do Midaz. O banco oferece contas correntes, poupança e transferências via Pix.

```
Organization: "Neobank S.A."
│
├── Ledger: "Main Ledger (BRL)"
│   │
│   ├── Segments
│   │   ├── "Standard" (default tier)
│   │   ├── "VIP" (premium customers)
│   │   └── "Business" (corporate accounts)
│   │
│   ├── Account Types
│   │   ├── "checking" → everyday transactions
│   │   ├── "savings" → interest-bearing deposits
│   │   ├── "settlement" → internal clearing
│   │   └── "fee-revenue" → bank fee collection
│   │
│   ├── Internal Accounts
│   │   ├── Settlement Account (clearing for Pix, TED)
│   │   ├── Fee Revenue Account
│   │   └── Interest Expense Account
│   │
│   └── Customer Portfolios
│       ├── Portfolio: "Maria Silva"
│       │   ├── Checking Account (BRL) — Segment: VIP
│       │   └── Savings Account (BRL) — Segment: VIP
│       │
│       └── Portfolio: "Tech Corp Ltda."
│           ├── Main Checking (BRL) — Segment: Business
│           ├── Payroll Account (BRL) — Segment: Business
│           └── Expense Account (BRL) — Segment: Business
│
└── Ledger: "Treasury"
    └── FX and interbank positions
```

### Como uma transferência Pix flui por essa estrutura

**1. Transação iniciada**

Maria envia R\$ 500 via Pix a partir da conta corrente dela.

**2. Rota de Transação valida**

A Rota de Transação "Pix Out" se aplica. Ela define um débito da conta corrente de Maria e um crédito para a Settlement Account. Ela também pode adicionar uma operação de tarifa.

**3. Operações são executadas**

O Midaz cria quatro operações atomicamente. Ele debita R$ 500 de Maria e credita R$ 500 para Settlement. Ele também debita uma tarifa de R$ 0,50 de Maria e credita R$ 0,50 para Fee Revenue.

**4. Evento publicado**

Quando o streaming está habilitado, `STREAMING_BROKERS` e a fonte de CloudEvents do Ledger estão configurados, e a transação alcança um estado de ciclo de vida elegível, o Midaz emite um CloudEvent de ciclo de vida de transação. O serviço de notificação do banco lê o evento e envia a Maria uma notificação push.

**5. Liquidação externa**

Uma integração externa concilia a Settlement Account com a infraestrutura Pix do banco central.

### Guia de decisão: quando dividir ledgers

| Cenário | Recomendação |
| :- | :- |
| Moeda única, unidade de negócio única | Um ledger é suficiente |
| Múltiplas moedas com câmbio ocasional | Um ledger, contas de ativo separadas por moeda |
| Entidades legais ou subsidiárias separadas | Um ledger por entidade, sob organizações separadas |
| Requisito regulatório de isolamento de dados | Ledgers separados, ou organizações separadas para isolamento total |
| Operações de tesouraria e trading | Ledger de tesouraria dedicado ao lado do ledger operacional |

> [!TIP]
>
> Na dúvida, comece com um único ledger. Você pode dividir depois, conforme a complexidade operacional cresce. Se você dividir cedo demais, adiciona sobrecarga de orquestração sem benefício claro.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.