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)

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 BTG/SPI.
Liquidação confirmada — O BTG 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)

Pix de entrada chega — O SPI/BTG 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.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",
  "config": {
    "ledger_id": "your-ledger-id",
    "currency": "BRL"
  }
}

Quando o Midaz está integrado com o Matcher (veja Integração com Midaz), as transações são ingeridas automaticamente via sincronização orientada a eventos. Nenhum upload manual é necessário para esta fonte.Fonte B — Extrato SPI do BACEN (tipo CUSTOM):

{
  "name": "BACEN SPI Settlement Extract",
  "type": "CUSTOM",
  "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.

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.A tabela a seguir mostra o mapeamento entre os campos canônicos do Matcher e os campos de cada fonte:

Campo do Matcher	Midaz (automático)	Extrato BACEN (mapa de campos)
`transaction_id`	`id`	`id_liquidacao`
`amount`	`amount`	`valor`
`currency`	`asset_code`	`moeda`
`date`	`created_at`	`data_liquidacao`
`reference`	`metadata.endToEndId`	`end_to_end_id`

Quando o Midaz está integrado com o Matcher, os campos padrão são mapeados automaticamente. O endToEndId fica nos metadados da transação e requer um override de mapeamento de campo customizado nas configurações da fonte (veja Integração com Midaz — mapeamento de campos customizado):Fonte Midaz — mapa de campos com override do endToEndId:

{
  "mapping": {
    "id": "transaction_id",
    "amount": "amount",
    "asset_code": "currency",
    "created_at": "date",
    "metadata.endToEndId": "reference"
  }
}

Fonte BACEN — mapa de campos:

{
  "mapping": {
    "id_liquidacao": "transaction_id",
    "valor": "amount",
    "moeda": "currency",
    "data_liquidacao": "date",
    "end_to_end_id": "reference"
  }
}

Veja Criar mapa de campos para o schema completo da requisição e Integração com Midaz para detalhes sobre o mapeamento automático de campos.

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. O matchScore menor de 85 sinaliza que esses matches devem ser revisados com um pouco mais de atenção, embora ainda sejam válidos. 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/config/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 aceita os formatos CSV e JSON.

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.

Dados do Midaz disponíveis automaticamente

Com a integração do Midaz configurada, as transações são continuamente ingeridas no Matcher conforme são confirmadas. Nenhum upload manual é necessário para a Fonte A. Veja Integração com Midaz para detalhes de configuraçã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	endToEndId	Valor	Tipo	Data
txn-001	E123456789202603170001	150.00	Pix OUT	2026-03-17 10:15
txn-002	E987654321202603170042	3200.50	Pix IN	2026-03-17 11:30
txn-003	E555666777202603170099	89.90	Pix OUT	2026-03-17 23:58
txn-004	E111222333202603170007	500.00	Pix IN	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) resolveu este com score de confiança 85.
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.

O plugin Pix suporta a iniciação de devoluções via POST /v1/transfers/{id}/refunds. Cada devolução carrega o originalEndToEndId e um novo returnIdentification para rastreabilidade ponta a ponta.

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.

Introduction

Primeiros passos

Configurações

Reconciliação diária

Guias de casos de uso

Integrações

Referência

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

Introduction

Primeiros passos

Configurações

Reconciliação diária

Guias de casos de uso

Integrações

Referência

​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