Eventos de envio e recebimento de Criptomoedas

Este documento descreve os diferentes tipos de eventos de webhook relacionados a transações de criptomoedas (envio e recebimento). Os webhooks são enviados automaticamente quando ocorrem mudanças no status das transações de cripto.

🏗️ Estrutura do Payload

🔑 Campos Principais

📊 Tipos de Eventos

1. 🔄 Transação Não Reivindicada Pendente de Confirmações

Tipo: UNCLAIMED_TRANSACTION_PENDING_CONFIRMATIONS

Descrição: Transação recebida em um endereço que não está associado a nenhuma carteira do sistema, aguardando confirmações na blockchain.

Características:

• walletId, ownerId, tenantId são null

• senderAddress é null

• Transação ainda não foi reivindicada por nenhum usuário

2. ➕ Transação Não Reivindicada Criada

Tipo: UNCLAIMED_TRANSACTION_CREATED

Descrição: Nova transação não reivindicada detectada na blockchain.

Características:

• Similar ao evento anterior, mas com status inicial

• Pode ter menos confirmações que o evento de pendência

3. ⏳ Transação Pendente de Confirmações

Tipo: TRANSACTION_PENDING_CONFIRMATIONS

Descrição: Transação associada a uma carteira específica aguardando confirmações na blockchain.

Características:

• walletId, ownerId, tenantId preenchidos

• senderAddress e recipientAddress preenchidos

• Transação já está associada a um usuário

4. 💰 Depósito Criado

Tipo: DEPOSIT_CREATED

Descrição: Novo depósito de criptomoeda detectado e associado a uma carteira.

Características:

• Transação de entrada (recebimento)

• senderAddress e recipientAddress preenchidos

• Pode ter externalRequestId como “WITHOUT”

5. 💸 Saque Criado

Tipo: WITHDRAW_CREATED

Descrição: Novo saque de criptomoeda iniciado.

Características:

• Transação de saída (envio)

• senderAddress e recipientAddress preenchidos

• externalRequestId e externalReferenceId preenchidos

🪙 Criptomoedas Suportadas

Moedas Nativas (COIN)

Tokens (TOKEN)

📊 Status das Transações

🔗 Blockchains Suportadas

📝 Exemplos de Payloads

Exemplo 1: Transação Não Reivindicada Pendente

{
  "type": "UNCLAIMED_TRANSACTION_PENDING_CONFIRMATIONS",
  "transactionId": "0x9876543210fedcba9876543210fedcba98765432",
  "walletId": null,
  "ownerId": null,
  "tenantId": null,
  "amount": "25.5",
  "symbol": "DAI",
  "typeAsset": "TOKEN",
  "status": "CREATE",
  "externalRequestId": null,
  "externalReferenceId": "0x9876543210fedcba9876543210fedcba98765432",
  "recipientAddress": "0x9876543210987654321098765432109876543210",
  "senderAddress": null,
  "blockchain": "polygon",
  "network": "mainnet",
  "currentConfirmations": 5,
  "targetConfirmations": 12,
  "contractAddress": "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
  "createdAt": "2024-01-15T13:30:00.000Z"
}

Exemplo 2: Depósito de Bitcoin

{
  "type": "TRANSACTION_PENDING_CONFIRMATIONS",
  "transactionId": "clx5555555555aaaaaa",
  "walletId": "clx1111111111bbbbbb",
  "ownerId": "user_99999",
  "tenantId": "tenant_88888",
  "amount": "0.1",
  "symbol": "BTC",
  "typeAsset": "COIN",
  "status": "CREATE",
  "externalRequestId": "req_btc789",
  "externalReferenceId": "ref_btc012",
  "recipientAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "senderAddress": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
  "blockchain": "bitcoin",
  "network": "mainnet",
  "currentConfirmations": 3,
  "targetConfirmations": 6,
  "createdAt": "2024-01-15T09:15:00.000Z"
}

Exemplo 3: Saque de Ethereum

{
  "type": "WITHDRAW_CREATED",
  "transactionId": "clx1234567890abcdef",
  "walletId": "clx0987654321fedcba",
  "ownerId": "user_12345",
  "tenantId": "tenant_67890",
  "amount": "0.5",
  "symbol": "ETH",
  "typeAsset": "COIN",
  "status": "CREATE",
  "externalRequestId": "req_abc123",
  "externalReferenceId": "ref_def456",
  "recipientAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "senderAddress": "0x8ba1f109551bD432803012645Hac136c",
  "blockchain": "ethereum",
  "network": "mainnet",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

🛡️ Dicas Importantes

✅ FAÇA:

• Verifique sempre o type do evento antes de processar

• Confirme se currentConfirmations >= targetConfirmations antes de considerar a transação como confirmada

• Use contractAddress para identificar tokens específicos

• Trate transações não reivindicadas de forma especial

• Valide os endereços de blockchain antes de processar

❌ NÃO FAÇA:

• Processar transações sem verificar as confirmações necessárias

• Ignorar o campo typeAsset ao identificar o tipo de ativo

• Assumir que todas as transações têm walletId preenchido

• Processar transações não reivindicadas como transações normais

🆘 Problemas Comuns

“Transação não está sendo confirmada!”

• Verifique se currentConfirmations < targetConfirmations

• Aguarde mais confirmações na blockchain

“Transação não reivindicada não aparece na carteira!”

• Transações não reivindicadas têm walletId: null

• Elas precisam ser associadas manualmente a uma carteira

“Token não reconhecido!”

• Verifique o contractAddress para identificar o token

• Confirme se o symbol está correto

📞 Suporte

Se nada funcionar:

1. Verifique o tipo de evento e processe adequadamente

2. Confirme as confirmações necessárias

3. Valide os endereços de blockchain

4. Entre em contato com nossa equipe de suporte