MED na integração Pix

Na API da xFlow, o MED, Mecanismo Especial de Devolução do Pix, chega por webhook. Quando uma infração é aberta contra um pagamento, a xFlow envia dispute.opened. No desfecho, envia dispute.accepted, se a defesa foi aceita, ou dispute.rejected, se foi rejeitada. A defesa não é feita pela API: ela é respondida no painel, em Disputas, dentro do prazo. Abaixo, o que a documentação da API mostra, o que ela não mostra e o que a sua integração deve ter pronto.

O que a documentação da xFlow mostra

O que está confirmado na documentação, em 25/10/2026:

• Os eventos dispute.* são disparados quando a conta tem MED ativo. Contas em plano sem MED não precisam agir: a equipe da xFlow cuida.
• A defesa é respondida no painel, em Disputas, dentro do prazo.
• As entregas seguem o padrão dos outros webhooks: POST JSON com corpo { event, data, createdAt }, header x-webhook-event e assinatura x-webhook-signature, o HMAC-SHA256 do corpo cru.

O que a documentação não traz: o formato do data dos eventos dispute.*, um endpoint para listar ou consultar disputas, um endpoint para enviar a defesa e o efeito de uma disputa no saldo. Por isso, este guia não supõe campos. A cobrança tem ainda os status under_review (em análise) e blocked (bloqueada), mas a documentação não os liga ao MED; trate os dois como "não liberar", como explica o guia de como saber se o Pix foi pago pela API.

Como o MED funciona, pelas regras do Pix

O MED está no Regulamento do Pix, capítulo XI, seção II, em vigor desde 16/11/2021. Os pontos que importam para quem recebe:

• Para que serve. Devolver um Pix quando há fundada suspeita de fraude, quando há falha operacional de um participante ou, desde a Resolução BCB nº 402/2024, em erros de autorização do Pix Automático (art. 41-B).
• O que fica de fora. Controvérsias sobre o negócio, como produto diferente do esperado, e pagamentos que foram para a conta de um terceiro de boa-fé (art. 41-B, § 1º).
• Bloqueio. O PSP de quem recebeu bloqueia o valor pedido ou, se o saldo for menor, o que houver na conta (art. 41-D). Desde 1º/7/2026, pela Resolução BCB nº 559/2026, o bloqueio é feito logo que a notificação chega e é completado sempre que entra dinheiro na conta, até o valor pedido ou até o fim do procedimento.
• Aviso. Quem recebeu é avisado do bloqueio e da devolução (art. 41-F).

O FAQ do Banco Central sobre o Mecanismo Especial de Devolução, consultado em 25/10/2026, completa: a vítima pede o MED na instituição dela em até 80 dias da data do Pix, as instituições envolvidas avaliam a notificação em até 7 dias e, se a fraude for confirmada e houver saldo, o dinheiro volta, inteiro ou em parte.

Nas regras do Pix, o bloqueio acontece na conta que recebeu o Pix, no PSP dela. Como isso aparece no seu saldo da xFlow, a documentação não detalha. Acompanhe pelo painel, em Disputas.

O que preparar na integração

1. Receber e guardar o evento inteiro

Como o data não é documentado, guarde o corpo cru de cada dispute.* e avise o time. Não tente dar baixa automática com base em campos que você supõe. Em Node.js com Express:

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();

app.post("/webhooks/xflow", express.raw({ type: "application/json" }), async (req, res) => {
  const esperado = "sha256=" + createHmac("sha256", process.env.XFLOW_WEBHOOK_SECRET)
    .update(req.body).digest("hex");
  const recebido = req.get("x-webhook-signature") ?? "";
  if (esperado.length !== recebido.length ||
      !timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido))) {
    return res.sendStatus(401);
  }

  const evento = req.get("x-webhook-event") ?? "";
  if (evento.startsWith("dispute.")) {
    await guardarEventoBruto(evento, req.body.toString("utf8")); // corpo inteiro, sem filtrar
    await avisarTime(evento); // fila, e-mail ou chat: a defesa é feita no painel
  }
  res.sendStatus(200);
});

Responda 2xx rápido: sem isso, a entrega é reenviada até 3 vezes. Por isso guardarEventoBruto precisa aceitar a mesma entrega duas vezes sem duplicar o caso. A validação da assinatura está explicada em webhook Pix.

2. Ter as evidências à mão

A defesa é no painel, mas os dados vêm do seu sistema e da API. Para cada venda, guarde o que liga o pedido ao pagamento:

• o id da cobrança e o seu external_reference;
• customer, o que você informou ao cobrar, e payer, quem de fato pagou, com nome, documento e banco informados pelo PSP;
• pix.endToEnd, o End-to-end ID que identifica o Pix;
• paidAt e as provas de entrega do seu lado: acesso liberado, rastreio, conversa com o cliente.

GET /api/v1/charges/{id} devolve todos esses campos de uma cobrança paga. Um payer diferente do customer não prova fraude, mas merece atenção na análise.

3. Acompanhar o saldo antes de pagar

GET /api/v1/balance separa o saldo available do reserved, e GET /api/v1/company traz os campos reservePercent e reserveDays da conta. Se você faz saques automáticos, como repasses a parceiros, confira o available antes de cada ciclo em vez de supor o valor. Um saque acima do disponível volta como 422 transfer_failed.

4. Devolver por conta própria quando for o caso

Se você mesmo identificar que um pagamento veio de fraude, ou que o cliente pagou em dobro, o caminho é o estorno: POST /api/v1/charges/{id}/refund devolve o valor total à conta que pagou, uma vez por cobrança, até 90 dias depois do pagamento. O estorno é seu; o MED é pedido pelo pagador no banco dele. As regras estão em estorno Pix por API.

5. Conciliar o desfecho

Dê ao pedido estados próprios para o caso: em disputa, disputa ganha, disputa perdida. Ligue cada evento ao pedido pelo registro que o time fez ao abrir o caso. O efeito financeiro de uma disputa perdida não está na documentação da API, então confira no painel antes de fechar o mês. O raciocínio de ligar cada movimento ao seu pedido está em conciliação de pagamentos.

6. Split e contas de terceiros

Se as suas cobranças usam split, a documentação não diz como uma disputa afeta a parte de cada recebedor. Combine essa regra com a equipe da xFlow antes de operar em volume.

Checklist rápido

1. Assinar dispute.opened, dispute.accepted e dispute.rejected em Integrações > Webhooks.
2. Guardar o corpo cru de cada evento e avisar o time na hora.
3. Manter payer, pix.endToEnd e as provas de entrega ligados a cada pedido.
4. Conferir o saldo antes de cada ciclo de saques.
5. Responder a defesa no painel, em Disputas, dentro do prazo.

Conteúdo informativo, atualizado em 25/10/2026. Não substitui orientação jurídica.