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

# Referência de payloads (webhooks)

> Semântica de event_type, event.id, deduplicação, exemplos de comerciante e apêndice de parceiro.

## Comerciante (clearpago → seu sistema)

### Estrutura geral

```http theme={null}
Content-Type: application/json
Digital-Signature: <base64>
```

```json theme={null}
{
  "event_type": "pix_cash_in",
  "event": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "correlation_id": "req-001",
    "external_id": "pedido-12345",
    "transaction_id": "12345",
    "status": "PAID",
    "value_cents": 15075,
    "end_to_end_id": "E00416968202504011200rjzxxzSSTD9",
    "payer_name": "João da Silva",
    "fee_amount_cents": 5,
    "confirmed_at": "2026-04-01T12:10:00.000000000Z",
    "created_at": "2026-04-01T12:00:00.000000000Z"
  }
}
```

### Semântica de `event.id` e `event.external_id` (crítico)

| `event_type`            | `event.id`                                  | `event.external_id`                     |
| ----------------------- | ------------------------------------------- | --------------------------------------- |
| `pix_cash_in`           | UUID do **cash-in**                         | `externalId` do **cash-in**             |
| `pix_cash_out`          | UUID do **cash-out**                        | `externalId` do **cash-out**            |
| `pix_cash_in_reversal`  | UUID do **cash-in original** (não o refund) | `externalId` do **refund-in** (estorno) |
| `pix_cash_out_reversal` | UUID do **cash-out**                        | `externalId` do **cash-out**            |

**Idempotência:** a origem recomenda chave composta **adequada** ao evento. Para `pix_cash_in_reversal`, além de `id` (cash-in), use `transaction_id` e `end_to_end_id` do **estorno** para evitar colisão entre múltiplos parciais.

### `pix_cash_in` (recebido, `PAID`)

```json theme={null}
{
  "event_type": "pix_cash_in",
  "event": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "correlation_id": "req-001",
    "external_id": "pedido-12345",
    "transaction_id": "12345",
    "status": "PAID",
    "value_cents": 15075,
    "end_to_end_id": "E00416968202504011200rjzxxzSSTD9",
    "payer_name": "João da Silva",
    "fee_amount_cents": 5,
    "confirmed_at": "2026-04-01T12:10:00.000000000Z",
    "created_at": "2026-04-01T12:00:00.000000000Z"
  }
}
```

### `pix_cash_out` (confirmado)

```json theme={null}
{
  "event_type": "pix_cash_out",
  "event": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "correlation_id": "transfer-001",
    "external_id": "saque-789",
    "transaction_id": "54321",
    "status": "CONFIRMED",
    "value_cents": 50000,
    "end_to_end_id": "E07136847202504011200O7654ABCD12",
    "fee_amount_cents": 10,
    "confirmed_at": "2026-04-01T12:30:00.000000000Z",
    "created_at": "2026-04-01T12:00:00.000000000Z"
  }
}
```

### `pix_cash_in_reversal` (estorno de recebimento)

Aqui `event.id` = **UUID do cash-in original**; `event.external_id` = **`externalId` do refund-in**.

```json theme={null}
{
  "event_type": "pix_cash_in_reversal",
  "event": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "correlation_id": "req-001",
    "external_id": "estorno-12345",
    "transaction_id": "11111",
    "status": "CONFIRMED",
    "value_cents": 15075,
    "end_to_end_id": "D07136847202504011500O5222ZRBI5A",
    "fee_amount_cents": 1,
    "confirmed_at": "2026-04-01T15:05:00.000000000Z",
    "created_at": "2026-04-01T15:00:00.000000000Z"
  }
}
```

Use preferencialmente o par `transaction_id` + `end_to_end_id` do estorno para idempotência, ou o `id` do refund visto em `GET /api/pix/refund/{id}`.

### `pix_cash_out_reversal`

