Visão geral

O que é o Security SDK

O @accithus/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 Accithus é autenticada via chave pública (pk_...), eliminando a necessidade de expor chaves secretas no frontend.

Instalação

npm install @accithus/security-sdk

bun add @accithus/security-sdk

yarn add @accithus/security-sdk

pnpm add @accithus/security-sdk

O SDK também pode ser carregado via CDN para uso direto em HTML:

<script src="https://cdn.accithus.com/sdk/v1/index.js"></script>
<!-- ou versão fixa -->
<script src="https://cdn.accithus.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 '@accithus/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()) {
  // Análise de fraude habilitada
}

As capacidades são determinadas pela configuração do merchant no dashboard da Accithus — 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.accithus.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

Começando

Cobranças

Submerchants

Financeiro

Configuração

SDK de Segurança

Webhooks

O que é o Security SDK

Instalação

Formatos disponíveis

Inicialização

Opções do Client

Verificando capacidades

URL base

Autenticação

Próximos passos

Fluxo simplificado

Tokenização

Autenticação 3DS

Análise de fraude

Fluxo completo (manual)

Erros

Produção e segurança

​O que é o Security SDK

​Instalação

​Formatos disponíveis

​Inicialização

​Opções do Client

​Verificando capacidades

​URL base

​Autenticação

​Próximos passos

Fluxo simplificado

Tokenização

Autenticação 3DS

Análise de fraude

Fluxo completo (manual)

Erros

Produção e segurança

O que é o Security SDK

Instalação

Formatos disponíveis

Inicialização

Opções do Client

Verificando capacidades

URL base

Autenticação

Próximos passos