Pular para o conteúdo principal

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. No checkout com cartão e na regeneração de Pix ou boleto, o vínculo da tentativa gera um evento com o novo data.object.latest_charge. O valor anterior está em data.previous_attributes.latest_charge, que vale null no primeiro vínculo. O pagamento mantém o status que tinha no momento do vínculo. Se a emissão de Pix ou boleto gerar um novo código, o evento dessa mudança traz o código em data.object.next_action. data.previous_attributes contém os valores anteriores dos campos públicos alterados. Use o objeto completo em data.object para sincronizar o estado atual. A resposta direta da operação também traz o objeto atualizado.
Quando a confirmação de um Pix muda o status de requires_confirmation para requires_action, payment.intent.updated é emitido. Nesse caso, data.previous_attributes.status vem como requires_confirmation, data.object.status vem como requires_action 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

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

Transições e status

payment.intent.updated pode representar uma mudança de campos ou uma transição intermediária de status. O bloco data.previous_attributes traz os valores anteriores dos campos alterados. Se status não aparecer nele, o estado do intent permaneceu igual naquela atualização.

Exemplo: confirmação de Pix

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.