Pix via JD

O Pix Direto via JD torna sua instituição um participante direto no Pix. Sua instituição está presente por direito próprio no sistema de liquidação (SPI) e no diretório de chaves (DICT) do BACEN. Ela se conecta pela infraestrutura certificada da JD (JDPI). Sua instituição é dona da sua participação no Pix, e a JD fornece a conectividade regulada até a rede do BACEN. Se o trilho em si for novo para você, comece por O que é o Pix?. Essa página explica as modalidades, o SPI, o DICT e os modelos de participação. Quando outro motor de core bancário da sua instituição usa o mesmo canal JD e o mesmo ISPB, o JD Courier compartilha o canal entre os motores. Tudo o que o trilho faz cabe em uma API. A sua especificação OpenAPI é a fonte desta documentação. Cada operação carrega as regras que um integrador não consegue adivinhar só pelo schema.

​

O tenant e os seus participantes diretos

---

Um tenant carrega um ou mais participantes diretos. Por padrão, ele carrega a única instituição que o seu vínculo nomeia. Com o catálogo de organizações, ele pode carregar as várias instituições reguladas de um grupo econômico. Cada uma delas é um participante direto por direito próprio, com os próprios livros. Veja Multiorganização e ledgers. Toda chamada é autenticada com as credenciais máquina a máquina do próprio tenant. 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 é um dado de roteamento. Ele decide em qual posição de liquidação o dinheiro se move. 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. O chamador delas é o PSP do pagador, uma parte que você nunca cadastrou. O modelo direto e indireto explica os dois tipos de participação. Ele também mostra quem detém a conta de liquidação no Banco Central e onde fica o dinheiro de cada instituição hospedada.

​

O mapa de domínios

---

Cada domínio abaixo é uma seção da referência da API. Esta página dá uma frase por domínio. A referência tem o contrato completo: quando chamar cada operação, qual lado a chama e o que ela recusa. Cada link abre uma operação típica da sua seção.

• Entradas de chave: cadastre, altere e remova as chaves Pix das suas contas no DICT. A seção também tem a verificação em lote e os dois fluxos de remoção em massa, para encerramento de conta e para remoção de titular.
• Reivindicações de chave: o processo do BACEN para tomar uma chave de outro PSP. Ele cobre a portabilidade da sua própria chave e as reivindicações de posse, com os dois lados da negociação.
• 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. A seção também tem a superfície de leitura que fecha o ciclo.
• Devoluções: a devolução de um pagamento que você recebeu, iniciada pelo recebedor. Cada uma é uma nova linha de transação, limitada ao valor original.
• Limites: limites de transação de saída por conta. O primeiro pagamento de saída da conta os cria, e o trilho os aplica 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. A introdução da seção documenta as rotas anônimas de payload público e de JWKS.
• Créditos em espera: credite, ou devolva ao pagador, um Pix recebido que o ledger não aceitou. Veja Pix recebido que espera um operador.
• Webhooks: as rotas de entrada que o JDPI chama em você. Elas cobrem o cash-in, a devolução iniciada pelo banco do recebedor e a validação de conta, síncrona e assíncrona.
• Participantes indiretos: o registro das instituições que alcançam o SPI pelo seu ISPB. Ele cobre o ciclo de vida delas, as posições de liquidação, os avisos de entrega e o feed de conciliação.
• MED 2.0: o mecanismo especial de devolução do BACEN. Ele cobre 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 no webhook de devolução, com código de devolução BE08 ou FR01. As listas de MED mantêm apenas os MEDs dos pagamentos que este trilho registrou ou das recuperações de valores que este trilho abriu. Uma solicitação de devolução ou uma recuperação de valores para qualquer outro pagamento responde 404 PIX-0063.
• Pix Automático: autorizações recorrentes, os agendamentos delas e QR codes compostos. A seção também tem as rotas 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 para operadores. Clientes de pagamento nunca precisam dela. A documentação da plataforma cobre as rotas dela, e esta referência não.

​

Ordens de pagamento e devoluções

---

Estas regras valem para todo cliente que envia dinheiro pelo trilho:

