Visão geral
A integração ClearPago envolve três camadas principais: o seu sistema, a plataforma ClearPago e o parceiro BaaS. Cada camada tem responsabilidades bem definidas.
Responsabilidades por camada
Seu sistema
| Componente | Responsabilidade |
|---|
| Cliente HTTP | Chama POST e GET na API REST. Inclui Authorization, Content-Type e X-Correlation-ID. |
| Endpoint de webhook | Recebe POST com Digital-Signature, valida a assinatura e responde 2xx rapidamente. |
| Banco de dados | Persiste id, externalId, transactionId, endToEndId e status de cada recurso. |
| Componente | Responsabilidade |
|---|
| API REST | Valida, cria e persiste recursos Pix. Faz despacho inicial ao BaaS em operações de cash-out. |
| Webhooks de entrada | Recebe eventos CashIn, CashOut, CashInReversal, CashOutReversal do parceiro. Não são implementados pelo integrador. |
| Fila de eventos | Desacopla recebimento de eventos do processamento. Garante durabilidade. |
| Workers | Aplicam transições de status, gravam ledger e enfileiram notificações ao comerciante. |
| Outbox | Garante entrega durável de notificações ao comerciante com retry e backoff. |
| Reconciliação | Consulta o BaaS periodicamente em estados intermediários ou ambíguos (PROVIDER_RESULT_UNKNOWN, RECONCILIATION_REQUIRED). |
Parceiro BaaS
| Componente | Responsabilidade |
|---|
| Pix / Liquidação | Processa pagamentos Pix, confirma ou rejeita, emite eventos de resultado. |
Fluxo de um cash-in
- Seu sistema chama
POST /api/pix/cash-in → plataforma retorna 201 com id, status: PENDING e pixCode.
- O pagador escaneia o QR e liquida no BaaS.
- O BaaS notifica a plataforma via
POST /api/webhooks/pix/cash-in (interno).
- Worker transiciona o status para
PAID, grava lançamento no ledger, enfileira notificação ao comerciante.
- Outbox entrega
POST com event_type: pix_cash_in e Digital-Signature ao seu endpoint.
- Você valida a assinatura e executa a lógica de negócio (ex.: liberar pedido).
Fluxo de um cash-out
POST /api/pix/cash-out → reserva criada, estado inicial.- Plataforma despacha para o BaaS; resultado pode ser imediato ou assíncrono.
- Resposta ambígua (timeout, 5xx) → estado
PROVIDER_RESULT_UNKNOWN → reconciliação resolve.
- BaaS confirma →
CONFIRMED; BaaS falha → FAILED e reserva liberada.
- Comerciante recebe
pix_cash_out com resultado final.
Modelo de entrega de notificações
| Tipo de operação | Canal de notificação | Latência esperada |
|---|
| Cash-in, refund-in | Outbox (durável, commit-first) | Baixa a moderada |
| Cash-out, reversão | Pool de goroutines + fallback SQS | Geralmente baixa; SQS em alta carga |
Não conte com ordem garantida entre eventos de canais diferentes. Deduplicação e ordenação por identificadores de negócio são sua responsabilidade.
Implicações para o integrador
- Não trate o
POST de criação como terminal. O status retornado é o estado no momento do commit; o estado final chega via webhook ou consulta.
- Implemente idempotência. Webhooks podem reentrar; seu handler deve ser seguro para execução múltipla.
- Persista
id cedo. Antes de qualquer lógica de negócio, grave o UUID retornado.
- Monitore estados ambíguos.
PROVIDER_RESULT_UNKNOWN e RECONCILIATION_REQUIRED não são terminais — monitore a idade e consulte via GET antes de escalar.
Referências
