Front-end10 min de leitura

Checkout Seguro no React: Tokenização com Stripe e UX de Formulário

Fluxo correto de pagamento: Stripe Elements no frontend (dados do cartão nunca tocam seu servidor), tokenização via PaymentIntent, máscara de input, validação de bandeira e tratamento de erros de pagamento no backend.

12 de agosto de 2026

A etapa de checkout é onde os negócios são fechados ou perdidos. Um formulário de cartão confuso, sem máscara, com feedback de erro genérico ('Pagamento falhou') pode custar 30-70% de abandono no checkout — números reais documentados em estudos de conversão. Mas o problema de UX é secundário: o problema técnico mais crítico é onde os dados do cartão passam.

A abordagem correta — e a única que mantém você fora do escopo PCI DSS nível 1 — é usar o Stripe Elements: o formulário de cartão renderiza dentro de iframes do Stripe, os dados do cartão nunca tocam seu servidor, e você recebe apenas um paymentMethodId para confirmar o pagamento no backend.

Arquitetura: O Fluxo Correto

Backend: cria um PaymentIntent no Stripe com o valor → recebe o clientSecret
Frontend: inicializa o Stripe Elements com o clientSecret
Usuário: preenche o formulário (dados vão direto para o Stripe, não para o seu servidor)
Frontend: chama stripe.confirmCardPayment() → Stripe processa e retorna o resultado
Backend: webhook do Stripe notifica que o pagamento foi confirmado → atualiza o banco de dados

bash

1npm install @stripe/stripe-js @stripe/react-stripe-js
npm install @stripe/stripe-js @stripe/react-stripe-js
2npm install stripe  # No backend
npm install stripe  # No backend

Backend: Criando o PaymentIntent

O PaymentIntent é o objeto central do Stripe: representa uma intenção de cobrar um valor de um cliente. Criar no backend (com a secret key) garante que o valor e a moeda não possam ser alterados pelo frontend. O clientSecret retornado é seguro para enviar ao navegador — ele autoriza apenas a confirmação daquele pagamento específico, não o acesso à conta Stripe.

CreatePaymentIntentUseCase.ts

1import Stripe from 'stripe';
import Stripe from 'stripe';
2

3const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
4  apiVersion: '2024-06-20',
  apiVersion: '2024-06-20',
5});
});
6

7interface CreatePaymentIntentDTO {
interface CreatePaymentIntentDTO {
8  orderId: string;
  orderId: string;
9  amountCents: number; // Stripe trabalha com centavos
  amountCents: number; // Stripe trabalha com centavos
10  currency: string;    // 'brl', 'usd'
  currency: string;    // 'brl', 'usd'
11  customerId?: string; // ID do customer no Stripe (para salvar cartão)
  customerId?: string; // ID do customer no Stripe (para salvar cartão)
12}
}
13

14export class CreatePaymentIntentUseCase {
export class CreatePaymentIntentUseCase {
15  async execute(dto: CreatePaymentIntentDTO) {
  async execute(dto: CreatePaymentIntentDTO) {
16    const paymentIntent = await stripe.paymentIntents.create({
    const paymentIntent = await stripe.paymentIntents.create({
17      amount: dto.amountCents,
      amount: dto.amountCents,
18      currency: dto.currency,
      currency: dto.currency,
19      customer: dto.customerId,
      customer: dto.customerId,
20      // Metadados para rastrear o pedido no webhook
      // Metadados para rastrear o pedido no webhook
21      metadata: { orderId: dto.orderId },
      metadata: { orderId: dto.orderId },
22      // automatic_payment_methods permite Pix, boleto, etc.
      // automatic_payment_methods permite Pix, boleto, etc.
23      automatic_payment_methods: { enabled: true },
      automatic_payment_methods: { enabled: true },
24    });
    });
25

26    return {
    return {
27      // clientSecret é enviado ao frontend — permite confirmar o pagamento
      // clientSecret é enviado ao frontend — permite confirmar o pagamento
28      // Não é a secret key! É seguro enviar ao cliente.
      // Não é a secret key! É seguro enviar ao cliente.
29      clientSecret: paymentIntent.client_secret,
      clientSecret: paymentIntent.client_secret,
30      paymentIntentId: paymentIntent.id,
      paymentIntentId: paymentIntent.id,
31    };
    };
32  }
  }
33}
}

Frontend: Stripe Elements

O PaymentElement do Stripe é um componente que renderiza dentro de um iframe isolado controlado pelo Stripe. O número do cartão, o CVV e a data de validade são capturados nesse iframe e enviados diretamente para os servidores do Stripe — o JavaScript da sua aplicação nunca tem acesso a esses dados. Isso elimina o escopo PCI DSS mais rigoroso, pois dados de cartão nunca transitam pela sua infraestrutura.

StripeProvider.tsx

1import { Elements } from '@stripe/react-stripe-js';
import { Elements } from '@stripe/react-stripe-js';
2import { loadStripe } from '@stripe/stripe-js';
import { loadStripe } from '@stripe/stripe-js';
3

4// Inicializado fora do componente — evita recriar a cada render
// Inicializado fora do componente — evita recriar a cada render
5const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY as string);
const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY as string);
6

