Documentation API

API de détection de fraude : scorer chaque paiement avant votre prestataire

Une API de détection de fraude reçoit des données sur le paiement, le client et l’appareil et renvoie en temps réel un score et une recommandation. Avec RiskCogs, vous chargez le SDK navigateur au paiement, envoyez session et commande à POST /v1/risk-score depuis votre serveur, appliquez la recommandation et renvoyez le résultat final.

Démarrer gratuitement en mode shadow

1. Charger le SDK navigateur au paiement

Le SDK collecte, avec le consentement de l’utilisateur, le contexte d’appareil et de session et renvoie un identifiant de session pour votre serveur. Endpoint et clé sont dans la console RiskCogs.

import { RiskCogs } from '@fraud/sdk-browser';

const risk = await RiskCogs.init({ endpoint: 'https://YOUR_RISKCOGS_INTAKE_HOST', publicKey: 'pub_YOUR_PUBLISHABLE_KEY' });
// On checkout submit: pass the session to your server score request.
const { sessionId } = await risk.getContext();

2. Scorer le paiement côté serveur

Appelez l’API avant d’envoyer le paiement à votre prestataire de paiement. Node 18 ou plus ne nécessite aucune bibliothèque.

// Server only: the secret (pr_*) key never reaches a browser.
const res = await fetch('https://YOUR_RISKCOGS_API_HOST/v1/risk-score', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.RISKCOGS_SECRET_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    requestId: order.id, flowType: 'checkout',
    email: order.email, ip: clientIp, sessionId: order.riskcogsSessionId,
    money: { amount: order.total, currency: order.currency }, // decimal string, major units
  }),
});
const { riskId, risk_score, level, recommendation, shadowMode } = await res.json();
// Keep riskId: send it with the outcome to POST /v1/risk-feedback later.

3. Ou tester avec curl

curl -X POST https://YOUR_RISKCOGS_API_HOST/v1/risk-score \
  -H "X-API-Key: $RISKCOGS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"quickstart-test-1","flowType":"checkout","email":"[email protected]","ip":"203.0.113.45","money":{"amount":"49.00","currency":"EUR"}}'

4. Lire la réponse et agir

Utilisez recommendation pour orienter le paiement : accepter, vérifier ou refuser. En mode shadow, journalisez la recommandation sans changer votre flux.

{
  "riskId": "0190f3c2-…",
  "risk_score": 18,
  "level": "low",
  "recommendation": "allow",
  "shadowMode": true,
  "flags": [],
  "signals": { "email": { … }, "ip": { … } }
}

Clés, montants et retour

Deux clés : pub_ pour le SDK navigateur, pr_ pour le serveur. La clé secrète n’atteint jamais le navigateur.
Montants en chaîne décimale avec devise, par exemple "49.00" EUR.
La réponse contient riskId, risk_score, level, recommendation, shadowMode, flags et signals.
Conservez riskId et envoyez le résultat à POST /v1/risk-feedback.
Seuils par défaut : moins de 40 accepter, 40 à 69 vérifier, 70 et plus refuser.

Diagramme de séquence : SDK au paiement, appel serveur à POST /v1/risk-score, score et raisons renvoyés, puis retour à POST /v1/risk-feedback

Questions fréquentes

Qu’est-ce qu’une API de détection de fraude ?

Un service web qui reçoit des données de paiement, de compte ou de connexion et renvoie un score avec une action recommandée.

Où l’appeler dans le parcours de paiement ?

Côté serveur, après validation de la commande et avant l’envoi au prestataire. Transmettez l’identifiant de session du SDK.

Pourquoi renvoyer les résultats ?

Pour que le score apprenne quels paiements étaient bons, remboursés ou rétrofacturés.

Plusieurs prestataires de paiement ?

Oui : le score est calculé avant tout prestataire, avec la même logique pour tous.

Mesurer d’abord. Bloquer ensuite.

Faites tourner RiskCogs en mode shadow à côté de votre prestataire de paiement actuel et vérifiez les décisions avant qu’elles ne touchent un seul client.