Telefonverifizierung: Warnungen & Risiko-Codes

Die Funktion Telefonverifizierung gibt Warnungen aus, sobald ein Risikosignal im OTP-Ablauf oder für die Nummer selbst ausgelöst wird: eine bekannte betrügerische Nummer, ein VoIP- oder Einweganschluss, das Erreichen eines Limits für OTP-Versuche oder ein Treffer mit der Sitzung eines anderen Benutzers. Diese Seite listet alle Codes auf, was sie auslöst und wie Sie die Workflow-Reaktion konfigurieren.

Übersicht

Warnungen sind mit der Funktion PHONE gekennzeichnet. Sie erscheinen unter phone_verifications[].warnings[] in GET /v3/session/{sessionId}/decision/ und folgen der standardmäßigen Struktur des Warnungsobjekts (feature, risk, additional_data, log_type, short_description, long_description, node_id). Jede Warnung wird zudem in das sitzungsspezifische Protokoll geleitet, sodass sie in der Business Console im Bereich „Phone“ angezeigt wird. Einige Warnungen sind Auslöser für eine feste automatische Ablehnung – sie setzen den Funktionsstatus immer auf Declined. Andere sind einer konfigurierbaren Aktion zugeordnet (DECLINE, REVIEW oder NO_ACTION, je nach Einstellung), die in Ihren Workflow-Einstellungen definiert ist, sodass derselbe Risiko-Code einen Workflow ablehnen kann, während er einen anderen lediglich markiert.

Bedingungen für die automatische Ablehnung

Die folgenden Warnungen lehnen den Schritt der Telefonverifizierung unabhängig von der Konfiguration immer ab und weisen stets log_type: "error" auf:

VERIFICATION_CODE_ATTEMPTS_EXCEEDED — der Benutzer hat ein Limit für OTP-Versuche ausgeschöpft: standardmäßig 2 fehlerhafte Code-Eingaben (phone_max_check_attempts) oder mehr als 2 OTP-Versendungen (phone_max_retries), beides pro Workflow-Knoten anpassbar. Die eigenständige Telefon-API erlaubt 3 Code-Versuche.
PHONE_NUMBER_IN_BLOCKLIST — die Nummer befindet sich in Ihrer über die Lists API verwalteten Sperrliste oder stimmt mit einer auf der Sperrliste geführten Sitzung überein.

HIGH_RISK_PHONE_NUMBER — die Betrugsbekämpfungsebene des Zustellanbieters verweigert den Versand des OTP (Blocked-Versand) — lehnt standardmäßig ab, ist jedoch nicht mehr bedingungslos: siehe high_risk_phone_action unten.

Konfigurierbare Risiken

Jedes der folgenden Risiken ist einer Workflow-Einstellung zugeordnet, die Sie auf DECLINE, REVIEW oder NO_ACTION konfigurieren können (die Standardeinstellung – die Warnung wird erfasst, ohne den Status zu beeinflussen). Die konfigurierte Aktion legt auch den log_type der Warnung fest: DECLINE → error, REVIEW → warning, NO_ACTION → information.

Einstellung	Risiko-Code	Wird ausgelöst, wenn
`voip_number_action`	`VOIP_NUMBER_DETECTED`	Der Anschluss vom Netzbetreiber als Leitungstyp `voip`, `isp` oder `vpn` eingestuft wird.
`disposable_number_action`	`DISPOSABLE_NUMBER_DETECTED`	Die Abfrage den Anbieter der Nummer als temporären/Wegwerf-Anbieter kennzeichnet.
`duplicated_phone_number_action`	`DUPLICATED_PHONE_NUMBER`	Die Nummer mit einer anderen Sitzung mit beliebigem Status übereinstimmt, die zu einem anderen Endbenutzer gehört. Wird übersprungen, wenn die Nummer auf der Positivliste steht.

