Conciliação assistida entre débito e título (F2)

A conciliação assistida aproxima um débito bancário observado de um título a pagar do ERP, mostra a evidência e registra a decisão de um revisor autorizado. O resultado é um ajuste analítico na reserva do diagnóstico, guardado à parte do título.

A Malvo não dá baixa no ERP. Uma confirmação não altera o título, não grava nada no sistema do parceiro e não aumenta o caixa observado. Os eventos payment_match.* informam o estado na Malvo e não ordenam baixa. Se você registrar a baixa no ERP a partir de payment_match.confirmed, faça isso por decisão própria e devolva o payment_match_id na liquidação da próxima carga (veja payment_match_id).

Chaves do módulo

As rotas existem com CONSOLIDATED_INTELLIGENCE_ENABLED e OBLIGATION_IMPORTS_ENABLED ligadas, junto com as de títulos. Todas nascem desligadas.

Chave	Padrão	Efeito
`FINANCIAL_PROFILE_INFERRED_ABSORPTION_ENABLED`	`false`	Liga a absorção `inferred_exact`. Desligada, só `explicit_reference` absorve sem revisão; o resto vai para `manual_review`
`FINANCIAL_PROFILE_PAYMENT_MATCH_DAYS_BEFORE_DUE`	`7`	Dias antes do vencimento em que um débito é candidato
`FINANCIAL_PROFILE_PAYMENT_MATCH_DAYS_AFTER_DUE`	`30`	Dias depois do vencimento em que um débito é candidato

Candidatos

Um débito é candidato quando, ao mesmo tempo:

é de conta BANK de uma fonte vinculada ao perfil, com consentimento AUTHORISED e a permissão ACCOUNTS_TRANSACTIONS_READ;
tem, na API Contas, creditDebitType = DEBITO e completedAuthorisedPaymentType = TRANSACAO_EFETIVADA. LANCAMENTO_FUTURO e TRANSACAO_PROCESSANDO ficam de fora;
está em BRL, não é transferência entre contas próprias, não é estorno nem foi estornado e não está em revisão de representação.

O título candidato está ativo na fotografia, é payable, em BRL, open ou partially_settled, com valor em aberto maior que zero. A janela é civil em America/Sao_Paulo, do vencimento menos 7 dias ao vencimento mais 30 dias, inclusive. Ela não desloca o vencimento.

Evidência e estado inicial

Critério (`criteria`)	Regra
`due_date_window`	Débito dentro da janela (sempre presente)
`counterparty_document`	CNPJ ou CPF do favorecido do débito igual ao da contraparte do título. Documentos diferentes descartam o par
`payment_reference`	`source_reference` ou `bank_obligation_reference` do título igual à referência do pagamento ou contida na descrição do débito
`amount_exact`	Saldo livre do débito igual ao saldo livre do título
`amount_partial`	Débito menor que o título

`evidence_level`	Combinação	Estado
`high`	`amount_exact` + documento ou referência	`suggested`
`medium`	`amount_partial` + documento ou referência	`suggested`
`medium`	Débito maior que o título + documento ou referência	`review_required` (`amount_difference`)
`low`	`amount_exact` sem documento nem referência	`review_required` (`evidence_incomplete`)

Sem valor exato e sem documento ou referência, não há sugestão: nome, valor ou data isolados não comprovam pagamento. Quando um débito ou um título tem mais de um candidato e o par não é o único melhor dos dois lados, todos ficam review_required (ambiguous_candidates), com as alternativas em alternatives. Não há percentual de probabilidade. Ausência de candidato não prova que o título está em aberto na realidade. divergences lista o que enfraquece a evidência: counterparty_missing e amount_exceeds_outstanding.

Estados

`state`	`label`
`suggested`	Possível pagamento — aguardando confirmação
`confirmed`	Pagamento confirmado
`review_required`	Correspondência em revisão
`rejected`	Correspondência rejeitada
`reversed`	Correspondência revertida

O payment_match_id é estável: a mesma sugestão (mesmo débito e mesmo título) mantém o id e ganha version nova quando a evidência muda. Sugestão que deixa de ser candidata sai da lista (withdrawn: true). Rejeição e reversão guardam uma impressão digital da evidência: o par não volta como sugestão enquanto ela for a mesma. review_reason diz por que a correspondência está em revisão:

