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

# Perguntas frequentes

> Perguntas de integração sobre IDs, cash-in pago, cash-out confirmado, refund, assinaturas, idempotência e reconciliação.

### Qual identificador devo armazenar?

**Mínimo:** o **`id`** (UUID) retornado pela plataforma em toda criação. **Também** o **`externalId`** que você enviou. Guarde ainda `transactionId` e `endToEndId` quando retornos ou webhooks os trouxerem, para rastreio e conciliação. Ver [identidade](/core-concepts/identity-model).

### Posso integrar só com `externalId` para consulta?

A API referencia a consulta de detalhe por **UUID** (`/api/pix/.../{id}`). O `externalId` é sua chave de negócio, mas a **primária** da plataforma é o `id` — persistindo ambos, você evita ambiguidade. `TODO: endpoint de get-by-externalId` se existir, não consta claramente na origem.

### Quando considerar o cash-in “pago”?

Quando o status de domínio for **`PAID`** (via consulta coerente com o [modelo de status](/core-concepts/status-model)), alinhado à sua política de *ledger* e ao webhook `pix_cash_in`. **Não** conclua em `PENDING` ou em estados ambíguos.

### Quando o cash-out está realmente confirmado?

`CONFIRMED` após o pipeline (incluindo passagem por reserva/despacho; ver [envio por chave](/guides/send-pix-cash-out-key)). **Não** conclua em `PROVIDER_RESULT_UNKNOWN` sem evidência; aguarde reconciliação ou ação corretiva.

### Como tratar reversão de cash-out?

O cash-out passa a **`REVERSED`**; há crédito no ledger. Webhook: `pix_cash_out_reversal` — atenção a `value_cents` e *fallback* documentado. Ver [guia](/guides/handle-cash-out-reversal).

### Como validar a assinatura do webhook?

Leia a chave pública de `/public-key` e valide o **body bruto** com **ECDSA P-256 + SHA-256** no header `Digital-Signature`. [Passo a passo](/guides/verify-webhook-signatures).

### Como evitar processar o mesmo evento duas vezes?

Idempotência no handler: trate **reentregas** com chave mínima por evento. Para `pix_cash_in_reversal`, a origem chama atenção para **não** colidir *parciais* — compor com `transaction_id` + `end_to_end_id` do estorno; ver tabela [aqui](/webhooks/webhook-event-reference).

### Como solicitar refund parcial?

`POST /api/pix/refund-in/{id}` (UUID do **cash-in**) com `refundValue` abaixo do teto. Múltiplos parciais permitidos. Ver [refund-in](/guides/refund-a-cash-in).

### O que fazer quando a transação entra em reconciliação?

Não conclua “pago”/“falhou” cedo demais. Monitore idade, consulte o detalhe, siga o [guia de reconciliação](/guides/reconcile-transactions) e, se a operação estiver parada, o [canal de suporte](/go-live/checklist).

### O integrador implementa `POST /api/webhooks/pix/...`?

**Não.** Esses *endpoints* são **entrada** do parceiro → clearpago. O seu sistema expõe apenas a URL de **comerciante** (webhook *outbound*). [Detalhe](/webhooks/partner-to-clearpago).

### Requests são em reais, mas a resposta vem em centavos?

Frequentemente, **sim** (conforme a convenção do documento de origem): request em reais, **response** com campos `*Cents` em vários casos. Trate a conversão explicitamente. [Convenções](/getting-started/environments-and-headers).