Visão Geral & Arquitetura
Conheça a infraestrutura de pagamentos instantâneos da KavroPay.
https://api.kavropay.online/v1
A API REST da KavroPay oferece uma solução completa e de alta performance para processar pagamentos PIX instantâneos, gerenciar clientes, realizar saques automáticos de saída e receber notificações em tempo real.
Resolução PIX em < 100ms
Geração imediata do código PIX Copia e Cola e do QR Code em imagem Base64.
Roteamento Inteligente
Redirecionamento dinâmico entre adquirentes para garantir máxima aprovação.
Micro-pagamentos Flexíveis
Cálculo inteligente para transações abaixo de R$ 1,00 mantendo o repasse líquido.
Nomenclatura Híbrida
Aceita e devolve os campos em camelCase e snake_case.
Autenticação & Cabeçalhos HTTP
Padrões de segurança e headers obrigatórios para requisições.
Todas as chamadas à API devem incluir os seguintes cabeçalhos no formato JSON:
| Header | Tipo | Obrigatório | Descrição / Exemplo |
|---|---|---|---|
| Authorization | string | Sim | Token Bearer (Bearer sk_live_... ou Bearer sk_test_...). |
| x-api-key | string | Opcional | Header alternativo de autenticação. |
| Content-Type | string | Sim | Deve ser estritamente application/json. |
| Idempotency-Key | string | Opcional | UUID para evitar transações duplicadas em falhas de rede. |
Escopos de Permissão
Níveis de acesso e permissões atribuídas a cada chave de API.
| Escopo | Descrição | Endpoints Permitidos |
|---|---|---|
| payments:write | Permite criar novas cobranças e QR Codes PIX. | POST /v1/charges, POST /v1/payments |
| payments:read | Permite consultar cobranças, clientes, histórico e saldo. | GET /v1/charges/*, GET /v1/customers/*, GET /v1/balance |
| withdrawals:write | Permite realizar saques/transferências PIX de saída. | POST /v1/withdrawals |
| withdrawals:read | Permite listar e consultar saques efetuados. | GET /v1/withdrawals/* |
Parâmetros de Entrada & Metadata
Detalhes sobre os campos aceitos na criação de transações e suporte a metadados livres.
O Campo metadata em POST /v1/charges
O campo metadata aceita qualquer objeto JSON customizado para rastreamento de pedidos, itens do carrinho ou parâmetros de afiliados. Ele é devolvido idêntico nas consultas e nos webhooks.
{
"amount": 250.00,
"description": "Combo Gamer #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",
"buyerName": "Carlos Eduardo Silva",
"buyerDocument": "12345678909",
"buyerEmail": "carlos@email.com.br",
"buyerPhone": "11987654321",
"utm_source": "google_ads",
"utm_campaign": "black_friday_2026",
"affiliate_id": "afiliado_marcos",
"cart_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 }
]
}
}
Objeto customer (Pagador)
| Campo | Tipo | Obrigatório | Regras de Validação | Exemplo |
|---|---|---|---|---|
| name | string | Opcional | Nome do pagador (padrão: "Cliente PIX"). | "Carlos Eduardo Silva" |
| document | string | Opcional | Validação oficial de CPF (11d) ou CNPJ (14d). | "12345678909" |
| string | Opcional | E-mail para envio de comprovantes. | "carlos@email.com" | |
| phone | string | Opcional | Telefone fixo ou celular com DDD do Brasil. | "11987654321" |
Algoritmo de Micro-pagamentos (< R$ 1,00)
Para cobranças com valor menor que 100 centavos (ex: R$ 0,30): A API calcula a taxa fixa de R$ 0,50 e soma ao valor do PIX gerado (R$ 0,30 + R$ 0,50 = R$ 0,80). O cliente paga R$ 0,80 no aplicativo do banco e o valor líquido repassado ao seu saldo é exatamente os R$ 0,30 desejados!
Guia de Início Rápido (Quickstart)
Exemplos completos de criação de cobrança PIX em 5 linguagens de programação.
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": 250.00,
"description": "Combo Gamer #998811",
"externalId": "ped_998811",
"expiresInMinutes": 30,
"customer": {
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br"
},
"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: 250.00,
description: 'Combo Gamer #998811',
externalId: 'ped_998811',
expiresInMinutes: 30,
customer: {
name: 'Carlos Eduardo Silva',
document: '12345678909',
email: 'carlos@email.com.br'
},
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
$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([
'amount' => 250.00,
'description' => 'Combo Gamer #998811',
'externalId' => 'ped_998811',
'customer' => [
'name' => 'Carlos Eduardo Silva',
'document' => '12345678909',
'email' => 'carlos@email.com.br'
],
'metadata' => [
'order_id' => 'ped_998811'
],
'notification_url' => 'https://seusite.com.br/api/kavropay-webhook'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Código PIX: " . $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": 250.00,
"description": "Combo Gamer #998811",
"externalId": "ped_998811",
"customer": {
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br"
},
"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("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": 250.00,
"description": "Combo Gamer #998811",
"externalId": "ped_998811",
"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")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
fmt.Println("Resposta:", string(respBody))
}
Cobranças PIX (Inbound Payments)
Geração de QR Code PIX em tempo real e consulta de transações.
https://api.kavropay.online/v1
/v1/charges
(ou /v1/payments)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| amount | number | Sim | Valor em Reais (ex: 250.00 ou "250.00"). |
| description | string | Opcional | Descrição do produto ou serviço. |
| externalId | string | Opcional | ID do pedido no seu banco de dados. |
| expiresInMinutes | integer | Opcional | Validade em minutos (padrão: 30 minutos). |
| customer | object | Opcional | Dados cadastrais do comprador (name, document, email, phone). |
| metadata | object | Opcional | Objeto JSON com quaisquer dados customizados adicionais. |
| notification_url | string | Opcional | URL do seu servidor para receber Webhooks. |
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": 250.00,
"description": "Combo Gamer #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",
"utm_source": "google_ads"
}
}'
{
"id": "pay_9876543210abcdef",
"amount": 25000,
"fee": 797,
"net": 24203,
"status": "waiting_payment",
"pix_copy_paste": "00020126580014br.gov.bcb.pix0136pay_9876543210abcdef5204000053039865405250.005802BR5913KavroPay Gateway6009SAO PAULO62070503***6304E3F2",
"qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAR...",
"expires_at": "2026-08-07T17:48:02.000Z",
"created_at": "2026-08-07T17:18:02.000Z",
"externalId": "ped_998811",
"external_reference": "ped_998811",
"metadata": {
"order_id": "PEDIDO-998811",
"cart_id": "cart_88392",
"utm_source": "google_ads"
}
}
/v1/charges/{id}
curl https://api.kavropay.online/v1/charges/pay_9876543210abcdef \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
{
"id": "pay_9876543210abcdef",
"status": "paid",
"amount": 25000,
"paidAt": "2026-08-07T17:19:12.000Z",
"acquirerTxId": "E9274656202608071719abcdef",
"externalId": "ped_998811",
"customer": {
"name": "Carlos Eduardo Silva",
"document": "123.***.*89-09",
"email": "carlos@email.com.br"
},
"metadata": {
"order_id": "ped_998811",
"utm_source": "google_ads"
}
}
/v1/charges
(Listar Cobranças Paginadas)
curl "https://api.kavropay.online/v1/charges?status=paid&limit=20&offset=0" \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
{
"data": [
{
"id": "pay_9876543210abcdef",
"status": "paid",
"amount": 25000,
"paidAt": "2026-08-07T17:19:12.000Z",
"externalId": "ped_998811"
}
],
"total": 1,
"limit": 20,
"offset": 0
}
Gestão de Clientes (Customers API)
Gerencie o cadastro de pagadores da sua conta via API Key.
https://api.kavropay.online/v1/customers
Requisição cURL
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"
}'
Exemplo de Resposta (HTTP 201 Created)
{
"id": "cus_abc123def456",
"name": "Renata Alcantara",
"document": "98765432100",
"email": "renata@email.com",
"phone": "21999998888",
"created_at": "2026-08-07T17:18:02.000Z"
}
Requisição cURL
curl "https://api.kavropay.online/v1/customers?search=Renata&limit=10" \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
Exemplo de Resposta (HTTP 200 OK)
{
"data": [
{
"id": "cus_abc123def456",
"name": "Renata Alcantara",
"document": "98765432100",
"email": "renata@email.com",
"phone": "21999998888",
"created_at": "2026-08-07T17:18:02.000Z"
}
],
"total": 1,
"limit": 10,
"offset": 0
}
Requisição cURL
curl https://api.kavropay.online/v1/customers/cus_abc123def456 \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
Exemplo de Resposta (HTTP 200 OK)
{
"id": "cus_abc123def456",
"name": "Renata Alcantara",
"document": "98765432100",
"email": "renata@email.com",
"phone": "21999998888",
"created_at": "2026-08-07T17:18:02.000Z"
}
Requisição cURL
curl -X PATCH https://api.kavropay.online/v1/customers/cus_abc123def456 \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
-H "Content-Type: application/json" \
-d '{ "phone": "21988887777" }'
Exemplo de Resposta (HTTP 200 OK)
{
"id": "cus_abc123def456",
"name": "Renata Alcantara",
"document": "98765432100",
"email": "renata@email.com",
"phone": "21988887777",
"updated_at": "2026-08-07T18:00:00.000Z"
}
Requisição cURL
curl -X DELETE https://api.kavropay.online/v1/customers/cus_abc123def456 \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
Exemplo de Resposta (HTTP 200 OK)
{
"id": "cus_abc123def456",
"deleted": true
}
Saques PIX (Outbound Withdrawals)
Envio de transferências e liquidação para chaves PIX externas.
https://api.kavropay.online/v1/withdrawals
/v1/withdrawals
Transferir fundos do saldo disponível para qualquer chave PIX externa.
curl -X POST https://api.kavropay.online/v1/withdrawals \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
-H "Content-Type: application/json" \
-d '{
"amount": 100.00,
"pix_key": "12345678909",
"pix_key_type": "CPF",
"description": "Retirada de comissão"
}'
{
"id": "wit_1234567890abcdef",
"amount": 10000,
"status": "processing",
"pix_key": "12345678909",
"pix_key_type": "CPF",
"created_at": "2026-08-07T17:20:00.000Z"
}
Consulta de Saldo da Conta
Verificação em tempo real de saldo disponível e valores retidos.
https://api.kavropay.online/v1/balance
/v1/balance
Requisição cURL com Autenticação
curl https://api.kavropay.online/v1/balance \
-H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
Exemplo de Resposta (HTTP 200 OK)
{
"available": 3450.00,
"availableCents": 345000,
"locked": 0.00,
"lockedCents": 0,
"currency": "BRL"
}
Webhooks & Notificações em Tempo Real
Notificações assíncronas enviadas instantaneamente ao seu servidor.
Abaixo está o exemplo do payload enviado no evento charge.paid incluindo os metadados:
{
"event": "charge.paid",
"timestamp": "2026-08-07T17:19:12.000Z",
"data": {
"id": "pay_9876543210abcdef",
"status": "paid",
"amount": 250.00,
"amountCents": 25000,
"feeCents": 797,
"netCents": 24203,
"externalId": "ped_998811",
"paidAt": "2026-08-07T17:19:12.000Z",
"acquirerTxId": "E9274656202608071719abcdef",
"customer": {
"name": "Carlos Eduardo Silva",
"document": "12345678909",
"email": "carlos@email.com.br",
"phone": "11987654321"
},
"metadata": {
"order_id": "ped_998811",
"utm_source": "google_ads"
}
}
}
Idempotência & Infraestrutura
Práticas de resiliência, cotas de requisição e links públicos.
11. Idempotência
Envie o cabeçalho Idempotency-Key para garantir que conexões instáveis não resultem em requisições duplicadas.
12. Limites de Taxa (Rate Limiting)
A cota padrão para todas as chaves de API é de 60 requisições por minuto.
13. Links de Pagamento
Links de pagamento são gerenciados via Dashboard. Para integrações via API Key utilize a rota POST /v1/charges.