Token inválido ou ausente
Sintoma:401 Unauthorized em qualquer chamada.
| Verificação | Ação |
|---|---|
Header Authorization presente? | Adicionar: Authorization: Bearer <token> |
Prefixo Bearer com espaço? | Corrigir: Bearer (com espaço após) |
| Token correto para o ambiente? | Confirmar base URL e token (produção ≠ sandbox) |
| Token expirado ou revogado? | Reemitir via POST /api-key/generate com token administrativo |
Token administrativo correto em /api-key/generate? | Validar com a equipe de plataforma |
Payload inválido (400 / 422)
Sintoma:400 Bad Request ou 422 Unprocessable Entity.
| Verificação | Ação |
|---|---|
Content-Type: application/json presente? | Adicionar em todos os POST com corpo |
| JSON malformado? | Validar com jq ou ferramenta online |
| Campos obrigatórios ausentes? | Revisar a referência do endpoint |
value ou refundValue em BRL (não centavos)? | Corrigir: campos de request são em reais (ex.: 150.75) |
pixKeyType coerente com pixKey? | Ex.: email deve ter formato a@b.com |
externalId duplicado (409)
Sintoma: 409 Conflict.
| Verificação | Ação |
|---|---|
| Mesma criação sendo reenviada? | Buscar o recurso existente pelo externalId (se houver endpoint) ou pelo id persistido |
Lógica de retry sem novo externalId? | Usar novo externalId apenas para nova intenção de operação, não para retry da mesma |
externalId sendo reutilizado entre operações distintas? | externalId deve ser único por operação |
Transação não encontrada (404)
Sintoma:404 Not Found em GET /api/pix/cash-in/{id} ou similar.
| Verificação | Ação |
|---|---|
| UUID correto? | Conferir o id retornado no 201 da criação |
Confundindo id do cash-in com id do refund? | Leia modelo de identidade |
Usando transactionId do BaaS em vez do UUID? | GET /api/pix/cash-in/{id} usa o UUID interno, não o transactionId |
| Ambiente correto? | Produção vs. sandbox: base URLs distintas |
Webhook não recebido
Sintoma: pagamento confirmado (via GET), mas nenhum webhook chegou.Verificar o endpoint
Testar a URL com uma requisição manual (
curl -X POST https://seu-sistema.com/webhooks/pix -H "Content-Type: application/json" -d '{}') — deve retornar 2xx (mesmo sem assinatura válida, o endpoint deve estar acessível).Verificar logs
Logs do seu endpoint de webhook para o período — possível 5xx que gerou retentativas sem sucesso.
Verificar WAF / firewall
Regras de WAF podem bloquear headers como
Digital-Signature. Permitir passagem desse header.Assinatura inválida
Sintoma: verificação deDigital-Signature sempre falha.
| Verificação | Ação |
|---|---|
| Raw body preservado? | Salvar o buffer antes do parse JSON; middlewares podem modificar |
| Chave pública desatualizada? | Buscar novamente via GET /public-key; cache pode estar expirado |
| Encoding Base64 correto? | Sem espaços ou quebras de linha na string da assinatura |
| Algoritmo correto? | ECDSA P-256 + SHA-256 sobre o body bruto |
| Formato da assinatura (DER vs. IEEE P1363)? | TODO: confirmar com a plataforma o encoding exato |
QR Code expirado
Sintoma: pagador informa que o QR não funciona ou o cash-in estáEXPIRED.
| Verificação | Ação |
|---|---|
expirationDate da cobrança verificado? | Comparar com o horário atual em UTC |
| Cobrança expirada? | Criar nova cobrança com POST /api/pix/cash-in e novo externalId |
expirationTime muito curto? | Aumentar o valor em segundos na criação |
Refund rejeitado
Sintoma:422 ao tentar criar refund-in.
| Mensagem | Causa | Ação |
|---|---|---|
refundValue must be greater than zero | Valor zerado ou negativo | Corrigir o valor |
refundValue exceeds the amount available for refund | Teto atingido (pending + confirmed) | Reduzir o valor ou aguardar devoluções pendentes serem resolvidas |
refund deadline of 89 days has been exceeded | Prazo regulatório | Não é possível devolver; encerrar o processo |
refunds can only be issued for PAID cash-in transactions | Cash-in não está PAID | Verificar status com GET /api/pix/cash-in/{id} |
original cash-in transaction not found | UUID errado no path | Usar o id do cash-in, não o transactionId |
Estado ambíguo (PROVIDER_RESULT_UNKNOWN / RECONCILIATION_REQUIRED)
Sintoma: transação presa sem avançar para estado terminal.| Estado | Ação imediata | Próxima ação |
|---|---|---|
PROVIDER_RESULT_UNKNOWN | Monitorar com GET a cada 60s | Após 15min sem resolução: escalar |
RECONCILIATION_REQUIRED | Abrir ticket de suporte com id e X-Correlation-ID | Aguardar resolução; não concluir internamente |
Cash-out falhado inesperadamente
Sintoma: cash-out vai aFAILED sem causa aparente.
| Verificação | Ação |
|---|---|
| Saldo suficiente na conta? | Consultar ledger e saldo disponível |
| Chave Pix do destinatário válida? | Verificar formato e tipo em pixKey/pixKeyType |
| BaaS rejeitou por regra interna? | Consultar mensagem de erro no GET /api/pix/cash-out/{id} |
| Reserva foi liberada? | Status RELEASED confirma liberação; saldo retornou |
Inconsistência entre consulta e notificação
Sintoma: GET retornaCONFIRMED mas o webhook diz FAILED (ou vice-versa).
Regra: GET /.../{id} é o dado mais recente e autoritativo. Webhooks são at-least-once e podem chegar fora de ordem.
| Situação | Ação |
|---|---|
| GET mais avançado que webhook | Confiar no GET; webhook estava atrasado ou desordenado |
| Webhook mais avançado que GET | Aguardar consistência eventual (segundos) e consultar novamente |
| Discordância persistente | Abrir ticket com ambos os dados para análise |