Pular para o conteúdo principal

Biblioteca Sopague

Biblioteca JavaScript para criptografia RSA e inserção de anti-fraude em aplicações web.

Funcionalidades​

  • Criptografia RSA-OAEP com SHA-256
  • Biblioteca anti-fraude integrada (não é necessário importar bibliotecas separadas)
  • Zero dependências
  • Leve e rápido (~5KB minificado)
  • Compatível com todos os navegadores modernos

Instalação​

Via CDN​

<!-- Versão específica (recomendado para produção) -->
<!-- Para obter a URL do CDN da biblioteca Sopague, entre em contato com o suporte -->
<script src="https://cdn.exemplo.com/sopague/sopague.min.js"></script>

Download Local​

<!-- Baixe o arquivo e referencie localmente -->
<script src="/libs/sopague-integration-library-1.0.0.min.js"></script>

Uso Rápido​

Criptografia RSA​

// Configurar chave pública
const publicKey = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`;

Sopague.setEncryptPublicKey(publicKey);

// Criptografar número do cartão
const encrypted = await Sopague.encryptCard('0000000000000000');
console.log(encrypted); // Base64 string
⚠️ Importante sobre Criptografia
  • Tempo de validade: O token criptografado expira em 5 minutos
  • Momento ideal: Criptografe apenas no momento de processar o pagamento
  • Não armazene: Evite salvar tokens criptografados por longos períodos

Anti-Fraude​

// Inicializar detecção de fraude
const sessionId = Sopague.initAntiFraud('bc5a19ab-4dec-4ce2-b489-6b7ada73b88c');
console.log(sessionId); // 'adiq_brbc5a19ab-4dec-4ce2-b489-6b7ada73b88c'

// Com opções personalizadas
Sopague.initAntiFraud('user_123456', {
  orgId: 'custom_org_id',
  sessionPrefix: 'myapp_'
});

// Obter session ID atual
const currentSession = Sopague.getAntiFraudSessionId();

// Remover quando não for mais necessário
Sopague.removeAntiFraud();

API Completa​

Criptografia​

setEncryptPublicKey(publicKeyPem: string): void​

Configura a chave pública RSA em formato PEM.

Sopague.setEncryptPublicKey(publicKeyPem);

encryptCard(plainText: string): Promise<string>​

Criptografa um número de cartão e retorna em Base64.

⏰ Tempo de Validade

O código gerado na criptografia só funciona por 5 minutos. Após esse período, o token criptografado expira e não pode ser usado para processar pagamentos.

💡 Recomendação

Criptografe apenas na hora de concretizar o pagamento para evitar tokens expirados. Não armazene dados criptografados por longos períodos.

const encrypted = await Sopague.encryptCard('0000000000000000');

Anti-Fraude​

initAntiFraud(antiFraudId: string, options?: Object): string​

Inicializa o módulo de anti-fraude e retorna o session ID completo.

Parâmetros:

  • antiFraudId (string): GUID gerado pela sua aplicação
  • options (opcional):
    • orgId (string): ID da organização
    • sessionPrefix (string): Prefixo da sessão
const sessionId = Sopague.initAntiFraud('user123', {
  orgId: '1snn5n9w',
  sessionPrefix: 'myapp_'
});

removeAntiFraud(): void​

Remove o iframe de anti-fraude.

Sopague.removeAntiFraud();

getAntiFraudSessionId(): string | null​

Retorna o session ID atual do anti-fraude.

const sessionId = Sopague.getAntiFraudSessionId();

setAntiFraudOrgId(orgId: string): void​

Configura o ID da organização para anti-fraude.

Sopague.setAntiFraudOrgId('custom_org_id');

setAntiFraudSessionPrefix(prefix: string): void​

Configura o prefixo da sessão para anti-fraude.

Sopague.setAntiFraudSessionPrefix('myapp_');

Utilitários​

getVersion(): string​

Retorna a versão da biblioteca.

console.log(Sopague.getVersion()); // '1.0.0'

getInfo(): Object​

Retorna informações detalhadas sobre a biblioteca.

const info = Sopague.getInfo();
console.log(info);
// {
//   version: '1.0.0',
//   modules: {
//     crypto: { available: true, hasPublicKey: true },
//     antiFraud: { available: true, isActive: true, sessionId: '...' }
//   }
// }

Integração NextJS​

Tipagens TypeScript​

export type AntiFraudOptionsType = {
    orgId: string;
    sessionPrefix: string;
}

export type InfoType = {
    version: string;
    modules: ModulesType;
}

export type ModulesType = {
    crypto: CryptoModuleType;
    antiFraud: AntiFraudModuleType;
}

export type AntiFraudModuleType = {
    available: boolean;
    isActive: boolean;
    sessionId: string;
}

export type CryptoModuleType = {
    available: boolean;
    hasPublicKey: boolean;
}

// Declaração global da Classe Sopague
declare global {
    interface Window {
        Sopague: {
            setEncryptPublicKey: (key: string) => void;
            encryptCard: (text: string) => Promise<string>;
            initAntiFraud: (antiFraudId: string, options?: AntiFraudOptionsType) => string;
            removeAntiFraud: () => void;
            getAntiFraudSessionId: () => string | null;
            getVersion: () => string;
            getInfo: () => InfoType;
        };
    }
}

Hook Customizado​

import { useState, useEffect } from 'react';

export function useSopague() {
    const [isLoaded, setIsLoaded] = useState(false);
    const [error, setError] = useState<string | null>(null);

    useEffect(() => {
        if (typeof window !== 'undefined' && window.Sopague) {
            setIsLoaded(true);
            return;
        }

        const script = document.createElement('script');
        script.src = '/libs/sopague-integration-library-1.0.0.min.js';
        script.async = true;

        script.onload = () => {
            setIsLoaded(true);
        };

        script.onerror = () => {
            setError('Erro ao carregar Sopague');
        };

        document.body.appendChild(script);

        return () => {
            document.body.removeChild(script);
        };
    }, []);

    return {
        Sopague: typeof window !== 'undefined' ? window.Sopague : null,
        isLoaded,
        error,
    };
}

Exemplo de Uso no Componente​

import React, { useState } from 'react';
import { useSopague } from '../hooks/useSopague';

export default function PaymentForm() {
    const { Sopague, isLoaded, error } = useSopague();
    const [cardNumber, setCardNumber] = useState('');
    const [encryptedCard, setEncryptedCard] = useState('');

    const handleEncrypt = async () => {
        if (!Sopague || !cardNumber) return;

        try {
            // Configurar chave pública
            Sopague.setEncryptPublicKey(process.env.NEXT_PUBLIC_RSA_PUBLIC_KEY);
            
            // Inicializar anti-fraude
            Sopague.initAntiFraud('user-session-id');
            
            // Criptografar cartão
            const encrypted = await Sopague.encryptCard(cardNumber);
            setEncryptedCard(encrypted);
        } catch (err) {
            console.error('Erro na criptografia:', err);
        }
    };

    if (error) return <div>Erro ao carregar biblioteca: {error}</div>;
    if (!isLoaded) return <div>Carregando biblioteca...</div>;

    return (
        <div>
            <input
                type="text"
                value={cardNumber}
                onChange={(e) => setCardNumber(e.target.value)}
                placeholder="Número do cartão"
            />
            <button onClick={handleEncrypt}>Criptografar</button>
            {encryptedCard && <p>Cartão criptografado: {encryptedCard}</p>}
        </div>
    );
}

Integração JavaScript Vanilla​

<!DOCTYPE html>
<html>
<head>
    <title>Integração Sopague</title>
<!-- Para obter a URL do CDN da biblioteca Sopague, entre em contato com o [suporte](/suporte) -->
<script src="https://cdn.exemplo.com/sopague/sopague.min.js"></script>
</head>
<body>
    <div>
        <input type="text" id="inputData" placeholder="Número do cartão">
        <button id="btnEncrypt">Criptografar</button>
        <div id="output"></div>
    </div>

    <script>
        const outputEl = document.getElementById('output');
        const inputEl = document.getElementById('inputData');
        const btn = document.getElementById('btnEncrypt');

        const publicKey = `-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC...
