CashOutReversal

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.

Campo	Valor
`event`	`CashOutReversal`
`movementType`	`CREDIT`
Significado	Você 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.refundobject

Detalhes da devolução recebida.

metadata.refund.valuenumber

Valor devolvido em centavos.

Exemplo: 8 (R$ 0,08)

metadata.refund.originalValuenumber

Valor original da transação em centavos.

Exemplo: 31000 (R$ 310,00)

metadata.refund.referenceTransactionIdnumber

ID interno de referência da transação original no provedor.

parentTransaction

parentTransactionobjectobrigatorio

Dados da transação PIX Out original que foi devolvida.

parentTransaction.transactionIdstring

ID numérico da transação PIX Out original (retornado como string).

parentTransaction.externalIdstring

ID externo que você forneceu ao criar o PIX Out.

parentTransaction.wasTotalRefundedboolean

Indica se o valor total foi devolvido.

true: Devolução total
false: Devolução parcial

parentTransaction.remainingAmountForRefundnumber

Valor restante que ainda pode ser devolvido (em reais).

parentTransaction.counterpartobject

Dados do recebedor original que devolveu o PIX.

Diferença: CashInReversal vs CashOutReversal

Aspecto	CashInReversal	CashOutReversal
Quem inicia	Você (via API Refund-In)	O recebedor ou o banco destino
Direção	Você → Pagador original	Recebedor → Você
movementType	`DEBIT` (saída)	`CREDIT` (entrada)
Quando ocorre	Você decide devolver	Você 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

sequenceDiagram
    participant SeuSistema
    participant Avista
    participant Recebedor

    Note over SeuSistema,Recebedor: Transação original (CashOut)
    SeuSistema->>Avista: POST /api/pix/payment
    Avista->>Recebedor: PIX enviado
    Avista->>SeuSistema: Webhook CashOut

    Note over SeuSistema,Recebedor: Devolução (CashOutReversal)
    Recebedor->>Avista: Devolve PIX
    Avista->>Avista: Processa devolução
    Avista->>SeuSistema: Webhook CashOutReversal
    SeuSistema-->>Avista: HTTP 200 OK
    SeuSistema->>SeuSistema: Credita saldo