Referência de payloads (webhooks)

Comerciante (clearpago → seu sistema)

Estrutura geral

Content-Type: application/json
Digital-Signature: <base64>

{
  "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`)

{
  "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)

{
  "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.

{
  "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`

{
  "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`

{
  "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`

{
  "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`

{
  "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`

{
  "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.

Início

Introdução

Conceitos

Guias

Referência de API

Webhooks

Ledger e Reconciliação

Erros

Go-live

FAQ

Referência de payloads (webhooks)

Comerciante (clearpago → seu sistema)

Estrutura geral

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

`pix_cash_in` (recebido, `PAID`)

`pix_cash_out` (confirmado)

`pix_cash_in_reversal` (estorno de recebimento)

`pix_cash_out_reversal`

Apêndice: parceiro (BaaS → clearpago)

A) `CashIn`

B) `CashInReversal`

C) `CashOut`

D) `CashOutReversal`

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

Ver

​Comerciante (clearpago → seu sistema)

​Estrutura geral

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

​pix_cash_in (recebido, PAID)

​pix_cash_out (confirmado)

​pix_cash_in_reversal (estorno de recebimento)

​pix_cash_out_reversal

​Apêndice: parceiro (BaaS → clearpago)

​A) CashIn

​B) CashInReversal

​C) CashOut

​D) CashOutReversal

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

​Ver

Comerciante (clearpago → seu sistema)

Estrutura geral

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

`pix_cash_in` (recebido, `PAID`)

`pix_cash_out` (confirmado)

`pix_cash_in_reversal` (estorno de recebimento)

`pix_cash_out_reversal`

Apêndice: parceiro (BaaS → clearpago)

A) `CashIn`

B) `CashInReversal`

C) `CashOut`

D) `CashOutReversal`

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

Ver