CashOut

Overview

The CashOut event is sent when a PIX payment sent from your account reaches a final status: CONFIRMED (transfer completed) or ERROR (transfer not performed).

This event is fired both for payments via PIX key (/api/pix/cash-out) and for payments via QR Code (/api/pix/cash-out-qrcode).

The movementType for CashOut is always DEBIT, indicating outgoing funds from the account.

Field	Value
`event`	`CashOut`
`movementType`	`DEBIT`
Meaning	Money left your account

Full Payload

{
  "event": "CashOut",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "67890",
  "externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
  "endToEndId": "E071368472025121120065P1T3N1CS1A",
  "pixKey": "07646173380",
  "feeAmount": 0.01,
  "originalAmount": 0.30,
  "finalAmount": 0.31,
  "mismatchAmount": null,
  "processingDate": "2025-12-11T20:06:12.117Z",
  "errorCode": null,
  "errorMessage": null,
  "providerId": "f6e5d4c3b2",
  "counterpart": {
    "name": "Ana Costa",
    "document": "*.765.432-**",
    "bank": {
      "bankISPB": null,
      "bankName": null,
      "bankCode": "260",
      "accountBranch": null,
      "accountNumber": null
    }
  },
  "metadata": {}
}

CashOut-Specific Fields

CashOut includes the counterpart object with data about the recipient (who received the PIX).

counterpartobjectobrigatorio

Data about the recipient (who received the PIX you sent).

counterpart.namestring | null

Recipient's full name as registered at the destination bank.

counterpart.documentstring | null

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

Example: "*.765.432-**"

counterpart.bankobject

Recipient's bank details: bankISPB, bankName, bankCode, accountBranch and accountNumber. The object always contains the five keys; each one is null when the data is not available.

counterpart.bank.bankCodestring | null

COMPE code of the recipient's bank.

Example: "260" (Nubank)

counterpart.bank.bankISPBstring | null

ISPB code of the recipient's bank.

counterpart.bank.bankNamestring | null

Name of the recipient's bank.

Final Amount Calculation

For DEBIT (outgoing) events, the final amount is calculated as:

finalAmount = originalAmount + feeAmount

The fee (feeAmount) is added to the original amount. If you sent R$ 100.00 and the fee is R$ 0.50, the total debit on your account will be R$ 100.50.

Use Cases

1. Supplier Payment

async function handleCashOut(payload) {
  const paymentId = payload.externalId.replace('PIX-OUT-', '');

  await paymentService.markAsCompleted({
    paymentId,
    transactionId: payload.transactionId,
    endToEndId: payload.endToEndId,
    completedAt: payload.processingDate
  });

  // Notify finance team
  await notificationService.sendPaymentCompleted(paymentId);
}

2. Customer Withdrawal

async function handleCashOut(payload) {
  await withdrawalService.confirm({
    withdrawalId: payload.externalId,
    transactionId: payload.transactionId,
    amount: payload.originalAmount,
    fee: payload.feeAmount
  });
}

Typical Flow

sequenceDiagram
    participant YourSystem
    participant FyPay
    participant Recipient

    YourSystem->>FyPay: POST /api/pix/cash-out
    FyPay->>FyPay: Validates and processes
    FyPay->>Recipient: Transfers PIX
    Recipient-->>FyPay: Confirmation
    FyPay->>YourSystem: CashOut Webhook
    YourSystem-->>FyPay: HTTP 2xx

Error Handling

When a CashOut fails, you will receive the webhook with status: "ERROR" and the errorCode/errorMessage fields filled in:

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "67890",
  "externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
  "endToEndId": null,
  "pixKey": "07646173380",
  "feeAmount": 0.01,
  "originalAmount": 0.30,
  "finalAmount": 0.31,
  "mismatchAmount": null,
  "processingDate": "2025-12-11T20:06:12.117Z",
  "errorCode": "TAX_ID_MISMATCH",
  "errorMessage": "O documento informado não corresponde ao titular da chave PIX",
  "providerId": null,
  "counterpart": {
    "name": "Ana Costa",
    "document": "12345678900",
    "bank": {
      "bankISPB": null,
      "bankName": null,
      "bankCode": null,
      "accountBranch": null,
      "accountNumber": null
    }
  },
  "metadata": {}
}

When status is ERROR, the endToEndId is usually null, since the PIX was not settled. feeAmount and finalAmount show the values calculated for the operation, but nothing remains debited from your account.

When status is ERROR, the amount does not remain debited from your account. Handle the error and inform the user.

Error codes vary by settlement provider. The errorCode values depend on your account's settlement provider. Treat the errorCode field as a generic string and do not use it for logic; display errorMessage to the user.

CashOut

Overview

Full Payload

CashOut-Specific Fields

Final Amount Calculation

Use Cases

1. Supplier Payment

2. Customer Withdrawal

Typical Flow

Error Handling

Next Steps

PIX Cash-Out

Cash-Out via QR Code

Refund Received

On this page