Pular para o conteúdo
Criar conta
 ou
Entrar
O logotipo da documentação da Stripe
/
Criar conta
Login

Crie uma integração de assinaturas

Crie e gerencie assinaturas para aceitar pagamentos recorrentes.

Página de assinatura do Checkout
Low-code

Personalize logotipo, imagens e cores.

Use formulários hospedados criados previamente para coletar pagamentos e gerenciar assinaturas.

Clone uma amostra de integração do GitHub.

Para ver uma versão detalhada deste guia, consulte o Início rápido da integração do Billing.

Explore o exemplo no GitHub ou a demonstração.

O que você pode criar

Este guia descreve como vender assinaturas mensais com preço fixo usando o Stripe Checkout.

Este guia ensina a:

  • Modelar seus negócios criando um catálogo de produtos
  • Adicionar uma sessão do Checkout ao seu site, com um botão e páginas de confirmação e cancelamento
  • Monitorar os eventos de assinatura e dar acesso ao seu serviço
  • Configurar o portal do cliente
  • Adicionar uma sessão do portal de clientes ao seu site, com botão e redirecionamento
  • Permitir que os clientes gerenciem a assinatura no portal
  • Saiba como usar o modo de faturamento flexíve para acessar o comportamento de faturamento aprimorado e recursos adicionais.

Após a conclusão da integração, você pode ampliá-la para:

Configurar a Stripe

Instale o cliente Stripe de sua escolha:

Command Line
Ruby
Python
PHP
Java
Node
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Instale a Stripe CLI (opcional). A CLI fornece testes de webhook que você pode executar para criar produtos e preços.

Command Line
homebrew
Instalar da fonte
No results
# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

Para obter opções de instalação adicionais, consulte Comece a usar o Stripe CLI.

Criar o modelo de preços
Dashboard ou Stripe CLI

Crie seus produtos e preços usando o Dashboard ou a Stripe CLI.

Este exemplo usa um serviço de preço fixo com duas opções diferentes de nível de serviço: Básico e Premium. Para cada opção de nível de serviço, você precisa criar um produto e um preço recorrente. (Se quiser adicionar uma cobrança avulsa para um item como tarifa de configuração, crie um terceiro produto com um preço avulso. Para simplificar, este exemplo não inclui uma cobrança avulsa.)

Neste exemplo, o faturamento de cada produto é mensal. O produto básico custa 5 USD e o produto Premium custa 15 USD.

Acesse a página Adicionar um produto e crie dois produtos. Adicione um preço para cada produto, cada um com um período de faturamento mensal recorrente:

  • Produto premium: serviço premium com recursos extras

    • Preço: Tarifa fixa | 15 USD

  • Produto básico: serviço básico com recursos mínimos

    • Preço: Tarifa fixa | 5 USD

Depois de criar os preços, registre o ID deles para utilizá-los em outras etapas. Os IDs de preço têm esta estrutura: price_G0FvDp6vZvdwRZ.

Quando tudo estiver pronto, use o botão Copiar para modo de produção, no canto superior direito, para clonar seu produto de uma área restrita para o modo de produção.

Se você oferecer vários intervalos de cobrança, use o Checkout para fazer upsell aos clientes em intervalos de cobrança maiores e coletar mais receitas antecipadamente.

Para outros modelos de preços, consulte os exemplos de cobrança.

Criar uma sessão do Checkout
Cliente e servidor

Adicione um botão de checkout ao seu site para chamar um endpoint do lado do servidor e criar uma sessão do Checkout.

index.html
Visualizar exemplo completo
<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <!-- Note: If using PHP set the action to /create-checkout-session.php -->

      <input type="hidden" name="priceId" value="price_G0FvDp6vZvdwRZ" />
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

No back-end do seu aplicativo, defina um endpoint que cria a sessão para a chamada do seu front-end. Você precisa destes valores:

  • O ID do preço da assinatura ao qual o cliente está se registrando. Seu front-end passa esse valor
  • O success_url, uma página do seu site que o Checkout envia ao cliente quando ele finaliza o pagamento

Como opção, você pode informar cancel_url, uma página no seu site para a qual o Checkout encaminha o cliente se ele cancelar o processo de pagamento. Também é possível configurar uma âncora de ciclo de cobrança para sua assinatura nesta chamada.

