Evento de saque PIX que falhou

Quando um PIX de saque falha durante o processamento, você receberá um webhook com o evento pix.withdraw.failed contendo todas as informações da transação que falhou de forma detalhada e organizada.

🏗️ Estrutura do Payload

🔑 Campos Principais

Campo	Tipo	Descrição
`data.event`	string	Tipo do evento (`pix.withdraw.failed`)
`data.data`	object	Dados específicos da transação PIX que falhou
`id`	string	ID único do evento webhook
`apiKeyId`	string	ID da chave API que gerou o evento
`eventType`	string	Tipo do evento (igual a `data.event`)
`timestamp`	number	Timestamp Unix do evento

💰 Dados da Transação PIX

Campo	Tipo	Descrição
`pix.id`	string	🆔 ID único da transação PIX
`pix.uuid`	string	🔗 UUID da transação
`pix.amount`	number	💵 Valor da transação em centavos
`pix.status`	string	📊 Status atual da transação
`pix.type`	string	📤 Tipo da transação (`WITHDRAW`)
`pix.pixKeyType`	string	🔑 Tipo da chave PIX (`RANDOM`)
`pix.qrCodeId`	string	📱 ID do QR Code (null para chave aleatória)
`pix.pixKey`	string	🎲 Chave PIX aleatória
`pix.e2e`	string	🔗 ID end-to-end da transação PIX
`pix.description`	string	📝 Descrição da transação
`pix.providerReferenceId`	string	🏢 ID de referência do provedor
`pix.expireAt`	string	⏰ Data/hora de expiração (ISO 8601)
`pix.executedAt`	string	⏱️ Data/hora de execução (ISO 8601)
`pix.provider`	string	🏦 Provedor de pagamento
`pix.createdAt`	string	📅 Data/hora de criação (ISO 8601)
`pix.updatedAt`	string	🔄 Data/hora de atualização (ISO 8601)
`pix.senderInfo`	object	👤 Informações do remetente
`pix.receiverInfo`	object	👥 Informações do destinatário
`pix.feeBatchId`	string	💰 ID do lote de taxas
`pix.feeDistributionCompletedAt`	string	✅ Data/hora de distribuição de taxas
`pix.feeDistributionMetadata`	object	📊 Metadados da distribuição de taxas
`pix.userId`	string	👤 ID do usuário que criou a transação
`pix.tenantId`	string	🏢 ID do tenant/organização
`pix.user`	object	👨‍💼 Dados do usuário
`timestamp`	string	🕐 Timestamp da falha (ISO 8601)

👤 Dados do Usuário

Campo	Tipo	Descrição
`pix.user.id`	string	🆔 ID único do usuário
`pix.user.email`	string	📧 Email do usuário
`pix.user.name`	string	👨‍💼 Nome completo do usuário
`pix.user.role`	string	👑 Função do usuário (`ADMIN`, `CLIENT`, `TENANT`, `MANAGER`)
`pix.user.cognitoId`	string	🔐 ID do Cognito (autenticação)
`pix.user.tenantId`	string	🏢 ID do tenant/organização
`pix.user.managerId`	string	👨‍💼 ID do gerente responsável
`pix.user.baasId`	string	🏦 ID do BaaS (Banking as a Service)
`pix.user.paymentId`	string	💳 ID de pagamento do usuário
`pix.user.level`	string	⭐ Nível do usuário (`premium`, `basic`)
`pix.user.status`	string	📊 Status do usuário (`active`, `inactive`)
`pix.user.complianceReviewDate`	string	📋 Data de revisão de compliance
`pix.user.complianceReason`	string	📝 Motivo da revisão de compliance
`pix.user.complianceAnalystId`	string	👨‍💻 ID do analista de compliance
`pix.user.createdAt`	string	📅 Data de criação do usuário
`pix.user.updatedAt`	string	🔄 Data de atualização do usuário
`pix.user.assignedManagerId`	string	👨‍💼 ID do gerente designado
`pix.user.profile`	object	👤 Perfil completo do usuário

📊 Status Possíveis

FAILED - ❌ Transação falhou durante o processamento

