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

---

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); // encrypted 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: 'custom_session_prefix'
});

// 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 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.encrypt('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('bc5a19ab-4dec-4ce2-b489-6b7ada73b88c', {
  orgId: 'custom_org_id',
  sessionPrefix: 'custom_session_prefix'
});

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('custom_session_prefix');

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>

---

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

Browsers

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

⚠️ Requires HTTPS (Web Crypto API)

Frameworks

✅ React
✅ Next.js
✅ Vue.js
✅ Angular
✅ Vanilla JavaScript

---

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.