Mithilfe von Plugins wird die Integration der lynck Zahlungsarten und Dienstleistungen in den Checkout von Standard-Onlineshops erleichtert. Dabei kann die Art der Installation, je nach Shopsystem, sehr unterschiedlich sein. Weiterführende Informationen zur Installation befinden sich deshalb auf der jeweiligen Plugin-Seite.
Grundlegendes
Wie in vielen anderen Anwendungsbereichen, so gibt es auch in der lynck Welt einige Grundlagen und Vokabeln, mit denen wir uns vor der Integration von lynck vertraut machen sollten.
Begriffe
Transaktion
Unter einer Transaktion verstehen wir [den Rahmen für] einen einzelnen Zahlungsvorgang mit lynck. Der eindeutige Bezeichner einer lynck Transaktion ist die orderID. Um eine möglichst einfache Beziehung zwischen Bestellung und Zahlung herzustellen, verwenden diejenigen Plugins, bei denen die Bestellnummer des Shopsystems rechtzeitig bekannt ist, diese Bestellnummer auch als orderID. In einigen Shopsystemen wird die Bestellnummer jedoch erst nach der Auswahl der Zahlungsart vergeben. In diesen Fällen wird die orderID generisch vergeben und die Verknüpfung zur Bestellung wird über einen Datenbankverweis hergestellt.
Zusätzliche OrderID (merchantReference)
Die zusätzliche OrderID heißt technisch merchantReference und ist ein Attribut einer lynck Transaktion, das selbst nach der erfolgreichen Reservierung einer Transaktion verändert werden kann. Diejenigen lynck Plugins, welche mit einer generischen orderID arbeiten, nutzen dieses Feld, um nach dem Bestellabschluss die Shop-Bestellnummer als zusätzliche OrderID bei lynck bekannt zu machen.
Reservierung
Den vorläufigen Abschluss einer lynck-Zahlung im Checkout nennen wir bei lynck die Reservierung. Eine erfolgreiche Reservierung bedeutet im Sinne von lynck, dass eine Zahlung erfolgreich durch den Käufer autorisiert wurde. Das muss aber nicht bedeuten, dass das Geld dieser Zahlung bereits geflossen ist; beim Rechnungskauf beispielsweise ist das Geld noch nicht bezahlt, aber das lynck System hat die definierten Risiko- und Bonitätschecks positiv beendet und die Bestellung kann für den Versand vorbereitet werden.
Buchung (Capture)
Damit aus einer Reservierung eine offene Forderung – inkl. der lynck Zahlungsüberwachung – wird, muss die reservierte Zahlung gebucht werden. Die lynck Plugins automatisieren diesen Prozess in der Regel auf Grundlage der Rechnungserstellung im Shop-Backend oder anhand von Bestell-Status-Übergängen. Die individuell relevanten Informationen sind deshalb auf der jeweiligen Plugin Seite zu finden.
Gutschrift (Refund)
Gebuchte Beträge können – im Sinne einer Rechnungskorrektur – durch einen Refund nachträglich reduziert oder bei Bedarf gutgeschrieben werden. Das lynck System erkennt bei diesem Prozess ganz automatisch, ob die zu dem Refund gehörende Buchung bereits bezahlt wurde und entscheidet somit eigenständig, ob die Reduzierung ausstehender Forderungen möglich ist oder ob eine Gutschrift an den Endkunden notwendig ist.
Zahlungsüberwachung (EBICS)
Ein elementarer Baustein der lynck Lösung ist die Zahlungsüberwachung. Um eingehende Zahlungen der Konto basierten Zahlungsarten Rechnung, Lastschrift und Vorkasse automatisch zuordnen zu können, wird mindestens ein lesender Zugriff auf das Händler- bzw. Debitorenkonto benötigt. Dieser Zugriff ist in der lynck Lösung über EBICS (Electronic Banking Internet Communication Standard) geregelt.
Das EBICS Protokoll definiert dabei zwei für lynck relevante Zugriffsarten. Die folgende Tabelle zeigt die relevanten Unterschiede:
Vollautomatische… | A-Zugriff | T-Zugriff | ohne EBICS |
---|---|---|---|
Zahlungszuordnung | ja | ja | nein |
Ausführung von Lastschriften | ja | nein | nein |
Ausführung von Gutschriften | ja | nein | nein |
lynck Systeme
Für die Integration der lynck Lösung stellt lynck eine Sandbox bereit. Die Sandbox ist eine nahezu identische Kopie des Produktivsystems und bietet damit die Möglichkeit, alle Prozessabläufe zu integrieren, ohne dass echte Zahlungsvorgänge ausgelöst werden.
Bemerkung: Da beide Systeme logisch und physisch voneinander getrennt sind, sind für beide Systeme ganz eigene Accounts und Mandanten konfiguriert. Die API Zugangsdaten für Sandbox- und Produktivbetrieb sind deshalb i.d.R. nicht identisch.
Die folgende Gegenüberstellung zeigt die relevanten Unterschiede beider Systeme:
Funktion | Produktion | Sandbox |
---|---|---|
FQDN | api.crefopay.de | sandbox.crefopay.de |
IP Incoming (API) | dynamisch | 13.49.254.144 |
IP Outgoing | 52.59.56.19, 52.57.73.137, 52.29.50.170 | 13.49.254.144 |
Infrastruktur | Verteiltes System mit Load-Balancing | Virtuelle Maschine |
Händler Service Bereich | service.crefopay.de | sandbox.crefopay.de |
Bonitätscheck | aktiv | inaktiv |
Risikochecks | aktiv | inaktiv |
Zahlungsüberwachung | aktiv | inaktiv |
Zahlungsabwicklung | Realtransaktionen | Testtransaktionen |
Händler Service Bereich
Der Händler Service Bereich bietet alle notwendigen und hinreichenden Funktionen für die Verwaltung der lynck Lösung. Technisch relevant für die Plugin-Installation sind die folgenden Abschnitte.
URL Konfiguration
Die URL Konfiguration definiert die Callback Adressen, welche im Falle einer externen Umleitung (z.B. 3D Secure, Sofort. usw.) den korrekten Rückweg nach der Zahlung definieren.
Bemerkung: Jedes Plugins verwenden seine eigenen Callback Adressen. Dies ist zum einen der historischen Entwicklung der Plugins geschuldet, zum anderen auch abhängig von der jeweiligen Shopsystem-Architektur. Die korrekten Callback Adressen sind auf der jeweiligen Plugin-Seite zu finden.
Hosted Fields Konfiguration
Zur sicheren Übertragung von Kreditkarten-Daten setzt lynck auf die sog. Hosted Fields Technologie (auch Secure Fields genannt). Dabei werden die Eingabefelder der sensiblen Informationen als Iframes in die Frontend-Templates des Shops integriert. So erfolgt die Eingabe der Daten technisch gesehen direkt auf einem gesicherten lynck Server und gar nicht im Shopsystem selbst.
Für den funktionalen Einsatz der Hosted Fields wird eine JavaScript Bibliothek verwendet. Damit diese auch bei verschlüsselten SSL Verbindungen alle benötigten Ressourcen korrekt initialisieren kann, muss die Domäne des Shopsystems im gleichnamigen Abschnitt der Konfiguration korrekt hinterlegt werden:
Bemerkung: Die Domain muss dabei mit dem führenden Protokoll (z.B. https://), aber ohne eine Pfadangabe (z.B. /staging) angegeben werden.
Richtig: https://support.lynck.de
Falsch: https://support.lynck.de/ (selbst ein einfacher „/“ ist hier nicht erlaubt)
Händlerbenachrichtigungssystem
Mit Hilfe des Händlerbenachrichtigungssystems werden Status-Informationen zu jeder lynck Transaktion als digitale Push-Benachrichtigungen versendet.
Die technischen Endpunkte für Push-Benachrichtigungen werden von den lynck Plugins bereitgestellt und zur Aktualisierung des Zahlungsstatus der Bestellungen verwendet. Die Adresse der Benachrichtigungs-URL ist auf der jeweiligen Plugin-Seite zu finden.
API Zugangsdaten
Das lynck System ist mandantenfähig aufgebaut. Das bedeutet, dass für jeden Account mehrere, voneinander unabhängige Anwendungen (i.d.R. Onlineshops) konfiguriert werden können.
Damit eine Konfiguration eindeutig identifiziert werden kann ist immer eine Kombination aus der Händler ID und der
Shop ID notwendig. Zu jeder Shop ID gehört darüber hinaus ein 32-stelliger Token, der sogenannte Öffentliche Schlüssel. Zur Autorisierung der Kommunikation mit der lynck API werden die Zugangsdaten mit dem Privaten Schlüssel komplettiert.
Bemerkung: Die Plugins verwenden teilweise abweichende Bezeichnungen dieser vier Zugangsdaten. Dies ist der historischen Entwicklung der Plugins geschuldet. Die jeweils verwendete Bezeichnung ist auf der jeweiligen Plugin-Seite zu finden.
Die lynck API Zugangsdaten können jederzeit im gleichnamigen Abschnitt der Shop Details im lynck Händler Service Bereich abgerufen werden.
Inbetriebnahme
Die Installation und Grundeinrichtung der lynck Plugins wird auf der jeweiligen Plugin Seite erläutert. In diesem Abschnitt haben wir noch einmal wichtige Hinweise für die ersten Schritte mit lynck zusammengestellt.
Testen mit localhost
Ein lokales Testing der lynck Lösung ist auch mit der Sandbox nur eingeschränkt möglich. Eine lynck Transaktion gilt erst dann als vollständig reserviert, wenn die AcknowledgePending Notification mit einem http/200 beantwortet wurde (siehe auch Notification Call).
Da lokale Testinstanzen für unsere Sandbox nicht erreichbar sind, sollte beim lokalen Testing eine Statusbenachrichtigungsziel-URL hinterlegt werden, die per Default mit einem http/200 antwortet. Dies tut beispielsweise die Seite https://www.example.com.
Weiterhin ist das Testen von Umleitungszahlarten in einer lokalen Umgebung nicht möglich. Zwar kann aus dem Shop bzw. der Anwendung zur Autorisierung beim Drittanbieter umgeleitet werden, jedoch kann die finale Umleitung zurück in den Shop nicht erfolgen, wenn die lokale Maschine von der lynck Sandbox aus nicht erreichbar ist.
Testen mit Verzeichnisschutz (.htaccess)
Häufig werden Testsysteme hinter einem Verzeichnisschutz, häufig auch .htaccess Schutz genannt, betrieben. In diesem Fall erwartet der Server eine Autorisierung mit Benutzernamen und Passwort bei eingehenden Anfragen. Damit sowohl der lynck Benachrichtigungsservice, als auch die Umleitungszahlarten funktionieren, können die benötigten Zugangsdaten über die URL-Konfiguration bekannt gemacht werden.
Beispiel:
https://benutzername:passwort@mein.test.shop/success.php
Bemerkung:
Es sollte unbedingt darauf geachtet werden, dass für den Benutzernamen und das Passwort keine Sonderzeichen verwendet werden, die als Steuerzeichen einer URL interpretiert werden können (/&#.-= usw.). Sollten diese Zeichen trotzdem verwendet werden, muss das Passwort URL encoded hinterlegt werden.
Alternative Lösung:
Die .htaccess Konfiguration des Webservers erlaubt die Freischaltung spezieller IP-Adressen, die dann von der Authentifizierung ausgenommen sind. Da alle Anfragen der lynck Sandbox von derselben IP-Adresse (13.49.254.144) erfolgen, kann diese auch von der Authentifizierung ausgenommen werden.
Testdaten
Die folgenden Testdaten gelten für die Sandbox und sind damit für alle lynck Plugins nutzbar.
Lastschrift
Kontoinhaber | frei wählbar |
IBAN | frei wählbar (siehe auch) |
BIC | optional |
Kreditkarte
Inhaber | frei wählbar |
Nummer | 4321 1234 4321 1234 |
CVV | frei wählbar |
Gültigkeit | frei wählbar |
3D Secure Code | frei wählbar (z.B. 12345) |
Für ein Testing einiger Gateway-Fehler, die bei der Kreditkartenabwicklung u.U. auftreten können, haben wir auf unserer Sandbox einige spezielle Beträge zu Testzwecken definiert:
ID | Titel | Betrag | Aktion | PaymentMethod | ResultCode | Message | Beschreibung |
---|---|---|---|---|---|---|---|
TC10 | Ablehnung vom Aquirer | 1,11 € | reserve() | CC | 2001 | The Payment has been rejected. Please use another payment method. | |
TC20 | Ablehnung vom Aquirer bei 3D Secure | 1,12 € | reserve() | CC3D | 2001 | The Payment has been rejected. Please use another payment method. | |
TC30 | Ablehnung beim Capture | 1,13 € | capture() | CC | CC3D | 2037 | Capture rejected | |
TC40 | Ablehnung bei Rückerstattung | 1,14 € | refund() | CC | CC3D | – | – | |
TC50 | – | 1,17 € | – | CC | CC3D | – | – | interner Testcase |
TC60 | – | 1,18 € | – | CC | CC3D | – | – | interner Testcase |
TC70 | Authorisierungsfehler | 1,19 € | Callback | CC3D | – | Redirect to Failure-URL | Simuliert die Ablehnung nach Kundenauthentifizierung (3D Secure Challange) |
AmazonPay
Benutzername | amazonmerchant+sandbox@crefopay.de |
Passwort | test123 |
PayPal
Benutzername | testing@crefopay.de |
Passwort | #vaS7Rjt |
Sofort. (ehem. Sofortüberweisung)
Benutzername | 88888888 |
Passwort | 88888888 |
PIN | 8888 |
B2B Bonitätsprüfung (Sandbox)
Die Bonitätsprüfung ist in der Regel auf der Sandbox deaktiviert. Um Tests mit den lynck SolvencyChecks auf der Sandbox durchzuführen, senden Sie bitte eine kurze Anfrage über unser Kontaktformular.
Firma | Kundentestsystem Netz Ost GmbH – BITTE NICHT ÄNDERN |
Straße | Eckenerstrasse 89 |
PLZ | 99423 |
Ergebnis | ROT |
Firma | Kundentestsystem Group Marketing GmbH – BITTE NICHT ÄNDERN |
Straße | Hermann-Brill Platz 172 |
PLZ | 99423 |
Ergebnis | GELB |
Firma | Kundentestsystem E-Aktiengesellschaft – BITTE NICHT ÄNDERN |
Straße | Lisztstrasse 145 |
PLZ | 99423 |
Ergebnis | GRÜN |
B2C Bonitätsprüfung (Sandbox)
Name | Surname | Salutation | Birthdate | Phone | Score | Specialaddress | |
---|---|---|---|---|---|---|---|
Uno | Eins | M | noreply@lynck.de | 1960-07-07 | +493011111 | 63 | S8 |
Uno | Sechzig | M | noreply@lynck.de | 1966-06-06 | +493011111 | 71 | S8 |
Uno | Neununddreißig | M | noreply@lynck.de | 1996-01-11 | +493011111 | 94 | |
Uno | Einhundert | M | noreply@lynck.de | 1910-10-10 | +493011111 | 97 | |
Uno | Siebzig | M | noreply@lynck.de | 1989-05-05 | +493011111 | 5200 | |
Uno | Sechs | M | noreply@lynck.de | 1910-07-07 | +493011111 | 5800 | |
Uno | Zwei | M | noreply@lynck.de | 1950-07-07 | +493011111 | 5800 |
Testfälle
Die folgenden Testfälle gelten für die Sandbox und sind damit für alle lynck Plugins nutzbar.
Checkout
TestCase | Beschreibung | OK |
---|---|---|
TC 010 | Checkout mit einer Direct Bezahlart* als angemeldeter Benutzer. | |
TC 020 | Checkout mit einer Redirect Bezahlart** als angemeldeter Benutzer. | |
TC 030 | Checkout mit einer Direct Bezahlart als Gast-Benutzer. | |
TC 040 | Checkout mit einer Redirect Bezahlart als Gast-Benutzer. | |
TC 050 | Ein manueller Abbruch bei Kreditkarte 3D Secure oder Sofort. – durch drücken auf den zugehörigen Button beim Drittanbieter – leitet zurück in den Online-Shop, wo eine andere Bezahlart ausgewählt werden kann. |
** unter Redirect Bezahlart verstehen wir die Zahlungsarten Kreditkarte, Sofort. und PayPal, bei denen nach dem Kaufabschluss im Shop noch zu einem Drittanbieter umgeleitet werden muss.
Händler Service Bereich
Die in diesem Abschnitt aufgeführten Testfälle beziehen sich speziell auf den lynck Händler Service Bereich.
TestCase | Beschreibung | OK |
---|---|---|
TC 110 | Alle im Checkout erstellten Transaktionen sind über die Suche im Händler Service Bereich zu finden. | |
TC 120 | In den Transaktionsdetails (Übersicht) enthaltene Informationen stimmen mit der Bestellung im Shop überein. | |
TC 130 | In den Transaktionsdetails (Detailansicht) enthaltene Informationen stimmen mit der Bestellung im Shop überein. | |
TC 140 | Zu jeder erfolgreich abgeschlossenen Bestellung existiert eine Benachrichtigung mit dem Status MERCHANTPENDING; Ausnahme ist die Vorkasse, hier ist der korrekte Status CIAPENDING. | |
TC 150 | Die Transaktionsrisikoklasse aller Transaktionen ist Standard (1.0). |
Transaktionsfluss
Im Abschnitt Händler Service Bereich haben wir bereits das Händlerbenachrichtigungssystem kennengelernt. In diesem letzten Abschnitt werden noch einmal die wichtigsten Status einer lynck Transaktion bzw. einer Buchung erläutert.
Transaktionsstatus
Status | Bedeutung |
---|---|
New | Eine Transaktion ist gestartet, sobald der Kunde das erste Mal die Zahlungsauswahl lädt. Eine Transaktion verbleibt in diesem Status, bis entweder eine Reservierung der Zahlung erfolgt oder die Gültigkeit abgelaufen ist. |
MerchantPending | Der Status MerchantPending zeigt die erfolgreiche Reservierung einer Zahlung an. Für Sie als Händler bedeutet dieser Status, dass Sie nun die Bestellung versenden können. Für die unsicheren Zahlungsarten Rechnung und Lastschrift bedeutet das, dass eine positive Bonitäts- und Risikoprüfung durchgeführt wurde. |
Expired | Wird eine Transaktion nicht innerhalb von 4 Stunden (Standard) erfolgreich reserviert, so läuft sie aus und wechseln in den Status Expired. |
AcknowledgePending | Mit diesem Status wird die Reservierung der Transaktion an den Onlineshop bzw. der Anwendung übermittelt, welche die Transaktion gestartet hat. |
CIAPending | Der Status CIAPending zeigt an, dass eine Vorkasse Zahlung auf Geldeingang wartet. |
InProgress | Für die Transaktion existiert mindestens eine offene Forderung. Bemerkung: In älteren Versionen des Benachrichtigungsservice ist die InProgress Notification nicht enthalten. |
Done | Die Transaktion ist erfolgreich abgeschlossen und alle offenen Forderungen sind ausgeglichen. |
Cancelled | Die Transaktion wurde storniert/abgebrochen. |
Buchungsstatus
Die hier aufgeführten Status gelten innerhalb einer Buchung. Für Buchungen mit einer offenen Forderung startet der Ablauf mit dem Status PayPending, für bereits bezahlte Forderungen startet der Ablauf direkt im Status Paid.
Status | Bedeutung |
---|---|
PayPending | Die offene Forderung für diese Buchung ist noch nicht durch einen Zahlungseingang ausgeglichen. |
Paid | Die offene Forderung wurde durch einen Zahlungseingang ausgeglichen. |
PaymentFailed | Der Zahlungseinzug (z.B. Lastschrift) ist fehlgeschlagen. |
Chargeback | Kreditkarte: Die Zahlung wurde vom Endkunden aktiv zurückgeholt. Lastschrift: Die Lastschrift konnte zum Zeitpunkt der Wertstellung mangels Deckung nicht eingelöst werden oder die Zahlung wurde vom Endkunden aktiv zurückgeholt. |
DunningPending | Das Fälligkeitsdatum für diese Forderung wurde erreicht. Sofern Sie das automatisierte Forderungsmanagement von lynck verwenden, wird die offene Forderung beim Mahndienstleister angemeldet. Bemerkung: In diesem Status sind keine Gutschriften erlaubt. |
InDunning | Für das Mahnverfahren wurde vom Mahndienstleister eine Akte angelegt und die erste Mahnung wurde versendet. Bemerkung: Bleibt die 1. Mahnung ohne Erfolg, wird fristgerecht die 2. Mahnung versendet. Hierfür wird jedoch keine erneute Benachrichtigung ausgelöst. |
InCollection | Das Mahnverfahren blieb ohne Ergebnis und die Akte der offenen Forderung wurde ins Inkasso abgegeben. |