@fastsoftbr/security-sdk NPM

📝 Tabela de Conteúdos

Sobre
Funcionalidades
Instalação
Guia de Uso
API de Referência
Características do Token
Segurança
Validações Implementadas
Compatibilidade
Suporte
FAQ

🧐 Sobre

O FastSoft Security SDK uma biblioteca de segurança criada pela FastSoft que permite a tokenização de dados de cartão de crédito de maneira segura e eficiente. Além disso, coleta o fingerprint do dispositivo do consumidor para integração com sistemas de antifraude, aumentando a segurança das transações e reduzindo o risco de fraudes.

O SDK foi desenvolvido especificamente para adicionar uma camada extra de segurança e validação nos gateways de pagamento que utilizam a tecnologia white label da FastSoft. Essa abordagem permite que os gateways parceiros ofereçam proteção avançada contra fraudes sem precisarem desenvolver e manter sua própria infraestrutura de segurança.

⚡ Funcionalidades

Funcionalidade	Status	Descrição
Tokenização de Cartão	✅	Criptografa dados sensíveis do cartão utilizando algoritmos de alta segurança
Fingerprint do Dispositivo	✅	Coleta informações do dispositivo do consumidor para análise antifraude
Integração com Antifraude	✅	Envia dados anonimizados para análise de risco em tempo real
Compatibilidade com Múltiplos Ambientes	✅	Funciona perfeitamente em navegadores modernos e diferentes frameworks

💻 Instalação

A biblioteca pode ser instalada e utilizada de diversas formas, escolha a que melhor se adapta ao seu projeto:

Via CDN (Recomendado para Integrações Rápidas)

<script src="https://js.fastsoftbrasil.com/fastsoft.min.js"></script>

Via NPM

npm install @fastsoftbr/security-sdk --save

Via Yarn

yarn add @fastsoftbr/security-sdk

Via PNPM

pnpm add @fastsoftbr/security-sdk

🚀 Guia de Uso

Configuração Básica

Antes de utilizar o SDK, você precisa configurar sua chave pública obtida no painel da FastSoft:

// Configure a chave pública (obrigatório)
await fastsoft.setPublicKey('sua_chave_publica_aqui');

Tokenização de Cartão

// Dados do cartão a serem tokenizados
const card = {
  number: '4111111111111111',     // Número do cartão
  holderName: 'NOME COMPLETO',    // Nome completo impresso no cartão
  expMonth: '12',                 // Mês de expiração (1-12)
  expYear: '2030',                // Ano de expiração (formato de 4 dígitos)
  cvv: '123'                      // Código de segurança
};

// Tokenizar os dados
const cardToken = await fastsoft.encrypt(card);

// O resultado será um token que pode ser enviado com segurança ao seu servidor
console.log('Token do cartão:', cardToken);

Ambientes

O SDK suporta dois ambientes:

Produção: Ambiente padrão, utilizado para transações reais
Sandbox: Ambiente de testes, para desenvolvimento e homologação

Para utilizar o ambiente de sandbox:

// Configura o SDK para utilizar o ambiente de desenvolvimento
fastsoft.setProductionOff();

📚 API de Referência

Métodos Principais

`setPublicKey(key: string): Promise<void>`

Descrição: Configura a chave pública para uso da API
Parâmetros:
- key (string): Chave pública fornecida pela FastSoft
Retorno: Promise que resolve quando a configuração for concluída

Exemplo:

await fastsoft.setPublicKey('pk_abcdefghijklmn');

`setProductionOff(): void`

Descrição: Configura o SDK para utilizar o ambiente de desenvolvimento (sandbox)
Parâmetros: Nenhum
Retorno: Void
Exemplo:
```
fastsoft.setProductionOff();
```

`encrypt(card: CardData): Promise<string>`

Descrição: Criptografa dados do cartão e retorna um token seguro
Parâmetros:
- card (objeto): Dados do cartão com as seguintes propriedades:
  - number (string): Número do cartão
  - holderName (string): Nome do titular como impresso no cartão
  - expMonth (string): Mês de expiração (1-12)
  - expYear (string): Ano de expiração (formato de 4 dígitos)
  - cvv (string): Código de segurança