Se tiver criado um preço avulso na etapa 2, passe também esse ID de preço. Depois de criar uma Sessão do Checkout, redirecione o cliente ao URL retornado na resposta.

Você pode ativar um modo de cobrança mais estável e previsível ao criar a sessão de checkout, definindo billing_mode[type] como flexible. Para isso, é obrigatório utilizar a versão da API do Stripe 2025-06-30.basil ou superior.

Observação

Você pode usar lookup_keys para obter preços em vez de IDs de preço. Veja o exemplo de aplicativo para ver um exemplo.

server.rb
Ruby
Python
PHP
Java
Node
Go
.NET
No results
Visualizar exemplo completo
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


# The price ID passed from the front end.
#   price_id = params['priceId']
price_id = '{{PRICE_ID}}'

session = Stripe::Checkout::Session.create({
  success_url: 'https://example.com/success.html?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://example.com/canceled.html',
  mode: 'subscription',
  line_items: [{
    # For usage-based billing, don't pass quantity
    quantity: 1,
    price: price_id,
  }],
  subscription_data: {
    billing_mode: { type: 'flexible' }
  }
})

# Redirect to the URL returned on the session
#   redirect session.url, 303

Este exemplo personaliza o success_url vinculando o ID da sessão. Para obter mais informações sobre essa abordagem, consulte a documentação para saber como personalizar a página de confirmação.

Na Dashboard, ative as formas de pagamento que deseja aceitar de seus clientes. O checkout aceita várias formas de pagamento.

Provisionar e monitorar assinaturas
Servidor

Depois que a assinatura for cadastrada, o cliente retornará ao seu site no success_url, que inicia um webhook checkout.session.completed. Ao receber um evento checkout.session.completed, você pode fornecer a assinatura. Continue fornecendo mensalmente (se a cobrança for mensal) à medida que recebe eventos invoice.paid. Se você receber um evento invoice.payment_failed, notifique seu cliente e encaminhe-o ao portal do cliente para atualizar a forma de pagamento.

Para determinar a próxima etapa da lógica do sistema, verifique o tipo de evento e analise a carga de cada objeto de evento, como invoice.paid. Armazene os objetos de evento subscription.id e customer.id no banco de dados para verificação.

Para fins de teste, você pode monitorar eventos na guia Eventos do Workbench. Para produção, configure um endpoint de webhook e inscreva-se nos tipos de eventos apropriados. Se você não souber sua chave STRIPE_WEBHOOK_SECRET, navegue até a visualização de detalhes de destino da aba Webhooks no Workbench para visualizá-la.

server.rb
Ruby
Python
PHP
Java
Node
Go
.NET
No results
Visualizar exemplo completo
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


post '/webhook' do
  webhook_secret = 
'{{STRIPE_WEBHOOK_SECRET}}'

  payload = request.body.read
  if !webhook_secret.empty?
    # Retrieve the event by verifying the signature using the raw body and secret if webhook signing is configured.
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    event = nil

    begin
      event = Stripe::Webhook.construct_event(
        payload, sig_header, webhook_secret
      )
    rescue JSON::ParserError => e
      # Invalid payload
      status 400
      return
    rescue Stripe::SignatureVerificationError => e
      # Invalid signature
      puts '⚠️  Webhook signature verification failed.'
      status 400
      return
    end
  else
    data = JSON.parse(payload, symbolize_names: true)
    event = Stripe::Event.construct_from(data)
  end
  # Get the type of webhook event sent
  event_type = event['type']
  data = event['data']
  data_object = data['object']

  case event_type
  when 'checkout.session.completed'
    # Payment is successful and the subscription is created.
    # You should provision the subscription and save the customer ID to your database.
  when 'invoice.paid'
    # Continue to provision the subscription as payments continue to be made.
    # Store the status in your database and check when a user accesses your service.
    # This approach helps you avoid hitting rate limits.
  when 'invoice.payment_failed'
    # The payment failed or the customer does not have a valid payment method.
    # The subscription becomes past_due. Notify your customer and send them to the
    # customer portal to update their payment information.
  else
    puts "Unhandled event type: \#{event.type}"
  end

  status 200
end

Mínimo de tipos de evento a serem monitorados:

