Stripe

Integração com Stripe

Este documento detalha a arquitetura e o fluxo de interação com a API do Stripe para processamento de pagamentos na plataforma Base dos Dados.

Visão Geral

Utilizamos o Stripe para gerenciar doações e pagamentos de assinaturas. A integração é projetada para ser segura, robusta e escalável, lidando com diferentes etapas do ciclo de vida de um pagamento.

O fluxo principal envolve três componentes:

1. Frontend (Cliente): A interface com o usuário, construída com Next.js/React, onde o processo de pagamento é iniciado.
2. Backend (Servidor): Nossa API que lida com a lógica de negócios, cria sessões de pagamento e interage de forma segura com o Stripe.
3. Stripe: A plataforma de pagamentos que processa as transações e envia notificações sobre o status dos pagamentos.

Fluxo de Pagamento

O processo de pagamento, desde o clique do usuário até a confirmação, segue as etapas abaixo:

1. Início do Pagamento (Frontend):

   • O usuário seleciona um plano de assinatura e navega para a página de pagamento.
   • O frontend envia uma requisição para o nosso backend (ex: /api/stripe/createSubscription), passando o ID do plano e um cupom, se aplicável.

2. Criação do Intento de Pagamento (Backend):

   • Nosso backend recebe a requisição.
   • Ele utiliza a biblioteca stripe-node para criar uma Assinatura (Subscription) associada a um cliente.
   • Dependendo do status da assinatura, o Stripe gera um PaymentIntent (para um pagamento imediato) ou um SetupIntent (para salvar o método de pagamento para cobranças futuras).
   • O backend extrai o client_secret do latest_invoice.payment_intent (no caso de assinaturas) ou do pending_setup_intent.
   • O client_secret é retornado ao frontend. Este segredo é uma chave única que autoriza o frontend a coletar os dados de pagamento de forma segura para este intento específico.

3. Renderização do Formulário (Frontend):

   • O frontend recebe o clientSecret.
   • Ele usa o componente <Elements> da biblioteca @stripe/react-stripe-js para criar um contexto do Stripe, passando o clientSecret.
   • Dentro do <Elements>, o componente <PaymentElement> é usado para renderizar um formulário de pagamento seguro e dinâmico, diretamente na página.

4. Submissão e Confirmação (Frontend):

   • O usuário preenche os dados do cartão e clica em "Confirmar Pagamento".
   • A função handlerSubmit é chamada.
   • Ela usa stripe.confirmPayment() ou stripe.confirmSetup() (dependendo do tipo de clientSecret) para enviar os dados de forma segura diretamente para o Stripe, sem que eles passem pelo seu servidor.

5. Processamento e Retorno (Stripe -> Frontend):

   • O Stripe processa o pagamento ou a configuração do método de pagamento.
   • A API do Stripe retorna o resultado da operação (sucesso ou erro) para o frontend.
   • O frontend então lida com o resultado, chamando onSucess() ou onErro() para mostrar a mensagem apropriada ao usuário.

Webhooks: Lidando com Eventos Assíncronos

Para garantir que nosso sistema seja notificado sobre eventos importantes que ocorrem após o checkout (como pagamentos confirmados, falhas, disputas, etc.), utilizamos Webhooks.

1. Configuração: Um endpoint específico em nosso backend é configurado no painel do Stripe para receber notificações de eventos.

2. Recebimento de Eventos: O Stripe envia uma requisição POST para nosso endpoint de webhook sempre que um evento relevante acontece.

3. Verificação de Assinatura: É crucial verificar a assinatura do webhook para garantir que a requisição veio de fato do Stripe e não de um terceiro mal-intencionado. A biblioteca do Stripe fornece um método para isso.