Skip to main content

Sopague Library

JavaScript library for RSA encryption and anti-fraud integration in web applications.

Features​

  • RSA-OAEP encryption with SHA-256
  • Built-in anti-fraud library (no need to import separate libraries)
  • Zero dependencies
  • Lightweight and fast (~5KB minified)
  • Compatible with all modern browsers

Installation​

Via CDN​

<!-- Specific version (recommended for production) -->
<!-- To obtain the Sopague library CDN URL, contact support -->
<script src="https://cdn.exemplo.com/sopague/sopague.min.js"></script>

Local download​

<!-- Download the file and reference it locally -->
<script src="/libs/sopague-integration-library-1.0.0.min.js"></script>

Quick usage​

RSA encryption​

// Set public key
const publicKey = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`;

Sopague.setEncryptPublicKey(publicKey);

// Encrypt card number
const encrypted = await Sopague.encryptCard('0000000000000000');
console.log(encrypted); // Base64 string
⚠️ Important about encryption
  • Validity: The encrypted token expires in 5 minutes
  • Best timing: Encrypt only at the moment you process the payment
  • Do not store: Avoid storing encrypted tokens for long periods

Anti-fraud​

// Initialize fraud detection
const sessionId = Sopague.initAntiFraud('bc5a19ab-4dec-4ce2-b489-6b7ada73b88c');
console.log(sessionId); // 'adiq_brbc5a19ab-4dec-4ce2-b489-6b7ada73b88c'

// With custom options
Sopague.initAntiFraud('user_123456', {
  orgId: 'custom_org_id',
  sessionPrefix: 'myapp_'
});

// Get current session ID
const currentSession = Sopague.getAntiFraudSessionId();

// Remove when no longer needed
Sopague.removeAntiFraud();

Full API​

Encryption​

setEncryptPublicKey(publicKeyPem: string): void​

Sets the RSA public key in PEM format.

Sopague.setEncryptPublicKey(publicKeyPem);

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

Encrypts a card number and returns a Base64 string.

⏰ Validity period

The encryption result only works for 5 minutes. After that, the encrypted token expires and cannot be used to process payments.

💡 Recommendation

Encrypt only at the time you finalize the payment to avoid expired tokens. Do not store encrypted data for long periods.

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

Anti-fraud​

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

Initializes the anti-fraud module and returns the full session ID.

Parameters:

  • antiFraudId (string): GUID generated by your application
  • options (optional):
    • orgId (string): Organization ID
    • sessionPrefix (string): Session prefix
const sessionId = Sopague.initAntiFraud('user123', {
  orgId: '1snn5n9w',
  sessionPrefix: 'myapp_'
});

removeAntiFraud(): void​

Removes the anti-fraud iframe.

Sopague.removeAntiFraud();

getAntiFraudSessionId(): string | null​

Returns the current anti-fraud session ID.

const sessionId = Sopague.getAntiFraudSessionId();

setAntiFraudOrgId(orgId: string): void​

Sets the anti-fraud organization ID.

Sopague.setAntiFraudOrgId('custom_org_id');

setAntiFraudSessionPrefix(prefix: string): void​

Sets the anti-fraud session prefix.

Sopague.setAntiFraudSessionPrefix('myapp_');

Utilities​

getVersion(): string​

Returns the library version.

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

getInfo(): Object​

Returns detailed information about the library.

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

NextJS integration​

TypeScript typings​

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;
}

// Global declaration for the Sopague class
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;
        };
    }
}

Custom hook​

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,
    };
}

Example usage in a component​

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 {
            // Set public key
            Sopague.setEncryptPublicKey(process.env.NEXT_PUBLIC_RSA_PUBLIC_KEY);
            
            // Initialize anti-fraud
            Sopague.initAntiFraud('user-session-id');
            
            // Encrypt card
            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>
    );
}

Vanilla JavaScript integration​

<!DOCTYPE html>
<html>
<head>
    <title>Sopague Integration</title>
<!-- To obtain the Sopague library CDN URL, contact [support](/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 {
                // Initialize anti-fraud
                Sopague.initAntiFraud('b12d3b7a-2f8b-4281-84ee-b4e99e029aa1');
                
                // Set public key
                Sopague.setEncryptPublicKey(publicKey);
                
                // Encrypt card
                const encrypted = await Sopague.encryptCard(data);
                outputEl.textContent = encrypted;
            } catch (err) {
                outputEl.textContent = 'Erro: ' + err.message;
            }
        });
    </script>
</body>
</html>

Compatibility​

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

⚠️ Requires HTTPS (Web Crypto API)

Security​

The Sopague library implements security best practices:

  • RSA-OAEP encryption with SHA-256 for maximum security
  • Zero external dependencies to reduce attack surface
  • Strict input validation to prevent injection
  • HTTPS required to ensure secure communication

Support​

For questions or issues with Sopague library integration, contact our support team.

Next steps​

  1. Implementation: Add the library to your project following the examples above
  2. Configuration: Set public keys and anti-fraud IDs
  3. Testing: Test in a development environment
  4. Production: Deploy to production following security best practices

For more information about secure payments, see our 3DS payments documentation.