POST/v1/predict/fraud
Analyser une transaction
Envoyez la transaction avant de l’exécuter : la réponse donne la décision, le score et ses raisons. Envoyez transaction, avec les noms de champs standard, ou raw_transaction, avec ceux de votre système. Droit requis : envoyer des transactions.
Clé d’API requise
Corps de la requête (JSON)
raw_transactionobject · facultatif- La transaction avec les noms de champs de votre système, à la place de
transaction. La correspondance est établie à la mise en service. request_idstring · facultatif- Identifiant de l’analyse : le vôtre, ou celui que génère YARDA. Un identifiant déjà utilisé est refusé (409).
transactionobject · facultatif- La transaction, avec les noms de champs standard. Elle ou
raw_transactionest obligatoire. transaction.amountnumber · obligatoire- Montant, positif ou nul, dans la devise indiquée.
transaction.receiver_idstring · obligatoire- Identifiant du bénéficiaire dans votre système. Pseudonymisé à l’arrivée.
transaction.sender_idstring · obligatoire- Identifiant de l’expéditeur dans votre système. Pseudonymisé à l’arrivée.
transaction.transaction_idstring · obligatoire- Votre référence de la transaction, unique dans votre établissement (100 caractères au plus).
transaction.agent_idstring · facultatif- Agent qui a traité l’opération. Pseudonymisé à l’arrivée.
transaction.cash_point_idstring · facultatif- Caisse de l’agent ou point de retrait. Pseudonymisé à l’arrivée.
transaction.channelstring · facultatif- Canal de l’opération : agent, application, USSD, web, par exemple.
transaction.corridorstring · facultatif- Corridor de la transaction, selon la nomenclature de votre profil.
transaction.currencystring · facultatif- Code ISO 4217 de la devise, ou symbole d’une monnaie stable comme EURC ou USDC.
transaction.device_changed_atstring (date-time) · facultatif- Date du dernier changement d’appareil de l’expéditeur.
transaction.device_idstring · facultatif- Appareil ou installation de l’application de l’expéditeur. Pseudonymisé à l’arrivée.
transaction.fee_amountnumber · facultatif- Frais facturés à l’expéditeur, dans la devise de l’opération ; comparés à votre grille tarifaire.
transaction.funding_methodstring · facultatif- Comment l’expéditeur a payé :
cash,mobile_money,bank_account,card,cryptoouother. transaction.ip_addressstring · facultatif- Adresse IP d’une opération à distance (IPv4 ou IPv6). Conservée sous pseudonyme.
transaction.kyc_tierstring · facultatif- Niveau de connaissance du client de l’expéditeur dans votre système.
transaction.locationstring · facultatif- Accepté pour compatibilité, jamais conservé.
transaction.merchant_idstring · facultatif- Marchand payé. Pseudonymisé à l’arrivée.
transaction.metadataobject · facultatif- Informations complémentaires de votre système ; l’analyse ne les utilise pas.
transaction.original_transaction_idstring · facultatif- Pour un remboursement ou une annulation, la référence de l’opération qu’il défait.
transaction.payout_amountnumber · facultatif- Montant payé au bénéficiaire, quand il diffère du montant envoyé (autre devise, frais déduits).
transaction.payout_currencystring · facultatif- Devise payée au bénéficiaire.
transaction.payout_methodstring · facultatif- Comment le bénéficiaire a été payé :
cash,mobile_money,bank_account,card,cryptoouother. transaction.pin_reset_atstring (date-time) · facultatif- Date de la dernière réinitialisation du code ou du mot de passe de l’expéditeur.
transaction.receiver_countrystring · facultatif- Pays du bénéficiaire, en code ISO (par exemple CI).
transaction.receiver_namestring · facultatif- Nom du bénéficiaire. Exigé par la loi sur tout virement et criblé contre vos listes de sanctions. Comparé en mémoire, jamais conservé.
transaction.receiver_phonestring · facultatif- Téléphone du bénéficiaire. Pseudonymisé à l’arrivée.
transaction.sender_addressstring · facultatif- Adresse de l’expéditeur, l’un des moyens de l’identifier exigés par la loi. Seule sa présence est vérifiée ; jamais conservée.
transaction.sender_balancenumber · facultatif- Solde du compte ou du portefeuille de l’expéditeur avant l’opération.
transaction.sender_birth_datestring (date) · facultatif- Date de naissance de l’expéditeur ; avec le lieu de naissance, elle suffit à l’identifier. Seule sa présence est vérifiée ; jamais conservée.
transaction.sender_birth_placestring · facultatif- Lieu de naissance de l’expéditeur. Seule sa présence est vérifiée ; jamais conservé.
transaction.sender_countrystring · facultatif- Pays de l’expéditeur, en code ISO (par exemple SN).
transaction.sender_declared_monthly_amountnumber · facultatif- Montant mensuel que l’expéditeur a déclaré à l’entrée en relation.
transaction.sender_id_numberstring · facultatif- Numéro de la pièce d’identité officielle de l’expéditeur. Seule sa présence est vérifiée ; jamais conservé.
transaction.sender_namestring · facultatif- Nom de l’expéditeur. Exigé par la loi sur tout virement (loi uniforme, article 39 ; règlement (UE) 2023/1113) et criblé contre vos listes de sanctions. Comparé en mémoire, jamais conservé.
transaction.sender_phonestring · facultatif- Téléphone de l’expéditeur. Pseudonymisé à l’arrivée.
transaction.sender_sincestring (date) · facultatif- Date d’entrée en relation avec l’expéditeur.
transaction.sender_typestring · facultatif- Personne physique (
person) ou morale (legal_entity). transaction.sim_swap_atstring (date-time) · facultatif- Date du dernier changement de carte SIM de l’expéditeur, si vous la connaissez.
transaction.statusstring · facultatif- Statut de l’opération :
completed,pending,failed,cancelledoureversed. Les termes courants de vos exports sont reconnus (success,refunded,annulé...). transaction.timestampstring (date-time) · facultatif- Date et heure de la transaction, au format ISO 8601.
transaction.transaction_typestring · facultatif- Type d’opération :
cash_in,cash_out,p2p,merchant_payment,bill_payment,remittance, par exemple. transaction.wallet_idstring · facultatif- Portefeuille de l’expéditeur, s’il se distingue de l’expéditeur. Pseudonymisé à l’arrivée.
Réponse 200
anomaly_scorenumber · obligatoire- Score du modèle de comportement inhabituel, de 0 à 1.
client_idstring · obligatoire- L’identifiant de votre établissement chez YARDA.
client_phasestring · obligatoire- La phase d’apprentissage de votre espace.
decisionstring · obligatoire- La décision.
blockn’apparaît que si vous avez autorisé le blocage.Valeurs :allow,review,alert,block explanationsarray of object · obligatoire- La contribution de chaque modèle au score final.
explanations[].scorenumber · obligatoire- Son score, de 0 à 1.
explanations[].sourcestring · obligatoire- Le modèle concerné.
explanations[].weightnumber · obligatoire- Son poids.
explanations[].weighted_scorenumber · obligatoire- Son score multiplié par son poids.
explanations[].detailsarray of string · facultatif- Précisions propres au modèle.
final_scorenumber · obligatoire- Score final, de 0 à 1 : le rang de la transaction dans votre propre trafic.
inference_time_msnumber · obligatoire- La durée de l’analyse côté serveur, en millisecondes.
ml_scorenumber · obligatoire- Score du modèle supervisé, de 0 à 1, lorsqu’un tel modèle est en service.
request_idstring · obligatoire- Identifiant de l’analyse : le vôtre, ou celui que génère YARDA. Un identifiant déjà utilisé est refusé (409).
thresholdsobject · obligatoire- Les seuils de revue, d’alerte et de blocage appliqués à cette analyse.
timestampstring (date-time) · obligatoire- Date et heure de la réponse.
transaction_idstring · obligatoire- Votre référence de la transaction.
weightsobject · obligatoire- Poids de chaque modèle dans le score final.
decision_causeobject · facultatif- La cause décisive de la décision.
decision_cause.decisionstring · obligatoire- La décision que cette cause explique.
decision_cause.kindstring · obligatoire- Nature de la cause :
score_band,score_rules,detection_cap,typology,list_entry,declarative,on_erroroublocking_disabled. decision_cause.reason_enstring · obligatoire- La cause, rédigée en anglais.
decision_cause.reason_frstring · obligatoire- La cause, rédigée en français.
decision_cause.detailsobject · facultatif- Les valeurs citées dans la cause : score, seuil, version.
decision_cause.originalobject · facultatif- Pour
blocking_disabled, la cause qui demandait le blocage. decision_cause.rulestring · facultatif- La règle qui a décidé, lorsque c’est une règle.
decision_policyobject · facultatif- Présent lorsque votre politique a modifié la décision : un blocage ramené à une alerte, par exemple.
decision_policy.codestring · obligatoire- Nature de l’ajustement, aujourd’hui
blocking_disabled. decision_policy.decisionstring · obligatoire- La décision après l’ajustement.
decision_policy.original_decisionstring · obligatoire- La décision avant l’ajustement.
decision_policy.reason_enstring · obligatoire- L’ajustement, expliqué en anglais.
decision_policy.reason_frstring · obligatoire- L’ajustement, expliqué en français.
degradedboolean · facultatif- Vrai lorsqu’un modèle n’a pas pu répondre : la décision suit alors le plancher fixé par votre politique.Par défaut :
false legalobject · facultatif- Le socle légal, à part de la décision : l’expéditeur et le bénéficiaire criblés contre vos listes de sanctions quand vous envoyez leurs noms (
sender_name,receiver_name). legal.holdboolean · obligatoire- Vrai lorsqu’une partie ressemble à une entrée d’une liste de sanctions, ou que le criblage a échoué : n’exécutez pas le virement avant qu’une personne ait statué dans la console. Le gel ne change ni le score ni la décision. Vous êtes prévenu de sa levée par webhook (
legal.hold.updated) et pouvez suivre chaque gel avecGET /v1/legal-holds. legal.screeningstring · obligatoirescreened: les parties nommées ont été criblées ;names_absent: aucun nom envoyé, rien n’a pu être criblé ;unavailable: aucune de vos listes n’est chargée ;failed: le criblage a échoué et le virement est gelé.Valeurs :screened,names_absent,unavailable,failedlegal.cashobject · facultatif- Les espèces du jour des parties, pour un client soumis à l’UEMOA : pour chaque partie qui a remis ou reçu des espèces, le jour local, le total en FCFA (cette opération comprise) et le nombre d’opérations, avec les seuils de 9 000 000 FCFA (identification, loi uniforme art. 17 i) et de 15 000 000 FCFA (déclaration à la CENTIF, art. 72). Nul pour une opération sans espèces.
legal.dutiesarray of string · facultatif- Ce que votre établissement doit faire, jamais un gel :
cash_identification, identifier le client dont les espèces du jour dépassent 9 000 000 FCFA ;cash_report, déclarer les espèces à la CENTIF à partir de 15 000 000 FCFA. legal.list_setstring · facultatif- Les versions des listes contre lesquelles les parties ont été criblées.
legal.partiesarray of object · facultatif- Pour chaque partie nommée : son rôle, son pseudonyme, son statut (
clear,potential,confirmed,dismissed), les références des entrées soulevées et le meilleur score. legal.reasonsarray of string · facultatif- Les motifs du gel :
sanctions_potential_sender,sanctions_potential_receiver,sanctions_confirmed_sender,sanctions_confirmed_receiver,screening_failed,transfer_information_incomplete. legal.transfer_informationobject · facultatif- Si le virement porte les informations que la loi exige sur ses parties : statut (complete, incomplete, not_applicable, ou attested quand votre établissement mène l’analyse de ses alertes et tient lui-même ces informations), ce qui manque (payer_name, payee_name, payer_identification) et les régimes appliqués (uemoa, eu). Incomplet, le virement est gelé : ne l’exécutez pas avant d’avoir obtenu ces informations.
model_version_idinteger · facultatif- La version du modèle supervisé qui a noté la transaction, le cas échéant.
reasonsarray of object · facultatif- Les variables de comportement qui expliquent le score.
reasons[].directionstring · obligatoirehighsi la valeur est inhabituellement haute,lowsi elle est basse.reasons[].featurestring · obligatoire- La variable concernée.
reasons[].typicalnumber · obligatoire- La valeur habituelle.
reasons[].valuenumber · obligatoire- La valeur pour cette transaction.
reasons[].weightnumber · obligatoire- Le poids de la raison : rareté pour le modèle de comportement, contribution vers la fraude pour le modèle supervisé.
reasons[].sourcestring · facultatif- Le modèle qui donne la raison :
anomalyousupervised. triggered_rulesarray of object · facultatif- Les règles et typologies qui ont agi sur la transaction.
triggered_rules[].rule_namestring · obligatoire- Le nom de la règle.
triggered_rules[].rule_typestring · obligatoiretypology(typologie intégrée ou liste de blocage) oudeclarative(votre règle).triggered_rules[].scorenumber · obligatoire- La hausse de score demandée, 1 lorsqu’elle n’en demande aucune.
triggered_rules[].descriptionstring · facultatif- Pourquoi la règle a agi, en anglais.
triggered_rules[].severitystring · facultatif- La décision minimale imposée (
review,alert,block), ouflag.Par défaut :low triggered_rules[].versioninteger · facultatif- La version de votre règle.
warningsarray of object · facultatif- Ce que la transaction contient et que son modèle n’a pas appris : un champ presque toujours rempli à l’entraînement et absent ici, ou une valeur jamais vue. La transaction peut paraître inhabituelle pour cette seule raison : vérifiez ce que votre intégration envoie. Ces avertissements ne changent jamais la décision ; liste vide quand il n’y en a pas.
warnings[].codestring · obligatoirefield_absent(champ absent) ouunknown_value(valeur inconnue du modèle).warnings[].fieldstring · obligatoire- Le champ concerné de la transaction.
warnings[].message_enstring · obligatoire- L’avertissement rédigé en anglais.
warnings[].message_frstring · obligatoire- L’avertissement rédigé en français.
warnings[].training_sharenumber · obligatoire- Part des transactions d’entraînement où le champ est rempli, de 0 à 1.
warnings[].valuestring · facultatif- Pour
unknown_value, la valeur reçue.
422 Requête non conforme au schéma.