Webhooks: parceiro → ClearPago

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
  }
}

Mapeamento de campos BaaS → plataforma

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.

Início

Introdução

Conceitos

Guias

Referência de API

Webhooks

Ledger e Reconciliação

Erros

Go-live

FAQ

Webhooks: parceiro → ClearPago

Contexto

Por que conhecer esses webhooks

Eventos do parceiro

Payload de referência: `CashIn`

Payload de referência: `CashInReversal`

Mapeamento de campos BaaS → plataforma

Autenticação do parceiro (entrada)

Processamento assíncrono

Referências

​Contexto

​Por que conhecer esses webhooks

​Eventos do parceiro

​Payload de referência: CashIn

​Payload de referência: CashInReversal

​Mapeamento de campos BaaS → plataforma

​Autenticação do parceiro (entrada)

​Processamento assíncrono

​Referências

Contexto

Por que conhecer esses webhooks

Eventos do parceiro

Payload de referência: `CashIn`

Payload de referência: `CashInReversal`

Mapeamento de campos BaaS → plataforma

Autenticação do parceiro (entrada)

Processamento assíncrono

Referências