API de verificação e risco de transações

Use uma chave de API da plataforma para iniciar, a partir dos seus próprios sistemas, verificação individual (KYC), verificação empresarial (KYB), monitoramento de transações e análise de endereços de carteira, e para consultar registros de verificação. A API aberta e o console executam o mesmo processo de verificação: os mesmos preços e as mesmas regras de resultados, reembolsos e conciliação.

Primeiro, clique em “Ativar” em “Verificação e risco de transações” no console; depois, crie uma chave em “Gerenciamento de APIs” e conceda as permissões de “Verificação e risco”: verification.read para consultar preços e registros, verification.write para iniciar verificações. Cada verificação é cobrada do saldo da conta.

Endpoints da API

• GET /api/v1/verification/info: Retorna se a sua conta ativou o serviço, se cada um dos quatro tipos de verificação está disponível e o respectivo preço (USD), além das redes e ativos disponíveis para monitoramento de transações e análise de carteira. Tipos indisponíveis não têm preço.
• POST /api/v1/verification/checks: Inicia uma verificação; a cobrança e a criação do registro ocorrem na mesma requisição. Verificações de identidade retornam um handoff_url, que você envia ao titular; monitoramento de transações e análise de carteira normalmente retornam o resultado diretamente.
• GET /api/v1/verification/checks: A lista é ordenada pela hora de início, das mais recentes para as mais antigas, e aceita filtros por kind, status, verdict e keyword (referência, endereço ou número da cobrança), com page e page_size para paginação (até 100 por página). A consulta de um registro inclui handoff_url enquanto a sessão ainda estiver com o titular. Atualizar lê novamente o resultado junto ao fornecedor (a análise de carteira não pode ser atualizada; analisar de novo gera nova cobrança).

Repetir com o mesmo idempotency_key e o mesmo conteúdo retorna o registro original, sem nova cobrança; reutilizar a chave com conteúdo diferente é rejeitado (400). Iniciar novamente uma verificação de identidade para uma referência cuja sessão ainda não foi concluída retorna essa sessão (reused é true), também sem cobrança.

Callbacks de resultado

Em “Configurações de integração” no console, informe uma URL de callback https e ative-a. Quando o status ou o resultado de um registro de verificação muda de forma assíncrona (verificação de identidade concluída, revisão manual alterou o resultado, resultado da transação atualizado, falha com reembolso), a plataforma envia um evento via POST. A chamada que você mesmo fez para iniciar a verificação não gera envio, pois a resposta síncrona já traz o resultado.

Cabeçalhos da requisição: X-Tovanix-Event é o tipo de evento (check.updated, ou ping para testes), X-Tovanix-Delivery é o event_id, X-Tovanix-Timestamp é o horário Unix em segundos e X-Tovanix-Signature é sha256= seguido do hexadecimal de HMAC-SHA256(segredo de assinatura, timestamp + "." + corpo bruto da requisição).

Uma resposta 2xx conta como entregue. Qualquer outra, incluindo timeouts, gera novas tentativas com espera de 1 minuto, 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas e 12 horas, até 8 tentativas no total; depois disso, o envio é interrompido. As novas tentativas enviam o mesmo event_id e o mesmo corpo, portanto faça a deduplicação por event_id. Os eventos podem chegar fora de ordem: mantenha o que tiver data.updated_at mais recente ou chame o endpoint de consulta para obter o status mais recente. Depois que você desativar o callback, os eventos ainda não entregues não serão enviados.

Páginas relacionadas: Verificação e risco de transações · Verificação de identidade: pessoas e empresas · Risco de transações: monitoramento e análise de carteiras · Documentação da API