Credenciais e ambiente
Token Bearer gerado via
POST /api-key/generate e armazenado em variável de ambiente (não no repositório).Base URL configurada corretamente:
https://api.clearpago.com.br.Header
Authorization: Bearer <token> presente em todas as chamadas autenticadas.Header
Content-Type: application/json presente em todos os POST com corpo.X-Correlation-ID sendo gerado e enviado em cada requisição para rastreabilidade.Cash-in
Criação de cash-in retorna
201 com id (UUID) e status: PENDING.UUID do cash-in persistido na base do seu sistema imediatamente após o
201.externalId único por cobrança; colisões retornam 409 e estão sendo tratadas.QR Code EMV (
pixCode) presente na resposta quando generateQrCode: true.expirationDate lido e exibido corretamente ao usuário/sistema.GET /api/pix/cash-in/{id} funcionando e retornando o status atual.Webhook do comerciante
Endpoint
POST público configurado e acessível via HTTPS.URL registrada via
POST /webhook com os eventos pix_cash_in, pix_cash_out, pix_cash_in_reversal, pix_cash_out_reversal.Chave pública obtida de
GET /public-key e armazenada (com TTL de cache definido).Verificação de
Digital-Signature implementada: ECDSA P-256 + SHA-256 sobre o corpo bruto.Handler de webhook retorna 2xx em menos de 5 segundos.
Lógica de negócio executada após a resposta HTTP (fila ou processamento assíncrono).
Handler idempotente: o mesmo evento entregue duas vezes não duplica efeito colateral.
Chave de idempotência definida: pelo menos
event_type + event.id + transição de status.Cash-out (se aplicável)
POST /api/pix/cash-out retorna 201 com id e estado de reserva.UUID do cash-out persistido imediatamente.
Webhook
pix_cash_out processado corretamente ao receber status CONFIRMED.Estado
PROVIDER_RESULT_UNKNOWN e RECONCILIATION_REQUIRED não tratados como terminais.Refund-in (se aplicável)
POST /api/pix/refund-in/{id} usando o UUID do cash-in (não o transactionId do parceiro).refundValue em BRL (não em centavos) no request.UUID do refund-in retornado no
201 persistido para auditoria.Webhook
pix_cash_in_reversal deduplicando por transaction_id + end_to_end_id do estorno (não só por event.id).Valores monetários
Requests enviados com valores em BRL (ex.:
150.75).Responses com campos
*_cents convertidos corretamente antes de comparação ou exibição.Nenhuma comparação direta entre campo BRL e campo centavos no seu código.
Estados e erros
HTTP
4xx com corpo de erro lido e logado (nunca silenciado).409 em externalId duplicado capturado e tratado (não gera novo recurso sem intenção).PROVIDER_RESULT_UNKNOWN e RECONCILIATION_REQUIRED monitorados e não marcados como sucesso/falha prematuramente.