CashIn

Descripción General

El evento CashIn se envía cuando un pago PIX es recibido exitosamente en su cuenta. Este es el evento más común e indica que el dinero está disponible.

El movementType para CashIn es siempre CREDIT, indicando una entrada de fondos en la cuenta.

Campo	Valor
`event`	`CashIn`
`movementType`	`CREDIT`
Significado	El dinero entró a 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,
  "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 datos del pagador (quien envió el PIX).

counterpartobjectobrigatorio

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

counterpart.namestring

Nombre completo del pagador tal como está registrado en el banco de origen.

counterpart.documentstring

CPF/CNPJ del pagador (parcialmente enmascarado por privacidad).

Ejemplo: "*.345.678-**"

counterpart.bankobject

Datos bancarios del pagador.

counterpart.bank.bankISPBstring

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

counterpart.bank.bankNamestring

Nombre del banco del pagador.

counterpart.bank.bankCodestring

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

counterpart.bank.accountBranchstring

Sucursal del pagador (cuando esté disponible).

counterpart.bank.accountNumberstring

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 deduce 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. Siempre compare ese valor con el que usted generó en el cobro (Código QR) antes de liberar mercancía o servicio.

Para facilitar esa 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 que lo cobrado. Ej.: `50.00` = cobrado R$ 100.00, pagado R$ 50.00.
Negativo	El pagador pagó más que 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:

{
  "type": "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 diferente de null significa que el monto recibido no es el que usted cobró.

Casos de Uso

1. Pago de Pedido

async function handleCashIn(payload) {
  // Use externalId to correlate with the order
  const orderId = payload.externalId.replace('PIX-', '');

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

  // Notify customer
  await notificationService.sendPaymentConfirmation(orderId);
}

2. Recarga de Saldo

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

Flujo Típico

sequenceDiagram
    participant Payer
    participant Brasil Bitcoin
    participant YourSystem

    Payer->>Brasil Bitcoin: Sends PIX
    Brasil Bitcoin->>Brasil Bitcoin: Processes transaction
    Brasil Bitcoin->>YourSystem: Webhook CashIn
    YourSystem->>YourSystem: Validates authentication
    YourSystem->>YourSystem: Checks idempotency
    YourSystem-->>Brasil Bitcoin: HTTP 200 OK
    YourSystem->>YourSystem: Processes payment