Evento charge.dispute.updated

Evento `charge.dispute.updated`

Disparado quando um dispute muda de estado ou recebe nova evidência. 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: envio de defesa, 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
Evidência enviada	`evidence_details.submission_count` aumenta e `has_evidence` fica `true`.
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.

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`	Conteúdo ou arquivo de evidência anexado.
`evidence_details.has_evidence`	Indica se existe evidência registrada.
`evidence_details.due_by`	Prazo de envio quando o dispute ainda exige resposta.
`evidence_details.submission_count`	Quantas defesas já foram enviadas com sucesso.
`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": {
        "file": "file_62n4ydA9BjXtX1z8"
      },
      "evidence_details": {
        "due_by": "2026-05-29T03: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-29T03: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

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento charge.dispute.updated