OneSpan Developer: Endpunkt für die Transaktionsvalidierung

Hakim Aldaoub, 9. Dezember 2020

OneSpan Developer: Transaction Validation Endpoint

OneSpan Intelligent Adaptive Authentication (IAA ) bietet den Transaktionsvalidierungs-Endpunkt, um monetäre Ereignisse auf adaptive Weise zu behandeln. Immer wenn eine Anfrage in Richtung Transactions/Validate API ausgelöst wird, reagiert Risk Analytics (RA ), um die entsprechende Authentifizierungsmethode des Endbenutzers zu erfassen, basierend auf dem mit der Transaktion verbundenen Risiko. Im heutigen Blog erläutern wir, wie die Anfrage für eine monetäre Transaktion mithilfe der Sandbox Interactive API vorbereitet wird, und zeigen die möglichen RA-Antworten auf dieses Ereignis

Bevor wir beginnen

Bevor Sie den Transaktionsvalidierungs-Endpunkt erkunden können, müssen Sie zunächst Mitglied der OneSpan-Community sein und sich für ein kostenloses Intelligent Adaptive Authentication-Sandbox-Konto anmelden; hier finden Sie eine schrittweise Anleitung dazu.

Sie sollten auch sicher sein, dass mindestens ein registrierter Benutzer vorhanden ist, bevor Sie diesen Aufruf versuchen. Wie Sie einen Benutzer registrieren können, erfahren Sie in diesem ausführlichen Blog zur Benutzerregistrierung.

Endpunkt-URL

Die Anfrage-URL für diesen API-Aufruf wird dem unten stehenden Beispiel ähneln:

https://{Ihre_Mieter_ID}.sdb.tid.onespan.cloud/v1/users/{[email protected]}/transactions/validate

Sie müssen diese URL während des Tutorials nicht angeben. Sie dient nur dazu, die Struktur der URL zu zeigen. Die URL wird in der Interaktiven API beim Aufruf des Webservice automatisch zugewiesen

Probieren Sie es aus

Um mit der Transaktionsvalidierungs-API zu experimentieren, navigieren Sie in Ihrem OneSpan-Community-Konto zum Dokument IAA Sandbox Interactive API. Erweitern Sie im Open API Swagger-Editor die Ressource "Transactions". Sie finden dann einen Eintrag für die Methode "Transactions/Validate HTTP Post", wie in der folgenden Abbildung dargestellt

URL-Pfad-Parameter:

Für den Zweck des API-Aufrufs "Transaction/Validate" gibt es einen erforderlichen Pfadparameter für die eindeutige Benutzerkennung. Sie wird als [email protected] formatiert. Ein Beispiel für die UserID ist "iaa_user". Es ist die UserID, die auf dem vertrauenswürdigen Gerät aktiviert wurde. Der Teil des Parameters, der auf das "@"-Zeichen folgt, ist die Benutzerdomäne. Dieser Eintrag sollte durch die unten gezeigte Zeichenfolge "Sandbox-Benutzer" ersetzt werden, die Sie im Abschnitt "Sandbox-Details" unter der Registerkarte "Intelligente adaptive Authentifizierung" auf Ihrer Sandbox-Homepage finden.

Körper der Transaktionsvalidierungsanforderung

Wählen Sie unter dem Abschnitt "Request Body" des Endpunkts "Transaction/Validate" den Objekttyp "AdaptiveTransactionValidationInput" aus dem Dropdown-Menü aus, wie unten gezeigt. Sie erhalten dann ein Beispiel für die JSON-Anfrage-Payload, die vom Transaktionsvalidierungs-Endpunkt benötigt wird

Der Anfragerumpf sieht wie das folgende Beispiel für die erforderlichen Felder des Endpunkts "Transaction/Validate" aus.

