Por que PIX é essencial para e-commerce brasileiro?

O PIX se tornou o método de pagamento preferido no Brasil. Com confirmação instantânea e taxas baixas, integrar PIX no seu e-commerce não é mais opcional - é essencial.

Escolhendo o Gateway de Pagamento

Principais opções no mercado brasileiro:

  • Stripe: Internacional, suporte PIX via PagSeguro
  • PagSeguro: Nativo brasileiro, excelente documentação
  • Mercado Pago: Popular, fácil integração
  • Asaas: Focado em PIX, taxas competitivas

Passo 1: Criar Conta e Obter Credenciais

Após escolher o gateway, você precisará de:

  • API Key (produção e sandbox)
  • Webhook Secret
  • Certificado (se necessário)

Passo 2: Instalar SDK

// Node.js com PagSeguro
npm install pagseguro-nodejs

// Ou usando Axios para API direta
npm install axios

Passo 3: Criar Pedido com PIX

const pagseguro = require('pagseguro-nodejs');

const payment = new pagseguro.Payment({
    email: 'seu-email@exemplo.com',
    token: 'SEU_TOKEN',
    mode: 'sandbox' // ou 'production'
});

payment.currency('BRL');
payment.reference('PEDIDO-12345');

// Adicionar itens
payment.addItem({
    id: '1',
    description: 'Produto Exemplo',
    amount: '100.00',
    quantity: 1
});

// Configurar PIX
payment.paymentMethod('pix', {
    expiration: 3600 // 1 hora
});

payment.send((error, response) => {
    if (error) {
        console.error(error);
        return;
    }
    
    // Retornar QR Code e código PIX para o cliente
    console.log(response.pix.qrCode);
    console.log(response.pix.copyPaste);
});

Passo 4: Configurar Webhook

Webhooks são essenciais para receber notificações de pagamento em tempo real:

// Endpoint para receber webhooks
app.post('/webhook/pagseguro', async (req, res) => {
    const notificationCode = req.body.notificationCode;
    
    // Verificar assinatura do webhook
    const isValid = verifyWebhookSignature(req);
    if (!isValid) {
        return res.status(401).send('Unauthorized');
    }
    
    // Consultar status do pagamento
    const paymentStatus = await getPaymentStatus(notificationCode);
    
    // Atualizar pedido no banco de dados
    await updateOrderStatus(paymentStatus.reference, paymentStatus.status);
    
    res.status(200).send('OK');
});

async function getPaymentStatus(notificationCode) {
    const response = await axios.get(
        `https://ws.sandbox.pagseguro.uol.com.br/v3/transactions/notifications/${notificationCode}`,
        {
            params: {
                email: process.env.PAGSEGURO_EMAIL,
                token: process.env.PAGSEGURO_TOKEN
            }
        }
    );
    
    return {
        reference: response.data.reference,
        status: response.data.status,
        amount: response.data.grossAmount
    };
}

Passo 5: Interface do Usuário

Crie uma interface amigável para exibir o QR Code e código PIX:

// React Component
function PixPayment({ qrCode, copyPasteCode }) {
    const [copied, setCopied] = useState(false);
    
    const copyToClipboard = () => {
        navigator.clipboard.writeText(copyPasteCode);
        setCopied(true);
        setTimeout(() => setCopied(false), 2000);
    };
    
    return (
        

            
Pagamento via PIX

            
            
            
Escaneie o QR Code ou copie o código PIX

        

    );
}

Passo 6: Verificação de Pagamento

Implemente polling ou use webhooks para verificar status:

// Verificação periódica (fallback)
setInterval(async () => {
    const pendingOrders = await getPendingPixOrders();
    
    for (const order of pendingOrders) {
        const status = await checkPaymentStatus(order.paymentId);
        
        if (status === 'PAID') {
            await confirmOrder(order.id);
            // Enviar email de confirmação
            await sendConfirmationEmail(order);
        }
    }
}, 60000); // A cada minuto

Melhorias na Experiência do Usuário

1. Contador de Expiração

Mostre ao cliente quanto tempo resta para pagar:

function CountdownTimer({ expiresAt }) {
    const [timeLeft, setTimeLeft] = useState(calculateTimeLeft(expiresAt));
    
    useEffect(() => {
        const timer = setInterval(() => {
            setTimeLeft(calculateTimeLeft(expiresAt));
        }, 1000);
        
        return () => clearInterval(timer);
    }, [expiresAt]);
    
    return 
Tempo restante: {timeLeft}
;
}

2. Notificação em Tempo Real

Use WebSockets ou Server-Sent Events para notificar quando o pagamento for confirmado:

// WebSocket para atualização em tempo real
const io = require('socket.io')(server);

io.on('connection', (socket) => {
    socket.on('subscribe-order', (orderId) => {
        socket.join(`order-${orderId}`);
    });
});

// Quando pagamento for confirmado
io.to(`order-${orderId}`).emit('payment-confirmed');

3. Redirecionamento Automático

Após confirmação, redirecione automaticamente para página de sucesso.

Tratamento de Erros

Sempre implemente tratamento robusto de erros:

  • Timeouts de pagamento
  • Pagamentos duplicados
  • Falhas na comunicação com gateway
  • Validação de valores

Segurança

Mantenha suas credenciais seguras:

  • Nunca commite credenciais no código
  • Use variáveis de ambiente
  • Valide assinatura de webhooks
  • Implemente rate limiting
  • Use HTTPS sempre

Testes

Teste todos os cenários:

  • Pagamento bem-sucedido
  • Pagamento expirado
  • Cancelamento
  • Estornos
  • Webhooks duplicados

Dica profissional: Sempre teste em ambiente sandbox antes de ir para produção. A maioria dos gateways oferece ferramentas para simular diferentes cenários de pagamento.