CashIn

Descripción General

El evento CashIn se envía cuando se procesa un pago PIX recibido en su cuenta. Con status: "CONFIRMED", el monto fue acreditado y está disponible.

El movementType de CashIn es siempre CREDIT, lo que indica entrada de fondos en la cuenta.

Campo	Valor
`event`	`CashIn`
`movementType`	`CREDIT`
Significado	Entró dinero en su cuenta

Payload Completo

{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "12345",
  "externalId": "PIX-5482123298-EJUYFSMU1UU",
  "endToEndId": "E00416968202512111942rjzxxzSSTD9",
  "pixKey": "1ff6ce09-4244-44d5-aa8f-1fe69f8986a9",
  "feeAmount": 0.01,
  "originalAmount": 0.5,
  "finalAmount": 0.49,
  "mismatchAmount": null,
  "processingDate": "2025-12-11T19:42:04.080Z",
  "errorCode": null,
  "errorMessage": null,
  "providerId": "a1b2c3d4e5",
  "counterpart": {
    "name": "Carlos Oliveira",
    "document": "*.345.678-**",
    "bank": {
      "bankISPB": null,
      "bankName": null,
      "bankCode": null,
      "accountBranch": null,
      "accountNumber": null
    }
  },
  "metadata": {}
}

Campos Específicos de CashIn

CashIn incluye el objeto counterpart con los datos del pagador (quien envió el PIX).

counterpartobjectobrigatorio

Datos del pagador (quien le envió el PIX).

counterpart.namestring | null

Nombre completo del pagador según lo registrado en el banco de origen.

counterpart.documentstring | null

CPF/CNPJ del pagador, en el formato informado por el PSP (puede venir parcialmente enmascarado).

Ejemplo: "*.345.678-**"

counterpart.bankobject

Datos bancarios del pagador. El objeto siempre trae las cinco claves siguientes; cada una es null cuando el PSP no informa el dato.

counterpart.bank.bankISPBstring | null

Código ISPB del banco del pagador (identificador único en el Sistema de Pagos Brasileño).

counterpart.bank.bankNamestring | null

Nombre del banco del pagador.

counterpart.bank.bankCodestring | null

Código COMPE del banco (ej.: "001" para Banco do Brasil, "260" para Nubank).

counterpart.bank.accountBranchstring | null

Agencia del pagador (cuando esté disponible).

counterpart.bank.accountNumberstring | null

Número de cuenta del pagador (cuando esté disponible).

Cálculo del Monto Final

Para eventos CREDIT (entrada), el monto final se calcula como:

finalAmount = originalAmount - feeAmount

La tarifa (feeAmount) se descuenta del monto original. Si el pagador envió R$ 100,00 y la tarifa es R$ 0,50, usted recibirá R$ 99,50.

Verificación del Monto Pagado

El campo originalAmount trae el monto efectivamente pagado por el pagador. Compare siempre ese monto con el que generó en el cobro (código QR) antes de liberar mercancía o servicio.

Para facilitar esta verificación, el webhook trae el campo mismatchAmount con la diferencia ya calculada:

`mismatchAmount`	Significado
`null`	No hubo divergencia: el pagador pagó exactamente el monto cobrado.
Positivo	El pagador pagó menos de lo cobrado. Ej.: `50.00` = cobrado R$ 100,00, pagado R$ 50,00.
Negativo	El pagador pagó más de lo cobrado. Ej.: `-50.00` = cobrado R$ 50,00, pagado R$ 100,00.

Ejemplo de un cobro de R$ 100,00 pagado con R$ 50,00:

{
  "event": "CashIn",
  "originalAmount": 50.0,
  "feeAmount": 0.5,
  "finalAmount": 49.5,
  "mismatchAmount": 50.0
}

Trate la divergencia en su conciliación antes de considerar el pedido pagado. Un mismatchAmount distinto de null significa que el monto recibido no es el que usted cobró.

Casos de Uso

1. Pago de Pedido

async function handleCashIn(payload) {
  // Usar externalId para correlacionar con el pedido
  const orderId = payload.externalId.replace('PIX-', '');

  await orderService.markAsPaid({
    orderId,
    transactionId: payload.transactionId,
    amount: payload.finalAmount,
    paidAt: payload.processingDate
  });

  // Notificar al cliente
  await notificationService.sendPaymentConfirmation(orderId);
}

2. Recarga de Saldo

El metadata trae el additionalInfo que usted envió al crear el cobro. En este ejemplo, el cobro se creó con additionalInfo.userId.

async function handleCashIn(payload) {
  await walletService.credit({
    userId: payload.metadata.userId,
    amount: payload.finalAmount,
    reference: payload.transactionId
  });
}

Flujo Típico

sequenceDiagram
    participant Pagador
    participant FyPay
    participant SuSistema

    Pagador->>FyPay: Envía PIX
    FyPay->>FyPay: Procesa transacción
    FyPay->>SuSistema: Webhook CashIn
    SuSistema->>SuSistema: Valida X-Avista-Signature
    SuSistema->>SuSistema: Verifica idempotencia
    SuSistema-->>FyPay: HTTP 2xx
    SuSistema->>SuSistema: Procesa pago