llms.txt (Guia para Modelos de IA & Agentes)

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.online/llms.txt

​

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

​

2. Autenticação e Cabeçalhos

Authorization: Bearer sk_live_SUA_CHAVE_AQUI
Content-Type: application/json

x-api-key: sk_live_SUA_CHAVE_AQUI

Idempotency-Key: ped_98124_tentativa_1

​

3. Formato de Valores Financeiros & Taxas

​

Formato de Envio

1. String Decimal em Reais (amount):
   • Sempre com duas casas decimais: "10.00" para R$ 10,00 ou "0.50" para 50 centavos.
   • Números inteiros diretos no campo amount (como 10) retornam erro 400 exigindo casas decimais.
2. Inteiro em Centavos (amountCents ou amount_cents):
   • 1000 para R$10,00 ou `50` para R$ 0,50.

​

Estrutura de Taxas Padrão

• **Até R$100,00**: 0,99$ 0,50 fixos.
• **Acima de R$100,00**: **2,99$ 0,50 fixos.

​

4. Endpoints Principais da API

​

4.1. Cobranças PIX (Inbound)

​

Criar Cobrança PIX (com Split Opcional)

• Rota: POST https://api.kavropay.online/v1/charges (ou POST /v1/payments)
• Escopo: payments:write
• Body JSON:
  {
    "amount": "150.00",
    "description": "Assinatura Mensal #1029",
    "externalId": "pedido_1029",
    "expiresInMinutes": 30,
    "payment_link": true,
    "customer": {
      "name": "Carlos Eduardo",
      "document": "12345678909",
      "email": "carlos@email.com",
      "phone": "11987654321"
    },
    "split": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "percentage": 20,
        "chargeProcessingFee": false,
        "description": "Comissão Parceiro"
      }
    ],
    "notification_url": "https://seu-servidor.com/webhook"
  }
  
• Campos do pagador (customer): Opcionais. Se omitidos, a KavroPay preenche fallbacks inteligentes e seguros automaticamente para compatibilidade bancária instantânea.
• Resposta Sucesso (HTTP 201 Created):
  {
    "id": "PAY048E35EA7272EB1AC328AA",
    "amount": 150.00,
    "fee": 4.99,
    "net": 145.01,
    "status": "waiting_payment",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY048E35EA7272EB1AC328AA...",
    "qr_code_base64": "data:image/svg+xml;base64,...",
    "payment_url": "https://pay.kavropay.online/p/pag_048e35ea7272eb1ac328aa",
    "split": {
      "totalNet": 145.01,
      "originator": {
        "companyId": "a0000000-0000-0000-0000-000000000001",
        "net": 115.01
      },
      "recipients": [
        {
          "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
          "recipientName": "Loja Parceira",
          "amount": 30.00,
          "net": 30.00,
          "status": "pending"
        }
      ]
    },
    "externalId": "pedido_1029",
    "expires_at": "2026-09-28T14:00:00.000Z",
    "created_at": "2026-09-28T13:00:00.000Z"
  }
  

​

Consultar Cobrança PIX

• Rota: GET https://api.kavropay.online/v1/charges/:id
• Escopo: payments:read
• O parâmetro :id aceita tanto o ID KavroPay (PAY...) quanto o seu externalId.

​

Cancelar Cobrança PIX

• Rota: POST https://api.kavropay.online/v1/charges/:id/cancel
• Escopo: payments:write

​

4.2. Split de Pagamentos (Multi-Recebedores)

​

Simular / Calcular Split

• Rota: POST https://api.kavropay.online/v1/splits/calculate
• Escopo: payments:read
• Body JSON:
  {
    "amount": "150.00",
    "split": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "percentage": 20
      }
    ]
  }
  

​

Listar Extrato de Splits

• Rota: GET https://api.kavropay.online/v1/splits?role=all&page=1&limit=20
• Escopo: payments:read

​

Detalhes do Split de uma Cobrança

• Rota: GET https://api.kavropay.online/v1/splits/:transactionId
• Escopo: payments:read

​

4.3. Status Unificado (Polling Ultra-Rápido < 10ms)

• Rota: GET https://api.kavropay.online/v1/status?idtransaction=PAY048E35EA7272EB1AC328AA
• Alternativa: POST https://api.kavropay.online/v1/status com {"idtransaction": "PAY..."}
• Escopo: payments:read

​

4.4. Saques PIX (Cashout / Outbound)

​

Solicitar Saque

• Rota: POST https://api.kavropay.online/v1/withdrawals
• Escopo: withdrawals:write
• Tipos de chave aceitos: CPF, CNPJ, EMAIL, TELEFONE (ou PHONE), EVP (ou RANDOM).

​

4.5. Saldo da Conta

• Rota: GET https://api.kavropay.online/v1/balance
• Escopo: payments:read

​

4.6. Webhooks em Tempo Real

• charge.paid: Cobrança liquidada no Banco Central (saldo creditado e splits rateados atomicamente).
• charge.expired: Cobrança expirou sem pagamento.
• withdrawal.completed: Saque transferido com sucesso para a chave destinatária.
• withdrawal.failed: Saque rejeitado pelo banco receptor (saldo e taxa estornados automaticamente).

​

5. Tabela de Status & Códigos HTTP

​

Status de Transação

• Cobrança: waiting_payment (aguardando), paid (paga), expired (expirada), cancelled (cancelada).
• Saque: pending (em fila), processing (em liquidação), completed / paid_out (concluído), failed (rejeitado/estornado).

​

Códigos de Erro HTTP

• 400 Bad Request: Erro de validação de payload (ex: amount como inteiro sem amountCents, ou soma de splits > 100%).
• 401 Unauthorized: Chave de API ausente ou inválida.
• 402 Payment Required: Saldo insuficiente para saque.
• 403 Forbidden: Chave de API sem escopo para a rota solicitada.
• 404 Not Found: Registro não localizado.
• 429 Too Many Requests: Cota de 120 req/min ultrapassada (consulte header Retry-After).
• 500 Server Error: Instabilidade transitória com failover automático de gateway.