Contexto
Os webhooks de entrada são chamadas HTTP que o parceiro BaaS faz para a ClearPago quando um evento Pix ocorre — liquidação, falha, devolução, reversão. Eles entram em rotas como POST /api/webhooks/pix/cash-in, POST /api/webhooks/pix/cash-out, etc.
O seu sistema não implementa esses endpoints. Eles existem na plataforma ClearPago. Esta página é documentação de referência para fins de suporte, auditoria e entendimento do fluxo interno.
Por que conhecer esses webhooks
- Suporte a incidentes: entender o payload do parceiro ajuda a diagnosticar por que uma transação ficou presa.
- Auditoria: o
endToEndId do BaaS é o identificador regulatório definitivo de uma operação Pix.
- Mapeamento de estados: o
status do parceiro é traduzido para o status interno da plataforma (ex.: CONFIRMED → PAID em cash-in).
Eventos do parceiro
| Evento BaaS | Recurso afetado | Efeito interno |
|---|
CashIn com CONFIRMED | Cash-in | Status → PAID, ledger crédito, notificação ao comerciante |
CashIn com FAILED / CANCELLED | Cash-in | Status → FAILED |
CashInReversal com CONFIRMED | Refund-in | Status → CONFIRMED, ledger débito, notificação ao comerciante |
CashOut com CONFIRMED | Cash-out | Status → CONFIRMED, ledger débito |
CashOut com FAILED | Cash-out | Status → FAILED, reserva liberada |
CashOutReversal | Cash-out | Status → REVERSED, ledger crédito, notificação ao comerciante |
Payload de referência: CashIn
{
"event": "CashIn",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "CREDIT",
"transactionId": "12345",
"externalId": "PIX-5482123298-EJUYFSMU1UU",
"endToEndId": "E00416968202512111942rjzxxzSSTD9",
"pixKey": "empresa@email.com",
"feeAmount": 0.05,
"originalAmount": 150.75,
"finalAmount": 150.75,
"processingDate": "2026-04-01T12:00:00.000Z",
"errorCode": null,
"errorMessage": null,
"metadata": {},
"counterpart": {
"name": "João da Silva",
"document": "***.456.789-**",
"bank": {
"bankISPB": "60701190",
"bankName": "Itaú Unibanco",
"bankCode": "341",
"accountBranch": "1234",
"accountNumber": "56789-0"
}
}
}
Payload de referência: CashInReversal
{
"event": "CashInReversal",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "11111",
"externalId": "estorno-12345",
"endToEndId": "D07136847202504011500O5222ZRBI5A",
"feeAmount": 0.01,
"originalAmount": 150.75,
"finalAmount": 150.76,
"processingDate": "2026-04-01T15:00:00.000Z",
"parentTransaction": {
"transactionId": "12345",
"externalId": "PIX-5482123298-EJUYFSMU1UU",
"endToEndId": "E00416968202504011200rjzxxzSSTD9",
"processingDate": "2026-04-01T12:00:00.000Z",
"wasTotalRefunded": true,
"remainingAmountForRefund": 0.00
}
}
| Campo BaaS | Campo interno / webhook comerciante |
|---|
transactionId | transaction_id no webhook ao comerciante |
endToEndId | end_to_end_id no webhook ao comerciante |
externalId (BaaS) | Interno — diferente do externalId do integrador |
status: CONFIRMED (CashIn) | Status do cash-in: PAID |
status: CONFIRMED (CashOut) | Status do cash-out: CONFIRMED |
finalAmount | value_cents (em centavos) no webhook ao comerciante |
Autenticação do parceiro (entrada)
TODO: mecanismo de autenticação dos webhooks inbound (HMAC com timestamp, IP allowlist, etc.) — não detalhado na documentação de origem disponível. Confirmar com a equipe de plataforma para fins de segurança da rota de entrada.
Processamento assíncrono
O recebimento do webhook do parceiro é assíncrono:
- A plataforma recebe e responde 200 imediatamente.
- O evento é enfileirado (SQS / fila interna).
- Workers processam: atualizam status, gravam ledger, disparam outbox de notificação ao comerciante.
Isso significa que há um delay entre o evento do BaaS e a notificação ao seu sistema. Em condições normais, esse delay é de segundos. Em alta carga ou falha de worker, pode ser maior — daí a importância de monitoring e reconciliação.
Referências
