Evento charge.updated

Evento `charge.updated`

Disparado quando uma charge muda sem entrar diretamente em succeeded ou failed. data.object contém a charge completa atualizada. data.previous_attributes contém apenas os campos públicos alterados, com os valores anteriores. Use este evento para acompanhar mudanças intermediárias da tentativa, como a passagem de pending para processing, alterações de metadata ou atualizações que não sejam o resultado final aprovado/falho.

O payload em data.object é sempre a charge completa e atual. Use data.previous_attributes apenas para saber o que mudou, não como fonte do estado final.

Quando acontece

Situação	Como aparece no payload
Pagamento entrou em processamento	`previous_attributes.status: "pending"` e `data.object.status: "processing"`.
Metadata foi atualizada	`previous_attributes.metadata` mostra o valor anterior da metadata alterada.
Dados públicos da tentativa mudaram	`data.previous_attributes` traz somente os campos alterados.
Status final chegou por outro evento	Aprovação e falha têm eventos específicos: `charge.succeeded` e `charge.failed`.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (ch_*) para atualizar a tentativa 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.
Para liberar acesso, baixa ou entrega, espere charge.succeeded ou confirme status: "succeeded".

Campos importantes

Campo	O que observar
`data.object.status`	Estado atual da tentativa depois da mudança.
`data.previous_attributes`	Valores anteriores dos campos públicos que mudaram.
`paid` / `captured`	Ajudam a diferenciar tentativa em processamento de cobrança paga.
`payment_error`	Permanece `null` enquanto não houver falha normalizada.
`receipt_url`	Pode continuar `null` até a cobrança ser paga.
`metadata`	Ecoa os metadados enviados na criação para correlacionar com seu pedido.

Status possíveis

Valor	Descrição
`pending`	Aguardando confirmação do pagamento.
`processing`	Pagamento em processamento.
`succeeded`	Pagamento confirmado.
`failed`	A tentativa de pagamento falhou.
`canceled`	A cobrança foi cancelada.

Exemplo de payload

{
  "id": "evt_2P6t1EipZ91iXQAv",
  "object": "event",
  "created_at": "2026-05-19T18:35:00Z",
  "data": {
    "object": {
      "id": "ch_Cf3Fmm8dC7DpDcMA",
      "object": "charge",
      "amount": 9990,
      "amount_captured": 0,
      "amount_refunded": 0,
      "billing_details": {
        "billing_address": {},
        "document": "12345678901",
        "document_type": "cpf",
        "email": "nome@email.com",
        "name": "Cliente Exemplo"
      },
      "captured": false,
      "created_at": "2026-05-19T18:34:58Z",
      "currency": "brl",
      "customer": "cus_tzz6NfZjsHe88Dcz",
      "description": "Assinatura do Plano Pro",
      "disputed": false,
      "invoice": "inv_KiMpMpN4tvzDC7JG",
      "livemode": true,
      "metadata": {},
      "paid": false,
      "payment_error": null,
      "payment_intent": "pi_to1R9T1BF5rDM4Wn",
      "payment_method": "pm_YBLn59s9U5YwktNK",
      "payment_method_details": {
        "card": {
          "amount_authorized": null,
          "authorization_code": null,
          "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": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [],
        "has_more": false,
        "url": "/v1/refunds?charge=ch_Cf3Fmm8dC7DpDcMA"
      },
      "status": "processing",
      "updated_at": "2026-05-19T18:35:00Z"
    },
    "previous_attributes": {
      "status": "pending"
    }
  },
  "livemode": true,
  "organization": "org_Fribmp1WncewsxFo",
  "request": {
    "id": null
  },
  "type": "charge.updated"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento charge.updated