Skip to main content

​
O que você implementa

Um endpoint POST público acessível via HTTPS que recebe notificações assinadas da ClearPago. A plataforma envia um POST com Content-Type: application/json e o header Digital-Signature em cada evento relevante. Você não implementa os webhooks de entrada do parceiro BaaS — esses ficam dentro da plataforma.

​
Registrar seu endpoint

Antes de receber notificações, registre sua URL: 
curl -X POST https://api.clearpago.com.br/webhook \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema.com/webhooks/pix",
    "events": ["pix_cash_in", "pix_cash_out", "pix_cash_in_reversal", "pix_cash_out_reversal"]
  }'
TODO: confirmar o corpo exato de POST /webhook com a spec interna.

​
Formato HTTP da notificação

POST https://seu-sistema.com/webhooks/pix
Content-Type: application/json
Digital-Signature: <base64(ECDSA P-256 SHA-256(rawBody))>

​
Eventos suportados

event_typeCondição de disparo
pix_cash_inCash-in atinge PAID ou FAILED
pix_cash_outCash-out atinge CONFIRMED ou FAILED
pix_cash_in_reversalRefund-in atinge CONFIRMED ou FAILED
pix_cash_out_reversalCash-out previamente CONFIRMED é REVERSED

​
Payloads por evento

​
pix_cash_in

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

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

{
  "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"
  }
}
event.id em pix_cash_in_reversal é o UUID do cash-in original, não do refund-in. O event.external_id é o externalId do refund-in. Para idempotência, use transaction_id + end_to_end_id do estorno.

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

​
Resposta esperada

  • Tempo: responda 2xx em menos de 5 segundos.
  • Código: 200 ou 204.
  • Corpo: pode ser vazio.
  • Em caso de erro: 5xx gera retentativa com backoff; 4xx pode não gerar retentativa.

​
Segurança

  1. Verificar Digital-Signature antes de qualquer lógica.
  2. Rejeitar com 401 se inválida.
  3. Usar HTTPS com certificado público válido.
  4. Nunca processar payload sem assinatura verificada.

​
Retry e backoff

A plataforma realiza retentativas em caso de 5xx ou timeout usando backoff exponencial. Por isso:
  • Handlers devem ser idempotentes.
  • Responda 2xx assim que a assinatura for verificada; não aguarde o processamento completo.

​
Canais de entrega

Tipo de operaçãoCanalCaracterística
Cash-in, refund-inOutbox (commit-first)Entrega durável, latência baixa a moderada
Cash-out, reversãoPool de goroutines + fallback SQSGeralmente baixa latência; SQS em alta carga
Não assuma ordem garantida entre eventos. Deduplicação é sempre necessária.

​
Referências