Como funcionam as assinaturas

Gerencie pagamentos recorrentes e ciclos de vida de assinaturas.

Com Subscriptions, os clientes fazem pagamentos recorrentes para acessar um produto. Como você precisa cobrar as assinaturas no futuro, é necessário reter mais dados sobre os clientes do que nas compras avulsas.

A Stripe oferece muitos recursos que ajudam você a gerenciar o faturamento de assinaturas:

O ciclo de vida da assinatura

O processo de criação e gerenciamento de assinaturas depende dos principais recursos da API da Stripe, incluindo Clientes, Faturas e PaymentIntents. Consulte Definições de objetos da API para obter a lista completa de recursos relacionados à assinatura.

Este é o fluxo de assinatura recomendado:

Criar a assinatura

Você pode criar uma nova assinatura no Dashboard ou com a API. Toda vez que você cria uma assinatura, um evento é acionado. Ouça esses eventos com os endpoints do Webhook e certifique-se de que sua integração os trate adequadamente.

Opcionalmente, você pode criar uma versão de teste que não exija pagamentos para a assinatura. Nesse caso, o status é trialing. Quando o teste termina, a assinatura passa para active e o cliente assinante é cobrado.

Comportamento do pagamento

Recomendamos que você defina payment_behavior de uma assinatura como default_incomplete para ajudar a lidar com pagamentos com falha e fluxos de pagamento complexos, como o 3DS. Isso criará assinaturas com status incomplete se o pagamento for necessário, o que permite que você colete e confirme as informações de pagamento para ativar a assinatura mais tarde.

Se você definir payment_behavior como allow_incomplete, a Stripe tentará imediatamente recolher o pagamento da fatura. Se o pagamento falhar, o status da assinatura muda para incomplete. Se você definir payment_behavior como error_if_incomplete, a criação da assinatura falhará se o pagamento falhar.

As assinaturas que você cria no Dashboard adotam o comportamento de pagamento apropriado conforme a forma de pagamento.

Tratar a fatura

Ao criar uma assinatura, a Stripe gera automaticamente uma fatura com o status open. Seu cliente tem cerca de 23 horas para efetuar um pagamento. Nesse período, o status da assinatura permanece incomplete e o status da fatura permanece open. Esse período de 23 horas existe porque seu cliente costuma fazer o primeiro pagamento de uma assinatura enquanto está na sessão. Se o cliente retornar ao aplicativo após 23 horas, crie uma nova assinatura para ele.

O cliente paga

Se o cliente pagar a fatura, a assinatura será atualizada para active e a fatura, para paid. Se ele não efetuar o pagamento, a assinatura será atualizada para incomplete_expired e a fatura se tornará void.

Para confirmar se a fatura foi paga:

Configure um endpoint de webhook ou outro tipo de destino de evento e ouça o evento invoice.paid.
Verifique manualmente o objeto de assinatura e procure subscription.status=active. O status muda para active quando a fatura é paga por uma cobrança automática ou manualmente pelo cliente.

Para obter mais detalhes, consulte Status de assinatura e Status de pagamento.

Provisionar acesso ao seu produto

Ao criar uma assinatura para um cliente, você cria um direito ativo para cada recurso associado a esse produto. Quando um cliente acessa seus serviços, use os direitos ativos dele para conceder acesso aos recursos incluídos na assinatura.

Como alternativa, você pode rastrear assinaturas ativas com eventos de webhook e provisionar o produto para o cliente com base nessa atividade.

Atualizar a assinatura

Você pode modificar as assinaturas existentes conforme necessário, sem precisar cancelá-las e recriá-las. Algumas das alterações mais significativas que você pode fazer são upgrade ou downgrade do preço da assinatura ou pausa na cobrança do pagamento de uma assinatura ativa.

You can listen to subscription events with webhook endpoints for changes to the subscription. For example, you might want to email a customer if a payment fails or revoke a customer’s access when they cancel their subscription.

