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)
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: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)
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_cardImportante: 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.
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
2.4 Efetuar Pagamento
Realize o pagamento usando cartão de crédito ou PIX:- Cartão de Crédito
- PIX
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
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ículoTokenizar Cartão
POST /uvvi/v1/card-tokenGera token seguro do cartão de créditoSimular Parcelas
POST /uvvi/v1/installmentsSimula opções de parcelamento disponíveisGerar Checkout
POST /uvvi/v1/checkoutCria checkout com débitos selecionadosEfetuar Pagamento
POST /uvvi/v1/paymentProcessa pagamento via cartão ou PIXConsultar Pagamento
POST /uvvi/v1/payment/statusVerifica status e liquidação do pagamentoFluxo Completo - Diagrama
Exemplo Completo de Integração
Processamento Síncrono vs Assíncrono
Comportamento da API
A API Uvvipague opera em dois modos:- Resposta Síncrona (Normal)
- Resposta Assíncrona (Timeout)
Cenário Ideal: Quando os sistemas estão operando normalmente, você recebe a resposta imediatamente na mesma requisição.Status retornados sincronamente:
paid- Pagamento aprovadorefused- Pagamento recusadoin_analysis- Em análiseprocessing- 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