> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavropay.online/llms.txt
> Use this file to discover all available pages before exploring further.
# Formato de Valores & Metadata
> Padrão decimal simplificado em Reais e suporte a metadados dinâmicos.
**`amount` deve ser enviado como string decimal, não como número JSON**
A API espera **sempre uma string** com exatamente duas casas decimais — nunca um número JSON puro. Isso é proposital: números JSON não preservam zeros à direita (`10.00` é serializado como `10`), e a API rejeita valores sem as duas casas decimais explícitas.
* Para R\$ 49,00 envie: `"amount": "49.00"` — **não** `"amount": 49.00` (isso vira `49` no JSON e é rejeitado)
* Para R\$ 0,49 (49 centavos) envie: `"amount": "0.49"`
Se você calcula o valor programaticamente, formate sempre com `.toFixed(2)` (ou equivalente na sua linguagem) e envie como string antes de montar o payload.
## 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.
```json Payload JSON de Exemplo com Metadata theme={null}
{
"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 }
]
}
}
```