Pular para o conteúdo principal
Para liquidar um Pix no Banco Central, uma instituição precisa de uma conexão com a infraestrutura do Sistema Financeiro Nacional. Essa conexão é cara e lenta de obter, e nem toda instituição tem uma. A instituição sem ela usa a conexão de outra instituição. Ela vira um participante indireto, e um participante direto liquida por ela e a hospeda. O modelo direto e indireto explica esse arranjo: quem detém a conta de liquidação, e onde fica o dinheiro de cada instituição. Um tenant que hospeda participantes indiretos é antes de tudo um participante direto. Termine os passos 1 a 7 de Configuração do trilho exatamente como aquela página diz. Esta página é o passo 8 dela para um deploy que liquida Pix para outras instituições. Se o seu deploy liquida apenas o Pix dos seus próprios clientes, pule esta página.
Faça o passo 1 antes do passo 3. Sem a chave de criptografia, todo cadastro falha. Faça o passo 2 antes do passo 4: com a postura desligada, o passo do certificado é recusado com 422 PIX-0111. Faça os passos 4 e 5 depois do passo 3, porque os dois agem sobre a participação que o cadastro cria. Os passos 4 e 5 não dependem um do outro.
Esta página trata do provisionamento. Participantes indiretos explica o que uma participação hospedada é, como um crédito de entrada chega até ela, como o seu ciclo de vida se comporta e cada recusa que ela pode responder.
Para dar a um participante indireto uma credencial própria do Pix JD, veja Parceiros no Pix JD.

​
Passo 1: a chave de criptografia do segredo de entrega

No SaaS, não há nada a fazer neste passo. A Lerian configura a chave para o seu tenant. Siga para o passo 2. O resto deste passo vale para um deploy self-hosted.
Por que este passo existe. Quando você cadastra um participante indireto, você informa um segredo de entrega. O plugin assina com ele cada aviso que envia ao endpoint daquela instituição. É assim que a instituição sabe que o aviso veio mesmo de você. Esse segredo é guardado criptografado, e a chave que o criptografa não vem do banco de dados. Ela vem de fora. Se a chave não estiver configurada, todo cadastro que carrega um segredo falha. Essa falha cobre toda a superfície de escrita do fluxo de indiretos.
A mensagem garante que nenhum segredo foi armazenado. A criptografia falha antes de qualquer escrita, então não existe uma linha meio criada com um segredo em texto claro para você ir limpar. Corrija a chave e repita o POST. Essa é toda a recuperação.
Este 409 significa “provisione a chave”, não “tente de novo mais tarde”. O trilho procurou a chave e constatou que ela não existe. Apenas um operador pode adicioná-la. Repetir a chamada sem essa mudança falha da mesma forma. É por isso que o código é um 409 e não diz nada sobre nova tentativa.O irmão dele é 503 PIX-0123, “Indirect delivery key source unavailable”. Você o recebe quando o trilho não conseguiu ler a chave, porque a fonte de chaves dele recusou ou não respondeu. O trilho então não sabe que a chave não existe, porque a leitura não terminou. A resposta nomeia a dependência que falhou, e tentar de novo é a ação certa. Os dois códigos recusam o cadastro e não armazenam nada. O par permite distinguir uma configuração incompleta de uma indisponibilidade.
O plugin inicia sem a chave, e não se recusa a subir. O processo grava um aviso no log ao iniciar e sobe saudável. Na inicialização, nada distingue um deploy que vai hospedar participantes indiretos de um que nunca cadastra nenhum. Então o sintoma chega no primeiro cadastro, não no deploy. Se você não leu o log de inicialização, a recusa é o seu primeiro aviso.
Onde ela vive, e por que não fica no systemplane. Esse contraste explica onde cada tipo de valor pertence neste trilho.
Não coloque a chave de criptografia no systemplane. O systemplane é o plano de configuração ao vivo, legível pela API de administração, e é a casa certa para tudo o que não é segredo. Material de credencial não vai para lá, e o trilho separa os dois de propósito.Também não faça commit dela: nem em um .env versionado, nem em um values.yaml, nem em um arquivo de compose.
O formato: exatamente 64 caracteres hexadecimais. É uma chave AES-256 (32 bytes), codificada em hexadecimal. Isso são 64 caracteres hexadecimais, não 63 e não 65.
Gere uma por deploy. Não copie a chave de outro ambiente e não reutilize a de outro serviço.
Um valor ausente, em branco ou malformado produz o mesmo 409 PIX-0107. Não há padrão e não há degradação para guardar o segredo em texto claro. Isso é deliberado: um padrão silencioso aqui guardaria segredos de clientes criptografados com uma chave que todo mundo conhece.
Em um deploy self-hosted, defina a variável de deploy:
Esse placeholder deliberadamente não é uma chave válida. Colado como está, ele falha fechado com a recusa acima. Ele não criptografa os segredos dos seus clientes com um valor publicado em uma página de documentação. O plugin lê a chave na inicialização, então uma mudança exige reiniciar o processo. O vínculo do ISPB é diferente: o plugin o lê a cada chamada, e uma mudança produz efeito sem reinício.
Não digite o valor em uma linha de comando. Ele acaba no histórico do seu shell e nos logs de CI. Leia de um cofre, ou digite com read -rs, que não ecoa.
Como checar se ela funcionou. Nenhuma rota lê a chave de volta, porque ela é um segredo. Há dois sinais. O log de inicialização. Com a chave resolvível, o aviso “key unavailable” não aparece. Se ele aparecer, nenhum cadastro que carrega um segredo vai passar. O comportamento. Cadastre um participante indireto. A resposta muda de 409 PIX-0107 para 201.
Pense antes de usar a checagem por comportamento. Um cadastro é permanente. Não há rota de exclusão, e a única saída é close, que mantém a linha e segura o ISPB. Em um ambiente de produção, não use um cadastro descartável para testar a chave. Use um ISPB que você pretende operar. O log de inicialização poupa esse custo.

