CashOut

Visão Geral

O evento CashOut é enviado quando um pagamento PIX é enviado com sucesso da sua conta para outra conta. Indica que a transferência foi completada.

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,
  "processingDate": "2025-12-11T20:06:12.117Z",
  "errorCode": null,
  "errorMessage": null,
  "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).

object

obrigatório

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

string

Nome completo do recebedor conforme cadastrado no banco de destino.

string

CPF/CNPJ do recebedor (parcialmente mascarado por questões de privacidade).Exemplo: "*.765.432-**"

object

Dados bancários do recebedor.

string

Código COMPE do banco do recebedor.Exemplo: "260" (Nubank)

string

Código ISPB do banco do recebedor.

string

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

Tratamento de Erros

Quando um CashOut falha, você receberá o webhook com status: "ERROR":

{
  "event": "CashOut",
  "status": "ERROR",
  "errorCode": "INVALID_PIX_KEY",
  "errorMessage": "Chave PIX não encontrada ou inválida",
  ...
}

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

Próximos Passos

PIX Cash-Out

Aprenda a enviar pagamentos PIX

Cash-Out via QR Code

Pague via QR Code PIX

Devolução Recebida

Entenda o evento de devolução

Introdução

Guias de Integração

Webhooks

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

​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

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