Tokenização

Como funciona

A tokenização substitui o número do cartão (PAN), data de validade e nome do portador por um token opaco que representa esses dados de forma segura. O fluxo é:

O SDK coleta os dados do cartão no frontend
Envia diretamente para a API da Accithus via HTTPS
A API criptografa os dados com AES-256-GCM e retorna um token
Seu frontend envia apenas o token ao seu backend para criar a cobrança

O CVV é usado apenas para validação no momento da tokenização e nunca é armazenado. Os dados criptografados contêm apenas número, nome do portador e validade.

Uso básico

const result = await client.tokenizer.tokenize({
  card: {
    number: '4000000000002701',
    holderName: 'COMPRADOR TESTE',
    expirationMonth: '12',
    expirationYear: '2030',
    cvv: '123',
  },
});

console.log(result.token);          // "tok_abc123..."
console.log(result.brand);          // "visa"
console.log(result.lastFourDigits); // "2701"
console.log(result.firstSixDigits); // "400000"

Parâmetros do cartão

Campo	Tipo	Obrigatório	Descrição
`number`	`string`	Sim	Número do cartão (13 a 19 dígitos).
`holderName`	`string`	Sim	Nome do portador como impresso no cartão.
`expirationMonth`	`string`	Sim	Mês de validade (`01`–`12`).
`expirationYear`	`string`	Sim	Ano de validade (4 dígitos, ex: `2030`).
`cvv`	`string`	Sim	Código de segurança (3 ou 4 dígitos).

Retorno (`TokenizeResult`)

Campo	Tipo	Descrição
`token`	`string`	Token opaco que representa o cartão. Use para criar cobranças.
`brand`	`string`	Bandeira detectada (`visa`, `mastercard`, `elo`, `amex`, `hipercard`, `diners`, `jcb`, `discover`).
`lastFourDigits`	`string`	Últimos 4 dígitos do cartão. Seguro para exibição ao usuário.
`firstSixDigits`	`string`	Primeiros 6 dígitos (BIN).
`expirationMonth`	`string`	Mês de validade.
`expirationYear`	`string`	Ano de validade.

Deduplicação

O SDK detecta automaticamente se o mesmo cartão já foi tokenizado anteriormente para o mesmo merchant. Se um token existente for encontrado (via fingerprint do cartão), ele é retornado diretamente — evitando a criação de tokens duplicados. A detecção é feita por:

Fingerprint HMAC-SHA-256 do número completo do cartão
Fallback por BIN + últimos 4 dígitos + validade (para tokens legados)

Detecção de bandeira

A bandeira é detectada automaticamente pelo BIN (primeiros dígitos do cartão):

Bandeira	Prefixos
Elo	`636368`, `438935`, `504175`, `451416`, `509048–509075`, `36297` e outros
Hipercard	`606282`, `637095`, `637568`, `637599`, `637609`, `637612`
Amex	`34`, `37`
Mastercard	`51–55`, `2221–2720`
Visa	`4`
Diners	`300–305`, `36`, `38`
JCB	`35`
Discover	`6011`, `622126–622925`, `644–649`, `65`

Tratamento de erros

import { ValidationError, ApiError } from '@accithus/security-sdk';

try {
  const result = await client.tokenizer.tokenize({ card: { ... } });
} catch (error) {
  if (error instanceof ValidationError) {
    // Dados do cartão inválidos
    console.error(`Campo inválido: ${error.field}`, error.message);
  } else if (error instanceof ApiError) {
    // Erro retornado pela API
    console.error(`Erro ${error.code}: ${error.message}`);
  }
}

Os erros mais comuns são:

Erro	Causa
`ValidationError` (field: `card.number`)	Número com menos de 13 dígitos
`ValidationError` (field: `card.cvv`)	CVV com menos de 3 dígitos
`ValidationError` (field: `card.holderName`)	Nome do portador vazio
`AuthenticationError`	Chave pública inválida ou inativa

Usando o token na cobrança

Após tokenizar, envie o token ao seu backend e use-o no campo payment_details.token da cobrança:

const response = await fetch('https://api.accithus.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 15000,
    payment_method: 'credit_card',
    product_type: 'digital',
    customer: {
      name: 'Comprador Teste',
      email: '[email protected]',
      tax_id: '12345678900',
      phone: '11999998888',
      type: 'individual',
    },
    items: [
      { name: 'Pedido', quantity: 1, unit_price: 15000, tangible: false },
    ],
    payment_details: {
      token: result.token,
      installments: 1,
    },
  }),
});

curl -X POST https://api.accithus.com/v1/charges \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "payment_method": "credit_card",
    "product_type": "digital",
    "customer": {
      "name": "Comprador Teste",
      "email": "[email protected]",
      "tax_id": "12345678900",
      "phone": "11999998888",
      "type": "individual"
    },
    "items": [
      { "name": "Pedido", "quantity": 1, "unit_price": 15000, "tangible": false }
    ],
    "payment_details": {
      "token": "tok_abc123...",
      "installments": 1
    }
  }'

Começando

Cobranças

Submerchants

Financeiro

Configuração

SDK de Segurança

Webhooks

Como funciona

Uso básico

Parâmetros do cartão

Retorno (`TokenizeResult`)

Deduplicação

Detecção de bandeira

Tratamento de erros

Usando o token na cobrança

​Como funciona

​Uso básico

​Parâmetros do cartão

​Retorno (TokenizeResult)

​Deduplicação

​Detecção de bandeira

​Tratamento de erros

​Usando o token na cobrança

Como funciona

Uso básico

Parâmetros do cartão

Retorno (`TokenizeResult`)

Deduplicação

Detecção de bandeira

Tratamento de erros

Usando o token na cobrança