Documentazione API

API antifrode: valuta ogni pagamento prima del fornitore di pagamento

Un’API antifrode riceve dati su pagamento, cliente e dispositivo e restituisce in tempo reale un punteggio di rischio e una raccomandazione. Con RiskCogs carichi l’SDK browser nel checkout, invii sessione e ordine dal server a POST /v1/risk-score, agisci sulla raccomandazione e riporti l’esito.

Inizia gratis in modalità shadow

1. Carica l’SDK browser nel checkout

L’SDK raccoglie, con il consenso dell’utente, il contesto di dispositivo e sessione e restituisce un ID di sessione per il server. Endpoint e chiave sono nella 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. Valuta il pagamento dal server

Chiama l’API prima di inviare il pagamento al fornitore. Con Node 18 o successivo non servono librerie.

// 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. Oppure prova con 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. Leggi la risposta e agisci

Usa recommendation per instradare il pagamento: accettare, verificare o rifiutare. In modalità shadow registra la raccomandazione senza cambiare il flusso.

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

Chiavi, importi e feedback

Due chiavi: pub_ per l’SDK browser, pr_ per il server. La chiave segreta non arriva mai al browser.
Importi come stringa decimale con valuta, ad esempio "49.00" EUR.
La risposta contiene riskId, risk_score, level, recommendation, shadowMode, flags e signals.
Conserva riskId e invia l’esito a POST /v1/risk-feedback.
Soglie predefinite: sotto 40 accettare, 40–69 verificare, da 70 rifiutare.

Diagramma di sequenza: SDK nel checkout, chiamata server a POST /v1/risk-score, punteggio e motivi, poi feedback a POST /v1/risk-feedback

Domande frequenti

Cos’è un’API antifrode?

Un servizio web che riceve dati di pagamento, account o login e restituisce un punteggio con un’azione consigliata.

Dove chiamarla nel checkout?

Dal server, dopo l’invio dell’ordine e prima del fornitore di pagamento, passando l’ID di sessione dell’SDK.

Perché inviare gli esiti?

Così il punteggio impara quali pagamenti erano buoni, rimborsati o contestati.

Funziona con più fornitori?

Sì, il punteggio si calcola prima di qualsiasi fornitore.

Prima misura. Poi blocca.

Usa RiskCogs in modalità shadow accanto al tuo attuale fornitore di pagamenti e verifica le decisioni prima che tocchino un solo cliente.