7interface StripeProviderProps {
interface StripeProviderProps {
8  clientSecret: string;
  clientSecret: string;
9  children: React.ReactNode;
  children: React.ReactNode;
10}
}
11

12export function StripeProvider({ clientSecret, children }: StripeProviderProps) {
export function StripeProvider({ clientSecret, children }: StripeProviderProps) {
13  return (
  return (
14    <Elements
    <Elements
15      stripe={stripePromise}
      stripe={stripePromise}
16      options={{
      options={{
17        clientSecret,
        clientSecret,
18        appearance: {
        appearance: {
19          theme: 'stripe',
          theme: 'stripe',
20          variables: {
          variables: {
21            colorPrimary: '#6366f1',  // Adapte à sua paleta de cores
            colorPrimary: '#6366f1',  // Adapte à sua paleta de cores
22            borderRadius: '8px',
            borderRadius: '8px',
23          },
          },
24        },
        },
25        locale: 'pt-BR',
        locale: 'pt-BR',
26      }}
      }}
27    >
    >
28      {children}
      {children}
29    </Elements>
    </Elements>
30  );
  );
31}
}

CheckoutForm.tsx

1import { useState } from 'react';
import { useState } from 'react';
2import {
import {
3  PaymentElement,
  PaymentElement,
4  useStripe,
  useStripe,
5  useElements,
  useElements,
6} from '@stripe/react-stripe-js';
} from '@stripe/react-stripe-js';
7

8export function CheckoutForm({ orderId }: { orderId: string }) {
export function CheckoutForm({ orderId }: { orderId: string }) {
9  const stripe = useStripe();
  const stripe = useStripe();
10  const elements = useElements();
  const elements = useElements();
11  const [isProcessing, setIsProcessing] = useState(false);
  const [isProcessing, setIsProcessing] = useState(false);
12  const [errorMessage, setErrorMessage] = useState<string | null>(null);
  const [errorMessage, setErrorMessage] = useState<string | null>(null);
13

14  async function handleSubmit(e: React.FormEvent) {
  async function handleSubmit(e: React.FormEvent) {
15    e.preventDefault();
    e.preventDefault();
16

17    if (!stripe || !elements) return; // Stripe ainda carregando
    if (!stripe || !elements) return; // Stripe ainda carregando
18

19    setIsProcessing(true);
    setIsProcessing(true);
20    setErrorMessage(null);
    setErrorMessage(null);
21

22    // Valida os campos antes de submeter
    // Valida os campos antes de submeter
23    const { error: submitError } = await elements.submit();
    const { error: submitError } = await elements.submit();
24    if (submitError) {
    if (submitError) {
25      setErrorMessage(submitError.message ?? 'Erro ao validar formulário.');
      setErrorMessage(submitError.message ?? 'Erro ao validar formulário.');
26      setIsProcessing(false);
      setIsProcessing(false);
27      return;
      return;
28    }
    }
29

30    // Confirma o pagamento — dados do cartão vão direto para o Stripe
    // Confirma o pagamento — dados do cartão vão direto para o Stripe
31    // Seu servidor nunca vê o número do cartão
    // Seu servidor nunca vê o número do cartão
32    const { error } = await stripe.confirmPayment({
    const { error } = await stripe.confirmPayment({
33      elements,
      elements,
34      confirmParams: {
      confirmParams: {
35        return_url: `${window.location.origin}/checkout/success?order=${orderId}`,
        return_url: `${window.location.origin}/checkout/success?order=${orderId}`,
36      },
      },
37    });
    });
38

39    if (error) {
    if (error) {
40      // Erros específicos do Stripe para UX melhor
      // Erros específicos do Stripe para UX melhor
41      if (error.type === 'card_error' || error.type === 'validation_error') {
      if (error.type === 'card_error' || error.type === 'validation_error') {
42        setErrorMessage(error.message ?? 'Pagamento recusado. Verifique os dados.');
        setErrorMessage(error.message ?? 'Pagamento recusado. Verifique os dados.');
43      } else {
      } else {
44        setErrorMessage('Erro inesperado. Tente novamente.');
        setErrorMessage('Erro inesperado. Tente novamente.');
45      }
      }
46    }
    }
47

48    // Se não houve erro, o Stripe redireciona para return_url
    // Se não houve erro, o Stripe redireciona para return_url
49    setIsProcessing(false);
    setIsProcessing(false);
50  }
  }
51

52  return (
  return (
53    <form onSubmit={handleSubmit} className="space-y-6">
    <form onSubmit={handleSubmit} className="space-y-6">
54      {/* PaymentElement renderiza dentro de iframe do Stripe
      {/* PaymentElement renderiza dentro de iframe do Stripe
55          Os dados do cartão nunca chegam ao seu JavaScript */}
          Os dados do cartão nunca chegam ao seu JavaScript */}
56      <PaymentElement
      <PaymentElement
57        options={{
        options={{
58          layout: 'tabs', // Separa cartão, Pix, etc. em abas
          layout: 'tabs', // Separa cartão, Pix, etc. em abas
59        }}
        }}
60      />
      />
61

62      {errorMessage && (
      {errorMessage && (
63        <p className="text-red-500 text-sm" role="alert">
        <p className="text-red-500 text-sm" role="alert">
64          {errorMessage}
          {errorMessage}
65        </p>
        </p>
66      )}
      )}
67

68      <button
      <button
69        type="submit"
        type="submit"
70        disabled={!stripe || isProcessing}
        disabled={!stripe || isProcessing}
71        className="w-full bg-indigo-600 text-white py-3 px-6 rounded-lg
        className="w-full bg-indigo-600 text-white py-3 px-6 rounded-lg
72                   disabled:opacity-50 disabled:cursor-not-allowed
                   disabled:opacity-50 disabled:cursor-not-allowed
73                   hover:bg-indigo-700 transition-colors"
                   hover:bg-indigo-700 transition-colors"
74      >
      >
75        {isProcessing ? 'Processando...' : 'Confirmar Pagamento'}
        {isProcessing ? 'Processando...' : 'Confirmar Pagamento'}
76      </button>
      </button>
77    </form>
    </form>
78  );
  );
79}
}

