Skip to main content

​
Objetivo

Devolver ao pagador original parte ou a totalidade de um cash-in PAID, dentro de 89 dias após o recebimento, via POST /api/pix/refund-in/{id} com {id} = UUID do cash-in (não o transactionId do parceiro).

​
Corpo (exemplo)

{
  "refundValue": 150.75,
  "reason": "Pedido cancelado pelo cliente",
  "externalId": "estorno-12345"
}
CampoObrigatórioDescrição
refundValueSimValor em BRL (> 0).
reasonNãoMotivo.
externalIdNãoSeu id de estorno; se omitido, a plataforma pode gerar.

​
Regras de negócio (origem)

RegraDetalhe
Pré-condiçãoCash-in em PAID.
PrazoAté 89 dias após o recebimento.
Soma de devoluçõesNão pode exceder o valor original.
CompetiçãoEstornos confirmados e ainda pendentes/ambíguos competem pelo mesmo teto (regras internas de soma).
Parciais múltiplosPermitidos; cada um vira um pix_refund_in distinto.

​
Estados do refund

StatusQuando ocorre
PENDINGSolicitação aceita; aguarda webhook.
CONFIRMEDDevolução confirmada.
FAILEDRejeitada.
PROVIDER_RESULT_UNKNOWN / RECONCILIATION_REQUIREDConforme status.

​
Consultas

  • GET /api/pix/refund/{id} — {id} é o UUID do refund-in (não o cash-in).
  • GET /api/pix/refund — lista paginada com filtros documentados.

​
Notificação ao comerciante

O evento pix_cash_in_reversal traz event.id = UUID do cash-in original e event.external_id = externalId do refund-in — atenção à semântica na referência de eventos.

​
Erros de negócio comuns (mensagens orientativas)

SituaçãoMensagem (tipificada)
Valor inválidorefundValue must be greater than zero
Acima do disponívelrefundValue exceeds the amount available for refund
Prazorefund deadline of 89 days has been exceeded
Cash-in não pagorefunds can only be issued for PAID cash-in transactions
Não encontradooriginal cash-in transaction not found
Mais: Códigos de erro.

​
API reference