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,
  "mismatchAmount": null,
  "processingDate": "2025-12-11T20:09:27.786Z",
  "errorCode": null,
  "errorMessage": null,
  "providerId": "d3v0luc4o",
  "metadata": {
    "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,
    "providerId": "f6e5d4c3b2",
    "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 o objeto parentTransaction com os dados do PIX Out original.

Neste evento, o metadata é preenchido pela plataforma com informações da devolução recebida do PSP. O conteúdo varia conforme o PSP e serve apenas como referência: não dependa de chaves específicas dele. Para valores, use originalAmount, feeAmount e finalAmount.

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 | null

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

parentTransaction.endToEndIdstring | null

ID End-to-End do PIX Out original.

parentTransaction.processingDatestring

Data de criação do PIX Out original (ISO 8601 UTC).

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.providerIdstring | null

Identificador do PIX Out original no PSP. null se ausente.

parentTransaction.metadataobject

metadata do PIX Out original.

parentTransaction.counterpartobject

Dados do recebedor original que devolveu o PIX (mesma estrutura do counterpart do CashOut).

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 } = 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({
    paymentId: parentTransaction.externalId,
    refundAmount: payload.originalAmount
  });
}

Fluxo Típico

sequenceDiagram
    participant SeuSistema
    participant FyPay
    participant Recebedor

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

    Note over SeuSistema,Recebedor: Devolução (CashOutReversal)
    Recebedor->>FyPay: Devolve PIX
    FyPay->>FyPay: Processa devolução
    FyPay->>SeuSistema: Webhook CashOutReversal
    SeuSistema-->>FyPay: HTTP 2xx
    SeuSistema->>SeuSistema: Credita saldo

CashOutReversal

Visão Geral

Payload Completo

Campos Específicos do CashOutReversal

parentTransaction

Diferença: CashInReversal vs CashOutReversal

Casos de Uso

1. Devolução Recebida

Fluxo Típico

Próximos Passos

PIX Cash-Out

CashOut

Nesta página