Skip to main content

Visão Geral

O fluxo completo da Uvvipague permite que o parceiro consulte débitos veiculares e realize o pagamento de forma integrada, com proteção antifraude incluída.
Antifraude Integrado: Todos os pagamentos passam pelo sistema antifraude da Uvvipague, garantindo segurança nas transações.

Fluxo de Integração

O processo completo é dividido em duas etapas principais:
1

Etapa 1: Consulta de Débitos

Consulte os dados do veículo e seus débitos pendentes
2

Etapa 2: Pagamento e Liquidação

Tokenize o cartão, gere o checkout e efetue o pagamento

Etapa 1: Consulta de Débitos

Nesta etapa, você consulta as informações do veículo e seus débitos pendentes.

1.1 Enriquecer Dados do Veículo (Opcional)

Primeiro, você pode enriquecer os dados do veículo usando apenas a placa:
string
required
Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul)
string
Sigla do estado (opcional, mas recomendado para otimizar a consulta)
Resposta:
Este passo é opcional. Você pode pular direto para a consulta de débitos se já tiver os dados do veículo (placa, RENAVAM e CPF/CNPJ do proprietário).

1.2 Consultar Débitos do Veículo

Consulte os débitos pendentes do veículo:
Resposta:

Etapa 2: Pagamento e Liquidação

Após consultar os débitos, você pode processar o pagamento.

2.1 Tokenizar Cartão de Crédito

Antes de processar o pagamento, tokenize os dados do cartão para maior segurança:
string
required
Número do cartão de crédito (apenas números)
string
required
Nome do titular do cartão (como impresso no cartão)
string
required
Data de validade no formato MM/AAAA ou MM/AA
string
required
Código de segurança (CVV - 3 ou 4 dígitos)
Resposta:
Segurança: Nunca armazene dados completos do cartão. Sempre use o token gerado para processar pagamentos.

2.2 Simular Parcelas (Opcional)

Antes de criar o checkout, você pode simular as opções de parcelamento disponíveis:
number
required
Valor total a ser parcelado em reais
string
required
Método de pagamento: credit_card
Resposta:
Importante: A simulação mostra todas as opções de parcelamento disponíveis com os valores exatos de juros. Use essas informações para apresentar as opções ao usuário antes de processar o pagamento.
Atenção: Todos os pagamentos possuem juros aplicados, incluindo pagamento à vista (1x) e PIX. Sempre apresente o valor total ao usuário de forma transparente.

2.3 Gerar Checkout

Crie um checkout com os débitos que serão pagos:
array
required
Lista de IDs dos débitos a serem pagos
object
required
Dados do cliente pagador
object
required
Dados do veículo
Resposta:

2.4 Efetuar Pagamento

Realize o pagamento usando cartão de crédito ou PIX:
string
required
ID do checkout gerado
string
required
Método de pagamento: credit_card
string
required
Token do cartão gerado na tokenização
number
required
Número de parcelas (1 para pagamento à vista)
Resposta Cartão de Crédito:

Status de Pagamento

Status Imediatos (Cartão de Crédito)

Ao processar pagamento com cartão, os seguintes status são retornados imediatamente:

paid

Pago: Transação aprovada e processada com sucesso

in_analysis

Em Análise: Transação em análise pelo antifraude

refused

Recusado: Transação recusada pela operadora ou antifraude

processing

Processando: Transação sendo processada

awaiting_payment

Aguardando Pagamento: Aguardando confirmação (comum em PIX)

Todos os Status Possíveis

Para ver a lista completa de status de transações, incluindo status de liquidação, consulte a documentação de status.

2.5 Consultar Status do Pedido

Após o pagamento, você pode consultar o status de liquidação:
string
required
ID do pagamento a ser consultado
Resposta:

Resumo dos Endpoints

Enriquecer Veículo

GET /api/v1/vehicle/enrichment/{placa}Enriquece dados do veículo pela placa (opcional)

Consultar Débitos

POST /uvvi/v1/debtsConsulta débitos pendentes do veículo

Tokenizar Cartão

POST /uvvi/v1/card-tokenGera token seguro do cartão de crédito

Simular Parcelas

POST /uvvi/v1/installmentsSimula opções de parcelamento disponíveis

Gerar Checkout

POST /uvvi/v1/checkoutCria checkout com débitos selecionados

Efetuar Pagamento

POST /uvvi/v1/paymentProcessa pagamento via cartão ou PIX

Consultar Pagamento

POST /uvvi/v1/payment/statusVerifica status e liquidação do pagamento

Fluxo Completo - Diagrama

Exemplo Completo de Integração

Processamento Síncrono vs Assíncrono

Importante sobre Timeouts: A API pode retornar respostas de forma síncrona na maioria dos casos, porém, em situações de alta carga ou lentidão nos sistemas dos Detrans, você pode receber um timeout na resposta síncrona.

Comportamento da API

A API Uvvipague opera em dois modos:
Cenário Ideal: Quando os sistemas estão operando normalmente, você recebe a resposta imediatamente na mesma requisição.
Status retornados sincronamente:
  • paid - Pagamento aprovado
  • refused - Pagamento recusado
  • in_analysis - Em análise
  • processing - Processando

Fluxo Recomendado

1

Envie a Requisição

Faça a requisição de pagamento normalmente com timeout adequado de 30-60 segundos.
2

Trate a Resposta

Se receber resposta síncrona, processe o status imediatamente.
3

Em Caso de Timeout

Se ocorrer timeout, não considere como erro. Aguarde o webhook.
4

Receba o Webhook

O webhook será enviado com o status final do pagamento quando o processamento for concluído.
5

Fallback Manual

Se não receber o webhook após as retentativas, consulte manualmente o status usando o endpoint de consulta.

Exemplo de Implementação

Boas Práticas

Configure Timeout Adequado

Use timeout de 30-60 segundos para dar tempo de processamento sem travar sua aplicação.

Sempre Configure Webhook

Configure webhooks mesmo que receba resposta síncrona. É seu fallback em caso de timeout.

Use externalId

Sempre envie externalId único para correlacionar requisições com webhooks.

Status Intermediário

Salve status intermediário “awaiting_webhook” quando ocorrer timeout para tracking.
Resumo: Trate a API como síncrona por padrão, mas esteja preparado para processamento assíncrono via webhook em caso de timeout. Configure webhooks como parte essencial da integração.

Próximos Passos

Webhooks

Configure webhooks para receber notificações

Autenticação

Configure sua API Key para começar

ENUMs e Tipos

Consulte todos os status e tipos possíveis

Consulta de Débitos

Entenda o fluxo de consulta de débitos