Pular para o conteúdo
Criar conta
ou
Entrar
O logotipo da documentação da Stripe
/
Pergunte à IA
Criar conta
Login
Comece já
Pagamentos
Receita
Plataformas e marketplaces
Gestão de valores
Recursos para desenvolvedores
Visão geral
Billing
Visão geralSobre as APIs do Billing
Assinaturas
    Como funcionam as assinaturas
    Início rápido
    Casos de uso
    Crie sua integração
    Recursos de assinatura
    Direitos
    Análises
Invoicing
Cobrança por uso
Cotações
Gerenciamento de clientes
Billing with other products
Recuperação de receitas
Automações
Reconhecimento de receitas
Teste sua integração
Tributos
Visão geral
Use Stripe tax
Manage compliance
Relatórios
Visão geral
Selecionar um relatório
Configure reports
API de relatórios
Relatórios para várias contas
Reconhecimento de receitas
Dados
Visão geralEsquema
Relatórios personalizados
Data Pipeline
Gerenciamento de dados
Página inicialReceitaSubscriptions

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.

Objetos de assinatura

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

RecursoDefinição
ClienteRepresenta um cliente que compra uma assinatura. Use o objeto Customer associado a uma assinatura para fazer e rastrear cobranças recorrentes e para gerenciar os produtos dos quais têm assinatura.
DireitoRepresenta o acesso de um cliente a um recurso incluído em um produto de serviço que assina. Quando você cria uma assinatura para a compra recorrente de um produto por um cliente, um direito ativo é automaticamente criado para cada recurso associado a esse produto. Quando um cliente acessa seus serviços, use os direitos ativos para habilitar os recursos incluídos na assinatura.
RecursoRepresenta uma função ou capacidade que seus clientes podem acessar quando assinam um produto de serviço. Você pode incluir recursos em um produto criando ProductFeatures.
FaturaUma declaração de valores devidos por um cliente que acompanha os status de pagamento desde o esboço até o pagamento (ou outro tipo de finalização). As assinaturas geram faturas automaticamente.
PaymentIntentUma maneira de criar fluxos de pagamentos dinâmicos. Um PaymentIntent acompanha o ciclo de vida do fluxo de checkout de um cliente e aciona etapas adicionais de autenticação quando for exigido por mandatos regulatórios, regras personalizadas contra fraudes do Radar ou formas de pagamento baseadas em redirecionamento. As faturas criam PaymentIntents automaticamente.
PaymentMethodAs formas de pagamento que um cliente usa para pagar seus produtos. Por exemplo, você pode armazenar um cartão de crédito em um objeto Customer e usá-lo para fazer pagamentos recorrentes para esse cliente. Normalmente usado com as APIs Payment Intents ou Setup Intents.
PriceDefine o preço unitário, a moeda e o ciclo de faturamento de um produto.
ProductUm produto ou serviço que sua empresa vende. Um produto de serviço pode incluir um ou mais recursos.
ProductFeatureRepresenta a inclusão de um único recurso em um único produto. Cada produto está associado a um ProductFeature para cada recurso que é incluído, e cada recurso é associado a um ProductFeature para cada produto que o inclui.
SubscriptionRepresenta a compra recorrente agendada de um produto por um cliente. Use uma assinatura para coletar pagamentos e fornecer entregas repetidas ou acesso contínuo a um produto.

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.

Como os objetos da Stripe funcionam em um ciclo de vida de assinatura.

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

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

Observação

As assinaturas criadas no Dashboard são definidas por padrão como payment_behavior=error_if_incomplete se você não usar as formas de pagamento Oxxo, Konbini ou boleto. Se o pagamento inicial falhar devido à autenticação do 3D Secure, você pode criar a assinatura com payment_behavior=default_incomplete.

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:

Resultado do pagamentoStatus do PaymentIntentStatus da faturaStatus da assinatura
Sucessosucceededpaidactive
Falhas por erro no cartãorequires_payment_methodopenincomplete
Falhas por autenticaçãorequires_actionopenincomplete

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.

RespostaAssinaturaPaymentIntent
{ "id": "sub_1ELI8bClCIKljWvsvK36TXlC", "object": "subscription", "status": "active", ... "latest_invoice": { "id": "in_EmGqfJMYy3Nt9M", "status": "paid", "payments": { "data": [ { "payment": { "type": "payment_intent", "payment_intent": { "status": "succeeded", ... } } ... } ], ... } }
activesucceeded
Fluxo da rede de pagamentos por assinatura.

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.

RespostaAssinaturaPaymentIntent
{ "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", ... } } ... } ], ... } } }
incompleterequires_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.

Como gerenciar falhas no 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.

RespostaAssinaturaPaymentIntent
{ "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", ... }, ... } } ... } ], } } }
incompleterequires_action

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.
Como gerenciar pagamentos de assinatura que exigem ação adicional do cliente.

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.

