Dokumentation zum Softwares 3D Secure Integration Guide
Integrationsleitfaden 3D Secure
Ab dem 01.01.2021 wird die Zwei-Faktor-Authentifizierung als obligatorische Anforderung für alle E-Commerce-Kartenzahlungstransaktionen eingeführt. Um dieser Verpflichtung nachzukommen,
Betreiber von Kreditkartennetzwerken werden das sogenannte 3D Secure-Verfahren verwenden. Für Sie als Händler ist es zwingend erforderlich, dieses Verfahren für Ihre Kunden durchführen zu können.
01.01.2021. Nachfolgend finden Sie eine Beschreibung der verschiedenen Integrationsmöglichkeiten und wie das 3D Secure Verfahren hierfür umgesetzt werden muss.
Bitte wählen Sie die von Ihnen verwendete Integrationsmethode aus
- Nutzen Sie das Checkout-Formular hCO?
- Nutzen Sie das Checkout-Formular hPF?
- Verarbeiten Sie Zahlungen ohne die Nutzung eines vom Unzer-System bereitgestellten Formulars?
Bitte beachten Sie: Wichtig ist auch, auf welche Art und Weise Abbuchungen oder Vorautorisierungen (Reservierungen) erfolgen. Auch wenn Sie zur Erfassung der Kartendaten ein Zahlformular der Unzer GmbH verwenden, wird bei der ersten Abbuchung bzw. Autorisierung der Kartendaten das 3D Secure Verfahren ohne Checkout-Formular durchgeführt. In diesem Fall greift der von Unzer bereitgestellte dritte Weg der formularlosen Einbindung.
Bitte beachten Sie auch:
Wenn Sie wiederkehrende Zahlungen (Abonnementzahlungen) verwenden, lesen Sie unbedingt den Abschnitt „3D Secure und wiederkehrende Zahlung“.
3D Secure Verfahren bei Nutzung des hCO Checkout-Formulars
Das hCO-Checkout-Formular ist bereits für das 3D Secure-Verfahren ausgelegt. Für die Durchführung des Verfahrens sind von Ihrer Seite keine weiteren Maßnahmen erforderlich. Sie
müssen Sie sicherstellen, dass Ihr System die entsprechenden Antworten unseres Zahlungssystems verarbeiten kann, falls der 3D Secure-Prozess gestartet wird. In der asynchronen Antwort des
Zahlungssystem an Ihren Server, das Ergebnis der Transaktion wird übermittelt und muss dort vor einer Rückgabe ausgewertet werden URL wird an das Zahlungssystem übermittelt.
Hierzu müssen folgende Parameter ausgewertet werden.
- VERARBEITUNG.RÜCKGABECODE = 000.200.000
- PROCESSING.RETURN = Transaktion+ausstehend
- VERARBEITUNG.ERGEBNIS = ACK
Erläuterung: Der Status der Transaktion ist „pending“, der Parameter PROCESSING.RESULT
stellt nur ein vorläufiges Ergebnis dar. Solange der 3D Secure-Prozess durchgeführt wird, ist der Status
bleiben weiterhin offen.
Das Endergebnis der Transaktion ist dann entweder
- VERARBEITUNG.RÜCKGABECODE = 000.000.000
- VERARBEITUNG.ERGEBNIS = ACK
or - PROCESSING.RETURN.CODE = irgendein Wert ungleich 000.000.000 oder 000.200.000
- VERARBEITUNG.ERGEBNIS = NOK
Im ersten Fall wurde die Transaktion erfolgreich abgeschlossen, im zweiten Fall ist sie insgesamt fehlgeschlagen. Letzteres kann verschiedene Gründe haben, darunter eine Ablehnung der Authentifizierung. Sie werden
Genauere Informationen erhalten Sie in den Parametern „PROCESSING.RETURN“ und „PROCESSING.RETURN.CODE“.
Wir empfehlen, dass Sie für beide Nachrichten einen Test durchführen. Weitere Informationen dazu, wie Sie einen Test durchführen und welche Kreditkartendaten Sie für einen Test verwenden können, finden Sie weiter unten.
3D Secure Verfahren bei Nutzung des hPF Checkout-Formulars
Auch das hPF-Checkout-Formular ist bereits für die Nutzung des 3DS-Verfahrens ausgelegt. Für die Durchführung des Verfahrens sind keine weiteren Maßnahmen Ihrerseits erforderlich. Wie beschrieben
Bei der hCO-Implementierung erfolgt die Antwort des Zahlungssystems in zwei Schritten, weshalb Ihr System den Wert des PROCESSING.RETURN.CODE überprüfen muss
Parameter bei der Verarbeitung der Antwort.
Hierzu müssen folgende Parameter ausgewertet werden.
- VERARBEITUNG.RÜCKGABECODE = 000.200.000
- PROCESSING.RETURN = Transaktion+ausstehend
- VERARBEITUNG.ERGEBNIS = ACK
Erläuterung: Der Status der Transaktion ist „pending“, der Parameter PROCESSING.RESULT stellt nur ein vorläufiges Ergebnis dar. Solange der 3D Secure Prozess durchgeführt wird, ist der Status
bleiben weiterhin offen.
Das Endergebnis der Transaktion ist dann entweder
- VERARBEITUNG.RÜCKGABECODE = 000.000.000
- VERARBEITUNG.ERGEBNIS = ACK
or - PROCESSING.RETURN.CODE = irgendein Wert ungleich 000.000.000 oder 000.200.000
- VERARBEITUNG.ERGEBNIS = NOK
Im ersten Fall wurde die Transaktion erfolgreich abgeschlossen, im zweiten Fall ist sie insgesamt fehlgeschlagen. Letzteres kann verschiedene Gründe haben, darunter eine Ablehnung der Authentifizierung. Sie werden
Genauere Informationen erhalten Sie in den Parametern „PROCESSING.RETURN“ und „PROCESSING.RETURN.CODE“.
Wir empfehlen, dass Sie für beide Nachrichten einen Test durchführen. Weitere Informationen dazu, wie Sie einen Test durchführen und welche Kreditkartendaten Sie für einen Test verwenden können, finden Sie weiter unten.
3D Secure Verfahren mit Direktanbindung
Sofern Sie für die Abwicklung von Kreditkartenzahlungen kein von Unzer (vormals heidelpay) bereitgestelltes Zahlformular verwenden oder lediglich eine Karte über eines der Formulare registrieren und die Vorautorisierung (Reservierung) bzw. Abbuchung als Bezug zur Registrierung als direkte Kommunikation mit dem Zahlungssystem abwickeln, müssen Sie das 3D Secure Verfahren implementieren.
Asynchroner Transaktionsfluss:
Dies ist ein asynchroner Prozess, bei dem Ihr Server eine Weiterleitung erhält URL (Umleiten URL) von unserem Zahlungssystem. Ihr Server muss den Kunden an dieses weiterleiten URL damit er die Authentifizierung per 3D Secure Verfahren durchführen kann. Das Ergebnis dieser 3D Secure Authentifizierung wird von der kartenausgebenden Bank direkt an Unzer gemeldet.
Nach erfolgreicher Authentifizierung wird die Transaktion im Unzer-System wie von Ihnen gewohnt weiterverarbeitet, indem Ihr System am Ende ein Gesamtergebnis übermittelt, auf das Sie antworten
mit einer Umleitung URL. Das Zahlungssystem leitet den Kunden dann mit dieser Weiterleitung zurück zu Ihrem System URL von Ihrem System
Bitte beachten Sie: In diesem Workflow erhält Ihr System zwei Antworten vom Zahlungssystem:
– Eine mit dem Status „pending“ (PROCESSING.RETURN.CODE=000.200.000 und PROCESSING.RETURN=Transaction+pending) und den Umleitungsparametern an die kartenausgebende Bank des Kunden
– Eine mit dem Endergebnis der Abbuchung oder Reservierung. Außerdem gibt es zwei Umleitungs URLDabei handelt es sich um zwei Prozesse, einen aus dem Bezahlsystem, zu dem der Kunde weitergeleitet werden muss, um sich bei seiner kartenausgebenden Bank zu authentifizieren und einen aus Ihrem System, um den Kunden nach Erhalt des Endergebnisses wieder zurück in Ihr System zu leiten.
Die folgenden Änderungen werden gegenüber dem regulären Verfahren vorgenommen. Bitte beachten Sie, dass aufgrund der Implementierung anderer asynchroner Zahlungsmethoden, wie z. B. Paypal, einige dieser
In Ihrer Implementierung sind möglicherweise bereits Prozesse vorhanden.
- Antwort URL
Beim ersten Aufruf (Nr. 2 im Diagramm) an das Zahlungssystem wird eine „Response URL“ muss in der Frontend-Gruppe übergeben werden.
Bitte beachten Sie: Der Parameter IDENTIFICATION.REFERENCEID ist nur relevant, wenn Sie sich auf eine Registrierung oder eine andere bereits bestehende Transaktion beziehen. - Weiterleitung wird verarbeitet URL Wenn eine Authentifizierung erforderlich ist, wird eine Umleitung URL und weitere Parameter der Redirect-Gruppe werden in der Antwort des Bezahlsystems übergeben (Nr. 5 im Diagramm).
- Weiterleitung des Kunden an die Redirect URL
Wenn die Umleitungsgruppe mit einer Umleitung antwortet URLmuss der Browser des Kunden auf diese Seite umgeleitet werden. URL (Nr. 6 im Diagramm), um die Authentifizierung durchzuführen. Die zusätzlichen Parameter aus der Umleitungsgruppe müssen an die externe webSite als POST-Parameter.
Bitte beachten: Nur bei 3D Secure Version 1 werden zusätzliche Parameter in der Gruppe „PROCESSING.REDIRECT.xxx“ zurückgegeben (auch dort können Anzahl und Benennung variieren), bei 3D Version 2 hingegen nur ein PROCESSING.REDIRECT.URL wie unten angezeigt wird zurückgegeben: https://heidelpay.hpcgw.net/AuthService/v1/auth/public/2258_2863FFA4C5241C12E39F37
CCF/run Dies bedeutet, dass der Client-Browser unabhängig von der Art und Anzahl der Parameter zu PROCESSING.REDIRECT umleiten muss.URL.
Nachfolgend finden Sie einen einfachen Code, z. B.ample, wie eine solche Umleitung durchgeführt werden kann. Die Teil ist für Endkunden gedacht, deren Systeme Javascript nicht unterstützen oder deaktiviert haben. Wir empfehlen dringend, die Weiterleitung innerhalb des aktiven Browserfensters des Kunden durchzuführen und keine Popup-Fenster oder neue Browserfenster zu verwenden, da dies
Kunden verärgern und dazu führen, dass sie die Seite schließen, auf die sie weitergeleitet werden.
- Asynchrone Ergebnisprüfung
Das Ergebnis der Authentifizierung wird asynchron an Ihren Server gesendet. Das Zahlungssystem erwartet eine gültige URL als Antwort. (Nr. 12 und 13 im Diagramm). Für erfolgreiche oder abgelehnte
Zahlungen, eine andere URL können hier von Ihrem System beantwortet werden. - Rückweg des Kunden
Das Zahlungssystem leitet den Kunden weiter zum URL wird vom System des Händlers bereitgestellt, nachdem der Authentifizierungsprozess und die Zahlungstransaktion abgeschlossen sind.
Bitte beachten Sie: Die Schritte 4.) und 5.) laufen exakt so ab, wie Sie es bereits von bestehenden NONE 3D Secure Transaktionen kennen.
3D Secure und wiederkehrende Zahlung
Ab dem 1. Januar 2021 ist 3D Secure für alle E-Commerce-Kartentransaktionen obligatorisch. Da dies jedoch bei wiederkehrenden Zahlungen kaum anwendbar ist,
Systeme verfügen hierfür über einen eigenen Workflow.
Zu diesem Zweck unterscheiden die Banken zwischen
- CIT = vom Kunden initialisierte Transaktionen
- MIT = vom Händler initialisierte Transaktionen
Die erste Transaktion einer Karte in Ihrem Händlerkonto muss ab dem 3 mit 01.01.2021D Secure authentifiziert werden. Eine solche erfolgreiche Authentifizierung ist eine zwingende Voraussetzung in
um anschließend weitere Buchungen mit derselben Karte ohne 3D Secure vornehmen zu können. Der Kunde muss also für die erste Abbuchung in
gemäß dem oben beschriebenen Verfahren und authentifiziert sich dort als Karteninhaber. Ist zum Zeitpunkt der Bestellung keine Abbuchung vorgesehen, z.B.ampAufgrund einer Testphase muss stattdessen eine Reservierung (Vorautorisierung) von mindestens einem Euro mit 3D Secure im Beisein des Kunden vorgenommen werden. Eine Erfassung dieser Reservierung ist nicht notwendig.
Für Bestandskunden muss jedoch keine 3D Secure-Authentifizierung durchgeführt werden. Wenn die erste erfolgreiche Abbuchung vor dem 01.01.2021 erfolgte, kann auch davon ausgegangen werden, dass der Kundendatensatz
wurden erfolgreich authentifiziert. Für Neukunden ab 01.01.2021 ist die 3D Secure Authentifizierung hingegen bei der ersten Abbuchung bzw. Reservierung verpflichtend (Vorautorisierung).
Bitte beachten Sie: Das Banksystem schaut sich insoweit die Kartendaten an, nicht die Kundendaten. Wenn also ein Bestandskunde nach dem 01.01.2021 eine neue Karte nutzt, z.B.ample, weil die vorherige
abgelaufen ist oder weil er seine kartenausgebende Bank gewechselt hat, ist dies aus Sicht der Banken ein neuer wiederkehrender Zyklus view und muss bei der ersten Buchung mit 3D Secure authentifiziert werden.
Sobald diese erste Authentifizierung erfolgreich durchgeführt wurde, sind alle weiteren Transaktionen von der Verpflichtung zur Nutzung von 3D Secure befreit. Die Voraussetzungen für wiederkehrende Zahlungen ohne 3D Secure sind daher:
- Es liegt mindestens eine erfolgreiche Abbuchung bzw. Reservierung (Vorautorisierung) vor, die entweder mit 3D Secure durchgeführt wurde oder vor dem 01.01.2021 stattgefunden hat.
- es wird auf eine bestehende Anmeldung verwiesen und bei Einreichung abgebucht
Um dem Zahlungssystem mitzuteilen, dass es sich um eine wiederkehrende Zahlung handelt, muss zusätzlich der Parameter RECURRENCE.MODE=REPEATED gesendet werden. Dies signalisiert dem System, dass eine
Die wiederkehrende Zahlung ist an die Banksysteme zu melden.
Bitte beachten Sie: Wird beim erstmaligen Aufladen einer neuen Karte der Parameter RECURRENCE.MODE=REPEATED eingetragen, wird die 3D Secure Weiterleitung trotz dieses Parameters durchgeführt.
Testen der 3D Secure-Implementierung
Sie können die 3D Secure Verbindung jederzeit über unser Zahlungssystem testen. Nutzen Sie dazu den Modus „CONNECTOR_TEST“ für eine Transaktion, wie im Beispiel gezeigt.amples oben.
Verbindungsdaten für diesen Test:
| SICHERHEIT.SENDER | 31HA07BC8142C5A171745D00AD63D182 |
| BENUTZER-ANMELDUNG | 31ha07bc8142c5a171744e5aef11ffd3 |
| USER.PWD | 93167DE7 |
| TRANSAKTIONSKANAL | 31HA07BC8142C5A171749A60D979B6E4 |
| Für 3D Version 2 konfigurierte Währungen | EUR, USD, SEK |
| Für 3D Version 1 konfigurierte Währungen | GBP, CZK, CHF |
Der System-Gateway-Endpunkt ist entweder
SGW-Gateway:
– https://test-heidelpay.hpcgw.net/sgw/gtw – Latin-15 kodiert
– https://test-heidelpay.hpcgw.net/sgw/gtwu – UTF-8 kodiert
NGW-Gateway:
– https://test-heidelpay.hpcgw.net/ngw/post
Kreditkartendaten für diesen Test:
| Marken | Kartennummern | CVV | Verfallsdatum | Notiz |
| MasterCard | 5453010000059543 | 123 | zukünftiges Datum | 3D – Passwort: secret3 |
| Visum | 4711100000000000 | 123 | zukünftiges Datum | 3DS – Passwort: geheim!33 |
Bitte beachten Sie: Bei 3D Secure Version 2 müssen Sie kein Passwort eingeben, sondern können lediglich auf den Link „Klicken Sie hier, um die Authentifizierung abzuschließen“ klicken.
Die einzige Möglichkeit einen Fehler bei 3D Secure Version 2 zu simulieren besteht darin, auf der Seite mit dem Link ein Timeout (ca. 18 Minuten) ablaufen zu lassen.
Lesen Sie mehr über dieses Handbuch und laden Sie das PDF herunter:
Dokumente / Ressourcen
 |
Software 3D Secure Integrationshandbuch [pdf] Dokumentation Unzer, Integration Guide, 3D Secure |
