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
Parceiro BaaS
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
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
