Evento charge.dispute.updated

Evento `charge.dispute.updated`

Disparado quando um dispute muda de estado, tem campos de evidence preenchidos ou limpos, ou tem a defesa enviada. data.previous_attributes traz apenas os campos alterados com os valores anteriores. Use este evento para acompanhar a evolução do caso enquanto ele ainda não teve decisão final: evidência preenchida ou limpa, envio de defesa — manual ou automático no fim do prazo —, entrada em análise, atualização de prazo ou mudança em campos públicos do dispute.

O payload em data.object é sempre o dispute completo e atual. O diff em data.previous_attributes mostra apenas o que mudou, como status ou evidence_details.

Quando acontece

Situação	Como aparece no payload
Campo de evidência preenchido ou limpo	O campo muda em `evidence` e `evidence_details.has_evidence` acompanha.
Defesa enviada (por você ou automaticamente no fim do prazo)	`evidence_details.submission_count` vira `1` e `data.object.status: "under_review"`.
Dispute entrou em análise	`previous_attributes.status: "needs_response"` e `data.object.status: "under_review"`.
Prazo ou evidência mudou	`previous_attributes.evidence_details` traz o valor anterior.
Metadata foi atualizada	`previous_attributes.metadata` mostra o valor anterior da metadata alterada.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (dp_*) para atualizar o caso local.
Atualize o estado local usando data.object.status, não apenas o diff.
Use data.previous_attributes para auditoria e para disparar notificações condicionais.
Quando status for under_review, considere a defesa enviada e aguarde charge.dispute.closed para o resultado final.
O envio automático no fim do prazo chega por este evento igual a um envio manual — não trate como caso especial.

Campos importantes

Campo	O que observar
`data.object.status`	Estado atual do dispute depois da mudança.
`data.previous_attributes`	Valores anteriores dos campos públicos que mudaram.
`evidence`	Os 27 campos nomeados da defesa no momento do evento — `null` nos vazios.
`evidence_details.has_evidence`	Indica se algum campo de `evidence` está preenchido.
`evidence_details.due_by`	Prazo para preencher `evidence` e enviar a defesa quando o dispute ainda exige resposta.
`evidence_details.submission_count`	`1` depois que a defesa foi enviada — o envio é único.
`metadata`	Ecoa os metadados enviados na criação da venda para correlacionar com seu pedido.

Status possíveis

Valor	Descrição
`warning_needs_response`	Alerta prévio de disputa aguardando resposta da organização.
`warning_under_review`	Alerta prévio com resposta enviada, em análise.
`warning_closed`	Alerta prévio encerrado sem virar disputa.
`needs_response`	Disputa aberta aguardando o envio da contestação.
`under_review`	Contestação enviada, em análise.
`won`	Decisão final favorável à organização.
`lost`	Decisão final favorável ao portador.

Exemplo de payload

{
  "id": "evt_vvtD559xqHP3v9XN",
  "object": "event",
  "created_at": "2026-05-22T18:10:00Z",
  "data": {
    "object": {
      "id": "dp_WDnt7UZXcYmgRds8",
      "object": "dispute",
      "amount": 15000,
      "charge": "ch_FgnuP7VF2etM7oK4",
      "closed_at": null,
      "created_at": "2026-05-22T03:00:00Z",
      "currency": "brl",
      "customer": "cus_hENVXu41E3HgCVd6",
      "evidence": {
        "access_activity_log": "2026-05-20 14:02 UTC — login e acesso ao conteúdo pelo IP 187.34.12.90",
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": "file_pW7xK4mQ2rT9nV5c",
        "customer_email_address": "[email protected]",
        "customer_name": "Comprador",
        "customer_purchase_ip": "187.34.12.90",
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": "Assinatura mensal do plano Pro, com acesso imediato",
        "receipt": "file_62n4ydA9BjXtX1z8",
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": "2026-05-28T03:00:00Z",
        "has_evidence": true,
        "past_due": false,
        "submission_count": 1
      },
      "is_charge_refundable": true,
      "livemode": true,
      "metadata": {},
      "payment_intent": "pi_aYL8s2Px5B78rES7",
      "reason": "fraudulent",
      "status": "under_review",
      "updated_at": "2026-05-22T18:10:00Z"
    },
    "previous_attributes": {
      "evidence_details": {
        "due_by": "2026-05-28T03:00:00Z",
        "has_evidence": true,
        "past_due": false,
        "submission_count": 0
      },
      "status": "needs_response"
    }
  },
  "livemode": true,
  "organization": "org_5LLf3L2bbLyG6riP",
  "request": {
    "id": null
  },
  "type": "charge.dispute.updated"
}

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Evento charge.dispute.updated