Tokenização
Substitua dados sensíveis do cartão por um token seguro antes de enviar ao seu backend.
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 SoarLabz 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',
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 '@soarlabz/security-sdk';
try {
const result = await client.tokenizer.tokenize({ card: { ... } });
} catch (error) {
if (error instanceof ValidationError
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.payhubrasil.com.br/v1/charges', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify