Papel da plataforma
A clearpago atua como camada entre o seu sistema e o parceiro bancário (BaaS Fire). Você consome somente a API REST e as notificações HTTP assinadas; diferenças de instituição, transporte e mapeamento de eventos permanecem encapsuladas. Este portal é a documentação ClearPago dessa integração: contrato técnico, fluxos e boas práticas para o time de integração.Modelo assíncrono (padrão)
- Criação rápida:
POSTde cash-in, cash-out e refund costuma retornar com estado ainda em evolução (PENDING, reserva, etc.). - Conclusão fora do request/response primário: a liquidação e falhas finais chegam via webhook do parceiro processado internamente e/ou reconciliação quando a rede ou o parceiro responde de forma ambígua (timeout, 5xx, atraso).
- Não trate o corpo de resposta de criação como estado terminal salvo o que o documento de status explicitar para o seu caso.
Por que id, webhooks e reconciliação importam
| Tema | Motivo prático |
|---|---|
id (UUID) | Chave primária do recurso na plataforma: consultas, POST /api/pix/refund-in/{id} com UUID do cash-in, auditoria. |
externalId | Sua chave de negócio: idempotência e correlação com ERP; deve ser única onde a API exigir. |
| Webhooks ao comerciante | Sinal principal de término relevante (ex.: PAID, CONFIRMED, FAILED, REVERSED) de forma assinada. |
| Reconciliação | Destrava estados como PROVIDER_RESULT_UNKNOWN e RECONCILIATION_REQUIRED com consulta autoritativa no BaaS, deduplicando com webhooks atrasados. |
Componentes que afetam sua integração
| Componente | Função |
|---|---|
API /api/pix/* | Criar e consultar cash-in, cash-out, refund-in, ledger. |
Webhooks POST /api/webhooks/pix/* | Entrada de eventos do parceiro (não implementados no seu sistema). Resposta 200 rápida; processamento assíncrono. |
| Workers de reconciliação | Consultam status no parceiro em estados intermediários ou ambíguos. |
| Outbox de notificações | Entrega durável de notificações ao comerciante após commit (cash-in e refund-in usam este caminho). |
| Ledger | Registro de créditos e débitos por operação Pix confirmada. |