@fastsoftbr/security-sdk

v1.0.2

Published

10 months ago

FastSoft Security SDK

0High
0Medium
0Low

smookeydev

fastsoft payment gateway

📝 Tabela de Conteúdos

🧐 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: [email protected]
🔧 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.