SopagueDocs
v3

Biblioteca Antifraude

Introdução à Biblioteca Antifraude

A Biblioteca Antifraude é uma biblioteca JavaScript utilizada na integração de pagamentos com cartão em aplicações web. Ela reúne funções para inicializar o módulo antifraude no navegador e criptografar o número do cartão antes do envio à API de pagamento.

Para que serve a biblioteca?

A biblioteca auxilia a preparação dos dados utilizados na integração. A inicialização cria uma sessão antifraude no navegador, enquanto a criptografia protege o número do cartão com RSA-OAEP e SHA-256, utilizando uma chave pública obtida na API.

Esses recursos fazem parte da preparação do pagamento. A biblioteca não envia a requisição de pagamento nem retorna uma aprovação ou um score de risco.

No código, a biblioteca é acessada pelo objeto Sopague. Esse é o objeto usado nos exemplos, mesmo com o nome desta página sendo Biblioteca Antifraude.

Responsabilidades na integração

  • Biblioteca no navegador: inicializa a sessão antifraude e disponibiliza as funções de criptografia do cartão.
  • Aplicação e backend do integrador: coordenam essas etapas, preparam os dados exigidos pelo endpoint e enviam a requisição autenticada à API.
  • API de pagamento: recebe a requisição, processa a solicitação de pagamento e retorna o resultado para a aplicação.

Para concluir a integração, utilize este guia junto com a documentação do endpoint de criação de pagamento, que apresenta os campos da requisição e os retornos da API.

Antes de começar

Fluxo de integração

Carregue a biblioteca, inicialize uma sessão antifraude e criptografe os dados do cartão ao preparar o pagamento. Depois, monte a chamada à API conforme a documentação do endpoint. Inicializar a biblioteca não envia nem aprova um pagamento.

1. Carregue a biblioteca

Escolha uma das opções de carregamento abaixo.

CDN

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

Versão específica

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

Arquivo local

Baixe a versão que pretende utilizar e disponibilize o arquivo na sua aplicação. O caminho abaixo é um exemplo:

<script src="/libs/sopague-integration-library-1.5.2.min.js"></script>

2. Inicialize o antifraude

Informe um GUID gerado pela sua aplicação para identificar a sessão antifraude. O identificador abaixo é ilustrativo; não reutilize o mesmo valor em todas as sessões.

const antiFraudId = 'SUBSTITUA_PELO_GUID_DA_SESSAO';
const sessionId = Sopague.initAntiFraud(antiFraudId);

Para consultar o identificador depois da inicialização:

const currentSession = Sopague.getAntiFraudSessionId();

A inicialização retorna um identificador de sessão, não uma aprovação de pagamento ou um score de risco.

3. Configure a chave e criptografe os dados do cartão

Substitua a chave abreviada abaixo pela chave pública válida obtida na API. O número do cartão é ilustrativo.

const publicKey = `-----BEGIN PUBLIC KEY-----
SUBSTITUA_PELO_CONTEUDO_DA_CHAVE_PUBLICA
-----END PUBLIC KEY-----`;
 
Sopague.setEncryptPublicKey(publicKey);
const encrypted = await Sopague.encryptCard('0000000000000000');

O token criptografado expira em 5 minutos. Criptografe ao preparar o pagamento e não armazene o resultado para transações futuras.

4. Continue na API de pagamento

Consulte a criação de pagamento com antifraude para montar a requisição e tratar os retornos de sucesso e erro. Este guia não demonstra a chamada de pagamento.

5. Remova o módulo quando não for mais necessário

A função abaixo remove o iframe antifraude. Ela é uma operação de limpeza, não o próximo passo a executar imediatamente após a inicialização.

Sopague.removeAntiFraud();

Exemplo: Integração JavaScript Vanilla

Este exemplo demonstra apenas a inicialização e a criptografia. Substitua a chave pública abreviada e o GUID fixo da sessão antes de testar. Ele não chama o endpoint de pagamento.

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.sopague.com.br/JS/GATEWAY/sopague-integration-library.min.js"></script>
</head>
<body>
  <input type="text" id="inputData" placeholder="Número do cartão">
  <button id="btnEncrypt">Criptografar</button>
  <div id="output"></div>
 
  <script>
    const publicKey = `-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC...
-----END PUBLIC KEY-----`;
 
    document.getElementById('btnEncrypt').addEventListener('click', async () => {
      const data = document.getElementById('inputData').value.replace(/\s/g, '');
      if (!data) return alert('Informe o número do cartão!');
 
      Sopague.initAntiFraud('b12d3b7a-2f8b-4281-84ee-b4e99e029aa1');
      Sopague.setEncryptPublicKey(publicKey);
 
      const encrypted = await Sopague.encryptCard(data);
      document.getElementById('output').textContent = encrypted;
    });
  </script>
</body>
</html>