Visão geral
O Security SDK da SoarLabz permite integrar tokenização de cartões, autenticação 3D Secure e análise de fraude diretamente no seu frontend.
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 SoarLabz é autenticada via chave pública (pk_...), eliminando a necessidade de expor chaves secretas no frontend.
Instalação
npm install @soarlabz/security-sdkbun add @soarlabz/security-sdkyarn add @soarlabz/security-sdkpnpm add @soarlabz/security-sdkO SDK também pode ser carregado via CDN para uso direto em HTML:
<script src="https://cdn.soarlabz.com/sdk/v1/index.js"></script>
<!-- ou versão fixa -->
<script src="https://cdn.soarlabz.com/sdk/v1.0.0/index.js"></script>Formatos disponíveis
| Formato | Caminho | Uso |
|---|---|---|
| ESM | dist/esm/index.js | Bundlers modernos (Vite, Webpack, Rollup) |
| CJS | dist/cjs/index.cjs | Node.js / CommonJS |
| UMD | dist/umd/index.js | <script> tag direto no HTML |
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();O método initialize() faz uma chamada à API para buscar as configurações do merchant. Você deve aguardar a conclusão antes de usar qualquer funcionalidade do SDK.
Opções do Client
| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
publicKey | string | Sim | — | Chave pública da API (pk_...). Obtida no dashboard em Configuração > Chaves de API. |
debug | boolean | Não | false | Ativa logs detalhados no console do navegador. |
timeout | number | Não | 30000 | Timeout das requisições HTTP em milissegundos (1.000–60.000). |
baseUrl | string | Não | — | Sobrescreve a URL base da API. Útil para desenvolvimento local. |
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()) {
// 3DS habilitado
}
if (client.isFraudAnalysisAvailable()) {
As capacidades são determinadas pela configuração do merchant no dashboard da SoarLabz — especificamente, as conexões com adquirentes e as configurações de segurança.
URL base
O SDK se conecta automaticamente à API de produção:
| URL |
|---|
https://api.soarlabz.com/v1/public/sdk |
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:)A chave secreta nunca deve ser usada no frontend. O SDK opera exclusivamente com a chave pública, que tem permissões limitadas a operações de tokenização, 3DS e antifraude.
Próximos passos
Fluxo simplificado
Uma única chamada para o fluxo completo de pagamento — recomendado
Tokenização
Substitua dados do cartão por tokens seguros
Autenticação 3DS
Autentique o portador do cartão junto ao emissor
Análise de fraude
Colete fingerprint do dispositivo para análise antifraude
Fluxo completo (manual)
Controle granular sobre cada etapa do pagamento
Erros
Referência de tipos de erro e tratamento
Produção e segurança
CSP, PCI DSS e compatibilidade de navegadores