`review_reason`	Quando
`ambiguous_candidates`, `evidence_incomplete`, `amount_difference`	Na sugestão (tabela acima)
`reduction_mismatch`, `settlement_mismatch`, `title_changed`, `title_reappeared`, `multiple_allocations`, `inference_disabled`, `inference_expired`	Na absorção, quando a carga nova não permite absorver sem revisão
`transaction_ineligible`, `transaction_changed`	O débito confirmado sumiu, mudou ou deixou de ser efetivado
`source_revoked`	A fonte bancária do débito foi revogada
`absorption_reversed`	Um revisor desfez a absorção

Rotas

`GET /financial-profiles/{id}/payment-matches?state=&obligation_id=&transaction_id=&include_withdrawn=&page=&pageSize=`

Reavalia candidatos e confirmações e lista as correspondências, paginadas. A reavaliação lê só o banco da Malvo: não chama instituição nem dispara sincronização. reserves traz, por título com alocação ativa, o valor em aberto do ERP, o ajuste aplicável e a reserva efetiva.

Parâmetro	Valores
`state`	`suggested`, `confirmed`, `rejected`, `review_required` ou `reversed`
`obligation_id`, `transaction_id`	UUID
`include_withdrawn`	`true` ou `false` (padrão)

Valor fora da lista responde 400 VALIDATION_ERROR.

Correspondências 200

{
  "financial_profile_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "reserves": [],
  "total": 1,
  "total_pages": 1,
  "page": 1,
  "results": [
    {
      "payment_match_id": "3f2b8c1e-9d4a-4e6b-8a71-2c5d0e9f4b13",
      "financial_profile_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "state": "suggested",
      "label": "Possível pagamento — aguardando confirmação",
      "version": 1,
      "withdrawn": false,
      "transaction_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "transaction_version": "9b2e4f6a8c0d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f",
      "obligation_id": "e8b1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
      "external_obligation_id": "T-1001",
      "obligation_version_id": "11f2e3d4-c5b6-4a79-8e81-92a3b4c5d6e7",
      "evidence_level": "medium",
      "criteria": [
        "amount_partial",
        "counterparty_document",
        "due_date_window"
      ],
      "divergences": [],
      "alternatives": [],
      "review_reason": null,
      "absorption_basis": null,
      "confirmation": null,
      "rejection": null,
      "reversal": null,
      "allocations": [],
      "created_at": "2026-10-13T13:20:00Z",
      "updated_at": "2026-10-13T13:20:00Z"
    }
  ]
}

`GET /financial-profiles/{id}/payment-matches/{matchId}`

Uma correspondência, com as alocações e o efeito de cada uma na reserva. Correspondência de outro perfil ou aplicação responde 404 NOT_FOUND.

Correspondência confirmada 200

{
  "payment_match_id": "3f2b8c1e-9d4a-4e6b-8a71-2c5d0e9f4b13",
  "financial_profile_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "state": "confirmed",
  "label": "Pagamento confirmado",
  "version": 2,
  "withdrawn": false,
  "transaction_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "transaction_version": "9b2e4f6a8c0d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f",
  "obligation_id": "e8b1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "external_obligation_id": "T-1001",
  "obligation_version_id": "11f2e3d4-c5b6-4a79-8e81-92a3b4c5d6e7",
  "evidence_level": "medium",
  "criteria": [
    "amount_partial",
    "counterparty_document",
    "due_date_window"
  ],
  "divergences": [],
  "alternatives": [],
  "review_reason": null,
  "absorption_basis": null,
  "confirmation": {
    "at": "2026-10-13T14:00:00Z",
    "by": "revisor@parceiro.example",
    "reason": "Conferido com o extrato"
  },
  "rejection": null,
  "reversal": null,
  "allocations": [
    {
      "transaction_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "transaction_version": "9b2e4f6a8c0d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f",
      "transaction_date": "2026-10-13T13:05:00Z",
      "account_id": "6d7e8f90-a1b2-4c3d-8e4f-5a6b7c8d9e0f",
      "obligation_id": "e8b1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
      "obligation_version_id": "11f2e3d4-c5b6-4a79-8e81-92a3b4c5d6e7",
      "amount": "600.00",
      "active": true,
      "absorption_basis": null,
      "absorbed_at": null,
      "reserve_effect": {
        "status": "applied",
        "reason": null,
        "position_reference": "b7c8d9e0-f1a2-4b3c-9d4e-5f6a7b8c9d0e",
        "position_at": "2026-10-13T16:00:00Z",
        "adjustable_amount": "600.00"
      }
    }
  ],
  "created_at": "2026-10-13T13:20:00Z",
  "updated_at": "2026-10-13T14:00:00Z"
}

