Crie uma integração de assinaturas

Crie e gerencie assinaturas para aceitar pagamentos recorrentes.

Web

iOS

Android

React Native

togethere.work

Esforço de integração

Low-code

Personalização da IU

Personalize a aparência

Tipo de integração

Use formulários integrados pré-criados para recolher pagamentos e gerenciar subscriptions.

Configure o servidor

Configurar a Stripe

Instale o Stripe client de sua escolha:

Criar um produto e preço

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

Adicione um endpoint em seu servidor que crie uma Checkout Session.

Quando você criar a Checkout Session , passe os seguintes parâmetros:

Para usar o formulário de pagamento integrado, defina ui_mode como embedded.
Para criar assinaturas quando o cliente fizer checkout, defina o modo para subscription.
Para definir a página para a qual o cliente retorna após a conclusão do pagamento ou a tentativa de pagamento, especifique uma return_url. Inclua a variável de modelo {CHECKOUT_SESSION_ID} na URL. O Checkout substitui a variável pela ID da sessão de checkout antes de redirecionar o cliente. você cria e hospeda a página de retorno em seu site.
Para incluir os termos de assinatura e cancelamento, além de um link para que seus clientes possam atualizar ou cancelar a assinatura, use, opcionalmente, um texto personalizado. Recomendamos configurar lembretes e notificações por e-mail para seus assinantes.

Para montar o Checkout, use o client_secret da Checkout Session retornado na resposta.

Criar sua página de assinatura
Cliente

Montar o Checkout

Carregar o Stripe.js

Use o Stripe.js para manter a conformidade com o PCI, garantindo que os dados de pagamento sejam enviados diretamente para a Stripe e nunca passem pelo servidor. Sempre carregue o Stripe.js de js.stripe.com para manter a conformidade. Não inclua o script em um pacote nem o hospede.

Defina o formulário de pagamentos

Para recolher com segurança as informações do cliente, crie um espaço reservado vazio div. A Stripe insere um iframe no div.

O Checkout está disponível como parte do Stripe.js(/js). Inclua o script Stripe.js na sua página, adicionando-o ao cabeçalho do arquivo HTML. Em seguida, crie um nódulo DOM vazio (contêiner) para usar na montagem.

index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Accept a payment</title>
    <meta name="description" content="A demo of a payment on Stripe" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="style.css" />
    <!-- Add the Stripe.js script here -->
    <script src="https://js.stripe.com/clover/stripe.js"></script>
    <script src="checkout.js" defer></script>
  </head>
  <body>
    <!-- Display a payment form -->
      <div id="checkout">
        <!-- Checkout inserts the payment form here -->
      </div>
  </body>
</html>

Inicializar o Stripe.js

Inicialize o Stripe.js com sua chave de API publicável.

Obter o segredo do cliente da Checkout Session

Crie uma função assíncrona fetchClientSecret que faça uma solicitação ao servidor para criar uma Checkout Session e recuperar o segredo do cliente.

Inicializar o Checkout

Inicialize o Checkout com sua função fetchClientSecret e monte-a no espaço reservado <div> em seu formulário de pagamento. O Checkout é renderizado em um iframe que envia com segurança as informações de pagamento para a Stripe por meio de uma conexão HTTPS.

Evite colocar o Checkout dentro de outro iframe porque algumas formas de pagamento exigem redirecionamento a outra página para confirmação do pagamento.

index.js
// Initialize Stripe.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Exibir uma página de retorno

Depois que o cliente tenta efetuar o pagamento, a Stripe o redireciona para uma página de retorno que você hospeda em seu site. Ao criar a Checkout Session, você especificou a URL da página de retorno no parâmetro return_url.

Observação

Durante o pagamento, algumas formas de pagamento redirecionam o cliente para uma página intermediária, como uma página de autorização bancária. Quando o cliente conclui essa página, a Stripe o redireciona para a sua página de retorno.

Crie um endpoint para recuperar uma Checkout Session

Adicione um endpoint para recuperar o status de uma Checkout Session com o ID da Checkout Session na URL.