Die Duplikaterkennung läuft innerhalb Ihrer Anwendung über KYC, KYB und eigenständige API-Telefonverifizierungen hinweg und gruppiert Sitzungen nach vendor_data – Sitzungen mit demselben vendor_data-Wert werden als ein einzelner Endbenutzer behandelt und von den Treffergebnissen ausgeschlossen. Bleibt vendor_data leer, wird jede Sitzung als eigenständiger Benutzer behandelt.

Blockierte Versendungen

HIGH_RISK_PHONE_NUMBER folgt demselben Muster mit einem kleineren Auswahlsatz, da eine vom Anbieter verweigerte Versendung nicht genehmigt werden kann:

Einstellung	Risiko-Code	Wird ausgelöst, wenn
`high_risk_phone_action`	`HIGH_RISK_PHONE_NUMBER`	Die Betrugsbekämpfungsebene des Zustellanbieters das Senden des OTP verweigert hat (`Blocked`-Versand). Akzeptiert nur `DECLINE` oder `REVIEW` und ist standardmäßig auf `DECLINE` gesetzt.

Die Einstellung wird nur dann angewendet, wenn jede Hochrisiko-Blockierung für den Schritt in additional_data.risk_factors exakt ["device_attribute"] enthält – das Signal des Anbieters „dieses Gerät sieht verdächtig aus“, das bei gewöhnlichen Mobilfunkanschlüssen anschlägt. Jeder andere Risikofaktor, jede Mischung, die device_attribute lediglich enthält, oder eine Blockierung ganz ohne Risikofaktoren führt unabhängig von der Einstellung zu einer Ablehnung. Der Grund für die Blockierung (repeated_attempts, suspicious oder spam) ist ein separates Feld, das in additional_data.blocked_reason zurückgegeben wird. Unabhängig von der Einstellung wird eine Nummer auf einer über die Lists API erstellten Telefon-Positivliste bei einem blockierten Versand niemals automatisch abgelehnt: Der Schritt wechselt zu In Prüfung, die Warnung weist log_type: "warning" auf und additional_data.phone_number_in_allowlist ist true.

Limits für Verifizierungsversuche

Die Funktion „Telefonverifizierung“ wendet eine feste Obergrenze für OTP-Versuche an, um Missbrauch zu verhindern:

Code-Eingabeversuche — Standardmäßig 2 falsche Eingaben (phone_max_check_attempts), bevor der Schritt als Declined mit VERIFICATION_CODE_ATTEMPTS_EXCEEDED abgeschlossen wird. Die Standalone-Telefon-API erlaubt 3 Code-Versuche pro Verifizierung.
Sendeversuche — Standardmäßig insgesamt 2 Sendungen (phone_max_retries): der anfängliche Versand plus ein erneuter Versand. Eine weitere Sendeanfrage schließt den Schritt ab und löst VERIFICATION_CODE_ATTEMPTS_EXCEEDED aus.
OTP-Gültigkeit — Ein ausstehendes OTP ist für 5 Minuten ab dem ersten Versand gültig; Wiederholungsversuche verlängern dieses Zeitfenster nicht.

Beide Obergrenzen sind pro Workflow-Knoten anpassbar. Unabhängig von diesen Obergrenzen kann die Betrugserkennung des Zustellanbieters einen Versand direkt blockieren (Grund repeated_attempts, suspicious oder spam) – dies löst HIGH_RISK_PHONE_NUMBER aus, nicht die Warnung zu Versuchen.

Generierte Warnungen

