Skip to main content
POST
/
uvvi
/
v1
/
checkout
Criar Checkout
curl --request POST \
  --url https://api.uvvipague.com.br/uvvi/v1/checkout \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "debts": [
    {
      "id": "debt_123abc",
      "amount": 206.86
    }
  ],
  "customer": {
    "name": "João da Silva",
    "email": "joao@example.com",
    "cpfCnpj": "12345678900"
  },
  "externalId": "550e8400-e29b-41d4-a716-446655440000"
}
'
{
  "success": true,
  "data": {
    "checkoutId": "chk_abc123xyz",
    "totalAmount": 1302.86,
    "expiresAt": "2024-01-15T23:59:59Z"
  }
}

Descrição

Cria um checkout para pagamento de débitos veiculares. O checkout agrupa os débitos selecionados e gera um identificador único que será usado no processamento do pagamento.
Validade: O checkout é válido por 24 horas após a criação. Após este período, será necessário criar um novo checkout.

Fluxo de Uso

1

Consultar Débitos

Primeiro, consulte os débitos do veículo via POST /uvvi/v1/debts.
2

Selecionar Débitos

Permita que o cliente escolha quais débitos deseja pagar.
3

Criar Checkout

Crie o checkout com os débitos selecionados usando este endpoint.
4

Processar Pagamento

Use o checkoutId retornado para processar o pagamento.

Seleção de Débitos

Débitos Obrigatórios

Alguns débitos são obrigatórios e devem ser pagos em conjunto:
  • IPVA: Deve ser pago junto com o licenciamento
  • Licenciamento: Pode ter débitos dependentes
  • Multas: Algumas multas são pré-requisitos para o licenciamento
Atenção aos Dependentes: Consulte a documentação de débitos dependentes para entender as regras de dependência entre débitos.

Validação de Débitos

A API valida automaticamente:
  • Se todos os débitos obrigatórios estão incluídos
  • Se os débitos pertencem ao mesmo veículo
  • Se os débitos ainda estão válidos e não foram pagos
  • Se os valores correspondem aos débitos consultados

Campo externalId

Rastreabilidade: Use o campo externalId (UUID) para rastrear o checkout no seu sistema e correlacionar com webhooks futuros.
const externalId = crypto.randomUUID(); // Gera UUID v4

const checkout = await criarCheckout({
  debts: debitosSelecionados,
  customer: dadosCliente,
  externalId: externalId // Use o mesmo ID para rastreamento
});

Dados do Cliente

Os dados do cliente são necessários para:
  • Emissão de nota fiscal
  • Envio de comprovantes por e-mail
  • Validação antifraude
  • Comunicação sobre o status do pagamento

Campos Obrigatórios

  • name: Nome completo do cliente
  • email: E-mail válido para envio de comprovantes
  • cpfCnpj: CPF ou CNPJ (apenas números)
O CPF/CNPJ informado deve corresponder ao proprietário do veículo ou pessoa autorizada a pagar os débitos.

Estrutura do Checkout

Débitos

Cada débito deve conter:
{
  "id": "debt_123abc",
  "amount": 206.86
}
  • id: Identificador do débito retornado na consulta
  • amount: Valor do débito (para validação)

Cliente

{
  "name": "João da Silva",
  "email": "joao@example.com",
  "cpfCnpj": "12345678900"
}

Exemplo de Uso Completo

// 1. Após consultar débitos e receber via webhook
const debitos = webhookData.debts;

// 2. Cliente seleciona quais débitos pagar
const debitosSelecionados = debitos.filter(d => 
  clienteEscolheu.includes(d.id)
);

// 3. Criar checkout
const response = await fetch('https://api.uvvipague.com.br/uvvi/v1/checkout', {
  method: 'POST',
  headers: {
    'x-api-key': 'sua-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    debts: debitosSelecionados.map(d => ({
      id: d.id,
      amount: d.amount
    })),
    customer: {
      name: 'João da Silva',
      email: 'joao@example.com',
      cpfCnpj: '12345678900'
    },
    externalId: crypto.randomUUID()
  })
});

