Evento charge.dispute.created

Evento `charge.dispute.created`

Disparado quando uma disputa é aberta 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 disputa aberta	`status: "needs_response"` e `evidence_details.has_evidence: false`.
Prazo de defesa definido	`evidence_details.due_by` traz a data limite, 6 dias corridos após a criação.
Nenhuma evidência preenchida ainda	`evidence` vem com todos os campos `null` 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 disputa e orientar o fluxo interno.
Preencha a evidência cedo: se o prazo terminar com campo de arquivo preenchido e defesa não enviada, a Chargefy envia automaticamente.

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 disputa.
`reason`	Motivo normalizado da disputa quando disponível.
`evidence_details.due_by`	Prazo para preencher `evidence` e enviar a defesa quando o dispute exige resposta.
`evidence_details.submission_count`	`1` depois que a defesa foi enviada — o envio é único.
`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": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "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": 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": "2026-05-22T03:00:00Z"
    }
  },
  "livemode": true,
  "organization": "org_d3ebJLkYWF5kYHKH",
  "request": {
    "id": null
  },
  "type": "charge.dispute.created"
}

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

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