Pular para o conteúdo principal
Um deploy novo deste trilho lança toda movimentação Pix em uma organização do Midaz e um ledger: o par que o vínculo dele nomeia. Esse par é o padrão. Um deploy também pode servir um grupo econômico. Por exemplo, uma holding pode operar uma instituição de pagamento, uma fintech de crédito e um banco. Cada instituição regulada mantém a própria organização, e cada organização mantém quantos ledgers precisar. A funcionalidade inteira é um toggle em uma única chave do systemplane. Enquanto essa chave está vazia, o trilho se comporta exatamente como se comportava antes de a chave existir. Um deploy que é uma instituição com um livro não precisa desta página. Para esse deploy, Configurar o trilho basta.

​
Um teto, vários armários, várias gavetas

Pense no deploy como um escritório de retaguarda com uma parede de armários de arquivo. Cada armário pertence a uma instituição regulada. Os arquivos dele nunca se misturam com os arquivos de outra instituição, porque um regulador audita cada instituição separadamente. Dentro de um armário, gavetas separam linhas de negócio: uma para o produto de carteira, uma para o produto de crédito. Na parede fica pendurada uma ficha que lista os armários e as gavetas. Um funcionário arquiva movimentações de dinheiro apenas em uma gaveta que está na ficha. O funcionário devolve uma movimentação para uma gaveta que não está na ficha, e nunca a arquiva em uma gaveta “perto o bastante”. O vocabulário do trilho mapeia um a um: Dois resultados vêm do modelo:
  • Todo lançamento carrega o seu escopo. O trilho escreve cada transação na organização e no ledger em que ela resolveu. Os registros de cada instituição são, portanto, completos por conta própria. Relatórios regulatórios e contábeis saem por instituição, sem livro compartilhado para separar.
  • O trilho nunca adivinha um escopo. Ele confere a organização e o ledger de uma movimentação contra o catálogo. Se não consegue prová-los, ele recusa a movimentação antes de qualquer lançamento. O desenho existe para tornar impossível que o dinheiro caia no ledger da instituição errada.

​
O toggle: uma chave vazia significa desligado

A chave do catálogo começa vazia, e vazia significa não provisionado. O tenant então lança apenas na organização e no ledger que o vínculo dele nomeia, como antes de a chave existir. Uma escrita de catálogo liga a funcionalidade. O par que o vínculo nomeia continua sendo o padrão: o escopo de todo fluxo que não resolve outro.
O ledger padrão nunca fica no catálogo. As rotas contábeis dele ficam nas chaves routing.*, e o ativo e a conta de compensação dele ficam nas chaves midaz.*. Configurar o trilho mostra como provisioná-los. O catálogo declara apenas o que o vínculo não declara. Uma cópia do ledger padrão no catálogo daria a um livro duas fontes da verdade, então o trilho recusa esse catálogo.
O deploy define até onde o toggle alcança. Um deploy self-hosted é um participante direto. O catálogo dele pode acrescentar ledgers da própria organização: mais livros da mesma instituição. Uma entrada que carrega qualquer outro ISPB é recusada na leitura, porque um deploy self-hosted tem uma credencial da JD e não pode se autenticar como uma segunda instituição. Para atuar como vários participantes, com vários ISPBs sob um teto, fale com a Lerian sobre a Lerian Cloud, em que cada participante adicional tem uma credencial da JD própria.

​
Ative, passo a passo

1

Complete a configuração comum primeiro

O catálogo estende um deploy que funciona. Ele não substitui a configuração. Rode Configurar o trilho do início ao fim. O vínculo que você escreve lá torna a sua instituição o participante padrão e o ledger dela o livro padrão. Se o seu deploy é uma instituição com um livro, pare lá. Enquanto a chave do catálogo estiver vazia, nada nesta página muda coisa alguma.
2

Provisione o livro adicional no Midaz e no CRM