`POST /financial-profiles/{id}/payment-matches/{matchId}/confirm`

Confirma a correspondência com alocações explícitas.

Confirmar

{
  "version": 1,
  "actor": "revisor@parceiro.example",
  "reason": "Conferido com o extrato",
  "allocations": [
    {
      "transaction_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "transaction_version": "9b2e4f6a8c0d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f",
      "obligation_id": "e8b1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
      "obligation_version_id": "11f2e3d4-c5b6-4a79-8e81-92a3b4c5d6e7",
      "amount": "600.00"
    }
  ]
}

`POST /financial-profiles/{id}/payment-matches/{matchId}/reject`

Rejeita uma sugestão com motivo. A rejeição não muda reserva e o par não volta como sugestão sem mudança material de evidência.

Rejeitar

{
  "version": 1,
  "actor": "revisor@parceiro.example",
  "reason": "Débito de outro fornecedor com o mesmo CNPJ do grupo"
}

`POST /financial-profiles/{id}/payment-matches/{matchId}/reverse`

Reverte a confirmação (target: "confirmation", padrão) ou só a absorção (target: "absorption"). Reverter a confirmação desativa as alocações: o débito fica livre de novo e a reserva volta ao valor do ERP. Reverter a absorção devolve a correspondência para revisão (absorption_reversed).

Reverter

{
  "version": 2,
  "actor": "revisor@parceiro.example",
  "reason": "Débito estornado pelo banco",
  "target": "confirmation"
}

Decisões

As três ações exigem:

a permissão payment_matches.review da aplicação, desligada por padrão; o dono ou um admin do time concede no console;
o header Idempotency-Key (^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$);
version (a versão atual da correspondência), actor (até 128 caracteres) e reason (até 500).

allocations, difference_reason e resolution só valem no confirm; target só no reverse. transaction_version e obligation_version_id vêm do GET. A resposta 200 é a correspondência atualizada, no formato do GET. Reenvio com a mesma chave e o mesmo corpo devolve 200 com o estado atual, sem novo efeito.

Alocações

Uma confirmação pode ter várias alocações: parte de um débito, vários débitos para um título ou um débito para vários títulos. Ela precisa incluir o débito ou o título da sugestão.

Valor decimal positivo com 2 a 4 casas; par débito-título sem repetição.
A soma das alocações ativas de um débito, em todas as correspondências, vai até o valor do débito.
A soma das alocações ativas e ainda não absorvidas de um título vai até o valor em aberto do ERP.
Débito com sobra depois da confirmação exige difference_reason: juros, multa, desconto ou tarifa não são distribuídos em silêncio.

A confirmação é serializada por perfil. Dois revisores que disputam o mesmo débito são atendidos em série: o segundo recebe 409 e nada é gravado. O mesmo pagamento nunca é reservado duas vezes.

Erros

Situação	Resposta
Sem `Idempotency-Key`, corpo inválido ou campo fora da ação	`400 VALIDATION_ERROR`
Alocação com valor inválido ou par repetido	`400 INVALID_ALLOCATION`
Sem a permissão `payment_matches.review`	`403 PERMISSION_REQUIRED`
Correspondência de outro perfil ou aplicação	`404 NOT_FOUND`
Mesma chave com corpo diferente	`409 IDEMPOTENCY_KEY_CONFLICT`
`version` diferente da atual	`409 MATCH_VERSION_CONFLICT`
`transaction_version` ou `obligation_version_id` diferente do atual	`409 TRANSACTION_VERSION_CONFLICT`, `409 OBLIGATION_VERSION_CONFLICT`
Estado que não aceita a ação, ou nenhuma absorção a reverter	`409 MATCH_STATE_CONFLICT`
Alocações acima do débito ou do valor em aberto	`409 ALLOCATION_EXCEEDS_TRANSACTION`, `409 ALLOCATION_EXCEEDS_OBLIGATION`
Débito inelegível, de outro perfil ou de fonte sem autorização	`422 TRANSACTION_NOT_ELIGIBLE`
Título fora da fotografia, quitado, cancelado ou de outra natureza	`422 OBLIGATION_NOT_ELIGIBLE`
Alocações sem o débito nem o título da sugestão	`422 ALLOCATION_UNRELATED`
Débito com sobra sem `difference_reason`	`422 DIFFERENCE_REASON_REQUIRED`
Confirmada em revisão sem `resolution`	`422 RESOLUTION_REQUIRED`
`resolution` com alocações diferentes das confirmadas	`422 ALLOCATIONS_CHANGED`

