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

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.

Paid Amount Verification

The originalAmount field carries the amount actually paid by the payer. Always compare this value with the amount 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 divergence — 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:

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

Handle the divergence in your reconciliation before considering the order paid. A mismatchAmount other than null means the amount received is not the amount 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

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

Typical Flow

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