Skip to main content
Use este checklist como portão de entrada antes de ativar a integração em produção. Cada item representa um requisito funcional ou operacional necessário para uma operação saudável.

​
Credenciais e ambiente

Credenciais de produção geradas e armazenadas em cofre de segredos (não em repositório).
Base URL de produção configurada: https://api.clearpago.com.br.
Nenhum token de sandbox ou desenvolvimento ativo no ambiente de produção.
Rotação de credenciais planejada e documentada internamente.

​
Webhooks

URL de produção registrada via POST /webhook com todos os eventos necessários.
Endpoint de webhook acessível publicamente via HTTPS com certificado válido.
Verificação de Digital-Signature implementada e testada em ambiente de staging.
Handler de webhook idempotente: reprocessamento não duplica efeito colateral.
Chave pública obtida de GET /public-key com cache e lógica de rotação.
Endpoint responde 2xx em menos de 5 segundos.
Lógica de negócio executada de forma assíncrona após a resposta HTTP.

​
Persistência e rastreabilidade

id (UUID) de cada recurso criado persistido imediatamente no 201.
externalId armazenado junto ao id para correlação com o seu sistema.
transactionId e endToEndId armazenados quando disponíveis (webhooks e consultas).
X-Correlation-ID sendo gerado e enviado em todas as requisições.
Logs de criação, webhook recebido e status final retidos por período adequado (mínimo 90 dias).

​
Idempotência e controle de fluxo

Criação de cash-in não é reenviada para o mesmo externalId sem intenção explícita.
Cash-out não é reenviado enquanto estiver em PROVIDER_RESULT_UNKNOWN ou RECONCILIATION_REQUIRED.
Refund não ultrapassa o teto disponível (lógica de controle no lado do integrador).
Estados intermediários monitorados e não tratados como terminais.

​
Valores monetários

Todos os campos de request enviados em BRL (ex.: 150.75).
Respostas com campos *_cents convertidos corretamente para exibição e comparação.
Nenhuma comparação direta entre valor em BRL e campo em centavos.

​
Monitoramento e alertas

Alertas configurados para transações em PROVIDER_RESULT_UNKNOWN e RECONCILIATION_REQUIRED.
Alerta para cash-ins em PENDING há mais de N minutos após expiração esperada.
Alerta para taxa de erro 5xx no endpoint de webhook.
Dashboard de saúde da integração operacional.
Runbook de resposta a incidentes documentado internamente.

​
Segurança

Todos os itens do Checklist de segurança validados.

​
Observabilidade

Todos os itens do Checklist de observabilidade validados.

​
Testes de aceitação

Fluxo de cash-in (criação → pagamento → webhook pix_cash_in → GET confirmado) testado end-to-end.
Fluxo de cash-out (criação → CONFIRMED → webhook pix_cash_out) testado.
Fluxo de refund-in (POST refund-in/{id} → webhook pix_cash_in_reversal) testado.
Handler de webhook idempotente testado com reenvio do mesmo payload.
Falha de assinatura testada: endpoint retorna 401.
Tratamento de externalId duplicado (409) testado.

​
Contato de suporte

TODO: confirmar canal oficial de suporte técnico para produção. Em produção, acione o suporte com:
  • id da transação afetada
  • X-Correlation-ID das chamadas
  • Timestamp do problema
  • Status atual (GET /.../{id})
  • Logs relevantes do seu sistema
Endereço atual de suporte: tech@clearpago.com.br