Nenhuma recusa muda alocação, reserva ou estado.

409 MATCH_VERSION_CONFLICT

{
  "code": 409,
  "message": "version is not the current payment match version",
  "codeDescription": "MATCH_VERSION_CONFLICT",
  "requestId": "req-sintetico-0005"
}

Efeito na reserva

Uma sugestão não muda valores. Uma confirmação só reduz a reserva quando o débito já está refletido na posição bancária usada. A posição é o updateDateTime do saldo da API Contas, nunca o horário em que a Malvo recebeu o dado.

`reserve_effect.status`	Quando	Ajuste
`applied`	Confirmada, não absorvida, e a última posição da conta do débito é posterior ao débito	Valor alocado
`awaiting_position`	Sem posição do provedor (`position_not_verifiable`), posição igual ou anterior ao débito (`position_before_debit`) ou débito só com data e posição do mesmo dia (`same_day_unordered`)	Zero
`suspended`	Correspondência em `review_required`	Zero
`absorbed`	O ERP já incorporou a baixa	Zero
`none`	Alocação inativa (revertida)	Zero

reserve_effect.position_reference e position_at identificam o saldo usado, para o corte ser verificável. A reserva efetiva do título é o valor em aberto do ERP menos os ajustes aplicados, nunca menor que zero:

reserves com confirmação aplicada

[
  {
    "obligation_id": "e8b1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
    "external_obligation_id": "T-1001",
    "obligation_version_id": "11f2e3d4-c5b6-4a79-8e81-92a3b4c5d6e7",
    "outstanding_amount": "1000.00",
    "adjustable_amount": "600.00",
    "effective_reserve": "400.00",
    "review_pending": false,
    "payment_match_ids": [
      "3f2b8c1e-9d4a-4e6b-8a71-2c5d0e9f4b13"
    ]
  }
]

Absorção pela origem

Quando uma carga nova do ERP é ativada, cada título que ganhou versão e tem alocação confirmada ainda não absorvida passa por esta ordem, registrada em absorption_basis:

explicit_reference: alguma liquidação da versão nova traz o payment_match_id. Absorve sem revisão.
inferred_exact (com FINANCIAL_PROFILE_INFERRED_ABSORPTION_ENABLED): uma única correspondência confirmada com uma única alocação, nenhuma em revisão no título, primeira versão nova em até 30 dias da confirmação, valor em aberto reduzido exatamente pelo alocado (ou título settled com aberto anterior igual ao alocado), liquidação nova única com o mesmo valor e settled_at igual ou posterior ao débito, sem mudança de valor original, vencimento, moeda ou contraparte, sem reabertura nem cancelamento, e débito na mesma versão confirmada.
manual_review: qualquer outro caso. A correspondência vai para review_required com o motivo e o ajuste fica suspenso: a reserva volta a ser o valor em aberto do ERP, sem subtrair de novo e sem ficar negativa.

Carga com o título igual não mexe na correspondência. Título que sai da fotografia mantém a alocação (a ausência não prova baixa) e o débito continua consumido.

Momento	ERP em aberto	Alocação	Ajuste aplicado	Reserva efetiva
Carga de 12/10	`1000.00`	—	`0.00`	`1000.00`
Confirmação em 13/10, débito na posição	`1000.00`	`600.00`	`600.00`	`400.00`
Carga de 14/10 com aberto `400.00` (explícita ou inferida)	`400.00`	`600.00`	`0.00`	`400.00`
Carga de 14/10 com aberto `450.00` (liquidação de `550.00`)	`450.00`	`600.00`	`0.00` (`manual_review`)	`450.00`

As cargas de exemplo estão no contrato v1.

Revisão depois da absorção

Uma correspondência confirmada que foi para revisão aceita confirm com resolution:

absorbed: a baixa do ERP é esse pagamento; as alocações ficam com absorption_basis: "manual_review";
keep: o pagamento ainda não está no ERP; as alocações seguem ativas, desde que não passem do novo valor em aberto.

O corpo repete as alocações confirmadas (mesmos pares e valores) com as versões atuais.

Resolver revisão