Em integrações do Stripe Checkout, você não poderá atualizar a assinatura ou sua fatura se a assinatura da sessão estiver incomplete. Você pode ouvir o evento checkout.session.completed para fazer a atualização após a conclusão da sessão. Você também poderá expirar a sessão se desejar cancelar a assinatura da sessão, anular a fatura da assinatura ou marcar a fatura como incobrável.

Lidar com assinaturas não pagas

Para assinaturas com faturas não pagas, as faturas não pagas permanecem abertas, mas novas tentativas de pagamento são suspensas. A assinatura continua gerando faturas a cada período de cobrança, que permanecem no estado draft. Para reativar a assinatura:

Colete novos dados de pagamento, se necessário.
Habilite a cobrança automática definindo o auto_advance como true em faturas provisórias.
Finalize e pague as faturas abertas. O pagamento da fatura não anulada mais recente antes da data de vencimento atualiza o status da assinatura para active.

As faturas marcadas como incobráveis mantêm a assinatura subjacente active. A Stripe ignora faturas anuladas ao determinar o status da assinatura e usa a fatura não anulada mais recente.

O status da assinatura não paga depende das suas configurações de falha de pagamento no Dashboard.

Cancelar a assinatura

Você pode cancelar uma assinatura a qualquer momento, inclusive no final de um ciclo de faturamento ou após um número definido de ciclos de faturamento.

Por padrão, o cancelamento de uma assinatura desabilita a criação de novas faturas e interrompe a cobrança automática de todas as faturas pendentes da assinatura. Também exclui a assinatura e você não poderá mais atualizá-la ou seus metadados. Se o seu cliente quiser assinar novamente, você precisará coletar novas informações de pagamento e criar uma nova assinatura.

Status da assinatura

As assinaturas podem ter os status a seguir. As ações a serem executadas em uma assinatura dependem do seu status.

Status	Descrição
`trialing`	A assinatura está em período de avaliação e você pode fornecer seu produto com segurança para o cliente. A assinatura muda automaticamente para `active` quando o cliente faz o primeiro pagamento.
`active`	a assinatura está adimplente. Para assinaturas `past_due`, pagar a fatura associada mais recente ou marcá-la como incobrável faz a assinatura mudar para `active`. `active` não indica que todas as faturas pendentes associadas à assinatura foram pagas. Você pode deixar outras faturas pendentes abertas para pagamento, marcá-las como incobráveis ou anulá-las como achar melhor.
`incomplete`	O cliente precisa fazer um pagamento em até 23 horas para ativar a assinatura. Ou o pagamento demanda atenção, como autenticação do cliente. As assinaturas também podem ficar `incomplete` se houver um pagamento pendente e o status do PaymentIntent for `processing`.
`incomplete_expired`	O pagamento inicial da assinatura falhou e o cliente não concretizou o pagamento em 23 horas após a criação da assinatura. Essas assinaturas não cobram os clientes. Esse status existe para que você acompanhe os clientes que não ativaram as assinaturas.
`past_due`	O pagamento da última fatura finalizada falhou ou não foi tentado. A assinatura continua a criar faturas. As configurações de assinatura do seu Dashboard determinam o próximo status da assinatura. Se a fatura ainda não tiver sido paga depois de todos os Smart Retries tentados, você poderá configurar a assinatura de modo a passar para `canceled`, `unpaid` ou deixá-la como `past_due`. Para reativar a assinatura, peça para o cliente pagar a fatura mais recente. O status da assinatura torna-se `active` independentemente de o pagamento ser feito antes ou depois da data de vencimento da fatura mais recente.
`canceled`	A assinatura foi cancelada. Durante o cancelamento, a cobrança automática de todas as faturas não pagas é desativada (`auto_advance=false`). Este estado é terminal e não pode ser atualizado.
`unpaid`	A fatura mais recente não foi paga, mas a assinatura continua ativa. A última fatura está aberta e as faturas continuam a ser geradas, mas não são feitas tentativas de pagamento. Suspensa o acesso ao seu produto quando a assinatura estiver `unpaid`, porque as tentativas de pagamento já foram feitas enquanto estava em `past_due`. Para colocar a assinatura no modo `active`, pague a fatura mais recente antes do vencimento.
`paused`	A período de avaliação da assinatura terminou sem uma forma de pagamento padrão e o trial_settings.end_behavior.missing_payment_method está definido como `pause`. Não são criadas mais faturas para a assinatura. Após vincular uma forma de pagamento padrão ao cliente, você pode reiniciar a assinatura.

