# ClearPago

> Documentação oficial da API Pix ClearPago — integração, referência e operações.

## Docs

- [POST /api/pix/cash-in](https://docs.clearpago.com/api-reference/create-cash-in.md): Criar cobrança Pix; retorna 201 com id, status (geralmente PENDING) e opcionalmente pixCode (EMV).
- [POST /api/pix/cash-out](https://docs.clearpago.com/api-reference/create-cash-out.md): Criar envio por chave Pix; 201 com estado pós-reserva e pipeline (ver status-model).
- [POST /api/pix/cash-out-qrcode](https://docs.clearpago.com/api-reference/create-cash-out-qrcode.md): Pagamento Pix a partir de string EMV (pix copia e cola); mesmo ciclo de cash-out.
- [POST /api/pix/refund-in/{id}](https://docs.clearpago.com/api-reference/create-refund-in.md): Solicita devolução (refund-in) — {id} é o UUID do cash-in, não o transactionId do parceiro.
- [DELETE /webhook/{webhook_id}](https://docs.clearpago.com/api-reference/delete-webhook.md): Remove um webhook registrado; sem corpo de exemplo no documento origem.
- [GET /organization/balance](https://docs.clearpago.com/api-reference/get-balance.md): Consulta o saldo disponível da organização em todas as moedas configuradas.
- [GET /api/pix/cash-in/{id}](https://docs.clearpago.com/api-reference/get-cash-in.md): Detalhe de um cash-in pelo UUID (id) retornado na criação.
- [GET /api/pix/cash-out/{id}](https://docs.clearpago.com/api-reference/get-cash-out.md): Detalhe de um cash-out; exibe reserva, teto de tarifa e estados de pipeline, incl. DISPATCHED.
- [GET /api/pix/ledger/{id}](https://docs.clearpago.com/api-reference/get-ledger-entry.md): Obtém uma entrada do ledger por UUID.
- [GET /public-key](https://docs.clearpago.com/api-reference/get-public-key.md): Chave pública PEM para verificação de Digital-Signature (webhooks ao comerciante).
- [GET /api/pix/refund/{id}](https://docs.clearpago.com/api-reference/get-refund.md): Detalhe de um refund-in pelo UUID do refund; não use o id do cash-in neste path.
- [GET /api/pix/cash-in](https://docs.clearpago.com/api-reference/list-cash-ins.md): Listar cash-ins com paginação, filtros de status e intervalo de datas (inclusivo, YYYY-MM-DD).
- [GET /api/pix/cash-out](https://docs.clearpago.com/api-reference/list-cash-outs.md): Listar cash-outs com page, limit, status e datas (inclusivas, YYYY-MM-DD).
- [GET /api/pix/ledger](https://docs.clearpago.com/api-reference/list-ledger-entries.md): Lista de lançamentos do livro-caixa; paginação preferencialmente por cursor, filtros e datas inclusivas.
- [GET /api/pix/refund](https://docs.clearpago.com/api-reference/list-refunds.md): Lista de refund-in com page, limit, status (PENDING, CONFIRMED, FAILED) e intervalo de datas.
- [GET /webhook](https://docs.clearpago.com/api-reference/list-webhooks.md): Lista inscrições de webhooks (estrutura de resposta não detalhada no documento origem).
- [POST /webhook (registro de notificações)](https://docs.clearpago.com/api-reference/register-webhook.md): Registra a URL pública e os eventos desejados. Corpo: TODO (não consta no documento fonte).
- [Arquitetura](https://docs.clearpago.com/core-concepts/architecture.md): Visão lógica da integração ClearPago: componentes, fluxos e responsabilidades de cada parte.
- [Idempotência e correlação](https://docs.clearpago.com/core-concepts/idempotency-and-correlation.md): externalId, X-Correlation-ID, deduplicação de webhooks e armazenamento do lado do integrador.
- [Modelo de identidade](https://docs.clearpago.com/core-concepts/identity-model.md): id, externalId, transactionId e endToEndId — quem define, persistência e uso em refund e suporte.
- [Ledger e saldo](https://docs.clearpago.com/core-concepts/ledger-and-balance.md): O que é o ledger, quando lançamentos são criados, relação com saldo e como consultar e interpretar entradas.
- [Modelo de status](https://docs.clearpago.com/core-concepts/status-model.md): Status de cash-in, cash-out e refund-in, estados intermediários, terminalidade e ação do integrador.
- [Ciclo de vida das operações](https://docs.clearpago.com/core-concepts/transaction-lifecycle.md): Grandes fluxos: cash-in, cash-out, refund-in, reversão, como os eventos chegam e reação do integrador.
- [Códigos, sintomas e ações](https://docs.clearpago.com/errors/error-codes.md): Tabelas de HTTP, erros de refund, troubleshooting de integração (token, externalId, webhooks, QR, estados ambíguos).
- [Tratamento de erros](https://docs.clearpago.com/errors/error-handling.md): Envelope, HTTP, retentativas, divergência webhook vs. GET e o que fazer com estados ambíguos.
- [Troubleshooting](https://docs.clearpago.com/errors/troubleshooting.md): Diagnóstico passo a passo para os problemas mais comuns: token, payload, externalId, webhook, assinatura, QR, refund e estados ambíguos.
- [Perguntas frequentes](https://docs.clearpago.com/faq/index.md): Perguntas de integração sobre IDs, cash-in pago, cash-out confirmado, refund, assinaturas, idempotência e reconciliação.
- [Autenticação](https://docs.clearpago.com/getting-started/authentication.md): Bearer token, geração via POST /api-key/generate e boas práticas de segredo.
- [Ambientes, headers e convenções](https://docs.clearpago.com/getting-started/environments-and-headers.md): Base URL, headers padrão, X-Correlation-ID, datas, dinheiro e códigos HTTP.
- [Checklist de primeira integração](https://docs.clearpago.com/getting-started/first-integration-checklist.md): Lista de verificação para ter a primeira integração ClearPago funcionando corretamente em ambiente de teste.
- [Visão geral](https://docs.clearpago.com/getting-started/overview.md): Papel da clearpago, modelo assíncrono e o porquê de IDs, webhooks e reconciliação.
- [Quickstart](https://docs.clearpago.com/getting-started/quickstart.md): Fluxo mínimo: token, cash-in, webhook, consulta e registro de webhook do comerciante.
- [Checklist de observabilidade](https://docs.clearpago.com/go-live/observability-checklist.md): Logs, métricas, alertas, correlation ID e reconciliação operacional para manter a integração saudável em produção.
- [Checklist de produção](https://docs.clearpago.com/go-live/production-checklist.md): Lista de verificação obrigatória antes de ir a produção com a integração ClearPago.
- [Checklist de segurança](https://docs.clearpago.com/go-live/security-checklist.md): Requisitos de segurança para a integração ClearPago: tokens, assinaturas, TLS, LGPD e boas práticas de logs.
- [Lidar com reversão de cash-out](https://docs.clearpago.com/guides/handle-cash-out-reversal.md): O que é reversão de cash-out, como o webhook chega, impacto no ledger e como o sistema integrador deve reagir.
- [Receber Pix (Cash-in)](https://docs.clearpago.com/guides/receive-pix-cash-in.md): Fluxo completo de recebimento: criar cobrança, gerar QR Code, monitorar pagamento via webhook e consultar status.
- [Reconciliar transações](https://docs.clearpago.com/guides/reconcile-transactions.md): Quando usar reconciliação, como tratar estados ambíguos, divergências entre webhook e GET, e práticas operacionais.
- [Devolver um cash-in (Refund-in)](https://docs.clearpago.com/guides/refund-a-cash-in.md): Como solicitar devolução de um recebimento Pix: regras de negócio, prazo de 89 dias, devoluções parciais e auditoria.
- [Registrar webhooks do comerciante](https://docs.clearpago.com/guides/register-merchant-webhooks.md): Como registrar, listar e remover webhooks de notificação; eventos suportados e boas práticas de implementação.
- [Enviar Pix por chave (Cash-out)](https://docs.clearpago.com/guides/send-pix-cash-out-key.md): Fluxo completo de envio por chave Pix: criação, reserva, despacho, confirmação, falha e reconciliação.
- [Enviar Pix por QR Code (Cash-out QR)](https://docs.clearpago.com/guides/send-pix-cash-out-qrcode.md): Fluxo de pagamento a partir de string EMV (pix copia e cola); diferenças em relação ao cash-out por chave.
- [Verificar assinaturas de webhook](https://docs.clearpago.com/guides/verify-webhook-signatures.md): Como validar o header Digital-Signature com ECDSA P-256 SHA-256; boas práticas, cache da chave pública e exemplos de código.
- [ClearPago — API Pix](https://docs.clearpago.com/index.md): Documentação oficial da API Pix ClearPago. Integre recebimento, envio, devoluções e webhooks em minutos.
- [Ledger — Visão geral](https://docs.clearpago.com/ledger-and-reconciliation/ledger-overview.md): O que é o ledger da ClearPago, quando lançamentos são criados, como consultar e como interpretar créditos e débitos.
- [Monitoramento operacional](https://docs.clearpago.com/ledger-and-reconciliation/operational-monitoring.md): O que monitorar, como detectar operações presas, divergências entre webhook e consulta, e práticas de suporte a incidentes.
- [Reconciliação](https://docs.clearpago.com/ledger-and-reconciliation/reconciliation.md): Por que existe reconciliação, quando ela é acionada, como o integrador deve agir e quando escalar.
- [Webhooks: ClearPago → comerciante](https://docs.clearpago.com/webhooks/clearpago-to-merchant.md): O que o comerciante implementa: endpoint receptor, Digital-Signature ECDSA P-256 SHA-256, eventos, retry e boas práticas.
- [Webhooks: parceiro → ClearPago](https://docs.clearpago.com/webhooks/partner-to-clearpago.md): Visão dos webhooks inbound (BaaS → plataforma): eventos, processamento interno e o que o integrador precisa saber.
- [Referência de payloads (webhooks)](https://docs.clearpago.com/webhooks/webhook-event-reference.md): Semântica de event_type, event.id, deduplicação, exemplos de comerciante e apêndice de parceiro.

## OpenAPI Specs

- [openapi](https://docs.clearpago.com/api-reference/openapi.json)