📤 Tipos de Transação

WITHDRAW - 💸 Saque/envio de PIX

🔑 Tipos de Chave PIX

RANDOM - 🎲 Chave PIX aleatória
EMAIL - 📧 Chave PIX por email
CPF - 👤 Chave PIX por CPF
CNPJ - 🏢 Chave PIX por CNPJ
PHONE - 📱 Chave PIX por telefone

📝 Exemplo de Payload Completo

{
  "data": {
    "event": "pix.withdraw.failed",
    "data": {
      "pix": {
        "id": "p1x2i3d4-e5f6-7890-abcd-ef1234567890",
        "userId": "u1s2e3r4-i5d6-7f8g-9h0i-j1k2l3m4n5o6",
        "tenantId": "t1e2n3a4-n5t6-7i8d-9j0k-l1m2n3o4p5q6",
        "qrCodeId": null,
        "uuid": "u1u2i3d4-v5a6-7890-abcd-ef1234567890",
        "pixKey": "p1x2k3e4-y5k6-7890-abcd-ef1234567890",
        "e2e": "",
        "pixKeyType": "RANDOM",
        "type": "WITHDRAW",
        "amount": 570,
        "description": null,
        "status": "FAILED",
        "providerReferenceId": null,
        "expireAt": "2025-08-13T18:47:29.564Z",
        "executedAt": null,
        "provider": null,
        "createdAt": "2025-08-13T18:47:29.566Z",
        "updatedAt": "2025-08-13T18:47:31.089Z",
        "senderInfo": null,
        "receiverInfo": null,
        "feeBatchId": null,
        "feeDistributionCompletedAt": null,
        "feeDistributionMetadata": null,
        "user": {
          "id": "u1s2e3r4-i5d6-7f8g-9h0i-j1k2l3m4n5o6",
          "email": "ana.silva@empresa.com.br",
          "name": "ANA SILVA SANTOS",
          "role": "ADMIN",
          "cognitoId": "ana.silva@empresa.com.br",
          "tenantId": "t1e2n3a4-n5t6-7i8d-9j0k-l1m2n3o4p5q6",
          "managerId": null,
          "baasId": null,
          "paymentId": "p1a2y3m4-e5n6-7t8i-9d0-1p2a3y4m5e6n7",
          "level": "premium",
          "status": "active",
          "complianceReviewDate": null,
          "complianceReason": null,
          "complianceAnalystId": null,
          "createdAt": "2025-05-13T15:49:20.894Z",
          "updatedAt": "2025-06-26T23:06:07.789Z",
          "assignedManagerId": null,
          "profile": null
        }
      },
      "timestamp": "2025-08-13T18:47:31.110Z"
    }
  },
  "id": "ev1nt2id3-4ev5-6nt7-8id9-0ev1nt2id3ev4",
  "apiKeyId": "ap1k2ey3-4ap5-6ke7-8y9-0ap1k2ey3ap4",
  "eventType": "pix.withdraw.failed",
  "timestamp": 1755110851123
}

🎯 Campos Principais

Campo	Descrição
`data.event`	🎪 Tipo do evento (`pix.withdraw.failed`)
`data.data.pix.id`	🆔 ID único da transação PIX
`data.data.pix.amount`	💵 Valor da transação em centavos
`data.data.pix.status`	📊 Status atual da transação
`data.data.pix.type`	📤 Tipo da transação (`WITHDRAW`)
`data.data.pix.pixKeyType`	🔑 Tipo da chave PIX (`RANDOM`)
`data.data.pix.pixKey`	🎲 Chave PIX aleatória
`data.data.pix.expireAt`	⏰ Data/hora de expiração
`data.data.pix.createdAt`	📅 Data/hora de criação
`data.data.pix.updatedAt`	🔄 Data/hora de atualização
`data.data.pix.user.name`	👨‍💼 Nome do usuário
`data.data.pix.user.email`	📧 Email do usuário
`data.data.pix.user.role`	👑 Função do usuário
`data.data.pix.user.level`	⭐ Nível do usuário
`id`	🆔 ID único do evento webhook
`timestamp`	🕐 Timestamp do evento