> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipague.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Tokenizar Cartão
> Tokeniza os dados de um cartão de crédito para uso seguro em transações, garantindo conformidade PCI-DSS
## 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
Obtenha os dados do cartão do cliente de forma segura (preferencialmente usando um iframe ou SDK).
Envie os dados para este endpoint para gerar um token seguro.
Armazene apenas o token retornado (nunca os dados originais do cartão).
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
```javascript theme={null}
// 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
Cartões Visa
Cartões Mastercard
Cartões Elo
Cartões Amex
Cartões Hipercard
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:
| Bandeira | Número | CVV | Resultado |
| ---------- | ------------------ | ----- | ----------------- |
| Visa | `4111111111111111` | `123` | Aprovado |
| Mastercard | `5555555555554444` | `123` | Aprovado |
| Elo | `6362970000457013` | `123` | Aprovado |
| Visa | `4000000000000002` | `123` | Recusado |
| Mastercard | `5555555555554445` | `123` | Erro 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](/api-reference/endpoint/installments) - Calcule opções de parcelamento
2. [Processar Pagamento](/api-reference/endpoint/payment) - Efetue o pagamento usando o token
## Suporte
Entre em contato com nosso suporte técnico para questões sobre tokenização e segurança.
## OpenAPI
````yaml POST /uvvi/v1/card-token
openapi: 3.1.0
info:
title: Uvvipague API
description: >-
API completa para consulta e pagamento de débitos veiculares em todo o
Brasil
version: 1.0.0
contact:
name: Suporte Uvvipague
email: suporte@uvvipague.com.br
url: https://uvvipague.com.br
servers:
- url: https://api.uvvipague.com.br
description: Servidor de Produção
- url: https://api-sandbox.uvvipague.com.br
description: Servidor de Homologação/Sandbox
security:
- apiKey: []
tags:
- name: Veículos
description: Endpoints para consulta e enriquecimento de informações de veículos
- name: Débitos
description: Endpoints para consulta de débitos veiculares
- name: Pagamentos
description: Endpoints para processamento de pagamentos
- name: Webhooks
description: Endpoints para configuração e gerenciamento de webhooks
paths:
/uvvi/v1/card-token:
post:
tags:
- Pagamentos
summary: Tokenizar Cartão
description: >-
Tokeniza os dados de um cartão de crédito para uso seguro em transações,
garantindo conformidade PCI-DSS
operationId: tokenizeCard
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardTokenRequest'
responses:
'200':
description: Cartão tokenizado com sucesso
content:
application/json:
schema:
$ref: '#/components/schemas/CardTokenResponse'
'400':
description: Dados do cartão inválidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Cartão válido mas não pode ser tokenizado
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
CardTokenRequest:
type: object
required:
- cardNumber
- cardholderName
- expirationDate
- cvv
properties:
cardNumber:
type: string
description: Número do cartão (13 a 19 dígitos)
example: '4111111111111111'
cardholderName:
type: string
description: Nome do titular como impresso no cartão
example: JOAO DA SILVA
expirationDate:
type: string
description: Data de validade no formato MM/AAAA ou MM/AA
example: 12/2030
cvv:
type: string
description: Código de segurança (3 ou 4 dígitos)
example: '123'
CardTokenResponse:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
token:
type: string
description: Token do cartão para uso em transações
example: tok_abc123xyz789
brand:
type: string
description: Bandeira do cartão
enum:
- visa
- mastercard
- elo
- amex
- hipercard
- diners
example: visa
lastFourDigits:
type: string
description: Últimos 4 dígitos do cartão
example: '1111'
expiresAt:
type: string
format: date-time
description: Data de expiração do token (24 horas)
example: '2024-01-16T14:30:00Z'
Error:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
enum:
- INVALID_REQUEST
- UNAUTHORIZED
- NOT_FOUND
- VALIDATION_ERROR
- RATE_LIMIT_EXCEEDED
- SERVICE_UNAVAILABLE
example: INVALID_REQUEST
description: Código do erro
message:
type: string
example: Parâmetros inválidos na requisição
details:
type: object
description: Detalhes adicionais sobre o erro
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key fornecida no painel administrativo da Uvvipague
````