Gerenciar falhas de cobrança 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.

Objetos envolvidos no gerenciamento de pagamentos de assinaturas com falha ou ação necessária.

Para gerenciar esses cenários, configure um endpoint de webhook e ouça o evento customer.subscription.updated para ser notificado quando as assinaturas entram em um 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 Client-side

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.

Como lidar com falhas de autenticação em pagamentos de assinaturas.

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 Client-side

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.

Como gerenciar falhas de autorização de pagamento de assinaturas.

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:

Comportamento do pagamento

Quando você define payment_behavior como default_incomplete, o status da assinatura é incomplete. Saiba mais sobre por que recomendamos o uso desse tipo de comportamento de pagamento para assinaturas.

  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 endpoints de webhook configurados.
  5. Você provisiona acesso ao produto. Para confirmar se a fatura foi paga:

    • Configurar um endpoint de webhook ou outro tipo de destino de evento e escutar 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.

Fluxo de trabalho de criação e validade de assinaturas

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.

Observação

Formas de pagamento assíncronas, como ACH Direct Debit, gerenciam as transições de status da assinatura de forma diferente das formas de pagamento imediatas. Quando você usa métodos assíncronos, as assinaturas passam diretamente para um estado active no momento da criação, ignorando o estado incomplete normalmente associado a outros tipos de pagamento. Se um pagamento assíncrono falhar posteriormente, a fatura associada será anulada; no entanto, a assinatura permanece no estado active. Esse comportamento é diferente das formas de pagamento imediatas, em que pagamentos malsucedidos geralmente resultam em estados incomplete ou past_due. Conheça essa distinção e implemente uma lógica adequada para gerenciar o status da assinatura, o controle de acesso e os mecanismos de novas tentativas de pagamento.

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 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 adiantamento automático 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.

Anular uma fatura gerada por assinatura

Se você anular a primeira fatura de uma assinatura, a seguinte lógica será aplicada, dependendo do status da assinatura:

  • Se a assinatura estiver incomplete, o status da assinatura é definido como incomplete_expired.
  • Se a assinatura for past_due, o status da assinatura é definido como active.
  • Se a assinatura for active, o status da assinatura permanece inalterado.

Se você anular a fatura mais recente de uma assinatura ativa que não seja a primeira, a Stripe aplicará 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 status 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 status 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 status 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 status 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 indicação

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

StatusDescrição
trialingA 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.
activea 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.
incompleteO 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_expiredO 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_dueO 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. Se a fatura não for paga após todas as tentativas do Smart Retries, você pode configurar a assinatura para mudar para canceled, unpaid ou deixá-la como past_due. Para reativar a assinatura, peça ao cliente que pague a fatura mais recente. O status da assinatura muda para active, independentemente de o pagamento ser feito antes ou depois da data de vencimento da última fatura.
canceledA 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.
unpaidA 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.
pausedA 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.

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.

A tabela a seguir descreve os eventos mais comuns associados a assinaturas e, se for o caso, sugere ações para gerenciá-los.

customer.createdEnviado quando um Customer é criado.
customer.subscription.createdEnviado quando a assinatura é criada. O status da assinatura pode ser incomplete se a autenticação do cliente for necessária para concluir o pagamento ou se você definir payment_behavior como default_incomplete. Para saber mais, consulte o comportamento do pagamento da assinatura.
customer.subscription.deletedEnviado quando a assinatura do cliente termina.
customer.subscription.pausedEnviado quando o status de uma assinatura muda para paused. Por exemplo, isso é enviado quando uma assinatura é configurada para ser suspensa ao final de uma avaliação gratuita sem forma de pagamento. O faturamento só ocorre quando a assinatura é 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.resumedEnviado quando uma assinatura com status paused é retomada. Não se aplica quando a cobrança do pagamento é reiniciada.
customer.subscription.trial_will_endEnviado três dias antes do final do período de avaliação. O evento é acionado quando o período de avaliação é inferior a três dias.
customer.subscription.updatedEnviado 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.updatedEnviado quando os direitos ativos de um cliente são atualizados. Quando receber esse evento, você pode provisionar ou cancelar o acesso aos recursos do produto. Leia mais sobre integração com direitos.
invoice.createdEnviado quando uma fatura é criada para uma assinatura nova ou em renovação. 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.
  • Responda à notificação enviando uma solicitação para a API finalizar uma fatura.
invoice.finalizedEnviado quando uma fatura é finalizada e está pronta para pagamento.
  • Você pode enviar a fatura ao cliente. Para saber mais, consulte finalização de faturas.
  • Dependendo da configuração, cobraremos automaticamente a forma de pagamento padrão ou tentaremos fazer a cobrança. Para saber mais, consulte e-mails após a finalização.
