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 precisa de um Customer para cada assinatura. No front-end do seu aplicativo, colete todas as informações necessárias dos seus usuários e passe-as ao back-end.

Se você precisar coletar detalhes de endereço, o Address Element permite coletar um endereço de entrega ou cobrança para seus clientes. Para obter mais informações sobre o Address Element, visite a página 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 seu novo cliente escolha um plano e crie a assinatura. Neste guia, ele escolhe Básico ou Premium.

No front-end, passe o ID do preço selecionado e o ID do registro do cliente ao 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 status incomplete usando payment_behavior=default_incomplete. Em seguida, retorne o client_secret do primeiro Payment Intent da assinatura ao front-end para concluir o pagamento, expandindo o confirmation_secret na última fatura da assinatura.

Defina save_default_payment_method como on_subscription para salvar a forma de pagamento como o padrão para uma assinatura quando um pagamento for bem-sucedido. Salvar uma forma 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'},
    expand: ['latest_invoice.confirmation_secret']
  )

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

Neste ponto, a assinatura fica inactive e aguardando pagamento. Aqui está um exemplo de resposta. Os campos mínimos para armazenar são destacados, mas armazene qualquer coisa que o aplicativo acessar 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 coletar detalhes de pagamento e ativar a assinatura. Você pode personalizar o Elements para corresponder à aparência do seu aplicativo.

O Payment Element aceita Link, cartões de crédito, débito automático SEPA e débito automático BECS para pagamento de assinaturas. Ele exibe as formas de pagamento habilitadas e coleta com segurança os dados de pagamento de acordo com a 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 checkout adicionando-o ao head do arquivo HTML. Sempre carregue 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/basil/stripe.js"></script>
</head>
<body>
  <!-- content here -->
</body>

Crie uma instância da Stripe com o seguinte JavaScript em sua página de checkout:

// 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 Element Pagamento à sua página

O Element Pagamento precisa de um local para residir na sua página de pagamentos. Crie um nó DOM vazio (contêiner) com um ID único no seu formulário de pagamentos.

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

Quando o formulário acima tiver sido carregado, crie uma instância do Element Pagamento e monte-o no nó DOM do contêiner. Na etapa criar uma assinatura, você passou o valor client_secret para o front-end. Passe esse valor como opção ao criar uma instância do Elements.

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

// Set up Stripe.js and Elements to use in checkout 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 ao cliente selecionar uma forma de pagamento. O formulário coleta automaticamente todos os dados de pagamento necessários para a forma de pagamento selecionada.

Configurações opcionais do Payment Element

• Personalize o Payment Element para corresponder ao design do seu site, passando o objeto appearance para options ao criar uma instância do Elements.
• Configure a interface do Apple Pay para retornar um token de comerciante para aceitar pagamentos recorrentes, com recarga automática e diferidos.

Finalizar pagamento

Use stripe.confirmPayment para concluir o pagamento usando os detalhes do Element Pagamento e ative a assinatura. Isso cria um PaymentMethod e confirma o primeiro PaymentIntent incompleto da Assinatura, resultando em uma cobrança. Se for exigido o uso de Autenticação Forte do Cliente (SCA) para o pagamento, o Element Pagamento gerencia o processo de autenticação antes de confirmar o PaymentIntent.

Forneça um return_url a essa função para indicar para onde a Stripe redireciona o usuário após a conclusão do pagamento. Seu 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 são redirecionados imediatamente para o return_url quando um pagamento é finalizado.

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 will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected 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 de consulta para recuperar o PaymentIntent. Inspecione o status do PaymentIntent para decidir o que mostrar aos 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 will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [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, é preciso processar os webhooks enviados pela Stripe. Os webhooks são eventos acionados sempre que o estado dentro da Stripe for alterado, como assinaturas criando novas faturas. No seu aplicativo, configure um gerenciador de HTTP para aceitar uma solicitação POST contendo o evento de 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 check out https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

Durante o desenvolvimento, use o Stripe CLI para observar webhooks e encaminhá-los ao seu aplicativo. Execute o seguinte em um novo terminal enquanto seu aplicativo de desenvolvimento está sendo executado:

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

Para produção, configure um URL de endpoint de webhook no Dashboard ou use a API Webhook Endpoints.

Você escutará alguns eventos para concluir as etapas restantes neste guia. Consulte Eventos de assinatura para obter mais detalhes sobre webhooks específicos de assinaturas.

Agora que a assinatura está ativa, forneça ao usuário o acesso ao seu serviço. Para fazer isso, escute os eventos customer.subscription.created, customer.subscription.updated e customer.subscription.deleted. Esses eventos passam um objeto de assinatura 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 dos status.

No seu gerenciador de webhooks:

1. Verifique o status da assinatura. Se estiver active, o usuário pagou o 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 intervalo 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 estado de uma assinatura pode mudar a qualquer momento durante sua vida útil, mesmo se o aplicativo não fizer nenhuma chamada direta para a Stripe. Por exemplo, uma renovação pode falhar devido a um cartão de crédito vencido, o que coloca a assinatura em um estado vencido. Ou, se você implementar o portal do cliente, um usuário pode cancelar a assinatura sem visitar diretamente seu aplicativo. A implementação correta do manipulador mantém o estado do aplicativo em sincronia com a Stripe.

É comum permitir que os clientes cancelem suas assinaturas. Este exemplo 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, defina o endpoint para a chamada do seu 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 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, consulte testar sua integração com o Billing.