Pular para o conteúdo principal

​
Visão Geral

O evento CashOutReversal é enviado quando você recebe uma devolução de um PIX que enviou anteriormente. Isso pode ocorrer quando:
  • O recebedor devolve o valor voluntariamente
  • Há um problema com a transação original (dados inválidos, conta encerrada, etc.)
  • O banco destino rejeita a transação
O movementType para CashOutReversal é CREDIT, pois você está recebendo de volta dinheiro que havia saído da sua conta.
CampoValor
eventCashOutReversal
movementTypeCREDIT
SignificadoVocê recebeu de volta dinheiro que havia enviado

​
Payload Completo

{
  "event": "CashOutReversal",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "22222",
  "externalId": null,
  "endToEndId": "D18236120202512112009s0018351d9f",
  "pixKey": "07646173380",
  "feeAmount": 0.01,
  "originalAmount": 0.08,
  "finalAmount": 0.07,
  "processingDate": "2025-12-11T20:09:27.786Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {
    "refund": {
      "value": 8,
      "originalValue": 31000,
      "referenceTransactionId": 917561
    },
    "provider": "hyperwallet",
    "counterpart": {
      "bankCode": "260",
      "bankIspb": "18236120",
      "bankName": "NU PAGAMENTOS S.A. - INSTITUIÇÃO DE PAGAMENTO"
    },
    "webhookEvent": "PixOutReversalExternal",
    "originatedFrom": "WEBHOOK_DIRECT"
  },
  "parentTransaction": {
    "transactionId": "67890",
    "externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
    "endToEndId": "E071368472025121120065P1T3N1CS1A",
    "processingDate": "2025-12-11T20:06:12.117Z",
    "wasTotalRefunded": false,
    "remainingAmountForRefund": 0.22,
    "metadata": {},
    "counterpart": {
      "name": "Ana Costa",
      "document": "*.765.432-**",
      "bank": {
        "bankISPB": null,
        "bankName": null,
        "bankCode": "260",
        "accountBranch": null,
        "accountNumber": null
      }
    }
  }
}

​
Campos Específicos do CashOutReversal

O CashOutReversal inclui campos adicionais no metadata e o objeto parentTransaction.

​
metadata.refund

​
metadata.refund
object
Detalhes da devolução recebida.
​
metadata.refund.value
number
Valor devolvido em centavos.Exemplo: 8 (R$ 0,08)
​
metadata.refund.originalValue
number
Valor original da transação em centavos.Exemplo: 31000 (R$ 310,00)
​
metadata.refund.referenceTransactionId
number
ID interno de referência da transação original no provedor.

​
parentTransaction

​
parentTransaction
object
obrigatório
Dados da transação PIX Out original que foi devolvida.
​
parentTransaction.transactionId
string
ID numérico da transação PIX Out original (retornado como string).
​
parentTransaction.externalId
string
ID externo que você forneceu ao criar o PIX Out.
​
parentTransaction.wasTotalRefunded
boolean
Indica se o valor total foi devolvido.
  • true: Devolução total
  • false: Devolução parcial
​
parentTransaction.remainingAmountForRefund
number
Valor restante que ainda pode ser devolvido (em reais).
​
parentTransaction.counterpart
object
Dados do recebedor original que devolveu o PIX.

​
Diferença: CashInReversal vs CashOutReversal

AspectoCashInReversalCashOutReversal
Quem iniciaVocê (via API Refund-In)O recebedor ou o banco destino
DireçãoVocê → Pagador originalRecebedor → Você
movementTypeDEBIT (saída)CREDIT (entrada)
Quando ocorreVocê decide devolverVocê recebe de volta

​
Casos de Uso

​
1. Devolução Recebida

async function handleCashOutReversal(payload) {
  const { parentTransaction, metadata } = payload;

  // Creditar o valor devolvido no saldo
  await balanceService.credit({
    amount: payload.finalAmount,
    reference: payload.transactionId,
    originalPaymentId: parentTransaction.transactionId
  });

  // Atualizar status do pagamento original
  await paymentService.markAsRefunded({
    paymentId: parentTransaction.externalId,
    refundAmount: payload.originalAmount,
    wasFullRefund: parentTransaction.wasTotalRefunded
  });

  // Notificar equipe financeira
  await notificationService.sendRefundReceived({
    originalAmount: metadata.refund.originalValue / 100,
    refundAmount: metadata.refund.value / 100
  });
}

​
2. Tratamento de Rejeição

async function handleCashOutReversal(payload) {
  // Se o PIX foi devolvido, pode ser rejeição do banco
  if (payload.metadata.originatedFrom === 'WEBHOOK_DIRECT') {
    console.log('PIX rejeitado pelo banco destino');

    await transferService.markAsFailed({
      transferId: payload.parentTransaction.externalId,
      reason: 'Devolvido pelo banco destino'
    });

    // Notificar usuário para verificar dados
    await notificationService.sendTransferFailed();
  }
}

​
Fluxo Típico

​
Próximos Passos

PIX Cash-Out

Aprenda a enviar pagamentos PIX

CashOut

Entenda o evento de envio