Referência da API

#URL base

https://api.kokupay.com/v1

#Autenticação

Toda requisição leva a chave de API da sua conta no cabeçalho Authorization. A conta e o ambiente vêm da chave. Cada endpoint exige um escopo; veja Chaves de API.

Authorization: Bearer koku_live_3f9a1c2b4d5e_<segredo>

#Convenções

• JSON no corpo e na resposta (Content-Type: application/json), chaves em snake_case.
• Valores em centavos. Na entrada, inteiro ou string; na saída, string decimal ("15990" = R$ 159,90). Moeda: BRL.
• Datas em ISO-8601, UTC (ex.: 2026-10-07T15:30:00.000Z).
• Campos desconhecidos no corpo são recusados com 422.
• Idempotência: Idempotency-Key obrigatório ao criar cobrança e ao pedir devolução. Veja Idempotência.
• Paginação por cursor (cursor → next_cursor). Veja Paginação.
• Erros no formato { "error": { "code", "message", "details", "correlation_id" } }. Veja Erros.
• Correlation ID em toda resposta (X-Correlation-Id).
• Compatibilidade: novos campos podem aparecer nas respostas; ignore os que não conhece.

#Especificação OpenAPI

A especificação OpenAPI 3.1 desta API pública está em /openapi.json. Importe no seu cliente HTTP preferido ou gere tipos a partir dela.

#Endpoints