Disputas (MED)

Liste contestações abertas pelo Bacen, consulte detalhes e envie evidências para defender suas transações. Para o conceito completo, veja MED — Mecanismo Especial de Devolução.

Listar disputas

GET/v1/disputes

Retorna todas as disputas do merchant autenticado, paginadas e filtráveis.

Query params

Query (opcional)

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string[]	Não	OPENED, RESPONDED, RESOLVED_WON, RESOLVED_LOST, EXPIRED`Ex: "OPENED"`
`type`	string	Não	MED, CHARGEBACK, REFUND_REQUEST`Ex: "MED"`
`startDate`	string	Não	Filtro por data inicial (YYYY-MM-DD)`Ex: "2026-05-01"`
`endDate`	string	Não	Filtro por data final (YYYY-MM-DD)`Ex: "2026-05-31"`
`page`	number	Não	Página (default 1)`Ex: 1`
`limit`	number	Não	Itens por página (default 20)`Ex: 20`

Resposta

HTTP 200 OK
{
  "success": true,
  "data": [
    {
      "id": "9b1c...",
      "type": "MED",
      "status": "OPENED",
      "amount": 150.50,
      "balanceDeducted": 145.99,
      "reason": "Pagador alega não reconhecimento da transação",
      "deadline": "2026-06-10T23:59:59.000Z",
      "merchantResponse": null,
      "evidenceUrls": [],
      "respondedAt": null,
      "result": null,
      "resolvedAt": null,
      "transaction": {
        "chargeId": "a1b2c3d4...",
        "externalId": "txid_abc123",
        "externalReference": "ORDER-12345",
        "amount": 150.50,
        "netAmount": 145.99,
        "method": "PIX",
        "customer": { "name": "João da Silva", "cpf": "12345678901" },
        "paidAt": "2026-05-20T14:23:00.000Z"
      },
      "createdAt": "2026-05-26T10:15:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Detalhe de uma disputa

GET/v1/disputes/{disputeId}

Retorna os dados completos de uma disputa específica.

Use este endpoint para obter o motivo, prazo, status e — se já respondida — as evidências enviadas. Disputas de outros merchants retornam 404.

Enviar evidências (responder MED) — armazenamento local

POST/v1/disputes/{disputeId}/respond

Registra descrição + URLs de evidências NO NOSSO sistema (sem encaminhar ao gateway).

Atenção: este endpoint apenas armazena a sua resposta no nosso sistema — ele não encaminha a evidência ao gateway upstream. Para gateways que suportam contestação ativa via API (ex: 3xpay), use POST /v1/disputes/{id}/forward-to-gateway.

Parâmetros

Body (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
`description`	string	Sim	Descrição da defesa (máx. 5000 caracteres). Explique por que a transação é legítima.`Ex: "Cliente confirmou compra via WhatsApp"`
`evidenceUrls`	string[]	Não	Até 10 URLs publicamente acessíveis com evidências (PDFs, imagens). Não armazenamos os arquivos — guardamos apenas as URLs.`Ex: ["https://...pdf", "https://...png"]`

Exemplos

curl -X POST "https://api.activepayments.com.br/api/v1/disputes/{disputeId}/respond" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Transação legítima — cliente confirmou compra via WhatsApp. Veja evidências anexas.",
    "evidenceUrls": [
      "https://meudominio.com/evidencias/log-ip-abc123.png",
      "https://meudominio.com/evidencias/conversa-cliente.pdf",
      "https://meudominio.com/evidencias/nota-fiscal.pdf"
    ]
  }'

Códigos de erro

Código	Quando ocorre
`400`	Disputa em status que não aceita resposta (ex: já resolvida ou expirada).
`403`	A disputa pertence a outro merchant.
`404`	Disputa não encontrada.

Encaminhar ao gateway (contestação ativa via API)

POST/v1/disputes/{disputeId}/forward-to-gateway

Encaminha descrição + arquivo de evidência ao gateway upstream (3xpay etc) via API.

Diferente de /respond, este endpoint de fato envia a defesa ao gateway upstream para análise formal. Suportado apenas em gateways que disponibilizam API de contestação ativa.

Parâmetros (Body JSON)

Body

Parâmetro	Tipo	Obrigatório	Descrição
`description`	string	Sim	Texto da defesa, máx 2000 caracteres.`Ex: "Cliente confirmou compra via WhatsApp"`
`fileBase64`	string	Não	Arquivo de evidência em base64 (sem prefixo data:). Máx ~10MB. Obrigatório para 3xpay.`Ex: "JVBERi0xLjQKJ..."`
`fileName`	string	Não	Nome do arquivo com extensão. Será sanitizado (path traversal removido).`Ex: "comprovante.pdf"`
`fileMimeType`	string	Não	MIME type. Aceitos apenas: application/pdf, image/jpeg, image/png, image/gif, image/webp.`Ex: "application/pdf"`

Validações de segurança

Tamanho máximo: 10MB descompactado.
MIME type restrito a PDF e imagens estáticas — SVG, HTML, executáveis e arquivos Office são bloqueados.
Magic bytes verificados — o conteúdo deve bater com o MIME type informado. Rejeitamos arquivos renomeados.
Nome do arquivo é sanitizado (remove path traversal, caracteres especiais e garante extensão coerente).

Webhooks relacionados

charge.dispute_opened — Nova disputa criada. Reaja imediatamente.
charge.dispute_resolved — Resolução final (campo result: WON, LOST ou EXPIRED).

Configure seus endpoints em Webhooks.