Skip to main content
Este documento foi estruturado especificamente para modelos de linguagem (LLMs), agentes de desenvolvimento (Cursor, Windsurf, Claude Code, GitHub Copilot) e automações que precisam de instruções concisas, inequívocas e completas para integrar pagamentos PIX com a KavroPay. Versão raw disponível para download e scraping direto em: https://api.kavropay.com.br/llms.txt

1. Visão Geral & Especificações Técnicas

2. Autenticação e Cabeçalhos

Todas as requisições autenticadas devem enviar:
Header alternativo aceito:
Para criação de cobranças e saques, envie sempre uma chave de idempotência para evitar duplicidade em timeouts:

3. Formato de Valores Financeiros & Taxas

Formato de Envio

A API aceita duas formas de especificar valores monetários:
  1. String Decimal em Reais (amount):
    • Sempre com duas casas decimais: "10.00" para R$ 10,00 ou "0.50" para 50 centavos.
  2. Inteiro em Centavos (amountCents ou amount_cents):
    • 1000 para R10,00ou‘50‘paraR 10,00 ou `50` para R 0,50.

Estrutura de Taxas Padrão

  • **Até R100,00∗∗:0,99 100,00**: 0,99% (99 bps) + R 0,50 fixos.
  • **Acima de R100,00∗∗:2,99 100,00**: 2,99% (299 bps) + R 0,50 fixos.

4. Endpoints Principais da API

4.1. Cobranças PIX (Inbound)

  • POST /v1/charges: Criar cobrança PIX com QR Code dinâmico e Copia e Cola.
  • GET /v1/charges/:id: Consultar dados e status da cobrança.
  • GET /v1/charges/:id/status: Consultar status leve para polling (< 15ms).
  • GET /v1/charges: Listar cobranças paginadas.

4.2. Saques PIX (Outbound)

  • POST /v1/withdrawals: Solicitar saque para chave PIX (CPF, CNPJ, EMAIL, PHONE, EVP).
  • GET /v1/withdrawals/:id: Consultar comprovante e status do saque.
  • GET /v1/withdrawals: Listar saques efetuados.

4.3. Gestão de Subcontas

  • POST /v1/subaccounts: Criar subconta vinculada com markup configurável.
  • GET /v1/subaccounts: Listar subcontas cadastradas.
  • GET /v1/subaccounts/:id: Consultar detalhes da subconta.
  • GET /v1/subaccounts/:id/balance: Consultar saldo disponível e bloqueado da subconta.
  • POST /v1/subaccounts/:id/add-balance: Aporte de saldo da Master para subconta.
  • POST /v1/subaccounts/:id/remove-balance: Resgate de saldo da subconta para Master.
  • POST /v1/subaccounts/transfer: Transferência direta entre contas.
  • POST /v1/subaccounts/:id/pricing: Configurar taxas/spread da subconta.
  • POST /v1/subaccounts/:id/limits: Configurar limites operacionais de saque.
  • POST /v1/subaccounts/:id/lock: Bloquear ou desbloquear subconta.
  • GET /v1/subaccounts/:id/statement: Extrato contábil de transações.
  • DELETE /v1/subaccounts/:id: Excluir subconta zerada.
  • POST /v1/paylinks: Criar link de pagamento compartilhável.
  • GET /v1/paylinks: Listar links de pagamento.
  • GET /v1/paylinks/:id: Consultar link de pagamento e conversão.
  • POST /v1/paylinks/public/:id/checkout: Endpoint público de checkout.

4.5. Status Unificado & Saldo Master

  • GET /v1/status/:identifier: Polling universal ultra-rápido para cobrança ou saque.
  • GET /v1/balance: Consultar saldo disponível e bloqueado da Conta Master.

4.6. Webhooks

  • Eventos despachados: payment.paid, payment.created, payment.expired, withdrawal.paid, withdrawal.failed.
  • Assinatura criptográfica enviada no header X-KavroPay-Signature (e X-Kavro-Signature) via HMAC-SHA256 no formato t={timestamp},v1={hash}.
  • Suporte a notification_url exclusivo por cobrança com escopo estrito tx:<id> e chave segura notification_secret (whsec_...).
  • Gestão de Webhooks: GET /v1/webhooks, POST /v1/webhooks, GET /v1/webhooks/:id/secret, POST /v1/webhooks/:id/rotate-secret, GET /v1/webhooks/diagnostic.