Como funcionam as 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:

• Suporte para diferentes modelos de planos de preços
• Gerenciamento de descontos de assinatura
• Gerenciamento de avaliações
• Pro rata para assinaturas modificadas
• Gerenciamento de autoatendimento do cliente
• Invoicing para recolher pagamentos
• Recuperação de receitas automatizada
• Relatórios e análises

O ciclo de vida da assinatura

Este é o fluxo de assinatura recomendado:

1. Crie a assinatura. O status da assinatura será incomplete se você seguir estes passos. Se você criar uma assinatura sem especificar o payment_behavior, o status padrão será active.

2. A Stripe cria automaticamente uma fatura com o status open para a assinatura.

3. O cliente paga a primeira fatura.

4. Quando o pagamento é bem-sucedido:

   • O status da assinatura muda para active
   • O status da fatura é definido como paid
   • A Stripe envia um evento invoice.paid aos seus endpoints de webhook configurados

5. Você concede acesso ao seu produto. 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.

O status mudará para trialing se você oferecer avaliações que não exigem pagamentos. Quando a avaliação termina, a assinatura muda para active e o cliente com a assinatura começa a ser cobrado.

Comportamento do pagamento da assinatura

Para simplificar o gerenciamento de pagamentos com falha, crie assinaturas com payment_behavior definido como default_incomplete. As assinaturas são criadas com o status incomplete, o que permite coletar e confirmar dados de pagamento em uma única interface de usuário. Quando você usa allow_incomplete ou error_if_incomplete, a Stripe tenta pagar imediatamente a fatura. Em caso de falha de pagamento, o status da assinatura muda para incomplete, ou a criação falha.

Pagamentos bem-sucedidos

Quando o cliente paga a fatura, o status da assinatura é atualizado para active, e o da fatura é atualizado para paid. Nesse momento, você pode conceder acesso ao produto.

Janela de pagamento

Os clientes têm cerca de 23 horas para concluir o pagamento. Nesse período, a assinatura permanece no status incomplete, e a fatura permanece open. Quando o cliente paga a fatura, a assinatura é atualizada para active, e a fatura atualiza para paid. Se o cliente não pagar, a assinatura será atualizada para incomplete_expired, e a fatura mudará para void.

Esse cronograma existe porque o primeiro pagamento de uma assinatura geralmente é feito com o cliente na sessão. Se o cliente retornar ao aplicativo após 23 horas, crie outra assinatura para ele.

Pagamentos malsucedidos

O status da assinatura permanece active enquanto os pagamentos automáticos são bem-sucedidos. Quando o pagamento automático falha, a assinatura é atualizada para past_due, e a Stripe tenta recuperar o pagamento de acordo com as regras para novas tentativas. Se a recuperação também falhar, você poderá definir o status da assinatura como canceled, unpaid ou deixá-lo como past_due.

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 ciclo de faturamento, que permanecem no estado draft. Para reativar a assinatura:

1. Colete novos dados de pagamento, se necessário.

2. Habilite a cobrança automática definindo o auto_advance como true em faturas provisórias.

3. 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.

Faturas marcadas como incobráveis são tratadas como paid na determinação do status da assinatura, mesmo que sua propriedade paga permaneça false. A Stripe ignora faturas anuladas ao determinar o status da assinatura; a fatura não anulada mais recente é usada.

O status de uma assinatura não paga é baseado nas suas configurações de pagamento malsucedido no Dashboard.

Cancelar assinaturas

O cancelamento da assinatura desativa a criação de faturas e interrompe a cobrança automática de todas as faturas da assinatura porque define auto_advance como false. Ela também exclui a assinatura e você não poderá mais atualizar a assinatura ou seus metadados. Além disso, a assinatura é excluída. Para que o cliente assine novamente, é preciso coletar novos dados de pagamento e criar outra assinatura.

Alterar assinaturas

A Stripe permite modificar assinaturas existentes sem a necessidade de cancelá-las e recriá-las. As alterações mais significativas permitidas são fazer upgrade ou downgrade do preço da assinatura, ou cancelar ou suspender a cobrança de pagamento de uma assinatura ativa. Saiba mais sobre como modificar assinaturas existentes.

Gerenciar sessões de checkout

Para integrações do Stripe Checkout, você não pode atualizar a assinatura ou sua fatura se a assinatura da sessão estiver no status incomplete. Escute o evento checkout.session.completed para fazer a atualização após a conclusão da sessão.

