Visão geral

O que é o Security SDK

O @soarlabz/security-sdk é uma biblioteca JavaScript/TypeScript para navegadores que lida com operações sensíveis de pagamento no lado do cliente. Ele oferece três capacidades principais:

• Tokenização de cartões — substitui dados sensíveis do cartão por um token seguro antes de enviar ao seu backend
• Autenticação 3D Secure (3DS) — orquestra o fluxo de autenticação do portador do cartão junto ao emissor
• Análise de fraude — coleta o fingerprint do dispositivo via ThreatMetrix para alimentar a análise antifraude

Toda comunicação entre o SDK e a API da UniPay é autenticada via chave pública (pk_...), eliminando a necessidade de expor chaves secretas no frontend.

Instalação

npm install @soarlabz/security-sdk@1.2.0

bun add @soarlabz/security-sdk@1.2.0

yarn add @soarlabz/security-sdk@1.2.0

pnpm add @soarlabz/security-sdk@1.2.0

Para uso direto em HTML, carregue a versão publicada e fixa pelo CDN npm:

<script src="https://cdn.jsdelivr.net/npm/@soarlabz/security-sdk@1.2.0/dist/umd/index.js"></script>

Você também pode servir dist/umd/index.js da versão instalada pela sua aplicação. O caminho de CDN fica disponível após a publicação dessa versão no npm; mantenha a versão fixa e inclua a origem cdn.jsdelivr.net na CSP quando usar esse formato.

Formatos disponíveis

Inicialização

Para usar o SDK, crie uma instância do Client com sua chave pública e chame initialize():

import { Client } from '@soarlabz/security-sdk';

const client = new Client({
  publicKey: 'pk_live_sua_chave_aqui',
});

await client.initialize();

Opções do Client

Verificando capacidades

Após a inicialização, você pode verificar quais funcionalidades estão disponíveis para o merchant:

await client.initialize();

if (client.isTokenizationAvailable()) {
  // Tokenização habilitada
}

if (client.isThreeDSAvailable()) {
  // Preparação/autenticação por sessão da plataforma habilitada
}

if (client.isSmartThreeDSAvailable()) {

As capacidades consideram regras elegíveis, conexões próprias, subcontas e processamento autorizado pela conexão master. O método preparePayment também coleta device quando smart_threeds está habilitado e o 3DS antes da cobrança está desligado.

URL base

O SDK se conecta automaticamente à API de produção:

Para desenvolvimento local, use a opção baseUrl para apontar para sua API local.

Autenticação

Todas as requisições do SDK usam Basic Auth com a chave pública:

Authorization: Basic base64(pk_sua_chave:)

Próximos passos