Tudo nestas páginas que provisiona ou configura o trilho descreve um deploy single-tenant, em que o seu time opera o serviço. Na oferta gerenciada multi-tenant da Lerian (SaaS), tudo o que é específico do cliente — credenciais da JD, o domínio público de QR, o vínculo com o ledger do Midaz, a conexão com o CRM e cada serviço com que o trilho conversa — é provisionado e resolvido automaticamente, por tenant, pela plataforma. Não há nada para você configurar além da sua própria integração.
Um tenant, um participante direto
Um tenant é um participante direto. Toda chamada é autenticada com as credenciais máquina a máquina do próprio participante direto, e o tenant vem do bearer validado — nunca de um payload nem de um path. As instituições que você hospeda como participantes indiretos vivem dentro do seu tenant e nunca têm credencial própria. O id de um indireto em uma requisição é dado de roteamento: ele decide em qual posição de liquidação o dinheiro se move, e a garantia de que a requisição realmente pertence àquela instituição é sua, antes de você enviá-la. A única exceção anônima são as rotas públicas de payload de QR e de JWKS, cujo chamador é o PSP do pagador — uma parte que nunca foi cadastrada com você.
O mapa de domínios
Cada domínio abaixo é uma seção da referência da API. Uma frase aqui; a referência carrega o contrato completo — quando cada operação é chamada, por qual lado, e o que ela recusa. Cada link leva a uma operação representativa da sua seção.
- Entradas de chave — cadastre, altere e remova as chaves PIX vinculadas às suas contas no DICT, além da verificação em lote e dos dois fluxos de remoção em massa (encerramento de conta e remoção de titular).
- Reivindicações de chave — o processo do BACEN para tomar uma chave de outro PSP: portabilidade da sua própria chave, ou uma reivindicação de posse, com os dois lados da negociação expostos.
- Bancos — o catálogo nacional de participantes do SPI, lido ao vivo do JDPI.
- Transações — pagamentos de saída, pelo SPI (duas fases, assíncronos) ou liquidados no seu próprio livro quando o recebedor é da própria instituição, além da superfície de leitura que fecha o ciclo.
- Devoluções — devolução de um pagamento que você recebeu, iniciada pelo recebedor, sempre uma nova linha de transação limitada ao valor original.
- Limites — limites de transação de saída por conta, criados a partir do primeiro pagamento de saída da conta e aplicados antes de qualquer dinheiro se mover.
- QR codes — códigos estáticos e dinâmicos imediatos com payloads assinados hospedados por você, decodificação e listagem; as rotas anônimas de payload público e de JWKS estão documentadas na introdução dessa seção.
- Webhooks — o espelho de entrada que o JDPI chama em você: cash-in, devolução iniciada pelo banco do recebedor e validação síncrona de conta.
- Participantes indiretos — o registro das instituições que alcançam o SPI pelo seu ISPB: ciclo de vida, posições de liquidação, avisos de entrega e o feed de conciliação.
- MED 2.0 — o mecanismo especial de devolução do BACEN: relatos de infração, solicitações de devolução nos dois papéis, recuperações de valores do lado de quem criou e marcadores de fraude; o crédito de uma devolução que você ganhou chega em um webhook próprio, em MED Inbound Credit.
- Pix Automático — autorizações recorrentes, os agendamentos sob elas, QR codes compostos e as pernas de entrada de cadastro, de liquidação e de evento que o JDPI chama em você.
- Systemplane — a superfície de configuração em runtime voltada ao operador; clientes de pagamento nunca precisam dela. Suas rotas estão documentadas junto com a plataforma, não como uma seção desta referência.
Dinheiro: uma API, duas unidades
Todo campo de dinheiro do contrato desta API é uma contagem int64 de centavos —
110001 significa R$ 1.100,01 — em corpos JSON, query, path e header. Todo campo de dinheiro em um corpo escrito pelo JDPI — os espelhos de webhook, o crédito de entrada do MED e as rotas de entrada, de liquidação e de evento do Pix Automático — é um número JSON em reais (1100.01), porque esse é o contrato da JD nos payloads que a JD envia; o trilho converte para centavos na fronteira. O discriminador é qual lado escreveu o corpo, nunca o idioma do campo: campos com nome em português nas superfícies de escrita desta API continuam sendo centavos inteiros. A descrição de cada campo na referência informa a sua unidade.
Erros
Os erros são
application/problem+json da RFC 9457, e cada um carrega um código de taxonomia PIX-XXXX no membro code — faça a correspondência pelo código, nunca pelo texto legível. A disciplina de status é de atribuição: um 4xx significa que a requisição, ou o dado que ela nomeia, foi o que falhou, e o corpo nomeia o campo ou a entidade; um 5xx nomeia a dependência que falhou (por exemplo 503 PIX-1050, JDPI temporariamente indisponível) em vez de se esconder atrás de um erro genérico. O catálogo completo, com o detail exato que cada código carrega, é a lista de erros do Pix JD.
Como as movimentações Pix chegam ao Midaz
O plugin de participação direta lança toda movimentação Pix liquidada no Midaz como uma transação no ledger. A perna externa vai contra a conta de compensação (por exemplo,
@external/BRL). As movimentações liquidadas incluem cash-out, cash-in, devoluções (refunds), pernas de efetivação de MED e a liquidação do Pix Automático. O Midaz registra o lançamento. A identidade do pagador e do recebedor (banco, agência, conta, nome e documento do titular, chave Pix) vive apenas no registro de transação do próprio plugin. Toda referência do BACEN vive apenas nesse registro.
A correlação entre os dois sistemas funciona por identificadores, não por metadados:
- O ID end-to-end (E2E) é a chave de idempotência do lançamento no Midaz, então uma liquidação repetida nunca pode lançar em duplicidade no ledger. As pernas seguintes do mesmo E2E (uma devolução ou uma efetivação de MED) derivam a sua chave do E2E com um sufixo de fluxo. Elas nunca colidem com o lançamento original.
- O plugin guarda o ID do lançamento no Midaz no seu próprio registro de transação. Ele usa esse ID para confirmar ou cancelar o débito pendente de um cash-out de duas fases.
Por onde começar
- Configurar o trilho — a cadeia de provisionamento, em ordem: o ledger do Midaz e os registros do CRM, as vinte rotas contábeis, as chaves do systemplane que carregam o seu ISPB e a checagem que prova que cada passo funcionou.
- Hospedar participantes indiretos — os três passos extras de provisionamento para um deploy que liquida Pix em nome de outras instituições. Pule se você liquida apenas o Pix dos seus próprios clientes.
- Variáveis de ambiente — a configuração de deploy: conectividade com a JD, os endpoints do ledger e do CRM, a hospedagem de QR e os provedores de notificação.
- A referência da API — escolha o seu domínio no mapa acima; cada link leva a uma operação representativa da sua seção.
A Lerian provisiona a configuração específica do provedor para a participação direta via JD junto com a sua integração. Para configurar a participação direta no Pix, fale com o nosso time.