Evento payment.intent.updated

Evento `payment.intent.updated`

Disparado quando um campo público ou um estado intermediário de um payment_intent muda. Isso inclui tanto alterações feitas por POST /v1/payment-intents/:id quanto mudanças produzidas por ações de lifecycle, como a confirmação de um PIX. data.object traz o estado atual completo. data.previous_attributes traz apenas os campos alterados, com os valores anteriores. Use este evento para manter cache, pedido e conciliação em sincronia enquanto o intent ainda não chegou a um desfecho. A resposta direta da operação não traz diff; o diff aparece aqui, no webhook.

Quando a confirmação de um PIX muda o status de requires_confirmation para pending, payment.intent.updated é emitido. Nesse caso, data.previous_attributes.status vem como requires_confirmation, data.object.status vem como pending e data.object.next_action contém o PIX que deve ser apresentado ao comprador.

data.previous_attributes é histórico. Para atualizar seu banco, use sempre o objeto completo em data.object como fonte do estado atual.

Quando acontece

Situação	Como aparece no payload
Confirmação de PIX mudou o intent para `pending`	`previous_attributes.status` mostra `requires_confirmation`; `data.object` traz `status: "pending"`, `latest_charge` e o novo `next_action`.
Código PIX ou boleto venceu sem pagamento	`data.object` traz `status: "requires_payment_method"` e `next_action: null`. A tentativa acabou, o intent não: um novo código pode ser emitido no mesmo intent via `/regenerate_pix` ou `/regenerate_boleto`.
Tentativa avulsa recusada	`data.object` traz `status: "requires_payment_method"` e `last_payment_error` com o motivo; o detalhe da tentativa sai em `charge.failed`. O mesmo intent aceita nova confirmação.
Um novo código foi emitido por regenerate	`data.object` volta a `status: "pending"` com o novo `next_action` e um novo `latest_charge`.
Valor ou moeda foram alterados	`previous_attributes.amount` ou `previous_attributes.amount_details` mostra o valor anterior.
Parcelamento ou repasse foram recalculados	`payment_method_options` e `amount_details` aparecem no diff quando mudam.
Metadata foi atualizada	`previous_attributes.metadata` mostra a metadata anterior.
Método de pagamento ou métodos permitidos mudaram	`payment_method` ou `payment_method_types` aparecem em `data.object` com o estado atual.
Outra ação mudou um estado intermediário	`previous_attributes.status` mostra o status anterior e `data.object.status` mostra o atual.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Atualize o registro local usando data.object.id (pi_*) e o objeto completo de data.object.
Use data.previous_attributes para auditoria, logs e notificações condicionais.
Recalcule totais locais quando amount_details ou payment_method_options aparecerem no diff.
Não libere pedido apenas por payment.intent.updated; use payment.intent.succeeded para conclusão.
Use metadata, customer e invoice para localizar o pedido ou fatura correspondente.

Campos importantes

Campo	O que observar
`data.object.status`	Estado atual do intent depois da atualização.
`data.previous_attributes`	Valores anteriores dos campos públicos que mudaram.
`amount` / `amount_details`	Total atual e quebra entre principal, repasse e juros.
`payment_method_options`	Opções atuais do método, como parcelas de cartão.
`payment_method`	Método salvo associado depois da atualização.
`payment_method_types`	Métodos permitidos depois da atualização.
`metadata`	Metadata atual; o valor anterior aparece no diff quando mudou.
`updated_at`	Horário da atualização refletida no webhook.

Transições e status

payment.intent.updated pode representar uma mudança de campos ou uma transição intermediária de status. Quando status não aparece em data.previous_attributes, considere que o estado do intent não mudou.

Sinal no payload	Como interpretar
`previous_attributes.status` ausente	Update de campos; use `data.object.status` como estado atual.
`previous_attributes.status` presente	Compare o valor anterior com `data.object.status` para auditar a transição.
`data.object.status: "requires_confirmation"`	O intent está pronto para confirmação.
`data.object.status: "requires_capture"`	O cartão foi autorizado e ainda precisa de captura.
`data.object.status: "pending"`	Aguardando ação do comprador ou confirmação assíncrona.
A confirmação termina em `succeeded`	A confirmação emite `payment.intent.succeeded`, sem um `payment.intent.updated` adicional para o mesmo desfecho.
A confirmação termina recusada	O próprio `payment.intent.updated` carrega o desfecho: `status: "requires_payment_method"` com `last_payment_error`.
A confirmação termina em `canceled`	A confirmação emite `payment.intent.canceled`, sem um `payment.intent.updated` adicional para o mesmo desfecho.

Exemplo: confirmação de PIX

{
  "id": "evt_Hf2ym93m3UUGmqVs",
  "object": "event",
  "created_at": "2026-05-16T18:35:00Z",
  "data": {
    "object": {
      "id": "pi_gpNgh1UXjAraAPke",
      "object": "payment_intent",
      "amount": 7500,
      "amount_capturable": 0,
      "amount_details": {
        "amount": 7500,
        "installment_interest_amount": 0,
        "principal_amount": 7500,
        "surcharge_amount": 0
      },
      "amount_received": 0,
      "canceled_at": null,
      "cancellation_reason": null,
      "capture_method": "automatic",
      "client_secret": "pi_gpNgh1UXjAraAPke_secret_edd4b9780096b3e23089f218c8ff76a2736c247b96ddf72e",
      "confirmation_method": "automatic",
      "created_at": "2026-05-16T18:34:58Z",
      "currency": "brl",
      "customer": null,
      "installment_interest_amount": 0,
      "installments": null,
      "invoice": null,
      "last_payment_error": null,
      "latest_charge": "ch_puWvZLLk2LgotPVq",
      "livemode": true,
      "metadata": {},
      "next_action": {
        "pix_display_qr_code": {
          "expires_at": "2026-05-16T19:35:00Z",
          "qr_code": "00020101021226860014br.gov.bcb.pix...",
          "qr_code_url": null
        },
        "type": "pix_display_qr_code"
      },
      "payment_method": null,
      "payment_method_options": {},
      "payment_method_types": [
        "pix"
      ],
      "principal_amount": 7500,
      "status": "pending",
      "surcharge_amount": 0,
      "updated_at": "2026-05-16T18:35:00Z"
    },
    "previous_attributes": {
      "latest_charge": null,
      "next_action": null,
      "status": "requires_confirmation",
      "updated_at": "2026-05-16T18:34:58Z"
    }
  },
  "livemode": true,
  "organization": "org_jGQi3eGR6YPNbLyu",
  "request": {
    "id": "req_B5Fvjq6ZKE2u2hSu"
  },
  "type": "payment.intent.updated"
}

Páginas relacionadas

Objeto Payment Intent

Contrato completo de data.object.

Atualizar Payment Intent

Campos editáveis e estados permitidos.

Formato dos eventos

Envelope, objeto completo e regras de previous_attributes.

Implementar Payment Intents

Como sincronizar mudanças sem concluir a operação cedo demais.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento payment.intent.updated