​
Passo 2: declare que este tenant hospeda participantes indiretos

Defina plugin-br-pix-jd.indirects/enabled como true. Esta é uma escrita de configuração, então exige Plugin PIX JD Editor.
O plugin responde 204 quando aceita o valor. O valor é um booleano JSON, sem aspas: {"value":"true"} responde 400. O cadastro funciona com a postura desligada, então você pode cadastrar participantes antes de habilitá-la. A postura controla os caminhos do dinheiro e o certificado de QR próprio do passo 4. Com a postura desligada, o passo 4 responde 422 PIX-0111. Antes de cadastrar alguém mostra o que cada metade faz.
A leitura falha fechada. Quando um caminho do dinheiro “volta ao comportamento de direto” e ninguém mudou a chave, essa é a causa. Olhe o systemplane.

​
Passo 3: cadastre um participante indireto

Uma chamada faz toda a montagem. Ela checa o ISPB, cria a conta de liquidação @pi_{ispb} no Midaz e marca a participação como ativa. Ela exige Plugin PIX JD Contributor ou Plugin PIX JD Editor.
Um 201 significa que a participação está pronta para uso. O status é sempre ACTIVE. Você não precisa ficar consultando.
Não escreva o ISPB de um participante indireto em tenancy/jd_integration_binding. Essa chave é a identidade que o plugin apresenta à JD. O ISPB de um terceiro ali faz o plugin se apresentar como outra instituição. Nada avisa você: o plugin aceita qualquer ISPB válido, e a escrita responde 204. A chave é uma por tenant, não uma por participante indireto. Cada participante indireto que você hospeda alcança o SPI pelo seu ISPB.
O cadastro é permanente. Não existe DELETE em /v1/indirects, e CLOSED é terminal. Um cadastro feito por engano em um tenant ativo fica lá. O ISPB dele continua retido pela regra de unicidade até alguém encerrá-lo. Confira o nome, o ISPB e o endpoint antes de chamar. Ensaie em um ambiente descartável.
Participantes indiretos traz as recusas, as ações de ciclo de vida e como ler o registro de volta.

​
Passo 4: configure o certificado de QR próprio dele, se ele tiver um

Pule este passo para um participante indireto que não tem certificado de QR próprio na JD. Os QR codes dinâmicos dele são então assinados com o seu certificado e servidos no seu host, como para os seus próprios clientes. Por que este passo existe. Alguns participantes indiretos têm o próprio certificado de QR na JD. A JD então assina os QR codes dinâmicos deles com esse certificado. O app do pagador confere a assinatura contra o conjunto de chaves que ele encontra no mesmo host do payload do QR. Então o payload e o conjunto de chaves desse participante devem estar no host do próprio participante, não no seu. Acesso: Plugin PIX JD Contributor ou Plugin PIX JD Editor.
1

Informe o host do participante

Envie PATCH /v1/indirects/{indirectId} com o indirectId do cadastro:
O orçamento de 77 caracteres. A JD limita a URL de um payload de QR a 77 caracteres. O plugin a monta como publicBaseUrl, depois QRCODE_PAYLOAD_PATH, depois, no SaaS, o ISPB da sua instituição, depois o tipo da cobrança e um identificador de até 22 caracteres. Com o QRCODE_PAYLOAD_PATH padrão, qr, sobram 37 caracteres para o host. Um deploy com um QRCODE_PAYLOAD_PATH mais longo deixa menos. Então cada QR code dinâmico desse participante responde 422 PIX-0112. Escolha o host dentro desse orçamento antes de cadastrá-lo.Um 200 retorna a participação. Confira que qrCertificate.ownCertificate é true e que qrCertificate.publicBaseUrl é o host que você enviou.
2

Publique o conjunto de chaves do participante no host dele

