API-Dokumentation
Betrugserkennung per API: jede Zahlung vor dem Zahlungsanbieter bewerten
Eine Betrugserkennungs-API erhält Daten zu Zahlung, Kunde und Gerät und liefert in Echtzeit einen Risiko-Score mit Empfehlung. Mit RiskCogs laden Sie das Browser-SDK im Checkout, senden Sitzung und Bestellung serverseitig an POST /v1/risk-score, handeln nach der Empfehlung und melden das Ergebnis zurück.
Kostenlos im Shadow-Modus starten1. Browser-SDK im Checkout laden
Das SDK erfasst mit Einwilligung des Nutzers Geräte- und Sitzungskontext und liefert eine Session-ID für Ihren Server. Endpoint und Schlüssel finden Sie in der RiskCogs-Konsole.
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. Zahlung serverseitig bewerten
Rufen Sie die API auf, bevor Sie die Zahlung an Ihren Zahlungsanbieter senden. Node 18 oder neuer braucht keine zusätzliche Bibliothek.
// 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. Oder mit curl testen
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. Antwort lesen und handeln
Mit recommendation steuern Sie die Zahlung: durchlassen, prüfen oder ablehnen. Im Shadow-Modus protokollieren Sie die Empfehlung und lassen Ihren Ablauf unverändert.
{
"riskId": "0190f3c2-…",
"risk_score": 18,
"level": "low",
"recommendation": "allow",
"shadowMode": true,
"flags": [],
"signals": { "email": { … }, "ip": { … } }
}Schlüssel, Beträge und Feedback
- Zwei Schlüssel: pub_ für das Browser-SDK, pr_ für Server-Aufrufe. Der geheime Schlüssel erreicht nie den Browser.
- Beträge als Dezimal-String in Haupteinheiten mit Währung, z. B. "49.00" EUR.
- Die Antwort enthält riskId, risk_score, level, recommendation, shadowMode, flags und signals.
- Speichern Sie riskId und melden Sie das Ergebnis an POST /v1/risk-feedback.
- Standard-Schwellen: unter 40 durchlassen, 40 bis 69 prüfen, ab 70 ablehnen.
Häufige Fragen
Was ist eine Betrugserkennungs-API?
Ein Webdienst, der Daten zu Zahlung, Konto oder Login erhält und eine Risikobewertung mit Score und empfohlener Aktion zurückgibt.
Wo rufe ich die API im Checkout auf?
Serverseitig nach dem Absenden der Bestellung und vor der Übergabe an den Zahlungsanbieter. Übergeben Sie die Session-ID aus dem SDK.
Warum Ergebnisse zurückmelden?
Nur so lernt der Score aus Ihrem Traffic, welche Zahlungen gut waren, erstattet oder zurückgebucht wurden.
Funktioniert das mit mehreren Zahlungsanbietern?
Ja. RiskCogs bewertet die Zahlung, bevor sie einen Anbieter erreicht, mit derselben Logik für alle Anbieter.
Erst messen, dann durchsetzen.
Lassen Sie RiskCogs im Shadow-Modus neben Ihrem bestehenden Zahlungsanbieter laufen und prüfen Sie die Entscheidungen, bevor sie einen einzigen Kunden betreffen.