Devolver um cash-in (Refund-in)

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ção	Detalhe
Cash-in em `PAID`	Só é possível devolver recebimentos confirmados.
Prazo	Máximo 89 dias após o recebimento.
Saldo disponível	A 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

Campo	Obrigatório	Notas
`refundValue`	Sim	Valor em BRL a devolver. Pode ser menor que o original (devolução parcial).
`reason`	Não	Motivo da devolução (descritivo).
`externalId`	Não	Sua 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 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>"

Status	Significado
`PENDING`	Devolução aceita; aguardando confirmação do BaaS.
`CONFIRMED`	Devolução confirmada — valor devolvido ao pagador.
`FAILED`	Devolução rejeitada pelo BaaS.
`PROVIDER_RESULT_UNKNOWN`	Resposta 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

Mensagem	Causa	Ação
`refundValue must be greater than zero`	Valor inválido	Corrija o valor.
`refundValue exceeds the amount available for refund`	Teto atingido	Reduza o valor ou verifique devoluções pendentes.
`refund deadline of 89 days has been exceeded`	Prazo expirado	Não é possível devolver; encerre o processo.
`refunds can only be issued for PAID cash-in transactions`	Cash-in não está `PAID`	Verifique o status com `GET /api/pix/cash-in/{id}`.
`original cash-in transaction not found`	UUID inválido	Verifique 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>"

Início

Introdução

Conceitos

Guias

Referência de API

Webhooks

Ledger e Reconciliação

Erros

Go-live

FAQ

Devolver um cash-in (Refund-in)

Visão geral

Pré-requisitos

Identificadores críticos

Criar a devolução

Campos

Devoluções parciais

Monitorar o status

Receber o webhook

Erros comuns

Auditoria

Referências

​Visão geral

​Pré-requisitos

​Identificadores críticos

​Criar a devolução

​Campos

​Devoluções parciais

​Monitorar o status

​Receber o webhook

​Erros comuns

​Auditoria

​Referências

Visão geral

Pré-requisitos

Identificadores críticos

Criar a devolução

Campos

Devoluções parciais

Monitorar o status

Receber o webhook

Erros comuns

Auditoria

Referências