SopagueDocs
v3

Exemplos práticos de como integrar a Biblioteca Sopague em diferentes cenários de pagamento.

Pré-requisito: Carregamento da Biblioteca

Inclua a biblioteca via CDN antes de utilizar qualquer funcionalidade:

<script src="https://cdn.sopague.com.br/JS/GATEWAY/sopague-integration-library.min.js"></script>

Exemplo: E-commerce (HTML + JavaScript)

// 1. Configurar chave pública RSA
Sopague.setEncryptPublicKey(`-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC...
-----END PUBLIC KEY-----`);
 
// 2. Inicializar anti-fraude
const sessionId = Sopague.initAntiFraud('bc5a19ab-4dec-4ce2-b489-6b7ada73b88c');
 
// 3. Criptografar cartão no momento do pagamento
const encrypted = await Sopague.encryptCard('4111111111111111');
 
// 4. Enviar para sua API com o token e o sessionId
const payload = {
  encryptedCard: encrypted,
  antiFraudSessionId: Sopague.getAntiFraudSessionId(),
  // ... demais dados do pagamento
};

O token criptografado gerado por encryptCard é válido por apenas 5 minutos. Criptografe o cartão somente no momento de processar o pagamento e envie imediatamente para sua API.

Exemplo: Hook React/NextJS

// hooks/useSopague.ts
import { useState, useEffect, useCallback } 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 = 'https://cdn.sopague.com.br/JS/GATEWAY/sopague-integration-library.min.js';
    script.async = true;
    script.onload = () => {
      setIsLoaded(true);
      if (window.Sopague && process.env.NEXT_PUBLIC_RSA_PUBLIC_KEY) {
        window.Sopague.setEncryptPublicKey(process.env.NEXT_PUBLIC_RSA_PUBLIC_KEY);
      }
    };
    script.onerror = () => setError('Erro ao carregar Sopague');
    document.body.appendChild(script);
 
    return () => { document.body.removeChild(script); };
  }, []);
 
  const encryptCard = useCallback(async (cardNumber: string): Promise<string> => {
    if (!window.Sopague) throw new Error('Sopague não carregado');
    return await window.Sopague.encryptCard(cardNumber);
  }, []);
 
  const initAntiFraud = useCallback((sessionId: string): string => {
    if (!window.Sopague) throw new Error('Sopague não carregado');
    return window.Sopague.initAntiFraud(sessionId);
  }, []);
 
  const getSessionId = useCallback((): string | null => {
    if (!window.Sopague) return null;
    return window.Sopague.getAntiFraudSessionId();
  }, []);
 
  return { isLoaded, error, encryptCard, initAntiFraud, getSessionId };
}

Boas Práticas

  1. Criptografe apenas no momento do pagamento — não armazene tokens criptografados
  2. Processe imediatamente — envie o token para a API assim que gerado
  3. Implemente retry — se houver erro de expiração, gere um novo token
  4. Use HTTPS — a Web Crypto API exige ambiente seguro