const { data } = await response.json();

// 4. Usar checkoutId no pagamento
console.log(`Checkout criado: ${data.checkoutId}`);
console.log(`Total: R$ ${data.totalAmount}`);
console.log(`Expira em: ${data.expiresAt}`);

Resposta do Checkout

A resposta contém:
  • checkoutId: ID único do checkout para usar no pagamento
  • totalAmount: Valor total de todos os débitos selecionados
  • expiresAt: Data/hora de expiração do checkout (24 horas)
{
  "success": true,
  "data": {
    "checkoutId": "chk_abc123xyz",
    "totalAmount": 1302.86,
    "expiresAt": "2024-01-16T14:30:00Z"
  }
}

Expiração do Checkout

Checkout Expirado: Se tentar processar um pagamento com um checkout expirado, você receberá um erro 422. Neste caso, crie um novo checkout.

Renovar Checkout

Se o checkout expirar antes do pagamento:
// Verificar se checkout expirou
const agora = new Date();
const expiracao = new Date(checkout.expiresAt);

if (agora > expiracao) {
  console.log('Checkout expirado, criando novo...');
  const novoCheckout = await criarCheckout(mesmosDebitos);
}

Códigos de Resposta HTTP

200 - Sucesso

Checkout criado com sucesso. Use o checkoutId para processar o pagamento.

400 - Bad Request

Dados inválidos na requisição. Possíveis motivos:
  • Débitos inválidos ou não encontrados
  • Valores não correspondem aos débitos
  • Dados do cliente inválidos (CPF/CNPJ, e-mail)
  • Débitos obrigatórios faltando

422 - Unprocessable Entity

Dados válidos mas não podem ser processados:
  • Débitos já foram pagos
  • Débitos de veículos diferentes
  • Dependências de débitos não satisfeitas
  • Checkout duplicado (mesmo externalId)

Validação de Dependências

Antes de criar o checkout, valide as dependências:
function validarDependencias(debitos, debitosSelecionados) {
  for (const debito of debitosSelecionados) {
    if (debito.dependencies && debito.dependencies.length > 0) {
      const dependenciasFaltando = debito.dependencies.filter(depId => 
        !debitosSelecionados.find(d => d.id === depId)
      );
      
      if (dependenciasFaltando.length > 0) {
        throw new Error(
          `Débito ${debito.description} requer: ${dependenciasFaltando.join(', ')}`
        );
      }
    }
  }
  return true;
}

Interface de Usuário

Boas Práticas

Exiba o valor total antes de criar o checkout:
<div className="checkout-summary">
  <h3>Resumo do Pagamento</h3>
  <ul>
    {debitosSelecionados.map(d => (
      <li key={d.id}>
        {d.description}: R$ {d.amount.toFixed(2)}
      </li>
    ))}
  </ul>
  <strong>Total: R$ {total.toFixed(2)}</strong>
</div>
Marque visualmente débitos que devem ser pagos juntos:
{debito.required && (
  <Badge color="red">Obrigatório</Badge>
)}
Valide no frontend antes de criar o checkout:
if (!validarEmail(customer.email)) {
  alert('E-mail inválido');
  return;
}

if (!validarCPF(customer.cpfCnpj)) {
  alert('CPF/CNPJ inválido');
  return;
}
Informe ao cliente sobre a validade do checkout:
<Alert>
  Este checkout expira em 24 horas.
  Conclua o pagamento antes de {formatarData(expiresAt)}.
</Alert>

Próximos Passos

Após criar o checkout:

Suporte

Dúvidas sobre Checkout?

Entre em contato para esclarecer dúvidas sobre criação de checkout e validação de débitos.

Authorizations

x-api-key
string
header
required

API Key fornecida no painel administrativo da Uvvipague

Body

application/json
debts
object[]
required
customer
object
required
externalId
string
Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

Checkout criado com sucesso

success
boolean
Example:

true

data
object