# Como funcionam as assinaturas Gerencie pagamentos recorrentes e ciclos de vida de assinaturas. Subscriptions permitem que os clientes façam pagamentos recorrentes para ter acesso a um produto. Diferente das compras pontuais, as assinaturas exigem que você armazene informações adicionais do cliente para cobranças futuras. A Stripe oferece diversos recursos que ajudam você a gerenciar o faturamento das assinaturas. - [Suporte para diferentes modelos de planos de preços](https://docs.stripe.com/products-prices/pricing-models.md) - [Gerenciamento de descontos de assinatura](https://docs.stripe.com/billing/subscriptions/coupons.md) - [Gerenciamento de avaliações](https://docs.stripe.com/billing/subscriptions/trials.md) - [Pro rata para assinaturas modificadas](https://docs.stripe.com/billing/subscriptions/prorations.md) - [Gerenciamento de autoatendimento do cliente](https://docs.stripe.com/customer-management.md) - [Invoicing para recolher pagamentos](https://docs.stripe.com/billing/invoices/subscription.md) - [Recuperação de receitas automatizada](https://docs.stripe.com/billing/revenue-recovery.md) - [Relatórios e análises](https://docs.stripe.com/billing/subscriptions/analytics.md) ## O ciclo de vida da assinatura As seções a seguir descrevem o ciclo de vida recomendado da assinatura na Stripe. ### Criar a assinatura Você pode criar uma nova assinatura no [Dashboard](https://dashboard.stripe.com/subscriptions?status=active) ou com a [API](https://docs.stripe.com/api/subscriptions/create.md). Toda vez que você cria uma assinatura, um [evento](https://docs.stripe.com/billing/subscriptions/webhooks.md#events) é acionado. Ouça esses eventos com os [endpoints do Webhook](https://docs.stripe.com/billing/subscriptions/webhooks.md) e certifique-se de que sua integração os trate adequadamente. Opcionalmente, crie um período de [teste](https://docs.stripe.com/billing/subscriptions/trials.md) que não exija pagamento pela assinatura. Neste caso, o`status` é`testando`. Quando o teste termina, a assinatura passa para`ativo` e a Stripe cobra o cliente inscrito. #### Comportamento do pagamento Defina o `payment_behavior` de uma assinatura como [default_incomplete](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior) para ajudar a lidar com pagamentos com falha e fluxos de pagamento complexos, como o 3DS. Isso criará assinaturas com status `incompleto` se o pagamento for necessário, o que permite que você recolha e confirme as informações de pagamento para ativar a assinatura mais tarde. Quando você define `payment_behavior` para: - `allow_incomplete`: A Stripe imediatamente tenta recolher pagamento na fatura. Se o pagamento falhar, o status da assinatura muda para`incompleto`. - `error_if_incomplete`: Se o pagamento falhar, a criação da assinatura falha completamente. Subscriptions que você cria no Dashboard adotam o comportamento de pagamento apropriado, dependendo da forma de pagamento. ### Tratar a fatura Ao criar uma assinatura, a Stripe cria automaticamente uma [fatura](https://docs.stripe.com/billing/invoices/subscription.md) com o status `aberta`. Seu cliente tem cerca de 23 horas para efetuar um pagamento. Nesse período, o status da assinatura permanece `incompleta` e o status da fatura permanece como `aberta`. Esse intervalo de 23 horas existe porque o primeiro pagamento de uma assinatura geralmente é feito com o cliente *on-session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method). Se o cliente retornar ao aplicativo após 23 horas, crie outra 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](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-statuses) e [Status de pagamento](https://docs.stripe.com/billing/subscriptions/overview.md#payment-status). ### Provisionar acesso ao seu produto Ao criar uma assinatura para um cliente, você cria um [direito](https://docs.stripe.com/billing/entitlements.md) 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](https://docs.stripe.com/billing/subscriptions/webhooks.md#active-subscriptions) com eventos de webhook e provisionar o produto para o cliente com base nessa atividade. ### Atualizar a assinatura Você pode [modificar as assinaturas existentes](https://docs.stripe.com/billing/subscriptions/change.md) 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](https://docs.stripe.com/billing/subscriptions/change-price.md) do preço da assinatura ou [pausa na cobrança do pagamento](https://docs.stripe.com/billing/subscriptions/pause-payment.md) de uma assinatura ativa. Você pode monitorar os [eventos da assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md#events) com [endpoints de Webhook](https://docs.stripe.com/billing/subscriptions/webhooks.md) para saber se houve alterações na assinatura. Por exemplo, você poderá enviar um e-mail a um cliente se um pagamento falhar ou revogar o acesso de um cliente quando ele cancelar a assinatura. Em integrações do [Stripe Checkout](https://docs.stripe.com/payments/checkout.md), 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](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) para fazer a atualização após a conclusão da sessão. Você também poderá [expirar a sessão](https://docs.stripe.com/api/checkout/sessions/expire.md) se desejar cancelar a assinatura da sessão, anular a fatura da assinatura ou marcar a fatura como incobrável. ### Atualizar a primeira fatura Você poderá atualizar a primeira fatura de uma assinatura se [collection_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method) for `send_invoice`. Após a criação da fatura, você tem uma hora para fazer atualizações em valores, itens, descrição, metadados e assim por diante. Não será possível atualizar a fatura depois que ela for finalizada e enviada ao cliente para pagamento. A primeira fatura de uma assinatura com o`collection_method` definido como `charge_automatically` é finalizado e cobrado imediatamente. Você não pode atualizar a primeira fatura antes de finalizá-la, mas pode atualizar as faturas subsequentes para renovações de assinatura. Você também não pode atualizar a primeira fatura para agendamentos de assinatura. A primeira fatura está sempre aberta, independentemente do método de cobrança. ### 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: 1. Colete novos dados de pagamento, se necessário. 1. Habilite a cobrança automática definindo o [auto_advance](https://docs.stripe.com/api/invoices/update.md#update_invoice-auto_advance) como `true` em faturas provisórias. 1. [Finalize](https://docs.stripe.com/api/invoices/finalize.md) 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](https://dashboard.stripe.com/settings/billing/automatic) no Dashboard. ### Cancelar a assinatura Você pode [cancelar](https://docs.stripe.com/billing/subscriptions/cancel.md) uma assinatura a qualquer momento, inclusive no [final de um ciclo de faturamento](https://docs.stripe.com/billing/subscriptions/cancel.md#cancel-at-the-end-of-the-current-billing-period) ou após um [número definido de ciclos de faturamento](https://docs.stripe.com/billing/subscriptions/cancel.md#subscription-schedules). Por padrão, cancelar uma assinatura desabilita a criação de novas faturas e [interrompe a cobrança automática](https://docs.stripe.com/billing/subscriptions/cancel.md#handle-invoice-items-when-canceling-subscriptions) de todas as faturas pendentes da assinatura. Também exclui a assinatura e você não poderá mais atualizá-la ou seus [metadados](https://docs.stripe.com/metadata.md). 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á em bom estado. Para assinaturas`past_due`, pagar a fatura associada mais recente ou marcá-la como não coletável muda as assinatura para `ativo`. Note que`ativo` não indica que todas as faturas pendentes associadas a assinatura foram pagas. Você pode deixar outras faturas pendentes abertas para pagamento, marcá-las como não cobráveis ou anulá-las conforme achar melhor. | | `incomplete` | O cliente precisa fazer um pagamento em até 23 horas para ativar a assinatura. Ou o pagamento [demanda atenção](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action), 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](https://dashboard.stripe.com/settings/billing/automatic) 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](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) 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 assinatura encerrou o período de teste sem uma forma de pagamento padrão e [trial_settings.end_behavior.missing_payment_method](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment) está definido como `suspenso`. As faturas não são mais criadas para a assinatura. Após adicionar uma forma de pagamento padrão ao cliente, você pode [retomar a assinatura](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#resume-a-paused-subscription). | ## Status de pagamento Um [PaymentIntent](https://docs.stripe.com/payments/payment-intents.md) rastreia o ciclo de vida de cada pagamento. Sempre que o pagamento de uma assinatura vence, a Stripe gera uma [fatura](https://docs.stripe.com/billing/invoices/subscription.md) 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` | Formas de pagamento assíncronas, como o ACH Direct Debit, tratam as transições de status de assinatura de forma diferente dos métodos de pagamento imediatos. Quando você usa um método de pagamento assíncrono, uma assinatura pode passar diretamente para o status `ativa` após a criação e ignorar o status `incompleta`. Se o pagamento falhar mais tarde, a Stripe anula a fatura, mas a assinatura permanece `ativa`. Considere esse comportamento ao definir seu controle de acesso e sua lógica de novas tentativas. 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](https://docs.stripe.com/payments/payment-methods/integration-options.md) 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](https://docs.stripe.com/billing/subscriptions/overview.md#provision-access) ao produto. ### Exige forma de pagamento Se o pagamento falhar devido a um [ erro do cartão](https://docs.stripe.com/api/errors.md#errors-card_error), como um [pagamento recusado](https://docs.stripe.com/declines.md#issuer-declines): - 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](https://docs.stripe.com/api/payment_intents/confirm.md). - Atualize a [forma de pagamento padrão](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) na assinatura. - A Stripe tenta o pagamento novamente usando o [Smart Retries](https://docs.stripe.com/invoicing/automatic-collection.md#smart-retries) ou com base nas suas [regras de nova tentativa](https://dashboard.stripe.com/account/billing/automatic) personalizadas. - Use o evento [invoice.payment_failed](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md#invoice-payment-failed-webhook) 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](https://docs.stripe.com/api.md#invoice_object-next_payment_attempt) é definido usando as configurações de assinatura atuais no Dashboard. Saiba como [gerenciar falhas de pagamento de assinaturas](https://docs.stripe.com/billing/subscriptions/webhooks.md#payment-failures). ### Exige ação Algumas formas de pagamento exigem a autenticação do cliente com o [3D Secure](https://docs.stripe.com/payments/3d-secure.md) (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](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#three-ds-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`. Para gerenciar esses cenários: - Monitore a notificação de evento `invoice.payment_action_required` com [endpoints de webhook](https://docs.stripe.com/billing/subscriptions/webhooks.md). Isso indica que a autenticação é necessária. - Avise o cliente de que a autenticação é necessária. - Recupere o segredo do cliente para o PaymentIntent e passe-o em uma chamada para [stripe.ConfirmCardPayment](https://docs.stripe.com/js/payment_intents/confirm_card_payment). Isso exibe um modal de autenticação para seus clientes, faz a tentativa de pagamento, fecha o modal e devolve o contexto para sua inscrição. - 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. ## See also - [Criar uma integração de assinaturas](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) - [Subscriptions quickstart](https://docs.stripe.com/billing/quickstart.md) - [Exemplo de assinatura com preço fixo](https://github.com/stripe-samples/subscription-use-cases/tree/main/fixed-price-subscriptions)