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"
}
'

import requests

url = "https://api.uvvipague.com.br/uvvi/v1/checkout"

payload = {
    "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"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.uvvipague.com.br/uvvi/v1/checkout', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.uvvipague.com.br/uvvi/v1/checkout",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.uvvipague.com.br/uvvi/v1/checkout"

	payload := strings.NewReader("{\n  \"debts\": [\n    {\n      \"id\": \"debt_123abc\",\n      \"amount\": 206.86\n    }\n  ],\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@example.com\",\n    \"cpfCnpj\": \"12345678900\"\n  },\n  \"externalId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.uvvipague.com.br/uvvi/v1/checkout")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"debts\": [\n    {\n      \"id\": \"debt_123abc\",\n      \"amount\": 206.86\n    }\n  ],\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@example.com\",\n    \"cpfCnpj\": \"12345678900\"\n  },\n  \"externalId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.uvvipague.com.br/uvvi/v1/checkout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"debts\": [\n    {\n      \"id\": \"debt_123abc\",\n      \"amount\": 206.86\n    }\n  ],\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@example.com\",\n    \"cpfCnpj\": \"12345678900\"\n  },\n  \"externalId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "checkoutId": "chk_abc123xyz",
    "totalAmount": 1302.86,
    "expiresAt": "2024-01-15T23:59:59Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Parâmetros inválidos na requisição",
    "details": {}
  }
}

POST

uvvi

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"
}
'

import requests

url = "https://api.uvvipague.com.br/uvvi/v1/checkout"

payload = {
    "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"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.uvvipague.com.br/uvvi/v1/checkout', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.uvvipague.com.br/uvvi/v1/checkout",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.uvvipague.com.br/uvvi/v1/checkout"

	payload := strings.NewReader("{\n  \"debts\": [\n    {\n      \"id\": \"debt_123abc\",\n      \"amount\": 206.86\n    }\n  ],\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@example.com\",\n    \"cpfCnpj\": \"12345678900\"\n  },\n  \"externalId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.uvvipague.com.br/uvvi/v1/checkout")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"debts\": [\n    {\n      \"id\": \"debt_123abc\",\n      \"amount\": 206.86\n    }\n  ],\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@example.com\",\n    \"cpfCnpj\": \"12345678900\"\n  },\n  \"externalId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.uvvipague.com.br/uvvi/v1/checkout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"debts\": [\n    {\n      \"id\": \"debt_123abc\",\n      \"amount\": 206.86\n    }\n  ],\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@example.com\",\n    \"cpfCnpj\": \"12345678900\"\n  },\n  \"externalId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "checkoutId": "chk_abc123xyz",
    "totalAmount": 1302.86,
    "expiresAt": "2024-01-15T23:59:59Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Parâmetros inválidos na requisição",
    "details": {}
  }
}

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

Consultar Débitos

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

Selecionar Débitos

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

Criar Checkout

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

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

Mostre o Total Claramente

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>

Indique Débitos Obrigatórios

Marque visualmente débitos que devem ser pagos juntos:

{debito.required && (
  <Badge color="red">Obrigatório</Badge>
)}

Valide Antes de Enviar

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;
}

Mostre Tempo de Expiração

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:

Tokenizar Cartão

Tokenize o cartão do cliente de forma segura

Simular Parcelas

Simule opções de parcelamento para o valor total

Processar Pagamento

Efetue o pagamento usando o checkoutId

Débitos Dependentes

Entenda as regras de dependência entre débitos

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

Show child attributes

customer

object

required

Show child attributes

externalId

string

Example:

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

Response

Checkout criado com sucesso

success

boolean

Example:

true

data

object

Show child attributes

Consultar Débitos Tokenizar Cartão

Documentação da API

Veículos

Débitos

Pagamentos

Webhooks

Criar Checkout

Descrição

Fluxo de Uso

Seleção de Débitos

Débitos Obrigatórios

Validação de Débitos

Campo externalId

Dados do Cliente

Campos Obrigatórios

Estrutura do Checkout

Débitos

Cliente

Exemplo de Uso Completo

Resposta do Checkout

Expiração do Checkout

Renovar Checkout

Códigos de Resposta HTTP

200 - Sucesso

400 - Bad Request

422 - Unprocessable Entity

Validação de Dependências

Interface de Usuário

Boas Práticas

Próximos Passos

Tokenizar Cartão

Simular Parcelas

Processar Pagamento

Débitos Dependentes

Suporte

Dúvidas sobre Checkout?

Authorizations

Body

Response

​Descrição

​Fluxo de Uso

​Seleção de Débitos

​Débitos Obrigatórios

​Validação de Débitos

​Campo externalId

​Dados do Cliente

​Campos Obrigatórios

​Estrutura do Checkout

​Débitos

​Cliente

​Exemplo de Uso Completo

​Resposta do Checkout

​Expiração do Checkout

​Renovar Checkout

​Códigos de Resposta HTTP

​200 - Sucesso

​400 - Bad Request

​422 - Unprocessable Entity

​Validação de Dependências

​Interface de Usuário

​Boas Práticas

​Próximos Passos

Tokenizar Cartão

Simular Parcelas

Processar Pagamento

Débitos Dependentes

​Suporte

Dúvidas sobre Checkout?

Authorizations

Body

Response

Descrição

Fluxo de Uso

Seleção de Débitos

Débitos Obrigatórios

Validação de Débitos

Campo externalId

Dados do Cliente

Campos Obrigatórios

Estrutura do Checkout

Débitos

Cliente

Exemplo de Uso Completo

Resposta do Checkout

Expiração do Checkout

Renovar Checkout

Códigos de Resposta HTTP

200 - Sucesso

400 - Bad Request

422 - Unprocessable Entity

Validação de Dependências

Interface de Usuário

Boas Práticas

Próximos Passos

Suporte