Envio de eventos para avaliação de risco em tempo real: um guia de integração

Para obter uma decisão de risco em tempo real, seu sistema de backend faz chamadas.POST /api/v1/transactionspara cada pagamento, transferência, depósito ou saque, ePOST /api/v1/activitiesPara cada login, cadastro, redefinição de senha, alteração de beneficiário e eventos similares na conta, cada chamada retorna uma decisão na mesma solicitação.allow,reviewoublock, com uma pontuação, o motivo mais forte e uma sugestão de próxima ação. Seu código controla a ação relacionada a essa decisão.

Três fatores determinam se a integração é eficaz: a chamada no momento certo (antes da transferência de dinheiro, não depois), o envio de informações completas sobre quem enviou e quem recebeu os fundos e o uso de identificadores estáveis ​​para que novas tentativas nunca gerem uma segunda avaliação. Este guia aborda cada um desses fatores, com os formatos de requisição da documentação de monitoramento de eventos (abre num novo separador) .

Disponibilidade. Esses endpoints pertencem à área de Monitoramento de Fraudes de Toden O Risk Intelligence está disponível para contas com acesso a ele. O uso em produção também requer um perfil comercial aprovado. Se os endpoints não estiverem habilitados para sua conta, entre em contato com o suporte. Toden antes de construir contra eles.

A qual endpoint cada evento pertence?

Atividadetypeé uma lista fechada:login,signup,password_reset,beneficiary_added,profile_change,device_change,payoutewithdrawalA documentação é categórica ao afirmar que a movimentação de dinheiro com comprovante de remetente e destinatário é feita pelo endpoint de transações, e não pelo endpoint de atividades.payout.

Em que ponto do seu fluxo de trabalho a chamada deve ser inserida?

Entre a confirmação do cliente e a etapa irreversível. Veja um exemplo de transferência bancária de saída em um aplicativo de carteira digital:

1. O cliente confirma a transferência para um novo beneficiário.

2. Seu servidor envia a transação e aguarda a resposta.

3. Ele se baseia emassessment.summary.outcome.

4. Somente emallowO pagamento é enviado ao banco?

Cobrar após o pagamento já ter sido efetuado é uma forma de monitoramento, que ainda tem valor para investigações, mas não impede a perda. Se a decisão for bloquear algo, isso precisa ser feito primeiro. Toden Retorna uma decisão; não bloqueia contas em seu aplicativo, portanto, o controle é o seu código.

Como é um primeiro pedido?

Todas as chamadas do Risk Intelligence utilizam uma chave secreta do seu sistema:sk_test_contrahttps://sandbox-api.toden.co/api/v1,sk_live_contrahttps://api.toden.co/api/v1O Node.js oficial SDK é@myazahq/trust-sdk( ESM (somente Node.js 20 ou mais recente) e escolhe o host a partir de seuenvironmentopção. Do guia de início rápido do Risk Intelligence (abre num novo separador) :

import { Myaza } from '@myazahq/trust-sdk';

const myaza = new Myaza({
  apiKey: process.env.MYAZA_SECRET_KEY,
  environment: 'sandbox',
});

const assessment = await myaza.transactions.create({
  externalActivityId: 'activity_txn_10001',
  subject: { type: 'individual', externalUserId: 'user_42' },
  occurredAt: new Date().toISOString(),
  transaction: {
    externalTransactionId: 'txn_10001',
    assetClass: 'fiat',
    direction: 'outbound',
    amount: '48000.00',
    currency: 'NGN',
    transactionType: 'bank_transfer',
  },
}, { idempotencyKey: 'transaction-txn_10001' });

console.log(assessment.summary?.outcome, assessment.summary?.reason);

Observe queamounté uma string. A API Aceita uma sequência decimal positiva com até oito casas decimais, portanto, o valor monetário nunca é arredondado por meio de um número de ponto flutuante durante a entrada.

Essa solicitação é válida, mas está incompleta, e a próxima seção explica por que isso é importante.

Por que as festas são tão importantes?

Porque a triagem depende deles. A transaçãodirectioné sempre do ponto de vista do seu cliente, e Toden Analisa o outro lado do movimento antes de tomar a decisão:

Os números de contas bancárias são mantidos como comprovante de relacionamento e não são usados ​​para verificação. Se o nome ou a carteira necessários para a verificação estiverem ausentes, a resposta será uma decisão de revisão com a justificativa de dados insuficientes, em vez de tratar a transação como aprovada.

Esse é o comportamento correto e significa que uma integração simples gera uma fila de revisão bastante ocupada. Envie opartiesmatriz. Cada parte precisa de umarole(sender,recipient,customeroucounterparty), uma referência estável (externalUserId,entityIdouexternalPartyId), e para triagem externa de decretosdisplayNameAnexe a conta ou carteira que cada parte utilizou como instrumento:

{
  "role": "recipient",
  "externalPartyId": "beneficiary_998877",
  "type": "individual",
  "displayName": "Amina Bello",
  "country": "NG",
  "instruments": [
    {
      "type": "bank_account",
      "externalInstrumentId": "beneficiary_account_998877",
      "identifier": "9988776655",
      "institutionName": "Recipient Bank",
      "country": "NG",
      "currency": "NGN"
    }
  ]
}

