> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavropay.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral

> Base URL, autenticação, formato das respostas e primeiros passos na API KavroPay

A **KavroPay** é uma infraestrutura moderna de pagamentos instantâneos PIX projetada para desenvolvedores, plataformas SaaS, e-commerces e criadores de conteúdo que necessitam de processamento de altíssima velocidade, liquidação em tempo real e redundância bancária automática.

> [card] [Criar Cobrança PIX](https://docs.kavropay.online/cobrancas-pix/criar-cobranca.md)
>
> Gere QR Code dinâmico e código Copia e Cola instantâneo em menos de 800ms.

> [card] [Saques PIX](https://docs.kavropay.online/saques-pix/solicitar-saque.md)
>
> Automatize transferências para qualquer chave PIX (CPF, CNPJ, e-mail, telefone, chave aleatória).

> [card] [Webhooks em Tempo Real](https://docs.kavropay.online/webhooks/visao-geral.md)
>
> Receba notificações instantâneas no seu servidor assim que o PIX for pago.

> [card] [Validação de Assinatura HMAC](https://docs.kavropay.online/webhooks/validacao-hmac.md)
>
> Proteja sua integração validando a assinatura criptográfica dos webhooks.

***

## Informações Gerais da API

| Propriedade | Valor de Produção |
| :- | :- |
| **Base URL Oficial** | `https://api.kavropay.com.br/v1` |
| **Base URL de Transição** | `https://api.kavropay.online/v1` (compatibilidade mantida durante migração) |
| **Ambiente de Produção** | `https://api.kavropay.com.br` (Chaves com prefixo `kvk_live_...`) |
| **Ambiente de Sandbox** | `https://api.kavropay.com.br` (Chaves com prefixo `kvk_test_...`) |
| **Protocolo** | RESTful JSON sobre HTTPS / TLS 1.3 |
| **Autenticação** | Header `Authorization: Bearer kvk_live_...` ou `x-api-key: kvk_live_...` |
| **Idempotência** | Suporte nativo via header `Idempotency-Key` (TTL 24h) |
| **Rate Limit** | 120 requisições por minuto por chave de API |
| **Tempo de Resposta** | Médio sub-segundo (\< 800ms) com roteamento inteligente |

***

## Quickstart (Primeira Cobrança em 2 Minutos)

Para gerar uma cobrança PIX imediata, envie uma requisição `POST /v1/charges` autenticada:

```bash cURL theme={null}
curl -X POST https://api.kavropay.com.br/v1/charges \
  -H "Authorization: Bearer kvk_live_SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ped_1001_tentativa1" \
  -d '{
    "amount": "10.00",
    "description": "Pedido #1001",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "12345678909"
    }
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api.kavropay.com.br/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer kvk_live_SEU_TOKEN_AQUI',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ped_1001_tentativa1'
  },
  body: JSON.stringify({
    amount: "10.00", // ou amountCents: 1000
    description: "Pedido #1001",
    customer: {
      name: "João Silva",
      email: "joao@email.com",
      document: "12345678909"
    }
  })
});

const data = await response.json();
console.log('ID da Cobrança:', data.id);
console.log('PIX Copia e Cola:', data.pix_copy_paste);
```

```python Python theme={null}
import requests

url = "https://api.kavropay.com.br/v1/charges"
headers = {
    "Authorization": "Bearer kvk_live_SEU_TOKEN_AQUI",
    "Content-Type": "application/json",
    "Idempotency-Key": "ped_1001_tentativa1"
}
payload = {
    "amount": "10.00",
    "description": "Pedido #1001",
    "customer": {
        "name": "João Silva",
        "email": "joao@email.com",
        "document": "12345678909"
    }
}

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

```php PHP theme={null}
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.kavropay.com.br/v1/charges",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer kvk_live_SEU_TOKEN_AQUI",
        "Content-Type: application/json",
        "Idempotency-Key: ped_1001_tentativa1"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => "10.00",
        "description" => "Pedido #1001",
        "customer" => [
            "name" => "João Silva",
            "email" => "joao@email.com",
            "document" => "12345678909"
        ]
    ]),
]);

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

$data = json_decode($response, true);
echo "PIX Copia e Cola: " . $data["pix_copy_paste"];
```

> [!TIP]
>
> **Exemplo de Resposta (HTTP 201 Created)**
>
> ```json theme={null}
> {
>   "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
>   "amount": 10.00,
>   "fee": 0.99,
>   "net": 9.01,
>   "status": "waiting_payment",
>   "environment": "live",
>   "livemode": true,
>   "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY9B1DEB4D3B7D4BAD9BDD2B520400005303986540510.005802BR5913KavroPay6009SAO PAULO62070503***6304D1A9",
>   "qr_code_base64": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0MS...",
>   "externalId": "ped_1001",
>   "expires_at": "2026-10-15T22:00:00.000Z",
>   "created_at": "2026-10-15T21:30:00.000Z"
> }
> ```

***

## Próximos Passos

Explore os tópicos abaixo para dominar todos os recursos da API KavroPay:

> [card] [Autenticação & Chaves](https://docs.kavropay.online/autenticacao.md)
>
> Saiba como gerar e configurar suas chaves `kvk_live_` e `kvk_test_`.

> [card] [Formato de Valores](https://docs.kavropay.online/parametros.md)
>
> Veja como enviar valores em Reais (string decimal) ou centavos inteiros.

> [card] [Status Unificado](https://docs.kavropay.online/status-unificado.md)
>
> Consulte qualquer transação em tempo real pelo endpoint leve de status.

> [card] [Central de Erros & Status](https://docs.kavropay.online/erros-status.md)
>
> Tabela completa de códigos HTTP, status de transação e eventos do sistema.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.