> ## 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. # Pix via JD > Participação direta no Pix, no SPI e no DICT do BACEN, pela conectividade certificada da JD: uma API para chaves, pagamentos, QR codes, webhooks, MED 2.0, Pix Automático e os participantes indiretos que você hospeda. 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?](https://docs.lerian.studio/pt/interfaces/pix/pix-overview.md). 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](https://docs.lerian.studio/pt/interfaces/jd-courier/what-is-jd-courier.md) compartilha o canal entre os motores. Tudo o que o trilho faz cabe em uma API. A sua [especificação OpenAPI](https://docs.lerian.studio/pt/openapi/v3-current/pix.yaml) é a fonte desta documentação. Cada operação carrega as regras que um integrador não consegue adivinhar só pelo schema. > [!NOTE] > > Em um deploy self-hosted, o seu time opera o serviço. Na Lerian Cloud, a Lerian roda o serviço e configura a conexão com a JD, o domínio público de QR, a conexão com o CRM e cada serviço com que o trilho conversa. Nos dois casos, o resto da configuração é seu para executar: os seus livros no Midaz, os seus registros de titular no CRM, as suas rotas contábeis e as configurações do trilho. ## 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](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md). 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](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-and-indirect-model.md) 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/list-keys.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/create-claim.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/list-pix-participant-bank-ids.md)**: o catálogo nacional de participantes do SPI, lido ao vivo do JDPI. * **[Transações](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/create-transaction.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/create-refund.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/retrieve-transaction-limits.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/create-dynamic-qr-code.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/credit-a-parked-received-pix.md)**: credite, ou devolva ao pagador, um Pix recebido que o ledger não aceitou. Veja [Pix recebido que espera um operador](#received-pix-that-waits-for-an-operator). * **[Webhooks](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/process-an-inbound-upstream-cash-in.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/indirect-participants.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/list-med-infractions.md), [solicitações de devolução](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/open-a-med-refund-request.md) nos dois papéis, [recuperações de valores](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/create-a-med-value-recovery.md) do lado de quem criou e [marcadores de fraude](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/register-a-med-fraud-marker.md). O crédito de uma devolução que você ganhou chega no [webhook de devolução](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/process-a-payee-bank-initiated-pix-devolu-o.md), 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/request-a-pix-automatico-authorization.md)**: 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](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md)**: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/indirect-participants.md#returning-a-pix-that-an-indirect-participant-received). * **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](https://docs.lerian.studio/pt/products/midaz/fees/using-fee-engine.md#price-a-ted-or-pix-by-a-fee-context). * **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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/look-up-a-pix-key-before-paying-it.md) (`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: | Status | Código | Quando | | - | - | - | | `400` | `PIX-0061` | Uma consulta sem `indirectId` não tem `account_id`, ou tem `X-Payer-Document`. Uma consulta com `indirectId` não tem nem `X-Payer-Document` nem `account_id`, ou tem os dois. `X-Payer-Document` não é um CPF ou CNPJ. Um parceiro envia `account_id` com `indirectId`. `ispb` não tem 8 letras maiúsculas ou dígitos. | | `404` | `PIX-2016` | `account_id` não resolve para uma conta. | | `404` | `PIX-1011` | O DICT não tem essa chave. | | `404` | `PIX-0095` | `indirectId` não nomeia nenhum participante indireto deste tenant. | | `422` | `PIX-0127` | Este deploy atua como vários participantes diretos, `ispb` está ausente e não há `indirectId`. | | `422` | `PIX-0128` | `ispb` nomeia um participante que este deploy não representa, e não há `indirectId`. | | `422` | `PIX-0100` | O participante indireto que `indirectId` nomeia não está `ACTIVE`. | | `422` | `PIX-0102` | `ispb` nomeia um participante diferente do que hospeda o participante indireto. | | `422` | `PIX-0111` | A requisição tem `indirectId`, e `plugin-br-pix-jd.indirects/enabled` é `false`. | | `429` | `PIX-0009` | A conta do pagador atingiu o limite de consultas deste deploy, ou um orçamento de leituras do DICT está vazio. A resposta traz `Retry-After`. | | `429` | `PIX-1008` | O DICT recusou a consulta pelo próprio limite. O Pix JD então esvazia o orçamento daquele pagador para aquele tipo de chave, e as próximas leituras do pagador respondem `429 PIX-0009` até que ele se reponha. | | `503` | `PIX-1050` | A JD está indisponível. | | `503` | `PIX-1054` | A JD não pode ser alcançada. | | `504` | `PIX-1051` | A JD não respondeu a tempo. | **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`. **O orçamento de leituras do DICT.** Antes de perguntar ao DICT, o Pix JD gasta o orçamento antiscan do DICT, mantido por tenant no Valkey. Uma consulta de chave, uma leitura de detalhes de chave, uma abertura de reivindicação e uma decodificação de QR code gastam, cada uma, 1 ficha do orçamento do pagador. Um pagador tem um orçamento para chaves de e-mail e telefone e outro para chaves CPF, CNPJ e aleatórias. Uma pessoa tem 100 fichas, que se repõem a 2 por minuto. Uma empresa tem 1000 fichas, que se repõem a 20 por minuto. O orçamento conta o documento de um pagador uma só vez no tenant, qualquer que seja o participante indireto. Uma chave que o DICT não guarda custa 20 fichas. Um pagamento que a JD aceita com o `endToEndId` da consulta devolve 1 ficha, ou 2 para uma empresa. A instituição tem mais um orçamento, compartilhado por todos os pagadores. Ele segue a política que a JD informa para a sua instituição, que o Pix JD lê de novo a cada hora. Quando um orçamento está vazio, a chamada responde `429 PIX-0009` com `Retry-After`. Em uma consulta de chave, o limite de consultas acima vale à frente dele. Quando o Valkey não responde, as leituras passam sem contagem. **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. > [!WARNING] > > A rota de consulta exige a permissão de acesso `entries-lookup` (ação `get`), que os papéis do Pix recebem do Access Manager. Em um deploy self-hosted (BYOC) em que a declaração de permissões do Pix JD não está publicada, confirme que os papéis do Pix têm essa permissão **antes** de atualizar o plugin Pix para a 1.1.0 ou posterior. Caso contrário, a rota responde `403`. ## Pix a partir de um QR code *** Para pagar um QR code, decodifique-o primeiro com [Decodificar QR code](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/decode-qr-code.md) (`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. Uma decodificação gasta o orçamento de leituras do DICT do pagador, como uma consulta de chave. Quando o orçamento está vazio, ela responde `429 PIX-0009` com `Retry-After`. Veja [O orçamento de leituras do DICT](#pix-by-key-to-a-third-party). 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](https://docs.lerian.studio/pt/interfaces/pix-jd/hosting-indirect-participants.md#name-the-indirect-participants-customer). ## 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](https://docs.lerian.studio/pt/products/tracer/integration-guide.md#midaz-ledger-reservation-seam), e não da [triagem na validação de conta](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md#inbound-credit-screening). Para agir antes disso, um operador da sua instituição pode: * **Creditar o Pix** com [Creditar um Pix recebido em espera](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/credit-a-parked-received-pix.md), 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/return-a-parked-received-pix-to-its-payer.md). 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. | `pendingReason` | Significado | | - | - | | `BALANCE_NOT_RECEIVING` | O ledger recusou o crédito, porque o saldo de destino não aceita créditos. | | `TRACER_DENIED` | O seu Tracer recusou o crédito, por uma regra, um limite ou uma revisão. | | `CREDITING` | Um crédito do Pix está em andamento. | | `RETURNING` | Uma devolução do Pix está em andamento. | | `RETURN_REFUSED` | O SPI recusou a devolução. As duas ações ficam abertas de novo. | | `RETURNED` | O Pix voltou ao pagador e não foi creditado. O status dele é `ERROR`. | ## 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/list-pix-automatico-waiting-debits.md) 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/confirm-claim.md). 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/cancel-claim.md). 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`](https://docs.lerian.studio/pt/reference/events/pix-direct-jd). ## 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/pix-jd-error-list.md) 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](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/retrieve-transaction-status.md) (`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: | `status` | Significado | | - | - | | `PENDING` | O relatório é devido, e a JD ainda não o aceitou. | | `SENT` | A JD aceitou o relatório, e o SPI ainda não respondeu. | | `CONFIRMED` | O SPI registrou o relatório. | | `REJECTED` | A JD ou o SPI recusou o relatório de forma definitiva. | | `INCOMPLETE` | Falta à transação um campo que o relatório exige, ou um documento de uma das partes não é um CPF ou CNPJ. O trilho não envia o relatório até que os dados estejam completos. | Para um relatório em `REJECTED` ou `INCOMPLETE`, abra um ticket em [Lerian Clients](https://docs.lerian.studio/pt/products/midaz/lerian-support-portal.md). ## Por onde começar *** 1. **[Configuração do trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md)**: 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](https://docs.lerian.studio/pt/interfaces/pix-jd/payment-order-signing.md)**: o passo 2 do roteiro, apenas se a JD exige ordens de pagamento assinadas para a sua instituição. 3. **[Variáveis de ambiente](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md)**: as variáveis de deploy do serviço, com o formato e o padrão delas. 4. **[O modelo direto e indireto](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-and-indirect-model.md)**: os dois tipos de participação, e onde fica o dinheiro de um participante indireto. Depois, leia **[Hospedar participantes indiretos](https://docs.lerian.studio/pt/interfaces/pix-jd/hosting-indirect-participants.md)**, 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](#the-domain-map)**: escolha o seu domínio no mapa acima. Cada link abre uma operação típica da sua seção. > [!NOTE] > > 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](https://lerian.studio/contact). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.