💳 Tokenização de Cartões

📋 Visão Geral

A tokenização de cartões é um processo fundamental para garantir a segurança das transações. Ao invés de transmitir dados sensíveis do cartão, você envia um token único e seguro que representa essas informações.

🔒

Segurança PCI DSS

Reduza o escopo de conformidade PCI ao não armazenar dados de cartão

♻️

Tokens Reutilizáveis

Use o mesmo token para múltiplas transações do cliente

⚡

Validação em Tempo Real

Validamos o cartão no momento da tokenização

🚀 Início Rápido

1. Incluir a Biblioteca

Adicione nosso SDK JavaScript ao seu HTML:

<!-- Produção -->
<script src="https://js.fastsoftbrasil.com/security.js"></script>

2. Configurar Chave Pública

Configure sua chave pública antes de tokenizar:

// Aguarde o carregamento do SDK
document.addEventListener('DOMContentLoaded', async function() {
  try {
    // Configure sua chave pública (carrega scripts de segurança automaticamente)
    await FastSoft.setPublicKey('pk_live_sua_chave_publica_aqui');
    
    console.log('FastSoft SDK inicializado com sucesso');
  } catch (error) {
    console.error('Erro ao inicializar SDK:', error.message);
  }
});

3. Tokenizar o Cartão

async function tokenizeCard() {
  const cardData = {
    number: "4111111111111111",
    holderName: "JOAO DA SILVA",
    expMonth: "12",
    expYear: "2025",
    cvv: "123"
  };

  try {
    // Tokenizar o cartão
    const cardToken = await FastSoft.encrypt(cardData);
    
    console.log('Tokenização bem-sucedida!');
    console.log('Token:', cardToken);
    
  } catch (error) {
    console.error('Erro na tokenização:', error.message);
    handleTokenizationError(error);
  }
}

// Resposta de sucesso - retorna diretamente o token string
// Exemplo: "card_a1b2c3d4e5f6"

🛡️ Validações Automáticas

Nossa biblioteca realiza validações completas antes da tokenização:

Validações de Cartão

Campo	Validação	Exemplo Válido
Número	Obrigatório, remove espaços automaticamente	4111111111111111
Nome	Obrigatório, trim automático	JOAO SILVA
Mês	Máximo 2 caracteres	03 ou 12
Ano	Exatamente 4 caracteres	2025
CVV	Entre 3-4 caracteres, remove espaços	123 ou 1234

Tratamento de Erros

try {
  const token = await FastSoft.encrypt(cardData);
} catch (error) {
  // Mensagens de erro específicas do validador
  switch (error.message) {
    case 'card é obrigatório.':
      // Dados do cartão não fornecidos
      break;
    case 'card.number é obrigatório.':
      // Número do cartão não informado
      break;
    case 'card.holderName é inválido.':
      // Nome do portador inválido
      break;
    case 'card.expMonth é inválido. Precisa ser menor ou igual a 2 caracteres.':
      // Mês de expiração inválido
      break;
    case 'card.expYear é inválido. Precisa ter 4 caracteres.':
      // Ano de expiração inválido
      break;
    case 'card.cvv é inválido. Precisa ter entre 3 e 4 caracteres.':
      // CVV inválido
      break;
    default:
      // Erro de rede ou API
      console.error('Erro:', error.message);
  }
}

🔧 Métodos Disponíveis

FastSoft.setPublicKey(key)

Define a chave pública e carrega automaticamente os scripts de segurança necessários.

Parâmetros:

• key (string): Sua chave pública

Retorno:

• Promise que resolve quando os scripts são carregados

FastSoft.encrypt(cardData)

Tokeniza os dados do cartão e retorna o token.

Parâmetros:

• cardData (object): Dados do cartão
  • number (string): Número do cartão (espaços são removidos automaticamente)
  • holderName (string): Nome no cartão (trim aplicado automaticamente)
  • expMonth (string): Mês de expiração (máximo 2 caracteres)
  • expYear (string): Ano de expiração (exatamente 4 caracteres)
  • cvv (string): CVV (3-4 caracteres, espaços removidos automaticamente)

Retorno:

• Promise que resolve com o token (string)

FastSoft.getApiUrl()

Retorna a URL da API atual (produção ou local).

🔒 Recursos de Segurança

Scripts Dinâmicos

O SDK carrega automaticamente scripts de segurança necessários, incluindo:

• Scripts de criptografia
• Scripts de antifraude (quando aplicável)
• Scripts de 3DS (quando aplicável)

SessionId para Antifraud

O SDK procura automaticamente por um elemento com ID sessionId no DOM para envio junto com a tokenização:

<input type="hidden" id="sessionId" value="session_123">

Headers de Segurança

Todas as requisições incluem:

• x-public-key: Sua chave pública
• Accept: application/json
• Content-Type: application/json

❓ FAQ Técnico

O token expira?

Sim, tokens expiram após 15 minutos de existência. Para pagamentos recorrentes, recomendamos re-tokenizar periodicamente.

Como funciona o carregamento de scripts?

O SDK carrega dinamicamente scripts de segurança ao chamar setPublicKey(). Estes scripts incluem criptografia e antifraud.

O que é o sessionId?

O sessionId é um identificador de sessão usado pelo sistema de antifraud. Se presente no DOM (elemento com ID sessionId), será enviado automaticamente.

O método retorna que tipo de dado?

O método encrypt() retorna diretamente uma string com o token, não um objeto complexo.

---

📚 Próximos passos: Criar Primeira Transação | Webhooks