CashInReversal

Descripción General

El evento CashInReversal se envía cuando usted inicia una devolución de un pago PIX previamente recibido, retornando el monto al pagador original. Este evento ocurre cuando usted llama a la API de Refund-In.

El movementType para CashInReversal es DEBIT, porque está retornando dinero que había entrado a su cuenta.

Campo	Valor
`event`	`CashInReversal`
`movementType`	`DEBIT`
Significado	Usted retornó dinero que había recibido

Payload Completo

{
  "event": "CashInReversal",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "11111",
  "externalId": "refund-678689ca-3e16-4f5e-a08f-09a984a97781",
  "endToEndId": "D07136847202512112011O5222ZRBI5A",
  "pixKey": null,
  "feeAmount": 0.01,
  "originalAmount": 0.3,
  "finalAmount": 0.31,
  "processingDate": "2025-12-11T20:11:13.289Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {},
  "parentTransaction": {
    "transactionId": "12345",
    "externalId": "PIX-5482123298-EJUYFSMU1UU",
    "endToEndId": "E00416968202512111942rjzxxzSSTD9",
    "processingDate": "2025-12-11T19:42:04.080Z",
    "wasTotalRefunded": false,
    "remainingAmountForRefund": 0.2,
    "metadata": {},
    "counterpart": {
      "name": "Carlos Oliveira",
      "document": "*.345.678-**",
      "bank": {
        "bankISPB": null,
        "bankName": null,
        "bankCode": null,
        "accountBranch": null,
        "accountNumber": null
      }
    }
  }
}

Campos Específicos de CashInReversal

CashInReversal incluye el objeto parentTransaction con datos de la transacción original que se está devolviendo.

parentTransaction

parentTransactionobjectobrigatorio

Datos de la transacción PIX In original que se está devolviendo.

parentTransaction.transactionIdstring

ID numérico de la transacción PIX In original (retornado como string).

parentTransaction.externalIdstring

ID externo de la transacción original.

parentTransaction.endToEndIdstring

ID End-to-End de la transacción original.

parentTransaction.processingDatestring

Fecha de procesamiento de la transacción original.

parentTransaction.wasTotalRefundedboolean

Indica si el monto total de la transacción original fue devuelto.

true: Devolución total (no se permiten más devoluciones)
false: Devolución parcial (el monto restante aún puede devolverse)

parentTransaction.remainingAmountForRefundnumber

Monto restante que aún puede devolverse (en BRL).

Ejemplo: 0.2 (R$ 0.20 aún pueden devolverse)

parentTransaction.counterpartobject

Datos del pagador original que recibirá la devolución.

Devolución Total vs Parcial

Devolución Total

Cuando retorna el 100% del monto recibido:

{
  "parentTransaction": {
    "wasTotalRefunded": true,
    "remainingAmountForRefund": 0
  }
}

Devolución Parcial

Cuando retorna solo parte del monto:

{
  "parentTransaction": {
    "wasTotalRefunded": false,
    "remainingAmountForRefund": 0.2
  }
}

Puede realizar múltiples devoluciones parciales hasta que wasTotalRefunded sea true.

Casos de Uso

1. Devolución por Pago Duplicado

async function handleCashInReversal(payload) {
  const refundId = payload.transactionId;
  const originalOrderId = payload.parentTransaction.externalId;

  await refundService.markAsCompleted({
    refundId,
    originalOrderId,
    amount: payload.originalAmount,
    completedAt: payload.processingDate
  });

  // Notify customer about the refund
  await notificationService.sendRefundConfirmation({
    orderId: originalOrderId,
    amount: payload.originalAmount
  });
}

2. Seguimiento de Devolución Parcial

async function handleCashInReversal(payload) {
  const { parentTransaction } = payload;

  await refundService.updateStatus({
    originalTransactionId: parentTransaction.transactionId,
    totalRefunded: !parentTransaction.wasTotalRefunded
      ? false
      : true,
    remainingAmount: parentTransaction.remainingAmountForRefund
  });

  if (parentTransaction.wasTotalRefunded) {
    console.log('Transaction fully refunded');
  } else {
    console.log(`Still available for refund: R$ ${parentTransaction.remainingAmountForRefund}`);
  }
}

Flujo Típico

sequenceDiagram
    participant YourSystem
    participant Avista
    participant OriginalPayer

    Note over YourSystem,OriginalPayer: Original transaction (CashIn)
    OriginalPayer->>Avista: PIX received previously
    Avista->>YourSystem: Webhook CashIn

    Note over YourSystem,OriginalPayer: Refund (CashInReversal)
    YourSystem->>Avista: POST /api/pix/refund-in/\{id\}
    Avista->>OriginalPayer: Returns PIX
    Avista->>YourSystem: Webhook CashInReversal
    YourSystem-->>Avista: HTTP 200 OK