Guia técnico completo para integrar a API REST da KlivoPay: autenticação, criação de cobranças, webhooks.
A API da KlivoPay usa Bearer Token. Gere sua chave secreta em Configurações > API Keys no painel. Use o header: Authorization: Bearer SEU_TOKEN. Nunca exponha sua chave no frontend ou repositórios públicos.
POST /v1/charges com body JSON: { amount: 9990 (em centavos), payment_method: 'pix', customer: { name, email, cpf }, description: 'Produto X' }. A API retorna o ID da cobrança e o QR Code Pix.
GET /v1/charges/{id} retorna o status atual: pending, paid, refused, refunded. Polling a cada 5 segundos é aceitável para Pix. Para produção, prefira webhooks (mais eficiente).
Em Configurações > Webhooks, adicione sua URL de destino (deve ser HTTPS). A KlivoPay enviará um POST com o payload da transação para cada evento: charge.paid, charge.refused, charge.refunded. Valide a assinatura HMAC-SHA256 para segurança.
Código 400: dados inválidos (verifique o payload). Código 401: token inválido. Código 422: erro de validação (CPF, valor mínimo). Código 500: erro interno — tente novamente em 30 segundos. Implemente retry com backoff exponencial.