Skip to main content
POST
/
uvvi
/
v1
/
card-token
Tokenizar Cartão
curl --request POST \
  --url https://api.uvvipague.com.br/uvvi/v1/card-token \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "cardNumber": "4111111111111111",
  "cardholderName": "JOAO DA SILVA",
  "expirationDate": "12/2030",
  "cvv": "123"
}
'
{
  "success": true,
  "data": {
    "token": "tok_abc123xyz789",
    "brand": "visa",
    "lastFourDigits": "1111",
    "expiresAt": "2024-01-16T14:30:00Z"
  }
}

​
Descrição

Tokeniza os dados de um cartão de crédito para uso seguro em transações futuras. Este endpoint converte dados sensíveis do cartão em um token seguro que pode ser utilizado no endpoint de pagamento.
Segurança PCI-DSS: A tokenização garante que você nunca precise armazenar dados sensíveis de cartão no seu sistema, mantendo conformidade com PCI-DSS.

​
Fluxo de Tokenização

1

Coletar Dados do Cartão

Obtenha os dados do cartão do cliente de forma segura (preferencialmente usando um iframe ou SDK).
2

Enviar para Tokenização

Envie os dados para este endpoint para gerar um token seguro.
3

Armazenar Token

Armazene apenas o token retornado (nunca os dados originais do cartão).
4

Usar no Pagamento

Utilize o token no endpoint /uvvi/v1/payment para processar o pagamento.

​
Campos do Cartão

​
Número do Cartão

  • Formato: 13 a 19 dígitos
  • Validação: Algoritmo de Luhn
  • Bandeiras aceitas: Visa, Mastercard, Elo, Amex, Hipercard

​
Data de Validade

  • Formato: MM/AAAA ou MM/AA
  • Validação: Deve ser uma data futura

​
CVV

  • Formato: 3 ou 4 dígitos
  • Nota: Nunca é armazenado, apenas validado durante a transação

​
Nome do Titular

  • Formato: Texto, exatamente como impresso no cartão
  • Validação: Mínimo 3 caracteres

​
Validade do Token

Expiração: Tokens de cartão são válidos por 24 horas após a criação. Após este período, será necessário tokenizar novamente.

​
Segurança

​
Boas Práticas

  • Não salve o número completo do cartão
  • Não salve o CVV em hipótese alguma
  • Armazene apenas o token retornado pela API
  • Sempre use conexões HTTPS
  • Valide certificados SSL
  • Não transmita dados de cartão em URLs ou logs
  • Valide o formato do cartão antes de enviar
  • Use bibliotecas como card-validator ou creditcards
  • Forneça feedback imediato ao usuário
  • Use tokenização para reduzir escopo PCI
  • Implemente logs de auditoria
  • Monitore tentativas de fraude

​
Exemplo de Validação Client-Side

// Exemplo usando a biblioteca card-validator
import cardValidator from 'card-validator';

function validateCard(cardNumber, cvv, expiryDate) {
  const numberValidation = cardValidator.number(cardNumber);
  const cvvValidation = cardValidator.cvv(cvv);
  const expiryValidation = cardValidator.expirationDate(expiryDate);
  
  if (!numberValidation.isValid) {
    return { valid: false, error: 'Número do cartão inválido' };
  }
  
  if (!cvvValidation.isValid) {
    return { valid: false, error: 'CVV inválido' };
  }
  
  if (!expiryValidation.isValid) {
    return { valid: false, error: 'Data de validade inválida' };
  }
  
  return { valid: true, brand: numberValidation.card.type };
}

​
Bandeiras Aceitas

Visa

Cartões Visa

Mastercard

Cartões Mastercard

Elo

Cartões Elo

American Express

Cartões Amex

Hipercard

Cartões Hipercard

Diners

Cartões Diners

​
Códigos de Resposta HTTP

​
200 - Sucesso

Cartão tokenizado com sucesso. Use o token retornado para processar pagamentos.

​
400 - Bad Request

Dados do cartão inválidos. Possíveis motivos:
  • Número de cartão inválido (falha no algoritmo de Luhn)
  • Data de validade expirada ou inválida
  • CVV com formato incorreto
  • Nome do titular muito curto

​
422 - Unprocessable Entity

Cartão válido mas não pode ser tokenizado:
  • Cartão bloqueado
  • Bandeira não aceita
  • Cartão de teste em produção

​
Testando Tokenização

​
Cartões de Teste (Sandbox)

Use estes cartões no ambiente sandbox:
BandeiraNúmeroCVVResultado
Visa4111111111111111123Aprovado
Mastercard5555555555554444123Aprovado
Elo6362970000457013123Aprovado
Visa4000000000000002123Recusado
Mastercard5555555555554445123Erro de validação
Data de Validade: Use qualquer data futura (ex: 12/2030) para testes.

​
Próximos Passos

Após tokenizar o cartão:
  1. Simular Parcelas - Calcule opções de parcelamento
  2. Processar Pagamento - Efetue o pagamento usando o token

​
Suporte

Precisa de Ajuda?

Entre em contato com nosso suporte técnico para questões sobre tokenização e segurança.

Authorizations

​
x-api-key
string
header
required

API Key fornecida no painel administrativo da Uvvipague

Body

application/json
​
cardNumber
string
required

Número do cartão (13 a 19 dígitos)

Example:

"4111111111111111"

​
cardholderName
string
required

Nome do titular como impresso no cartão

Example:

"JOAO DA SILVA"

​
expirationDate
string
required

Data de validade no formato MM/AAAA ou MM/AA

Example:

"12/2030"

​
cvv
string
required

Código de segurança (3 ou 4 dígitos)

Example:

"123"

Response

Cartão tokenizado com sucesso

​
success
boolean
Example:

true

​
data
object