Autenticação & Cabeçalhos HTTP

A API da KavroPay opera exclusivamente sob HTTPS / TLS 1.3 e exige autenticação em todas as requisições privadas através de chaves de API geradas no painel.

Você pode gerar suas credenciais diretamente no Dashboard KavroPay em Configurações > Chaves de API. Mantenha suas chaves privadas em sigilo e nunca as exponha em código client-side (frontend) ou em repositórios públicos.

Modos de Autenticação

A KavroPay aceita autenticação via Bearer Token (padrão RFC 6750) no cabeçalho Authorization ou via cabeçalho direto x-api-key:

Authorization Bearer (Recomendado)
x-api-key Header

Authorization: Bearer kvk_live_sua_chave_secreta_aqui

x-api-key: kvk_live_sua_chave_secreta_aqui

Ambientes e Prefixos de Chaves

A KavroPay separa estritamente os ambientes de homologação e produção através dos prefixos oficiais das chaves:

Prefixo	Ambiente	Descrição
`kvk_live_...`	Produção	Movimenta saldo real, gera cobranças PIX registradas no Banco Central e liquida transferências financeiras reais.
`kvk_test_...`	Sandbox	Ambiente de testes seguro para homologação de fluxos, simulação de pagamentos e testes de integração sem movimentação financeira.

Identificação Segura do Ambiente

Tanto as respostas da API quanto os webhooks entregues incluem campos explícitos de identificação do ambiente:

"environment": "sandbox" ou "live"
"livemode": false (quando em testes) ou true (quando em produção)
Nos Webhooks: cabeçalho HTTP X-Kavro-Environment: sandbox ou live

Cabeçalhos HTTP Suportados

Ao realizar requisições para a API KavroPay, inclua os seguintes cabeçalhos:

Cabeçalho	Tipo	Obrigatório	Descrição / Exemplo
`Authorization`	string	Sim*	Token no formato `Bearer kvk_live_...` ou `Bearer kvk_test_...`. (*Obrigatório se não utilizar `x-api-key`).
`x-api-key`	string	Opcional	Alternativa direta para enviar a chave de API sem o prefixo `Bearer`.
`Content-Type`	string	Sim	Obrigatório em rotas `POST`, `PUT` e `PATCH`. Deve ser `application/json`.
`Idempotency-Key`	string	Recomendado	Chave exclusiva (UUID v4 ou ID de pedido) para evitar duplicidade de cobranças ou saques em caso de retry ou oscilação de rede. Também aceito como `x-idempotency-key`.

Testando sua Conexão

Execute uma chamada simples ao endpoint de saldo para verificar se sua chave está ativa e configurada corretamente:

curl -X GET https://api.kavropay.com.br/v1/balance \
  -H "Authorization: Bearer kvk_live_seu_token_aqui" \
  -H "Content-Type: application/json"

const res = await fetch('https://api.kavropay.com.br/v1/balance', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer kvk_live_seu_token_aqui',
    'Content-Type': 'application/json'
  }
});
const data = await res.json();
console.log('Saldo:', data);

import requests

url = "https://api.kavropay.com.br/v1/balance"
headers = {
    "Authorization": "Bearer kvk_live_seu_token_aqui",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.kavropay.com.br/v1/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer kvk_live_seu_token_aqui",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

Resposta de Sucesso (HTTP 200 OK)

{
  "available": 1500.50,
  "blocked": 0.00,
  "currency": "BRL"
}

Erros de Autenticação

Caso a chave esteja incorreta, ausente ou revogada, a API responderá com status 401 Unauthorized:

{
  "statusCode": 401,
  "message": "Invalid or revoked API Key",
  "error": "Unauthorized"
}

Boas práticas de segurança:

Armazene suas chaves em variáveis de ambiente (.env).
Nunca envie credenciais de produção (kvk_live_) para ambientes de homologação ou repositórios públicos.
Caso suspeite de vazamento de credenciais, revogue a chave imediatamente no painel e gere uma nova.

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Autenticação & Cabeçalhos HTTP

Modos de Autenticação

Ambientes e Prefixos de Chaves

Identificação Segura do Ambiente

Cabeçalhos HTTP Suportados

Testando sua Conexão

Resposta de Sucesso (HTTP 200 OK)

Erros de Autenticação