Você também pode expirar a sessão se quiser cancelar a assinatura da sessão, anular a fatura da assinatura ou marcar a fatura como incobrável.

Exemplo de integração

Esta seção descreve o nosso exemplo de integração no GitHub, que mostra como criar uma integração de assinaturas. Se estiver com tudo pronto para criar sua própria integração, consulte o guia de início rápido do Billing ou o guia de integração.

Página de chegada

No front-end, a página de chegada coleta inicialmente o e-mail. O aplicativo pode coletar outros dados específicos do cliente que você desejar, como nome de usuário ou endereço. Depois que o cliente clica no botão de inscrição, os dados coletados na página de chegada são enviados para o back-end. Esse processo cria um cliente e exibe a página de preços no front-end.

Página de preços

A página de preços exibe as opções de assinatura de acordo com os produtos e preços criados durante a configuração da integração, ou seja, não é preciso criar outros sempre que um cliente se inscreve. A página de preços exibe os preços criados e os clientes escolhem a opção desejada. O exemplo no GitHub exibe um formulário de pagamento quando um cliente seleciona uma opção. Saiba mais sobre produtos e preços.

Pagamento

O formulário de pagamento coleta o nome e os dados do cartão. A Stripe hospeda esse formulário se você usar o Checkout. Esse é um dos principais recursos que permite receber pagamentos em conformidade com o PCI. Quando o cliente clica em Assinar:

1. Cria uma assinatura com os IDs do cliente e do preço.
2. Gera uma fatura para seu ciclo de assinatura inicial.
3. Coleta dados de pagamento e paga a fatura.
4. Define a forma de pagamento como forma de pagamento padrão da assinatura, um requisito para os próximos pagamentos.

Não deixe de confirmar o pagamento antes de provisionar acesso para o seu cliente.

Para implementar isso:

• Aceitar pagamentos sem código: se você não quiser programar, saiba como criar um Payment Link e compartilhá-lo com os clientes.
• Criar uma página de checkout: use a API Checkout Sessions para aceitar pagamentos por meio de uma página hospedada, um formulário integrado em seu site ou uma página de checkout personalizada com componentes integrados.
• Integração avançada: use o Stripe Elements para coletar detalhes de pagamento e ativar a assinatura com o Payment Element.

Provisionamento

Use os direitos para determinar quando você pode conceder ou revogar acesso a recursos de produtos aos clientes. Como alternativa, após um pagamento bem-sucedido, você pode fornecer o produto com segurança para o cliente. Isso geralmente significa:

1. Verificar se o status da assinatura é active.
2. Conceder ao cliente o acesso aos produtos e recursos assinados.

Saiba como usar destinos de evento para:

• Acompanhar assinaturas ativas
• Gerenciar falhas de pagamento
• Verificar objetos Event

Como funcionam os pagamentos de assinaturas

Para simplificar o gerenciamento de falhas de pagamento e criar assinaturas antes de tentar o pagamento:

1. Passe payment_behavior=default_incomplete quando criar uma assinatura. Se ela exige pagamento, é criada com um status incomplete. Nos demais casos, ela se torna imediatamente active.

2. Activate an incomplete subscription by paying the first invoice.

3. Passe a identificação da intenção de pagamento da fatura para a interface de usuário a fim de coletar dados de pagamento e confirmar a intenção de pagamento. Você pode usar o Elements, o SDK para Android ou o iOS SDK.

Cobranças recorrentes

A Stripe gerencia as cobranças recorrentes para você de forma automática, incluindo:

• Faturamento automático dos clientes e tentativa de pagamento no início de novos ciclos de cobrança.
• Quando os pagamentos falham, a Stripe faz novas tentativas usando o recurso Smart Retries ou seu cronograma personalizado de novas tentativas. Isso faz uma nova tentativa automática de pagamento de acordo com as configurações do seu Dashboard quando os cartões são recusados. Se uma falha retornar um código de recusa rígido, as novas tentativas agendadas continuam, mas o pagamento somente é executado se você obter uma nova forma de pagamento.

Você pode enviar um e-mail de cobrança aos clientes com pagamentos em atraso a fim de aumentar a chance de êxito na recuperação. Para pagamentos que exigem 3D Secure, você pode definir as configurações de faturamento para enviar um link hospedado aos clientes para que concluam o fluxo.

Status do pagamento

O processo de pagamento varia em função das formas de pagamento e da localização geográfica. Além disso, os pagamentos podem falhar inicialmente (o cliente pode informar um número de cartão incorreto ou não ter saldo suficiente). Por isso, há vários resultados possíveis para o pagamento.

