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.

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.

You can determine which features to provision for a customer by retrieving their active entitlements or listening to the Active Entitlement Summary event. You don’t have to retrieve their subscriptions, products, and features.

Exemplo de integração

Esta seção descreve o exemplo de integração no GitHub, que mostra como criar uma integração com o Subscriptions. Se você está 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 escolhe 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 o ciclo inicial da assinatura.
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.

Para implementar isso:

• No code: se você não quiser programar, saiba como criar um Payment Link e compartilhá-lo com os clientes.
• Low-code: se você usa o Checkout, saiba como adicionar ao site um botão que cria uma sessão do Checkout.
• Programação personalizada: se você usa o Elements, saiba como coletar dados de pagamento e ativar a assinatura com o Payment Element ou Card Element.

Provisionamento

Use Direitos para determinar quando você pode conceder ou revogar o acesso a recursos de produtos dos seus clientes.

Por outro lado, após o pagamento, você pode provisionar 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:

• Monitorar 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. Ative uma assinatura incompleta pagando a primeira fatura.
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.

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 acompanha o ciclo de vida de cada pagamento. A Stripe gera uma fatura e um PaymentIntent para cada vencimento da assinatura. O ID do PaymentIntent é associado à fatura e você pode acessá-lo nos objetos Invoice e Subscription. O estado do PaymentIntent afeta o estado da fatura e da assinatura. Veja como os vários resultados de um pagamento são associados aos 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",
    ...
    "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",
    ...
    "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 de latest_invoice.payment_intent.status é requires_action quando um cliente precisa autenticar um pagamento. O 3DS conclui o processo de autenticação. Suas regras do 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",
    ...
    "payment_intent": {
      "status": "requires_action",
      "client_secret": "pi_91_secret_W9",
      "next_action": {
        "type": "use_stripe_sdk",
        ...
      },
      ...
    }
  }
}

Para gerenciar esses cenários:

• Monitor da notificação de evento invoice.payment_action_required with destinos de evento. This indicates that authentication is required.
• 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.

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 um pagamento falha, 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 Dashboard quando os cartões são recusados. Se uma falha retornar um código de recusa sem possibilidade de ser tentado novamente, 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.

Criar seu próprio gerenciamento de falhas nas cobranças recorrentes

Se você não quer usar as ferramentas da Stripe para gerenciar falhas, pode criar suas próprias ferramentas. Quando um pagamento falha ou exige autenticação do cliente, o status da assinatura é definido como past_due e o status do PaymentIntent é requires_payment_method ou requires_action.

Para gerenciar esses cenários, configure um destino de evento e ouça o evento customer.subscription.updated para ser notificado quando as assinaturas entram no estado past_due:

{
  "id": "sub_E8uXk63MAbZbto",
  "object": "subscription",
  ...
  "status": "past_due",
  "latest_invoice": "in_1EMLu1ClCIKljWvsfTjRFAxa"
}

Para essas assinaturas, você precisa retornar os clientes ao aplicativo para coletar uma forma de pagamento diferente e finalizar o pagamento. Você pode usar um e-mail ou uma notificação enviada ao celular. A Stripe fornece e-mails de lembrete integrados para gerenciar esses casos. Você pode configurá-los na página de configurações de faturamento.

Quando o cliente voltar ao aplicativo, reutilize o fluxo de falha de pagamento ou o fluxo de ação do cliente, dependendo do status do PaymentIntent associado. Depois que o pagamento é bem-sucedido, o status da assinatura é active, e o da fatura é paid.

Gerenciar faturas sem pagamento

Geralmente, assinaturas que incluem avaliações gratuitas, faturamento por uso, faturas com aplicação de cupons ou saldos de crédito de cliente geram faturas sem pagamento. Isso significa que você não cobra imediatamente o cliente na criação da fatura.

Mesmo que você não cobre os clientes na primeira fatura, geralmente é útil autenticar e autorizar o cartão, pois isso pode aumentar a chance de êxito do primeiro pagamento diferente de zero. Esses pagamentos são conhecidos como pagamentos fora da sessão. A Stripe criou o SetupIntents para gerenciar esses cenários.

Usar SetupIntents

Você pode usar os SetupIntents para:

• Colete os dados de pagamento.
• Autentique o cartão do cliente para solicitar isenções depois.
• Autorize o cartão do cliente sem cobrá-lo.

