Mithilfe von Plugins wird die Integration der CrefoPay 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 CrefoPay Welt einige Grundlagen und Vokabeln, mit denen wir uns vor der Integration von CrefoPay vertraut machen sollten.

Begriffe

Transaktion

Unter einer Transaktion verstehen wir [den Rahmen für] einen einzelnen Zahlungsvorgang mit CrefoPay. Der eindeutige Bezeichner einer CrefoPay 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 CrefoPay Transaktion, das selbst nach der erfolgreichen Reservierung einer Transaktion verändert werden kann. Diejenigen CrefoPay Plugins, welche mit einer generischen orderID arbeiten, nutzen dieses Feld, um nach dem Bestellabschluss die Shop-Bestellnummer als zusätzliche OrderID bei CrefoPay bekannt zu machen.

Reservierung

Den vorläufigen Abschluss einer CrefoPay-Zahlung im Checkout nennen wir bei CrefoPay die Reservierung. Eine erfolgreiche Reservierung bedeutet im Sinne von CrefoPay, 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 CrefoPay 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 CrefoPay Zahlungsüberwachung – wird, muss die reservierte Zahlung gebucht werden. Die CrefoPay 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 CrefoPay 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 CrefoPay 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 CrefoPay Lösung über EBICS (Electronic Banking Internet Communication Standard) geregelt.

Das EBICS Protokoll definiert dabei zwei für CrefoPay relevante Zugriffsarten. Die folgende Tabelle zeigt die relevanten Unterschiede:

Vollautomatische…A-ZugriffT-Zugriffohne EBICS
Zahlungszuordnungjajanein
Ausführung von Lastschriftenjaneinnein
Ausführung von Gutschriftenjaneinnein

CrefoPay Systeme

Für die Integration der CrefoPay Lösung stellt CrefoPayment eine Sandbox bereit. Die CrefoPay 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:

FunktionProduktionSandbox
FQDNapi.crefopay.desandbox.crefopay.de
IP Incoming (API)dynamisch13.49.254.144
IP Outgoing52.59.56.19, 52.57.73.137, 52.29.50.17013.49.254.144
InfrastrukturVerteiltes System mit Load-BalancingVirtuelle Maschine
Händler Service Bereichservice.crefopay.desandbox.crefopay.de
Bonitätscheckaktivinaktiv
Risikochecksaktivinaktiv
Zahlungsüberwachungaktiv inaktiv
ZahlungsabwicklungRealtransaktionenTesttransaktionen

Händler Service Bereich

Der CrefoPay Händler Service Bereich bietet alle notwendigen und hinreichenden Funktionen für die Verwaltung der CrefoPay 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 CrefoPay 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 CrefoPay 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:

Hosted Fields Konfig

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.crefopay.de

Falsch: https://support.crefopay.de/ (selbst ein einfacher „/“ ist hier nicht erlaubt)

Händlerbenachrichtigungssystem

Mit Hilfe des Händlerbenachrichtigungssystems werden Status-Informationen zu jeder CrefoPay Transaktion als digitale Push-Benachrichtigungen versendet.

Die technischen Endpunkte für Push-Benachrichtigungen werden von den CrefoPay 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 CrefoPay 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 CrefoPay 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.

Beispiel API Zugangsdaten im CrefoPay Händler Service Bereich

Die CrefoPay API Zugangsdaten können jederzeit im gleichnamigen Abschnitt der Shop Details im CrefoPay Händler Service Bereich abgerufen werden.

Inbetriebnahme

Die Installation und Grundeinrichtung der CrefoPay Plugins wird auf der jeweiligen Plugin Seite erläutert. In diesem Abschnitt haben wir noch einmal wichtige Hinweise für die ersten Schritte mit CrefoPay zusammengestellt.

Testen mit localhost

Ein lokales Testing der CrefoPay Lösung ist auch mit der Sandbox nur eingeschränkt möglich. Eine CrefoPay 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 CrefoPay 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 CrefoPay 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 CrefoPay 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 CrefoPay Sandbox und sind damit für alle CrefoPay Plugins nutzbar.

Lastschrift

Kontoinhaberfrei wählbar
IBANfrei wählbar (siehe auch)
BICoptional

Kreditkarte

Inhaberfrei wählbar
Nummer4321 1234 4321 1234
CVV frei wählbar
Gültigkeit frei wählbar
3D Secure Codefrei wählbar (z.B. 12345)

AmazonPay

Benutzernameamazonmerchant+sandbox@crefopay.de
Passworttest123

PayPal

Benutzernametesting@crefopay.de
Passwort#vaS7Rjt