Status de pagamento

Um PaymentIntent rastreia o ciclo de vida de cada pagamento. Sempre que o pagamento de uma assinatura vence, a Stripe gera uma fatura e um PaymentIntent. O ID do PaymentIntent é anexado à fatura e você pode acessá-lo a partir dos objetos Fatura e Assinatura.

O status do PaymentIntent afeta o status da fatura e da assinatura. Veja como os diferentes resultados de um pagamento são mapeados para os diferentes status:

Resultado do pagamento	Status do PaymentIntent	Status da fatura	Status da assinatura
Sucesso	`succeeded`	`paid`	`active`
Falhas por erro no cartão	`requires_payment_method`	`open`	`incomplete`
Falhas por autenticação	`requires_action`	`open`	`incomplete`

Observação

Formas de pagamento assíncronas, como ACH Direct Debit, gerenciam transições de status de assinatura de forma diferente das formas de pagamento imediatas. Quando você usa formas de pagamento assíncronas, as assinaturas passam diretamente para um estado active na criação, ignorando o status incomplete normalmente associado a outros tipos de pagamento. Se um pagamento assíncrono falhar posteriormente, ela anulará a fatura associada; porém, a assinatura permanece no estado active. Esse comportamento contrasta com formas de pagamento imediatas, em que pagamentos com falha geralmente resultam em um estado incomplete ou past_due. Esteja ciente dessa distinção e implemente lógica apropriada para gerenciar o status da assinatura, do controle de acesso e dos mecanismos de novas tentativas de pagamento.

As próximas seções explicam esses status e o que fazer para cada um deles.

Pagamento bem-sucedido

Quando o pagamento do cliente é realizado:

O status do PaymentIntent passa para succeeded.
O status da assinatura é active.
O status da fatura é paid.
A Stripe envia um evento invoice.paid aos seus endpoints de webhook configurados.

Para as formas de pagamento com períodos de processamento mais longos, as assinaturas são ativadas imediatamente. Nesses casos, o status do PaymentIntent pode ser processing para uma assinatura active até que o pagamento seja realizado.

Agora que sua assinatura está ativada, provisione acesso ao produto.

Exige forma de pagamento

If payment fails because of a card error such as a decline:

O status do PaymentIntent é requires_payment_method.
O status da assinatura é incomplete.
O status da fatura é open.

Para gerenciar esses cenários:

Avise o cliente.
Colete novas informações de pagamento e confirme o PaymentIntent.
Atualize a forma de pagamento padrão na assinatura.
A Stripe tenta o pagamento novamente usando o Smart Retries ou com base nas suas regras de nova tentativa personalizadas.
Use o evento invoice.payment_failed para monitorar eventos de falha de pagamento de assinatura e atualizações de novas tentativas. Após uma tentativa de pagamento em uma fatura, seu valor next_payment_attempt é definido usando as configurações de assinatura atuais no Dashboard.

Saiba como gerenciar falhas de pagamento de assinaturas.

Exige ação

Algumas formas de pagamento exigem a autenticação do cliente com o 3D Secure (3DS) para concluir o processo de pagamento. O 3DS conclui o processo de autenticação. A exigência de autenticação de uma forma de pagamento depende das suas regras do Radar e do banco emissor do cartão.

Se o pagamento falhar porque o cliente precisa autenticar um pagamento:

O status do PaymentIntent é requires_action.
O status da assinatura é incomplete.
O status da fatura é open.