A autenticação de pagamentos permite que o cliente conceda permissões para cobrar o cartão. Esse é um requisito da Autenticação Forte de Cliente e, muitas vezes, é cumprido usando 3DS. A coleta de dados da forma de pagamento, e a autenticação garante uma cobrança bem-sucedida da forma de pagamento.

Em cenários fora da sessão, o SetupIntents permite cobrar o primeiro pagamento diferente de zero dos clientes sem que eles tenham de voltar ao site ou aplicativo para autenticação, o que simplifica a experiência do usuário.

O campo pending_setup_intent em uma assinatura não cancela automaticamente quando a assinatura termina. Escute os eventos customer.subscription.deleted e cancele manualmente uma assinatura SetupIntent se for necessário.

A Stripe cria automaticamente SetupIntents para assinaturas que não exigem um pagamento inicial. Os processos de autenticação e autorização também são executados, se necessários. Se os dois são bem-sucedidos ou não são necessários, nenhuma ação é exigida, e o campo subscription.pending_setup_intent é null. Se um deles falha, a Stripe recomenda usar o SetupIntent no front-end para resolver o problema enquanto o cliente está na sessão. Nas próximas duas seções, explicamos detalhadamente como gerenciar cenários com falha de autenticação ou autorização.

Gerenciar falhas de autenticação Lado do cliente

As falhas de autenticação ocorrem quando a Stripe não consegue autenticar o cliente no emissor do cartão. Quando isso acontece, o status do SetupIntent é definido como requires_action.

Para resolver esses cenários, chame confirmCardSetup no front-end para que o cliente conclua manualmente o fluxo de autenticação. O exemplo de código abaixo expande o pending_setup_intent para concluir o fluxo.

const {pending_setup_intent} = subscription;

if (pending_setup_intent) {
  const {client_secret, status} = subscription.pending_setup_intent;

  if (status === "requires_action") {
    const {setupIntent, error} = await stripe.confirmCardSetup(client_secret);

    if (error) {
      // Display error.message in your UI.
    } else {
      // The setup has succeeded. Display a success message.
    }
  }
}

Após a conclusão do fluxo, a autorização é executada, se necessária. Quando a autorização é bem-sucedida ou não é necessária, pending_setup_intent é atualizado para null depois da conclusão.

Gerenciar falhas de autorização Lado do cliente

As falhas na autorização de pagamento ocorrem quando a Stripe não consegue verificar se um cartão pode ser cobrado. Quando isso ocorre, o status do SetupIntent é definido como requires_payment_method. Geralmente, isso significa que cobranças subsequentes nesse cartão também falharão.

Para resolver esses cenários, colete uma nova forma de pagamento e atualize a forma de pagamento padrão do cliente ou da assinatura. O exemplo de código abaixo expande pending_setup_intent para concluir o fluxo.

const {pending_setup_intent, latest_invoice} = subscription;

if (pending_setup_intent) {
  const {client_secret, status} = subscription.pending_setup_intent;

  if (status === "requires_action") {
    const {setupIntent, error} = await stripe.confirmCardSetup(client_secret);

    if (error) {
      // Display error.message in your UI.
    } else {
      // The setup has succeeded. Display a success message.
    }
  } else if (status === "requires_payment_method") {
    // Collect new payment method
  }
}

O ciclo de vida da assinatura

Este é o fluxo de assinatura recomendado:

1. Você cria a assinatura. O status da assinatura é incomplete (quando você segue o fluxo recomendado; para assinaturas criadas sem especificar payment_behavior, o status padrão é active).
2. Uma fatura é criada para a assinatura. O status da fatura é open.
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 destinos de evento configurados.
5. Você provisiona acesso ao produto. Para confirmar se a fatura foi paga:
   • Configure um destino de evento e escute 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 também pode se tornar 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 muda para active, e o da fatura muda para paid. 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 muda para paid. Se o cliente não pagar, a assinatura será atualizada para incomplete_expired, e a fatura mudará para void.

Esse intervalo 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 não pagas, a fatura mais recente permanece em aberto, mas não são feitas tentativas de pagamento. A assinatura continua a gerar faturas a cada ciclo de faturamento e permanecem no estado draft. Para reativar a assinatura, é preciso:

• Colete os novos dados de pagamento.
• Reative a cobrança automática definindo auto advance como true nas faturas provisórias.
• Finalize e pague as faturas em aberto. Pague a fatura mais recente antes da data de vencimento para atualizar o status para active.

