CashIn

Overview

The CashIn event is sent when a PIX payment received in your account is processed. With status: "CONFIRMED", the amount has been credited and is available.

The movementType for CashIn is always CREDIT, indicating incoming funds to the account.

Field	Value
`event`	`CashIn`
`movementType`	`CREDIT`
Meaning	Money entered your account

Full Payload

{
  "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": {}
}

CashIn-Specific Fields

CashIn includes the counterpart object with data about the payer (who sent the PIX).

counterpartobjectobrigatorio

Data about the payer (who sent the PIX to you).

counterpart.namestring | null

Payer's full name as registered at the originating bank.

counterpart.documentstring | null

Payer's CPF/CNPJ, in the format provided by the PSP (may be partially masked).

Example: "*.345.678-**"

counterpart.bankobject

Payer's bank details. The object always contains the five keys below; each one is null when the PSP does not provide the data.

counterpart.bank.bankISPBstring | null

ISPB code of the payer's bank (unique identifier in the Brazilian Payment System).

counterpart.bank.bankNamestring | null

Name of the payer's bank.

counterpart.bank.bankCodestring | null

Bank COMPE code (e.g. "001" for Banco do Brasil, "260" for Nubank).

counterpart.bank.accountBranchstring | null

Payer's branch (when available).

counterpart.bank.accountNumberstring | null

Payer's account number (when available).

Final Amount Calculation

For CREDIT (incoming) events, the final amount is calculated as:

finalAmount = originalAmount - feeAmount

The fee (feeAmount) is deducted from the original amount. If the payer sent R$ 100.00 and the fee is R$ 0.50, you will receive R$ 99.50.

Paid Amount Check

The originalAmount field carries the amount actually paid by the payer. Always compare this value with what you generated in the charge (QR Code) before releasing goods or services.

To make this check easier, the webhook includes the mismatchAmount field with the difference already calculated:

`mismatchAmount`	Meaning
`null`	No mismatch — the payer paid exactly the charged amount.
Positive	The payer paid less than charged. E.g.: `50.00` = charged R$ 100.00, paid R$ 50.00.
Negative	The payer paid more than charged. E.g.: `-50.00` = charged R$ 50.00, paid R$ 100.00.

Example of a R$ 100.00 charge paid with R$ 50.00:

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

Handle the mismatch in your reconciliation before considering the order paid. A mismatchAmount other than null means the amount received is not what you charged.

Use Cases

1. Order Payment

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. Balance Top-up

The metadata carries the additionalInfo you sent when creating the charge. In this example, the charge was created with additionalInfo.userId.

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

Typical Flow

sequenceDiagram
    participant Payer
    participant FyPay
    participant YourSystem

    Payer->>FyPay: Sends PIX
    FyPay->>FyPay: Processes transaction
    FyPay->>YourSystem: CashIn Webhook
    YourSystem->>YourSystem: Validates X-Avista-Signature
    YourSystem->>YourSystem: Checks idempotency
    YourSystem-->>FyPay: HTTP 2xx
    YourSystem->>YourSystem: Processes payment