Retorno: Promise que resolve com o token do cartão

Exemplo:

const cardToken = await fastsoft.encrypt({
  number: '4111111111111111',
  holderName: 'NOME COMPLETO',
  expMonth: '12',
  expYear: '2030',
  cvv: '123'
});

🎫 Características do Token

Os tokens gerados pelo SDK possuem as seguintes características de segurança:

Tempo de Expiração: O token expira automaticamente após 5 minutos da sua geração
Uso Único: Cada token só pode ser utilizado uma única vez para processamento
Ambiente-específico: Tokens gerados em ambiente de sandbox não funcionam em produção e vice-versa
Validação no Servidor: Os tokens são validados novamente nos servidores da FastSoft antes do processamento da transação

🔒 Segurança

A biblioteca implementa diversas camadas de segurança para garantir a proteção dos dados sensíveis:

✅ Validação Completa dos Dados: Validação extensiva de todos os campos do cartão
✅ Criptografia de Ponta a Ponta: Dados sensíveis são criptografados antes de sair do dispositivo do usuário
✅ Integração com Sistema Antifraude: Coleta de dados comportamentais e de dispositivo para análise de risco
✅ Carregamento Dinâmico de Scripts: Scripts de segurança são carregados sob demanda e apenas quando necessário
✅ Verificação de Ambiente: Sistema de prevenção que impede o carregamento dos scripts de segurança fora de um navegador
✅ Conformidade PCI: Implementação seguindo as melhores práticas de segurança PCI DSS
✅ Sem Armazenamento Local: Nenhum dado sensível é armazenado localmente

🔍 Validações Implementadas

O SDK realiza as seguintes validações antes da tokenização:

💳 Número do Cartão: Validação do algoritmo Luhn
👤 Nome do Titular: Verificação de caracteres válidos e remoção de caracteres especiais
📅 Data de Expiração: Validação de formato e verificação de data válida e não expirada
- Mês de expiração deve ter no máximo 2 caracteres (1-12)
- Ano de expiração deve ter exatamente 4 caracteres e ser maior ou igual ao ano atual
🔐 CVV: Validação de comprimento (3-4 caracteres) e formato numérico

💻 Compatibilidade

O SDK é compatível com:

Navegadores: Chrome, Firefox, Safari, Edge (versões recentes)
Frameworks: React, Vue, Angular, Vanilla JS
Plataformas: Web, PWA, Webviews em aplicativos móveis
Versões JavaScript: ES5+, com suporte para importação via CommonJS e ESModules

💬 Suporte

Para mais informações ou suporte técnico:

🌐 Website: https://fastsoftbrasil.com
📚 Documentação Completa: https://developers.fastsoftbrasil.com
📧 Suporte Técnico: suporte@fastsoftbrasil.com
🔧 Status dos Serviços: https://status.fastsoftbrasil.com

❓ Perguntas Frequentes

Como saber se o token foi gerado corretamente?

O método encrypt() retorna uma Promise que, quando resolvida com sucesso, contém o token. Caso ocorra algum erro, a Promise será rejeitada com uma mensagem de erro descritiva.

É possível usar o SDK em ambientes Node.js?

O SDK foi projetado principalmente para uso em navegadores. Em ambientes Node.js, o SDK detectará automaticamente que não está em um navegador e algumas funcionalidades relacionadas à coleta de fingerprint do dispositivo serão limitadas.

O que acontece se um campo do cartão estiver inválido?

O SDK realizará validações e retornará um erro específico indicando qual campo está inválido e o motivo.

É necessário implementar autenticação 3D Secure?

Não, a autenticação 3D Secure é gerenciada separadamente pelo gateway de pagamento. O SDK da FastSoft cuida apenas da tokenização segura dos dados do cartão. No entanto, estamos atualmente desenvolvendo suporte nativo para 3DS, que estará disponível em uma versão futura da SDK.

fastsoft payment gateway

1.0.2

10 months ago

1.0.1

10 months ago

1.0.0

10 months ago