Reconciliação Pix

Este guia orienta a conciliação de transações Pix entre o Midaz Ledger e os dados de liquidação do BACEN (Banco Central do Brasil) usando o Matcher. Ele cobre tanto Pix enviado (cash-out) quanto Pix recebido (cash-in), desde a configuração até a operação diária e o tratamento de exceções. Ao final deste guia, você terá um contexto do Matcher totalmente configurado que concilia automaticamente suas transações Pix contra os extratos de liquidação SPI do BACEN em base diária.

Fluxos de transação Pix

Entender como as transações Pix fluem pelo sistema é essencial para configurar a conciliação corretamente. Os dois fluxos abaixo mostram o que o Matcher precisa conciliar em cada lado.

Pix enviado (cash-out)

Fluxo de cash-out Pix — Fluxo de cash-out: da iniciação pelo cliente, passando pela liquidação SPI, até a conciliação no Matcher.

Cliente inicia o Pix — O usuário final dispara um pagamento Pix via app ou API.
Plugin cria a iniciação — O plugin Pix cria um registro de iniciação e resolve a conta de destino via consulta ao DICT.
Plugin processa o pagamento — O plugin debita a conta do cliente no Midaz (transação em status pending) e envia a instrução de pagamento ao SPI.
Liquidação confirmada — O SPI envia um webhook confirmando a liquidação. A transação no Midaz é confirmada.
Matcher concilia — O Matcher compara a transação confirmada no Midaz contra a entrada correspondente no extrato de liquidação SPI do BACEN.

Pix recebido (cash-in)

Fluxo de cash-in Pix — Fluxo de cash-in: da notificação SPI de entrada, passando pelo crédito no Midaz, até a conciliação no Matcher.

Pix de entrada chega — O SPI envia um webhook síncrono contendo os dados do Pix recebido.
Plugin valida — O plugin Pix valida o payload e aprova a transação.
Transação de crédito criada — O plugin cria uma transação de CRÉDITO no Midaz para a conta do destinatário.
Liquidação confirmada — O webhook de liquidação confirma que a transação é final.
Matcher concilia — O Matcher compara a transação de crédito no Midaz contra a entrada correspondente no extrato de liquidação SPI do BACEN.

Em ambos os fluxos, o endToEndId é o identificador único que vincula a transação do Midaz ao registro de liquidação do BACEN. Esta é a chave primária para a conciliação.

Configuração passo a passo

Criar o contexto

Crie um contexto de conciliação para transações Pix. Use o tipo 1:1 porque cada transação Pix tem exatamente uma entrada correspondente de liquidação no BACEN.

{
  "name": "Pix Daily Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "feeToleranceAbs": "0",
  "feeTolerancePct": "0",
  "autoMatchOnUpload": false
}

Transações Pix não possuem taxas intermediárias ou liquidações parciais. Um Pix de R

150,00 no Midaz deve aparecer como exatamente R

150,00 no extrato do BACEN. Defina ambos os valores de tolerância como zero — eles são strings decimais, então passe "0".Definir autoMatchOnUpload como false dá a você controle sobre quando o matching é executado, o que é importante quando você precisa que ambas as fontes sejam ingeridas antes da execução.

Veja o schema completo da requisição em Criar contexto.

Criar as fontes

Cada contexto precisa de duas fontes: uma para as transações do Midaz e outra para o extrato de liquidação do BACEN.Fonte A — Midaz (tipo LEDGER):

{
  "name": "Midaz - Pix Transactions",
  "type": "LEDGER",
  "side": "LEFT",
  "config": {}
}

LEDGER é a categoria do Matcher para dados de ledger interno — não é um conector direto com o Midaz. Você exporta as transações Pix do dia do Midaz (incluindo o metadado endToEndId como coluna plana) e envia a exportação para esta fonte, manualmente ou por um pipeline automatizado. Veja Matcher e Midaz para o fluxo de exportação/importação.Fonte B — Extrato SPI do BACEN (tipo CUSTOM):

