Envoi d'événements pour l'évaluation des risques en temps réel : guide d'intégration

Pour obtenir une décision de risque en temps réel, votre système dorsal appellePOST /api/v1/transactionspour chaque paiement, virement, dépôt ou retrait, etPOST /api/v1/activitiesPour chaque connexion, inscription, réinitialisation de mot de passe, changement de bénéficiaire et événement similaire lié au compte, chaque appel renvoie une décision dans la même requête.allow,reviewoublockUne note est attribuée, accompagnée de la raison principale et d'une suggestion d'action suivante. Votre code conditionne l'exécution de cette action en fonction de cette décision.

Trois éléments déterminent la qualité de l'intégration : effectuer l'appel au bon moment (avant le transfert de fonds, et non après), transmettre des informations complètes sur l'expéditeur et le destinataire, et utiliser des identifiants stables afin d'éviter toute double évaluation en cas de nouvelle tentative. Ce guide détaille chacun de ces points, en s'appuyant sur les modèles de requêtes issus de la documentation relative au suivi des événements (s’ouvre dans un nouvel onglet) .

Disponibilité. Ces points de terminaison relèvent de la surveillance de la fraude. Toden Risk Intelligence est accessible aux comptes disposant des droits requis ; son utilisation en production exige aussi un profil d’entreprise approuvé. Si ces points de terminaison ne sont pas activés pour votre compte, contactez Toden avant de développer votre intégration.

À quel point de terminaison chaque événement appartient-il ?

Activitétypeest une liste fermée :login,signup,password_reset,beneficiary_added,profile_change,device_change,payoutetwithdrawalLa documentation indique clairement que les transferts d'argent avec justificatifs d'expéditeur et de destinataire transitent par le point de terminaison des transactions, et non par le point de terminaison d'activité.payout.

À quel moment de votre flux de travail l'appel doit-il s'insérer ?

Entre la confirmation du client et l'étape irréversible, prenons l'exemple d'un virement bancaire sortant via une application de portefeuille électronique :

1. Le client confirme un virement à un nouveau bénéficiaire.

2. Votre serveur envoie la transaction et attend la réponse.

3. Il se dirige versassessment.summary.outcome.

4. Uniquement surallowLe paiement est-il effectué auprès de la banque ferroviaire ?

L'évaluation après le départ du paiement relève du contrôle, certes utile pour les enquêtes, mais inadéquat. Toute décision de blocage doit être prise en amont. Toden renvoie une décision ; elle ne bloque pas les comptes dans votre application, donc le mécanisme de contrôle est votre code.

À quoi ressemble une première requête ?

Tous les appels Risk Intelligence utilisent une clé secrète de votre système dorsal :sk_test_contrehttps://sandbox-api.toden.co/api/v1,sk_live_contrehttps://api.toden.co/api/v1. Le Node.js officiel SDK est@myazahq/trust-sdk( ESM -uniquement, Node.js 20 ou plus récent), et il choisit l'hôte à partir de sonenvironmentoption. Extrait du guide de démarrage rapide de Risk Intelligence (s’ouvre dans un nouvel onglet) :

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);

Noter queamountest une chaîne de caractères. API Elle accepte une chaîne décimale positive avec jusqu'à huit décimales, de sorte que les montants ne sont jamais arrondis à l'aide d'un nombre à virgule flottante lors de leur saisie.

Cette demande est valable, mais elle est incomplète, et la section suivante explique pourquoi c'est important.

Pourquoi les partis sont-ils si importants ?

Car le contrôle dépend d'eux. La transactiondirectionest toujours du point de vue de votre client, et Toden examine l'autre aspect du mouvement avant de prendre une décision :

Les numéros de compte bancaire sont conservés comme justificatif de relation et ne servent pas à la vérification. Si le nom ou le portefeuille requis par la vérification est manquant, la réponse est une décision d'examen avec la mention « données insuffisantes », plutôt que de considérer la transaction comme valide.

C'est le comportement attendu, et cela signifie qu'une intégration légère génère une file d'attente de révision très active. Envoyez lepartiestableau. Chaque partie a besoin d'unrole(sender,recipient,customeroucounterparty), une référence stable (externalUserId,entityIdouexternalPartyId), et pour le contrôle externe des monnaies fiduciairesdisplayNameVeuillez joindre le compte ou le portefeuille utilisé par chaque partie comme instrument :

{
  "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"
    }
  ]
}

Le brut d'un instrumentidentifierLe numéro est indexé pour vérifier les liens de parenté et n'est pas stocké sous forme brute. Si vous préférez ne pas envoyer le numéro brut, veuillez fournir le vôtre.externalInstrumentIdou un existantfingerprintplutôt.