Nome do eventoDescrição
checkout.session.completedEnviado quando um cliente finaliza a sessão do Checkout, informando sobre uma nova compra.
invoice.paidEnviado a cada intervalo de faturamento quando um pagamento for efetivado.
invoice.payment_failedEnviado a cada intervalo de faturamento se houver um problema com a forma de pagamento do seu cliente.

Para monitorar ainda mais eventos, consulte Webhooks de assinatura.

Configurar o portal de clientes
Dashboard

O portal do cliente permite que os clientes gerenciem diretamente suas assinaturas e faturas existentes.

Use o Dashboard para configurar o portal. No mínimo, configure-o para que os clientes possam atualizar as formas de pagamento. Consulte Integrar o portal do cliente para obter informações sobre outras configurações que podem ser realizadas.

Criar uma sessão no portal
Servidor

Defina um endpoint que cria a sessão do portal do cliente para seu frontend chamar. Aqui, CUSTOMER_ID refere-se ao ID do cliente criado por uma sessão de checkout que você salvou ao processar o evento checkout.session.completed. Você também pode definir um link de redirecionamento padrão para o portal no Dashboard.

Passe um valor opcional return_url para a página no seu site para redirecionar o cliente após ele terminar de gerenciar a assinatura:

server.rb
Ruby
Python
PHP
Java
Node
Go
.NET
No results
Visualizar exemplo completo
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


# This is the URL that users are redirected to after they're done
# managing their billing.
return_url = 
'{{DOMAIN_URL}}'

customer_id = 
'{{CUSTOMER_ID}}'


session = Stripe::BillingPortal::Session.create({
  customer: customer_id,
  return_url: return_url,
})

# Redirect to the URL for the session
#   redirect session.url, 303

Enviar clientes ao portal de clientes
Cliente

No seu front-end, adicione um botão à página success_url que fornece um link para o portal de clientes:

success.html
Visualizar exemplo completo
<html>
  <head>
    <title>Manage Billing</title>
  </head>
  <body>
    <form action="/customer-portal" method="POST">
      <!-- Note: If using PHP set the action to /customer-portal.php -->
      <button type="submit">Manage Billing</button>
    </form>
  </body>
</html>

Depois de sair do portal do cliente, o cliente retorna ao seu site no return_url. Continue a monitorar eventos para acompanhar o estado da assinatura do cliente.

Se você configurar o portal do cliente para permitir ações como o cancelamento de uma assinatura, veja como outros eventos podem ser monitorados em Integrar o portal do cliente.

Teste a integração

Testar formas de pagamento

Use a tabela a seguir para testar diferentes formas de pagamento e cenários.

Forma de pagamentoCenárioComo testar
Débito automático BECSO cliente paga com débito automático BECS.Preencha o formulário usando o número de conta 900123456 e BSB 000-000. Inicialmente, o status do PaymentIntent muda para processing e, três minutos depois, para succeeded.
Débito automático BECSO pagamento do cliente falha com um código de erro account_closed.Preencha o formulário usando o número de conta 111111113 e BSB 000-000.
Cartão de créditoO pagamento com cartão é bem-sucedido e não precisa de autenticação.Preencha o formulário do cartão de crédito usando o número de cartão de crédito 4242 4242 4242 4242 com qualquer validade, CVC e código postal.
Cartão de créditoO pagamento com cartão precisa de autenticação.Preencha o formulário do cartão de crédito usando o número 4000 0025 0000 3155 com qualquer validade, CVC e código postal.
Cartão de créditoO cartão é recusado com um código de recusa como insufficient_funds.Preencha o formulário do cartão de crédito usando o número 4000 0000 0000 9995 com qualquer validade, CVC e código postal.
Débito automático SEPAO cliente paga com débito automático SEPA.Preencha o formulário usando o número de conta AT321904300235473204. Inicialmente, o status do PaymentIntent muda para processing e, três minutos depois, para succeeded.
Débito automático SEPAO status do PaymentIntent do cliente muda de processing para requires_payment_method.Preencha o formulário usando o número de conta AT861904300235473202.

Monitoramento de eventos

Configure webhooks para ouvir eventos de alteração de assinatura, como atualizações e cancelamentos. Saiba mais sobre webhooks de assinatura. É possível visualizar eventos no Dashboard ou com a Stripe CLI.

Para obter mais detalhes sobre como testar sua integração com o Billing, leia o guia.

Veja também

Esta página foi útil?
SimNão