Visão Geral & Arquitetura
Conheça a infraestrutura de pagamentos instantâneos de alta performance da KavroPay.
https://api.kavropay.online/v1
A API REST da KavroPay foi desenvolvida com foco em ultra-baixa latência (< 20ms), alta resiliência e facilidade máxima de integração para e-commerces, plataformas SaaS, infoprodutores e gateways de pagamento.
Resolução PIX em < 100ms
Geração instantânea da chave Copia e Cola (EMV) e da imagem Base64 do QR Code para exibição direta no seu checkout.
Roteamento Inteligente & Failover
Balanceamento dinâmico entre adquirentes parceiras de primeira linha garantindo 99.8% de taxa de conversão.
Status Unificado Ultra-rápido
Verifique o status de qualquer cobrança ou saque através de um único endpoint leve com suporte a qualquer ID.
Valores Decimais Claros
Envio e retorno padrão em Reais (amount: 49.00 ou 0.49 para centavos).
Autenticação & Cabeçalhos HTTP
Padrões de segurança, formato de chaves de API e headers obrigatórios.
A API da KavroPay utiliza autenticação baseada em Tokens Bearer ou no header personalizado x-api-key. Todas as requisições devem trafegar sob HTTPS.
| Header | Tipo | Obrigatório | Descrição / Exemplo |
|---|---|---|---|
| Authorization | string | Sim | Token Bearer no formato Bearer sk_live_... ou Bearer sk_test_.... |
| x-api-key | string | Opcional | Header alternativo para passar a chave sem o prefixo Bearer. |
| Content-Type | string | Sim | Deve ser estritamente application/json para rotas POST/PATCH. |
| Idempotency-Key | string | Recomendado | Identificador único (ex: UUID ou ID do pedido) para evitar cobranças ou saques duplicados em caso de timeout. |
Escopos de Permissão
Controle granular de acessos por chave de API (princípio de menor privilégio).
| Escopo | Descrição | Endpoints Permitidos |
|---|---|---|
| payments:write | Permite gerar novas cobranças e QR Codes PIX. | POST /v1/charges, POST /v1/payments |
| payments:read | Permite consultar status de cobranças, clientes, histórico e saldo. | GET /v1/charges/*, GET /v1/status, GET /v1/customers/*, GET /v1/balance |
| withdrawals:write | Permite solicitar saques/transferências PIX de saída para chaves externas. | POST /v1/withdrawals |
| withdrawals:read | Permite listar e consultar o histórico de saques efetuados. | GET /v1/withdrawals/* |
Formato de Valores & Metadata
Padrão decimal simplificado em Reais e suporte a metadados dinâmicos.
Padrão de Valores Monetários (Reais / Decimais)
Na KavroPay os valores são enviados e retornados diretamente no valor em Reais (como número float ou string decimal formatada).
O Campo metadata
O campo metadata aceita qualquer objeto JSON customizado (SKUs, IDs de afiliados, parâmetros de tracking UTM, número do pedido externo). Ele é preservado e retornado intacto em consultas e nos Webhooks.
{
"amount": 250.00,
"description": "Combo Gamer Headset + Teclado #998811",
"externalId": "ped_998811",
"expiresInMinutes": 30,
"notification_url": "https://seusite.com.br/api/kavropay-webhook",
"customer": {
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br",
"phone": "11987654321"
},
"metadata": {
"order_id": "PEDIDO-998811",
"cart_id": "cart_88392",
"affiliate_id": "afiliado_marcos",
"utm_source": "google_ads",
"utm_campaign": "black_friday_2026",
"items": [
{ "sku": "TECLADO-RGB", "name": "Teclado Mecânico", "price": 180.00, "qty": 1 },
{ "sku": "MOUSE-16K", "name": "Mouse Gamer 16000 DPI", "price": 70.00, "qty": 1 }
]
}
}
Guia de Início Rápido (Quickstart)
Exemplos de criação de cobrança PIX prontos para copiar e rodar em 5 linguagens.
curl -X POST https://api.kavropay.online/v1/charges \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ped_998811_attempt1" \
-d '{
"amount": 49.00,
"description": "Assinatura Mensal #998811",
"externalId": "ped_998811",
"expiresInMinutes": 30,
"customer": {
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br",
"phone": "11987654321"
},
"metadata": {
"order_id": "ped_998811",
"utm_source": "google_ads"
},
"notification_url": "https://seusite.com.br/api/kavropay-webhook"
}'
const response = await fetch('https://api.kavropay.online/v1/charges', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI',
'Content-Type': 'application/json',
'Idempotency-Key': 'ped_998811_attempt1'
},
body: JSON.stringify({
amount: 49.00,
description: 'Assinatura Mensal #998811',
externalId: 'ped_998811',
expiresInMinutes: 30,
customer: {
name: 'Carlos Eduardo Silva',
document: '12345678909',
email: 'carlos@email.com.br',
phone: '11987654321'
},
metadata: {
order_id: 'ped_998811',
utm_source: 'google_ads'
},
notification_url: 'https://seusite.com.br/api/kavropay-webhook'
})
});
const data = await response.json();
console.log('ID do Pagamento:', data.id);
console.log('Copia e Cola:', data.pix_copy_paste);
console.log('QR Code Base64:', data.qr_code_base64);
<?php
$payload = [
'amount' => 49.00,
'description' => 'Assinatura Mensal #998811',
'externalId' => 'ped_998811',
'expiresInMinutes' => 30,
'customer' => [
'name' => 'Carlos Eduardo Silva',
'document' => '12345678909',
'email' => 'carlos@email.com.br',
'phone' => '11987654321'
],
'metadata' => [
'order_id' => 'ped_998811'
],
'notification_url' => 'https://seusite.com.br/api/kavropay-webhook'
];
$ch = curl_init('https://api.kavropay.online/v1/charges');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer sk_live_SUA_CHAVE_AQUI',
'Content-Type: application/json',
'Idempotency-Key: ped_998811_attempt1'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$res = json_decode($response, true);
curl_close($ch);
echo "Código PIX Copia e Cola: " . $res['pix_copy_paste'];
import requests
url = "https://api.kavropay.online/v1/charges"
headers = {
"Authorization": "Bearer sk_live_SUA_CHAVE_AQUI",
"Content-Type": "application/json",
"Idempotency-Key": "ped_998811_attempt1"
}
payload = {
"amount": 49.00,
"description": "Assinatura Mensal #998811",
"externalId": "ped_998811",
"expiresInMinutes": 30,
"customer": {
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br",
"phone": "11987654321"
},
"metadata": {
"order_id": "ped_998811"
},
"notification_url": "https://seusite.com.br/api/kavropay-webhook"
}
res = requests.post(url, headers=headers, json=payload)
data = res.json()
print("ID da cobrança:", data["id"])
print("Código PIX:", data["pix_copy_paste"])
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.kavropay.online/v1/charges"
payload := map[string]interface{}{
"amount": 49.00,
"description": "Assinatura Mensal #998811",
"externalId": "ped_998811",
"expiresInMinutes": 30,
"customer": map[string]string{
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br",
},
"metadata": map[string]string{
"order_id": "ped_998811",
},
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer sk_live_SUA_CHAVE_AQUI")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "ped_998811_attempt1")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
fmt.Println("Resposta KavroPay:", string(respBody))
}
Cobranças PIX (Inbound Payments)
Geração de cobrança PIX instantânea com código Copia e Cola e QR Code.
/v1/charges
(ou /v1/payments)
| Campo | Tipo | Obrigatório | Descrição / Validação |
|---|---|---|---|
| amount | number | Sim | Valor em Reais (ex: 49.00 para R$ 49,00 ou 0.49 para 49 centavos). |
| description | string | Opcional | Texto exibido para o pagador no app bancário. |
| externalId | string | Opcional | ID do seu pedido para reconciliação automática. |
| expiresInMinutes | integer | Opcional | Tempo de validade em minutos (padrão: 30 minutos). |
| customer | object | Opcional | Objeto com name, document (CPF/CNPJ), email, phone. |
| metadata | object | Opcional | Metadados customizados devolvidos nas consultas e webhooks. |
| notification_url | string | Opcional | URL HTTPS para receber o Webhook quando for pago. |
curl -X POST https://api.kavropay.online/v1/charges \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ped_998811_attempt1" \
-d '{
"amount": 49.00,
"description": "Assinatura #998811",
"externalId": "ped_998811",
"customer": {
"name": "Carlos Eduardo",
"document": "12345678909",
"email": "carlos@email.com"
}
}'
const res = await fetch('https://api.kavropay.online/v1/charges', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 49.00,
description: 'Assinatura #998811',
externalId: 'ped_998811',
customer: { name: 'Carlos Eduardo', document: '12345678909', email: 'carlos@email.com' }
})
});
const charge = await res.json();
console.log('PIX Copia e Cola:', charge.pix_copy_paste);
<?php
$ch = curl_init('https://api.kavropay.online/v1/charges');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer sk_live_SUA_CHAVE_AQUI',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'amount' => 49.00,
'description' => 'Assinatura #998811',
'externalId' => 'ped_998811'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $res['pix_copy_paste'];
import requests
res = requests.post('https://api.kavropay.online/v1/charges',
headers={'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI', 'Content-Type': 'application/json'},
json={'amount': 49.00, 'description': 'Assinatura #998811', 'externalId': 'ped_998811'}
)
print(res.json()['pix_copy_paste'])
{
"id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
"amount": 49.00,
"fee": 0.99,
"net": 48.01,
"status": "waiting_payment",
"pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY9B1DEB4D3B7D4BAD9BDD2B520400005303986540549.005802BR5913KavroPay6009SAO PAULO62070503***6304D1A9",
"qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAR...",
"source": "api",
"externalId": "ped_998811",
"external_reference": "ped_998811",
"expires_at": "2026-08-26T12:30:00.000Z",
"created_at": "2026-08-26T12:00:00.000Z"
}
{
"statusCode": 400,
"error": "Bad Request",
"message": "Documento CPF inválido. O CPF deve conter 11 dígitos numéricos válidos."
}
/v1/charges/{id}
Busca os dados detalhados da cobrança. O parâmetro {id} pode ser o ID da KavroPay (PAY...) ou o seu externalId.
curl https://api.kavropay.online/v1/charges/PAY9B1DEB4D3B7D4BAD9BDD2B \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
{
"id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
"amount": 49.00,
"fee": 0.99,
"net": 48.01,
"status": "paid",
"paid_at": "2026-08-26T12:05:12.000Z",
"end_to_end_id": "E9274656202608261205abcdef",
"externalId": "ped_998811",
"customer": {
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br"
}
}
/v1/charges
(Listagem Otimizada < 15ms)
status (paid/waiting_payment/expired), limit (1 a 100), offset (0, 20...)
curl "https://api.kavropay.online/v1/charges?status=paid&limit=50&offset=0" \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
Verificação de Status Unificado
Consulta instantânea do status atual de qualquer cobrança ou saque através de um único endpoint leve.
Como Funciona o Status Unificado?
Este endpoint aceita o parâmetro idtransaction e busca automaticamente se pertence a uma Cobrança PIX ou a um Saque PIX, consultando em tempo real:
• ID Interno (PAY... ou WIT...) | • ID da Adquirente | • externalReference (seu ID de pedido)
/v1/status?idtransaction={id}
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| idtransaction | string | Sim | ID da transação (ex: PAY..., WIT..., ID externo do pedido ou txId da adquirente). |
curl "https://api.kavropay.online/v1/status?idtransaction=PAY9B1DEB4D3B7D4BAD9BDD2B" \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
const id = 'PAY9B1DEB4D3B7D4BAD9BDD2B';
const res = await fetch(`https://api.kavropay.online/v1/status?idtransaction=${id}`, {
headers: { 'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI' }
});
const data = await res.json();
console.log('Status Atual:', data.status); // 'paid', 'waiting_payment', 'paid_out', etc.
<?php
$id = 'PAY9B1DEB4D3B7D4BAD9BDD2B';
$ch = curl_init("https://api.kavropay.online/v1/status?idtransaction=" . urlencode($id));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer sk_live_SUA_CHAVE_AQUI']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Status: " . $res['status'];
import requests
id_tx = 'PAY9B1DEB4D3B7D4BAD9BDD2B'
res = requests.get(f'https://api.kavropay.online/v1/status?idtransaction={id_tx}',
headers={'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI'}
)
print('Status:', res.json()['status'])
{
"id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
"status": "paid"
}
Gestão de Clientes (Customers API)
Cadastre e gerencie a base de clientes pagadores da sua conta via API.
curl -X POST https://api.kavropay.online/v1/customers \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
-H "Content-Type: application/json" \
-d '{
"name": "Renata Alcantara",
"document": "98765432100",
"email": "renata@email.com",
"phone": "21999998888"
}'
{
"id": "cus_abc123def456",
"name": "Renata Alcantara",
"document": "98765432100",
"email": "renata@email.com",
"phone": "21999998888",
"created_at": "2026-08-26T12:00:00.000Z"
}
curl "https://api.kavropay.online/v1/customers?search=Renata&limit=10" \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
{
"data": [
{
"id": "cus_abc123def456",
"name": "Renata Alcantara",
"document": "98765432100",
"email": "renata@email.com",
"phone": "21999998888",
"created_at": "2026-08-26T12:00:00.000Z"
}
],
"total": 1,
"limit": 10,
"offset": 0
}
Saques PIX (Outbound Withdrawals)
Transferência e liquidação automatizada de saldo para chaves PIX externas.
| Campo | Tipo | Obrigatório | Descrição / Tipos Aceitos |
|---|---|---|---|
| amount | number | Sim | Valor do saque em Reais (ex: 100.00). |
| pix_key | string | Sim | Chave PIX de destino (criptografada em AES-256 no banco). |
| pix_key_type | string | Sim | Tipo da chave: CPF, CNPJ, EMAIL, TELEFONE, EVP. |
| description | string | Opcional | Identificador ou motivo do saque. |
curl -X POST https://api.kavropay.online/v1/withdrawals \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: wit_req_88192" \
-d '{
"amount": 100.00,
"pix_key": "12345678909",
"pix_key_type": "CPF",
"description": "Retirada de comissão de vendas"
}'
{
"id": "WIT7A28F1B3E4C9D01",
"amount": 100.00,
"fee": 2.50,
"net": 97.50,
"status": "processing",
"pix_key": "***.456.789-**",
"pix_key_type": "CPF",
"created_at": "2026-08-26T12:10:00.000Z"
}
{
"statusCode": 402,
"error": "Payment Required",
"message": "Saldo disponível insuficiente para realizar esta transferência."
}
Consulta de Saldo da Conta
Verifique em tempo real seu saldo disponível para saques e valores retidos.
/v1/balance
curl https://api.kavropay.online/v1/balance \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
{
"available": 3450.00,
"locked": 0.00,
"currency": "BRL"
}
Webhooks & Notificações em Tempo Real
Receba notificações automáticas de pagamento instantaneamente no seu servidor.
Assim que o cliente paga o PIX no banco dele, nosso servidor envia uma requisição HTTP POST para a sua notification_url com o payload abaixo:
{
"event": "charge.paid",
"timestamp": "2026-08-26T12:05:12.000Z",
"data": {
"id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
"status": "paid",
"amount": 49.00,
"fee": 0.99,
"net": 48.01,
"externalId": "ped_998811",
"paid_at": "2026-08-26T12:05:12.000Z",
"end_to_end_id": "E9274656202608261205abcdef",
"customer": {
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br",
"phone": "11987654321"
},
"metadata": {
"order_id": "ped_998811",
"utm_source": "google_ads"
}
}
}
Boas Práticas ao Receber Webhooks
- Retorne sempre o status HTTP 200 OK de imediato para acusar o recebimento com sucesso.
- Caso seu endpoint retorne erro 5xx ou 4xx, o sistema da KavroPay tentará reenviar automaticamente com retentativas exponenciais.
- Trate o
externalIdouidde forma idempotente para não liberar o produto duas vezes.
Idempotência & Infraestrutura
Práticas recomendadas para conexões instáveis, cotas de requisição e links públicos.
12. Cabeçalho de Idempotência
Ao enviar uma requisição de criação de cobrança ou saque com o header Idempotency-Key: meu_id_unico, caso a conexão caia e sua aplicação tente reenviar a mesma chamada, a KavroPay retornará exatamente a transação original sem criar duplicatas no banco ou gerar cobranças extras.
13. Limites de Taxa (Rate Limiting)
A cota padrão para chaves de API autenticadas é de 120 requisições por minuto por chave.
Os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining acompanham todas as respostas.