invoice.finalization_failedNão foi possível finalizar a fatura. Leia o guia 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.
  • Inspecione last_finalization_error da fatura para determinar a causa do erro.
  • Se você usa o Stripe Tax, confira o campo automatic_tax do objeto Invoice.
  • Se automatic_tax[status]=requires_location_inputs, não é possível finalizar a fatura e cobrar os pagamentos. Notifique o cliente e colete a localização do cliente obrigatória.
  • Se automatic_tax[status]=failed, tente a solicitação outra vez mais tarde.
invoice.paidEnviado quando a fatura é paga. Você pode provisionar acesso ao produto quando recebe este evento e status é active.
invoice.payment_action_requiredEnviado quando a fatura exige autenticação do cliente. Saiba como gerenciar a assinatura quando a fatura exigir ação.

invoice.payment_failed

Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para requires_action. O status da assinatura continua incomplete somente na primeira fatura da assinatura. Você pode tomar várias providências quando um pagamento falha:

  • Avise o cliente. Saiba como configurar a assinatura para ativar o Smart Retries e outros recursos de recuperação de receitas.
  • Se você usa PaymentIntents, colete os novos dados de pagamento e confirme o PaymentIntent.
  • Atualize a forma de pagamento padrão na assinatura.
invoice.upcomingEnviado 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.updatedEnviado 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.createdEnviado quando um PaymentIntent é criado.
payment_intent.succeededEnviado quando um PaymentIntent conclui um pagamento.
subscription_schedule.abortedEnviado quando um cronograma de assinatura é cancelado porque o pagamento inadimplente encerrou a assinatura relacionada.
subscription_schedule.canceledEnviado quando um cronograma de assinatura é cancelado, o que também cancela qualquer assinatura associada ativa.
subscription_schedule.completedEnviado quando todas as fases de um cronograma de assinatura são concluídas.
subscription_schedule.createdEnviado quando um novo cronograma de assinatura é criado.
subscription_schedule.expiringEnviado 7 dias antes da data de vencimento de um cronograma de assinatura.
subscription_schedule.releasedEnviado quando um cronograma de assinatura é lançado ou interrompido e dissociado da assinatura, que permanece.
subscription_schedule.updatedEnviado quando uma programação de assinatura é atualizada.

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 é possível fazer alterações após a finalização da fatura.

  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 repetir pagamentos malsucedidos. O Smart Retries usa o modelo de IA da Stripe para escolher o momento ideal para tentar novamente o pagamento durante um período configurável de até 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:

ConfiguraçãoDescrição
Cancelar a assinaturaA assinatura muda para um estado canceled após o número máximo de dias definido no cronograma de novas tentativas.
Marcar a assinatura como não pagaA assinatura muda para um estado unpaid após o número máximo de dias definido no cronograma de novas tentativas. As faturas continuam sendo geradas e permanecem em um estado de rascunho.
Deixar a assinatura vencidaA assinatura permanece em um estado past_due após o número máximo de dias definido no cronograma de novas tentativas. As faturas continuam sendo geradas e cobram o cliente com base em configurações de novas tentativas.

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:

  • An upcoming renewal reminder at the same time that we send the invoice.upcoming event for subscriptions set up to collect payment automatically.
  • 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.

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:

ConfiguraçãoDescrição
Cancelar a assinaturaA assinatura muda para um estado canceled após o número máximo de dias definido no cronograma de novas tentativas.
Marcar a assinatura como não pagaA assinatura muda para um estado unpaid após o número máximo de dias definido no cronograma de novas tentativas. As faturas continuam sendo geradas e ficam em um estado draft ou passam para um estado especificado nas suas configurações de fatura.
Deixar a assinatura vencidaA assinatura permanece em um estado past_due após o número máximo de dias definido no cronograma de novas tentativas. As faturas continuam sendo geradas em um estado open.

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:

ConfiguraçãoDescrição
Cancelar a assinaturaA assinatura muda para um estado canceled após o número máximo de dias definido no cronograma de novas tentativas.
Marcar a assinatura como não pagaA assinatura muda para um estado unpaid após o número máximo de dias definido no cronograma de novas tentativas. As faturas continuam sendo geradas e permanecem em um estado de rascunho.
Deixar a assinatura vencidaA assinatura permanece em um estado past_due após o número máximo de dias definido no cronograma de novas tentativas. As faturas continuam sendo geradas e cobram o cliente com base em configurações de novas tentativas.

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

Esta página foi útil?
SimNão
Precisa de ajuda? Fale com o suporte.
Participe do nosso programa de acesso antecipado.
Confira nosso changelog.
Dúvidas? Fale com a equipe de vendas.
LLM? Read llms.txt.
Powered by Markdoc
Produtos usados
Billing