Provisione cada ledger adicional com os mesmos passos da página de configuração, no livro novo:
  1. A organização e o ledger. Um ledger adicional da sua própria instituição vai sob a sua organização existente. Um participante adicional ganha uma organização própria, porque cada organização do Midaz contém exatamente uma instituição regulada.
  2. O ativo e as contas no ledger novo, com a própria conta externa de compensação. Um alias como @external/BRL é único dentro de um ledger, então cada livro precisa da sua.
  3. As rotas de operação no ledger novo: um par de crédito e débito para cada perfil de dinheiro do livro. Esses UUIDs não vão nas chaves routing.*. Eles vão dentro do documento do catálogo no próximo passo.
  4. Os titulares e os instrumentos no CRM, na organização dona do livro. O ledgerId do instrumento diz ao trilho em qual livro uma conta é mantida.
3

Escreva o catálogo

Escreva o catálogo com uma chamada a PUT /system/tenant_policy/organizations. O embrulho é o mesmo do vínculo. O corpo é {"value": ...}, e value é uma string cujo conteúdo é um documento JSON. O documento é uma lista com uma entrada por organização do catálogo. Cada entrada nomeia o ISPB do seu participante, a sua organização do Midaz e os ledgers dessa organização com as suas rotas.A sua própria organização fica no catálogo apenas quando tem ledgers adicionais, e nunca com o ledger padrão. A organização de um participante adicional sempre fica nele.Este é o documento, desembrulhado, com identificadores de exemplo:
Em um deploy self-hosted, a entrada tem o seu próprio ISPB e o seu próprio id de organização, e os ledgers são os livros adicionais.Cada perfil é um par de UUIDs de rota de operação do Midaz.Apenas in e inQrCode são obrigatórios, porque todo ledger do catálogo existe para receber. Um livro que não pode servir nenhuma das duas pernas de entrada mostra um erro de provisionamento. Sem refundSent, uma devolução que você envia é lançada em out. Qualquer outro fluxo que precisa de um perfil ausente recusa com 409 PIX-0105, e a resposta nomeia o perfil, a organização e o ledger. Uma chave routing.* não definida no livro padrão se comporta da mesma forma.Três campos são opcionais:
  • transactionRoute, dentro de um perfil: o UUID da rota de transação do Midaz que os lançamentos deste ledger naquele perfil nomeiam. Defina-o quando o ledger valida rotas. Sem ele, um ledger assim recusa o lançamento. Sem o campo, o lançamento não carrega rota de transação.
  • sharedIspbGate, em uma entrada: true declara que este participante compartilha o ISPB dele com outro core. As transferências on-us dele então consultam primeiro o mapa de propriedade do Courier. A organização padrão declara o mesmo fato com a chave tenant_policy/onus.shared_ispb_gate_enabled. Veja Mapa de propriedade do Courier.
  • qrPublicBaseUrl, em uma entrada: o host em que este participante publica os QR codes dinâmicos dele. Veja Hospedagem de QR code dinâmico.
Deixe o jq fazer o escape da string, como com o vínculo:
Uma escrita bem-sucedida responde 204. Leia a chave de volta como você lê o vínculo de volta. O valor volta como uma string entre aspas com o seu documento:
A chave recarrega sem reinício. Escreva-a com a aplicação em execução, e o deploy em execução passa a usá-la, sem reinício e sem redeploy.
4

Saiba o que os validadores recusam, e quando

O trilho confere o catálogo duas vezes. O validador de escrita pega todo erro que só o documento mostra. A superfície de administração, portanto, recusa um catálogo malformado antes que algum pagamento o encontre.A escrita recusa estes valores, com 400 validation_error:
  • um value diferente de string, ou qualquer coisa depois do primeiro documento JSON.
  • um campo desconhecido em qualquer profundidade. Um nome de perfil de rota digitado errado também é um campo desconhecido, então um erro de digitação não pode passar como um perfil ausente.
  • um ispb que não tem exatamente 8 letras maiúsculas ou dígitos.
  • um organizationId, ledgerId, perna de rota ou transactionRoute que não é um UUID diferente de zero.
  • um externalAlias ou asset vazio, um par de rotas sem uma das pernas, ou uma organização sem ledger.
  • um ledger sem o perfil in ou o perfil inQrCode.
  • o mesmo ispb, organizationId ou ledgerId duas vezes em qualquer lugar do documento.
  • um qrPublicBaseUrl com esquema, porta, query, fragmento, informações de usuário, um host que não é público, ou mais de 37 caracteres.
