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

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ê 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:

  • Use cancel_url para fornecer uma página no seu site para onde o Checkout envia seu cliente se ele cancelar o processo de pagamento.
  • Configure uma âncora de ciclo de faturamento para sua assinatura nessa chamada.
  • Use um texto personalizado para incluir os termos da sua assinatura e cancelamento, além de um link para que seus clientes possam atualizar ou cancelar a assinatura. Recomendamos configurar lembretes e notificações por e-mail para seus assinantes.

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.

Observação

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}',
  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 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

Esta página foi útil?
SimNão