Sofort. (ehem. Sofortüberweisung)

Benutzername88888888
Passwort88888888
PIN8888

B2B Bonitätsprüfung

Die Bonitätsprüfung ist in der Regel auf der Sandbox deaktiviert. Um Tests mit den CrefoPay SolvencyChecks auf der Sandbox durchzuführen, senden Sie bitte eine kurze Anfrage über unser Kontaktformular.

FirmaKundentestsystem Netz Ost GmbH – BITTE NICHT ÄNDERN
StraßeEckenerstrasse 89
PLZ99423
ErgebnisROT
FirmaKundentestsystem Group Marketing GmbH – BITTE NICHT ÄNDERN
StraßeHermann-Brill Platz 172
PLZ99423
ErgebnisGELB
FirmaKundentestsystem E-Aktiengesellschaft – BITTE NICHT ÄNDERN
StraßeLisztstrasse 145
PLZ99423
ErgebnisGRÜN

Testfälle

Die folgenden Testfälle gelten für die CrefoPay Sandbox und sind damit für alle CrefoPay Plugins nutzbar.

Checkout

TestCaseBeschreibungOK
TC 010Checkout mit einer Direct Bezahlart* als angemeldeter Benutzer.
TC 020Checkout mit einer Redirect Bezahlart** als angemeldeter Benutzer.
TC 030Checkout mit einer Direct Bezahlart als Gast-Benutzer.
TC 040Checkout mit einer Redirect Bezahlart als Gast-Benutzer.
TC 050Ein 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 Direct Bezahlart verstehen wir die Zahlungsarten Rechnung, Lastschrift und Vorkasse, also diejenigen, welche ohne eine Umleitung zu einem Drittanbieter abgeschlossen werden können.
** 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 CrefoPay Händler Service Bereich.

TestCaseBeschreibungOK
TC 110Alle im Checkout erstellten Transaktionen sind über die Suche im Händler Service Bereich zu finden.
TC 120In den Transaktionsdetails (Übersicht) enthaltene Informationen stimmen mit der Bestellung im Shop überein.
TC 130In den Transaktionsdetails (Detailansicht) enthaltene Informationen stimmen mit der Bestellung im Shop überein.
TC 140Zu jeder erfolgreich abgeschlossenen Bestellung existiert eine Benachrichtigung mit dem Status MERCHANTPENDING; Ausnahme ist die Vorkasse, hier ist der korrekte Status CIAPENDING.
TC 150Die Transaktionsrisikoklasse aller Transaktionen ist Standard (1.0).

Transaktionsfluss

Im Abschnitt Händler Service Bereich haben wir bereits das CrefoPay Händlerbenachrichtigungssystem kennengelernt. In diesem letzten Abschnitt werden noch einmal die wichtigsten Status einer CrefoPay Transaktion bzw. einer Buchung erläutert.

Transaktionsstatus

Transaction Status
StatusBedeutung
NewEine 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.
MerchantPendingDer 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.
ExpiredWird eine Transaktion nicht innerhalb von 4 Stunden (Standard) erfolgreich reserviert, so läuft sie aus und wechseln in den Status Expired.
AcknowledgePendingMit diesem Status wird die Reservierung der Transaktion an den Onlineshop bzw. der Anwendung übermittelt, welche die Transaktion gestartet hat.
CIAPendingDer Status CIAPending zeigt an, dass eine Vorkasse Zahlung auf Geldeingang wartet.
InProgressFür die Transaktion existiert mindestens eine offene Forderung.
Bemerkung: In älteren Versionen des Benachrichtigungsservice ist die InProgress Notification nicht enthalten.
DoneDie Transaktion ist erfolgreich abgeschlossen und alle offenen Forderungen sind ausgeglichen.
CancelledDie 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.

Capture Status
StatusBedeutung
PayPendingDie offene Forderung für diese Buchung ist noch nicht durch einen Zahlungseingang ausgeglichen.
PaidDie offene Forderung wurde durch einen Zahlungseingang ausgeglichen.
PaymentFailedDer Zahlungseinzug (z.B. Lastschrift) ist fehlgeschlagen.
ChargebackKreditkarte: 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.
DunningPendingDas Fälligkeitsdatum für diese Forderung wurde erreicht. Sofern Sie das automatisierte Forderungsmanagement von CrefoPay verwenden, wird die offene Forderung beim Mahndienstleister angemeldet.
Bemerkung: In diesem Status sind keine Gutschriften erlaubt.
InDunningFü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.
InCollectionDas Mahnverfahren blieb ohne Ergebnis und die Akte der offenen Forderung wurde ins Inkasso abgegeben.