> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks: parceiro → ClearPago

> Visão dos webhooks inbound (BaaS → plataforma): eventos, processamento interno e o que o integrador precisa saber.

## 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.

<Note>
  **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.
</Note>

## 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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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:

1. A plataforma recebe e responde **200** imediatamente.
2. O evento é enfileirado (SQS / fila interna).
3. 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](/guides/reconcile-transactions).

## Referências

* [Webhooks: ClearPago → comerciante](/webhooks/clearpago-to-merchant)
* [Referência de eventos](/webhooks/webhook-event-reference)
* [Arquitetura da integração](/core-concepts/architecture)