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.
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": "4ac6204e-7c82-47a8-9aea-7fbb6fde72db",
"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).
Dados do recebedor (quem recebeu o PIX que você enviou).
Nome completo do recebedor conforme cadastrado no banco de destino.
CPF/CNPJ do recebedor (parcialmente mascarado por questões de privacidade).Exemplo: "*.765.432-**"
Dados bancários do recebedor.
counterpart.bank.bankCode
Código COMPE do banco do recebedor.Exemplo: "260" (Nubank)
counterpart.bank.bankISPB
Código ISPB do banco do recebedor.
counterpart.bank.bankName
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 R100,00eataxaeˊ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
