Signaux de contexte

Avant de commencer

Les signaux de contexte évaluent les transactions de crédit finalisées et renvoient une évaluation du risque — auto-fraude ou ingénierie sociale — pour enrichir votre propre décision anti-fraude.

Ils sont complémentaires à la Vérification sans carte présente : ils ne modifient ni le contrat ni le comportement des points de terminaison de transaction que vous utilisez déjà. Vous continuez à recevoir l'état terminal de la transaction (approved, inconclusive, etc.) comme d'habitude, puis vous interrogez les signaux de contexte.

Vos requêtes API sont authentifiées à l'aide d'un jeton d'accès. Toute requête qui n'inclut pas un jeton d'accès valide renverra une erreur. Pour en savoir plus, consultez Authentification.

Accès contrôlé par permission

L'accès à ce point de terminaison est contrôlé par une permission (rôle) attribuée à votre entreprise. Sans elle, le point de terminaison renvoie 403. Demandez l'activation à l'équipe Unico.

URL de base

• UAT : https://transactions.transactional.uat.unico.app/api/public/v1
• Production : https://transactions.transactional.unico.app/api/public/v1

Obtenir les signaux de contexte

GET /transactions/{transaction_id}/signals — renvoie l'évaluation du risque d'une transaction finalisée.

Le résultat est précalculé de manière asynchrone dès que la transaction atteint son état terminal ; ce point de terminaison ne fait donc que consulter un résultat déjà disponible.

Paramètres de chemin

Paramètre	Type	Requis	Description
transaction_id	string	oui	ID de la transaction (UUID v4). Par exemple, 6ab1771e-dfab-4e47-8316-2452268e5481.

En-têtes

En-tête	Valeur
Authorization	Bearer {token} — un jeton d'accès valide.
Accept	application/json

Exemple de requête

GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json

200 OK

{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Champ	Type	Présence	Description
signals.auto_fraud_risk	string (enum)	optionnel	Niveau de risque d'auto-fraude. Présent uniquement lorsqu'il est détecté.
signals.social_eng_risk	string (enum)	optionnel	Niveau de risque d'ingénierie sociale. Présent uniquement lorsqu'il est détecté.
signals.more_info.limited_data	boolean	toujours	true lorsqu'il n'y a pas suffisamment de données pour une évaluation robuste.
signals.more_info.holder_identified	boolean	toujours	false lorsque le titulaire de la carte n'a pas pu être identifié.

Valeurs de risque possibles : very_low, low, medium, high, very_high.

info

auto_fraud_risk et social_eng_risk s'excluent mutuellement — ils n'apparaissent jamais ensemble dans la même réponse. Lorsque limited_data vaut true, les deux champs de risque sont censés être absents, faute de données suffisantes pour une évaluation.

Exemples de réponse

Risque d'ingénierie sociale détecté :

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Aucun risque identifié — une transaction normale :

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Données insuffisantes :

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

Titulaire de la carte non identifié :

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}

Autres codes de réponse

Les erreurs sont renvoyées dans le format d'erreur standard décrit dans Erreurs.

Code HTTP	Code	Situation	Que faire
202	—	Le résultat n'a pas encore été calculé — le traitement asynchrone est toujours en cours.	Répétez l'appel (polling) jusqu'à obtenir un 200.
400	40004	transaction_id est invalide (ce n'est pas un UUID v4) ou un paramètre est mal formé.	Corrigez le format de l'ID avant de renvoyer la requête.
403	40305	L'entreprise n'a pas la permission (rôle) activée pour ce point de terminaison.	Demandez l'activation à l'équipe Unico.
404	40401	La transaction n'a pas été trouvée.	Vérifiez l'ID de la transaction.
404	40484	La transaction n'a pas été trouvée pour l'évaluation.	Traitez-le comme signifiant qu'il n'y aura pas de résultat, et arrêtez d'interroger.
409	40983	La transaction n'a pas encore atteint son état terminal.	Attendez l'état terminal avant d'interroger à nouveau.
500	—	Erreur interne du service.	Réessayez avec un délai croissant (backoff). Si le problème persiste, contactez le support Unico.

Règles et bonnes pratiques

• Interrogez le point de terminaison uniquement après que la transaction a atteint son état terminal. Une requête antérieure renvoie 409.
• Seules les transactions de crédit sont évaluées. Les transactions capturées en mode silencieux ne le sont pas.
• En cas de 202, répétez l'appel jusqu'à obtenir un 200. Envoyez la première requête 1 seconde après la réponse de la transaction, puis espacez les tentatives : 2 s, 4 s, 8 s, 16 s — jusqu'à 5 tentatives.
• L'objectif de niveau de service est de 10 secondes après la réponse de la transaction.
• Traitez un 404 comme signifiant qu'il n'y aura pas de résultat, et arrêtez d'interroger.
• auto_fraud_risk et social_eng_risk s'excluent mutuellement.