Substitua dados sensíveis do cartão por um token seguro antes de enviar ao seu backend.
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 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.
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"| 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). |
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. |
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:
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 |
import { ValidationError, ApiError } from '@worldfy/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 |
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.worldfypayments.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: 'comprador@email.com',
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.worldfypayments.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": "comprador@email.com",
"tax_id": "12345678900",
"phone": "11999998888",
"type": "individual"
},
"items": [
{ "name": "Pedido", "quantity": 1, "unit_price": 15000, "tangible": false }
],
"payment_details": {
"token": "tok_abc123...",
"installments": 1
}
}'