Recuperar uma Checkout Session

Para usar os detalhes da Checkout Session, faça imediatamente uma solicitação ao endpoint em seu servidor para recuperar o status da Checkout Session usando o ID da Checkout Session na URL assim que a página de retorno for carregada.

Manipular a sessão

Tratar o resultado estabelecido no status da sessão:

complete: o pagamento foi bem-sucedido. Use as informações da sessão do Checkout para renderizar uma página de sucesso.
open: o pagamento falhou ou foi cancelado. Remonte o Checkout para que seu cliente possa tentar novamente.

return.js
// Retrieve a Checkout Session
// Use the session ID
initialize();

async function initialize() {
  const queryString = window.location.search;
  const urlParams = new URLSearchParams(queryString);
  const sessionId = urlParams.get('session_id');
  const response = await fetch(`/session-status?session_id=${sessionId}`);
  const session = await response.json();
// Handle the session according to its status
  if (session.status == 'open') {
    // Remount embedded Checkout
    window.location.replace('http://localhost:4242/checkout.html')
  } else if (session.status == 'complete') {
    document.getElementById('success').classList.remove('hidden');
    document.getElementById('customer-email').textContent = session.customer_email;
    // Show success page
    // Optionally use session.payment_status or session.customer_email
    // to customize the success page
  }
}

server.js
// Add an endpoint to fetch the Checkout Session status
app.get('/session_status', async (req, res) => {
  const session = await stripe.checkout.sessions.retrieve(req.query.session_id);
  const customer = await stripe.customers.retrieve(session.customer);

  res.send({
    status: session.status,
    payment_status: session.payment_status,
    customer_email: customer.email
  });
});

OpcionalConfigurar o portal de clientes

Você pode configurar o portal do cliente para permitir que seus clientes gerenciem diretamente suas assinaturas e faturas existentes.

Você pode configurar o portal no Dashboard. Para reduzir a rotatividade, você pode configurar o portal para permitir que os clientes atualizem suas formas de pagamento em caso de falha nos pagamentos.

Para ajudar os clientes a encontrá-lo, adicione um botão em seu site para redirecionar para o portal do cliente e permitir que os clientes gerenciem suas assinaturas. Ao clicar nesse botão, o cliente é redirecionado para a página do portal do cliente hospedado pela Stripe.

Saiba mais sobre o portal do cliente e outras opções de gerenciamento de clientes.

Criar uma sessão no portal

Para adicionar um portal do cliente, defina um endpoint que crie a sessão do portal do cliente para o front end chamar. O CUSTOMER_ID refere-se ao ID do cliente criado por uma Checkout Session que você salvou ao processar o Webhook 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:

Enviar clientes ao portal de clientes

No front end, adicione um botão à página em success_url que forneça um link para o portal do cliente:

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, certifique-se de monitorar eventos adicionais.

Provisionar acesso

Quando a assinatura estiver 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. Para gerenciar o acesso ao recurso de seu produto, saiba mais sobre integrar direitos.

No seu gerenciador de webhooks:

Verifique o status da assinatura. Se estiver ativa, o usuário pagou pelo seu produto.
Verifique o produto que o cliente assinou e conceda a ele acesso ao seu serviço. Ao verificar o produto em vez do preço, você pode alterar o preço ou o período de cobrança, conforme necessário.
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 da assinatura pode mudar a qualquer momento durante sua vida útil, mesmo que sua inscrição não faça nenhuma chamada direta para a Stripe. Por exemplo, uma renovação pode falhar devido a um cartão vencido, o que coloca a assinatura em um status vencido. Ou, se você implementar o portal do cliente , um usuário poderá cancelar a assinatura sem visitar diretamente a inscrição. A implementação correta do seu manipulador mantém o status da inscrição em sincronia com a Stripe.

Teste a integração

Testar formas de pagamento

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

Forma de pagamento	Cenário	Como testar
Débito automático BECS	O 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 BECS	O 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édito	O 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édito	O 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édito	O 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 SEPA	O 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 SEPA	O 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.