{
  "name": "BACEN SPI Settlement Extract",
  "type": "CUSTOM",
  "side": "RIGHT",
  "config": {
    "description": "Daily SPI settlement file from BACEN"
  }
}

A fonte do BACEN usa o tipo CUSTOM porque o arquivo de liquidação SPI é carregado manualmente ou via pipeline automatizado a cada dia.Cada fonte deve declarar um side (LEFT ou RIGHT). Um contexto concilia sua fonte LEFT contra sua fonte RIGHT, então atribua um lado ao Midaz e o outro ao BACEN, e mantenha a atribuição consistente em ambas as fontes.

Veja o schema completo da requisição em Criar fonte.

Criar mapas de campos

Os mapas de campos dizem ao Matcher como traduzir campos de cada fonte para os campos canônicos usados no matching.Um mapa de campos é um objeto JSON no formato { "<canonicalKey>": "<sourceColumn>" }. As chaves vêm do vocabulário canônico fechado do Matcher (external_id, amount, currency, date e os opcionais description, fee_amount, fee_currency); os valores são os nomes de coluna brutos em cada fonte. As buscas são planas — o valor de um mapeamento precisa nomear uma coluna de nível superior da linha, então a exportação do Midaz precisa trazer o endToEndId como coluna plana própria (veja Matcher e Midaz — mapeamento de campos customizado).

external_id é a referência de matching entre lados — o valor que o motor compara entre as duas fontes quando uma regra define matchReference. Mapeie-o para o endToEndId nos dois lados. Não mapeie IDs locais de cada lado (o id da transação no Midaz, o id_liquidacao do BACEN) em external_id: esses valores nunca coincidem entre as fontes, então o matching por referência jamais encontraria uma contraparte.

A tabela a seguir mostra como cada campo canônico é mapeado para a coluna em cada fonte:

Campo canônico	Coluna da exportação Midaz	Coluna do extrato BACEN
`external_id`	`endToEndId`	`end_to_end_id`
`amount`	`amount`	`valor`
`currency`	`asset_code`	`moeda`
`date`	`created_at`	`data_liquidacao`

Fonte Midaz — mapa de campos:

{
  "mapping": {
    "external_id": "endToEndId",
    "amount": "amount",
    "currency": "asset_code",
    "date": "created_at"
  }
}

Fonte BACEN — mapa de campos:

{
  "mapping": {
    "external_id": "end_to_end_id",
    "amount": "valor",
    "currency": "moeda",
    "date": "data_liquidacao"
  }
}

Veja Criar mapa de campos para o schema completo da requisição e Mapeamento de campos para o vocabulário canônico.

Criar regras de match

As regras de match definem como o Matcher compara transações entre fontes. Para a conciliação Pix, duas regras cobrem a grande maioria dos cenários.Regra 1 — Match exato por endToEndId (prioridade 1):

{
  "type": "EXACT",
  "priority": 1,
  "config": {
    "matchAmount": true,
    "matchCurrency": true,
    "matchDate": true,
    "matchReference": true,
    "datePrecision": "DAY",
    "caseInsensitive": false,
    "referenceMustSet": true,
    "matchScore": 100
  }
}

Esta regra resolve aproximadamente 95% dos casos. O endToEndId é único por transação Pix em todo o ecossistema. Quando a referência, o valor, a moeda e a data coincidem, é uma conciliação confirmada com confiança máxima. Note que caseInsensitive está definido como false porque os valores de endToEndId são case-sensitive, e referenceMustSet é true para garantir que ambos os lados possuam o endToEndId antes da comparação — isso previne falsos positivos baseados apenas em valor e data.Regra 2 — Fallback com tolerância de data (prioridade 51):

{
  "type": "DATE_LAG",
  "priority": 51,
  "config": {
    "maxDays": 1,
    "minDays": 0,
    "inclusive": true,
    "direction": "ABS",
    "feeTolerance": 0,
    "matchScore": 85,
    "matchCurrency": true
  }
}

Um Pix iniciado às 23:58 pode ser liquidado no BACEN no dia seguinte. Esta regra permite uma janela de 1 dia para cobrir cenários de liquidação D+1. Note que esta regra depende apenas da correspondência de valor e moeda — a comparação do endToEndId é tratada pela Regra 1.

