> ## 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.

# O modelo direto e indireto

> Como funcionam as participações direta e indireta no Pix neste trilho: o que um ISPB identifica, quem detém a conta de liquidação no Banco Central, onde fica o dinheiro de um participante indireto e como o participante direto controla cada posição.

Toda instituição no Pix participa de uma de duas formas. Um **participante direto** tem conexão própria com a infraestrutura de liquidação do Banco Central, e liquida Pix por direito próprio. Um **participante indireto** não tem conexão própria. Ele contrata um participante direto e opera pela conexão desse participante.

Este trilho torna a sua instituição o participante direto. Com [Hospedar participantes indiretos](https://docs.lerian.studio/pt/interfaces/pix-jd/hosting-indirect-participants.md), outras instituições podem alcançar o Pix por você.

## Todo participante tem o próprio ISPB

***

Direto ou indireto, todo participante carrega um **ISPB**. O ISPB é o código de 8 caracteres, letras maiúsculas ou dígitos, que o Banco Central atribui a cada instituição. Dois fatos sobre ele decidem a maior parte do que vem a seguir:

* **O ISPB dá identidade e roteamento.** O ISPB de um participante indireto o nomeia em cada mensagem Pix. Um crédito recebido o usa para encontrar a instituição certa. Uma ordem de saída o usa para dizer em nome de quem o dinheiro se move.
* **O ISPB não é liquidação.** O participante direto que hospeda um participante indireto liquida o Pix dele. Um ISPB não dá a uma instituição uma conta de liquidação no Banco Central.

Neste trilho, os dois ISPBs vivem em lugares diferentes, de propósito. O seu próprio ISPB é a identidade do deploy. Você o escreve uma vez, na chave do systemplane `tenancy/jd_integration_binding`. O ISPB de cada participante indireto vai no cadastro dele, e em nenhum outro lugar. [Hospedar participantes indiretos](https://docs.lerian.studio/pt/interfaces/pix-jd/hosting-indirect-participants.md) mostra o que acontece quando você confunde os dois.

## Uma conta de liquidação, três camadas de posição

***

A conta que liquida Pix no Banco Central é a **Conta PI**, a conta de liquidação do Pix. Existe exatamente uma por participante direto. Um deploy pode operar vários participantes pelo catálogo de organizações. Nesse caso, cada participante tem a sua própria Conta PI. Um participante indireto não tem Conta PI. É isso que o torna indireto.

A posição de um participante indireto existe em três camadas, e uma parte diferente mantém cada camada:

| Camada | Mantida em | O que é |
| - | - | - |
| 1 | o Banco Central | parte da Conta PI do participante direto. O Banco Central vê um saldo, o seu. O dinheiro de cada instituição hospedada está dentro dele |
| 2 | JD | um limite e um saldo internos por participante indireto, que você administra. A camada de conectividade os usa para saber quanto cada instituição hospedada pode mover |
| 3 | o seu ledger no Midaz | a conta de posição `@pi_` seguida do ISPB da instituição. Existe uma por participante indireto, e o plugin a cria quando você cadastra a instituição |

A segregação acontece na terceira camada. Cada participante indireto liquida na própria conta `@pi_{ispb}`. O dinheiro de uma instituição nunca se mistura com o dinheiro de outra, nem com o seu próprio livro. [Participantes indiretos](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/indirect-participants.md) mostra o que um cadastro cria e como o plugin deriva o alias.

O seu ledger é a camada que autoriza um pagamento. O trilho recusa um pagamento que excede o saldo no Midaz antes de enviar qualquer coisa à JD. Um saldo nas outras camadas não autoriza nada por si só. Isso inclui a Conta PI no Banco Central e o limite de uma instituição na JD. Quando o ledger diz não, a ordem nunca sai do seu lado.

## Como você controla cada posição

***

O participante direto é dono do ciclo de vida de cada posição, do início ao fim:

1. **O cadastro cria a posição.** `POST /v1/indirects` cria a conta `@pi_{ispb}` no Midaz antes de gravar a linha da participação. Você nunca cria a conta por conta própria.
2. **Você coloca saldo nela.** A posição começa em zero. A carga inicial vem da conta externa de compensação (por exemplo, `@external/BRL`), com a mesma mecânica de lançamento de qualquer saldo de abertura. Até que a posição tenha fundos, o trilho recusa todo pagamento que sai por aquele participante indireto, por saldo insuficiente. Para o procedimento, veja [coloque saldo na posição](https://docs.lerian.studio/pt/interfaces/pix-jd/hosting-indirect-participants.md#step-5-fund-the-position).
3. **O cash-in a credita.** Um Pix recebido para um cliente de um participante indireto é lançado na `@pi_{ispb}` daquela instituição. O dinheiro para com você. Depois do seu aviso, a instituição credita o próprio cliente no próprio core.
4. **O cash-out a debita.** Uma ordem de saída em nome de um participante indireto debita a `@pi_{ispb}` dele. Ela nunca debita as suas próprias contas nem a posição de outro participante indireto.
5. **Um encerramento exige a posição zerada.** O trilho recusa `close` com `409 PIX-0096` enquanto a conta `@pi` ainda tem fundos, e a resposta nomeia a causa. O dinheiro nunca fica preso dentro de uma posição encerrada.

## Hospedar participantes indiretos não muda o seu próprio livro

***

Um deploy com a hospedagem habilitada continua operando como um participante direto comum. Em cada crédito recebido, a resolução faz as suas perguntas nesta ordem:

1. **"Este ISPB do recebedor é o nosso?"** Se sim, o crédito é para o seu livro. A conta resolve pelo CRM, como em um deploy que não hospeda ninguém.
2. **Só então: "Corresponde a uma participação indireta?"** Se uma participação `ACTIVE` corresponde, o crédito é lançado na `@pi_{ispb}` daquela instituição.
3. **Nenhum dos dois?** O trilho recusa o crédito. Ele não adivinha nada e não lança nada às cegas.

A ordem é uma proteção, não uma preferência. Créditos dos seus próprios clientes nunca podem ir para a posição de uma instituição hospedada, nem por uma participação que você cadastrou incorretamente. Quando você habilita a funcionalidade, nada muda no fluxo do seu próprio livro.

## Um eixo diferente: vários participantes diretos em um deploy

***

Hospedar participantes indiretos não é a única forma de uma segunda instituição aparecer neste trilho. Não confunda os dois. Um grupo econômico pode rodar as duas instituições dele como participantes diretos em um deploy, pelo [catálogo de organizações](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md). Por exemplo, uma holding pode operar uma instituição de pagamento e uma fintech de crédito, cada uma com o próprio ISPB.

Os dois eixos diferem em tudo o que importa:

| | Um participante indireto | Uma organização adicional |
| - | - | - |
| O que é | uma instituição que alcança o Pix **por você** | um participante direto **por direito próprio**, operado pelo seu grupo |
| Onde o dinheiro dele fica | uma conta de posição `@pi_` dentro do **seu** livro | a **própria** organização e os próprios ledgers no Midaz |
| Quem liquida no Banco Central | você, na sua Conta PI | ela mesma, na própria conta de liquidação |
| A credencial dele na camada de conectividade | nenhuma (ele usa a sua) | a própria, por ISPB |

Um participante indireto é uma posição dentro do seu livro. Uma organização adicional é outro livro por inteiro: uma instituição regulada separada, e os registros dela nunca se misturam com os seus. Um deploy pode fazer os dois ao mesmo tempo. Ele pode hospedar participantes indiretos sob uma organização e operar várias organizações do mesmo grupo.

## Para onde ir agora

***

* **[Hospedar participantes indiretos](https://docs.lerian.studio/pt/interfaces/pix-jd/hosting-indirect-participants.md)**: o provisionamento. Ele cobre a chave de criptografia, a postura, o cadastro de cada instituição e o saldo da posição dela.
* **[Multiorganização e ledgers](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md)**: o outro eixo. Ele cobre vários participantes diretos, e vários livros por participante, em um deploy.
* **[Participantes indiretos](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/indirect-participants.md)**: o que uma participação hospedada é, como o dinheiro chega a uma, e o ciclo de vida dela.
* **[Configurar o trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md)**: a cadeia de provisionamento do participante direto. Tudo acima se apoia nela.
* **[Pix via JD](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-pix-via-jd.md)**: a visão geral do trilho e o mapa de domínios dele.


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