Formato de Valores & Metadata

A API da KavroPay foi projetada com alta flexibilidade para aceitar tanto valores monetários decimais em Reais quanto valores inteiros em centavos.

Formas de Enviar o Valor Monetário

Você pode escolher uma das duas abordagens abaixo em qualquer rota de cobrança ou saque:

Opção 1: String Decimal em Reais (`amount`) — Recomendado para Front-ends

Envie o campo amount como uma string com exatamente duas casas decimais:

{
  "amount": "49.90"
}

Para R$ 10,00 envie: "10.00" (ou "10,00")
Para R$ 0,50 envie: "0.50"
Se você calcula o valor numericamente no seu backend, formate com .toFixed(2) antes de serializar no JSON.

Atenção ao enviar números inteiros no campo amount:Se você enviar um número JSON puro sem casas decimais como "amount": 10, a API retornará o erro: "Valor inválido. Informe o valor com casas decimais (ex: 10.00 ou 10,00)."Isso ocorre porque o padrão JSON descarta zeros à direita (10.00 vira 10), gerando ambiguidade financeira. Para valores inteiros, utilize a Opção 2 (amountCents) abaixo.

Opção 2: Inteiro em Centavos (`amountCents`) — Padrão Stripe & Gateways

Se o seu sistema opera financeiramente em centavos inteiros (integers), envie amountCents ou amount_cents:

{
  "amountCents": 4990
}

R$ 10,00 = 1000 centavos
R$ 0,50 = 50 centavos
R$ 100,00 = 10000 centavos

Essa opção elimina completamente qualquer erro de arredondamento em pontos flutuantes.

O Campo `metadata`

O campo metadata aceita qualquer objeto JSON livre com até 50 chaves. Todas as chaves e valores enviados são armazenados e devolvidos intactos nas consultas (GET /v1/charges/:id) e nos payloads dos Webhooks.

Exemplo com Metadata Completo

{
  "amount": "250.00",
  "description": "Combo Gamer Pro #998811",
  "externalId": "ped_998811",
  "expiresInMinutes": 30,
  "notification_url": "https://seusite.com.br/api/kavropay-webhook",
  "customer": {
    "name": "Carlos Eduardo Ramos",
    "document": "12345678909",
    "email": "carlos.ramos@email.com",
    "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", "price": "70.00", "qty": 1 }
    ]
  }
}

Chaves & Autenticação

Veja como autenticar suas requisições com Authorization: Bearer.

Criar Cobrança PIX

Veja o guia completo para emissão de cobranças PIX.

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Formato de Valores & Metadata

Formas de Enviar o Valor Monetário

Opção 1: String Decimal em Reais (`amount`) — Recomendado para Front-ends

Opção 2: Inteiro em Centavos (`amountCents`) — Padrão Stripe & Gateways

O Campo `metadata`

Chaves & Autenticação

Criar Cobrança PIX

Formas de Enviar o Valor Monetário

Opção 1: String Decimal em Reais (amount) — Recomendado para Front-ends

Opção 2: Inteiro em Centavos (amountCents) — Padrão Stripe & Gateways

O Campo metadata

Chaves & Autenticação

Criar Cobrança PIX

Opção 1: String Decimal em Reais (`amount`) — Recomendado para Front-ends

Opção 2: Inteiro em Centavos (`amountCents`) — Padrão Stripe & Gateways

O Campo `metadata`