Evento charge.refunded - Chargefy

Evento `charge.refunded`

Disparado quando uma charge recebe um refund parcial ou total. Para detalhes do refund individual, use refund.created, refund.updated e refund.failed. data.object usa o mesmo shape de GET /v1/charges/:id.

Este evento descreve a charge depois do refund. O objeto de refund individual fica em data.object.refunds.data[] e também é enviado pelos eventos refund.*.

Quando acontece

Situação	Como aparece no payload
Refund parcial concluído	`amount_refunded` aumenta e `refunded` pode continuar `false`.
Refund total concluído	`amount_refunded` alcança o valor capturado; use `refunded` junto de `amount_refunded` para classificar o estado.
Novo refund associado	`refunds.data[]` inclui o refund relacionado à cobrança.
Charge segue paga	`status` continua `succeeded` porque o refund não apaga a tentativa aprovada.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (ch_*) para atualizar o saldo reembolsado da cobrança.
Recalcule o valor líquido do pedido com amount_captured - amount_refunded.
Use os eventos refund.* para acompanhar o status detalhado de cada refund.
Não trate status: "succeeded" como ausência de refund; verifique amount_refunded, refunded e refunds.data.

Campos importantes

Campo	O que observar
`amount_refunded`	Total já reembolsado nesta charge, em centavos.
`refunded`	Indica se a cobrança foi reembolsada conforme o estado atual do objeto.
`refunds.data[]`	Lista os refunds associados à cobrança.
`refunds.data[].status`	Estado do refund individual.
`amount_captured`	Base para calcular quanto ainda pode ser reembolsado.
`payment_intent` / `invoice` / `customer`	Referências para conciliar o refund com a venda original.
`metadata`	Ecoa os metadados enviados na criação para correlacionar com seu pedido.

Exemplo de payload

{
  "id": "evt_PijS2qgUvudAwrQ8",
  "object": "event",
  "created_at": "2026-05-20T18:36:00Z",
  "data": {
    "object": {
      "id": "ch_JjT5spePZPj1Bmwn",
      "object": "charge",
      "amount": 9990,
      "amount_captured": 9990,
      "amount_refunded": 5000,
      "billing_details": {
        "billing_address": {},
        "document": "12345678901",
        "document_type": "cpf",
        "email": "nome@email.com",
        "name": "Cliente Exemplo"
      },
      "captured": true,
      "created_at": "2026-05-20T18:34:58Z",
      "currency": "brl",
      "customer": "cus_KfjDQ1M2WwCAbZRv",
      "description": "Assinatura do Plano Pro",
      "disputed": false,
      "invoice": "inv_4rEbo6sdSY9qPh11",
      "livemode": true,
      "metadata": {},
      "paid": true,
      "payment_error": null,
      "payment_intent": "pi_y9ABem4E1ge3yy6A",
      "payment_method": "pm_11wSAcTQL1gf6iau",
      "payment_method_details": {
        "card": {
          "amount_authorized": 9990,
          "authorization_code": "123456",
          "brand": "visa",
          "checks": {
            "address_line1_check": "unchecked",
            "address_postal_code_check": "unchecked",
            "cvc_check": "pass"
          },
          "country": null,
          "exp_month": 12,
          "exp_year": 2030,
          "funding": null,
          "installments": 1,
          "last4": "4242",
          "network": null
        },
        "type": "credit_card"
      },
      "receipt_url": "https://receipts.chargefy.io/receipt/ch_JjT5spePZPj1Bmwn",
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
          {
            "id": "re_1pK9B9HFe1gxiA2h",
            "object": "refund",
            "amount": 5000,
            "balance_transaction": "txn_xGNxDM3HnPBL39YD",
            "charge": "ch_JjT5spePZPj1Bmwn",
            "created_at": "2026-05-20T18:35:00Z",
            "currency": "brl",
            "customer": "cus_KfjDQ1M2WwCAbZRv",
            "description": "Reembolso parcial do pedido original",
            "destination_details": {
              "card_last4": "4242",
              "type": "credit_card"
            },
            "failure_balance_transaction": null,
            "failure_reason": null,
            "instructions_email": "nome@email.com",
            "livemode": true,
            "metadata": {},
            "next_action": null,
            "payment_intent": "pi_y9ABem4E1ge3yy6A",
            "pending_reason": null,
            "reason": "requested_by_customer",
            "receipt_number": "RR-2026-0001",
            "source_transfer_reversal": null,
            "status": "succeeded",
            "transfer_reversal": null,
            "updated_at": "2026-05-20T18:36:00Z"
          }
        ],
        "has_more": false,
        "url": "/v1/refunds?charge=ch_JjT5spePZPj1Bmwn"
      },
      "status": "succeeded",
      "updated_at": "2026-05-20T18:36:00Z"
    }
  },
  "livemode": true,
  "organization": "org_12EPtWxw2ScKPzhi",
  "request": {
    "id": null
  },
  "type": "charge.refunded"
}