Veja Criar regra de match para o schema completo da requisição e todos os tipos de regra disponíveis.

Ativar e agendar

Com toda a configuração em vigor, ative o contexto e crie um agendamento diário.Ativar o contexto:

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "status": "ACTIVE" }'

Criar um agendamento para executar diariamente às 07:00 UTC:

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 7 * * *",
   "enabled": true
 }'

Executar às 07:00 UTC fornece margem suficiente para que liquidações D+1 apareçam no extrato do BACEN e para que o arquivo diário seja carregado antes da execução do matching.

Veja Atualizar contexto e Criar agendamento para os schemas completos das requisições.

Operação diária

Uma vez configurado, o fluxo de conciliação diária segue cinco passos.

Carregar o extrato do BACEN

Carregue o arquivo de liquidação SPI do dia anterior na fonte do BACEN. O Matcher interpreta CSV, JSON, XML e outros formatos do seu catálogo de formatos.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: multipart/form-data" \
 -F "file=@bacen_spi_2026-03-17.csv" \
 -F "format=csv"

Este passo pode ser automatizado via pipeline que busca o arquivo SPI e o carrega antes da execução agendada de matching.

Envie a exportação do Midaz

Exporte as transações Pix confirmadas do dia anterior do Midaz — incluindo o metadado endToEndId como coluna plana — e envie a exportação para a fonte do Midaz da mesma forma. Este passo costuma ser automatizado pelo mesmo pipeline. Veja Matcher e Midaz para o fluxo de exportação/importação.

Matcher executa às 07:00 (ou manualmente)

A execução agendada acontece automaticamente às 07:00 UTC. Para executar o matching manualmente, use o endpoint de execução.

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "mode": "DRY_RUN" }'

Use DRY_RUN primeiro para visualizar os resultados sem confirmá-los. Quando estiver satisfeito, execute novamente com COMMIT:

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "mode": "COMMIT" }'

Revisar resultados

Após a execução ser concluída, recupere os grupos de match para ver os resultados.

curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups" \
 -H "Authorization: Bearer $TOKEN"

Cada grupo mostra a transação do Midaz conciliada com sua entrada correspondente de liquidação do BACEN, junto com a regra que as conciliou e o score de confiança.

Resolver exceções

Transações não conciliadas aparecem como exceções. Elas requerem investigação — uma transação presente em uma fonte mas ausente da outra, ou uma divergência de valor ou data além da tolerância configurada.Revise as exceções, determine a causa raiz e resolva-as por force match, ignorando ou corrigindo os dados subjacentes.

Sempre execute um DRY_RUN primeiro ao testar novas regras ou após alterações de configuração. Isso previne que matches indesejados sejam confirmados.

Exemplo prático — um dia de dados

O exemplo a seguir ilustra uma execução completa de conciliação para 17 de março de 2026.

Transações Midaz (Fonte A)

ID (tipo)	endToEndId	Valor · data
txn-001 (Pix OUT)	E123456789202603170001	150.00 · 2026-03-17 10:15
txn-002 (Pix IN)	E987654321202603170042	3200.50 · 2026-03-17 11:30
txn-003 (Pix OUT)	E555666777202603170099	89.90 · 2026-03-17 23:58
txn-004 (Pix IN)	E111222333202603170007	500.00 · 2026-03-17 14:00

Extrato SPI do BACEN (Fonte B)

id_liquidacao	end_to_end_id	valor / data_liquidacao
liq-8801	E123456789202603170001	150.00 / 2026-03-17
liq-8802	E987654321202603170042	3200.50 / 2026-03-17
liq-8803	E555666777202603170099	89.90 / 2026-03-18
liq-8804	E444555666202603170055	750.00 / 2026-03-17

Resultados do matching

