Evento refund.updated

Evento `refund.updated`

Disparado quando um refund muda de estado. data.object contém o refund completo atualizado. data.previous_attributes contém apenas os campos públicos alterados, com os valores anteriores. Use este evento para acompanhar o ciclo assíncrono do refund depois da criação. Ele é especialmente importante quando a resposta de POST /v1/refunds retorna pending ou requires_action: a conclusão chega depois por webhook.

O payload em data.object é sempre o refund completo e atual. O diff fica em data.previous_attributes para você saber exatamente o que mudou sem perder o estado final.

Quando acontece

Situação	Como aparece no payload
Refund pendente concluiu	`previous_attributes.status: "pending"` e `data.object.status: "succeeded"`.
Refund passou a exigir ação	`data.object.status: "requires_action"` e `next_action` pode trazer a ação necessária.
Refund falhou	`data.object.status: "failed"` e `failure_reason` explica o motivo normalizado.
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 (re_*) como chave do refund no seu sistema.
Atualize o estado local usando data.object.status, não apenas o diff.
Use data.previous_attributes para auditoria, logs e notificações condicionais.
Quando receber succeeded, considere o valor de amount como devolvido para a charge original.
Quando receber failed, leia failure_reason antes de decidir se deve tentar outro refund ou acionar suporte.

Campos importantes

Campo	O que observar
`data.object.status`	Estado atual do refund depois da mudança.
`data.previous_attributes`	Valores anteriores dos campos públicos que mudaram.
`failure_reason`	Motivo normalizado quando `status` é `failed`; `null` nos demais estados.
`pending_reason`	Motivo de pendência quando o refund ainda está em processamento.
`next_action`	Ação necessária para avançar quando o status é `requires_action`.
`charge` / `payment_intent` / `customer`	Referências para conciliar o refund com a cobrança original.
`metadata`	Ecoa os metadados enviados na criação para correlacionar com seu pedido.

Status possíveis

Valor	Descrição
`pending`	Refund em andamento.
`requires_action`	Aguardando uma ação para concluir o refund.
`succeeded`	Refund concluído.
`failed`	O refund falhou.
`canceled`	O refund foi cancelado.

Exemplo de payload

{
  "id": "evt_3DoK6RE5PMNJrnHf",
  "object": "event",
  "created_at": "2026-05-20T18:36:00Z",
  "data": {
    "object": {
      "id": "re_M3R8PwXqMqxw3PGQ",
      "object": "refund",
      "amount": 5000,
      "balance_transaction": "txn_hKbj8Peq33BuLqgm",
      "charge": "ch_9KjspsTJ18sNBf3C",
      "created_at": "2026-05-20T18:35:00Z",
      "currency": "brl",
      "customer": "cus_RtcipUAVhhHP9YL4",
      "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_upKDkNh1Q7Bu1YT2",
      "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"
    },
    "previous_attributes": {
      "status": "pending"
    }
  },
  "livemode": true,
  "organization": "org_t3nRE1TnHuVdA1yr",
  "request": {
    "id": null
  },
  "type": "refund.updated"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento refund.updated