• Envie o header X-Idempotency em toda ordem de pagamento (POST /v1/transactions) e em toda devolução (POST /v1/refunds). Use uma string de negócio estável de 255 bytes ou menos. Sem ele, o trilho responde 400 PIX-0061 antes de qualquer chamada ao ledger ou ao JDPI.
• Um reenvio com uma chave registrada não move dinheiro. Ele responde 409 PIX-0029. Uma ordem de pagamento com o endToEndId de uma ordem registrada recebe a mesma resposta. Leia o resultado da primeira requisição com um GET.
• Um reenvio com a chave de uma ordem recusada responde 409 PIX-0133. A JD recusou essa ordem ou nunca a recebeu, então nenhum dinheiro se moveu. Para pagar, envie uma nova ordem com uma nova chave.
• A chave pertence ao pagador. O pagador é a organização que paga, mais o participante indireto em uma ordem ou devolução indireta. Dois pagadores podem usar o mesmo valor de chave.
• Uma ordem de pagamento não carrega a chave Pix do pagador. Um corpo com um campo key no nível superior responde 400 PIX-0061. A chave do recebedor, payee.key, não muda.
• A devolução de um Pix que um participante indireto recebeu carrega o indirectId dele. Caso contrário, o trilho responde 422 PIX-0135. Veja Participantes indiretos.
• Uma ordem de pagamento pode trazer um rótulo de tarifa em feeContext. O rótulo seleciona o pacote de tarifas do Midaz que precifica o Pix. Um rótulo recusado responde 400 PIX-0061 ou 422 PIX-0162, e nada fica retido. Veja Precifique um TED ou Pix por um contexto de tarifa.
• Um débito do Pix Automático é lançado na conta que a autorização nomeia. Quando a autorização não nomeia conta, o débito usa a única conta do pagador. Um pagador com duas ou mais contas e sem conta na autorização recebe 400 PIX-0061, antes de qualquer lançamento.

​

Pix por chave para terceiro

---

Para pagar uma chave Pix de qualquer instituição, consulte a chave primeiro e pague com o que a consulta devolve:

1. Consulte a chave do recebedor com Consultar uma chave Pix antes de pagá-la (GET /v1/entries/{entryId}/lookup). entryId é o valor da chave, codificado para URL. account_id é a conta do pagador, a conta de onde o pagamento sai. A consulta ao DICT é feita em nome do pagador: o DICT a conta contra o CPF ou CNPJ do pagador. Quando este deploy atua como vários participantes diretos, ispb nomeia o que paga. Quando o pagamento passa por um participante indireto, envie o indirectId dele, o mesmo que a ordem de pagamento carrega, e envie o CPF ou CNPJ do pagador no header X-Payer-Document no lugar de account_id. O DICT então gera o endToEndId sob o ISPB desse participante. Com indirectId, omita ispb.
2. Leia a resposta. Ela devolve um endToEndId e um bloco payee com exatamente os campos que o POST /v1/transactions espera. O número da conta vem inteiro em payee.accountNumber, como o DICT o devolve, e payee.accountDigit vem vazio.
3. Pague com POST /v1/transactions, enviando esse endToEndId e esse payee como estão. O pagamento vai para a JD como um pagamento iniciado por chave. Sem o endToEndId, ele sai como uma ordem digitada manualmente.

Uma consulta serve a um pagamento. Consulte a chave de novo antes de cada pagamento, e só quando o pagador estiver prestes a pagar: uma consulta que não é seguida de pagamento ainda gasta a cota de DICT do pagador e da instituição. Para verificar se uma lista de chaves existe, use POST /v1/entries/verification. A consulta responde estes erros: O limite de consultas. Por padrão, um pagador pode fazer 100 consultas a cada 60 segundos. O pagador é a conta em account_id, ou o documento em X-Payer-Document, contado à parte para cada participante indireto. O limite vale sempre, à parte dos limites gerais de requisição. O operador o ajusta no namespace de systemplane plugin-br-pix-jd.http, com as chaves rate_limit.key_lookup.max e rate_limit.key_lookup.window_sec. Um pagamento por chave para um recebedor da sua própria instituição é conferido no DICT. Antes de o pagamento liquidar no seu livro, o trilho compara o ISPB, a agência, a conta, o tipo de conta e o documento do recebedor com a conta à qual o DICT vincula a chave. Um campo que diverge responde 422 PIX-0033, nomeando o campo, e nenhum dinheiro se move. Envie o payee que a consulta devolveu e a conferência passa.

​

Pix a partir de um QR code

---

Para pagar um QR code, decodifique-o primeiro com Decodificar QR code (POST /v1/qrcodes/decode). Depois pague com POST /v1/transactions e envie estes valores da resposta da decodificação, sem mudar nada:

• endToEndId, e a key decodificada como payee.key.
• qrCodeType: STATIC ou DYNAMIC.
• txId: obrigatório para um código DYNAMIC, opcional para um código STATIC.

Para um recebedor em outra instituição, o pagamento vai para a JD como um pagamento por QR code, e o recebedor o concilia pelo txId dele. Sem qrCodeType, o pagamento sai como um pagamento por chave. Uma combinação inválida responde 400 PIX-0061 antes de qualquer valor ser retido. Para um pagamento por um participante indireto, a decodificação carrega o indirectId dele e o CPF ou CNPJ do pagador em X-Payer-Document. Veja Declare o cliente do participante indireto.