{
  "version": 3,
  "actor": "revisor@parceiro.example",
  "reason": "Baixa de 550,00 no ERP corresponde a este débito com desconto",
  "resolution": "absorbed",
  "allocations": [
    {
      "transaction_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "transaction_version": "9b2e4f6a8c0d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f",
      "obligation_id": "e8b1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
      "obligation_version_id": "33b4c5d6-e7f8-4091-a2b3-c4d5e6f70819",
      "amount": "600.00"
    }
  ]
}

Estorno, correção e revogação

A cada consulta, as confirmações são conferidas contra a transação atual. Débito que sumiu, deixou de ser efetivado ou mudou de versão vai para review_required e o ajuste fica suspenso. A revogação da fonte bancária retira as sugestões e manda as confirmações para revisão (source_revoked). O histórico de decisões é imutável e continua consultável.

Eventos

Cada transição publica um evento payment_match.* (veja Eventos financeiros). O evento traz ids, estado, versão e motivo, sem valores. Busque os valores na API.

Retenção

Sugestões não confirmadas e rejeições ficam 90 dias desde a última mudança. Confirmações ficam com o perfil. A trilha de auditoria (payment_match.confirmed, rejected, reversed) não guarda valores, e nenhum valor vai para log.

Base normativa

API Contas do Open Finance Brasil 2.5.1 (api_accounts_-_open_finance_brasil/2.5.1.yaml, lido em 12/10/2026): creditDebitType (DEBITO), completedAuthorisedPaymentType (TRANSACAO_EFETIVADA, LANCAMENTO_FUTURO, TRANSACAO_PROCESSANDO), transactionAmount com padrão ^\d{1,15}\.\d{2,4}$ e AccountBalancesData.updateDateTime como posição.
Contrato obligations.v1: liquidações com payment_match_id e decimais textuais.
IN BCB nº 615/2025, art. 1º e 3º, e Manual de APIs v7.0, seção 5.2, item V: a conciliação não faz chamada a instituição.
Lei nº 13.709/2018 (LGPD), art. 6º, 7º, 15, 16 e 18, e a política de retenção da Malvo aprovada em 10/10/2026.
PRD v1.3, seções 10 e 14 (FR-033; AC-036, AC-039 a AC-047 e AC-055 a AC-057). A janela e os níveis de evidência são o ponto de partida do PRD e serão calibrados com os parceiros.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Conciliação assistida entre débito e título (F2)

Chaves do módulo

Candidatos

Evidência e estado inicial

Estados

Rotas

`GET /financial-profiles/{id}/payment-matches?state=&obligation_id=&transaction_id=&include_withdrawn=&page=&pageSize=`

`GET /financial-profiles/{id}/payment-matches/{matchId}`

`POST /financial-profiles/{id}/payment-matches/{matchId}/confirm`

`POST /financial-profiles/{id}/payment-matches/{matchId}/reject`

`POST /financial-profiles/{id}/payment-matches/{matchId}/reverse`

Decisões

Alocações

Erros

Efeito na reserva

Absorção pela origem

Revisão depois da absorção

Estorno, correção e revogação

Eventos

Retenção

Base normativa

​Chaves do módulo

​Candidatos

​Evidência e estado inicial

​Estados

​Rotas

​GET /financial-profiles/{id}/payment-matches?state=&obligation_id=&transaction_id=&include_withdrawn=&page=&pageSize=

​GET /financial-profiles/{id}/payment-matches/{matchId}

​POST /financial-profiles/{id}/payment-matches/{matchId}/confirm

​POST /financial-profiles/{id}/payment-matches/{matchId}/reject

​POST /financial-profiles/{id}/payment-matches/{matchId}/reverse

​Decisões

​Alocações

​Erros

​Efeito na reserva

​Absorção pela origem

​Revisão depois da absorção

​Estorno, correção e revogação

​Eventos

​Retenção

​Base normativa

Chaves do módulo

Candidatos

Evidência e estado inicial

Estados

Rotas

`GET /financial-profiles/{id}/payment-matches?state=&obligation_id=&transaction_id=&include_withdrawn=&page=&pageSize=`

`GET /financial-profiles/{id}/payment-matches/{matchId}`

`POST /financial-profiles/{id}/payment-matches/{matchId}/confirm`

`POST /financial-profiles/{id}/payment-matches/{matchId}/reject`

`POST /financial-profiles/{id}/payment-matches/{matchId}/reverse`

Decisões

Alocações

Erros

Efeito na reserva

Absorção pela origem

Revisão depois da absorção

Estorno, correção e revogação

Eventos

Retenção

Base normativa