Usar webhooks com assinaturas
A Stripe envia notificações ao aplicativo com webhooks. Os webhooks são muito importantes para assinaturas, onde a maior parte das atividades ocorre de forma assíncrona.
Para usar webhooks com suas assinaturas:
- Crie um endpoint de webhook no aplicativo.
- Adicione lógica para gerenciar os eventos da Stripe. Para assinaturas, esses eventos incluem falhas de pagamento e mudanças no estado de assinaturas (como mudar de avaliação para um estado ativo).
- Teste o endpoint de webhook para confirmar se funciona da forma esperada.
Estes são alguns documentos úteis sobre webhooks:
- Para obter mais detalhes sobre configurar e usar webhooks recebidos, leia o guia.
- Use o início rápido de webhooks para aprender a criar um endpoint de webhook simples em uma experiência imersiva.
Eventos de webhook de assinatura
A Stripe aciona eventos sempre que uma assinatura é criada ou alterada. Alguns eventos são enviados imediatamente quando a assinatura é criada, mas outros se repetem em intervalos de faturamento regulares.
Verifique se a integração gerencia adequadamente os eventos. Por exemplo, você pode enviar um e-mail para o cliente quando um pagamento falha ou revogar o acesso dele quando uma assinatura é cancelada.
A tabela a seguir descreve os eventos mais comuns associados a assinaturas e, se for o caso, sugere ações para gerenciar esses eventos.
customer.created | Enviado quando um Customer é criado. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer.subscription.created | Enviado quando a assinatura é criada. O status da assinatura pode ser incomplete se a autenticação do cliente é necessária para finalizar o pagamento ou se você definiu payment_behavior como default_incomplete . Para obter mais detalhes, consulte o comportamento do pagamento da assinatura. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer.subscription.deleted | Enviado quando a assinatura do cliente termina. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer.subscription.paused | Enviado quando o status de uma assinatura muda para paused . Por exemplo, isso é enviado quando uma assinatura é configurada para suspensão no caso de uma avaliação gratuita terminar sem uma forma de pagamento. O faturamento não ocorrerá até que a assinatura seja retomada. Não enviamos esse evento se o recebimento de pagamentos for suspenso porque as faturas continuam sendo criadas durante esse período. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer.subscription.resumed | Enviado quando uma assinatura com status paused é retomada. Isso não se aplica quando a cobrança de pagamentos é reiniciada. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer.subscription.trial_will_end | Enviado três dias antes do final do período de avaliação. O evento é acionado quando o período de avaliação é menor que três dias. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer.subscription.updated | Enviado quando uma assinatura inicia ou é alterada. Por exemplo, o evento é acionado ao renovar uma assinatura, adicionar cupons, aplicar descontos, incluir itens de fatura ou alterar planos. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
entitlements.active_entitlement_summary.updated | Sent when a customer’s active entitlements are updated. When you receive this event, you can provision or de-provision access to your product’s features. Read more about integrating with entitlements. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.created | Enviado quando uma fatura é gerada para criar ou renovar uma assinatura. Se a Stripe não receber uma resposta positiva para invoice.created , a finalização de todas as faturas com cobrança automática será adiada por até 72 horas. Leia mais sobre a finalização de faturas.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.finalized | Enviado quando uma fatura é finalizada e está pronta para pagamento.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.finalization_failed | Não foi possível finalizar a fatura. Leia mais para saber como gerenciar falhas de finalização de faturas. Saiba mais sobre a finalização de faturas no guia de visão geral de faturas.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.paid | Enviado quando a fatura é paga. Você pode provisionar acesso ao produto quando recebe este evento e status é active . | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.payment_action_required | Enviado quando a fatura exige autenticação do cliente. Saiba como gerenciar a assinatura quando a fatura exige ação. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.upcoming | Enviado alguns dias antes da renovação da assinatura. O número de dias é baseado no número definido para Próximos eventos de renovação no Dashboard. Para assinaturas existentes, a alteração do número de dias entra em vigor no próximo período de cobrança. Se necessário, você ainda pode adicionar outros itens de fatura. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.updated | Enviado quando um pagamento é bem-sucedido ou falha. Se o pagamento for bem-sucedido, o atributo paid será definido como true , e status será paid . Se o pagamento falhar, paid será definido como false , e status permanecerá open . As falhas de pagamento também acionam um evento invoice.payment_failed . | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payment_intent.created | Enviado quando um PaymentIntent é criado. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payment_intent.succeeded | Enviado quando um PaymentIntent conclui um pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subscription_schedule.aborted | Enviado quando um cronograma de assinatura é cancelado porque o pagamento inadimplente encerrou a assinatura relacionada. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subscription_schedule.canceled | Enviado quando um cronograma de assinatura é cancelado, o que também cancela qualquer assinatura associada ativa. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subscription_schedule.completed | Enviado quando todas as fases de um cronograma de assinatura são concluídas. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subscription_schedule.created | Enviado quando um novo cronograma de assinatura é criado. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subscription_schedule.expiring | Enviado 7 dias antes da data de vencimento de um cronograma de assinatura. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subscription_schedule.released | Enviado quando um cronograma de assinatura é lançado ou interrompido e desassociado da assinatura, que permanece. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subscription_schedule.updated | Enviado quando uma programação de assinatura é atualizada. |
Gerenciar falhas de pagamento
As notificações por webhook são uma maneira confiável de receber notificações da Stripe sobre falhas nos pagamentos de faturas de assinaturas. Algumas falhas de pagamento são temporárias (por exemplo, o emissor do cartão pode recusar a cobrança inicial, mas permitir uma nova tentativa automática). Outras são finais e exigem uma ação, como um cliente sem forma de pagamento utilizável.
Evento | Descrição |
---|---|
| Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para
|
Para obter mais detalhes sobre como gerenciar falhas de pagamento que exigem uma forma de pagamento, consulte o guia de visão geral de assinaturas.
Gerenciar pagamentos que precisam de medidas adicionais
Algumas formas de pagamento podem exigir mais etapas para sua conclusão, como autenticação do cliente. Quando recebe esses eventos, o aplicativo precisa notificar o cliente para concluir a ação necessária. Para saber como gerenciar eventos que exigem ação adicional, leia o guia de visão geral de assinaturas.
Evento | Descrição |
---|---|
invoice.finalization_failed | Não foi possível finalizar a fatura. Descubra como gerenciar falhas de finalização de faturas. Saiba mais sobre a finalização de faturas no guia de visão geral de faturas.
|
| Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para
|
| Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para
|
Acompanhe as assinaturas ativas
As assinaturas exigem coordenação entre seu site e a Stripe. O sucesso ou falha dos pagamentos recorrentes de um cliente determinam a continuidade do acesso ao produto ou serviço.
Nas integrações comuns, quando um cliente faz uma assinatura, você armazena as credenciais dele e um valor de carimbo de data e hora com a data de validade do acesso dele ao seu site. Quando o cliente faz login, você verifica se o carimbo de data e hora ainda está no futuro. Se estiver, a conta está ativa e o cliente ainda tem acesso ao serviço.
Quando a assinatura é renovada, a Stripe fatura o cliente e tenta receber o pagamento cobrando automaticamente a forma de pagamento cadastrada ou enviando a fatura por e-mail ao cliente. A Stripe notifica o status da fatura ao site usando webhooks:
Seu site recebe um evento
invoice.paid
.- Quando cobramos automaticamente uma forma de pagamento, seu site recebe primeiro um evento
invoice.upcoming
no endpoint do webhook alguns dias antes da renovação. É possível escutar esse evento para adicionar itens de fatura à próxima fatura. Secollection_method=send_invoice
, a Stripe não envia um eventoinvoice.upcoming
.
- Quando cobramos automaticamente uma forma de pagamento, seu site recebe primeiro um evento
Seu endpoint de webhook encontra o cliente para o qual o pagamento acabou de ser feito.
Seu endpoint de webhook atualiza a data de validade do acesso do cliente no seu banco de dados com a data futura correta (mais um dia ou dois de tolerância).
Capturar alterações de status de assinaturas
Verifique se a integração monitora e gerencia adequadamente as transições entre os status de assinatura descritos na tabela a seguir.
Algumas mudanças de status exigem atenção especial:
Alguns dias antes do término da avaliação e da mudança da assinatura de
trialing
paraactive
, você recebe um eventocustomer.subscription.trial_will_end
. Quando isso acontecer, verifique se o cliente tem uma forma de pagamento cadastrada e efetue o faturamento. Se preferir, avise o cliente sobre a cobrança.Quando uma assinatura muda para
past_due
, avise o cliente e solicite a atualização dos dados de pagamento. A Stripe oferece vários recursos que ajudam a automatizar esse processo. Saiba mais sobre a recuperação de receitas.Quando uma assinatura muda para
canceled
ouunpaid
, revogue o acesso ao produto.
Status | Descrição |
---|---|
trialing | A assinatura está em um período de avaliação e é seguro fornecer o produto para o cliente. A assinatura muda automaticamente para active quando o primeiro pagamento é feito. |
active | A assinatura está adimplente, e o pagamento mais recente foi bem-sucedido. É seguro fornecer o produto ao cliente. |
incomplete | É necessário fazer um pagamento bem-sucedido em até 23 horas para ativar a assinatura. Ou o pagamento exige uma ação, como autenticação do cliente. Assinaturas também podem estar incomplete se houver um pagamento pendente e o status do PaymentIntent for processing . |
incomplete_expired | O pagamento inicial da assinatura falhou, e não houve pagamento bem-sucedido dentro de 23 horas após a criação da assinatura. Essas assinaturas não geram cobrança para os clientes. Este status existe para que você possa rastrear os clientes que não conseguiram ativar as assinaturas. |
past_due | O pagamento da fatura finalizada mais recente falhou ou não foi tentado. A assinatura continua gerando faturas. As configurações da assinatura determinam o próximo estado da assinatura. Quando a fatura continua não paga após todas as tentativas de Smart Retries, você pode configurar a assinatura para mudar para canceled , unpaid ou ficar como past_due . Para mudar a assinatura para active , pague a fatura mais recente antes do vencimento. |
canceled | A assinatura foi cancelada. Durante o cancelamento, a cobrança automática de todas as faturas não pagas é desativada (auto_advance=false ). Esse é um estado terminal que não pode ser atualizado. |
unpaid | A fatura mais recente não foi paga, mas a assinatura permanece em vigor. Essa fatura continua aberta e as faturas continuam sendo geradas, mas não são feitas tentativas de pagamento. Você deve revogar o acesso ao produto quando a fatura é unpaid , pois já foram feitas várias tentativas de pagamento enquanto ela estava past_due . Para mudar a assinatura para active , pague a fatura mais recente antes do vencimento. |
paused | A assinatura encerrou o período de avaliação sem uma forma de pagamento padrão e o trial_settings.end_behavior.missing_payment_method está definido como pause . As faturas não serão mais criadas para a assinatura. Após anexar uma forma de pagamento padrão ao cliente, você pode retomar a assinatura. |
Webhooks e faturas
Recomendamos o registro de um endpoint de webhook para acompanhar os status das faturas. Esse acompanhamento é particularmente importante para as faturas geradas por assinaturas.
Quando você habilita a cobrança automática, a Stripe finaliza automaticamente e começa a cobrança automática da fatura.
Para garantir que a integração de assinaturas funcione como esperado, inclusive a continuidade do recebimento de pagamentos em faturas geradas por assinaturas, é preciso gerenciar corretamente os webhooks associados à finalização de faturas. A finalização e o gerenciamento de finalizações de faturas de forma adequada são essenciais para a integração de assinaturas.
Se a Stripe não receber uma resposta adequada para
invoice.created
, a finalização de todas as faturas com cobrança automática será adiada por até 72 horas.Uma resposta adequada para
invoice.created
inclui gerenciar todos os endpoints de webhook configurados na sua conta e de todas as plataformas às quais você está conectado.Uma atualização de assinatura que cause uma tentativa de pagamento síncrono (na fatura inicial e em alguns tipos de atualização) não gera essa espera.
Quando ocorre uma falha na finalização da fatura, não é possível cobrar a fatura. Verifique se está ouvindo o evento
invoice.finalization_failed
no endpoint do webhook.
Eventos de webhook relacionados à finalização de faturas
Evento | Descrição |
---|---|
invoice.created | A fatura foi criada e está pronta para a finalização. Leia a documentação para saber mais sobre a finalização de faturas.
|
invoice.finalized | A fatura foi finalizada e está pronta para o pagamento.
|
invoice.finalization_failed | Não foi possível finalizar a fatura. Leia mais para saber como gerenciar falhas de finalização de faturas. Saiba mais sobre a finalização de faturas no guia de visão geral de faturas.
|
Finalização da fatura
A Stripe aguarda uma hora após receber uma resposta positiva para o evento invoice.created
antes de tentar fazer um pagamento. Se não recebermos uma resposta positiva em 72 horas, tentaremos finalizar e enviar a fatura.
Caso você deseje tratar faturas avulsas de forma diferente das faturas de assinatura, verifique a propriedade subscription
no corpo do webhook. Ela indica se a fatura foi criada para uma assinatura.
No modo de produção, se o seu endpoint de webhook não responder corretamente, a Stripe continuará tentando realizar a notificação do webhook por até três dias com intervalos que aumentam exponencialmente. No modo de teste, realizamos três tentativas em algumas horas. Nesse período, não haverá tentativas de cobrança do cliente se não houver resposta positiva. Também notificaremos você por e-mail se houver falha no webhook.
Esse comportamento se aplica a todos os endpoints de webhook definidos na sua conta, incluindo casos em que um aplicativo Connect ou outro serviço de terceiros está tendo problemas para gerenciar os webhooks de entrada.
Falha na finalização da fatura
Quando não consegue finalizar uma fatura, a Stripe envia um evento invoice.finalization_failed
ao endpoint de webhook. As assinaturas permanecem ativas quando não é possível finalizar as faturas, ou seja, os usuários podem continuar acessando o produto, mesmo que você não consiga cobrar os pagamentos. Lembre-se de tomar providências para faturas com falha de finalização. Não é possível cobrar pagamentos de uma fatura não finalizada.
Para determinar a causa da falha de finalização da fatura, examine o campo last_finalization_error
do objeto Invoice, que oferece mais informações sobre a falha, incluindo orientações sobre como proceder.
Se você usa o Stripe Tax, confira o campo automatic_tax
para determinar se a falha está associada à validação da localização do cliente. Quando o Stripe Tax não encontra uma localização de cliente reconhecida, não é possível finalizar a fatura. Saiba como gerenciar falhas de finalização de faturas.
Testes
Você tem duas opções para testar webhooks:
- Executar ações no modo de teste que enviam eventos legítimos ao endpoint. Por exemplo, para acionar o evento charge.succeeded, você pode usar um cartão de teste que gera uma cobrança bem-sucedida.
- Acione eventos usando a Stripe CLI ou use o Stripe for Visual Studio Code.