Conciliação de Pix

Este guia mostra como conciliar transações Pix entre o Midaz Ledger e os dados de liquidação do BACEN (o Banco Central do Brasil) usando o Matcher. Ele cobre tanto o Pix enviado (saída de caixa) quanto o Pix recebido (entrada de caixa), da configuração à operação diária e ao tratamento de exceções. Ao fim deste guia, você terá um contexto do Matcher que concilia as suas transações Pix com os extratos de liquidação do SPI do BACEN todo dia.

Fluxos de transações Pix

Os dois fluxos abaixo mostram o que o Matcher precisa conciliar em cada lado.

Pix enviado (saída de caixa)

Fluxo de saída de caixa do Pix enviado — Fluxo de saída de caixa: da iniciação pelo cliente, passando pela liquidação no SPI, até a conciliação no Matcher.

Cliente inicia o Pix: o usuário final dispara um pagamento Pix pelo app ou pela API.
Plugin cria a iniciação: o plugin Pix cria um registro de iniciação e resolve a conta de destino por 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 é efetivada.
Matcher concilia: o Matcher compara a transação efetivada no Midaz com a entrada correspondente no extrato de liquidação do SPI do BACEN.

Pix recebido (entrada de caixa)

Fluxo de entrada de caixa do Pix recebido — Fluxo de entrada de caixa: da notificação recebida do SPI, passando pelo crédito no Midaz, até a conciliação no Matcher.

Pix recebido chega: o SPI envia um webhook síncrono com 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 CREDIT no Midaz para a conta do recebedor.
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 do Midaz com a entrada correspondente no extrato de liquidação do SPI do BACEN.

Nos dois fluxos, o endToEndId é o identificador único que liga a transação do Midaz ao registro de liquidação do BACEN. Essa é a chave principal da conciliação.

Configuração passo a passo

Crie o contexto

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

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

As transações Pix não têm tarifas intermediárias nem liquidações parciais. Um Pix de R

150,00 no Midaz deve aparecer como exatamente R

150,00 no extrato do BACEN. Defina os dois valores de tolerância como zero. Eles são strings decimais, então passe "0".Definir autoMatchOnUpload como false dá a você o controle de quando a correspondência roda. Esse controle importa quando você precisa das duas fontes ingeridas antes de a execução rodar.

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

Crie as fontes

Cada contexto precisa de duas fontes: uma para as transações do Midaz e uma 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 internos de ledger. Não é um conector ativo do Midaz. Você exporta as transações Pix do dia a partir do Midaz, incluindo o metadado endToEndId como coluna plana. Depois você sobe a exportação para esta fonte, na mão ou por um pipeline automatizado. Veja Matcher e Midaz para o fluxo de exportação e 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 você sobe o arquivo de liquidação do SPI na mão ou por um pipeline automatizado todo dia.Cada fonte deve declarar um side (LEFT ou RIGHT). Um contexto concilia a fonte LEFT dele contra a fonte RIGHT dele. Atribua um lado ao Midaz e o outro ao BACEN. Mantenha a atribuição consistente nas duas fontes.

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

Crie os mapas de campo

Os mapas de campo dizem ao Matcher como traduzir os campos de cada fonte para os campos canônicos usados na correspondência.Um mapa de campo é um objeto JSON na forma { "<canonicalKey>": "<sourceColumn>" }. As chaves vêm do vocabulário canônico fechado do Matcher (external_id, amount, currency, date e, opcionais, description, fee_amount, fee_currency). Os valores são os nomes brutos das colunas em cada fonte. As buscas são planas. Um valor de mapeamento deve nomear uma coluna de primeiro nível na linha. Por isso a exportação do Midaz deve carregar endToEndId como uma coluna plana própria (veja Matcher e Midaz — mapeamento de campos personalizado).

external_id é a referência de correspondência entre os 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 de linha locais de um lado (o id da transação no Midaz, o id_liquidacao do BACEN) para external_id. Esses valores nunca batem entre as fontes, então a correspondência por referência nunca acharia uma contraparte.

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

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

Mapa de campo da fonte Midaz:

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

Mapa de campo da fonte BACEN:

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

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

Crie as regras de correspondência