{ "objectType": "AdaptiveTransactionValidationInput", "accountRef": "ACC123", "amount": "1064.99", "cddc": { "browserCDDC": { "fingerprintRaw": "{browser:{\"userAgent\":Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36},support:{\"ajax\":true,\"boxModel\":undefined,\"changeBubbles\":undefined,\"checkClone\":true,\"checkOn\":true,\"cors\":true,\"cssFloat\":undefined,\"hrefNormalized\":undefined,\"htmlSerialize\":undefined,\"leadingWhitespace\":undefined,\"noCloneChecked\":true,\"noCloneEvent\":undefined,\"opacity\":undefined,\"optDisabled\":undefined,\"style\":undefined,\"submitBubbles\":undefined,\"tbody\":undefined},computer:{\"screenWidth\":2560,\"screenHeight\":1440,\"OS\":\"Microsoft Windows\",\"platform\":\"Win32\"},additional:{}}", "fingerprintHash": "e96dadc9651f5fe8f071110eb174fe8e7a17a9d7a96b3b1980c13e5b4af3a4d7" } }, "currency": "EUR", "data": { "transactionMessage": { "dataFields": [

Nutzlast anfordern

Sie enthält zwei obligatorische JSON-Objekte, die in der Tabelle aufgeführt sind:

JSON Erforderliche Datenfelder	Beschreibung	Feld Datentyp
objektTyp*	Dies dient dazu, den Objekttyp für die Transaktion in der Anforderungs-Payload zu deklarieren ist für den Zweck der Intelligent Adaptive Authentication-Lösung.	Typ: Enum Beispiel: "[ AdaptiveTransactionValidationInput]"
kontoRef*	Verweis auf das Bankkonto des Kunden, der die Transaktion durchführt	Typ: JSON verschachteltes Objekt minLength: 1 maxLength: 250 Beispiel: Checking_Account_CH53
betrag*	Der Betragswert der Transaktion	Typ: String Muster: ^-?[0-9]{1,10}(\.[0-9]{1,2})?$ Beispiel: 999.99
cddc*	Client Device Data Collector-Metadaten. Die beiden Felder browserCDDC und mobileCDDC schließen sich gegenseitig aus und sind gemeinsam erschöpfend.	Typ: String Beispiel: "browserCDDC" oder "mobileCDDC"
beziehungRef*	Die Beziehungsreferenz der Benutzer-ID.	Typ: string minLength: 1 maxLength: 150 Beispiel: iaa_user
staticPassword*	Das anfängliche statische Kennwort, das dem Benutzer zugewiesen wurde.	Typ: String minLength: 8 maxLength: 255 Beispiel: Test1234
sessionID*	Kennung der Anwendungssitzung, formatiert als hexadezimale Zeichenfolge; gemeinsam für alle Transaktionen, die sich auf dieselbe Sitzung beziehen	Typ: String Muster: ^[0-9a-fA-F]+$ minLength: 2 maxLength: 100 Beispiel: 4ed23ea44f23
transaktionsTyp*	Dieses entscheidende Feld gibt den Transaktionstyp an, der in der Anfrage gesendet werden soll. Die Definition des Transaktionstyps ermöglicht die Flexibilität, dass die verschiedenen Transaktionen von Seiten der Risikoanalyse eindeutig behandelt werden können	Typ: String Beispiel: ExternalTransferBillPayments, MobileInternalTransfer

Aufrufen des Endpunkts

An diesem Punkt sind wir bereit, einen RESTful-Aufruf an den Endpunkt "Transaction/Validate" unter Verwendung der interaktiven IAA-Sandbox-API durchzuführen. Um den Aufruf durchzuführen, klicken Sie auf die Schaltfläche "Try it out", die im Screenshot unten gezeigt wird und sich rechts neben dem Abschnitt zur HTTP-POST-Methode befindet. Nach der Anfrage erhalten Sie den Antwortkörper in einem JSON-Format zurück. Sie ähnelt der Antwort-Payload, die im folgenden Abschnitt beschrieben wird.

Antwort-Nutzlast

Nachfolgend sehen Sie ein Beispiel für den zurückgegebenen Antwortkörper mit einem 200-Antwortcode, der eine erfolgreiche Transaktion anzeigt.

{ "requestID": "413b2c39-2d67-4293-9adb-25601731b062", "riskResponseCode": 0, "sessionStatus": "accepted", "requestMessage": "0000F8B81D" }

Beschreibung der Felder des Antwortkörpers

Die "requestID" ist das erste Feld in der Antwort, es ist eine Zeichenkette mit 36 Zeichen, die verwendet wird, um eine Referenz des vorangegangenen API-Aufrufs zu behalten. Diese ID kann für die Fehlersuche und Referenzierung nützlich sein.

Das Feld "riskResponseCode" ist der Antwortcode von Risk Analytics. Der Wert "0" in der obigen Antwort zeigt an, dass die Anfrage akzeptiert wurde und der Benutzer erfolgreich authentifiziert wurde, ohne dass zusätzliche Maßnahmen erforderlich waren. Nachfolgend finden Sie eine Liste anderer möglicher Werte, die von Risk Analytics zurückgegeben werden können. Außerdem können zusätzliche Werte über den Risk Analytics Presentation Service konfiguriert werden.

Risikoanalyse Verhalten	Risiko-Reaktions-Code (Ganzzahl)
Akzeptieren	0
Abnehmen	1
Herausforderung	2
HerausforderungSMS	3
ChallengeDevice2FA	5
HerausforderungEmail	8
HerausforderungCronto	11
ChallengeNoPIN	21
HerausforderungPIN	22
HerausforderungFingerabdruck	23
HerausforderungGesicht	24

Das Feld "sessionStatus" in der JSON-Antwort stellt den aktuellen Status der Sitzung dar, nachdem die Anfrage gesendet wurde, in der folgenden Tabelle sind die möglichen Statuswerte aufgeführt.

Session-Status	Status Beschreibung
unbekannt	Der Status ist nicht bekannt und die Antwort wird extern gehandhabt
anhängig	Warten auf eine Aktion des Endbenutzers
akzeptiert	Erfolgreich abgeschlossen
abgelehnt	Vom Endbenutzer abgelehnt
timeout	Zeitüberschreitung, nachdem innerhalb des Zeitrahmens keine Antwort empfangen wurde
gescheitert	Die OTP-Validierung schlägt fehl

Das Feld "requestMessage" ist vom Typ String. Es wird verwendet, um einen Orchestrierungsbefehl an das vertrauenswürdige Endbenutzergerät zu übertragen.

In diesem Blog haben wir beschrieben, wie Sie eine Geldtransaktion über die OneSpan Interactive API durchführen. In den kommenden Wochen werden wir weitere Blogs lesen, die sich auf den Endpunkt "Transaction/Validate" beziehen. Wenn Sie in der Zwischenzeit Fragen haben, können Sie uns in den Foren des OneSpan Community Portalserreichen .

OneSpan Blog