​

Pix recebido que espera um operador

---

Quando o ledger recusa o crédito de um Pix recebido porque o saldo de destino não aceita créditos, o trilho não lança nada. Ele responde à JD com 500 PIX-0151, e a JD entrega o Pix de novo. GET /v1/transactions mostra o Pix como PENDING, com pendingReason BALANCE_NOT_RECEIVING. Uma entrega posterior da JD, ou a passada de conciliação do trilho, lança o crédito quando o saldo passa a aceitar créditos. Quando o seu Tracer recusa o crédito no ledger, por uma regra, um limite ou uma revisão, o trilho também não lança nada. Ele responde à JD com 500 PIX-4011, e a JD entrega o Pix de novo. O Pix mostra pendingReason TRACER_DENIED. Uma entrega posterior da JD lança o crédito quando o seu Tracer o deixa passar. Essa recusa vem da verificação do Tracer no ledger, e não da triagem na validação de conta. Para agir antes disso, um operador da sua instituição pode:

• Creditar o Pix com Creditar um Pix recebido em espera, depois que o saldo aceitar créditos e o seu Tracer o deixar passar. A rota responde 200, com a transação EXECUTED. Enquanto o seu Tracer recusa o crédito, ela responde 422 PIX-4018.
• Devolver o Pix ao pagador com Devolver ao pagador um Pix recebido em espera. A devolução vai pelo SPI pelo valor total, com o motivo BE08, e não lança nada no ledger. A rota responde 202, com a devolução PENDING. Se o ledger já aceita o crédito, a ação credita o Pix no lugar e responde 409 PIX-0158. Quando o SPI liquida a devolução, o Pix recebido passa a ERROR, com pendingReason RETURNED.

Uma devolução recebida de um Pix que você enviou só pode ser creditada. As duas ações funcionam até 23 horas depois que o Pix chegou. Quando o ledger recusou o crédito porque o saldo não aceita créditos, porque o seu Tracer o recusou, ou porque o ledger não conhece a conta ou a rota contábil, elas funcionam até 7 dias menos 1 hora. Depois disso, elas respondem 409 PIX-0159. Elas precisam da permissão parked-credits (ação post). Depois de um 5xx, espere dois minutos e então envie o crédito.

​

Débitos do Pix Automático que esperam

---

O SPI pode liquidar um débito do Pix Automático que o ledger do pagador depois recusa. O trilho responde à JD com um erro que a JD tenta de novo, e a JD entrega o débito outra vez. O débito é lançado quando a causa deixa de existir. Listar débitos em espera do Pix Automático mostra esses débitos, do mais novo ao mais antigo, cada um com o pendingReason dele:

• INSUFFICIENT_BALANCE: o pagador não tem os fundos. Dê fundos ao pagador.
• TRACER_DENIED: o seu Tracer recusou o débito, por uma regra, um limite ou uma revisão. Confira essa regra, esse limite ou essa revisão no Tracer.

Um débito sai da lista quando é lançado. ispb restringe a lista aos pagadores de um participante direto. A leitura de um agendamento pelo endToEndId dele mostra o mesmo pendingReason, e waitingSince.

​

Reivindicações sobre as chaves dos seus clientes

---

Quando outra instituição reivindica uma chave que o seu cliente tem, você responde à reivindicação:

• Entregue a chave com Confirmar uma reivindicação de chave Pix. A chave fica na conta do seu cliente até o reivindicador concluir a reivindicação. Se a reivindicação for cancelada ou expirar, a chave volta a ACTIVE.
• Recuse a reivindicação com Cancelar uma reivindicação de chave Pix. O Bacen aceita a recusa de uma reivindicação de posse apenas como uma declaração de fraude, então envie fraudDeclared true. Sem ele, o trilho responde 400 PIX-0061 e não envia nada ao DICT. Você também pode recusar como fraude uma reivindicação de posse que você confirmou, até o prazo de conclusão dela.

Para avisar o seu cliente quando uma reivindicação é aberta, defina JOBS_CLAIM_RECEIVED_POLL_ENABLED=true para emitir key.claim-received.

​

Dinheiro: uma API, duas unidades

---

O próprio contrato desta API expressa todo campo de dinheiro como uma contagem int64 de centavos. Por exemplo, 110001 significa R$ 1.100,01. Essa regra cobre corpos JSON, query, path e header. O JDPI escreve alguns corpos: as rotas de webhook e as rotas de entrada, de liquidação e de evento do Pix Automático. Nesses corpos, todo campo de dinheiro é um número JSON em reais (1100.01). Esse é o contrato da JD nos payloads que a JD envia. O trilho converte para centavos na fronteira. O lado que escreveu o corpo define a unidade, nunca o idioma do campo. Campos com nome em português nas superfícies de escrita desta API continuam carregando centavos inteiros. A descrição de cada campo na referência informa a sua unidade.

