O Security SDK da PayHub permite integrar tokenização de cartões, autenticação 3D Secure e análise de fraude diretamente no seu frontend.
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:
Toda comunicação entre o SDK e a API da PayHub é autenticada via chave pública (pk_...), eliminando a necessidade de expor chaves secretas no frontend.
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>| 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 |
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.
| 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. |
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 PayHub — especificamente, as conexões com adquirentes e as configurações de segurança.
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.
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.
Uma única chamada para o fluxo completo de pagamento — recomendado
Substitua dados do cartão por tokens seguros
Autentique o portador do cartão junto ao emissor
Colete fingerprint do dispositivo para análise antifraude
Controle granular sobre cada etapa do pagamento
Referência de tipos de erro e tratamento
CSP, PCI DSS e compatibilidade de navegadores