```json theme={null}
{
  "event_type": "pix_cash_out_reversal",
  "event": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "correlation_id": "transfer-001",
    "external_id": "saque-789",
    "transaction_id": "54321",
    "status": "REVERSED",
    "value_cents": 50000,
    "end_to_end_id": "D07136847202504021600O9999ABCD99",
    "fee_amount_cents": 0,
    "confirmed_at": "2026-04-02T09:05:00.000000000Z",
    "created_at": "2026-04-01T12:00:00.000000000Z"
  }
}
```

> **Monitore** `value_cents` e documentação de **fallback** no código (metadados incompletos) para `pix_cash_out_reversal` — ref. seção 11 do documento de origem.

***

## Apêndice: parceiro (BaaS → clearpago)

Estes JSONs são úteis para suporte. **Direção:** BaaS → **clearpago** (rotas `POST /api/webhooks/pix/...`) — o **seu** sistema **não** recebe estes corpos; servem de referência.

### A) `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"
    }
  }
}
```

### B) `CashInReversal`

```json theme={null}
{
  "event": "CashInReversal",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "11111",
  "externalId": "estorno-12345",
  "endToEndId": "D07136847202504011500O5222ZRBI5A",
  "pixKey": null,
  "feeAmount": 0.01,
  "originalAmount": 150.75,
  "finalAmount": 150.76,
  "processingDate": "2026-04-01T15:00:00.000Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {},
  "parentTransaction": {
    "transactionId": "12345",
    "externalId": "PIX-5482123298-EJUYFSMU1UU",
    "endToEndId": "E00416968202504011200rjzxxzSSTD9",
    "processingDate": "2026-04-01T12:00:00.000Z",
    "wasTotalRefunded": true,
    "remainingAmountForRefund": 0.00
  }
}
```

### C) `CashOut`

```json theme={null}
{
  "event": "CashOut",
  "status": "CONFIRMED",
  "transactionId": "54321",
  "externalId": "saque-789",
  "endToEndId": "E07136847202504011200O7654ABCD12",
  "feeAmount": 0.10,
  "originalAmount": 500.00,
  "finalAmount": 500.10,
  "processingDate": "2026-04-01T12:30:00.000Z",
  "errorCode": null,
  "errorMessage": null,
  "counterpart": {
    "name": "Maria Oliveira",
    "document": "***.654.321-**",
    "bank": {
      "bankISPB": "00000000",
      "bankName": "Banco do Brasil",
      "bankCode": "001",
      "accountBranch": "5678",
      "accountNumber": "12345-6"
    }
  }
}
```

### D) `CashOutReversal`

```json theme={null}
{
  "event": "CashOutReversal",
  "status": "CONFIRMED",
  "transactionId": "99999",
  "externalId": "reversal-54321",
  "endToEndId": "D07136847202504011600O9999ABCD99",
  "feeAmount": 0.00,
  "originalAmount": 500.00,
  "finalAmount": 500.00,
  "processingDate": "2026-04-02T09:00:00.000Z",
  "errorCode": null,
  "errorMessage": null,
  "counterpart": {
    "name": "Maria Oliveira",
    "document": "***.654.321-**",
    "bank": { }
  },
  "parentTransaction": {
    "transactionId": "54321",
    "externalId": "saque-789",
    "endToEndId": "E07136847202504011200O7654ABCD12",
    "wasTotalRefunded": true,
    "remainingAmountForRefund": 0.00
  },
  "metadata": {
    "refund": {
      "value": 50000,
      "originalValue": 50000
    }
  }
}
```

***

## Deduplicação (chaves recomendadas, sumário)

* **Geral:** `event_type` + chave mínima que identifique a transição, sem confundir `event.id` entre tipos.
* **`pix_cash_in_reversal`:** força `id` = cash-in; compor com `transaction_id` + `end_to_end_id` do estorno.

## Ver

* [Idempotência](/core-concepts/idempotency-and-correlation)
* [Verificar assinaturas](/guides/verify-webhook-signatures)