-----END PUBLIC KEY-----`;

        btn.addEventListener('click', async () => {
            const data = inputEl.value.replace(/\s/g, "");
            if (!data) return alert('Informe o número do cartão!');
            
            try {
                // Inicializar anti-fraude
                Sopague.initAntiFraud('b12d3b7a-2f8b-4281-84ee-b4e99e029aa1');
                
                // Configurar chave pública
                Sopague.setEncryptPublicKey(publicKey);
                
                // Criptografar cartão
                const encrypted = await Sopague.encryptCard(data);
                outputEl.textContent = encrypted;
            } catch (err) {
                outputEl.textContent = 'Erro: ' + err.message;
            }
        });
    </script>
</body>
</html>

Compatibilidade​

✅ Chrome 37+
✅ Firefox 34+
✅ Safari 11+
✅ Edge 79+
✅ Opera 24+

⚠️ Requer HTTPS (Web Crypto API)

Segurança​

A biblioteca Sopague implementa as melhores práticas de segurança:

  • Criptografia RSA-OAEP com SHA-256 para máxima segurança
  • Zero dependências externas para reduzir vetores de ataque
  • Validação rigorosa de entrada para prevenir injeções
  • HTTPS obrigatório para garantir comunicação segura

Suporte​

Para dúvidas ou problemas com a integração da biblioteca Sopague, entre em contato com nossa equipe de suporte.

Próximos Passos​

  1. Implementação: Adicione a biblioteca ao seu projeto conforme os exemplos acima
  2. Configuração: Configure as chaves públicas e IDs de anti-fraude
  3. Testes: Realize testes em ambiente de desenvolvimento
  4. Produção: Implemente em produção seguindo as boas práticas de segurança

Para mais informações sobre pagamentos seguros, consulte nossa documentação de pagamentos com 3DS.