Webhook CashOut (Saques)

Receba notificacoes automaticas sobre o status das solicitacoes de saque.

Endpoint e Autenticacao

Definida pelo cliente na rota /api/SendWebhook

A URL do webhook e configurada pelo cliente. Exemplo: https://meusite.com.br/api/webhook/vorexy

Headers Obrigatorios

Headers

Content-Type: application/json
X-Idempotency-Key: <uuid>

Exemplo Real de Webhook Cashout

Webhook Payload - Successful

{
  "object": "withdraw",
  "type": "cashout",
  "status": "successful",
  "companyId": 1,
  "withdrawId": 7184,
  "value": 10,
  "valueInCents": 1000,
  "currency": "BRL",
  "provider": "A55",
  "providerStatus": 1,
  "providerTid": "wld-00007184",
  "providerPaymentId": "uuid-provider",
  "endToEndId": "Exxxxxxxx",
  "providerAmount": 10,
  "providerConfirmedAt": "2025-11-27T10:12:33Z",
  "providerDebitedAt": null,
  "providerPayload": { },
  "pixKey": "chave",
  "pixKeyType": "CPF",
  "creditorDocument": "xxx",
  "payer": {
    "name": "NOME DO BANCO/A55",
    "document": "xxx",
    "ispb": "xxxxx",
    "agency": "xxxx",
    "account": "xxxx"
  },
  "receiver": {
    "name": "NOME DO CLIENTE",
    "document": "xxx",
    "ispb": "xxxx",
    "agency": "xxxx",
    "account": "xxxx"
  },
  "createdAt": "2025-11-27T00:00:00Z",
  "updatedAt": "2025-11-27T00:00:00Z",
  "processedAt": "2025-11-27T00:00:00Z",
  "metadata": null
}

Descricao dos Campos

objectstringSempre 'withdraw'

typestringTipo do evento - sempre 'cashout'

statusstringStatus final: successful, failure, refunded

companyIdnumberID da empresa dona do saque

withdrawIdnumberID interno do saque na Vorexy

valuenumberValor sacado em reais

valueInCentsnumberValor sacado em centavos

currencystringMoeda (sempre 'BRL')

providerstringProvedor usado (ex: 'A55')

providerStatusnumberCodigo numerico retornado pelo provedor

providerTidstringTID do saque no provedor

providerPaymentIdstringID do pagamento no provedor (UUID)

endToEndIdstringCodigo PIX unico do saque (E2E). Pode ser usado para consultas Pix Out.

providerAmountnumberValor confirmado pelo provedor

providerConfirmedAtstringData/hora de confirmacao pelo provedor

providerDebitedAtstring|nullData/hora do debito na conta (se disponivel)

providerPayloadobjectResposta completa do provedor (raw)

pixKeystringChave PIX de destino

pixKeyTypestringTipo da chave (CPF, CNPJ, EMAIL, PHONE, EVP)

creditorDocumentstringDocumento do beneficiario

payerobjectDados do pagador (banco/A55)

receiverobjectDados do recebedor (cliente)

createdAtstringData/hora de criacao do saque

updatedAtstringData/hora da ultima atualizacao

processedAtstringData/hora que o provedor processou o saque

metadatastring|object|nullMetadados customizados enviados na solicitacao

Notas Importantes

O campo endToEndId ja e salvo automaticamente no banco:

Campo: ProviderEndToEndId | Tabela: Withdraws

Como usar o endToEndId:

Consultar status do PIX-out no provedor
Rastrear auditoria bancaria
Exibir detalhes no painel administrativo

Quando o Webhook e Enviado?

O webhook e disparado sempre que:

O saque e confirmado (successful)
O saque e estornado (refunded)
O saque e recusado / failure

Status Possiveis

pendingSolicitado, aguardando

successfulPago

failureFalhou / rejeitado

Reenvio Automatico

OK3 tentativas automaticas (1 min / 5 min / 15 min)

OKIdempotencia garantida pelo header X-Idempotency-Key

Exemplo de Resposta

Response

{ "received": true, "idempotent": false }

Exemplo de Handler

Node.js / Express

app.post('/webhook/vorexy/cashout', async (req, res) => {
  const { 
    type, 
    status, 
    withdrawId, 
    value,
    valueInCents,
    endToEndId,
    providerConfirmedAt,
    receiver 
  } = req.body;
  const idempotencyKey = req.headers['x-idempotency-key'];
  // Verificar idempotencia
  if (await checkIdempotency(idempotencyKey)) {
    return res.status(200).json({ received: true, idempotent: true });
  }
  if (type === 'cashout') {
    switch (status) {
      case 'successful':
        console.log(`Saque ${withdrawId} confirmado: R$ ${value}`);
        console.log(`Valor em centavos: ${valueInCents}`);
        console.log(`E2E: ${endToEndId}`);
        console.log(`Confirmado em: ${providerConfirmedAt}`);
        console.log(`Destinatario: ${receiver.name}`);
        await updateWithdrawStatus(withdrawId, 'confirmed');
        break;
      case 'failure':
        console.log(`Saque ${withdrawId} falhou`);
        await updateWithdrawStatus(withdrawId, 'failed');
        // Notificar usuario sobre falha
        break;
    }
  }
  await markAsProcessed(idempotencyKey);
  res.status(200).json({ received: true, idempotent: false });
});