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 criados previamente para coletar pagamentos e gerenciar assinaturas.

Configure o servidor

Configurar a Stripe

Instale o cliente Stripe 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ê oferecer vários intervalos de cobrança, use o Checkout para fazer upsell aos clientes em intervalos de cobrança maiores e coletar mais receitas antecipadamente.

Para outros modelos de preços, consulte os exemplos de cobrança.

Criar uma sessão do Checkout

Adicione um endpoint ao servidor que cria uma Checkout Session.

Ao criar a Checkout Session, passe os seguintes parâmetros:

Para usar o formulário do Checkout integrado, defina ui_mode como embedded.
Para criar assinaturas quando seu cliente fizer checkout, defina mode como subscription.
Para definir a página à qual o cliente retorna após concluir ou tentar o pagamento, especifique um return_url. Inclua a variável de modelo {CHECKOUT_SESSION_ID} no URL. O Checkout substitui a variável pelo ID da sessão do Checkout antes de redirecionar o cliente. Você cria e hospeda a página de devolução no seu site.

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

Criar sua página de assinatura
Cliente

Montar 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 do 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 coletar os dados do cliente com segurança, crie um espaço reservado vazio div. A Stripe insere um iframe no div.

O Checkout está disponível como parte do Stripe.js. Inclua o script Stripe.js na página, adicionando-o ao cabeçalho do arquivo HTML. Em seguida, crie um nó 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/basil/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 de uma Checkout Session

Crie uma função assíncrona fetchClientSecret que faz uma solicitação ao seu servidor para criar uma sessão do Checkout 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> no formulário de pagamento. O Checkout é renderizado em um iframe que envia dados de pagamento com segurança à Stripe por 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 devolução

Depois que o cliente tenta fazer o pagamento, a Stripe o redireciona para uma página de devolução hospedada por você no seu site. Quando criou a sessão do Checkout, você especificou o 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 concluírem essa página, a Stripe o redirecionará para sua página de retorno.

Criar um endpoint para recuperar uma sessão do Checkout

Adicione um endpoint para recuperar o status de uma sessão do Checkout com o ID da sessão do Checkout no URL.

Recuperar uma sessão do Checkout

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

Gerenciar a sessão

Trate o resultado de acordo com o 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

Provisionar acesso

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. Para saber mais sobre como gerenciar o acesso ao recurso do seu produto, consulte o documento sobre integração de direitos.

No seu gerenciador de webhooks:

Verifique o status da assinatura. Se estiver active, o usuário pagou o produto.
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.
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.

The status of a subscription might change at any point during its lifetime, even if your application doesn’t directly make any calls to Stripe. For example, a renewal might fail due to an expired credit card, which puts the subscription into a past due status. Or, if you implement the customer portal, a user might cancel their subscription without directly visiting your application. Implementing your handler correctly keeps your application status in sync with 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`.

Monitoramento de 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.

Saiba como testar sua integração com o Billing.