Skip to main content

​
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_typeevent.idevent.external_id
pix_cash_inUUID do cash-inexternalId do cash-in
pix_cash_outUUID do cash-outexternalId do cash-out
pix_cash_in_reversalUUID do cash-in original (não o refund)externalId do refund-in (estorno)
pix_cash_out_reversalUUID do cash-outexternalId 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.

​
Ver