Troubleshooting

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 registro

GET /webhook — confirmar que a URL está registrada e correta.

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 TLS

Certificado público válido, sem autoassinado, na URL registrada.

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.

Consultar via GET

Se o pagamento já está PAID na consulta, o estado real está correto. Reconciliar localmente e investigar a entrega em segundo plano.

Assinatura inválida

Sintoma: verificação de Digital-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

Veja Reconciliação para o fluxo completo.

Cash-out falhado inesperadamente

Sintoma: cash-out vai a FAILED 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 retorna CONFIRMED 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

Início

Introdução

Conceitos

Guias

Referência de API

Webhooks

Ledger e Reconciliação

Erros

Go-live

FAQ

Token inválido ou ausente

Payload inválido (400 / 422)

`externalId` duplicado (409)

Transação não encontrada (404)

Webhook não recebido

Assinatura inválida

QR Code expirado

Refund rejeitado

Estado ambíguo (PROVIDER_RESULT_UNKNOWN / RECONCILIATION_REQUIRED)

Cash-out falhado inesperadamente

Inconsistência entre consulta e notificação

Referências

​Token inválido ou ausente

​Payload inválido (400 / 422)

​externalId duplicado (409)

​Transação não encontrada (404)

​Webhook não recebido

​Assinatura inválida

​QR Code expirado

​Refund rejeitado

​Estado ambíguo (PROVIDER_RESULT_UNKNOWN / RECONCILIATION_REQUIRED)

​Cash-out falhado inesperadamente

​Inconsistência entre consulta e notificação

​Referências

Token inválido ou ausente

Payload inválido (400 / 422)

`externalId` duplicado (409)

Transação não encontrada (404)

Webhook não recebido

Assinatura inválida

QR Code expirado

Refund rejeitado

Estado ambíguo (PROVIDER_RESULT_UNKNOWN / RECONCILIATION_REQUIRED)

Cash-out falhado inesperadamente

Inconsistência entre consulta e notificação

Referências