CashIn

Visão Geral

O evento CashIn é enviado quando um pagamento PIX recebido na sua conta é processado. Com status: "CONFIRMED", o valor foi creditado e está disponível.

O movementType para CashIn é sempre CREDIT, indicando entrada de recursos na conta.

Campo	Valor
`event`	`CashIn`
`movementType`	`CREDIT`
Significado	Dinheiro entrou na sua conta

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 do CashIn

O CashIn inclui o objeto counterpart com dados do pagador (quem enviou o PIX).

counterpartobjectobrigatorio

Dados do pagador (quem enviou o PIX para você).

counterpart.namestring | null

Nome completo do pagador conforme cadastrado no banco de origem.

counterpart.documentstring | null

CPF/CNPJ do pagador, no formato informado pelo PSP (pode vir parcialmente mascarado).

Exemplo: "*.345.678-**"

counterpart.bankobject

Dados bancários do pagador. O objeto sempre traz as cinco chaves abaixo; cada uma é null quando o PSP não informa o dado.

counterpart.bank.bankISPBstring | null

Código ISPB do banco do pagador (identificador único no Sistema de Pagamentos Brasileiro).

counterpart.bank.bankNamestring | null

Nome do banco do pagador.

counterpart.bank.bankCodestring | null

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

counterpart.bank.accountBranchstring | null

Agência do pagador (quando disponível).

counterpart.bank.accountNumberstring | null

Número da conta do pagador (quando disponível).

Cálculo do Valor Final

Para eventos de CREDIT (entrada), o valor final é calculado como:

finalAmount = originalAmount - feeAmount

A taxa (feeAmount) é descontada do valor original. Se o pagador enviou R$ 100,00 e a taxa é R$ 0,50, você receberá R$ 99,50.

Conferência do Valor Pago

O campo originalAmount traz o valor efetivamente pago pelo pagador. Sempre compare esse valor com o que você gerou na cobrança (QR Code) antes de liberar mercadoria ou serviço.

Para facilitar essa conferência, o webhook traz o campo mismatchAmount com a diferença já calculada:

`mismatchAmount`	Significado
`null`	Não houve divergência — o pagador pagou exatamente o valor cobrado.
Positivo	O pagador pagou a menos que o cobrado. Ex.: `50.00` = cobrado R$ 100,00, pago R$ 50,00.
Negativo	O pagador pagou a mais que o cobrado. Ex.: `-50.00` = cobrado R$ 50,00, pago R$ 100,00.

Exemplo de uma cobrança de R$ 100,00 paga com R$ 50,00:

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

Trate a divergência na sua conciliação antes de considerar o pedido pago. Um mismatchAmount diferente de null significa que o valor recebido não é o que você cobrou.

Casos de Uso

1. Pagamento de Pedido

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

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

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

2. Recarga de Saldo

O metadata traz o additionalInfo que você enviou na criação da cobrança. Neste exemplo, a cobrança foi criada com additionalInfo.userId.

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

Fluxo Típico

sequenceDiagram
    participant Pagador
    participant FyPay
    participant SeuSistema

    Pagador->>FyPay: Envia PIX
    FyPay->>FyPay: Processa transação
    FyPay->>SeuSistema: Webhook CashIn
    SeuSistema->>SeuSistema: Valida X-Avista-Signature
    SeuSistema->>SeuSistema: Verifica idempotência
    SeuSistema-->>FyPay: HTTP 2xx
    SeuSistema->>SeuSistema: Processa pagamento