Evento charge.dispute.funds.withdrawn

Evento `charge.dispute.funds.withdrawn`

Disparado quando a disputa tira o dinheiro da venda do seu extrato. Acontece uma vez por disputa, junto com a abertura: o valor sai do saldo na mesma hora, num movimento adjustment negativo com source na disputa, que leva o líquido que a venda tinha creditado e a tarifa de recebimento de contestação. A venda continua paid: quem tira o dinheiro é a disputa. Numa venda parcelada, a disputa leva todas as parcelas de uma vez, inclusive as que ainda não tinham sido pagas. O alerta prévio (warning_*) não move dinheiro e não dispara este evento. data.object usa o mesmo shape de GET /v1/disputes/:id, com o movimento em transactions.

Quando acontece

Situação	Como aparece no payload
Disputa aberta	`data.object.status: "needs_response"` e um movimento em `transactions`.
Valor que saiu	`transactions[0].net_amount` negativo: o líquido da venda mais a tarifa.
Tarifa de recebimento de contestação	`transactions[0].fee_details` com `type: "dispute_received_fee"`.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use transactions[0].id (txn_*) para lançar a saída no seu controle financeiro uma única vez.
Relacione a saída à venda original usando charge, payment_intent ou metadata.

Campos importantes

Campo	O que observar
`transactions[0].net_amount`	Quanto saiu do saldo, em centavos, negativo.
`transactions[0].fee_details`	A tarifa de recebimento de contestação.
`transactions[0].settled_at`	Momento em que o dinheiro saiu.
`amount`	Valor contestado da venda, em centavos.

Exemplo de payload

{
  "id": "evt_Wd7kQ2mXr9TpLs4N",
  "object": "event",
  "created_at": "2026-05-22T03:00:00Z",
  "data": {
    "object": {
      "id": "dp_7QPYgr51yNhNTbyv",
      "object": "dispute",
      "amount": 15000,
      "charge": "ch_cgHAnW5CKA1P81G8",
      "closed_at": null,
      "created_at": "2026-05-22T03:00:00Z",
      "currency": "brl",
      "customer": "cus_RkWE27LYVzf8afo9",
      "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": false,
      "livemode": true,
      "metadata": {},
      "payment_intent": "pi_aj6A8EuFqUJFCk5U",
      "reason": "fraudulent",
      "status": "needs_response",
      "transactions": [
        {
          "id": "txn_Qm3vR8kZp2LwN7cT",
          "object": "transaction",
          "affiliate_fee_rate": null,
          "affiliation": null,
          "amount": -14415,
          "available_at": "2026-05-22T03:00:00Z",
          "created_at": "2026-05-22T03:00:00Z",
          "currency": "brl",
          "description": "Dispute",
          "expected_payout_at": null,
          "fee_amount": 256,
          "fee_details": [
            {
              "affiliation": null,
              "amount": 256,
              "description": "Dispute received fee",
              "type": "dispute_received_fee"
            }
          ],
          "installment": null,
          "installment_count": null,
          "livemode": true,
          "metadata": {},
          "net_amount": -14671,
          "payment_intent": "pi_aj6A8EuFqUJFCk5U",
          "settled_at": "2026-05-22T03:00:00Z",
          "source": "dp_7QPYgr51yNhNTbyv",
          "source_organization": "org_Nt99XL6FzLb1oCxT",
          "status": "paid",
          "type": "adjustment",
          "updated_at": "2026-05-22T03:00:00Z"
        }
      ],
      "updated_at": "2026-05-22T03:00:00Z"
    }
  },
  "livemode": true,
  "organization": "org_Nt99XL6FzLb1oCxT",
  "request": {
    "id": null
  },
  "type": "charge.dispute.funds.withdrawn"
}

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Evento charge.dispute.funds.withdrawn