Skip to main content

​
Visão geral

O refund-in é a devolução de um recebimento Pix (cash-in). Pode ser total ou parcial, com múltiplas devoluções parciais enquanto o saldo disponível permitir.

​
Pré-requisitos

Antes de solicitar a devolução, verifique:
CondiçãoDetalhe
Cash-in em PAIDSó é possível devolver recebimentos confirmados.
PrazoMáximo 89 dias após o recebimento.
Saldo disponívelA soma das devoluções (pendentes + confirmadas) não pode exceder o valor original recebido.

​
Identificadores críticos

O path POST /api/pix/refund-in/{id} exige o UUID do cash-in (campo id retornado no 201 de POST /api/pix/cash-in). Não use o transactionId do parceiro BaaS.

​
Criar a devolução

curl -X POST https://api.clearpago.com.br/api/pix/refund-in/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: req-refund-001" \
  -d '{
    "refundValue": 150.75,
    "reason": "Pedido cancelado pelo cliente",
    "externalId": "estorno-12345"
  }'
Resposta 201: 
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "status": "PENDING",
  "externalId": "estorno-12345"
}
Persista o id do refund imediatamente. Ele é necessário para consultar o status com GET /api/pix/refund/{id} e para auditoria de devoluções parciais.

​
Campos

CampoObrigatórioNotas
refundValueSimValor em BRL a devolver. Pode ser menor que o original (devolução parcial).
reasonNãoMotivo da devolução (descritivo).
externalIdNãoSua chave de negócio para o estorno. Recomendado para rastreio.

​
Devoluções parciais

Você pode fazer múltiplas devoluções parciais sobre o mesmo cash-in, desde que a soma total não ultrapasse o valor original. Exemplo: cash-in de R300,00.Devoluc\ca~oparcial1:R 300,00. Devolução parcial 1: R 100,00. Devolução parcial 2: R$ 200,00. A plataforma verifica o teto considerando tanto as devoluções CONFIRMED quanto as PENDING. Se houver devoluções pendentes que somam ao máximo, novas devoluções serão rejeitadas (422).

​
Monitorar o status

curl https://api.clearpago.com.br/api/pix/refund/d4e5f6a7-b8c9-0123-defa-234567890123 \
  -H "Authorization: Bearer <seu_api_token>"
StatusSignificado
PENDINGDevolução aceita; aguardando confirmação do BaaS.
CONFIRMEDDevolução confirmada — valor devolvido ao pagador.
FAILEDDevolução rejeitada pelo BaaS.
PROVIDER_RESULT_UNKNOWNResposta ambígua; reconciliação em andamento.

​
Receber o webhook

POST https://seu-sistema.com/webhooks/pix
Content-Type: application/json
Digital-Signature: <base64>

{
  "event_type": "pix_cash_in_reversal",
  "event": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "estorno-12345",
    "status": "CONFIRMED",
    "value_cents": 15075,
    "end_to_end_id": "D07136847202504011500O5222ZRBI5A",
    "fee_amount_cents": 1,
    "confirmed_at": "2026-04-01T15:05:00.000000000Z"
  }
}
Atenção à semântica de event.id: no evento pix_cash_in_reversal, event.id é o UUID do cash-in original, não o UUID do refund-in. O event.external_id é o externalId do refund-in.
Chave de idempotência recomendada: event_type + transaction_id + end_to_end_id do estorno. Evita colisão entre devoluções parciais do mesmo cash-in.

​
Erros comuns

MensagemCausaAção
refundValue must be greater than zeroValor inválidoCorrija o valor.
refundValue exceeds the amount available for refundTeto atingidoReduza o valor ou verifique devoluções pendentes.
refund deadline of 89 days has been exceededPrazo expiradoNão é possível devolver; encerre o processo.
refunds can only be issued for PAID cash-in transactionsCash-in não está PAIDVerifique o status com GET /api/pix/cash-in/{id}.
original cash-in transaction not foundUUID inválidoVerifique se está usando o id do cash-in (não transactionId).

​
Auditoria

Para listar todos os refunds: 
curl "https://api.clearpago.com.br/api/pix/refund?start_date=2026-04-01&end_date=2026-04-30" \
  -H "Authorization: Bearer <seu_api_token>"

​
Referências