endToEndId	Midaz ↔ BACEN	Resultado (regra)
E12345…0001	txn-001 ↔ liq-8801	Match — EXACT (score: 100)
E98765…0042	txn-002 ↔ liq-8802	Match — EXACT (score: 100)
E55566…0099	txn-003 ↔ liq-8803	Match (D+1) — DATE_LAG (score: 85)
E11122…0007	txn-004 ↔ —	Exceção — —
E44455…0055	— ↔ liq-8804	Exceção — —

Análise

txn-001 e txn-002: Match exato por endToEndId, valor, moeda e data. A Regra 1 resolveu estes com score de confiança 100.
txn-003: Pix iniciado às 23:58, liquidado no BACEN em 2026-03-18. A Regra 2 (DATE_LAG com janela de 1 dia) pareou este com score de confiança 85. Matches de date-lag nunca são confirmados automaticamente — o par vai para a fila de revisão para confirmação humana.
txn-004: Presente no Midaz mas ausente do BACEN. Possível falha de liquidação ou timeout SPI. Investigue o status da transação via plugin Pix.
liq-8804: Presente no BACEN mas ausente do Midaz. Um Pix de entrada que não foi processado. Verifique a entrega do webhook ou reprocesse a mensagem.

Tratamento de exceções Pix

A tabela a seguir cobre os cenários de exceção Pix mais comuns e as ações recomendadas.

Cenário	Causa provável	Ação recomendada
No Midaz, não no BACEN	Falha de liquidação, timeout SPI, transação rejeitada	Verifique o status da transação no plugin Pix. Se rejeitada, reverta no Midaz.
No BACEN, não no Midaz	Pix de entrada não processado, falha de webhook	Reprocesse a mensagem. Crie uma transação manual se necessário.
Divergência de valor	Raro no Pix (sem taxas intermediárias). Possível erro de arredondamento.	Investigue os registros originais. Faça force match se a diferença for aceitável.
Divergência de data (>1 dia)	Transação retida, reprocessamento	Verifique se é o mesmo Pix. Faça force match ou ignore.

Force match

Quando você confirmou que dois registros representam a mesma transação Pix mas o Matcher não conseguiu conciliá-los automaticamente, use force match.

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/force-match" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "notes": "Confirmed same Pix via endToEndId lookup in SPI",
   "overrideReason": "D+2 settlement delay confirmed with BACEN"
 }'

Ignorar transação

Quando uma transação deve ser excluída da conciliação (por exemplo, uma entrada duplicada ou um Pix já estornado), marque-a como ignorada.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/transactions/{transactionId}/ignore" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "Pix reversal already processed — duplicate entry"
 }'

Veja Force match e Ignorar transação para os schemas completos das requisições.

Devoluções Pix

Devoluções Pix geram transações reversas que também precisam de conciliação. Quando uma devolução é processada, o plugin Pix cria uma nova transação no Midaz com:

O originalEndToEndId vinculando à transação Pix original
Um novo returnIdentification (rtrId) que identifica unicamente a devolução no SPI

O extrato de liquidação do BACEN inclui entradas de devolução com ambos os identificadores, permitindo que o Matcher as concilie contra as transações de devolução correspondentes no Midaz. Para volumes baixos de devolução, elas podem ser conciliadas dentro do mesmo contexto de Conciliação Pix Diária. Para volumes altos, crie um contexto separado dedicado à conciliação de devoluções. Isso simplifica a triagem de exceções e mantém as métricas de devolução isoladas das métricas do fluxo Pix padrão.

A iniciação de devoluções via POST /v1/transfers/{id}/refunds é um endpoint do plugin Pix, não um endpoint do Matcher. O Matcher não inicia transferências ou devoluções — ele apenas concilia as transações resultantes. Cada devolução carrega o originalEndToEndId e um novo returnIdentification para rastreabilidade ponta a ponta, que o Matcher então usa para conciliar a devolução contra o extrato de liquidação do BACEN. Para a iniciação de devoluções, veja a documentação do plugin Pix.

Boas práticas

Use o endToEndId como referência principal

O endToEndId é o identificador Pix único em todo o ecossistema — da instituição iniciadora, passando pelo SPI, até a instituição recebedora. Garanta que ele esteja armazenado nos metadados da transação no Midaz e presente no extrato do BACEN. Sem ele, a conciliação recai em matching por valor e data, que é muito menos confiável.