​

Nomes de campo em inglês

---

No MED 2.0, no Pix Automático e na consulta de chave, um campo que as versões anteriores aceitavam com dois nomes, um em inglês e um em português obsoleto, agora tem só o nome em inglês. Por exemplo: recoveryId (era idRecValores), recurrenceId (era idRecorrencia), cancellationId (era idCancelamento), taxId (era cpfCnpj) e payee.accountNumber na consulta de chave (era nrConta). A referência traz o nome de cada campo.

• Um corpo de requisição com um nome em português é recusado com 400 PIX-0061, como qualquer campo que a API não declara. Nada é registrado. Envie o nome em inglês.
• Um parâmetro de query com um nome em português é ignorado. Uma listagem filtrada por ele volta sem filtro. Confira o nome de cada filtro na referência.
• As respostas carregam cada campo uma vez, com o nome em inglês.
• As rotas de recuperação de valores do MED são GET /v1/med/recoveries/awaiting-return e POST /v1/med/recoveries/{idRecValores}/return. Os paths awaiting-devolver e devolver não existem mais.

Os corpos que o JDPI escreve mantêm os nomes de campo da JD: as rotas de webhook e as rotas de entrada, liquidação e eventos do Pix Automático.

​

Erros

---

Os erros são application/problem+json da RFC 9457. Todo erro 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 lista de erros do Pix JD tem todos os códigos, com o detail exato de cada um.

​

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. O registro de transação do próprio plugin guarda a identidade do pagador e do recebedor (banco, agência, conta, nome e documento do titular, chave Pix) e toda referência do BACEN. A correlação entre os dois sistemas funciona por identificadores. O plugin grava esses identificadores como metadados em cada lançamento no Midaz. Os metadados que o plugin grava guardam apenas identificadores e classificação, nunca valores, nomes ou documentos:

• Em todo lançamento: contractVersion (2), plugin (br-pix-direct-jd), rail (PIX), flow e aggregateId. flow é CASH_OUT, CASH_IN, P2P, REFUND, MED ou AUTOMATIC_DEBIT. aggregateId é o identificador que o plugin dá à movimentação.
• Quando a movimentação tem esses dados: endToEndId, o ID E2E, e direction, IN ou OUT. Um lançamento REFUND também traz originalAggregateId, a movimentação devolvida. Os lançamentos do pagador de uma ordem de pagamento com rótulo de tarifa trazem feeContext.

O plugin também 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. Todo lançamento tem uma chave de idempotência que continua a mesma quando o plugin repete a mesma liquidação. Para ver o detalhe bancário por trás de um lançamento, consulte a API de transações do plugin pelo id de transação do plugin ou pelo ID E2E. O ledger fica só com a contabilidade.

​

Relatório ao Bacen de um Pix liquidado nos seus livros

Um Pix entre duas contas da sua instituição é liquidado nos seus livros e não passa pelo SPI. O trilho relata cada pagamento e cada devolução desse tipo ao Bacen pela JD. Consultar o status da transação (GET /v1/transactions/{transactionId}) mostra o relatório no campo internalSettlementReport. O campo aparece apenas para esse tipo de Pix depois que ele chega a EXECUTED. O status dele é um destes valores: Para um relatório em REJECTED ou INCOMPLETE, abra um ticket no Lerian Support Portal.

​

Por onde começar

---

1. Configuração do trilho: o roteiro de configuração, na ordem em que você age, para um serviço que já está rodando. Ele cobre os pré-requisitos, a assinatura das ordens de pagamento, o ledger do Midaz e os registros do CRM, as rotas contábeis, as configurações do plugin e as checagens que provam cada passo. Siga-o de cima a baixo.
2. Assinatura da ordem de pagamento: o passo 2 do roteiro, apenas se a JD exige ordens de pagamento assinadas para a sua instituição.
3. Variáveis de ambiente: as variáveis de deploy do serviço, com o formato e o padrão delas.
4. O modelo direto e indireto: os dois tipos de participação, e onde fica o dinheiro de um participante indireto. Depois, leia Hospedar participantes indiretos, com os passos extras para um deploy que liquida Pix para outras instituições. Pule os dois se você liquida apenas o Pix dos seus próprios clientes.
5. A referência da API: escolha o seu domínio no mapa acima. Cada link abre uma operação típica da sua seção.