Tag	`log_type`	Beschreibung
`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`	`error` (immer)	Der Benutzer hat die Obergrenze für OTP-Code-Eingaben oder Sendeversuche überschritten. Wird automatisch abgelehnt.
`HIGH_RISK_PHONE_NUMBER`	Folgt `high_risk_phone_action` oder `warning`, wenn auf der Allowlist	Der Zustellanbieter hat den OTP-Versand blockiert. Wird standardmäßig abgelehnt; setzen Sie `high_risk_phone_action` auf `REVIEW`, um eine Blockierung, die ausschließlich auf Gerätesignalen basiert, stattdessen in den Status „In Prüfung“ weiterzuleiten (siehe Blockierte Sendungen). Eine Nummer auf einer Telefon-Allowlist wird ebenfalls in den Status „In Prüfung“ versetzt. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`.
`PHONE_NUMBER_IN_BLOCKLIST`	`error` (immer)	Die Nummer befindet sich auf einer Sperrliste, die über die Lists API erstellt wurde, oder stimmt mit einer Sitzung auf der Sperrliste überein. Wird automatisch abgelehnt. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (alle `null` bei einem reinen Listentreffer).
`PHONE_NUMBER_IN_ALLOWLIST`	`information`	Die Nummer stimmte mit anderen Sitzungen überein, befindet sich jedoch auf einer Allowlist, die über die Lists API erstellt wurde, sodass Aktionen für doppelte Telefonnummern übersprungen werden. `additional_data`: `{ phone_number }`.
`DISPOSABLE_NUMBER_DETECTED`	Folgt `disposable_number_action`	Die Nummer stammt von einem Anbieter für temporäre/Wegwerfnummern, die häufig verwendet werden, um die Rückverfolgbarkeit zu umgehen.
`VOIP_NUMBER_DETECTED`	Folgt `voip_number_action`	Die Nummer führt zu einem `voip`-, `isp`- oder `vpn`-Anschluss anstelle eines standardmäßigen Mobilfunk- oder Festnetzanschlusses.
`DUPLICATED_PHONE_NUMBER`	Folgt `duplicated_phone_number_action`	Die Nummer stimmt mit einer anderen Sitzung – unabhängig von deren Status – überein, die zu einem anderen Endbenutzer gehört (gruppiert nach `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`.

Sitzungsübergreifende Übereinstimmungen

Wenn eine Nummer in anderen Sitzungen oder auf Ihrer Sperrliste erkannt wird, erscheinen diese Treffer auch unter phone_verifications[].matches[] (begrenzt auf 5 Einträge). Jeder Treffer enthält session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service und den Wert session für source (eine andere Sitzung mit derselben Nummer, beliebiger Status) oder list_entry (ein synthetischer Sperrlistentreffer, der dem Array vorangestellt wird). Befindet sich die aktuelle Nummer auf Ihrer Telefon-Allowlist, behält Didit die Übereinstimmungsnachweise bei, gibt jedoch PHONE_NUMBER_IN_ALLOWLIST aus, anstatt die Aktion für doppelte Nummern anzuwenden. Siehe den Bericht zur Telefonverifizierung für das vollständige Schema für Übereinstimmungen.

Beispiel

Ein blockierter Versand (HIGH_RISK_PHONE_NUMBER) bei einer VoIP-Nummer, wobei voip_number_action auf REVIEW konfiguriert ist:

{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}

Warnungstypen

Jedem Risiko wird basierend auf der Konfiguration Ihrer Anwendung ein Schweregrad zugewiesen. Schweregrade unterteilen sich in drei Kategorien:

Authentifizierung

Verifizierung

Überwachung

Plattform

Telefonverifizierung: Warnungen & Risiko-Codes

Übersicht

Bedingungen für die automatische Ablehnung

Konfigurierbare Risiken

Blockierte Versendungen

Limits für Verifizierungsversuche

Generierte Warnungen

Sitzungsübergreifende Übereinstimmungen

Beispiel

Warnungstypen

Verwandte Themen

​Übersicht

​Bedingungen für die automatische Ablehnung

​Konfigurierbare Risiken

​Blockierte Versendungen

​Limits für Verifizierungsversuche

​Generierte Warnungen

​Sitzungsübergreifende Übereinstimmungen

​Beispiel

​Warnungstypen

​Verwandte Themen

Übersicht

Bedingungen für die automatische Ablehnung

Konfigurierbare Risiken

Blockierte Versendungen

Limits für Verifizierungsversuche

Generierte Warnungen

Sitzungsübergreifende Übereinstimmungen

Beispiel

Warnungstypen

Verwandte Themen