Evento charge.dispute.created

Evento `charge.dispute.created`

Disparado quando uma contestação é criada para uma charge. Use este evento para abrir o caso no seu sistema, acompanhar o prazo de resposta e preparar a evidência antes da decisão final. data.object usa o mesmo shape de GET /v1/disputes/:id.

O dispute sempre aponta para a cobrança contestada em charge. O valor em amount é o valor contestado em centavos, não necessariamente o valor total da cobrança.

Quando acontece

Situação	Como aparece no payload
Nova contestação aberta	`status: "needs_response"` e `evidence_details.has_evidence: false`.
Prazo de defesa definido	`evidence_details.due_by` traz a data limite para envio.
Nenhuma evidência enviada ainda	`evidence` vem vazio e `evidence_details.submission_count` é `0`.
Charge ainda pode receber refund	`is_charge_refundable` indica se a cobrança segue elegível para refund.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (dp_*) como chave do dispute no seu sistema.
Relacione o caso à venda original usando charge, payment_intent, customer ou metadata.
Mostre o prazo de resposta com evidence_details.due_by quando status exigir ação.
Use reason para classificar o motivo da contestação e orientar o fluxo interno.

Campos importantes

Campo	O que observar
`data.object.status`	Estado inicial ou atual do dispute.
`amount`	Valor contestado em centavos.
`charge`	Charge que originou a contestação.
`reason`	Motivo normalizado da contestação quando disponível.
`evidence_details.due_by`	Prazo para enviar evidência quando o dispute exige resposta.
`evidence_details.submission_count`	Quantas defesas já foram enviadas com sucesso.
`is_charge_refundable`	Indica se a charge ainda pode receber refund.
`metadata`	Ecoa os metadados enviados na criação da venda para correlacionar com seu pedido.

Status iniciais comuns

Valor	Descrição
`needs_response`	Disputa aberta aguardando envio da defesa.
`warning_needs_response`	Alerta antecipado aguardando resposta.

Exemplo de payload

{
  "id": "evt_H8h2H1YDmL4hVteQ",
  "object": "event",
  "created_at": "2026-05-22T03:00:00Z",
  "data": {
    "object": {
      "id": "dp_tNmAgQVJmU9FdjLq",
      "object": "dispute",
      "amount": 15000,
      "charge": "ch_DqzfFnMgL4DcS5QX",
      "closed_at": null,
      "created_at": "2026-05-22T03:00:00Z",
      "currency": "brl",
      "customer": "cus_zgei5MF9sjy2JZcY",
      "evidence": {},
      "evidence_details": {
        "due_by": "2026-05-29T03:00:00Z",
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": true,
      "livemode": true,
      "metadata": {},
      "payment_intent": "pi_4CK6Z1BrRtCQ2aam",
      "reason": "fraudulent",
      "status": "needs_response",
      "updated_at": null
    }
  },
  "livemode": true,
  "organization": "org_d3ebJLkYWF5kYHKH",
  "request": {
    "id": null
  },
  "type": "charge.dispute.created"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento charge.dispute.created

Evento `charge.dispute.created`

Quando acontece

Como processar

Campos importantes

Status iniciais comuns

Exemplo de payload

​Evento charge.dispute.created

​Quando acontece

​Como processar

​Campos importantes

​Status iniciais comuns

​Exemplo de payload

Evento `charge.dispute.created`

Quando acontece

Como processar

Campos importantes

Status iniciais comuns

Exemplo de payload