Códigos de Resposta HTTP (4xx & 5xx)
| HTTP Status | Código de Erro | Causa do Erro | Como Resolver |
|---|---|---|---|
400 Bad Request | VALIDATION_ERROR | Parâmetro inválido, ausente ou divergente (ex: divergência entre amount e amountCents, ou documento inválido). | Envie o valor em formato decimal (ex: "49.00") ou centavos (4900) e informe CPF/CNPJ válido. |
401 Unauthorized | UNAUTHORIZED | Chave de API ausente, revogada ou malformatada. | Verifique o cabeçalho Authorization: Bearer kvk_live_... ou x-api-key. |
402 Payment Required | INSUFFICIENT_BALANCE | Tentativa de saque maior que o saldo disponível na carteira da empresa. | Consulte o saldo via GET /v1/balance antes de solicitar novas transferências. |
403 Forbidden | INSUFFICIENT_SCOPE | A chave de API utilizada não possui os escopos necessários (ex: payments:write). | Gere uma chave com as permissões exigidas no painel KavroPay. |
404 Not Found | NOT_FOUND | Cobrança, saque ou cliente pesquisado não foi localizado. | Verifique se o ID ou externalId pesquisado pertence à sua conta. |
429 Too Many Requests | RATE_LIMIT_EXCEEDED | Limite de requisições por minuto foi ultrapassado. | Aguarde o tempo indicado nos headers de Rate Limit (X-RateLimit-Reset) antes de tentar novamente. |
500 Server Error | INTERNAL_ERROR | Erro interno transitório na infraestrutura ou adquirente. | A KavroPay possui roteamento inteligente e redundância ativa com failover automático. |
Status das Cobranças PIX (Inbound)
Status (status) | Nome Exibido | Significado & Ciclo de Vida |
|---|---|---|
waiting_payment | Aguardando Pagamento | Cobrança gerada com sucesso e QR Code ativo no Banco Central aguardando leitura pelo pagador. |
paid | Pago / Confirmado | Pagamento PIX efetuado e liquidado no mesmo instante. Saldo creditado imediatamente na sua carteira. |
expired | Expirado | O tempo de validade do QR Code (expires_at) foi atingido sem que o cliente tenha realizado o pagamento. |
refunded | Reembolsado | Cobrança paga que sofreu estorno total ou parcial (solicitado pelo lojista ou via MED). |
chargeback | Disputa / Infração | Transação retida preventivamente devido à Notificação de Infração do Banco Central (MED). |
Sobre cancelamento de cobranças PIX:Cobranças PIX não possuem endpoint de cancelamento manual. O ciclo de vida do PIX é natural: a cobrança permanece em
waiting_payment até que ocorra o pagamento (paid) ou até que o tempo limite expire automaticamente (expired).Status de Saques PIX (Outbound)
Status (status) | Nome Exibido | Significado & Comportamento |
|---|---|---|
pending | Em Fila | Solicitação de saque registrada e aguardando liberação e análise de risco preventiva. |
processing | Em Processamento | Saque enviado para a rede do Banco Central para liquidação na conta de destino. |
paid_out | Concluído | Transferência PIX liquidada com sucesso na conta bancária de destino. |
failed | Falhou / Rejeitado | Falha na liquidação (chave inválida ou recusa pelo banco receptor). O saldo e as taxas são estornados na hora. |
Tabela de Eventos de Webhook
Evento (event) | Status Vinculado | Quando é Disparado? |
|---|---|---|
payment.paid | paid | Disparado no exato milissegundo em que o pagamento PIX do cliente é confirmado pelo Banco Central. |
payment.confirmed | paid | Alias canônico de payment.paid. Idêntico em comportamento e payload. |
payment.expired | expired | Disparado quando o prazo de validade (expires_at) do QR Code expira sem pagamento. |
payment.refunded | refunded | Disparado quando um PIX anteriormente pago é estornado/reembolsado ao pagador. |
withdrawal.completed | paid_out | Disparado quando a transferência PIX de saída é concluída com sucesso. |
withdrawal.failed | failed | Disparado se a transferência de saque falhar ou for recusada pelo banco destinatário. |