Skip to main content

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

​
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), 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). 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.

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

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

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

​
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 e, se a operação estiver parada, o canal de suporte.

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

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