CashIn

Overview

The CashIn event is sent when a PIX payment is received successfully in your account. This is the most common event and indicates that the money is available.

The movementType for CashIn is always CREDIT, indicating an inflow of funds into 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,
  "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": {}
}

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

Full name of the payer as registered at the originating bank.

counterpart.documentstring

Payer's CPF/CNPJ (partially masked for privacy).

Example: "*.345.678-**"

counterpart.bankobject

Payer's bank details.

counterpart.bank.bankISPBstring

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

counterpart.bank.bankNamestring

Name of the payer's bank.

counterpart.bank.bankCodestring

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

counterpart.bank.accountBranchstring

Payer's branch (when available).

counterpart.bank.accountNumberstring

Payer's account number (when available).

Final Amount Calculation

For CREDIT events (inflow), 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.

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

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

Typical Flow

sequenceDiagram
    participant Payer
    participant Avista
    participant YourSystem

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

CashIn

Overview

Full Payload

CashIn-Specific Fields

Final Amount Calculation

Use Cases

1. Order Payment

2. Balance Top-Up

Typical Flow

Next Steps

PIX Cash-In

Refund Payment

On this page