Kontextsignale

Bevor Sie beginnen

Kontextsignale bewerten abgeschlossene Kredittransaktionen und liefern eine Risikobewertung — Eigenbetrug oder Social Engineering — um Ihre eigene Betrugspräventionsentscheidung zu ergänzen.

Sie ergänzen Verifizierung ohne physische Karte: Sie ändern weder den Vertrag noch das Verhalten der Transaktions-Endpunkte, die Sie bereits verwenden. Sie erhalten weiterhin wie gewohnt den Endstatus der Transaktion (approved, inconclusive usw.) und fragen anschließend die Kontextsignale ab.

Ihre API-Anfragen werden mit einem Zugriffstoken authentifiziert. Jede Anfrage, die kein gültiges Zugriffstoken enthält, gibt einen Fehler zurück. Erfahren Sie mehr unter Authentifizierung.

Berechtigungsgesteuerter Zugriff

Der Zugriff auf diesen Endpunkt wird durch eine Ihrem Unternehmen zugewiesene Berechtigung (Rolle) gesteuert. Ohne diese gibt der Endpunkt 403 zurück. Fordern Sie die Freischaltung beim Unico-Team an.

Basis-URL

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

Kontextsignale abrufen

GET /transactions/{transaction_id}/signals — liefert die Risikobewertung einer abgeschlossenen Transaktion.

Das Ergebnis wird asynchron vorab berechnet, sobald die Transaktion ihren Endstatus erreicht. Dieser Endpunkt dient daher nur zum Abrufen eines bereits verfügbaren Ergebnisses.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
transaction_id	string	ja	Transaktions-ID (UUID v4). Zum Beispiel 6ab1771e-dfab-4e47-8316-2452268e5481.

Header

Header	Wert
Authorization	Bearer {token} — ein gültiges Zugriffstoken.
Accept	application/json

Anfragebeispiel

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
    }
  }
}

Feld	Typ	Vorhandensein	Beschreibung
signals.auto_fraud_risk	string (enum)	optional	Risikostufe für Eigenbetrug. Nur vorhanden, wenn erkannt.
signals.social_eng_risk	string (enum)	optional	Risikostufe für Social Engineering. Nur vorhanden, wenn erkannt.
signals.more_info.limited_data	boolean	immer	true, wenn nicht genügend Daten für eine belastbare Bewertung vorliegen.
signals.more_info.holder_identified	boolean	immer	false, wenn der Karteninhaber nicht identifiziert werden konnte.

Mögliche Risikowerte: very_low, low, medium, high, very_high.

Information

auto_fraud_risk und social_eng_risk schließen sich gegenseitig aus — sie erscheinen niemals gemeinsam in derselben Antwort. Wenn limited_data den Wert true hat, wird erwartet, dass beide Risikofelder fehlen, da nicht genügend Daten für eine Bewertung vorliegen.

Antwortbeispiele

Social-Engineering-Risiko erkannt:

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

Kein Risiko festgestellt — eine reguläre Transaktion:

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

Nicht genügend Daten:

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

Karteninhaber nicht identifiziert:

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

Weitere Antwortcodes

Fehler werden im in Fehler beschriebenen Standardfehlerformat zurückgegeben.

HTTP-Code	Code	Situation	Was zu tun ist
202	—	Das Ergebnis wurde noch nicht berechnet — die asynchrone Verarbeitung läuft noch.	Wiederholen Sie den Aufruf (Polling), bis Sie ein 200 erhalten.
400	40004	transaction_id ist ungültig (keine UUID v4) oder ein Parameter ist fehlerhaft formatiert.	Korrigieren Sie das ID-Format, bevor Sie die Anfrage erneut senden.
403	40305	Das Unternehmen verfügt nicht über die für diesen Endpunkt aktivierte Berechtigung (Rolle).	Fordern Sie die Freischaltung beim Unico-Team an.
404	40401	Die Transaktion wurde nicht gefunden.	Überprüfen Sie die Transaktions-ID.
404	40484	Die Transaktion wurde für die Bewertung nicht gefunden.	Behandeln Sie dies als „es wird kein Ergebnis geben“ und stoppen Sie die Abfrage.
409	40983	Die Transaktion hat ihren Endstatus noch nicht erreicht.	Warten Sie auf den Endstatus, bevor Sie erneut abfragen.
500	—	Interner Dienstfehler.	Wiederholen Sie mit Backoff. Wenn das Problem weiterhin besteht, wenden Sie sich an den Unico-Support.

Regeln und bewährte Praktiken

• Fragen Sie den Endpunkt erst ab, nachdem die Transaktion ihren Endstatus erreicht hat. Eine frühere Abfrage gibt 409 zurück.
• Nur Kredittransaktionen werden bewertet. Im Silent Mode erfasste Transaktionen werden nicht bewertet.
• Wiederholen Sie bei einem 202 den Aufruf, bis Sie ein 200 erhalten. Senden Sie die erste Anfrage 1 Sekunde nach der Transaktionsantwort und erhöhen Sie dann die Wartezeit: 2 s, 4 s, 8 s, 16 s — bis zu 5 Versuche.
• Das Service Level Objective beträgt 10 Sekunden nach der Transaktionsantwort.
• Behandeln Sie ein 404 als „es wird kein Ergebnis geben“ und stoppen Sie die Abfrage.
• auto_fraud_risk und social_eng_risk schließen sich gegenseitig aus.