As regras de correspondência definem como o Matcher compara transações entre fontes. Na conciliação de Pix, duas regras cobrem a grande maioria dos cenários.Regra 1 (correspondência exata 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 cerca de 95% dos casos. O endToEndId é único por transação Pix em todo o ecossistema. Uma correspondência por referência, valor, moeda e data dá uma conciliação confirmada com confiança máxima. A regra define caseInsensitive como false porque os valores de endToEndId diferenciam maiúsculas de minúsculas. A regra define referenceMustSet como true, então os dois lados devem carregar o endToEndId antes da comparação. Isso evita falsos positivos apenas por valor e data.Regra 2 (alternativa 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 liquidar no BACEN no dia de calendário seguinte. Esta regra permite uma janela de 1 dia para cobrir cenários de liquidação em D+1. Esta regra depende apenas da correspondência de valor e de moeda. A Regra 1 cuida da comparação do endToEndId.

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

Ative e agende

Com toda a configuração no lugar, ative o contexto e crie um agendamento diário.Ative 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" }'

Crie um agendamento para rodar 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
 }'

Rodar às 07:00 UTC dá margem suficiente para as liquidações em D+1 aparecerem no extrato do BACEN. Também dá tempo de você subir o arquivo diário antes de a execução de correspondência rodar.

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

Operação diária

Depois de configurado, o workflow diário de conciliação segue cinco passos.

Suba o extrato do BACEN

Suba o arquivo de liquidação do SPI do dia anterior para a fonte do BACEN. O Matcher interpreta CSV, JSON, XML e outros formatos do catálogo de formatos dele.

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"

Você pode automatizar este passo com um pipeline que busca o arquivo do SPI e o sobe antes da execução de correspondência agendada.

Suba a exportação do Midaz

Exporte do Midaz as transações Pix efetivadas do dia anterior, incluindo o metadado endToEndId como coluna plana. Suba a exportação para a fonte Midaz do mesmo jeito. Em geral o mesmo pipeline automatiza este passo. Veja Matcher e Midaz para o fluxo de exportação e importação.

O Matcher roda às 07:00 (ou na mão)

A execução agendada roda automaticamente às 07:00 UTC. Para rodar a correspondência na mão, 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 ver os resultados sem commitá-los. Quando estiver satisfeito, rode de novo 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" }'

Revise os resultados

Depois que a execução termina, busque os grupos correspondidos 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 correspondida e a entrada de liquidação do BACEN correspondente, junto com a regra que as correspondeu e a pontuação de confiança.

Resolva as exceções

As transações não conciliadas aparecem como exceções. Elas exigem investigação: uma transação presente em uma fonte mas não na outra, ou uma divergência de valor ou de data além da tolerância configurada.Revise as exceções, determine a causa raiz e resolva-as forçando a correspondência, ignorando ou corrigindo os dados de origem.

Rode sempre um DRY_RUN primeiro ao testar novas regras ou depois de mudanças de configuração. Isso evita que o Matcher comite correspondências indesejadas.

Exemplo prático: um dia de dados

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

Transações do 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 da correspondência

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

Análise

txn-001 e txn-002: correspondência exata por endToEndId, valor, moeda e data. A Regra 1 resolveu essas correspondências com pontuação 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 pontuação de confiança 85. Correspondências por defasagem de data nunca são autoconfirmadas. O par vai para a fila de revisão para uma pessoa confirmar.
txn-004: presente no Midaz mas ausente no BACEN. Possível falha de liquidação ou timeout do SPI. Investigue o status da transação pelo plugin Pix.
liq-8804: presente no BACEN mas ausente no Midaz. Este Pix recebido não chegou ao ledger. Confira a entrega do webhook ou reprocesse a mensagem.

Tratando exceções de Pix

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

Cenário	Causa provável	Ação recomendada
No Midaz, não no BACEN	Falha de liquidação, timeout do SPI, transação rejeitada	Confira o status da transação no plugin Pix. Se foi rejeitada, estorne no Midaz.
No BACEN, não no Midaz	Pix recebido não processado, falha de webhook	Reprocesse a mensagem. Crie uma transação manual se for preciso.
Divergência de valor	Raro no Pix (sem tarifas intermediárias). Possível erro de arredondamento.	Investigue os registros originais. Force a correspondência se a diferença for aceitável.
Divergência de data (>1 dia)	Transação retida, reprocessamento	Confirme que é o mesmo Pix. Force a correspondência ou ignore.

Correspondência forçada

Quando você confirmou que dois registros representam a mesma transação Pix mas o Matcher não conseguiu correspondência automática, use a correspondência forçada.

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 você deve excluir uma transação da conciliação (por exemplo, um lançamento duplicado 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 Forçar correspondência e Ignorar transação para os schemas completos das requisições.

Devoluções de Pix (refunds)

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

O originalEndToEndId que aponta de volta para a transação Pix original
Um novo returnIdentification (rtrId) que identifica a devolução de forma única no SPI

O extrato de liquidação do BACEN inclui as entradas de devolução com os dois identificadores, o que permite ao Matcher conciliá-las com as transações de devolução correspondentes no Midaz. Em volumes baixos de devolução, você pode conciliá-las dentro do mesmo contexto Pix Daily Reconciliation. Em 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.

Iniciar uma devolução por POST /v1/transfers/{id}/refunds é um endpoint do plugin Pix, não um endpoint do Matcher. O Matcher não inicia transferências nem devoluções. Ele apenas concilia as transações resultantes. Cada devolução carrega o originalEndToEndId e um novo returnIdentification para rastreio ponta a ponta, que o Matcher então usa para corresponder a devolução com o extrato de liquidação do BACEN. Para iniciar devoluções, veja a documentação do plugin Pix.

Boas práticas

Use o endToEndId como referência principal

O endToEndId é o identificador único do Pix em todo o ecossistema, da instituição que inicia, passando pelo SPI, até a instituição que recebe. Guarde-o nos metadados da transação no Midaz e garanta que o extrato do BACEN o carregue. Sem ele, a conciliação cai para a correspondência por valor e data, que é bem menos confiável.

Rode a conciliação no dia seguinte

Transações Pix perto do fim do dia podem liquidar no BACEN em D+1. Agendar o Matcher para 07:00 UTC garante que o extrato do BACEN inclua todas as liquidações do dia anterior antes de a correspondência rodar. Isso elimina falsas exceções causadas por timing.

Separe Pix IN e Pix OUT em alto volume

Ao processar volumes altos de Pix, crie dois contextos separados, um para a saída de caixa e um para a entrada de caixa. Isso simplifica a triagem de exceções, dá métricas mais granulares por fluxo e permite agendamento independente, se for preciso.

Monitore a taxa de correspondência

Uma conciliação de Pix saudável chega a mais de 99% de taxa de correspondência automática. Se a taxa cai abaixo de 95%, investigue problemas sistêmicos como falhas do plugin, mudanças de formato do BACEN ou metadados faltando nas transações do Midaz.

Tolerância zero é o padrão

O Pix não tem tarifas intermediárias, liquidações parciais nem encargos de processamento. Se os valores divergem entre Midaz e BACEN, isso indica um problema real, não arredondamento. Mantenha os dois valores, feeToleranceAbs e feeTolerancePct, em zero.

Veja a prévia antes de commitar

Rode sempre um DRY_RUN antes do COMMIT, principalmente depois de mudanças de regra ou de mapa de campo. Isso permite revisar os resultados de correspondência e pegar erros de configuração antes de eles afetarem os dados de produção.

Métricas principais

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

Métrica	Valor saudável	Limite de alerta
Taxa de correspondência automática	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á 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 correspondência

Explore todos os tipos de regra disponíveis e as configurações avançadas de correspondência.

Integração com o Midaz

Conheça o mapeamento automático de campos e a fonte de dados do Midaz Ledger.

Resolvendo exceções

Guia detalhado sobre investigar, forçar correspondências e gerenciar exceções de conciliação.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Conciliação de Pix

Fluxos de transações Pix

Pix enviado (saída de caixa)

Pix recebido (entrada de caixa)

Configuração passo a passo

Operação diária

Exemplo prático: um dia de dados

Transações do Midaz (Fonte A)

Extrato SPI do BACEN (Fonte B)

Resultados da correspondência

Análise

Tratando exceções de Pix

Correspondência forçada

Ignorar transação

Devoluções de Pix (refunds)

Boas práticas

Métricas principais

Próximos passos

Contextos e fontes

Regras de correspondência

Integração com o Midaz

Resolvendo exceções

​Fluxos de transações Pix

​Pix enviado (saída de caixa)

​Pix recebido (entrada de caixa)

​Configuração passo a passo

​Operação diária

​Exemplo prático: um dia de dados

​Transações do Midaz (Fonte A)

​Extrato SPI do BACEN (Fonte B)

​Resultados da correspondência

​Análise

​Tratando exceções de Pix

​Correspondência forçada

​Ignorar transação

​Devoluções de Pix (refunds)

​Boas práticas

​Métricas principais

​Próximos passos

Contextos e fontes

Regras de correspondência

Integração com o Midaz

Resolvendo exceções

Fluxos de transações Pix

Pix enviado (saída de caixa)

Pix recebido (entrada de caixa)

Configuração passo a passo

Operação diária

Exemplo prático: um dia de dados

Transações do Midaz (Fonte A)

Extrato SPI do BACEN (Fonte B)

Resultados da correspondência

Análise

Tratando exceções de Pix

Correspondência forçada

Ignorar transação

Devoluções de Pix (refunds)

Boas práticas

Métricas principais

Próximos passos