Pular para o conteúdo
Criar conta ou Entrar
O logotipo da documentação da Stripe
/
Criar contaLogin
Visão geral
Billing
Visão geralSobre as APIs do Billing
Assinaturas
Tributos
Visão geral
Relatórios
Visão geralRelatórios para várias contas
Dados
Visão geral

Crie uma integração de assinaturas

Crie e gerencie assinaturas para aceitar pagamentos recorrentes.

Página checkout de assinatura
Low-code

Personalize logotipo, imagens e cores.

Use páginas hospedadas pré-construídas para recolher pagamentos e gerenciar suas subscriptions.

Clone um exemplo de integração do GitHub.

Para obter uma versão imersiva deste guia, consulte o início rápido da integração do Faturamento.

Explore the sample on GitHub or the demo.

O que você vai criar

Este guia descreve como vender assinaturas mensais de 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 do cliente 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ível 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 Stripe client de sua escolha:

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

Opcionalmente, instale a CLI da Stripe. A CLI fornece o teste Webhook, e você pode executá-la para criar seus 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

Modelos de planos de preços recorrentes representam os produtos ou serviços que você vende, quanto custam, quais moedas você aceita para pagamentos e o período de serviço para assinaturas. Para montar o modelo de preços, crie produtos (o que você vende) e preços (quanto e com que frequência cobrar pelos seus produtos).

Este exemplo utiliza um plano de preços de taxa fixa com duas opções de nível de serviço diferentes: básico e premium. Para cada opção de nível de serviço, você precisa criar um produto e um preço recorrente. Para adicionar uma cobrança pontual, como uma tarifa de abertura, crie um terceiro produto com um preço pontual.

Cada produto fatura em intervalos mensais. O preço do produto básico é 5 USD. O preço do produto premium é 15 USD. Consulte o guia de plano de preços de taxa fixa para ver um exemplo com três níveis.

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ê oferece vários períodos de cobrança, use o Checkout para fazer upsell aos clientes em períodos de cobrança mais longos e recolher mais receita antecipadamente.

Para outros modelos de preços, consulte Exemplos de faturamento.

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 de 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 backend de sua inscrição, defina um endpoint que crie a sessão para ser chamada pelo frontend. você precisa desses valores:

  • O ID do preço da assinatura ao qual o cliente está se registrando. Seu front-end passa esse valor
  • Seu success_url, que é uma página do seu site para a qual o Checkout retorna o cliente depois que ele conclui o pagamento

Opcionalmente, você pode:

Se você criou um preço único no passo 2, passe também esse ID de preço. Depois de criar uma Checkout Session, redirecione o cliente para URL retornada na resposta.

Você pode ativar um comportamento de assinatura mais preciso e previsível ao criar uma Checkout Session definindo o modo de faturamento type como flexible. Você deve usar a versão da API da Stripe 2025-06-30.basil ou posterior.

Nota

You can use lookup_keys to fetch prices rather than price IDs. For an example, see the sample application.

server.rb
Ruby
Python
PHP
Java
Node.js
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}',
  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 acrescentando o ID da sessão. Saiba mais sobre como personalizar sua página de sucesso.

No Dashboard , ative as formas de pagamento que você deseja aceitar de seus clientes. O Checkout aceita várias formas de pagamento.

Provisionar e monitorar assinaturas
Servidor

Após a assinatura ser bem-sucedida, o cliente retornará ao seu site em success_url, que inicia um checkout.session.completed webhook. Ao receber um evento checkout.session.completed, use entitlements(/billing/entitlements) para provisionar a assinatura. Continue provisionando mensalmente (se a cobrança for mensal) conforme você receber eventos invoice.paid. Se receber um evento invoice.payment_failed, notifique seu cliente e o direcione ao portal do cliente para atualizar sua forma de pagamento.

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

Para fins de teste, você pode monitorar eventos na guia Events do Workbench. Para produção, configure um endpoint Webhook e assine os tipos de eventos apropriados. Se você não souber sua chave STRIPE_WEBHOOK_SECRET, acesse a visualização de detalhes do destino na guia Webhooks do Workbench para visualizá-la.

server.rb
Ruby
Python
PHP
Java
Node.js
Acesse
.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 doesn't 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 conclui com êxito a sessão de Checkout, informando você sobre uma nova compra.
invoice.paidEnviado a cada período de cobrança quando um pagamento for efetivado.
invoice.payment_failedEnviado a cada período de cobrança se houver um problema com a forma de pagamento do seu cliente.

Para obter ainda mais eventos para monitorar, consulte . Webhooks de assinatura.

Configurar o portal de clientes
Dashboard

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

Use o Dashboard para configurar o portal. No mínimo, certifique-se de configurar o portal para que os clientes possam atualizar suas formas de pagamento.

Criar uma sessão no portal
Servidor

Definir um endpoint que crie a sessão do portal do cliente para o seu frontend chamar. O CUSTOMER_ID refere-se ao ID do cliente criado por uma Checkout Session 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 do seu site para a qual o cliente será redirecionado depois que terminar de gerenciar a assinatura:

server.rb
Ruby
Python
PHP
Java
Node.js
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>

Após sair do portal do cliente, o cliente volta ao seu site em return_url. Continue a monitorar eventos para monitorar o status da assinatura do cliente.

Se você configurar o portal do cliente para permitir ações como o cancelamento de uma assinatura, monitore eventos adicionais.

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 da conta 900123456 e BSB 000000. O PaymentIntent confirmado inicialmente passa para o status processing, depois passa para succeeded três minutos depois.
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 da conta 111111113 e BSB 000000.
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.

Monitorar eventos

Configure Webhooks para ouvir os eventos de alteração de assinatura, como upgrades e cancelamentos. você pode visualizar eventos de Webhook de assinatura no Dashboard ou com o Stripe CLI.

Saiba mais sobre testando sua integração de Faturamento.

Veja também