O participante não consegue gerar o próprio conjunto de chaves, porque a JD guarda o certificado e assina. Leia o conjunto de chaves do plugin:
A resposta é um documento application/jwk-set+json. Sirva esses bytes como estão, com esse media type, em https:// mais o host do participante mais / mais QRCODE_JWK_PATH. Com o QRCODE_JWK_PATH padrão, isso é https://pix.indirect.example.com/v1/qrcodes/jwks. No SaaS, o caminho termina com mais um segmento: o ISPB da sua instituição, por exemplo https://pix.indirect.example.com/v1/qrcodes/jwks/12345678. Leia o conjunto de chaves de novo cada vez que a JD renovar o certificado do participante.O header X-JWK-Set-Freshness diz fresh ou stale. stale significa que a JD não respondeu e o plugin serviu a última cópia dele. Leia de novo antes de publicar.
Os payloads também vão para o host do participante. Quando você cria um QR code dinâmico com o indirectId desse participante, o plugin não serve o payload dele. A resposta traz payloadJws, e o participante o serve em payloadUrl no próprio host. Criar um QR code dinâmico descreve essa resposta, e como recuperar um payload que você não recebeu.

​
Passo 5: coloque saldo na posição

O cadastro cria a conta @pi_{ispb} vazia. Um Pix recebido a credita, mas um pagamento de saída precisa de saldo antes. Sem fundos, todo pagamento que sai por aquele participante indireto falha por saldo insuficiente. Você faz a carga inicial. Ela espelha o arranjo: na JD você administra o limite daquela instituição, e no seu ledger você coloca saldo na posição dela. A mecânica é a mesma do passo de saldo de Configuração do trilho. Lance uma transação do Midaz a partir de @external/BRL, com as mesmas variáveis daquela página. Apenas o destino muda, para o piAccountAlias do cadastro. É uma transação do Midaz, então exige Midaz Editor ou Midaz Contributor.
Se você perder a resposta de uma recarga, envie de novo o corpo exatamente igual em até 300 segundos. O Midaz então lança a recarga uma vez só. Depois dessa janela, confira o saldo da posição antes de enviar a recarga de novo.Mude o description apenas para uma recarga nova. Um novo description em uma nova tentativa real gera um segundo crédito por engano.
A posição também controla a saída da participação. O plugin recusa close com 409 PIX-0096 enquanto a conta @pi tem fundos, disponíveis ou retidos, e nomeia a causa. Zere a posição antes de encerrar. Uma posição com saldo mantém a participação aberta até você zerá-la. Como checar. Leia o saldo da conta de volta no Midaz. A checagem mais segura é por comportamento: um pagamento de saída pelo participante indireto para de ser recusado por saldo insuficiente.

​
Declare o cliente do participante indireto

Um participante indireto mantém os clientes dele no próprio core, não nos seus livros. Uma requisição para um desses clientes declara o cliente, e não nomeia nenhuma conta sua: Cada requisição também carrega o indirectId. O plugin não lê nenhum registro do cliente declarado, e o envia à JD.
  • Uma requisição com o cliente declarado e uma conta (accountId, ou account_id na consulta), ou sem nenhum dos dois, responde 400 PIX-0061.
  • Uma conta funciona quando a sua própria credencial envia a requisição. Com um parceiro por trás da requisição, a conta responde 400 PIX-0061.
  • O plugin não confere nenhum limite de conta em uma ordem com um pagador declarado. O saldo da posição @pi_{ispb} limita a ordem.
  • Um accountType 4 declarado responde 422 PIX-0098.

​
Devolver um Pix que um participante indireto recebeu

Um Pix para um cliente de um participante indireto cai na posição @pi_{ispb} desse participante. Para devolvê-lo, envie POST /v1/refunds com o indirectId desse participante. A devolução então debita essa posição. Ela não precisa de accountId: quem devolve é o recebedor que o Pix original nomeia. Com um parceiro por trás da requisição, um accountId responde 400 PIX-0061. O plugin recusa a devolução nestes casos, e não move dinheiro:
  • 422 PIX-0135: o Pix original caiu na posição de um participante indireto, e a devolução não tem indirectId.
  • 404 PIX-0147: a devolução nomeia outro participante indireto, ou o Pix original caiu em uma conta direta e a devolução tem um indirectId.
O indirectId passa pelas mesmas checagens de uma ordem de pagamento. A postura de hospedagem deve estar ligada, e a participação deve estar ACTIVE.

​
As chaves do systemplane do namespace indirects

Há cinco chaves, todas em plugin-br-pix-jd.indirects, e todas elas sempre existem. As três chaves de entrega e de resolução só produzem efeito quando enabled é true, porque elas ajustam os caminhos do dinheiro. validate_ispb_on_jd é a exceção. Ela controla um passo do cadastro, que funciona enquanto enabled ainda é false.
O plugin responde 204 quando aceita um valor e 400 quando o validador o recusa. Booleanos e inteiros vão sem aspas. Um valor fora da faixa responde 400. O plugin não o ajusta ao limite.
Os dois passos que podem parar o fluxo de indiretos por conta própria não estão neste namespace. A identidade é a chave do systemplane tenancy/jd_integration_binding. Sem ela, todo pagamento falha com 409 PIX-0092. A chave de criptografia vem de uma variável de deploy ou de um cofre de segredos. Sem ela, todo cadastro falha com 409 PIX-0107.