Assinaturas past_due são definidas como unpaid por padrão para oferecer o maior número de opções de reativação.

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.

Anular uma fatura gerada por assinatura

Se a assinatura estiver incomplete e você anular a primeira fatura gerada, a assinatura será atualizada para incomplete_expired. Se você anular a fatura mais recente de uma assinatura ativa e essa fatura não for a primeira, será aplicada a seguinte lógica a cada fatura (da mais recente para a mais antiga) até que uma das condições seja atendida:

• Em faturas no estado paid ou uncollectible, o estado da assinatura é definido como active.
• Se collection_method estiver definido como charge_automatically na fatura e a Stripe interromper a cobrança na fatura devido a limites de novas tentativas, o estado da assinatura será definido como canceled, unpaid ou past_due com base nas suas configurações de cobrança automática.
• Se collection_method estiver definido como send_invoice e a fatura estiver vencida, o estado da assinatura será definido como past_due.
• Se a fatura não tem em nenhum desses estados, as mesmas etapas são executadas na fatura mais recente.

Se nenhuma fatura corresponder aos critérios acima, o estado da assinatura será definido como active.

Sessões do 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.

Obter informações de referência

Você pode usar os Stripe Apps de afiliados e indicados para configurar e gerenciar programas de indicados e afiliados com a Stripe, obter dados dos clientes e automatizar ajustes de comissão no Stripe Dashboard.

Status da assinatura

Eventos de assinatura

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 faturamento regulares. Recomendamos ouvir eventos com um destino de evento.

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 gerenciá-los.

Ciclo de vida da fatura

A visão geral de faturas oferece uma explicação mais detalhada sobre o funcionamento das faturas. O ciclo de vida básico das faturas geradas por assinaturas tem a seguinte aparência:

1. A assinatura gera uma nova fatura no estado draft.
2. Cerca de uma hora após a criação da fatura, ela é finalizada (não pode mais ser alterada).
3. O status é definido como open e a Stripe tenta pagá-la automaticamente usando a forma de pagamento padrão.
4. Quando o pagamento é bem-sucedido, o status é atualizado para paid.
5. Se o pagamento falhar, a fatura permanecerá open e a assinatura se tornará past_due.

Neste fluxo, a Stripe não notifica o cliente sobre a fatura. A tentativa de pagamento da fatura é repetida automaticamente logo após sua geração. Se os e-mails do cliente estiverem ativados, enviaremos um recibo por e-mail.

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 da fatura, o evento mais importante que pode acontecer é a falha do pagamento. As falhas ocorrem por vários motivos:

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

Você pode configurar a Stripe para refazer pagamentos que falharam. O Smart Retries use o machine learning da Stripe para escolher o momento ideal para refazer o pagamento durante um período configurável de até um 2 meses após a falha do pagamento inicial.

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 quando enviamos o evento invoice.upcoming.
• 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 seu URL para atualizar o cartão, bem como o seu logotipo e as cores usadas no e-mail, conforme descrito na documentação sobre recibos.

Pagamento manual

Você pode configurar a data de vencimento para faturas que usam o send_invoice collection method para receber pagamentos manuais. Também é possível configurar até três lembretes, desde 10 dias antes da data de vencimento até 60 dias depois.

Você também pode tomar providências na assinatura 30, 60 ou 90 dias após o vencimento de uma fatura. As opções são:

Saiba mais sobre status de assinaturas.

Pagamentos que exigem 3D Secure

Para pagamentos que exigem 3D Secure, a Stripe pode enviar um e-mail de confirmação ao cliente ao mesmo tempo que enviamos o evento invoice.payment_action_required. Também é possível configurar o envio de até três lembretes de 1 a 7 dias após o início do pagamento.

Quando um pagamento não é concluído após o número de dias definido, você pode:

Avaliações

As bandeiras de cartão exigem que você informe seus clientes sobre as avaliações. A Stripe pode gerenciar essa comunicação para você. No Stripe Dashboard, é possível configurar o URL de cancelamento incluído nos e-mails de lembrete e no recibo da primeira fatura após o término da avaliação. Também existe a possibilidade de configurar a descrição no extrato para a primeira cobrança após a avaliação. Saiba mais sobre esses requisitos e configurações na página de avaliações.

Alterar assinaturas

A Stripe aceita 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.