Evento refund.created

Evento `refund.created`

Disparado quando um refund é criado. data.object usa o mesmo shape de GET /v1/refunds/:id. Use este evento para registrar que uma solicitação de refund entrou no ciclo de processamento. A criação não significa necessariamente conclusão: o refund pode nascer pending, requires_action ou já refletir outro estado conforme o fluxo.

Depois da criação, acompanhe refund.updated e refund.failed para saber se o refund concluiu, exigiu ação, falhou ou foi cancelado.

Quando acontece

Situação	Como aparece no payload
Refund aceito para processamento	`status: "pending"` e `pending_reason` explica a pendência.
Refund depende de ação	`status: "requires_action"` e `next_action` pode trazer a ação necessária.
Refund associado à cobrança	`charge`, `payment_intent` e `customer` apontam para a cobrança original.
Ledger público ainda indisponível	Campos como `balance_transaction` podem vir como `null`.

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.
Relacione o refund à venda original usando charge, payment_intent, customer ou metadata.
Atualize o valor em disputa ou devolução usando amount e currency.
Se status vier pending, aguarde refund.updated antes de tratar o refund como concluído.

Campos importantes

Campo	O que observar
`data.object.status`	Estado inicial do refund.
`amount`	Valor do refund em centavos.
`charge` / `payment_intent` / `customer`	Referências para conciliar com a cobrança original.
`pending_reason`	Motivo de pendência quando o refund ainda está em processamento.
`next_action`	Ação necessária quando o status é `requires_action`.
`failure_reason`	Fica `null` enquanto o refund não falhou.
`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_V8egobaJce3UPbzF",
  "object": "event",
  "created_at": "2026-05-20T18:35:00Z",
  "data": {
    "object": {
      "id": "re_81jJ4YCRMGcyb11J",
      "object": "refund",
      "amount": 5000,
      "balance_transaction": null,
      "charge": "ch_ELM2LmUzXzmMehsA",
      "created_at": "2026-05-20T18:35:00Z",
      "currency": "brl",
      "customer": "cus_4k4rPf91YhQAZ1DY",
      "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_GY7TravDE9wFeN5j",
      "pending_reason": "processing",
      "reason": "requested_by_customer",
      "receipt_number": null,
      "source_transfer_reversal": null,
      "status": "pending",
      "transfer_reversal": null,
      "updated_at": "2026-05-20T18:35:00Z"
    }
  },
  "livemode": true,
  "organization": "org_hn65mkP4W4F2pswo",
  "request": {
    "id": "req_Lb9NAgLRx8N2aXCw"
  },
  "type": "refund.created"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento refund.created

Evento `refund.created`

Quando acontece

Como processar

Campos importantes

Status possíveis

Exemplo de payload

​Evento refund.created

​Quando acontece

​Como processar

​Campos importantes

​Status possíveis

​Exemplo de payload

Evento `refund.created`

Quando acontece

Como processar

Campos importantes

Status possíveis

Exemplo de payload