Crie uma integração de assinaturas

Instale o cliente Stripe de sua escolha:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Em seguida, instale a Stripe CLI. A CLI fornece testes de webhooks, e você pode executá-la para fazer chamadas de API para a Stripe. Este guia mostra a você como usar a CLI para configurar um modelo de preços em uma seção posterior.

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

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.

A Stripe exige um Customer para cada assinatura criada. No front-end da aplicação, colete todas as informações necessárias dos usuários e envie ao servidor.

Se for necessário coletar informações de endereço, o Address Element permite que você colete endereço de entrega ou de cobrança dos seus clientes. Para mais detalhes sobre esse componente, veja a página do Address Element.

<form id="signup-form">
  <label>
    Email
    <input id="email" type="email" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>

const emailInput = document.querySelector('#email');

fetch('/create-customer', {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: emailInput.value,
  }),
}).then(r => r.json());

No servidor, crie o objeto Customer da Stripe.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}} \
  -d "shipping[address][city]"=Brothers \
  -d "shipping[address][country]"=US \
  -d "shipping[address][line1]"="27 Fredrick Ave" \
  -d "shipping[address][postal_code]"=97712 \
  -d "shipping[address][state]"=CA \
  -d "shipping[name]"={{CUSTOMER_NAME}} \
  -d "address[city]"=Brothers \
  -d "address[country]"=US \
  -d "address[line1]"="27 Fredrick Ave" \
  -d "address[postal_code]"=97712 \
  -d "address[state]"=CA

Permita que o cliente escolha um plano e, em seguida, crie a assinatura. No exemplo deste guia, o cliente escolhe entre o plano Básico e o plano Premium.

No front-end, passe o ID do preço selecionado e o ID do registro do cliente para o back-end.

fetch('/create-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    priceId: priceId,
    customerId: customerId,
  }),
})

No back end, crie a assinatura com um status incomplete usando payment_behavior=default_incomplete. Em seguida, retorne o client_secret do primeiro PaymentIntent da assinatura para o front end para concluir o pagamento. Para fazer isso, expanda o confirmation_secret na última fatura da assinatura.

Para ativar o comportamento aprimorado de assinatura , defina billing_mode[type] como flexível. você deve usar a versão da API do Stripe 2025-06-30.basil ou posterior.

Defina save_default_payment_method para on_subscription para salvar a forma de pagamento como padrão para uma assinatura quando o pagamento for bem-sucedido. Salvar um método de pagamento padrão aumenta a taxa de sucesso de futuros pagamentos de assinatura.

# 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 '/create-subscription' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)
  customer_id = cookies[:customer]
  price_id = data['priceId']

  # Create the subscription. Note we're expanding the Subscription's
  # latest invoice and that invoice's confirmation_secret
  # so we can pass it to the front end to confirm the payment
  subscription = Stripe::Subscription.create(
    customer: customer_id,
    items: [{
      price: price_id,
    }],
    payment_behavior: 'default_incomplete',
    payment_settings: {save_default_payment_method: 'on_subscription'},
    billing_mode: {type: 'flexible'},
    expand: ['latest_invoice.confirmation_secret']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret }.to_json
end

A assinatura agora está inativa e está aguardando pagamento. O exemplo de resposta abaixo destaca os campos mínimos a serem armazenados, mas você pode armazenar os campos que a sua inscrição acessa com frequência.

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,
    "enabled": false,
    "liability": "null"
  },
  "billing_cycle_anchor": 1623873347,

Use o Stripe Elements para recolher os detalhes do pagamento e ativar a assinatura. você pode personalizar o Elements para que corresponda à aparência de sua inscrição.

O Payment Element aceita Link, cartões de crédito, débito automático SEPA e débito automático BECS para assinaturas. você pode exibir as formas de pagamento habilitadas e recolher com segurança os detalhes do pagamento com base na seleção do cliente.

Configurar o Stripe Elements

O Payment Element está automaticamente disponível como um recurso do Stripe.js. Inclua o script Stripe.js em sua página de pagamento adicionando-o ao head do arquivo HTML. Sempre carregue o Stripe.js diretamente de js.stripe.com para manter a conformidade com PCI. Não inclua o script em um pacote nem hospede pessoalmente uma cópia dele.

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>
<body>
  <!-- content here -->
</body>

Crie uma instância da Stripe com o seguinte JavaScript na página de pagamentos:

// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

Adicione o Payment Element à sua página

O Payment Element precisa de um lugar para residir na sua página de pagamentos. Crie um node DOM vazio (contêiner) com um ID único no seu formulário de pagamento.

<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Subscribe</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Depois que o formulário for carregado, crie uma instância do Payment Element e monte-o no nódulo DOM do contêiner. Quando criou a assinatura, você passou o valor client_secret para o front end. Passe esse valor como uma opção quando você criar uma instância de Elements.

const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in the payment form, passing the client secret obtained in step 5
const elements = stripe.elements(options);

const paymentElementOptions = {
  layout: "tabs",
};

// Create and mount the Payment Element
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

O Payment Element renderiza um formulário dinâmico que permite que o cliente selecione uma forma de pagamento. O formulário recolhe automaticamente todos os detalhes de pagamento necessários para a forma de pagamento selecionada.

Configurações opcionais do Payment Element

Como opção, você pode fazer o seguinte:

• Customize o Payment Element para que corresponda ao design de seu site, passando o objeto de aparência para as opções ao criar uma instância de Elements.
• Configure a interface do Apple Pay para retornar um token de comerciante para aceitar pagamentos recorrentes, recarga automática e diferidos.