Um PaymentIntent rastreia o ciclo de vida de cada pagamento. Sempre que um pagamento para 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 estado do PaymentIntent afeta o estado da fatura e da assinatura. Veja como os diferentes resultados de um pagamento são mapeados para os diferentes status:

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

Pagamento bem-sucedido

Quando o pagamento é finalizado, o status do PaymentIntent é succeeded, e a assinatura torna-se active. Para formas de pagamento com períodos de processamento mais demorados, as assinaturas são ativadas imediatamente. Nesses casos, o status do PaymentIntent pode permanecer processing para uma assinatura active até que o pagamento seja finalizado.

Com sua assinatura ativada, forneça acesso ao seu produto. Leia o guia para saber mais sobre o ciclo de vida da assinatura e ver práticas recomendadas de provisionamento.

{
  "id": "sub_1ELI8bClCIKljWvsvK36TXlC",
  "object": "subscription",
  "status": "active",
  ...
  "latest_invoice": {
    "id": "in_EmGqfJMYy3Nt9M",
    "status": "paid",
    "payments": {
      "data": [
        {
          "payment": {
            "type": "payment_intent",
            "payment_intent": {
              "status": "succeeded",
              ...
            }
          }
          ...
        }
      ],
    ...
  }
}

Exige forma de pagamento

Quando o pagamento falha por erro no cartão (por exemplo, uma recusa), o status do PaymentIntent é requires_payment_method, e a assinatura é incomplete.

{
  "id": "sub_1ELI8bClCIKljWvsvK36TXlC",
  "object": "subscription",
  "status": "incomplete",
  ...
  "latest_invoice": {
    "id": "in_EmGqfJMYy3Nt9M",
    "status": "open",
    "payments": {
      "data": [
        {
          "payment": {
            "type": "payment_intent",
            "payment_intent": {
              "status": "requires_payment_method",
              ...
            }
          }
          ...
        }
      ],
      ...
    }
  }
}

Para resolver esses cenários:

• Avise o cliente.
• Colete dados de pagamento e confirme o PaymentIntent.
• Atualize a forma de pagamento padrão na assinatura.

Saiba como gerenciar falhas de pagamento de assinaturas.

Exige ação

Algumas formas de pagamento exigem autenticação do cliente com 3D Secure (3DS) para concluir o processo de pagamento. Se você usa a API Payment Intents, o valor status do PaymentIntent é requires_action quando um cliente precisa autenticar um pagamento. Você pode obter o PaymentIntent no recurso Invoice Payment expandindo latest_invoice.payments.data.payment.payment_intent ou especificando o parâmetro da fatura com a lista Invoice Payment. O 3DS conclui o processo de autenticação. Suas regras de Radar e as do banco emissor do cartão determinam se uma forma de pagamento precisa de autenticação.

Geralmente, as regulamentações na Europa exigem o 3D Secure. Consulte Autenticação Forte de Cliente para determinar se o gerenciamento desse status é importante para a empresa. Se você já tiver uma integração de faturamento e quiser aceitar esse fluxo, consulte também o guia de migração para SCA do Billing.

{
  "id": "sub_1ELI8bClCIKljWvsvK36TXlC",
  "object": "subscription",
  "status": "incomplete",
  ...
  "latest_invoice": {
    "id": "in_EmGqfJMYy3Nt9M",
    "status": "open",
    ...
    "payments": {
      "data": [
        {
          "payment": {
            "type": "payment_intent",
            "payment_intent": {
              "status": "requires_action",
              "client_secret": "pi_91_secret_W9",
              "next_action": {
                "type": "use_stripe_sdk",
                ...
              },
              ...
            }
          }
          ...
        }
      ],
    }
  }
}

Para gerenciar esses cenários:

• Monitore a notificação de evento invoice.payment_action_required com endpoints de webhook. Isso indica que a autenticação é necessária.
• Avise o cliente de que a autenticação é necessária.
• Acesse o segredo do cliente para a intenção de pagamento e passe-o em uma chamada para stripe.ConfirmCardPayment. Isso exibe um modal de autenticação para seus clientes, tenta o pagamento e, em seguida, fecha o modal e retorna o contexto para seu aplicativo.
• Monitore o evento invoice.paid no seu destino de evento para verificar se o pagamento foi bem-sucedido. Os usuários podem sair do aplicativo antes do término de confirmCardPayment(). Verificar se o pagamento foi bem-sucedido permite provisionar corretamente seu produto.

Status da assinatura

Configurações e recuperação de assinatura

Suas configurações de assinatura determinam como a Stripe responde a falhas de pagamentos ou vencimento de assinaturas.

Smart Retries

Após a criação de uma assinatura, a falha no pagamento é um dos eventos mais críticos que podem ocorrer. Essas falhas podem acontecer por diversos motivos:

• Cliente sem forma de pagamento.
• A forma de pagamento expirou.
• O pagamento foi recusado.

Você pode configurar o Stripe para tentar novamente os pagamentos com falha por até dois meses acessando Gerenciar pagamentos com falha para assinaturas no Dashboard. O recurso Smart Retries utiliza inteligência artificial para determinar o melhor momento para novas tentativas dentro do período definido.

Você também pode modificar o cronograma de novas tentativas com regras personalizadas. Até três tentativas podem ser configuradas, cada uma iniciada um número específico de dias após a tentativa anterior.

Você pode usar o evento invoice.payment_failed para monitorar eventos de falha de pagamento de assinatura e tentar atualizar novamente. Após uma tentativa de pagamento de uma fatura, o valor de next_payment_attempt é definido usando as configurações de assinatura atuais do Dashboard.

Quando a recuperação falha, o status da assinatura muda de acordo com as configurações. As opções são:

Após a tentativa de pagamento final, não fazemos nenhuma outra tentativa. As alterações nas configurações de assinatura afetam apenas as tentativas futuras.

E-mails

A Stripe pode enviar diferentes e-mails para os clientes usando os endereços associados ao objeto Customer:

• Um lembrete de renovação próxima ao mesmo tempo em que enviamos o evento invoice.upcoming para assinaturas configuradas para cobrar o pagamento automaticamente.
• Uma notificação de pagamento não efetivado, solicitando que os clientes atualizem dos dados de pagamento. Saiba como ativar notificações de pagamentos não efetivados.
• Uma notificação de cartão vencendo quando o cartão default_source do cliente está prestes a expirar.

Você pode personalizar os logotipos e as cores que seus clientes veem nos e-mails e na página de pagamento de fatura hospedada alterando as configurações de marca no Dashboard.

Avaliações

As bandeiras de cartão exigem que seus clientes sejam notificados sobre cobranças de teste. A Stripe pode cuidar dessa comunicação para você. No Dashboard, você pode definir o URL de cancelamento que será incluído nos e-mails de lembrete e no recibo da primeira fatura após o término do período de avaliação. Você também pode configurar o descritor da cobrança que aparecerá na fatura referente à primeira cobrança após o período de teste. Saiba mais sobre esses requisitos e opções na página sobre avaliações gratuitas.

Objetos de assinatura

Use estes recursos principais da API para criar e gerenciar assinaturas:

Aqui está um exemplo de como produtos, recursos e direitos funcionam juntos. Imagine que você deseja configurar um serviço de assinatura que oferece dois níveis: um produto padrão com funções básicas e um produto avançado que adiciona funções estendidas.

1. Você cria dois recursos: basic_features e extended_features.
2. Você cria dois produtos: standard_product e advanced_product.
3. Para o produto padrão, você cria uma ProductFeature que associa basic_features com standard_product.
4. Para o produto avançado, você cria duas ProductFeatures: uma que associa basic_features com advanced_product e outra que associa extended_features com advanced_product.

Um cliente, first_customer, assina o produto padrão. Quando você cria a assinatura, a Stripe cria automaticamente um Entitlement que associa first_customer com basic_features.

Outro cliente, second_customer, assina o produto avançado. Quando você cria a assinatura, a Stripe cria automaticamente dois Entitlements: um que associa second_customer a basic_features e outro que associa second_customer com extended_features.

É possível determinar quais recursos fornecer para um cliente recuperando seus direitos ativos ou escutando o evento Active Entitlement Summary. Você não precisa buscar as assinaturas, os produtos e os recursos dele.

Eventos de assinatura

Os eventos são acionados sempre que uma assinatura é criada ou alterada. Nós enviamos alguns eventos imediatamente quando a assinatura é criada, mas outros se repetem em intervalos de cobrança regulares. Recomendamos ouvir eventos com endpoints de webhook.

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.

Consulte Eventos de assinatura para obter uma lista dos eventos mais comuns relacionados a assinaturas e, quando aplicável, ações sugeridas para lidar com os eventos.