CashOut

Visão Geral

O evento CashOut é enviado quando um pagamento PIX enviado da sua conta chega a um status final: CONFIRMED (transferência concluída) ou ERROR (transferência não realizada).

Este evento é disparado tanto para pagamentos via chave PIX (/api/pix/cash-out) quanto para pagamentos via QR Code (/api/pix/cash-out-qrcode).

O movementType para CashOut é sempre DEBIT, indicando saída de recursos da conta.

Campo	Valor
`event`	`CashOut`
`movementType`	`DEBIT`
Significado	Dinheiro saiu da sua conta

Payload Completo

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

Campos Específicos do CashOut

O CashOut inclui o objeto counterpart com dados do recebedor (quem recebeu o PIX).

counterpartobjectobrigatorio

Dados do recebedor (quem recebeu o PIX que você enviou).

counterpart.namestring | null

Nome completo do recebedor conforme cadastrado no banco de destino.

counterpart.documentstring | null

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

Exemplo: "*.765.432-**"

counterpart.bankobject

Dados bancários do recebedor: bankISPB, bankName, bankCode, accountBranch e accountNumber. O objeto sempre traz as cinco chaves; cada uma é null quando o dado não está disponível.

counterpart.bank.bankCodestring | null

Código COMPE do banco do recebedor.

Exemplo: "260" (Nubank)

counterpart.bank.bankISPBstring | null

Código ISPB do banco do recebedor.

counterpart.bank.bankNamestring | null

Nome do banco do recebedor.

Cálculo do Valor Final

Para eventos de DEBIT (saída), o valor final é calculado como:

finalAmount = originalAmount + feeAmount

A taxa (feeAmount) é somada ao valor original. Se você enviou R$ 100,00 e a taxa é R$ 0,50, o débito total na sua conta será R$ 100,50.

Casos de Uso

1. Pagamento a Fornecedor

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

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

  // Notificar equipe financeira
  await notificationService.sendPaymentCompleted(paymentId);
}

2. Saque de Cliente

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

Fluxo Típico

sequenceDiagram
    participant SeuSistema
    participant FyPay
    participant Recebedor

    SeuSistema->>FyPay: POST /api/pix/cash-out
    FyPay->>FyPay: Valida e processa
    FyPay->>Recebedor: Transfere PIX
    Recebedor-->>FyPay: Confirmação
    FyPay->>SeuSistema: Webhook CashOut
    SeuSistema-->>FyPay: HTTP 2xx

Tratamento de Erros

Quando um CashOut falha, você receberá o webhook com status: "ERROR" e os campos errorCode/errorMessage preenchidos:

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

Quando status é ERROR, o endToEndId normalmente é null, pois o PIX não foi liquidado. feeAmount e finalAmount mostram os valores calculados para a operação, mas nada fica debitado da sua conta.

Quando status é ERROR, o valor não fica debitado da sua conta. Trate o erro e informe o usuário.

Códigos de erro variam por liquidante. Os valores de errorCode dependem do liquidante da sua conta. Trate o campo errorCode como string genérica e não o use para lógica; exiba errorMessage ao usuário.

CashOut

Visão Geral

Payload Completo

Campos Específicos do CashOut

Cálculo do Valor Final

Casos de Uso

1. Pagamento a Fornecedor

2. Saque de Cliente

Fluxo Típico

Tratamento de Erros

Próximos Passos

PIX Cash-Out

Cash-Out via QR Code

Devolução Recebida

Nesta página