Um 403 significa uma permissão ausente, nunca um valor recusado.A leitura recusa outros casos, porque só o trilho em execução conhece o seu vínculo e o seu modo. As recusas aparecem no caminho do dinheiro, antes de qualquer lançamento:
5

Entenda como o dinheiro roteia depois que está ligado

  • Toda transação vai para o seu escopo. O lançamento carrega a organização e o ledger em que ele resolveu. O livro de cada instituição, portanto, fica completo e auditável por conta própria.
  • Um crédito de entrada encontra o próprio livro. O ISPB do recebedor escolhe a organização. O registro da conta no CRM escolhe o ledger. Uma organização com um único ledger aceita um registro que não nomeia nenhum ledger, porque ela não tem escolha a fazer. Uma organização com vários ledgers recusa esse registro com 500 PIX-0120 e não adivinha.
  • Uma ordem de saída nomeia o participante pagador quando o tenant é vários. POST /v1/transactions aceita um payerIspb opcional. Um tenant que atua como um participante o omite. Um tenant que atua como vários deve enviá-lo. Sem ele, a ordem responde 422 PIX-0127. Um ISPB como o qual o tenant não atua responde 422 PIX-0128. Um pagador arbitrário poderia debitar o cliente de outra instituição.
  • Entre dois ledgers da mesma organização, a transferência é interna. Um alias é único dentro de um ledger, então um lançamento não consegue conter as duas pernas. O trilho reserva o valor no ledger do pagador contra a conta de compensação dele. Depois, lança o crédito no ledger do recebedor contra a conta de compensação daquele ledger. Por último, confirma a reserva. As duas pernas usam o par de rotas intraPsp próprio de cada ledger, e cada livro continua em partidas dobradas por conta própria.
  • Entre duas organizações do mesmo tenant, o pagamento é Pix comum. Duas organizações significam dois participantes regulados. O dinheiro, portanto, passa pelo trilho de liquidação (SPI), como faz um pagamento para qualquer outra instituição. O mesmo tenant nunca é “o mesmo livro”.
  • Cada participante adicional se autentica como ele mesmo. Ordens que saem de uma organização adicional são enviadas à JD sob a credencial própria daquele participante, provisionada por ISPB. Um participante cuja credencial não está provisionada recusa a primeira ordem dele com 409 PIX-0092 e libera a reserva, e a probe de readiness o reporta fora do ar nomeando aquele ISPB antes de o tráfego alcançá-lo.

​
Desligando

Você pode escrever uma string vazia de volta em tenant_policy/organizations. O tenant então volta ao comportamento só-padrão, como antes da ativação. Isso não desfaz nada já lançado. Dinheiro lançado em um escopo adicional fica naquele ledger, e este trilho não consegue mais alcançá-lo. Um fluxo que resolve para um escopo que o catálogo não declara mais recusa com 500 PIX-0120 antes de tocar o ledger. Então esvazie a chave apenas quando nada roteia para os livros adicionais. Isso significa nenhuma conta cujos registros apontam para eles, nenhum pagamento em andamento e nenhum participante hospedado em uma organização adicional. Para aposentar um livro e manter a funcionalidade, remova a entrada daquele ledger e mantenha o resto do catálogo. A mesma prova de leitura se aplica, escopo por escopo.

​
Para onde ir agora

Configurar o trilho

A cadeia de provisionamento que esta página estende: os objetos do ledger, os registros do CRM, as chaves de roteamento e o vínculo que nomeia o par padrão.

O modelo direto e indireto

Como este eixo difere de hospedar participantes indiretos. Um indireto é uma posição dentro do seu livro. Uma organização adicional é um participante direto com livros próprios.

Variáveis de ambiente

A configuração no momento do deploy, e os valores que ficam em chaves do systemplane em vez disso.

Lista de erros do Pix JD

Todo código PIX-NNNN que esta página nomeia, com o status dele e o texto detail da resposta.