A essência bruta de um instrumentoidentifierO número é identificado por meio de impressão digital para fins de correspondência de relacionamentos e não armazenado em formato bruto. Caso prefira não enviar o número bruto, forneça o seu próprio.externalInstrumentIdou um existentefingerprintem vez de.

Como faço para enviar um relatório de atividades da conta?

O mesmo envelope sem umtransactionbloco, mais umtypeUm login sobre HTTP :

curl -X POST "https://sandbox-api.toden.co/api/v1/activities" \
  -H "Authorization: Bearer $MYAZA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalActivityId": "login_10001",
    "subject": { "type": "individual", "externalUserId": "user_42" },
    "type": "login",
    "occurredAt": "2026-08-16T09:30:00.000Z",
    "channel": "mobile_app",
    "deviceRef": "device_7f53",
    "ipAddress": "102.89.12.34",
    "country": "NG",
    "customAttributes": { "trustedDevice": false, "failedAttemptsBeforeSuccess": 2 }
  }'

Dois campos contêm a maior parte do valor.deviceRefé a sua própria referência de dispositivo estável; reutilizá-la constrói o histórico do dispositivo e é o que permite que um sinal de novo dispositivo tenha algum significado.ipAddressDeve ser o endereço do usuário final .API Não substitui o IP do seu servidor, portanto, se o seu backend encaminhar a chamada, passe o endereço do cliente que você observou, não o seu próprio.

Envie apenas as evidências que você realmente coletou. A latitude e a longitude devem ser fornecidas juntas, e a localização que você fornecer será considerada prioritária em relação a qualquer informação inferida a partir do endereço IP.

Como você deve interpretar a resposta?

Lerassessment.summaryprimeiro. Ele contémoutcome,title,reason,score,riskLevel,matchedRulesenextActionE isso é suficiente para o roteamento normal. A mesma resposta também inclui as regras de correspondência detalhadas, as evidências de triagem e o detalhamento da cobrança para quando alguém investigar. ArmazenardecisionIdealertIdcontra a sua própria transação, para que um operador possa encontrar as provas mais tarde.

Use os valores da máquina (allow,review,block) em código e escreva seu próprio texto voltado para o cliente, conforme aconselha a documentação, em vez de repassar o texto da avaliação para o cliente.

Como tentar novamente sem pontuar duas vezes?

Com identificadores estáveis:

• UmexternalActivityIdpor avaliação lógica, mantida idêntica em todas as tentativas. Uma repetição retorna a avaliação existente comreplayed: truee não recalcula nem cobra novamente.

• UmexternalTransactionIdpor transação do cliente.

• Reutilizar qualquer um dos identificadores com dados imutáveis ​​diferentes retorna409(idempotency_conflictoutransaction_id_conflictIsso é um erro no seu esquema de identificação, não algo para tentar novamente.

• Envie o originaloccurredAtNão pode ser daqui a mais de cinco minutos, e Toden Registra tanto a ocorrência quanto o horário de recebimento, de modo que um evento tardio permaneça visível sem distorcer a linha do tempo.

O que deve acontecer quando nenhuma decisão for tomada?

Decida isso antes do lançamento, pois o comportamento documentado é falhar com a tela fechada. Os erros que você encontrará são:

A documentação sobre erros (abre num novo separador) acrescenta um ponto importante a ser incluído no seu manual de procedimentos: as decisões sobre transações e atividades falham quando o crédito não está disponível, e um registro atrasado não é uma resposta de autorização. Se você não conseguir uma decisão a tempo, seu produto precisa de uma regra específica, por exemplo, reter transferências de saída acima de um limite definido por você até que uma decisão seja recebida. Anote essa regra; não deixe que o tempo limite seja definido como "permitir" por padrão.

Você ainda precisa de webhooks?

Para operações, sim. Inscreva-se emfraud.transaction.assessedefraud.activity.assessedpara receber todas as decisões e parascreening.match,risk.signal.createdealert.createdAgir de acordo com as descobertas. Verificar cada assinatura em relação ao corpo bruto e remover duplicatas por ID do evento.event.flaggedpermanece apenas como um alias de compatibilidade para decisões de não permissão. Se você estiver emPOST /api/identity/eventsPlaneje a mudança para os pontos finais da versão 1: o formato antigo pode pontuar um evento simples, mas não consegue transportar festas ou instrumentos estruturados.

Lista de verificação

• A chave secreta e o recurso de Inteligência de Risco ficam hospedados exclusivamente no seu servidor;sk_test_com o host Sandbox durante a compilação.

• Transações são solicitadas antes da movimentação de fundos; o portão é o seu código.

• partiescom nomes ou carteiras para o lado protegido por tela de cada movimento.

• O endereço IP do usuário final e seu endereço IP estável.deviceRefsobre atividades.

• EstávelexternalActivityIdeexternalTransactionId, originaloccurredAt.

• Uma regra escrita sobre o que acontece quando não há decisão possível.

• Webhooks inscritos, verificados e desduplicados.

A página do produto de Monitoramento de Transações descreve as regras e ferramentas de investigação por trás dessas decisões, e a central do desenvolvedor fornece links para as referências completas.