Visão geral

O que é o Security SDK

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

Instalação

npm install @worldfy/security-sdk

bun add @worldfy/security-sdk

yarn add @worldfy/security-sdk

pnpm add @worldfy/security-sdk

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

<script src="https://cdn.worldfypayments.com/sdk/v1/index.js"></script>
<!-- ou versão fixa -->
<script src="https://cdn.worldfypayments.com/sdk/v1.0.0/index.js"></script>

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 '@worldfy/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()) {
  // 3DS habilitado
}

if (client.isFraudAnalysisAvailable()) {
  // Análise de fraude habilitada
}

As capacidades são determinadas pela configuração do merchant no dashboard da Worldfy — especificamente, as conexões com adquirentes e as configurações de segurança.

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