Backend: Webhook para Confirmar o Pagamento

StripeWebhookController.ts

1import type { Request, Response } from 'express';
import type { Request, Response } from 'express';
2import Stripe from 'stripe';
import Stripe from 'stripe';
3

4const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
5  apiVersion: '2024-06-20',
  apiVersion: '2024-06-20',
6});
});
7

8export class StripeWebhookController {
export class StripeWebhookController {
9  // IMPORTANTE: esta rota deve receber o body como raw Buffer (não JSON parsed)
  // IMPORTANTE: esta rota deve receber o body como raw Buffer (não JSON parsed)
10  // Adicione antes das outras rotas: app.use('/webhooks/stripe', express.raw({ type: 'application/json' }))
  // Adicione antes das outras rotas: app.use('/webhooks/stripe', express.raw({ type: 'application/json' }))
11  async handle(req: Request, res: Response): Promise<void> {
  async handle(req: Request, res: Response): Promise<void> {
12    const sig = req.headers['stripe-signature'] as string;
    const sig = req.headers['stripe-signature'] as string;
13

14    let event: Stripe.Event;
    let event: Stripe.Event;
15

16    try {
    try {
17      // Verifica a assinatura do webhook — protege contra requisições falsas
      // Verifica a assinatura do webhook — protege contra requisições falsas
18      event = stripe.webhooks.constructEvent(
      event = stripe.webhooks.constructEvent(
19        req.body as Buffer,
        req.body as Buffer,
20        sig,
        sig,
21        process.env.STRIPE_WEBHOOK_SECRET as string
        process.env.STRIPE_WEBHOOK_SECRET as string
22      );
      );
23    } catch (err) {
    } catch (err) {
24      res.status(400).json({ error: 'Webhook signature verification failed' });
      res.status(400).json({ error: 'Webhook signature verification failed' });
25      return;
      return;
26    }
    }
27

28    switch (event.type) {
    switch (event.type) {
29      case 'payment_intent.succeeded': {
      case 'payment_intent.succeeded': {
30        const paymentIntent = event.data.object as Stripe.PaymentIntent;
        const paymentIntent = event.data.object as Stripe.PaymentIntent;
31        const orderId = paymentIntent.metadata.orderId;
        const orderId = paymentIntent.metadata.orderId;
32

33        // Atualiza o pedido no banco de dados
        // Atualiza o pedido no banco de dados
34        await this.ordersRepo.markAsPaid(orderId, paymentIntent.id);
        await this.ordersRepo.markAsPaid(orderId, paymentIntent.id);
35        break;
        break;
36      }
      }
37

38      case 'payment_intent.payment_failed': {
      case 'payment_intent.payment_failed': {
39        const paymentIntent = event.data.object as Stripe.PaymentIntent;
        const paymentIntent = event.data.object as Stripe.PaymentIntent;
40        await this.ordersRepo.markAsFailed(paymentIntent.metadata.orderId);
        await this.ordersRepo.markAsFailed(paymentIntent.metadata.orderId);
41        break;
        break;
42      }
      }
43    }
    }
44

45    // Sempre retorne 200 para o Stripe — caso contrário ele reenvía o webhook
    // Sempre retorne 200 para o Stripe — caso contrário ele reenvía o webhook
46    res.json({ received: true });
    res.json({ received: true });
47  }
  }
48}
}

Nunca confie apenas na resposta do frontend para marcar um pedido como pago. O usuário pode fechar o browser antes do redirecionamento, ou a rede pode falhar. A fonte da verdade é sempre o webhook do Stripe — configure-o e implemente idempotência (verifique se o pedido já foi marcado como pago antes de processar novamente).

Conclusão

O Stripe Elements resolve dois problemas ao mesmo tempo: UX premium com formulário validado, máscara automática e suporte a múltiplos métodos de pagamento (cartão, Pix, boleto) — e conformidade PCI DSS, pois os dados do cartão nunca tocam seu servidor. O webhook é a peça crítica de confiabilidade: garante que pedidos sejam marcados como pagos mesmo quando a conexão do usuário cai após o pagamento.