Execute a conciliação no dia seguinte

Transações Pix próximas ao fim do dia podem ser liquidadas no BACEN em D+1. Agendar o Matcher para 07:00 UTC garante que todas as liquidações do dia anterior estejam incluídas no extrato do BACEN antes da execução do matching. Isso elimina exceções falsas causadas por timing.

Separe Pix IN e Pix OUT para alto volume

Ao processar volumes altos de Pix, crie dois contextos separados — um para cash-out e outro para cash-in. Isso simplifica a triagem de exceções, fornece métricas mais granulares por fluxo e permite agendamento independente se necessário.

Monitore a taxa de match

Uma conciliação Pix saudável alcança uma taxa de match automático acima de 99%. Se a taxa cair abaixo de 95%, investigue problemas sistêmicos como falhas no plugin, mudanças no formato do BACEN ou metadados ausentes nas transações do Midaz.

Tolerância zero é o padrão

O Pix não possui taxas intermediárias, liquidações parciais ou cobranças de processamento. Se os valores divergirem entre o Midaz e o BACEN, isso indica um problema real — não arredondamento. Mantenha tanto feeToleranceAbs quanto feeTolerancePct em zero.

Visualize antes de confirmar

Sempre execute um DRY_RUN antes do COMMIT, especialmente após alterações em regras ou mapas de campos. Isso permite revisar os resultados do matching e identificar erros de configuração antes que afetem os dados de produção.

Métricas-chave

Acompanhe estas métricas para monitorar a saúde do seu processo de conciliação Pix.

Métrica	Valor saudável	Limite de alerta
Taxa de match automático	Acima de 99%	Abaixo de 95%
Exceções diárias	Abaixo de 0,5% do volume	Acima de 2%
Tempo médio de resolução	Abaixo de 4 horas	Acima de 24 horas
Exceções não resolvidas há mais de 48h	0	Mais de 5

Use os endpoints de dashboard do Matcher para monitorar estas métricas em tempo real. Veja Métricas do dashboard.

Próximos passos

Contextos e fontes

Aprenda a configurar e gerenciar contextos de conciliação e fontes de dados.

Regras de match

Explore todos os tipos de regra disponíveis e configurações avançadas de matching.

Integração com Midaz

Aprofunde-se no mapeamento automático de campos e sincronização em tempo real com o Midaz Ledger.

Resolução de exceções

Guia detalhado sobre investigação, force match e gerenciamento de exceções de conciliação.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Reconciliação Pix

Fluxos de transação Pix

Pix enviado (cash-out)

Pix recebido (cash-in)

Configuração passo a passo

Operação diária

Exemplo prático — um dia de dados

Transações Midaz (Fonte A)

Extrato SPI do BACEN (Fonte B)

Resultados do matching

Análise

Tratamento de exceções Pix

Force match

Ignorar transação

Devoluções Pix

Boas práticas

Métricas-chave

Próximos passos

Contextos e fontes

Regras de match

Integração com Midaz

Resolução de exceções

​Fluxos de transação Pix

​Pix enviado (cash-out)

​Pix recebido (cash-in)

​Configuração passo a passo

​Operação diária

​Exemplo prático — um dia de dados

​Transações Midaz (Fonte A)

​Extrato SPI do BACEN (Fonte B)

​Resultados do matching

​Análise

​Tratamento de exceções Pix

​Force match

​Ignorar transação

​Devoluções Pix

​Boas práticas

​Métricas-chave

​Próximos passos

Contextos e fontes

Regras de match

Integração com Midaz

Resolução de exceções

Fluxos de transação Pix

Pix enviado (cash-out)

Pix recebido (cash-in)

Configuração passo a passo

Operação diária

Exemplo prático — um dia de dados

Transações Midaz (Fonte A)

Extrato SPI do BACEN (Fonte B)

Resultados do matching

Análise

Tratamento de exceções Pix

Force match

Ignorar transação

Devoluções Pix

Boas práticas

Métricas-chave

Próximos passos