Comment envoyer un rapport d'activité de compte ?

La même enveloppe sanstransactionbloc, plus untypeUne connexion sur 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 }
  }'

Deux champs concentrent l'essentiel de la valeur.deviceRefIl s'agit de votre propre référence stable pour vos appareils ; sa réutilisation permet de constituer un historique des appareils et donne un sens à un signal de nouvel appareil.ipAddressdoit être l' adresse de l'utilisateur final .API ne remplace pas l'adresse IP de votre serveur ; par conséquent, si votre serveur dorsal transfère l'appel, transmettez l'adresse du client que vous avez observée, et non la vôtre.

Veuillez ne transmettre que les preuves que vous avez effectivement recueillies. Les coordonnées de latitude et de longitude doivent être fournies ensemble, et la localisation que vous indiquez prévaut sur toute information déduite de l'adresse IP.

Comment devez-vous interpréter la réponse ?

Lireassessment.summarypremier. Il contientoutcome,title,reason,score,riskLevel,matchedRulesetnextActionet cela suffit pour un routage normal. La même réponse contient également les règles de correspondance détaillées, les preuves de filtrage et le détail de la facturation pour les cas d'enquête. MagasindecisionIdetalertIdcontre votre propre transaction afin qu'un opérateur puisse retrouver la preuve ultérieurement.

Utilisez les valeurs de la machine (allow,review,block) dans le code et rédigez votre propre texte destiné au client, comme le recommande la documentation, plutôt que de transmettre le texte d'évaluation au client.

Comment réessayer sans marquer deux fois ?

Avec des identifiants stables :

• UnexternalActivityIdpar évaluation logique, conservée identique d'une tentative à l'autre. Une relecture renvoie l'évaluation existante avecreplayed: trueet ne le note ni ne le facture à nouveau.

• UnexternalTransactionIdpar transaction client.

• Réutiliser l'un ou l'autre identifiant avec des données immuables différentes renvoie409(idempotency_conflictoutransaction_id_conflictIl s'agit d'un bug dans votre système d'identification, inutile de réessayer.

• Envoyez l'originaloccurredAtCela ne peut pas se situer à plus de cinq minutes dans le futur, et Toden L'appareil enregistre à la fois l'heure de survenue et l'heure de réception, de sorte qu'un événement tardif reste visible sans fausser la chronologie.

Que se passera-t-il si aucune décision n'est rendue ?

Décidez-en avant le lancement, car le comportement prévu est de fermer la fenêtre en cas d'échec. Voici les erreurs que vous pourriez rencontrer :

La documentation relative aux erreurs (s’ouvre dans un nouvel onglet) souligne un point important à consigner dans votre manuel d'exploitation : les décisions concernant les transactions et les activités échouent en cas d'indisponibilité de crédit, et un enregistrement tardif ne constitue pas une réponse d'autorisation. Si vous ne pouvez pas obtenir de décision à temps, votre produit doit impérativement intégrer une règle spécifique, par exemple en bloquant les transferts sortants dépassant une limite que vous définissez jusqu'à réception d'une décision. Documentez cette règle ; ne laissez pas le délai d'expiration être défini par défaut sur « autoriser ».

Avez-vous encore besoin de webhooks ?

Pour les opérations, oui. Abonnez-vous àfraud.transaction.assessedetfraud.activity.assessedrecevoir chaque décision, et àscreening.match,risk.signal.createdetalert.createdDonner suite aux constatations. Vérifier chaque signature par rapport au corps brut et dédupliquer par identifiant d'événement.event.flaggedne sert plus que d'alias de compatibilité pour les décisions de non-autorisation. Si vous êtes surPOST /api/identity/events, planifiez la migration vers les points de terminaison v1 : l’ancienne forme peut gérer un événement simple mais ne peut pas prendre en charge des groupes structurés ou des instruments.

Liste de contrôle

• Clé secrète et hébergement Risk Intelligence uniquement sur votre serveur ;sk_test_avec l'hôte Sandbox pendant la construction.

• Les transactions sont effectuées avant le transfert des fonds ; le code d'accès est votre mot de passe.

• partiesavec des noms ou des portefeuilles pour la partie contrôlée de chaque mouvement.

• L'adresse IP de l'utilisateur final et votre stabilitédeviceRefsur les activités.

• ÉcurieexternalActivityIdetexternalTransactionId, originaloccurredAt.

• Une règle écrite décrivant la procédure à suivre lorsqu'aucune décision n'est possible.

• Webhooks souscrits, vérifiés et dédupliqués.

La page produit « Surveillance des transactions » décrit les règles et les outils d’investigation qui sous-tendent ces décisions, et le centre de ressources pour les développeurs donne accès à la documentation complète.