Finalizar pagamento

Use stripe.confirmPayment para concluir o pagamento usando os detalhes do Stripe Elements e ativar a assinatura. Isso cria um PaymentMethod, confirma o primeiro PaymentIntent da assinatura incompleta e faz uma cobrança. Se Strong Customer Authentication (SCA) for necessária para o pagamento, o Payment Element tratará o processo de autenticação antes de confirmar o PaymentIntent.

Forneça um return_url para indicar para onde o Stripe redireciona o usuário depois que ele conclui o pagamento. O usuário pode ser redirecionado primeiro para um site intermediário, como uma página de autorização bancária, antes de ser redirecionado para o return_url. Os pagamentos com cartão redirecionam imediatamente para o return_url quando o pagamento é bem-sucedido.

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: "https://example.com/order/123/complete",
    }
  });

  if (error) {
    // This point is reached only if there's an immediate error when
    // confirming the payment. Show an error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer redirects to your `return_url`. For some payment
    // methods, such as iDEAL, your customer redirects to an intermediate
    // site first to authorize the payment, and then redirects to the `return_url`.
  }
});

Quando o cliente envia um pagamento, a Stripe o redireciona para o return_url e inclui os parâmetros de consulta de URL a seguir. A página de retorno pode usá-los para obter o status do PaymentIntent e exibir o status do pagamento para o cliente.

Ao especificar o return_url, você também pode anexar seus próprios parâmetros de consulta para uso na página de retorno.

Quando o cliente é redirecionado para o seu site, você pode usar o payment_intent_client_secret para consultar o PaymentIntent e exibir o status da transação ao cliente.

Use um dos parâmetros da consulta para recuperar o PaymentIntent. Inspecione o status do PaymentIntent para decidir o que mostrar aos seus clientes. você também pode anexar seus próprios parâmetros de consulta ao fornecer o return_url, que persiste durante o processo de redirecionamento.

// Initialize Stripe.js using your publishable key
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods [immediately succeed or fail][0] upon
  // confirmation, while others first enter a `processing` status.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

Para concluir a integração, você precisa processar os webhooks enviados pela Stripe. Esses eventos são acionados sempre que o status na Stripe muda, como assinaturas que criam novas faturas. No seu aplicativo, configure um manipulador HTTP para aceitar uma solicitação POST contendo o evento webhook e verifique a assinatura do evento:

# 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
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events, see https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

Durante o desenvolvimento, use a CLI da Stripe para observar Webhooks e encaminhá-los para sua inscrição. Execute o seguinte em um novo terminal enquanto seu aplicativo de desenvolvimento estiver em execução:

stripe listen --forward-to localhost:4242/webhook

Para produção, configure um endpoint de Webhook no Workbench, ou use o Webhook Endpoints API.

Ouça alguns eventos para concluir as etapas restantes deste guia. Consulte Eventos de assinatura para obter mais detalhes sobre Webhooks específicos de assinatura.

Agora que a assinatura está ativa, dê ao usuário acesso ao seu serviço. Para fazer isso, ouça os eventos customer.subscription.created, customer.subscription.updated e customer.subscription.deleted. Esses eventos passam um objeto Subscriptions que contém um campo status indicando se a assinatura está ativa, vencida ou cancelada. Consulte o ciclo de vida da assinatura para obter uma lista completa de status.

No seu gerenciador de webhooks:

1. Verifique o status da assinatura. Se estiver ativa, o usuário pagou pelo seu produto.
2. Confira o produto que o cliente assinou e conceda acesso ao serviço. Verificar o produto em vez do preço proporciona mais flexibilidade, caso seja necessário alterar os preços ou o período de faturamento.
3. Armazene o product.id, subscription.id e subscription.status no seu banco de dados junto com o customer.id que já salvou. Verifique esse registro quando determinar quais recursos precisam ser ativados para o usuário no seu aplicativo.

O status de uma assinatura pode mudar a qualquer momento durante sua existência, mesmo que seu aplicativo não faça chamadas diretas para a Stripe. Por exemplo, uma renovação pode falhar devido a um cartão de crédito expirado, o que coloca a assinatura em um status de vencida. Ou, se você implementar o portal do cliente, um usuário pode cancelar a assinatura sem acessar diretamente seu aplicativo. A implementação correta do manipulador mantém o status do seu aplicativo sincronizado com a Stripe.

Você pode permitir que os clientes cancelem suas assinaturas. O exemplo abaixo adiciona uma opção de cancelamento à página de configurações da conta.

Configurações da conta com a capacidade de cancelar a assinatura

function cancelSubscription(subscriptionId) {
  return fetch('/cancel-subscription', {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(cancelSubscriptionResponse => {
      // Display to the user that the subscription has been canceled.
    });
}

No back-end, configure um endpoint para ser chamado pelo front-end.

# 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 '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

Seu aplicativo recebe um evento customer.subscription.deleted.

Após o cancelamento da assinatura, remova do banco de dados o ID de assinatura da Stripe que você armazenou anteriormente e limite o acesso ao seu serviço.

Depois de serem canceladas, as assinaturas não podem ser reativadas. Obtenha dados de faturamento atualizados do seu cliente, atualize a forma de pagamento padrão e crie uma nova assinatura com o registro de cliente existente.

Testar formas de pagamento

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

Monitorar eventos

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

Para obter mais detalhes, consulte testando sua integração com o Billing.