Pré-requisitos
- URL base:
https://api.clearpago.com.br - Token (Bearer) obtido conforme Autenticação
X-Correlation-ID(string ou UUID) em cada chamada — recomendado
1
1. Obter token de API
Use
POST /api-key/generate com o token administrativo. Guarde o apiKey retornado.2
2. Criar cash-in
POST /api/pix/cash-in com valor em reais, externalId único e, se desejar QR, generateQrCode: true.id (UUID do cash-in) e, em geral, status PENDING. Persista id e externalId.3
3. Receber webhook (comerciante)
Efetue o pagamento no ambiente de teste ou produção. A plataforma notificará a URL que você registrar com POST /webhook (evento
pix_cash_in).Valide a assinatura Digital-Signature sobre o corpo bruto (ver Verificar assinaturas). Responda 2xx em poucos segundos; processe o negócio de forma assíncrona se necessário.4
4. Consultar transação
Use o UUID do passo 2:
GET /api/pix/cash-in/{id}. O sucesso financeiro para “liberar” o pedido em integração comum ocorre quando o status de domínio for PAID (e webhooks/ledger alinhados à sua política). Veja Receber cash-in.5
5. Registrar webhook do comerciante (se ainda não fez)
POST /webhook com a URL pública e a lista de eventos necessários. Detalhe de payload: clearpago → comerciante.TODO: corpo exato (JSON) de POST /webhook — não consta o exemplo no documento de origem; alinhar com o suporte ou especificação OpenAPI interna.O que acompanhar em seguida
- Modelo de identidade —
refund-inusa o UUID do cash-in no path. - Semântica de
event.idnos webhooks ao comerciante. - Checklist de go-live